Add read-only XMD information requests to `xmd plan`

[taras]

Story

As someone creating a Plan, I want the coding agent to request component documentation, file contents, and matching file paths when it needs them, so it can gather useful context in one XMD response before writing the Plan.

The same information loop belongs to the packaged <Plan> component used by xmd plan and by ordinary xmd run.

Example

An Agent may return this information request instead of a completed Plan:

Find the instruction files and inspect the project overview.

<Glob include={["**/AGENTS.md"]} exclude={["node_modules/**"]} as="paths" />
<File path="README.md" />
<Syntax names={["Elicit", "File"]} />

The complete response is evaluated through public <Evaluate text={agentResponse} allow={["read"]} as="information" />. Its rendered output and structured read results become context for the next Agent turn. The Glob path list is included even though Glob renders no text. The Agent can then return a complete Plan or another information request.

Current gap and delivery status

This feature is not delivered. PR #776, merged at 1a7b96ab6c75f29fcf82513017f6daabab4d0d82, delivers the general mechanism for carrying exact protected Syntax authority through generated XMD. Its description explicitly says it does not complete #762. Automatic closure on that merge was inaccurate.

The current Plan workflow has no response classifier or information loop. The ordinary run evaluation profile admits File reads but not Syntax or Glob; the plan command installs no evaluation profile. Generic composed limits, safe typed recovery, and complete-result replay still require core work.

Accepted product contract

• Both commands install the same ordinary run evaluation profile, extended with canonical self-closing Syntax and Glob alongside self-closing File in read. The ordinary write table is unchanged. Plan selects only read.
• Plan does not install or replace a profile, and does not create a separate child document execution to obtain different authority. Another trusted host's explicit profile remains authoritative.
• The future run's compact syntax vocabulary remains in the planning prompt. Named Syntax can describe that broader vocabulary without making its components executable. Bare generated Syntax shows the admitted read vocabulary. File's read form does not admit its write form.
• The Agent still receives no native tools or direct caller checkout. XMD-mediated File and Glob reads use the shared profile's existing Files and working-directory rules. Writes, deletion, network, credential APIs, processes, Agents, elicitation, services, imports and executable code remain unavailable in the generated request.
• Whole-fragment admission precedes every read. Ordinary fragment-local as capture is supported for admitted read components, including Glob; it grants no arbitrary expression evaluation or access to caller bindings.
• Initial-generation, repair and review-revision responses use one non-executing classifier. A non-empty ATX or Setext H1 as the first body block after optional lexically closed frontmatter marks a draft. Closed invalid YAML remains repairable as a draft. An unterminated frontmatter envelope, no first H1 or a preceding body block makes the response an information candidate. Review explanations stay outside the loop.
• A draft is never evaluated. Existing structural validation, review, final approval and exact-source delivery remain intact.
• The next turn receives the complete { observations, output } result as JSON data, or a safe refusal. Neither is executed as XMD or appended to the resulting Plan.
• Eight information requests share one invocation-wide budget across drafting, repairs and revisions. They do not consume or reset the ten-draft or three-repair limits. The ninth candidate is not evaluated and starts no further Agent turn.
• Limits compose around Evaluate as generic structured deadline and bounded-result operations. No limits prop or profile-owned resource limit is added. Each request has ten seconds and 65,536 UTF-8 bytes of the complete compact JSON result, including Glob values, JSON syntax and escaping. Ordinary unwrapped evaluations keep their defaults.
• Timeout and overflow cancel work, await cleanup, and return a safe refusal without partial results. Malformed or unauthorized requests and ordinary read failures may likewise recover. Stale/corrupt history, broken setup/providers, unexpected runtime failures, journal/secret failures, outer cancellation and any teardown failure stop authorship. Public Evaluate still throws; recovery uses typed distinctions, never message matching.
• A completed request publishes its closed plan_information outcome only after teardown. Its invocation-owned durable child coroutine is journal composition within the existing execution, not a second execution or profile. Completed replay repeats no Agent turn, Syntax lookup, File read or Glob traversal. Source, selected authority, lexical reference, filesystem scope, capture format and bounds are validated before reuse; changed identity is stale.
• Default command progress shows phase/count only. Verbose output shows complete cleared requests and results/refusals after commit. The journal includes structured read results and applies the secret gate before publication. The command journal remains write-only; embedded Plan emits no command progress into approved source.

Product verification

The architecture's PI1–PI12 matrix is the finite behavioral contract. It distinguishes:

1. Selected Syntax documentation followed by a normal Plan-producing turn, not eager full-documentation injection.
2. One composed Markdown/File/Glob/Syntax request, not a Syntax-specific parser or output-only forwarding.
3. Inert valid and invalid H1-first drafts, not classification by full structural validity.
4. Successful reads on both Plan surfaces and whole-fragment refusal of a later prohibited operation before any read, not a lingering Syntax-only child.
5. Documentation without new execution authority, including rejection of paired File after reading its documentation.
6. Cleanup before the next turn on every ending; cleanup failure is terminal, not hidden by a safe refusal.
7. Independent information/draft/repair budgets across phases.
8. Historical replay with live-reader/Agent tripwires, and stale validation for successes, refusals and completed roots.
9. Equivalent source, npm and compiled journeys, not only matching asset hashes.
10. Per-request timeout versus terminal outer cancellation, without changing ordinary run defaults.
11. Exact ASCII/multibyte JSON-result boundaries, including captured read values, without partial overflow disclosure.
12. Default/verbose/journal disclosure order and secret rejection before any detailed disclosure.

Architecture and delivery order

The accepted design is recorded in architecture.md, section Plan information requests. It supersedes the earlier Planner artifacts' documentation-only child profile, file-read prohibition, output-only forwarding and profile-owned limits.

1. Focused generic core completion: composed bounded result capture and settlement, typed failures, closed-result replay, and Glob capability/capture admission. Preserve Preserve protected Syntax authority through generated XMD #776's routing and unwrapped Evaluate behavior.
2. Plan product: shared command-profile installation, classifier, prompts, information wrapper, counters, durable records, disclosure, and distribution evidence.

No Plan-private evaluator bridges those deliveries.

Dependencies and follow-up

• Add <Syntax> to list the symbols available at its site #758 and Evaluate generated XMD text with constrained authority #713 supply Syntax and Evaluate foundations; PR Preserve protected Syntax authority through generated XMD #776 supplies protected generated routing.
• Add user-controlled filesystem access to Plan information requests #777 owns the later workspace-scope and user-approval escalation decisions. It does not defer File or Glob reads and does not block Add read-only XMD information requests to xmd plan #762.
• Prevent xmd run filesystem operations from escaping the working directory #227 owns concurrent host-path-replacement hardening; existing containment checks and their documented limitations remain unchanged here.
• Refine xmd plan against hand-authored reference workflows #679 remains separate evaluation work after product delivery.
• Generate website reference documentation from xmd CLI output #678 uses the same package-owned documentation index for release snapshots and the website.