melchizedek-agents 1.0.3 → 1.2.0

package/DOCUMENTATION.md

@@ -106,8 +106,8 @@ orchestrator:
   tools:
     - "google_search"             # names resolved via lib/toolRegistry.ts
   reasoning: medium               # none | low | medium | high, or { budget_tokens: 4096 }
-  generateContentConfig:
-    maxOutputTokens: 4096
+  sampling:
+    max_output_tokens: 4096
 
 subagents:
   - name: "Researcher"
@@ -135,20 +135,24 @@ Field reference:
 | `name` / `model` / `instruction` | agent | The agent triple. Any Gemini id, `claude-*`, or `ollama/*` for open-weight local models (see §5). |
 | `description` | subagent | **The delegation API.** The orchestrator reads this when deciding to hand off — write it like a function signature ("Use this subagent to…, pass it…"). |
 | `tools` | agent | Names resolved by the tool registry (§3). Long-term memory agents add `preload_memory` / `load_memory`. |
-| `reasoning` | agent | How hard the agent reasons, on any provider: `none`, `low`, `medium`, `high`, or `{ budget_tokens: <int> }`. The compiler sends each provider the field it reads: a thinking level on Gemini 3, a thinking budget on Claude 4.6 and earlier (2,048 / 8,192 / 16,384 tokens for low / medium / high), adaptive thinking with that effort on later Claude models ([ADR 0049](./wiki/decisions/0049-claude-requests-by-model-generation.md)), an effort word on GPT, Grok, Kimi, Ollama and the gateway ([ADR 0047](./wiki/decisions/0047-provider-neutral-reasoning-key.md)). Unset, each adapter keeps its own default. |
-| `generateContentConfig` | agent | Temperature, output caps. Its `thinkingConfig` and `reasoningEffort` are the older, provider-specific spelling of `reasoning`; setting either next to `reasoning` is a load error. |
-| `outputSchema` | agent | Structured-JSON contract. **Constraint:** an agent holding `outputSchema` cannot also hold transfer powers — structured output does not combine with delegation on one agent. Keep schema-holders as leaf agents (see `critic.yaml`'s header comment for the war story). |
+| `reasoning` | agent | How hard the agent reasons, on any provider: `none`, `low`, `medium`, `high`, `xhigh`, `max`, or `{ budget_tokens: <int> }`. The compiler sends each provider the field it reads: a thinking level on Gemini 3, a thinking budget on Claude 4.6 and earlier (2,048 / 8,192 / 16,384 tokens for low / medium / high), adaptive thinking with that effort on later Claude models ([ADR 0049](./wiki/decisions/0049-claude-requests-by-model-generation.md)), an effort word on GPT, Grok, Kimi, Ollama and the gateway ([ADR 0047](./wiki/decisions/0047-provider-neutral-reasoning-key.md)). `xhigh` and `max` reach the models that take them (both on Claude from Opus 4.7 and Sonnet 5, `max` on Kimi K3, `xhigh` on GPT-5.2 and later and grok-4.7); elsewhere the model's highest setting is sent and the span carries `llm.reasoning.weakened` (`npm run doctor -- --matrix` lists each path, [ADR 0117](./wiki/decisions/0117-tool-choice-and-effort-above-high-in-v2.md)). Unset, each adapter keeps its own default. |
+| `sampling` | agent | `{ temperature, top_p, max_output_tokens, stop }`, the fields the engine sends to every provider; each adapter sends the ones its API takes ([ADR 0115](./wiki/decisions/0115-yaml-schema-v2-provider-neutral-keys.md)). |
+| `output` | agent | `{ schema, mime }`. `mime` is `application/json` (JSON mode, with or without a schema) or `text/plain` (the default). `schema` is the structured-JSON contract: the agent ends its turn on one JSON object matching it. An orchestrator may hold one beside its subagents: it delegates first, then answers in the schema itself. The schema travels in the provider's own structured-output field beside the tools on Claude from Opus 4.8, Sonnet 5 and Haiku 5.5, on OpenAI, and on Gemini 2+ through Vertex AI, and as a `set_model_response` tool elsewhere (the capability matrix's `structured_output_with_tools`, [ADR 0109](./wiki/decisions/0109-structured-output-beside-tools.md)). Worked example: `examples/structured_critic.yaml`. A leaf that holds the schema (`critic.yaml`) and plan-dispatch remain the choices when the answer should be a specialist's. |
+| `model_overrides` | agent | A prompt nuance for one provider: keyed by `gemini`, `anthropic`, `openai`, `xai`, `moonshot` or `ollama`, each entry holds `instruction` (replaces the agent's instruction on that provider) or `instruction_append` (added after a blank line). The entry for the provider of the agent's `model` applies, before the skills index is appended; a `fallback_model` gets the primary's instruction. |
+| `tool_choice` | agent | Which tools the model may call: `auto` (the default), `none`, `required` (some tool), or `{ name: <tool> }` (that tool). A provider that rejects forcing sends a weaker choice and marks the span `llm.tool_choice.weakened` ([ADR 0117](./wiki/decisions/0117-tool-choice-and-effort-above-high-in-v2.md)). |
+| `generateContentConfig` / `outputSchema` | agent | The deprecated v1 spelling of `sampling`, `output.mime`, `reasoning` (as `thinkingConfig` / `reasoningEffort`), `tool_choice` (as `toolConfig.functionCallingConfig`) and `output.schema`. Both still load and behave the same; a load that finds either prints one deprecation line per file per process (`LoadSyndicateOptions.onWarning`, default `console.warn`), and a v2 key beside its v1 spelling on one agent is a load error. Only `toolConfig.functionCallingConfig.mode: VALIDATED` and Gemini's dynamic budget (`thinkingBudget: -1`) have no v2 form; `topK`, `seed`, the penalties, `candidateCount`, `safetySettings` and `includeThoughts` reach no provider, and the codemod drops `includeThoughts`. `npx melchizedek-codemod [--check] <file|dir>` rewrites a v1 file to v2, comments kept ([ADR 0115](./wiki/decisions/0115-yaml-schema-v2-provider-neutral-keys.md)). |
 | `yaml_reference` | subagent | Mount another syndicate file as a nested subagent. |
 | `a2a_agent_url` | subagent | A REMOTE agent over A2A (§6): the orchestrator delegates to it with one `request` argument; in plan-dispatch it can be a route. No `model`/`instruction` — the remote agent has its own. Credentials come from `A2A_AGENT_TOKENS`, never YAML. |
 | `max_steps` | root | Cap on model calls per turn, counted across every agent the turn reaches (orchestrator, subagents, nested syndicates). Exceeding it fails the turn with `STEP_LIMIT`. |
 | `includeContents` / `outputKey` / `globalInstruction` / `disallowTransferToParent` / `disallowTransferToPeers` | agent | Passed through to the agent (spelled after ADK's `LlmAgent` fields). `includeContents: none` makes an agent see only the current message. |
 | `fallback_model` | any agent | A model, ideally on another provider, that answers when this agent's model fails provider-side (5xx, 429, a connection reset, after its own retries) before producing any output, or while that provider's circuit is open: after `MODEL_BREAKER_THRESHOLD` consecutive provider failures (default 5; 0 disables) the provider is skipped for `MODEL_BREAKER_COOLDOWN_MS` (default 30 s). A 4xx and a canceled turn are never redirected, and a stream that already produced text is never replayed elsewhere ([ADR 0044](./wiki/decisions/0044-fallback-model-and-circuit-breaker.md)). |
 | `mcp_tools` | subagent | The MCP server's tools this agent may use; any other tool the server lists is not exposed. On a dispatch route `require_approval` may name them ([ADR 0041](./wiki/decisions/0041-tool-vendors-get-least-privilege.md)). |
+| `mcp_auth` | subagent | `{ oauth2 }`: the OAuth grant the MCP server takes, the same block as an OpenAPI `auth.oauth2`. `client_credentials` sends the server's own token; `authorization_code` sends each user's own token on their own connection (the consent pause asks for it) and needs `mcp_tools` ([ADR 0112](./wiki/decisions/0112-oauth-grants-declared-beside-the-tool.md)). |
 | `mcp_server_url` | subagent | Discover this subagent's tools from a remote MCP server at load time (§3). SSRF-guarded; `ALLOW_PRIVATE_MCP=true` permits localhost for development. |
 | `openapi` | any agent | HTTP APIs as tools, each from an OpenAPI 3 spec file (§3, OpenAPI tools): `spec`, and optionally `operations` (default: the GET operations only), `auth` (from environment variables), `base_url`, `prefix`. |
 | `code_execution` | any Gemini agent | `"gemini"`: the model writes Python and Gemini runs it in Google's server-side sandbox, returning the output to the model; nothing runs on this host. For arithmetic, data and checks a model gets wrong in its head. Gemini models only ([ADR 0033](./wiki/decisions/0033-context-task-code.md)). |
 | `context` | orchestrator | Compacts a long conversation: when the last request's prompt passed `compact_after_tokens`, earlier turns become one summary (written by `summary_model`, default the agent's own) and the last `keep_recent_events` stay verbatim. The full history stays stored; only what the model reads shrinks. The orchestrator of a delegate syndicate only: a dispatch route already reads a bounded projection, a workflow node sees only its input. |
-| `mode` | workflow node | `"task"`: the agent works with its tools until it calls `finish_task`, whose arguments (matching its `outputSchema`) become the node's output. Workflow nodes only. |
+| `mode` | workflow node | `"task"`: the agent works with its tools until it calls `finish_task`, whose arguments (matching its `output.schema`) become the node's output. Workflow nodes only. |
 | `examples` | any agent | Few-shot exchanges, `[{ input, output }]` (up to 20), added to every request's instruction as a few-shot block, the one ADK's `ExampleTool` wrote (an Instruction tool, `lib/tools/examples.ts`); the model never calls it. Keeps worked examples out of the prose of `instruction`. |
 | `skills` | any agent | Agent Skills (a directory of SKILL.md folders) the agent holds the way a coding harness does: every skill's name and description is appended to its instruction at compile time; `load_skill` reads one in full with the names of its files, `load_skill_resource` reads one file. `scripts: local` adds `run_skill_script`, which runs a skill's own scripts on this machine, each after a person approves (the `require_approval` pause), with PATH, HOME, the temp directory and the locale but none of the server's keys, plus the variable names listed under `env:` (or `secret_env:` for a secret-shaped name, ADR 0086), and stdout and stderr each cut at 20,000 characters; `tools:` names registry tools a skill's `allowed-tools` may unlock once loaded. Worked example: `examples/harness.yaml`; engine: `lib/tools/skillToolset.ts` over `lib/tools/skills/`. |
 
@@ -181,8 +185,8 @@ function, and every adapter recognises it by marker
 | `generate_image` | Contract | Calls the Gemini image model directly, saves the result under `outputs/`, returns the path. A function tool because binary `inlineData` cannot survive delegation, where a subagent returns only its final text. |
 | `inspect_image` | Contract | **Blind visual inventory** of a file under `outputs/`: subjects with exact counts, composition, light, palette, medium cues, artifacts — zero quality judgments. Its signature accepts *only* a file path, so an orchestrator cannot leak expectations into the observation (see `image_production.yaml`). |
 | `task_add` / `task_list` / `task_get` / `task_update` | Contract | A to-do list and job queue. Default: a single-user JSON file (`MELCHIZEDEK_TASKS_FILE`, default `outputs/tasks.json`), so every caller of a shared endpoint shares one list. With `DATABASE_URL` (migration 0009) each caller has its own list, scoped by the caller's scope key, and any number of workers take jobs safely. |
-| `ask_user` | Contract, long-running | Asks the person one question (optionally with `options`) and ends the turn `input-required`; the next message on the conversation is the call's result. Orchestrator or plan-dispatch route only (§6, Questions). |
-| `task_queue` | Contract | Queues a background job (a self-contained instruction). The tool only writes the queue; `npm run assistant:worker` (`melchizedek-worker`) claims each job, runs it through one agent compiled from YAML (default: the Assistant's Worker), and writes the result back for `task_get`. `--once` drains and exits, for cron. |
+| `ask_user` | Contract, long-running | Asks the person one question (optionally with `options`) and ends the turn `input-required`; the next message on the conversation is the call's result. Any agent but a workflow node's; inside a delegated subagent the question reaches the person with the agent path (§6, Questions). |
+| `task_queue` | Contract | Queues a background job (a self-contained instruction). The tool only writes the queue; `npm run assistant:worker` (`melchizedek-worker`) claims each job, runs it through one agent compiled from YAML (default: the Assistant's Worker), and writes the result back for `task_get`. `--once` drains and exits, for cron. A run is durable (ADR 0113): it is checkpointed beside the job at every step boundary (migration 0014 on Postgres), a job claimed again resumes from its last checkpoint (inside a dispatch route too, ADR 0121), a checkpoint above `MELCHIZEDEK_CHECKPOINT_MAX_BYTES` (default 5 MiB of JSON; `TaskBackendOptions.checkpointMaxBytes`, `postgresStorage({ taskQueue })`) is skipped and the previous one kept, SIGTERM re-queues the job in hand, and `task_update` can cancel a running job. |
 
 **MCP tools** are the exception to the registry: a subagent with
 `mcp_server_url:` in its YAML gets its tools from a remote MCP server at
@@ -221,12 +225,26 @@ without `operations`, only GET operations become tools, so anything that
 writes is exposed only by naming it, and a named operation can be listed
 under `require_approval` (as written under `operations`) so a person
 approves each call. `auth` names an environment variable, never a value
-(`bearer_env`, or `api_key` with `in: header | query` and `name`); an unset
-variable fails the compile, and so does one of the framework's own settings
+(`bearer_env`, or `api_key` with `in: header | query` and `name`), or
+declares an OAuth grant (`oauth2`: `provider`, `grant: authorization_code |
+client_credentials`, `authorization_url`, `token_url`, `client_id` or
+`client_id_env`, `client_secret_env`, `scopes`), whose token each call
+fetches: the run's user's own through the consent pause, or the server's own
+from the token endpoint ([ADR 0112](./wiki/decisions/0112-oauth-grants-declared-beside-the-tool.md)).
+`oauthClientsFor(configs)` (`melchizedek-agents/tools/oauthTools`) builds the
+consent step's clients from the same YAML, and `npm run doctor` lists every
+tool that needs a grant. The hosts a grant's token goes to must be ones the
+operator binds to its provider (`MELCHIZEDEK_OAUTH_HOSTS`, [ADR 0114](./wiki/decisions/0114-oauth-tokens-go-only-to-hosts-the-operator-binds.md));
+with no allowlist, `authorization_code` is refused. An unset variable fails the compile, and so does one of the framework's own settings
 (the database URL, a provider key, an `A2A_` secret: anything `.env.example`
 documents), since the YAML chooses the host it goes to.
 `OPENAPI_CREDENTIAL_ENVS`, when set, is the exact list of variables an `auth`
-may name. A refused or unset variable fails the compile, and a static token is applied to the request,
+may name. `MELCHIZEDEK_CREDENTIAL_HOSTS` binds each such variable to the hosts
+its value may reach (`TRACKER_TOKEN=api.tracker.example.com;…`, or
+`createA2AApp({ credentialHosts })`, [ADR 0122](./wiki/decisions/0122-static-credentials-go-only-to-hosts-the-operator-binds.md)):
+unset, a credential goes where the YAML says and the server and the doctor
+name it as unbound; set, it is the whole list, checked when a syndicate
+loads, when it compiles and before each call. A refused or unset variable fails the compile, and a static token is applied to the request,
 never stored in session state. Every server must be http(s) and pass the
 SSRF guard: its literal rules when the agent compiles, the full check with
 DNS before each call; `ALLOW_PRIVATE_OPENAPI=true` permits private hosts for
@@ -365,7 +383,7 @@ The xAI adapter carries the deepest capability surface: `grok-4.5`
 requests pin `reasoning.effort: "medium"` (`lib/config.ts`), SSE
 streaming works end-to-end (`runConfig: { streamingMode: 'sse' }` —
 partial delta events stream, one aggregated event persists with usage),
-structured outputs ride `outputSchema` → `text.format`, and two
+structured outputs ride `output.schema` → `text.format`, and two
 xAI-only tools — `x_search` and `collections_search` (§3) — turn on
 live X search and hosted-document RAG. All verified live on grok-4.5.
 
@@ -414,11 +432,26 @@ reads every syndicate YAML, resolves each agent's model under your `.env`,
 and prints one table — agent, model, provider, which declared server-side
 tools that path runs natively (✓) or drops (✗), and whether the path is
 funded — with one verdict per syndicate and the variables that would
-unlock the most. Read-only; no key value is ever printed. Every
+unlock the most. Read-only; no key value is ever printed, and a
+`MODEL_GATEWAY` it does not recognise is named as such, never repeated.
+`--check` exits 1 on a blocked syndicate, a runtime problem, a problem
+with the server's OAuth or credential settings, or a tool's OAuth grant
+whose hosts `MELCHIZEDEK_OAUTH_HOSTS` refuses. Every
 starter-pack file opens with a `# tier:` header (`keyless`, one provider
 such as `gemini`, or `multi-provider`) the doctor checks against the
 models. `GOOGLE_GENAI_API_KEY` alone runs fourteen of the nineteen examples.
 
+**Not sure where to start? `npx melchizedek-setup`** (`npm run setup` in a
+clone) opens a menu of authentication levels: no key (Ollama), one
+provider's key, several, a gateway key, Vertex AI / Bedrock / Azure,
+per-caller keys (BYOK), caller identities (`A2A_AUTH`), OAuth tool grants,
+and an honest entry for ChatGPT / Codex, Claude.ai and Gemini CLI sign-ins,
+which the engine does not use. Each prints a startup guide: variable names
+and shapes, the doctor check, the shipped files that run there, and the
+first commands. `--auto` reads the doctor's result and prints the guide
+for the highest level it detects, names only. The same guides, generated
+from the same code, are [`ONBOARDING.md`](./ONBOARDING.md).
+
 **One key instead of several — the gateway fallback.** Direct adapters
 are canonical: the native features above exist only on a provider's own
 endpoint. But with `MODEL_GATEWAY=vercel` (or `openrouter`) and
@@ -486,7 +519,7 @@ runs as a one-agent syndicate through `runSyndicateTurn`.
 
 Reasoning/thinking: scratchpads from every provider are surfaced as
 dimmed THINKING output and kept out of session history. On Claude, any
-`reasoning:` other than `none` (or the older
+`reasoning:` other than `none` (or the deprecated
 `generateContentConfig.thinkingConfig.thinkingBudget`) enables Anthropic
 extended thinking, tools included: the signed thinking blocks ride on the
 response's parts as `providerState` and are replayed verbatim within the
@@ -787,12 +820,31 @@ without it. A message that is not an answer gets the same request back,
 without a model call. The paused call and its arguments are pinned, so an
 approval cannot run a different call.
 
-Gates are allowed on the orchestrator and on the subagents of a
-plan-dispatch syndicate, which run as the turn's own agent, and on the
-agent nodes of a workflow (§6). A delegated
-subagent runs inside a tool call, where a pause cannot reach the caller, so a
-gate there is a load error, as is any gate inside a nested `yaml_reference`
-syndicate. Only function tools from the registry can be gated, not MCP tools
+Gates are allowed on the orchestrator, on the subagents of a plan-dispatch
+syndicate, on the agent nodes of a workflow (§6), and on a delegated
+subagent, at any depth of nested delegate syndicates
+([ADR 0110](./wiki/decisions/0110-pauses-inside-delegated-subagents-reach-the-turn.md)).
+A delegated subagent's gate pauses the whole turn: the call that reached it
+stays open, the request carries `path` (the agents from the turn's own down
+to the one that asked, e.g. `["Desk", "Mailer"]`, in the data part and in
+`approval.path`), and the decision goes back down to that subagent, which
+runs or refuses the call and finishes before its caller continues. The same
+holds inside nested syndicates
+([ADR 0111](./wiki/decisions/0111-pauses-inside-nested-syndicates.md)): a
+nested delegate syndicate's gates anywhere in it, a nested dispatch
+syndicate's on its routes, which it classifies and runs as at the top
+(`["Boss", "Team", "Ops"]`,
+[ADR 0120](./wiki/decisions/0120-nested-dispatch-syndicates-route-as-at-the-top.md)),
+and a nested workflow's gated agent nodes and
+`ask_user` nodes when the workflow is a delegated subagent; the path then
+ends at the node, e.g. `["Desk", "Writer", "Send"]`. A workflow run as a
+dispatch route or as another workflow's node pauses the turn the same way
+([ADR 0119](./wiki/decisions/0119-workflow-routes-and-nodes-pause-the-turn.md)),
+the path running from the route or node down, e.g. `["Writer", "Send"]`.
+Skill scripts (`skills.scripts: local`) on a delegated
+subagent pause the same way, with `run_skill_script` as the tool
+([ADR 0118](./wiki/decisions/0118-skill-scripts-and-oauth-consent-inside-delegated-subagents.md));
+an agent a map node runs still may not carry them. Only function tools from the registry can be gated, not MCP tools
 or native-search sentinels. In code, `runSyndicateTurn` returns
 `status: 'input-required'` with `approval`, and the next turn's part
 `approvalResponsePart(approval.id, approved)` answers it.
@@ -819,12 +871,14 @@ call's result, and the agent resumes its own tool loop where it asked. A
 workflow's `ask_user` node (§6, Workflows) publishes the same data part and
 is answered the same way, so a client handles both alike.
 
-`ask_user` is allowed where an approval gate is: the orchestrator and the
+`ask_user` is allowed where an approval gate is: the orchestrator, the
 subagents of a plan-dispatch syndicate (a dispatch turn that answers goes
-straight back to the route that asked, without the classifier). A delegated
-subagent or a workflow node listing it is a load error. In code,
+straight back to the route that asked, without the classifier), and a
+delegated subagent, whose question carries `path` and whose answer goes back
+down to it (ADR 0110). A workflow node listing it is a load error. In code,
 `runSyndicateTurn` returns `status: 'input-required'` with `input`
-(`node`, `message`, `payload`), and the next message's text answers it.
+(`node`, `message`, `payload`, and `path` for a delegated subagent's
+question), and the next message's text answers it.
 
 #### OAuth consent for tools
 
@@ -865,6 +919,13 @@ await createA2AApp({ /* … */ toolCredentials: { store, consent } });
    call again. A message sent before the grant gets the same request back,
    without a model call.
 
+The call may sit in a delegated subagent, at any depth (the systems_operator
+template's Systems, say): the request then carries `path`, the agents from
+the turn's own down to the one that asked (in the data part and in
+`consent.path`), the grant is stored under the conversation's app, and the
+next message resumes that subagent's call before its caller continues
+([ADR 0118](./wiki/decisions/0118-skill-scripts-and-oauth-consent-inside-delegated-subagents.md)).
+
 The callback refuses these, and stores nothing:
 
 - a state that is replayed, tampered with or older than ten minutes;
@@ -877,6 +938,48 @@ one replica, or route the callback to the instance that paused the call. In
 code, `runSyndicateTurn({ …, toolCredentials })` returns
 `status: 'input-required'` with `consent`.
 
+**From the environment (`melchizedek-serve`).** The server binary builds the
+store and the consent step itself, with the clients taken from the grants the
+served syndicate files declare (`auth.oauth2`, `mcp_auth`; a registry row may
+name a provider they declare, never define one):
+
+| Variable | Shape | What it does |
+|---|---|---|
+| `MELCHIZEDEK_CREDENTIAL_KEY` | 32 random bytes, base64 or 64 hex (`openssl rand -base64 32`) | Seals each user's tokens. Unset: no store, and an authorization-code tool answers `unavailable`. Rows live in Postgres with `DATABASE_URL`, else in process memory |
+| `OAUTH_REDIRECT_URI` | `https://agents.example.com/oauth/callback` (no query) | The callback, as registered at every provider. Mounts it and lets a run ask a user to connect. Needs the key |
+| `OAUTH_CALLBACK_IDENTITY` | `required` (default) or `state` | `required`: the browser that completes a grant carries the flow's user's identity, which only `A2A_AUTH=header` behind a gateway gives it. `state`: the single-use state alone binds the flow (a forwarded link can connect the wrong account) |
+| `MELCHIZEDEK_OAUTH_HOSTS` | `provider=host,host;provider=host` | Which hosts each provider's tokens and client secret may be sent to. A host is a hostname, `*.domain` (subdomains only), IPv4 or `[IPv6]` |
+| `MELCHIZEDEK_CREDENTIAL_HOSTS` | `VARIABLE=host,host;VARIABLE=host` | Which hosts each static credential variable a YAML sends (`bearer_env`, `api_key.env`, `client_secret_env`) may be sent to. Unset: as the YAML says, each named as unbound. Set: the whole list ([ADR 0122](./wiki/decisions/0122-static-credentials-go-only-to-hosts-the-operator-binds.md)) |
+
+**The host allowlist** ([ADR 0114](./wiki/decisions/0114-oauth-tokens-go-only-to-hosts-the-operator-binds.md))
+is the operator's binding, never the YAML's: `MELCHIZEDEK_OAUTH_HOSTS`, or
+`createA2AApp({ oauthHosts: { tracker: ['api.tracker.example.com'] } })`,
+which wins. Unset, an `authorization_code` grant is refused (a user's token
+never goes to a host nobody bound) and a `client_credentials` grant is
+allowed (its secret is the operator's, as `bearer_env`'s is). Set, it is the
+whole list: every grant's provider must be on it, and its API or MCP server,
+token endpoint and authorization endpoint must be that provider's hosts. A
+syndicate that breaks the rule is refused when the server loads it to serve,
+again when its tools compile, and every call checks the host it sends a
+token to. The server refuses to start on a malformed key, allowlist or
+redirect URI, or on a redirect URI without a key; `npm run doctor` reports
+each of these, and a declared grant with no key or redirect URI, by name.
+
+**The credential host allowlist** ([ADR 0122](./wiki/decisions/0122-static-credentials-go-only-to-hosts-the-operator-binds.md))
+does the same for the static credentials a YAML sends: `bearer_env` and
+`api_key.env` to an OpenAPI server, and `client_secret_env` to a token
+endpoint. `MELCHIZEDEK_CREDENTIAL_HOSTS`, or
+`createA2AApp({ credentialHosts: { TRACKER_TOKEN: ['api.tracker.example.com'] } })`,
+which wins. Unset, nothing changes: each credential goes to the host the
+YAML names, and the server's boot and `npm run doctor` name every variable a
+served YAML sends that no binding holds (names only). Set, it is the whole
+list: a variable not on it is sent nowhere, and one on it only to its own
+hosts. A syndicate that breaks the rule is refused when it loads, when it
+compiles, and each call (an OpenAPI call, a client-credentials token
+request, a consent code exchange, a refresh) checks again and sends nothing
+when refused. `MCP_BEARER_TOKENS` is not covered: it already maps each token
+to its host.
+
 #### Limits
 
 | Setting | Default |
@@ -1056,7 +1159,7 @@ user:
 | | DELEGATE (default) | PLAN-DISPATCH (`dispatch:` present) |
 |---|---|---|
 | Subagents are | tools on the orchestrator | plain configs the server selects from |
-| Orchestrator holds | subagent tools, no `outputSchema` | an `outputSchema`, no subagent tools |
+| Orchestrator holds | subagent tools, no `output.schema` | an `output.schema`, no subagent tools |
 | Routing decision is | implicit in which tool it calls | an explicit value in code |
 | The final answer comes from | the orchestrator re-emitting the answer | **the specialist itself** |
 | LLM calls per request | classify + specialist + relay | classify + specialist |
@@ -1070,14 +1173,14 @@ orchestrator:
   model: "gemini-3.5-flash-lite"
   instruction: |
     Name exactly ONE specialist for this message. ...
-  outputSchema:                        # a leaf holding a schema — no subagent tools
-    type: "OBJECT"
-    properties:
-      route:  { type: "STRING", description: "Exact specialist name" }
-      reason: { type: "STRING", description: "≤8 plain words for the waiting user" }
-    required: ["route"]
-  generateContentConfig:
-    responseMimeType: "application/json"
+  output:
+    mime: "application/json"
+    schema:                            # the router's schema; dispatch gives it no subagent tools
+      type: "OBJECT"
+      properties:
+        route:  { type: "STRING", description: "Exact specialist name" }
+        reason: { type: "STRING", description: "≤8 plain words for the waiting user" }
+      required: ["route"]
 ```
 
 **Why it exists.** In DELEGATE mode the orchestrator receives the
@@ -1090,13 +1193,18 @@ Plan-dispatch has no relay turn to fail, and the classifier's output
 shrinks from a whole relayed answer to ~15 tokens of JSON.
 
 **Why the classifier is tool-less.** An agent that holds an
-`outputSchema` answers with that JSON and nothing else, so the schema sits
-on a leaf that delegates nothing (see `config/agents/examples/critic.yaml`,
-whose header also tells how an orchestrator holding both deadlocked on
-ADK before 1.0.0).
-That constraint shapes the method: the classifier is a leaf, and the
+`output.schema` ends its turn on that JSON. The router's JSON names a
+route for code to run, so the router holds no subagent tools, and the
 hand-off happens in code, where it can be logged, traced, and streamed
-to the user as progress.
+to the user as progress. This is a choice of method, not a limit of the
+engine: an orchestrator may hold an `output.schema` beside its subagents,
+delegate, and answer in the schema itself
+([ADR 0109](./wiki/decisions/0109-structured-output-beside-tools.md));
+under ADK, before 1.0.0, an orchestrator holding both deadlocked (see
+`config/agents/examples/critic.yaml`'s header). Choose plan-dispatch when
+the answer is the specialist's, and a schema on the orchestrator when the
+answer is its own structured judgment of what its team returned
+(`config/agents/examples/structured_critic.yaml`).
 
 **Sessions.** Every *route* runs in the shared `<contextId>` session, so
 one transcript accumulates across routes and long-term memory ingests
@@ -1165,6 +1273,27 @@ Implemented in `runSyndicateTurn`, so every surface honours it: the A2A
 server, the CLI runner (`scripts/syndicate_chat.ts`), the worker and the
 evals.
 
+**Nested.** A `yaml_reference` to a plan-dispatch syndicate runs as it
+runs at the top, as a turn of its own on its own conversation, wherever
+it appears
+([ADR 0120](./wiki/decisions/0120-nested-dispatch-syndicates-route-as-at-the-top.md)):
+its classifier picks one of its routes, and the route's final text is
+what its caller gets: the tool's answer as a DELEGATE subagent, the turn's
+answer as a plan-dispatch route, the node's output as a workflow node. The
+classifier's JSON never reaches its caller. It runs under the turn's
+`max_steps`, deadline and cancel; its guards run once, on the answer at the
+top; its OAuth grants are stored under the root's app. An approval, an
+`ask_user` question or an OAuth consent on one of its routes, or inside a
+route's own delegation, pauses the whole turn with the path (e.g.
+`["Boss", "Team", "Ops"]` delegated, `["Team", "Ops"]` as a route), and
+the answer resumes that route without classifying again. As a workflow
+node it cannot pause on a consent request: the node fails. Its
+conversation is filed at `<app>/<caller>/<entry>` when delegated, at
+`<app>/route:<route>` as a route and at `<app>/node:<node>` as a node. A
+route that carries the entry's own name, a `map` over one, and a reference
+chain below it that reaches itself are refused by name before any model
+call.
+
 ### Workflows (`workflow:`) — the third orchestration method
 
 A syndicate that declares a `workflow:` block is a **graph**. Its agents
@@ -1190,7 +1319,7 @@ name is an agent or a declared node; a list of names fans out (after one
 node) or fans in (before one node); a map `{ <route>: <node or nodes>,
 default: <node> }` ends a chain and routes on the output of the node
 before it — the `route_key` property of a JSON output (an agent with an
-`outputSchema`), else the trimmed text — with `default` catching what no
+`output.schema`), else the trimmed text — with `default` catching what no
 key matched. Every node receives the previous node's output as its
 message; a join hands on `{ <predecessor>: <output>, … }`.
 
@@ -1245,9 +1374,15 @@ graph, under the entry's name and description, wherever it appears: as a
 DELEGATE subagent its last output is the tool's answer; as a plan-dispatch
 route it is the turn's answer, and the conversation keeps the message and
 that answer; as a node of another workflow it is the node's output. The
-graph's events are kept in the entry's own session, as for any subagent.
-A nested workflow may not have an `ask_user` node (a pause inside it
-cannot reach the caller); it is refused by name, as is a `map` over one.
+graph's events are kept in the entry's own session, filed under the agent
+path and its kind (`<app>/route:<route>`, `<app>/node:<node>`; a session
+an earlier release filed under `<app>/<entry>` or the entry's name alone is
+still continued). Wherever it
+runs, an `ask_user` node or a gated agent node inside it pauses the whole
+turn with the path down to that node, and the answer resumes the graph
+([ADR 0111](./wiki/decisions/0111-pauses-inside-nested-syndicates.md),
+[ADR 0119](./wiki/decisions/0119-workflow-routes-and-nodes-pause-the-turn.md)).
+A `map` over one is refused by name.
 
 **Not yet.** Remote `a2a_agent_url` subagents are refused inside a
 workflow by the schema. An `ask_user` tool on a node agent is refused