melchizedek-agents 1.1.0 → 1.3.0

package/DOCUMENTATION.md

@@ -135,19 +135,22 @@ 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. |
+| `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. |
-| `generateContentConfig` / `outputSchema` | agent | The deprecated v1 spelling of `sampling`, `output.mime`, `reasoning` (as `thinkingConfig` / `reasoningEffort`) 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` and the effort words `xhigh` / `max` have no v2 form yet; `topK`, `seed`, the penalties, `candidateCount`, `safetySettings` and `includeThoughts` reach no provider. `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)). |
+| `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_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)). With `client_registration: dynamic` and no client id or endpoints, the authorization server is discovered from the MCP server and this deployment registers itself as a client, every discovered host held to `MELCHIZEDEK_OAUTH_HOSTS` (ADR 0124). |
 | `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. |
+| `mcp_transport` | subagent | How `mcp_server_url` is reached: `auto` (default: Streamable HTTP, falling back to the legacy SSE transport on the spec's signal), `streamable_http` or `sse` ([ADR 0124](./wiki/decisions/0124-mcp-client-streamable-http-several-servers-and-dynamic-registration.md)). |
+| `mcp_servers` | any agent | Several MCP servers: a list of `{ name, url, tools, auth?, transport? }`. `tools` is required on each; a tool name on two servers, or shared with the agent's own tools, is refused at load. `require_approval` may name any server's tool. Not with `mcp_server_url` (ADR 0124). |
 | `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. |
@@ -185,14 +188,18 @@ function, and every adapter recognises it by marker
 | `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. 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, SIGTERM re-queues the job in hand, and `task_update` can cancel a running job. |
+| `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
-load time. `lib/tools/mcpToolFactory.ts` dials the server over SSE,
-lists its tools, and makes each one an own Tool (`loadMcpTools`) — the
+`mcp_server_url:` (or several servers under `mcp_servers:`) in its YAML
+gets its tools from remote MCP servers at load time.
+`lib/tools/mcpToolFactory.ts` dials each server over Streamable HTTP,
+falling back to the legacy SSE transport when the server answers with
+the spec's signal, lists its tools, and makes each one an own Tool (`loadMcpTools`) — the
 agent's reach is decided by the server, not compiled in.
-`config/agents/examples/librarian.yaml` plus the demo catalog server
+`config/agents/examples/connectors.yaml` reaches two servers at once
+and shows, commented, an official remote server with dynamic client
+registration. `config/agents/examples/librarian.yaml` plus the demo catalog server
 (`npm run mcp:demo`, `scripts/demo_mcp_server.ts`) are the worked
 example: read tools *and* write tools, so the agent demonstrably
 modifies data on the far side of the protocol. The factory refuses
