fix(system-prompt): reject a toolOrder that names an unregistered tool

Review follow-up (#196): a listed name with no registered tool was silently
ignored; misconfiguration must block work instead. The check lives in the
assembly — the earliest moment the registered tool set exists (tool plugins
register after the service constructs) and the only universal one (cordis has
no "all plugins loaded" event; registrations change at any time). assemble()
is now async so the throw surfaces as a rejection rather than a synchronous
escape from a Promise-returning method.

Blast radius, pinned by a loop-level test: the rejection reaches the turn's
outer catch — the turn closes balanced with an `error` reason, agent/error
mirrors it, no step opens, no request/header is logged, no request reaches
the adapter, and the agent returns to idle; every turn fails identically
until the config is fixed. A boot-time validation pass was considered and
rejected (recorded in the RFC). The general principle — misconfiguration
fails loud, never a silent skip — is added to AGENTS.md.

AGENTS.md

@@ -91,6 +91,7 @@ Real-API tests and demos read `DEEPSEEK_API_KEY` (and optional `DEEPSEEK_BASE_UR
 - **Capability seams are three packages** — interface / implementation / consumer ([capability seams](docs/rfc/implemented/architecture/2026-06-13-capability-seams.md)); don't split preemptively.
 - **Explicit > implicit at package seams**: defaulting is an explicit `resolve(request): Spec` step in the owning implementation, never a hidden `?? default` inside `run()` (the `dsh-bash` request/spec split is the template).
 - **No hardcoded tunables in plugins**: anything two deployments could want different — timeouts, caps, model names, base URLs — is a defaulted, validated `Config` field, not a literal; a `DEFAULT_*` constant or test-only seam is not configurability. The test: changeable from `cordis.yml`, no code edit. Protocol/wire constants, external-spec values, security invariants stay hardcoded.
+- **Misconfiguration fails loud**: a config value referencing something that does not exist (a `toolOrder` tool name, a plugin path) throws — at load when the check is self-contained, else at the earliest moment the referent exists (for `toolOrder`, every prompt assembly) — never a silent skip.
 - **Opaque cross-boundary ids are branded** (`Branded<B>` from `dsh-brand`), never bare `string` ([branded IDs](docs/rfc/implemented/architecture/2026-06-20-branded-ids.md)).
 - **An empty `catch` names what it swallows** and why nothing else can reach it; keep the `try` to one statement.
 - **Symmetry is usually more correct**: parallel values get parallel form; asymmetry smells of a missed extraction.

docs/config-catalog.md

@@ -558,13 +558,17 @@ export interface Config {
   persona?: string
   /**
    * Explicit model-facing tool order, as a list of `ToolSchema.name`s: listed
-   * tools take their listed position, names with no registered tool are
-   * ignored, and tools absent from the list are inserted at the
-   * {@link TOOL_ORDER_REST} (`'<unlisted-tools>'`) entry in lexicographic name order. A
-   * configured list must contain the rest entry exactly once and no duplicate names —
-   * anything else throws at load; a bad order config must never reach a
-   * model request. When omitted, tools are ordered lexicographically by name.
-   * Applied to the tools {@link SystemPrompt.assemble} collects, BEFORE the
+   * tools take their listed position, and tools absent from the list are
+   * inserted at the {@link TOOL_ORDER_REST} (`'<unlisted-tools>'`) entry in
+   * lexicographic name order. A configured list must contain the rest entry
+   * exactly once, no duplicate names, and no name without a registered tool —
+   * a misconfigured order blocks work instead of silently reaching a model
+   * request: shape violations throw at load, and an unregistered name rejects
+   * every assembly (failing the turn before any model request — the earliest
+   * moment the registered tool set exists to check against, since tool
+   * plugins register after this service constructs). When omitted, tools are
+   * ordered lexicographically by name. Applied to the tools
+   * {@link SystemPrompt.assemble} collects, BEFORE the
    * `system-prompt/assemble` waterfall — like the sections' `order` sort, it
    * canonicalizes what the registry contributed (registration order is a
    * plugin-load artifact); a waterfall listener that mutates the tool list
@@ -575,7 +579,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/core/system-prompt/src/index.ts:161`](../packages/core/system-prompt/src/index.ts)
+Source: [`packages/core/system-prompt/src/index.ts:174`](../packages/core/system-prompt/src/index.ts)
 
 ## `@deepseek-ai/dsh-tool-fs`
 

docs/cordis-catalog/services.md

@@ -190,7 +190,7 @@ variable(name: string, provider: (context: AssembleContext) => string | undefine
 assemble(context: AssembleContext = {}): Promise<PromptAssembly>
 ```
 
-Source: [`packages/core/system-prompt/src/index.ts:262`](../../packages/core/system-prompt/src/index.ts)
+Source: [`packages/core/system-prompt/src/index.ts:279`](../../packages/core/system-prompt/src/index.ts)
 
 ## `ctx.tools` — `ToolRegistry`
 

docs/rfc/implemented/feature/2026-07-06-explicit-tool-order.md

@@ -8,10 +8,15 @@ The order of the tool list a model call carries — `request/header.tools` on th
 
 ## Decision
 
-The system-prompt assembly owns the canonical model-facing tool order, exactly where it already owns section order:
+The system-prompt assembly owns the canonical model-facing tool order, exactly where it already owns section order. `toolOrder?: string[]` on `dsh-system-prompt` is the optional explicit policy:
 
-- **One config key on `dsh-system-prompt`.** `toolOrder?: string[]` names tools in the exact order to send. A listed tool takes its listed position; a listed name with no registered tool is ignored (a deployment may list optional tools it does not always load); tools absent from the list are inserted at the `'<unlisted-tools>'` rest entry (`TOOL_ORDER_REST`), in lexicographic name order among themselves. The list must contain the rest entry exactly once and no duplicate names — violations throw from the service constructor, failing the fiber at load, never mid-conversation. When `toolOrder` is unset, the canonical order is plain lexicographic name order (code-unit comparison, locale-independent) — determinism requires no configuration.
-- **Applied where the list is born: `assemble()`, before the `system-prompt/assemble` waterfall.** The assembly canonicalizes the tools it collects from providers the same way it sorts sections by their `order` field — on the initial assembly, killing the registration-order entropy at its source. Everything downstream inherits the order untouched: the waterfall, the loop's `EpochHeader`, the `request/header` event, the deep-frozen request, and the dev invariant's cross-check all see one deterministic list, with no new service surface and no loop change.
+- A listed tool that is registered takes its listed position.
+- A listed name with no registered tool is a configuration error. Shape errors (rest entry missing or duplicate names) fail from the service constructor; an unregistered name rejects every `assemble()` — the earliest moment the registered tool set exists to check against (tool plugins register after the service constructs), and the only universal one (registrations can change at any time; cordis has no "all plugins loaded" event). Under the shipped loop the first turn fails before any model request — see the consequences below for the exact blast radius.
+- A registered tool absent from the list is inserted at the `'<unlisted-tools>'` rest entry (`TOOL_ORDER_REST`), in lexicographic name order among the other unlisted tools.
+- The list must contain the rest entry exactly once and no duplicate names.
+- When `toolOrder` is unset, the canonical order is plain lexicographic name order (code-unit comparison, locale-independent), so determinism requires no configuration.
+
+The policy is applied where the list is born: `assemble()`, before the `system-prompt/assemble` waterfall. The assembly canonicalizes the tools it collects from providers the same way it sorts sections by their `order` field — on the initial assembly, killing the registration-order entropy at its source. Everything downstream inherits the order untouched: the waterfall, the loop's `EpochHeader`, the `request/header` event, the deep-frozen request, and the dev invariant's cross-check all see one deterministic list, with no new loop change.
 
 Scope is deliberately narrow: this fixes the REGISTRATION-ORDER race, not plugin behavior. A `system-prompt/assemble` listener may still add, remove, or rearrange tools — same as it may edit sections after their sort — and owns the determinism of what it emits; the waterfall contract already demands deterministic listeners (the reconstructability invariant would catch a listener that diverges between build and replay).
 
@@ -26,6 +31,7 @@ Config plumbing follows the `persona` precedent, and `toolOrder` sits beside it:
 - **A `LlmService` config + `orderTools()` method the loop calls before logging the header** — works, but adds a public service method and a loop edit solely to apply a policy at a distance; every future request composer must remember the call. Canonicalizing where the list is born makes an unordered list unrepresentable, with zero new surface.
 - **Normalizing inside `llm.stream()`** — runs after the header event is logged (the flake survives) and rebuilds the deep-frozen envelope, silently disarming the reconstruction invariant.
 - **An exhaustive list (no rest entry)** — every newly loaded tool plugin would break boot; the mandatory rest entry keeps unlisted tools deterministic and their position explicit.
+- **A boot-time validation pass (a `SystemPrompt.assertToolOrderSatisfied()` called by `dsh-app-boot` after `loader.await()`)** — would turn the misconfiguration into a startup death instead of a first-turn failure, but costs a public service method plus a structural coupling from the generic boot glue to one service, and cannot replace the assembly-time check anyway (embedded callers never run app boot; registrations change after boot). No existing event can host the check either: cordis v4 has no ready-like event, `loader/entry-init`/`internal/status` fire mid-load (racy against tool registration, the very entropy this RFC kills), and the agent lifecycle events are no earlier than the assembly. One enforcement point at `assemble()` was judged worth the later failure moment.
 
 ## Consequences
 
@@ -34,7 +40,8 @@ Config plumbing follows the `persona` precedent, and `toolOrder` sits beside it:
 - The snapshot suite's single pinned request-header fixture (`text-turn`) carries the new canonical tool order; every other ACP snapshot keeps the header bulk scrubbed as `{{system}}`/`{{tools}}`, per the pinned-header design.
 - A pure tool reordering between steps is representable only as a `request/header` `'fallback'` snapshot (the name-keyed `ToolsDelta` cannot express it); with a stable canonical order such reorders no longer occur in practice, so the fallback path stays a safety valve.
 - The `toolOrder` key rides the app → `agent-core` → `SystemPrompt` forwarding chain, so deployments set it next to `persona` in the app config; `dsh-llm` and the agent loop are untouched.
+- A misspelled or unloaded tool name in `toolOrder` fails the turn at prompt assembly, not the boot: the loop assembles inside the turn (after `turn/start`, before `step/start`), so the rejection reaches the turn's outer catch — the turn closes balanced with an `error` reason carrying the message, `agent/error` mirrors it, no step opens, no `request/header` is logged, no request reaches the adapter, and the agent returns to idle. Every turn fails identically until the config is fixed; the process itself stays up (matching the repo rule that explicit config references must not be silently ignored — the enforcement point is the assembly because no earlier universal moment exists).
 
 ## Testing
 
-Unit tests on `dsh-system-prompt` pin the ordering semantics (lexicographic default, listed/ignored/rest placement, stable handling of shared names, provider-order independence), the pre-waterfall contract (listeners observe the canonical list; a listener-appended tool is not re-sorted), and each invalid-list rejection at load. Loop-level tests assert the `request/header` fold carries the canonical order for scrambled registration orders (identical across permutations), that a configured `toolOrder` reaches both the logged header and the dispatched deep-frozen request, and that the frozen loop-built envelope survives to the adapter. Forwarding is asserted at every level that exposes the key (`dsh-agent-core`, `dsh-stdio-agent`, `dsh-acp-agent`). The snapshot tier replays all scenarios while only the pinned `text-turn` header carries the full canonical tool list; non-pinning fixtures continue to compare through `{{tools}}`.
+Unit tests on `dsh-system-prompt` pin the ordering semantics (lexicographic default, listed/rest placement, unknown-name rejection at assembly, stable handling of shared names, provider-order independence), the pre-waterfall contract (listeners observe the canonical list; a listener-appended tool is not re-sorted), and each invalid-list rejection at load. Loop-level tests assert the `request/header` fold carries the canonical order for scrambled registration orders (identical across permutations), that a configured `toolOrder` reaches both the logged header and the dispatched deep-frozen request, that the frozen loop-built envelope survives to the adapter, and that an unregistered `toolOrder` name fails the turn with a balanced `error` `turn/end`, an `agent/error`, no step, no logged header, and no dispatched request. Forwarding is asserted at every level that exposes the key (`dsh-agent-core`, `dsh-stdio-agent`, `dsh-acp-agent`). The snapshot tier replays all scenarios while only the pinned `text-turn` header carries the full canonical tool list; non-pinning fixtures continue to compare through `{{tools}}`.

packages/core/agent-loop/tests/tool-order.spec.ts

@@ -91,4 +91,27 @@ describe('loop-level canonical tool order', () => {
     expect(adapter.requests[0]?.tools?.map(tool => tool.name)).toEqual(['zulu', 'alpha', 'mike'])
     expect(Object.isFrozen(adapter.requests[0])).toBe(true)
   })
+
+  it('fails the turn — no model request — when toolOrder names an unregistered tool', async () => {
+    // The assemble rejection escapes to runTurn's outer catch: the open turn
+    // closes with an `error` reason (agent/error mirrors it), no step opens,
+    // no request/header is logged, the adapter never sees a request, and the
+    // agent returns to idle — a misconfigured deployment fails every turn
+    // deterministically instead of silently reordering nothing.
+    const adapter = new MockAdapter([textResponse('never sent')])
+    const ctx = await harness(adapter, ['ghost', TOOL_ORDER_REST])
+    registerNamed(ctx, 'alpha')
+    const errors: Error[] = []
+    ctx.on('agent/error', (_agent, _turn, _step, error) => void errors.push(error))
+    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    agent.send([{ type: 'text', text: 'go' }])
+    await waitForIdle(ctx, agent)
+    expect(adapter.requests).toHaveLength(0)
+    expect(errors.map(e => e.message)).toEqual(['toolOrder lists unregistered tool "ghost"; registered tools: alpha'])
+    expect(foldRequestHeader(agent.session.events)).toBeUndefined()
+    const end = agent.session.events.find(e => e.type === 'turn/end')
+    expect(end?.type === 'turn/end' && end.data.reason).toMatchObject({ kind: 'error', step: 1 })
+    // The turn is balanced (turn/start → turn/end) with no step events inside.
+    expect(agent.session.events.some(e => e.type === 'step/start')).toBe(false)
+  })
 })

packages/core/system-prompt/README.md

@@ -7,7 +7,7 @@ System prompt assembly registry. Plugins contribute ordered text sections, tool-
 | Key | Default | Meaning |
 |---|---|---|
 | `persona` | `''` | The deployment persona: the ONE deployment-authored prompt fragment, rendered as the order-0 `deployment:persona` section and shared by every agent in the context (subagents included). A template — complete `{{…}}` groups are interpreted strictly against the registered variables (the shipped loop registers `{{model}}`/`{{cwd}}`), with no escape syntax for literal braces yet. Empty ⇒ the section is dropped at render. |
-| `toolOrder` | — | Explicit model-facing tool order, as a list of `ToolSchema.name`s with one `'<unlisted-tools>'` rest entry (`TOOL_ORDER_REST`): listed tools take their listed position, names with no registered tool are ignored, unlisted tools land at the rest entry in lexicographic name order. Absent ⇒ plain lexicographic name order. Applied to the collected tools BEFORE the `system-prompt/assemble` waterfall — like the sections' `order` sort, it canonicalizes what the registry contributed (registration order is a plugin-load artifact), and a waterfall listener that mutates the list owns the determinism of what it emits. A list without exactly one rest entry, or with duplicates, throws at load. Why a central list and not per-plugin weights: [Explicit model-facing tool order](../../../docs/rfc/implemented/feature/2026-07-06-explicit-tool-order.md). |
+| `toolOrder` | — | Explicit model-facing tool order, as a list of `ToolSchema.name`s with one `'<unlisted-tools>'` rest entry (`TOOL_ORDER_REST`): listed tools take their listed position, unlisted tools land at the rest entry in lexicographic name order. Absent ⇒ plain lexicographic name order. Applied to the collected tools BEFORE the `system-prompt/assemble` waterfall — like the sections' `order` sort, it canonicalizes what the registry contributed (registration order is a plugin-load artifact), and a waterfall listener that mutates the list owns the determinism of what it emits. Misconfiguration fails loud: a list without exactly one rest entry, or with duplicates, throws at load; a listed name with no registered tool rejects every `assemble()` — under the shipped loop the turn fails before any model request. Why a central list and not per-plugin weights: [Explicit model-facing tool order](../../../docs/rfc/implemented/feature/2026-07-06-explicit-tool-order.md). |
 
 ## Service: `SystemPrompt` (ctx key: `systemPrompt`)
 
@@ -16,7 +16,7 @@ System prompt assembly registry. Plugins contribute ordered text sections, tool-
 - `ctx.systemPrompt.section(section: PromptSection): () => void` Contribute a section. Duplicate names throw. Disposed with the calling fiber.
 - `ctx.systemPrompt.tools(provider: () => ToolSchema[]): () => void` Contribute tool schemas (evaluated at each assembly). Disposed with the calling fiber.
 - `ctx.systemPrompt.variable(name: string, provider: (context) => string | undefined): () => void` Contribute a prompt variable, referenced from section text as `{{name}}`. Duplicate or unreferenceable names throw; `undefined` means "no value for this assembly". Disposed with the calling fiber.
-- `ctx.systemPrompt.assemble(context?: AssembleContext): Promise<PromptAssembly>` Assemble the prompt for one caller. Runs through the `system-prompt/assemble` waterfall.
+- `ctx.systemPrompt.assemble(context?: AssembleContext): Promise<PromptAssembly>` Assemble the prompt for one caller. Runs through the `system-prompt/assemble` waterfall. Rejects when a configured `toolOrder` names a tool no provider contributed.
 
 ### Events
 

packages/core/system-prompt/src/index.ts

@@ -120,10 +120,13 @@ const GROUP_AT = /^\{\{([^{}]*)\}\}/
 export const TOOL_ORDER_REST = '<unlisted-tools>'
 
 /**
- * Validate a configured tool-order list at service construction: the
- * {@link TOOL_ORDER_REST} rest entry exactly once, no duplicate names. Returns the list
- * (or undefined when unconfigured); throws otherwise, failing the service at
- * load — a bad order config must never reach an assembly.
+ * Validate a configured tool-order list's shape at service construction:
+ * the {@link TOOL_ORDER_REST} rest entry exactly once, no duplicate names.
+ * Returns the list (or undefined when unconfigured); throws otherwise,
+ * failing the service at load — a bad order config must never reach an
+ * assembly. Whether every listed name matches a registered tool is checked
+ * at each assembly instead ({@link orderTools}): tool plugins register after
+ * this service constructs, so the tool set does not exist yet here.
  */
 function validateToolOrder(toolOrder: string[] | undefined): string[] | undefined {
   if (toolOrder === undefined) return undefined
@@ -141,12 +144,22 @@ function validateToolOrder(toolOrder: string[] | undefined): string[] | undefine
 /**
  * Order collected tool schemas by the validated policy: with no configured
  * list, plain lexicographic name order; with one, listed names take their
- * listed position and every unlisted tool lands at the {@link TOOL_ORDER_REST} rest entry in
- * lexicographic name order. Never drops a tool, and both sorts are stable, so
- * tools sharing a name keep their collection order.
+ * listed position and every unlisted tool lands at the
+ * {@link TOOL_ORDER_REST} rest entry in lexicographic name order. A listed
+ * name with no collected tool throws — misconfiguration fails loud, and this
+ * is the earliest moment the registered tool set exists to check against
+ * (tool plugins register after the service constructs, so load time is too
+ * early): the assembly rejects, failing the caller's turn before any model
+ * request. Never drops a tool, and both sorts are stable, so tools sharing a
+ * name keep their collection order.
  */
 function orderTools(tools: ToolSchema[], toolOrder: string[] | undefined): ToolSchema[] {
   if (toolOrder === undefined) return tools.sort(compareToolNames)
+  const registered = new Set(tools.map(tool => tool.name))
+  const unknown = toolOrder.filter(name => name !== TOOL_ORDER_REST && !registered.has(name))
+  if (unknown.length > 0) {
+    throw new Error(`toolOrder lists unregistered tool${unknown.length > 1 ? 's' : ''} ${unknown.map(name => `"${name}"`).join(', ')}; registered tools: ${[...registered].sort().join(', ') || '(none)'}`)
+  }
   const listed = new Set(toolOrder)
   const rest = tools.filter(tool => !listed.has(tool.name)).sort(compareToolNames)
   return toolOrder.flatMap(name =>
@@ -174,13 +187,17 @@ export interface Config {
   persona?: string
   /**
    * Explicit model-facing tool order, as a list of `ToolSchema.name`s: listed
-   * tools take their listed position, names with no registered tool are
-   * ignored, and tools absent from the list are inserted at the
-   * {@link TOOL_ORDER_REST} (`'<unlisted-tools>'`) entry in lexicographic name order. A
-   * configured list must contain the rest entry exactly once and no duplicate names —
-   * anything else throws at load; a bad order config must never reach a
-   * model request. When omitted, tools are ordered lexicographically by name.
-   * Applied to the tools {@link SystemPrompt.assemble} collects, BEFORE the
+   * tools take their listed position, and tools absent from the list are
+   * inserted at the {@link TOOL_ORDER_REST} (`'<unlisted-tools>'`) entry in
+   * lexicographic name order. A configured list must contain the rest entry
+   * exactly once, no duplicate names, and no name without a registered tool —
+   * a misconfigured order blocks work instead of silently reaching a model
+   * request: shape violations throw at load, and an unregistered name rejects
+   * every assembly (failing the turn before any model request — the earliest
+   * moment the registered tool set exists to check against, since tool
+   * plugins register after this service constructs). When omitted, tools are
+   * ordered lexicographically by name. Applied to the tools
+   * {@link SystemPrompt.assemble} collects, BEFORE the
    * `system-prompt/assemble` waterfall — like the sections' `order` sort, it
    * canonicalizes what the registry contributed (registration order is a
    * plugin-load artifact); a waterfall listener that mutates the tool list
@@ -394,7 +411,8 @@ export class SystemPrompt extends Service {
    * against `context` and sorted by order, tools collected from all providers
    * and put in the canonical model-facing order ({@link Config.toolOrder}, or
    * lexicographic name order when unconfigured — provider registration order
-   * is a plugin-load artifact and never reaches the assembly), and every
+   * is a plugin-load artifact and never reaches the assembly; a configured
+   * order naming a tool no provider contributed rejects the assembly), and every
    * registered variable resolved against `context` into `assembly.variables`.
    * Tool schemas are deep-cloned because adapters and request waterfalls may
    * mutate schema objects. Runs through the `system-prompt/assemble`
@@ -408,7 +426,10 @@ export class SystemPrompt extends Service {
    *   see {@link AssembleContext}).
    * @returns the assembly after the waterfall has run.
    */
-  assemble(context: AssembleContext = {}): Promise<PromptAssembly> {
+  // async so the misconfigured-toolOrder throw in orderTools surfaces as a
+  // rejection: a Promise-returning method must not throw synchronously
+  // (`assemble().catch(...)` would miss it).
+  async assemble(context: AssembleContext = {}): Promise<PromptAssembly> {
     const variables: Record<string, string | undefined> = {}
     for (const [name, provider] of this.variableProviders) {
       variables[name] = provider(context)

packages/core/system-prompt/tests/tool-order.spec.ts

@@ -18,6 +18,8 @@ function names(assembly: PromptAssembly): string[] {
 }
 
 describe('SystemPrompt tool order', () => {
+  // The ONE place the public constant's value is pinned; everything else
+  // (tests and deployment configs alike) references TOOL_ORDER_REST.
   it('exports the rest entry as "<unlisted-tools>"', () => {
     expect(TOOL_ORDER_REST).toBe('<unlisted-tools>')
   })
@@ -40,12 +42,25 @@ describe('SystemPrompt tool order', () => {
     expect(names(await backward.systemPrompt.assemble())).toEqual(['alpha', 'zulu'])
   })
 
-  it('applies a configured toolOrder: listed positions, rest at the rest entry lexicographically, absent names ignored', async () => {
-    const ctx = await mount({ toolOrder: ['todo_write', 'ghost', TOOL_ORDER_REST, 'bash'] })
+  it('applies a configured toolOrder: listed positions, rest at the rest entry lexicographically', async () => {
+    const ctx = await mount({ toolOrder: ['todo_write', TOOL_ORDER_REST, 'bash'] })
     ctx.systemPrompt.tools(() => [tool('bash'), tool('echo_b'), tool('todo_write'), tool('echo_a')])
     expect(names(await ctx.systemPrompt.assemble())).toEqual(['todo_write', 'echo_a', 'echo_b', 'bash'])
   })
 
+  it('rejects the assembly when toolOrder names a tool that is not registered (misconfiguration blocks work)', async () => {
+    const ctx = await mount({ toolOrder: ['todo_write', 'ghost', TOOL_ORDER_REST, 'wraith'] })
+    ctx.systemPrompt.tools(() => [tool('bash'), tool('todo_write')])
+    await expect(ctx.systemPrompt.assemble()).rejects.toThrow(
+      'toolOrder lists unregistered tools "ghost", "wraith"; registered tools: bash, todo_write')
+  })
+
+  it('names the single unregistered tool when no tools are registered at all', async () => {
+    const ctx = await mount({ toolOrder: ['ghost', TOOL_ORDER_REST] })
+    await expect(ctx.systemPrompt.assemble()).rejects.toThrow(
+      'toolOrder lists unregistered tool "ghost"; registered tools: (none)')
+  })
+
   it('keeps collection order between tools that share a name (stable sort)', async () => {
     const ctx = await mount()
     ctx.systemPrompt.tools(() => [tool('dup', 'first'), tool('anchor'), tool('dup', 'second')])

packages/ui/acp-agent/README.md

@@ -24,7 +24,7 @@ Because the package wires no logger entry, an ACP leaf has **nothing to get wron
 |---|---|---|
 | `model` | (required) | the per-session agent template the bridge creates agents from |
 | `persona` | — | the deployment persona template (may reference `{{model}}`/`{{cwd}}`), routed to `dsh-system-prompt` |
-| `toolOrder` | — | explicit model-facing tool order (a name list with one `'<unlisted-tools>'` rest entry; absent — lexicographic), routed to `dsh-system-prompt` |
+| `toolOrder` | — | explicit model-facing tool order (a name list with one `'<unlisted-tools>'` rest entry; absent — lexicographic; an unregistered name fails each turn at prompt assembly), routed to `dsh-system-prompt` |
 | `persistenceRoot` | `./.sessions` | the JSONL backend's root directory |
 
 The leaf supplies the swappable backends: an LLM adapter (`llm-deepseek` for the real model, `llm-replay` for keyless snapshot replay) and a bash executor (`bash-local`).

packages/ui/stdio-agent/README.md

@@ -25,7 +25,7 @@ The leaf `cordis.yml` supplies only the **swappable backends** — an LLM adapte
 |---|---|---|
 | `model` | (required) | the pre-created `main` agent's model |
 | `persona` | — | the deployment persona template (may reference `{{model}}`), routed to `dsh-system-prompt` |
-| `toolOrder` | — | explicit model-facing tool order (a name list with one `'<unlisted-tools>'` rest entry; absent — lexicographic), routed to `dsh-system-prompt` |
+| `toolOrder` | — | explicit model-facing tool order (a name list with one `'<unlisted-tools>'` rest entry; absent — lexicographic; an unregistered name fails each turn at prompt assembly), routed to `dsh-system-prompt` |
 | `persistenceRoot` | `./.sessions` | the JSONL backend's root directory |
 | `welcome` | `ready.` | the stdin-chat banner |
 | `resumeSessionId` | — | resume a persisted session id instead of starting fresh (sourced from an env var in the leaf) |