@@ -238,7 +245,12 @@ with no allowlist, `authorization_code` is refused. An unset variable fails the
 (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
@@ -426,11 +438,28 @@ 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, an
+unrecognised `MODEL_GATEWAY`, 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,
+Sign in with ChatGPT on your own machine (local only, ADR 0126), and an
+honest entry for Codex CLI, 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
@@ -811,12 +840,19 @@ 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 classifier (its routes never run when it is nested, so a
-gate on one is a load error), and a nested workflow's gated agent nodes and
+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 gate or `ask_user`
-node in a workflow run as a dispatch route or as another workflow's node is
-still a load error, as are skill scripts on a delegated subagent. Only function tools from the registry can be gated, not MCP tools
+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.
@@ -891,6 +927,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;
@@ -914,6 +957,7 @@ name a provider they declare, never define one):
 | `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
@@ -929,6 +973,21 @@ 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 |
@@ -1099,6 +1158,95 @@ and the parent changes only when it is published again. `--no-bundle` stores
 the references bare, to resolve from files at run time; a version published
 before bundling existed behaves that way too.
 
+### MCP server mode (`melchizedek-mcp`)
+
+`npx melchizedek-mcp` (clone: `npm run mcp:serve --`) serves syndicates as
+MCP tools, so Claude Code, Codex or any MCP client asks a syndicate the way
+it calls any other tool ([ADR 0125](./wiki/decisions/0125-syndicates-as-mcp-tools.md)).
+Each syndicate is one tool named after its file (`research_desk.yaml` is
+`research_desk`), described by its orchestrator's `description`, taking
+`{ message, session_id? }`. The result is the turn's answer, then a line with
+the `session_id`; pass it back to continue the conversation, omit it to start
+a new one. An answer declared by an output schema (or JSON mode) is also
+returned as `structuredContent.output`. One more tool, `melch_resume
+{ session_id, approve?, answer? }`, answers a turn that paused.
+
+Which syndicates: `--syndicate <id>` (repeatable; a bare id also finds the
+shipped `examples/` and `templates/`), else every YAML at the agents
+directory's root (`--agents-dir`, `MELCHIZEDEK_AGENTS_DIR`, else
+`./config/agents`).
+
+**Claude Code** (stdio, run from the project, which holds `.env` and
+`config/agents/`):
+
+```bash
+claude mcp add melch -- npx melchizedek-mcp --syndicate research_desk
+# not installed in the project:
+claude mcp add melch -- npx -y -p melchizedek-agents melchizedek-mcp --syndicate research_desk
+# a remote server over Streamable HTTP:
+claude mcp add --transport http melch https://mcp.example.com/mcp --header "Authorization: Bearer $MCP_SERVER_SECRET"
+```
+
+A turn can run for minutes: raise Claude Code's tool timeout with
+`MCP_TOOL_TIMEOUT` (ms) when a syndicate needs longer than its default. The
+server sends progress notifications while a turn works.
+
+**Codex** (`~/.codex/config.toml`):
+
+```toml
+[mcp_servers.melch]
+command = "npx"
+args = ["-y", "-p", "melchizedek-agents", "melchizedek-mcp", "--syndicate", "research_desk"]
+cwd = "/path/to/your/project"
+tool_timeout_sec = 900
+
+# or a running HTTP server:
+# [mcp_servers.melch]
+# url = "http://127.0.0.1:4100/mcp"
+# bearer_token_env_var = "MCP_SERVER_SECRET"
+```
+
+**Pauses.** A turn that stops for a person returns `status: input-required`
+with what is waiting and the `session_id`, and nothing has run:
+
+| Waiting for | The result says | Resume with |
+|---|---|---|
+| an approval (`require_approval`) | the agent, the tool, its arguments | `melch_resume { session_id, approve: true \| false }` |
+| a question (`ask_user`) | the question and its options | `melch_resume { session_id, answer }` |
+| an OAuth grant | the provider and the authorization URL | `melch_resume { session_id }` once the person has granted it |
+
+An approval is answered only through `melch_resume`'s explicit `approve`: a
+message that reads "approve" on the syndicate's own tool repeats the request.
+The server never approves anything itself. Resumes run through the same path
+an A2A answer does, so a call paused inside a delegated subagent, a dispatch
+route or a workflow node resumes where it paused.
+
+**Transports.** stdio is the default; every log line goes to stderr, so stdout
+carries only the protocol. `--http` serves Streamable HTTP at `/mcp`
+(stateful sessions, `Mcp-Session-Id`), on `127.0.0.1:4100` (`--host`,
+`--port`, `MCP_HOST`, `MCP_PORT`). On loopback the Host header must name
+loopback (DNS rebinding). Beyond loopback the bin refuses to start without
+`MCP_SERVER_SECRET` (32 characters or more), which every request then
+presents as `Authorization: Bearer`; `MCP_ALLOWED_HOSTS` names the Host
+values it answers, `MCP_TRUST_PROXY` the proxies in front. Requests are
+limited to `MCP_RATE_LIMIT_PER_MINUTE` (240) per IP, and failed
+authentications to 30 per 15 minutes per IP. `X-User-Id` scopes an HTTP
+caller's sessions and memory as on the A2A server; a stdio client's scope is
+`MCP_USER_ID` (default `default`).
+
+**The same turn as A2A.** Each tool call is one task through the A2A
+executor: budgets (`A2A_BUDGETS`), the concurrency caps
+(`A2A_MAX_CONCURRENT_*`), one turn at a time per conversation, the deadline
+(`A2A_TASK_TIMEOUT_MS`), guards, the ledger, the task record and memory
+ingestion. MCP's `notifications/cancelled` cancels the turn. `DATABASE_URL`
+keeps sessions, memory, turn locks, the audit trail and tool credentials in
+Postgres; without it they live in process memory. The OAuth consent callback
+is mounted on `--http` when `OAUTH_REDIRECT_URI` is set; stdio serves none.
+
+In your own process: `createMcpServer({ syndicates, ... })` from
+`melchizedek-agents/mcp`, then `serveMcpStdio(mcp)` or
+`mcpHttpApp(mcp, { secret })`.
+
 ### Plan-dispatch routing (`dispatch:`) — the second orchestration method
 
 A syndicate that declares a `dispatch:` block stops delegating and
@@ -1222,6 +1370,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
@@ -1302,12 +1471,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.
-As a DELEGATE subagent, an `ask_user` node or a gated agent node inside it
-pauses the whole turn, and the answer resumes the graph
-([ADR 0111](./wiki/decisions/0111-pauses-inside-nested-syndicates.md)). As a
-route or a node, a pause inside it cannot reach the turn yet, so an
-`ask_user` node or a gate there 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