fix(review): reconcile sandbox and approval contracts

2026-07-11 21:37:38 +08:00
parent 6a13dcb364
commit b29a8eca71
61 changed files with 620 additions and 358 deletions
--- a/packages/README.md
+++ b/packages/README.md
@@ -13,7 +13,6 @@ Packages are grouped by modular role at `packages/<group>/<pkg>/`. The group dir
 | [`bash/`](bash/README.md) | Bash capability family: the executor seam, a local impl, and the model-facing tool | Product — stable surface |
 | [`code-runtime/`](code-runtime/README.md) | Code-execution capability family: the abstract runtime seam for model-written programs + a worker-thread backend | Product — stable surface |
 | [`sandbox/`](sandbox/README.md) | Process-confinement seam; bwrap/Landlock/Seatbelt backends | Product — stable surface |
-| [`approval/`](approval/README.md) | One-shot permission decisions | Product — stable surface |
 | [`fs/`](fs/README.md) | Filesystem capability family: the abstract seam, a local impl, and the model-facing file tools | Product — stable surface |
 | [`compact/`](compact/README.md) | Compaction capability family: the abstract seam + a basic backend (tool deferred) | Product — stable surface |
 | [`subagent/`](subagent/README.md) | Subagent capability family: the provider-registry seam and the model-facing delegation tool | Product — stable surface |
@@ -25,7 +24,7 @@ Packages are grouped by modular role at `packages/<group>/<pkg>/`. The group dir
 | [`cordis/`](cordis/README.md) | Self-referential runtime toolset: inspect the live runtime's plugins and services, mount/unmount model-written plugins ([design](../docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md)) | Product — stable surface |
 | [`hooks/`](hooks/README.md) | Hook bridges + the shared Claude Code / Codex wire-protocol library | Product — stable surface |
 | [`session-persistence/`](session-persistence/README.md) | Persistence capability family: the seam + JSONL/SQLite backends | Product — stable surface |
-| [`ui/`](ui/README.md) | Editor/client integration surfaces: ACP bridge, app packages, user-interaction seam, ask-user tool | Product — stable surface |
+| [`ui/`](ui/README.md) | Editor/client integration surfaces: ACP bridge, app packages, user-approval and user-interaction seams, ask-user tool | Product — stable surface |
 | [`support/`](support/README.md) | Dev/test/example infrastructure (invariants, replay adapter, subagent mock) | Support — lower compatibility expectations |
 | [`util/`](util/README.md) | Low-level zero-dependency utilities shared across groups (the `Branded<B>` primitive) | Support — small, stable, harness-dep-free |

--- a/packages/approval/README.md
+++ b/packages/approval/README.md
@@ -1,9 +0,0 @@
-# approval/ — approval family
-
-The asking half of permission handling: one seam through which the harness puts a one-shot question — "may this specific action proceed?" — to whatever answerers a deployment composes, with a closed outcome vocabulary and a fail-closed default. The full design: [the approval-seam RFC](../../docs/rfc/implemented/feature/2026-07-06-approval-seam.md). All **product** packages.
-
-| Package | Role | ctx key |
-|---|---|---|
-| `approval/` | The `ApprovalService` mechanism (waterfall dispatch, cancellation, audit events) + the vocabulary (`ApprovalRequest`, `ApprovalOutcome`, `ApprovalRequestId`) + the per-session policy tier (`ApprovalPolicy` `'ask'`/`'never'`, the `'approval/policy'` event fold, the prepend gate — [sandbox RFC § Per-session mode switching](../../docs/rfc/implemented/feature/2026-07-06-sandbox.md)) | `ctx.approval` |
-
-Answerers live with their owners, not here: the ACP bridge ([`ui/acp`](../ui/acp/)) answers for the editor sessions it owns (and switches each session's policy over ACP config options); tests answer with inline scripted listeners. Consumers today: [`core/tools`](../core/tools/) routes `tools/pre-execute`'s `ask` through the seam (degrading to deny when it is not mounted), and the bash tool's sandbox escalation gate ([`bash/tool-bash`](../bash/tool-bash/), [sandbox RFC § Escalation](../../docs/rfc/implemented/feature/2026-07-06-sandbox.md)).
--- a/packages/bash/bash-sandbox/src/index.ts
+++ b/packages/bash/bash-sandbox/src/index.ts
@@ -35,7 +35,8 @@
 * `dsh-tool-bash` through `ctx.approval` — this executor's contribution is the
 * per-call `sandboxMode` override it honors in {@link resolve}: an escalated
 * call runs (and classifies, and reports) under ITS granted mode while every
- * neighboring call keeps the configured default.
+ * neighboring call keeps its session's standing mode (or the configured
+ * default when that session has no override).
 *
 * @module @deepseek-ai/dsh-bash-sandbox
 */
@@ -138,17 +139,13 @@ function matchesSignature(exitCode: number | null, stderr: string, signatures: r
 /**
 * Sandbox-consuming bash executor. Registers as `ctx.bash` (loading it
 * INSTEAD OF `dsh-bash-local`, together with a `ctx.sandbox` provider, is
- * the whole swap — the tool layer is untouched). The DEFAULT mode is fixed at
- * config time for the executor's lifetime; a single call escalates past it
- * only through the request-level `sandboxMode` override its {@link resolve}
- * stamps onto the spec (granted upstream via `ctx.approval` — the
- * sandbox RFC § Escalation). The model learns of the sandbox only through
- * result facts: the static bash tool description explains the denial marker,
- * and every run's `result.sandbox` carries the mode it executed under and how
- * completely the runner enforced it. Runtime default-mode switching and a
- * current-mode prompt statement are deliberately absent until a config
- * surface exists to drive them (TODO(sandbox-config): the sandbox RFC's
- * future-work list brings both with the per-session config options).
+ * the whole swap — the tool layer is untouched). Its configured mode is the
+ * fallback exposed by {@link sandboxMode}; `dsh-tool-bash` folds a session's
+ * durable `bash/sandbox-mode` override and stamps the effective mode onto each
+ * request, while an approved escalation may stamp a strictly wider mode for
+ * one call. The tool's per-agent prompt section states that same effective
+ * mode, and each run's `result.sandbox` reports what actually executed plus
+ * enforcement completeness.
 */
 export class SandboxBashExecutor extends LocalBashExecutor {
  static inject = ['sandbox']
--- a/packages/bash/bash/src/index.ts
+++ b/packages/bash/bash/src/index.ts
@@ -76,11 +76,12 @@ export abstract class BashExecutor extends Service {
  /**
   * The sandbox mode this executor confines commands under BY DEFAULT, or
   * `undefined` when it does not sandbox at all — the capability fact the
-   * tool layer reads to advertise escalation honestly (a mode-widening lever
-   * is only offered when a sandboxing executor is mounted to honor it, and
-   * only for modes strictly wider than this one). Composition truth, not
-   * configuration: the base class reports `undefined`; a sandboxing
-   * implementation overrides the getter with its configured mode.
+   * tool and ACP layers read to advertise sandbox controls honestly. The
+   * getter proves a sandboxing executor is mounted and supplies its fallback
+   * mode; a session override may make the effective mode narrower or wider,
+   * so strict escalation widening is checked per call rather than encoded in
+   * this default-relative capability fact. The base class reports
+   * `undefined`; a sandboxing implementation overrides the getter.
   * @returns the configured default mode of a sandboxing executor;
   *   `undefined` for an executor that never confines.
   */
--- a/packages/bash/tool-bash/README.md
+++ b/packages/bash/tool-bash/README.md
@@ -52,7 +52,7 @@ The `BashExecRequest` seam carries optional `stdin` and `env`, used by the hooks

 Commands run with the executor's full authority unless a sandboxing executor ([`dsh-bash-sandbox`](../bash-sandbox/)) confines them — the deny-only sandbox reports denials as result facts, rendered here as the denial marker; per-call allow/deny/ask policy is the `tools/pre-execute` waterfall (see docs/architecture.md).

-On top of a denial sits the escalation gate ([the sandbox RFC § Escalation](../../../docs/rfc/implemented/feature/2026-07-06-sandbox.md)): an escalating call (`sandbox_permissions` + `justification`) resolves [`ctx.approval`](../../approval/approval/README.md) BEFORE anything executes — `allowed-once` stamps the granted mode onto the bash request as the seam-level `sandboxMode` override (that one call runs, classifies, and reports under the wider mode; its neighbors keep the session's effective mode), while `rejected`/`cancelled`/`unavailable` and the no-service / no-agent paths each fail closed with their own error text and execute nothing. The seam is consumed opportunistically (`ctx.get('approval')`, the dsh-tools ask-routing pattern); the grant is consumed by the very call that asked, and nothing is stored. The static description teaches — and a denied result itself prompts, via the escalation-available marker appended exactly when the fields are advertised — the SAME-TURN flow: on a denial a wider mode would cure, retry the exact command once with `sandbox_permissions` (the narrowest mode that suffices) + `justification` immediately, without detouring through chat (the approval prompt IS the user's consent); never speculatively — an escalation is grounded in a real denial (up-front only when the session already denied the same access), a prompt-stated approvals-disabled policy turns the exception off entirely, and a rejected escalation is final for that command.
+On top of a denial sits the escalation gate ([the sandbox RFC § Escalation](../../../docs/rfc/implemented/feature/2026-07-06-sandbox.md)): an escalating call (`sandbox_permissions` + `justification`) resolves [`ctx.approval`](../../ui/user-approval/README.md) BEFORE anything executes — `allowed-once` stamps the granted mode onto the bash request as the seam-level `sandboxMode` override (that one call runs, classifies, and reports under the wider mode; its neighbors keep the session's effective mode), while `rejected`/`cancelled`/`unavailable` and the no-service / no-agent paths each fail closed with their own error text and execute nothing. The seam is consumed opportunistically (`ctx.get('approval')`, the dsh-tools ask-routing pattern); the grant is consumed by the very call that asked, and nothing is stored. The static description teaches — and a denied result itself prompts, via the escalation-available marker appended exactly when the fields are advertised — the SAME-TURN flow: on a denial a wider mode would cure, retry the exact command once with `sandbox_permissions` (the narrowest mode that suffices) + `justification` immediately, without detouring through chat (the approval prompt IS the user's consent); never speculatively — an escalation is grounded in a real denial (up-front only when the session already denied the same access), a prompt-stated approvals-disabled policy turns the exception off entirely, and a rejected escalation is final for that command.

 ## Per-session mode switching

--- a/packages/bash/tool-bash/package.json
+++ b/packages/bash/tool-bash/package.json
@@ -23,7 +23,7 @@
  "license": "BSD-3-Clause",
  "peerDependencies": {
    "@deepseek-ai/dsh-agent": "^0.0.1",
-    "@deepseek-ai/dsh-approval": "^0.0.1",
+    "@deepseek-ai/dsh-user-approval": "^0.0.1",
    "@deepseek-ai/dsh-bash": "^0.0.1",
    "@deepseek-ai/dsh-llm": "^0.0.1",
    "@deepseek-ai/dsh-sandbox": "^0.0.1",
@@ -34,7 +34,7 @@
  "devDependencies": {
    "@deepseek-ai/dsh-agent": "workspace:^",
    "@deepseek-ai/dsh-agent-loop": "workspace:^",
-    "@deepseek-ai/dsh-approval": "workspace:^",
+    "@deepseek-ai/dsh-user-approval": "workspace:^",
    "@deepseek-ai/dsh-bash": "workspace:^",
    "@deepseek-ai/dsh-bash-local": "workspace:^",
    "@deepseek-ai/dsh-bash-sandbox": "workspace:^",
--- a/packages/bash/tool-bash/src/index.ts
+++ b/packages/bash/tool-bash/src/index.ts
@@ -65,7 +65,7 @@ import type {} from '@deepseek-ai/dsh-system-prompt'
 // Side-effect type import: declaration-merges `ctx.approval`, consumed
 // opportunistically by the escalation gate (`ctx.get('approval')` — the seam
 // stays optional at runtime, same pattern as dsh-tools' ask routing).
-import type {} from '@deepseek-ai/dsh-approval'
+import type {} from '@deepseek-ai/dsh-user-approval'
 import type { SandboxMode } from '@deepseek-ai/dsh-sandbox'
 import { BashTaskId, OwnerToken, effectiveSandboxMode } from '@deepseek-ai/dsh-bash'
 import type { BashRunResult, BashTask, CollectedOutput } from '@deepseek-ai/dsh-bash'
@@ -471,12 +471,12 @@ export function apply(ctx: Context): void {
    }
  })

-  // The escalation surface exists exactly when the mounted executor confines
-  // under a default that has a strictly wider mode to escalate to — a lever
-  // is never advertised that the composition cannot honor. Registration time
-  // is the right read: the executor's default is config-fixed for its
-  // lifetime, and an executor swap restarts this fiber (static inject) and
-  // re-registers the schema.
+  // The escalation surface exists whenever the mounted executor confines.
+  // Its enum is the closed target vocabulary, deliberately NOT cut down by
+  // the configured default: a session may switch to a narrower effective mode
+  // while sharing this globally registered schema. Strict widening therefore
+  // belongs to the per-call check below. An executor swap restarts this fiber
+  // (static inject) and re-registers the schema.
  const defaultMode = ctx.bash.sandboxMode
  const escalationModes: readonly SandboxMode[] = defaultMode === undefined ? [] : ESCALATION_TARGETS

@@ -505,8 +505,7 @@ export function apply(ctx: Context): void {
   */
  const approveEscalation = async (mode: string, justification: string, exec: ToolExecution): Promise<SandboxMode> => {
    // Schema validation only checks ADVERTISED keys, so an unadvertised
-    // `sandbox_permissions` (no sandboxing executor, or a `danger-full-access`
-    // default with nothing wider) still reaches execute — reject it here so a
+    // `sandbox_permissions` (no sandboxing executor) still reaches execute — reject it here so a
    // human is never prompted to "escalate" a sandbox that is not there. When
    // the fields ARE advertised, the registry's SchemaSpec enum has already
    // pinned `mode` to this ladder for every caller.
@@ -540,8 +539,8 @@ export function apply(ctx: Context): void {
      ...exec.signal ? { signal: exec.signal } : {},
    })
    switch (outcome) {
-      // The SchemaSpec enum already pinned `mode` to this executor's wider
-      // ladder; the cast records that validated fact.
+      // The SchemaSpec enum already pinned `mode` to the closed target
+      // vocabulary; the per-call check above proved it is strictly wider.
      case 'allowed-once': return mode as SandboxMode
      case 'rejected': throw new Error(`the user rejected escalating this command to "${mode}"`)
      case 'cancelled': throw new Error(`approval for escalating to "${mode}" was cancelled`)
--- a/packages/bash/tool-bash/tests/tools.spec.ts
+++ b/packages/bash/tool-bash/tests/tools.spec.ts
@@ -16,8 +16,8 @@ import { SandboxBashExecutor } from '@deepseek-ai/dsh-bash-sandbox'
 import { SandboxProvider } from '@deepseek-ai/dsh-sandbox'
 import type { ConfinedArgv } from '@deepseek-ai/dsh-sandbox'
 import { LocalSandboxProvider } from '@deepseek-ai/dsh-sandbox-local'
-import ApprovalService from '@deepseek-ai/dsh-approval'
-import type { ApprovalOutcome } from '@deepseek-ai/dsh-approval'
+import ApprovalService from '@deepseek-ai/dsh-user-approval'
+import type { ApprovalOutcome } from '@deepseek-ai/dsh-user-approval'
 import * as ToolBash from '@deepseek-ai/dsh-tool-bash'
 import { renderResult } from '@deepseek-ai/dsh-tool-bash'

@@ -27,6 +27,13 @@ const spillDir = mkdtempSync(join(tmpdir(), 'dsh-tool-bash-spec-'))
 // profile args up to `--` and execs the command unconfined — deterministic
 // without a host bwrap.
 const PASSTHROUGH_RUNNER = ['bash', '-c', 'while [ "$1" != "--" ]; do shift; done; shift; exec "$@"', 'passthrough-runner']
+const PASSTHROUGH_RUNNER_CONFIG = {
+  runnerCommand: PASSTHROUGH_RUNNER,
+  // The script has no pre-exec failure path; the provider still requires an
+  // explicit dialect so a future script change cannot silently turn runner
+  // failure into an ordinary command result.
+  runnerFailureSignatures: ['passthrough-runner: profile rejected'],
+}

 async function setup() {
  const ctx = new Context()
@@ -1022,7 +1029,7 @@ describe('sandbox rendering', () => {
    await ctx.plugin(SystemPrompt)
    await ctx.plugin(ToolRegistry)
    await ctx.plugin(AgentRegistry)
-    await ctx.plugin(LocalSandboxProvider, { runnerCommand: PASSTHROUGH_RUNNER })
+    await ctx.plugin(LocalSandboxProvider, PASSTHROUGH_RUNNER_CONFIG)
    await ctx.plugin(SandboxBashExecutor, { graceMs: 200 })
    const bash = ctx.bash as SandboxBashExecutor
    bash.internals = { spillDir }
@@ -1113,12 +1120,31 @@ describe('sandbox rendering', () => {
    expect(text(read)).not.toContain('file access denied')
  })

+  it('classifies an executable configured runner that refuses its profile before the command runs', async () => {
+    const signature = 'custom-runner-rejected'
+    const ctx = new Context()
+    await ctx.plugin(LocalSandboxProvider, {
+      runnerCommand: ['bash', '-c', `printf '${signature}\\n' >&2; exit 125`, 'custom-runner'],
+      runnerFailureSignatures: [signature],
+    })
+    await ctx.plugin(SandboxBashExecutor, { graceMs: 200 })
+    const bash = ctx.bash as SandboxBashExecutor
+    bash.internals = { spillDir }
+
+    await expect(bash.run(bash.resolve({ command: 'echo command-must-not-run' })))
+      .rejects.toMatchObject({ code: 'SANDBOX_UNAVAILABLE' })
+
+    const task = bash.start(bash.resolve({ command: 'echo command-must-not-run' }))
+    await task.done
+    expect(task.sandbox).toEqual({ mode: 'read-only', denied: false, enforcement: 'full', runnerFailed: true })
+  })
+
  it('reports a real denial end-to-end through the shipping sandbox executor', async () => {
    const ctx = new Context()
    await ctx.plugin(SystemPrompt)
    await ctx.plugin(ToolRegistry)
    await ctx.plugin(AgentRegistry)
-    await ctx.plugin(LocalSandboxProvider, { runnerCommand: PASSTHROUGH_RUNNER })
+    await ctx.plugin(LocalSandboxProvider, PASSTHROUGH_RUNNER_CONFIG)
    await ctx.plugin(SandboxBashExecutor, { graceMs: 200 })
    const bash = ctx.bash as SandboxBashExecutor
    bash.internals = { spillDir }
@@ -1141,7 +1167,7 @@ describe('sandbox escalation (sandbox_permissions / justification)', () => {
    await ctx.plugin(SystemPrompt)
    await ctx.plugin(ToolRegistry)
    await ctx.plugin(AgentRegistry)
-    await ctx.plugin(LocalSandboxProvider, { runnerCommand: PASSTHROUGH_RUNNER })
+    await ctx.plugin(LocalSandboxProvider, PASSTHROUGH_RUNNER_CONFIG)
    await ctx.plugin(SandboxBashExecutor, { graceMs: 200, ...mode !== undefined ? { mode } : {} })
    const bash = ctx.bash as SandboxBashExecutor
    bash.internals = { spillDir }
@@ -1363,7 +1389,7 @@ describe('per-session sandbox mode (the bash/sandbox-mode fold)', () => {
    await ctx.plugin(SystemPrompt)
    await ctx.plugin(ToolRegistry)
    await ctx.plugin(AgentRegistry)
-    await ctx.plugin(LocalSandboxProvider, { runnerCommand: PASSTHROUGH_RUNNER })
+    await ctx.plugin(LocalSandboxProvider, PASSTHROUGH_RUNNER_CONFIG)
    await ctx.plugin(SandboxBashExecutor, { graceMs: 200, mode })
    ;(ctx.bash as SandboxBashExecutor).internals = { spillDir }
    if (opts.approval === true) await ctx.plugin(ApprovalService)
--- a/packages/bash/tool-bash/tsconfig.json
+++ b/packages/bash/tool-bash/tsconfig.json
@@ -30,7 +30,7 @@
      "path": "../../core/system-prompt"
    },
    {
-      "path": "../../approval/approval"
+      "path": "../../ui/user-approval"
    },
    {
      "path": "../../sandbox/sandbox"
--- a/packages/core/tools/README.md
+++ b/packages/core/tools/README.md
@@ -38,7 +38,7 @@ tools:
 - `ToolDefinition` — `ToolSchema` + `execute(args, exec): Promise<ContentBlock[] | { content: ContentBlock[]; meta? }>` (the bare array is the model-facing content; the object form additionally attaches an opaque, JSON-serializable `meta` presentation payload persisted on the `tool/result` event and handed back to `presentResult`), plus optional `presentCall(args)` / `presentResult(args, result)` for tool-owned UI presentation (see below). It also carries an optional cooperative timeout budget `timeoutMs?: number` (ms) enforced by `@deepseek-ai/dsh-timeout-policy`, never sent to the model.
 - `ToolExecution` — one pending tool call: `{ callId, name, arguments, agent?, signal? }`.
 - `ToolExecutionResult` — outcome: `{ callId, content, isError, error?, additionalContext?, meta? }`. On failure with a `HarnessError`, `error: { name, code }` carries the structured failure class alongside the model-facing text (the loop forwards it onto the `tool/result` session event for retry/sandbox plugins and replay). `additionalContext` (a `HookContext`) ferries any `tools/post-execute` context up to the loop, which buffers it and appends it as a `context/message` after all `tool/result`s in the step. `meta` is the tool's opaque presentation payload from a successful `execute` (the object return form); the loop forwards it onto the `tool/result` session event for result-card rendering.
- `PreToolDecision` — `{kind:'allow'}` | `{kind:'deny', reason}` | `{kind:'ask', reason?}`. Input rewrite (changing `arguments`) is deliberately NOT offered (it would desync the pre-execution audit/history/UI from what ran — its own proposed RFC); `ask` is serviced by [`ctx.approval`](../../approval/approval/README.md) when a deployment mounts it (`allowed-once` proceeds to dispatch; `rejected`/`cancelled`/`unavailable` deny with distinct reasons) and degrades to `deny` when none is mounted or the execution carries no agent.
+- `PreToolDecision` — `{kind:'allow'}` | `{kind:'deny', reason}` | `{kind:'ask', reason?}`. Input rewrite (changing `arguments`) is deliberately NOT offered (it would desync the pre-execution audit/history/UI from what ran — its own proposed RFC); `ask` is serviced by [`ctx.approval`](../../ui/user-approval/README.md) when a deployment mounts it (`allowed-once` proceeds to dispatch; `rejected`/`cancelled`/`unavailable` deny with distinct reasons) and degrades to `deny` when none is mounted or the execution carries no agent.
 - `PostToolDecision` — `{kind:'accept', content?, additionalContext?}` (keep the call successful, optionally replacing the model-facing content) | `{kind:'block', feedback, additionalContext?}` (turn it into an `isError` whose content is the corrective feedback). Output replacement is clean because `tool/result` is logged AFTER `execute()` returns.
 - `ToolCallView` / `ToolResultView` — provider-neutral `card`-tagged render intents a tool returns from `presentCall` / `presentResult` to own how a UI renders ITS calls (see "Tool-owned UI presentation").

--- a/packages/core/tools/package.json
+++ b/packages/core/tools/package.json
@@ -23,7 +23,7 @@
  "license": "BSD-3-Clause",
  "peerDependencies": {
    "@deepseek-ai/dsh-agent": "^0.0.1",
-    "@deepseek-ai/dsh-approval": "^0.0.1",
+    "@deepseek-ai/dsh-user-approval": "^0.0.1",
    "@deepseek-ai/dsh-code-runtime": "^0.0.1",
    "@deepseek-ai/dsh-llm": "^0.0.1",
    "@deepseek-ai/dsh-session": "^0.0.1",
@@ -35,7 +35,7 @@
  },
  "devDependencies": {
    "@deepseek-ai/dsh-agent": "workspace:^",
-    "@deepseek-ai/dsh-approval": "workspace:^",
+    "@deepseek-ai/dsh-user-approval": "workspace:^",
    "@deepseek-ai/dsh-code-runtime": "workspace:^",
    "@deepseek-ai/dsh-llm": "workspace:^",
    "@deepseek-ai/dsh-session": "workspace:^",
--- a/packages/core/tools/src/index.ts
+++ b/packages/core/tools/src/index.ts
@@ -25,7 +25,7 @@ import type {} from '@deepseek-ai/dsh-system-prompt'
 import type { CodeRuntime } from '@deepseek-ai/dsh-code-runtime'
 // Type-only: makes `ctx.get('approval')` resolve to the ApprovalService
 // augmentation. The seam stays optional at runtime — see `serviceAsk`.
-import type {} from '@deepseek-ai/dsh-approval'
+import type {} from '@deepseek-ai/dsh-user-approval'
 import type { ToolCallView, ToolResultView } from './presentation.ts'
 import { createRunCodeTool, RUN_CODE_NAME, SDK_SECTION_ORDER } from './code-mode.ts'
 import { renderToolsSdk } from './ts-types.ts'
--- a/packages/core/tools/tests/tools.spec.ts
+++ b/packages/core/tools/tests/tools.spec.ts
@@ -3,7 +3,7 @@ import { Context } from 'cordis'
 import { CallId, HarnessError } from '@deepseek-ai/dsh-llm'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import type { Agent } from '@deepseek-ai/dsh-agent'
-import ApprovalService, { type ApprovalOutcome, type ApprovalRequest } from '@deepseek-ai/dsh-approval'
+import ApprovalService, { type ApprovalOutcome, type ApprovalRequest } from '@deepseek-ai/dsh-user-approval'
 import ToolRegistry, {
  defineTool, schemaSpecToJsonSchema, validateArgs, ToolArgsError, ToolNotFoundError,
  type InferArgs, type SchemaSpec, type PreToolDecision, type PostToolDecision,
--- a/packages/core/tools/tsconfig.json
+++ b/packages/core/tools/tsconfig.json
@@ -30,7 +30,7 @@
      "path": "../../core/agent"
    },
    {
-      "path": "../../approval/approval"
+      "path": "../../ui/user-approval"
    }
  ]
 }
--- a/packages/sandbox/sandbox-local/src/index.ts
+++ b/packages/sandbox/sandbox-local/src/index.ts
@@ -41,7 +41,9 @@ export interface Config {
   * `enforcement: 'full'`, and — the runner's kernel mechanism being unknown
   * — carries both Linux file-denial dialects as its denial signatures) —
   * the runner chain and its probes are skipped,
-   * and a broken runner fails loudly at spawn time like any missing command.
+   * and a broken runner fails loudly at execution time. The operator also
+   * supplies {@link runnerFailureSignatures}, which distinguish the runner
+   * refusing its profile from the wrapped command failing normally.
   * Absent (or empty — the schema normalizes an omitted array to `[]`): the
   * built-in platform chains — Linux `bwrap` then the Landlock launcher
   * (probed in that order), darwin `sandbox-exec` (the sole candidate,
@@ -49,6 +51,15 @@ export interface Config {
   * for deterministic fake runners in keyless test tiers.
   */
  runnerCommand?: string[]
+  /**
+   * Case-insensitive stderr substrings emitted when a configured
+   * {@link runnerCommand} refuses its profile before executing the wrapped
+   * command. Required and non-empty with `runnerCommand`; rejected without
+   * it. Missing/unexecutable runner errors are added automatically from
+   * `runnerCommand[0]`, while these signatures cover an executable runner's
+   * own failure dialect.
+   */
+  runnerFailureSignatures?: string[]
  /**
   * Per-probe timeout in milliseconds for the chain's functional probes
   * (default: 5000; must be a positive finite number — Node treats a 0
@@ -309,6 +320,7 @@ export class LocalSandboxProvider extends SandboxProvider {
  // Inline schema call: the config catalog walks `static Config` statically.
  static Config: z<Config> = z.object({
    runnerCommand: z.array(z.string()).default([]),
+    runnerFailureSignatures: z.array(z.string()).default([]),
    probeTimeoutMs: z.natural().default(5_000),
  })

@@ -316,17 +328,29 @@ export class LocalSandboxProvider extends SandboxProvider {
  internals: SandboxInternals = {}

  private readonly runnerCommand: string[] | undefined
+  private readonly configuredRunnerFailureSignatures: string[]
  private readonly probeTimeoutMs: number
  /** Cached chain verdict; undefined until the first confined wrap needs it. */
  private selectedRunner: SelectedRunner | 'unavailable' | undefined

  constructor(ctx: Context, config: Config) {
    super(ctx)
-    // The schema (static Config) defaults both fields — the casts record
+    // The schema (static Config) defaults every field — the casts record
    // those runtime facts. An empty runnerCommand means "not configured":
    // use the platform chain.
    const runner = config.runnerCommand as string[]
+    const runnerFailureSignatures = config.runnerFailureSignatures as string[]
+    if (runner.length === 0 && runnerFailureSignatures.length > 0) {
+      throw new Error('sandbox-local: runnerFailureSignatures requires runnerCommand')
+    }
+    if (runner.length > 0 && runnerFailureSignatures.length === 0) {
+      throw new Error('sandbox-local: runnerCommand requires at least one runnerFailureSignatures entry')
+    }
+    if (runnerFailureSignatures.some(signature => signature.trim().length === 0)) {
+      throw new Error('sandbox-local: runnerFailureSignatures entries must be non-empty')
+    }
    this.runnerCommand = runner.length > 0 ? runner : undefined
+    this.configuredRunnerFailureSignatures = runnerFailureSignatures
    this.probeTimeoutMs = config.probeTimeoutMs as number
    assertPositiveFinite('probeTimeoutMs', this.probeTimeoutMs)
  }
@@ -351,17 +375,16 @@ export class LocalSandboxProvider extends SandboxProvider {
        argv: [...this.runnerCommand, ...bwrapProfileArgs(policy), '--', ...argv],
        enforcement: 'full',
        denialSignatures: DENIAL_SIGNATURES.runnerCommand,
-        // The configured runner's own failure dialect is unknown (as is its
-        // kernel mechanism), but the consumer never spawns the wrap directly
-        // — it re-joins it through an outer `bash -c 'exec …'` — so a
-        // missing or unexecutable runner fails with the OUTER shell's
-        // argv0-scoped shapes, and those we do know. Scoping every shape to
+        // The operator names the configured runner's OWN pre-exec refusal
+        // dialect; the consumer additionally re-joins the wrap through an
+        // outer `bash -c 'exec …'`, so we can add the missing/unexecutable
+        // outer-shell shapes ourselves. Scoping every automatic shape to
        // argv0 keeps in-command errors out (a bare `exec:`/`Permission
-        // denied` prefix would claim tool output; `exec: <argv0>: not
-        // found` cannot). The residual collision — a command invoking a
-        // file named exactly like the runner and hitting the same errno —
-        // is the classifier's documented conservative-inference trade.
+        // denied` prefix would claim tool output; `exec: <argv0>: not found`
+        // cannot). The residual text-collision trade is documented by the
+        // seam's conservative classifier contract.
        runnerFailureSignatures: [
+          ...this.configuredRunnerFailureSignatures,
          `exec: ${argv0}: not found`,
          `${argv0}: No such file or directory`,
          `${argv0}: Permission denied`,
--- a/packages/sandbox/sandbox-local/tests/local.spec.ts
+++ b/packages/sandbox/sandbox-local/tests/local.spec.ts
@@ -102,7 +102,10 @@ describe('runnerCommand config', () => {
    const probeBwrap = vi.fn(() => false)
    const probeLandlock = vi.fn(() => 'unusable' as const)
    const probeSeatbelt = vi.fn(() => false)
-    const { sandbox } = await setup({ runnerCommand: ['fake-runner', '--flag'] }, { probeBwrap, probeLandlock, probeSeatbelt })
+    const { sandbox } = await setup({
+      runnerCommand: ['fake-runner', '--flag'],
+      runnerFailureSignatures: ['fake-runner: profile rejected'],
+    }, { probeBwrap, probeLandlock, probeSeatbelt })
    const confined = sandbox.confine(['bash', '-c', 'echo hi'], WW)
    expect(confined).toEqual({
      argv: ['fake-runner', '--flag', ...bwrapProfileArgs(WW), '--', 'bash', '-c', 'echo hi'],
@@ -115,6 +118,7 @@ describe('runnerCommand config', () => {
      // unexecutable runner fails with the OUTER shell's argv0-scoped
      // shapes, and those classify as sandbox failures like any rung.
      runnerFailureSignatures: [
+        'fake-runner: profile rejected',
        'exec: fake-runner: not found',
        'fake-runner: No such file or directory',
        'fake-runner: Permission denied',
@@ -131,6 +135,24 @@ describe('runnerCommand config', () => {
    expect(() => sandbox.confine(['true'], RO)).toThrow(SandboxUnavailableError)
    expect(probeBwrap).toHaveBeenCalledTimes(1)
  })
+
+  it('requires an operator-owned failure dialect for every configured runner', async () => {
+    await expect(setup({ runnerCommand: ['fake-runner'] })).rejects.toThrow(
+      'runnerCommand requires at least one runnerFailureSignatures entry',
+    )
+  })
+
+  it('rejects runner failure signatures when no custom runner consumes them', async () => {
+    await expect(setup({ runnerFailureSignatures: ['profile rejected'] })).rejects.toThrow(
+      'runnerFailureSignatures requires runnerCommand',
+    )
+  })
+
+  it('rejects blank configured-runner failure signatures', async () => {
+    await expect(setup({ runnerCommand: ['fake-runner'], runnerFailureSignatures: ['  '] })).rejects.toThrow(
+      'runnerFailureSignatures entries must be non-empty',
+    )
+  })
 })

 describe('the platform chains', () => {
--- a/packages/ui/README.md
+++ b/packages/ui/README.md
@@ -5,6 +5,7 @@ Integrations that expose the agent to an external editor or client. These are **
 | Package | Role | ctx key |
 |---|---|---|
 | `acp/` | Agent Client Protocol bridge: serves the agent to an ACP editor (Zed) over JSON-RPC stdio | (drives `ctx.agents`/`ctx.sessions`) |
+| `user-approval/` | One-shot user-approval mechanism, closed outcome vocabulary, audit events, and per-session approval policy | `ctx.approval` |
 | `user-interaction/` | Abstract human question/answer seam used by UI-backed confirmation tools | `ctx.userInteraction` |
 | `tool-ask-user/` | Model-facing `ask_user_question` tool over `ctx.userInteraction` | (registers on `ctx.tools`) |
 | `stdio-agent/` | Terminal stdio chat APP: the agent-core spine + console logger + readline UI + a pre-created `main` agent, with a `bin` | (composition + `bin`) |
@@ -13,6 +14,6 @@ Integrations that expose the agent to an external editor or client. These are **

 A UI integration is a client-driver plugin, not a loop change and not a capability seam: it consumes the existing `agent/*` event taxonomy and the `dsh-agent` factory. The readline UI is the unstructured analogue of the `acp` bridge and lives INSIDE the stdio app (the `stdio-chat` module of [`stdio-agent/`](stdio-agent/README.md)): it is scaffolding for that one front door, not an independently swappable integration, so it carries no package boundary of its own.

-`user-interaction` and `tool-ask-user` live here because asking a human is a UI-backed product affordance, not part of the providerless core spine. The seam remains provider-neutral (`ctx.userInteraction`), while the tool is the model-facing consumer and the app/bridge packages provide concrete providers.
+`user-approval`, `user-interaction`, and `tool-ask-user` live here because asking a human is a UI-backed product affordance, not part of the providerless core spine. `user-approval` owns the one-shot `ctx.approval` decision mechanism and its policy tier; answerers remain with their UI channel owners. `user-interaction` remains provider-neutral (`ctx.userInteraction`), while `tool-ask-user` is its model-facing consumer and the app/bridge packages provide concrete providers.

 `stdio-agent` and `acp-agent` are the two **app packages**: each composes the [`core/agent-core`](../core/agent-core/README.md) spine with its coupled front-door cluster (and owns the boot `bin`), so a leaf `cordis.yml` is the swappable backends plus one app entry plus any optional product tools. They live in `ui/` because each IS a user-facing front door; the stdout-purity coupling (logger vs. no logger) becomes a property of the artifact rather than a leaf convention.
--- a/packages/ui/acp/README.md
+++ b/packages/ui/acp/README.md
@@ -1,6 +1,6 @@
 # @deepseek-ai/dsh-acp

-The **Agent Client Protocol (ACP)** bridge: exposes DeepSeek Harness SDK agents as an ACP server over JSON-RPC stdio, so editors (Zed and other ACP clients) can drive them — streaming render, tool-call display, and resumable sessions. Zed is the current target client: baseline ACP behavior should remain reasonable for other clients, but bridge capabilities and compatibility decisions are evaluated against Zed first. **N concurrent sessions per connection** (see [ACP multi-session](../../../docs/rfc/proposed/feature/2026-06-14-acp-multi-session.md)): each maps to its own `ReactLoopAgent`, and every event is demuxed strictly by session id so two sessions streaming at once never interleave.
+The **Agent Client Protocol (ACP)** bridge: exposes DeepSeek Harness SDK agents as an ACP server over JSON-RPC stdio, so editors (Zed and other ACP clients) can drive them — streaming render, tool-call display, and resumable sessions. Zed is the current target client: baseline ACP behavior should remain reasonable for other clients, but bridge capabilities and compatibility decisions are evaluated against Zed first. **N concurrent sessions per connection** (see [ACP multi-session](../../../docs/rfc/implemented/feature/2026-06-14-acp-multi-session.md)): each maps to its own `ReactLoopAgent`, and every event is demuxed strictly by session id so two sessions streaming at once never interleave.

 It is a **client-driver / UI plugin**, the structured analogue of the readline `stdio-chat` plugin — NOT a loop change and NOT a [capability seam](../../../docs/rfc/implemented/architecture/2026-06-13-capability-seams.md). It consumes the existing `agent/*` event taxonomy, the `dsh-agent` create/resume factory, and `dsh-session-persistence`.

@@ -31,7 +31,7 @@ The `initialize` handshake reports a fixed server identity (`agentInfo: { name:
 | `session/cancel` | `agent.cancel()` | the queue-aware cancel: aborts a running step, clears queued + steering work, and drops a turn about to start, then settles the prompt `cancelled` — for ONLY that session (a cancel never touches another session's stream or prompt) |
 | `session/update` | `session/event` | `agent_message_chunk` (text-delta), `agent_thought_chunk` (reasoning-delta), `user_message_chunk` (load replay), `tool_call`/`tool_call_update` (the render intent — a `card`-tagged `ToolCallView`/`ToolResultView` — owned by the TOOL via `presentCall`/`presentResult`, which the bridge switches on to build the wire shape — see Tool-call presentation) |
 | `elicitation/create` | `ctx.userInteraction.ask()` | maps `ask_user_question` questions to ACP form elicitations; option descriptions are shown in enum titles, `multi_select` uses ACP array enums, optionless requests use a required `custom` field, and a non-empty custom answer overrides any selected choice |
-| `session/request_permission` | `approval/request` listener | the bridge is the [`ctx.approval`](../../approval/approval/README.md) answerer for the agents it owns: an `ask` (a hook or `tools/pre-execute` plugin) becomes an editor prompt attached to the streamed tool call, offering one-shot `allow_once`/`reject_once` options only; a foreign or call-less request delegates down the answerer chain (fail-closed `unavailable` default). See "Permission prompts" |
+| `session/request_permission` | `approval/request` listener | the bridge is the [`ctx.approval`](../user-approval/README.md) answerer for the agents it owns: an `ask` (a hook or `tools/pre-execute` plugin) becomes an editor prompt attached to the streamed tool call, offering one-shot `allow_once`/`reject_once` options only; a foreign or call-less request delegates down the answerer chain (fail-closed `unavailable` default). See "Permission prompts" |
 | `session/set_config_option` | `setSandboxMode` / `setApprovalPolicy` | per-session knob switching over [session config options](https://agentclientprotocol.com/protocol/session-config-options) — see "Session config options" |

 ## Multi-session
@@ -75,7 +75,7 @@ A `session/prompt` resolves (or rejects) exactly once, keyed off the canonical s

 ## Permission prompts

-The bridge registers an `approval/request` waterfall listener — the ACP answerer of the [approval seam](../../approval/approval/README.md). When `ctx.approval` routes an `ask` for an agent the bridge owns, the listener resolves the owning session through the reverse map and issues `session/request_permission` with the request's `callId` as the `toolCall` reference (the editor attaches the prompt to the already-streamed call) and the one-shot options `allow_once`/`reject_once` (`allow_always` is deferred to the approval RFC's grant-storage question). Outcomes map `allow-once → allowed-once`, any other selection → `rejected` (an unknown optionId from a non-conforming client never grants), client `cancelled → cancelled`. A request for an agent the bridge does NOT own — or one without a `callId` to attach to — delegates via `next()` so another answerer or the seam's fail-closed `unavailable` default takes it. A rejected `requestPermission` RPC (client gone mid-prompt) propagates to the ApprovalService, which contains it as `unavailable`. Whether a call asks at all is policy — a hook or `tools/pre-execute` plugin returning `ask` — never the bridge's own judgment; without such policy, tools keep the executor's full authority.
+The bridge registers an `approval/request` waterfall listener — the ACP answerer of the [user-approval seam](../user-approval/README.md). When `ctx.approval` routes an `ask` for an agent the bridge owns, the listener resolves the owning session through the reverse map and issues `session/request_permission` with the request's `callId` as the `toolCall` reference (the editor attaches the prompt to the already-streamed call) and the one-shot options `allow_once`/`reject_once` (`allow_always` is deferred to the approval RFC's grant-storage question). Outcomes map `allow-once → allowed-once`, any other selection → `rejected` (an unknown optionId from a non-conforming client never grants), client `cancelled → cancelled`. A request for an agent the bridge does NOT own — or one without a `callId` to attach to — delegates via `next()` so another answerer or the seam's fail-closed `unavailable` default takes it. A rejected `requestPermission` RPC (client gone mid-prompt) propagates to the ApprovalService, which contains it as `unavailable`. Whether a call asks at all is policy — a hook or `tools/pre-execute` plugin returning `ask` — never the bridge's own judgment; without such policy, tools keep the executor's full authority.

 ## Disposal & disconnect

@@ -87,7 +87,7 @@ Teardown reaches quiescence: for EVERY live session settle any pending prompt as

 ## stdout is the protocol

-The JSON-RPC frames go on stdout, so this plugin MUST run in an example that loads **no stdout logger** (the console logger writes to stdout and would corrupt the frames). The guarantee is config-only — see `examples/acp-agent` (no console logger) and [ACP support risks](../../../docs/rfc/proposed/feature/2026-06-14-acp-agent-client-protocol.md#risks). A stderr exporter is fine for logging.
+The JSON-RPC frames go on stdout, so this plugin MUST run in an example that loads **no stdout logger** (the console logger writes to stdout and would corrupt the frames). The guarantee is config-only — see `examples/acp-agent` (no console logger) and [ACP support risks](../../../docs/rfc/implemented/feature/2026-06-14-acp-agent-client-protocol.md#risks). A stderr exporter is fine for logging.

 ## Running

--- a/packages/ui/acp/acp-feature-support.md
+++ b/packages/ui/acp/acp-feature-support.md
@@ -10,7 +10,7 @@ Legend: ✅ supported · ⚠️ partial / fallback · ❌ not yet · — n/a. Th

 ## At a glance

-The bridge implements the **core prompt-turn loop** for N concurrent sessions: initialize, session new/load, prompt, cancel, streamed assistant/thought chunks, tool-call rendering (including Zed terminal cards), and resumable session replay. The largest **unbuilt** areas are the **permission gate** (`session/request_permission`), **MCP passthrough**, **session modes / config options / model selection**, **slash commands**, and **agent plans** — all of which both reference adapters ship — plus the client **filesystem** and **terminal** method families (which the adapters mostly do NOT drive either — see rows 43-49). See [Gap summary](#gap-summary).
+The bridge implements the **core prompt-turn loop** for N concurrent sessions: initialize, session new/load, prompt, cancel, streamed assistant/thought chunks, tool-call rendering (including Zed terminal cards), resumable session replay, one-shot permission prompts, and per-session sandbox/approval config options. The largest **unbuilt** areas are **MCP passthrough**, runtime model selection, **slash commands**, and **agent plans**, plus the client **filesystem** and **terminal** method families (which the adapters mostly do NOT drive either — see rows 43-49). See [Gap summary](#gap-summary).

 ## 1. Agent methods (client → agent)

@@ -39,7 +39,7 @@ These are capabilities the bridge would *drive* on the editor. The harness runs
 | Method | Stable | Bridge | Claude | Codex | Notes |
 |---|---|---|---|---|---|
 | `session/update` | S | ✅ | ✅ | ✅ | The bridge's primary output channel (see [§4](#4-sessionupdate-variants)). |
-| `session/request_permission` | S | ✅ | ✅ | ✅ | The bridge answers the [`ctx.approval`](../../approval/approval/README.md) seam for the agents it owns: an `ask` from a hook/plugin becomes an editor prompt attached to the streamed tool call, one-shot `allow_once`/`reject_once` options only. Whether a call asks is policy (nothing asks by default); `allow_always` is deferred (grant storage). |
+| `session/request_permission` | S | ✅ | ✅ | ✅ | The bridge answers the [`ctx.approval`](../user-approval/README.md) seam for the agents it owns: an `ask` from a hook/plugin becomes an editor prompt attached to the streamed tool call, one-shot `allow_once`/`reject_once` options only. Whether a call asks is policy (nothing asks by default); `allow_always` is deferred (grant storage). |
 | `fs/read_text_file` | S | ❌ | ✅ | ❌ | The harness reads files directly (it does not see the editor's unsaved buffer state). Claude delegates; Codex does not. |
 | `fs/write_text_file` | S | ❌ | ✅ | ❌ | Same — direct writes, no editor delegation. |
 | `terminal/create` | S | ❌ | ❌ | ❌ | Neither reference adapter drives the client terminal API either — both, like the bridge, render shell output as tool-call content + a `_meta` channel (see [§5 Terminal](#terminal-rendering)). |
@@ -130,7 +130,7 @@ The bridge rejects unsupported prompt blocks rather than silently dropping them
 | Feature | Stable | Bridge | Notes |
 |---|---|---|---|
 | `StopReason` mapping | S | ✅ | `turnEndToStopReason` is total over harness turn-end reasons → `end_turn`/`max_tokens`/`cancelled`. |
-| Multi-session (N per connection) | S | ✅ | Strict per-session demux; concurrent streams never interleave. See the [multi-session RFC](../../../docs/rfc/proposed/feature/2026-06-14-acp-multi-session.md). |
+| Multi-session (N per connection) | S | ✅ | Strict per-session demux; concurrent streams never interleave. See the [multi-session RFC](../../../docs/rfc/implemented/feature/2026-06-14-acp-multi-session.md). |
 | Disconnect / disposal teardown | S | ✅ | Quiesces every live session on client disconnect or Cordis disposal. |
 | `_meta` extensibility | S | ⚠️ | Consumed (Zed terminal cap) and emitted (terminal `_meta`); no other custom extensions. |
 | Background-task ownership isolation | — | ✅ | `bash_output`/`bash_kill` reject another session's task via an opaque owner token. |
@@ -141,7 +141,7 @@ The bridge rejects unsupported prompt blocks rather than silently dropping them
 Ranked by how commonly the reference adapters ship them and how much UX they unlock:

 1. **Session lifecycle** — `session/list` + `session/delete` (the persistence layer already lists), then `session/resume` / `session/close`.
-2. **Modes / config options / model selection** — the permission round-trip landed with the approval seam; the config surface (`sandbox_mode`/`approval_policy` options) is the sandbox RFC's config phase.
+2. **Model selection** — sandbox and approval config options are implemented; selecting the bridge's model at runtime remains open.
 3. **Agent plan** (`sessionUpdate: 'plan'`) — surface the loop's plan as structured entries.
 4. **Slash commands** (`available_commands_update`).
 5. **MCP passthrough** (`mcpServers` on `session/new` + `mcpCapabilities`).
--- a/packages/ui/acp/package.json
+++ b/packages/ui/acp/package.json
@@ -28,7 +28,7 @@
  },
  "peerDependencies": {
    "@deepseek-ai/dsh-agent": "^0.0.1",
-    "@deepseek-ai/dsh-approval": "^0.0.1",
+    "@deepseek-ai/dsh-user-approval": "^0.0.1",
    "@deepseek-ai/dsh-bash": "^0.0.1",
    "@deepseek-ai/dsh-llm": "^0.0.1",
    "@deepseek-ai/dsh-sandbox": "^0.0.1",
@@ -41,7 +41,7 @@
  "devDependencies": {
    "@deepseek-ai/dsh-agent": "workspace:^",
    "@deepseek-ai/dsh-agent-loop": "workspace:^",
-    "@deepseek-ai/dsh-approval": "workspace:^",
+    "@deepseek-ai/dsh-user-approval": "workspace:^",
    "@deepseek-ai/dsh-bash": "workspace:^",
    "@deepseek-ai/dsh-bash-local": "workspace:^",
    "@deepseek-ai/dsh-fs-local": "workspace:^",
--- a/packages/ui/acp/src/index.ts
+++ b/packages/ui/acp/src/index.ts
@@ -75,9 +75,9 @@ import type { Agent, AgentStatus } from '@deepseek-ai/dsh-agent'
 import { AgentId } from '@deepseek-ai/dsh-agent'
 import { SessionId } from '@deepseek-ai/dsh-session'
 import { SANDBOX_MODES, effectiveSandboxMode, setSandboxMode } from '@deepseek-ai/dsh-bash'
-import { APPROVAL_POLICIES, effectiveApprovalPolicy, setApprovalPolicy } from '@deepseek-ai/dsh-approval'
+import { APPROVAL_POLICIES, effectiveApprovalPolicy, setApprovalPolicy } from '@deepseek-ai/dsh-user-approval'
 import type { SandboxMode } from '@deepseek-ai/dsh-sandbox'
-import type { ApprovalPolicy } from '@deepseek-ai/dsh-approval'
+import type { ApprovalPolicy } from '@deepseek-ai/dsh-user-approval'
 import type { SessionEvent, TodoItem, TurnEndReason } from '@deepseek-ai/dsh-session'
 import type { ToolCallView, ToolRegistry, ToolResultView, TerminalResultView } from '@deepseek-ai/dsh-tools'
 // Side-effect type import: declaration-merges `ctx.sessionPersistence` onto
@@ -85,7 +85,7 @@ import type { ToolCallView, ToolRegistry, ToolResultView, TerminalResultView } f
 import type {} from '@deepseek-ai/dsh-session-persistence'
 // Side-effect type import: declaration-merges the `approval/request` waterfall
 // the bridge answers for its own agents (see the approval answerer below).
-import type {} from '@deepseek-ai/dsh-approval'
+import type {} from '@deepseek-ai/dsh-user-approval'
 import {
  UserInteractionError,
  type AskUserQuestionAnswer,
@@ -582,7 +582,7 @@ export function apply(ctx: Context, config: AcpConfig): void {

  // --- Approval answerer -----------------------------------------------------
  // The bridge is the approval channel for the agents it owns: an `ask` routed
-  // through `ctx.approval` (dsh-tools today, sandbox escalation later) becomes
+  // through `ctx.approval` (dsh-tools asks and sandbox escalation) becomes
  // an editor permission prompt attached to the already-streamed tool call. The
  // listener occupies the single decision slot ONLY for its own agents — a
  // foreign or call-less request delegates via next() so another answerer (or
--- a/packages/ui/acp/tests/approval.spec.ts
+++ b/packages/ui/acp/tests/approval.spec.ts
@@ -5,7 +5,7 @@ import { join } from 'node:path'
 import { PROTOCOL_VERSION } from '@agentclientprotocol/sdk'
 import { CallId } from '@deepseek-ai/dsh-llm'
 import { AgentId, type Agent } from '@deepseek-ai/dsh-agent'
-import ApprovalService, { type ApprovalRequest } from '@deepseek-ai/dsh-approval'
+import ApprovalService, { type ApprovalRequest } from '@deepseek-ai/dsh-user-approval'
 import { makeBridgeHarness, type BridgeHarness } from './harness.ts'

 /**
--- a/packages/ui/acp/tests/config-options.spec.ts
+++ b/packages/ui/acp/tests/config-options.spec.ts
@@ -13,8 +13,8 @@ import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { PROTOCOL_VERSION } from '@agentclientprotocol/sdk'
 import * as Invariants from '@deepseek-ai/dsh-invariants'
-import ApprovalService from '@deepseek-ai/dsh-approval'
-import type { ApprovalPolicy } from '@deepseek-ai/dsh-approval'
+import ApprovalService from '@deepseek-ai/dsh-user-approval'
+import type { ApprovalPolicy } from '@deepseek-ai/dsh-user-approval'
 import { LocalBashExecutor } from '@deepseek-ai/dsh-bash-local'
 import type { SandboxMode } from '@deepseek-ai/dsh-sandbox'
 import { makeBridgeHarness, textResponse, type BridgeHarness } from './harness.ts'
--- a/packages/ui/acp/tsconfig.json
+++ b/packages/ui/acp/tsconfig.json
@@ -36,7 +36,7 @@
      "path": "../../session-persistence/session-persistence"
    },
    {
-      "path": "../../approval/approval"
+      "path": "../user-approval"
    },
    {
      "path": "../../sandbox/sandbox"
--- a/packages/approval/approval/README.md
+++ b/packages/approval/approval/README.md
@@ -1,12 +1,12 @@
-# @deepseek-ai/dsh-approval
+# @deepseek-ai/dsh-user-approval

-Approval seam. Owns the `ctx.approval` service ([`ApprovalService`](src/index.ts)) and the one-shot permission vocabulary the harness shares: `ApprovalRequest` (agent + tool identity + reason + abort signal), the closed `ApprovalOutcome` union (`allowed-once` / `rejected` / `cancelled` / `unavailable`), the `ApprovalRequestId` brand pairing the two log-only audit events (`approval/asked` / `approval/decided`), and the `approval/request` waterfall the answerers listen on. Depends only on cordis and the core vocabulary packages (agent, session, llm brand), never on any UI.
+User-approval seam. Owns the `ctx.approval` service ([`ApprovalService`](src/index.ts)) and the one-shot permission vocabulary the harness shares: `ApprovalRequest` (agent + tool identity + reason + abort signal), the closed `ApprovalOutcome` union (`allowed-once` / `rejected` / `cancelled` / `unavailable`), the `ApprovalRequestId` brand pairing the two log-only audit events (`approval/asked` / `approval/decided`), and the `approval/request` waterfall the answerers listen on. It lives in the UI group because its purpose is human permission, while remaining channel-neutral: it depends only on Cordis and core vocabulary packages, never on a concrete UI.

 The contract in one line: `ctx.approval.request(req)` puts exactly one question — "may this specific action proceed?" — to whatever answerers the deployment composed, and always resolves to an outcome, never rejects: an aborted signal yields `cancelled`, a throwing or missing answerer yields `unavailable`, and `allowed-once` is a grant for the single asked-about action, never a class of future ones. The one precondition: ask from inside an open turn — the audit pair is turn-enclosed by contract (the turn is the durable log's commit/replay boundary; a bare event between turns is crash-tail garbage on reload), so an idle ask throws before appending anything.

 The service is the mechanism, answerers are the policy. Answerers are `approval/request` waterfall listeners occupying a single decision slot: answer for an agent you own by returning an outcome without calling `next()`, or delegate an agent you don't recognize by calling `next()` — the chain's built-in default is `unavailable`, so a deployment with no answerer (headless, CI) fails closed with zero configuration. Registration order across sibling plugins is not load-order deterministic; compose one terminal answerer per deployment and use `prepend` listeners only for decide-or-delegate gates.

-The seam also owns the per-session POLICY tier ([the sandbox RFC § Per-session mode switching](../../../docs/rfc/implemented/feature/2026-07-06-sandbox.md)): `ApprovalPolicy` is `'ask'` (delegate to the answerers — the prior behavior exactly) or `'never'` (deterministically reject without prompting anyone; the strict CI/unattended stance), with `effective = fold(the session's 'approval/policy' events, last one wins) ?? Config.policy` — the session log is the store, written only through `setApprovalPolicy(session, policy)`. The service decides `'never'` inside `request()` itself, before dispatching the waterfall (`'never'` → `'rejected'` with the audit pair still landing; no listener registration, including a later `prepend`, can precede it), states `'never'` — and only `'never'` — in a per-agent prompt section (a "you will be prompted" promise under `'ask'` would overclaim what a headless composition can do; the section scope activates only when `systemPrompt` is composed), and narrates a policy switch to the model in at most one coalesced `agent/pre-step` notice, attributed positionally (an override event after the log's last `request/header*` reads `changed by the user`; a config drift reads `changed by the operator/config`).
+The seam also owns the per-session POLICY tier ([the sandbox RFC § Per-session mode switching](../../../docs/rfc/implemented/feature/2026-07-06-sandbox.md)): `ApprovalPolicy` is `'ask'` (delegate to the answerers) or `'never'` (deterministically reject without prompting anyone; the strict CI/unattended stance), with `effective = fold(the session's 'approval/policy' events, last one wins) ?? Config.policy` — the session log is the store, written only through `setApprovalPolicy(session, policy)`. The service decides `'never'` inside `request()` itself, before dispatching the waterfall (`'never'` → `'rejected'` with the audit pair still landing; no listener registration, including a later `prepend`, can precede it), states `'never'` — and only `'never'` in prose — in a per-agent prompt section, records either value with a source-owned header marker, and narrates a policy switch to the model in at most one coalesced `agent/pre-step` notice. The restart fallback reads the marker rather than deployment-controlled persona prose; attribution is positional (an override event after the last `request/header*` reads `changed by the user`, otherwise `changed by the operator/config`).

 One seam serves both ask paths of [the sandbox RFC](../../../docs/rfc/implemented/feature/2026-07-06-sandbox.md): the `tools/pre-execute` `ask` decision (routed by [`@deepseek-ai/dsh-tools`](../../core/tools/) when this service is mounted; degrading to deny when it is not), and the sandbox post-denial escalated retry (the bash tool's `sandbox_permissions` gate in [`@deepseek-ai/dsh-tool-bash`](../../bash/tool-bash/) — [the sandbox RFC § Escalation](../../../docs/rfc/implemented/feature/2026-07-06-sandbox.md)). The full design: [the approval-seam RFC](../../../docs/rfc/implemented/feature/2026-07-06-approval-seam.md).

--- a/packages/approval/approval/package.json
+++ b/packages/approval/approval/package.json
@@ -1,6 +1,6 @@
 {
-  "name": "@deepseek-ai/dsh-approval",
-  "description": "Approval seam (ctx.approval) for the DeepSeek Harness: one-shot permission decisions dispatched to composed answerers over the approval/request waterfall, fail-closed by default",
+  "name": "@deepseek-ai/dsh-user-approval",
+  "description": "User-approval seam (ctx.approval) for the DeepSeek Harness: one-shot permission decisions dispatched to composed answerers over the approval/request waterfall, fail-closed by default",
  "version": "0.0.1",
  "private": true,
  "type": "module",
--- a/packages/approval/approval/src/index.ts
+++ b/packages/approval/approval/src/index.ts
@@ -8,8 +8,8 @@
 *
 * The service is the MECHANISM (dispatch, cancellation, audit); answerers are
 * the POLICY. It serves both ask paths the sandbox RFC names — the
- * `tools/pre-execute` `ask` decision today, and the sandbox post-denial
- * escalation when that phase lands — so every asker shares one outcome
+ * `tools/pre-execute` `ask` decision and the sandbox post-denial escalation —
+ * so every asker shares one outcome
 * vocabulary and one audit trail. Grants are one-shot by design: an
 * `'allowed-once'` outcome authorizes the single action it was asked about,
 * never a class of future actions.
@@ -30,7 +30,7 @@
 * asking); an `agent/pre-step` narrator explains a switch to the model in at
 * most one coalesced notice per step.
 *
- * @module @deepseek-ai/dsh-approval
+ * @module @deepseek-ai/dsh-user-approval
 */

 import { randomUUID } from 'node:crypto'
@@ -153,18 +153,32 @@ export const APPROVAL_POLICIES: readonly ApprovalPolicy[] = ['ask', 'never']

 /**
 * The prompt sentence stating a `'never'` policy — visibility for the one
- * deterministic policy (see {@link ApprovalPolicy}), and the narrator's parse
- * candidate for "what was the model last told": a folded `request/header*`
- * system text containing it was assembled under `'never'`; one without it
- * (but with any header at all) was assembled under `'ask'`, which states
- * nothing. The exact-wording compatibility surface (writer and parser) lives
- * entirely in this module; the bash tool description's escalation teaching
- * additionally defers to the sentence's opening claim by meaning (see
- * `dsh-tool-bash`), so keep the sentence opening with the approvals-disabled
- * statement.
+ * deterministic policy (see {@link ApprovalPolicy}). Narrator persistence
+ * does NOT parse this prose: deployments can quote it in a persona or another
+ * section, so the section also emits a source-owned marker.
 */
 const NEVER_SENTENCE = 'Approval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`).'

+/** Source-owned prompt markers used to reconstruct the policy in a logged header. */
+const POLICY_MARKERS = {
+  ask: '<!-- dsh-user-approval-policy:ask -->',
+  never: '<!-- dsh-user-approval-policy:never -->',
+} as const satisfies Record<ApprovalPolicy, string>
+
+/**
+ * Read the policy fact emitted by this service from a logged system prompt.
+ * The section is ordered after deployment persona text, and the last marker
+ * wins so a persona quoting an earlier marker cannot shadow the service's own
+ * contribution. Ordinary policy prose is deliberately ignored.
+ */
+function toldApprovalPolicy(system: string | undefined): ApprovalPolicy | undefined {
+  if (system === undefined) return undefined
+  const ask = system.lastIndexOf(POLICY_MARKERS.ask)
+  const never = system.lastIndexOf(POLICY_MARKERS.never)
+  if (ask < 0 && never < 0) return undefined
+  return never > ask ? 'never' : 'ask'
+}
+
 /**
 * The session's approval-policy override: the last `approval/policy` event in
 * the log, or undefined when the session never switched (callers apply the
@@ -258,13 +272,12 @@ export interface Config {
 * returned to the caller, never stored here.
 *
 * Owns the policy tier too (`effective = fold(the session's 'approval/policy'
- * events) ?? config.policy`): a PREPENDED decide-or-delegate gate resolves
- * `'never'` sessions to `'rejected'` before any interactive answerer is
- * prompted, a per-agent prompt section states a `'never'` policy (and only
- * that one — an `'ask'` promise could overclaim an answerer that headless
- * compositions do not have), and an `agent/pre-step` narrator injects at most
- * one coalesced notice when a session's effective policy moved past what the
- * model was last told.
+ * events) ?? config.policy`): `request()` resolves `'never'` to `'rejected'`
+ * before dispatching any interactive answerer, a per-agent prompt section
+ * states a `'never'` policy (and only that one in prose — an `'ask'` promise
+ * could overclaim an answerer that headless compositions do not have), and an
+ * `agent/pre-step` narrator injects at most one coalesced notice when a
+ * session's effective policy moved past what the model was last told.
 */
 export class ApprovalService extends Service {
  static Config: z<Config> = z.object({
@@ -278,9 +291,10 @@ export class ApprovalService extends Service {

    // Visibility layer 1, scoped on the prompt registry so headless
    // compositions mount the seam without it: state the one deterministic
-    // policy per session. 'ask' renders nothing — stating "you will be
-    // asked" would overclaim in a composition with no answerer, and absence
-    // under any logged header is exactly how the narrator reads 'ask' back.
+    // policy per session. 'ask' renders only a source-owned state marker —
+    // stating "you will be asked" would overclaim in a composition with no
+    // answerer. The marker, not deployment-controlled prose, is what the
+    // restart narrator reads back from the logged request header.
    ctx.inject(['systemPrompt'], (scope: Context) => {
      scope.systemPrompt.section({
        name: 'approval:policy',
@@ -289,7 +303,8 @@ export class ApprovalService extends Service {
          const agent = context.agent
          // A bare assemble() (tests, diagnostics) has no session to state.
          if (agent === undefined) return ''
-          return effective(agent) === 'never' ? NEVER_SENTENCE : ''
+          const policy = effective(agent)
+          return policy === 'never' ? `${NEVER_SENTENCE}\n${POLICY_MARKERS.never}` : POLICY_MARKERS.ask
        },
      })
    })
@@ -322,8 +337,7 @@ export class ApprovalService extends Service {
      // for POSITIONAL attribution; the default lives once, in the method.
      const current = this.effectivePolicy(agent)
      const header = session.requestHeader()
-      const told = narrated.get(session)
-        ?? (header === undefined ? undefined : header.system?.includes(NEVER_SENTENCE) === true ? 'never' : 'ask')
+      const told = narrated.get(session) ?? toldApprovalPolicy(header?.system)
      narrated.set(session, current)
      // Cold start (nothing ever told) narrates nothing — the section about
      // to go out states the truth, and there is no delta to explain.
@@ -331,7 +345,7 @@ export class ApprovalService extends Service {
      const cause = overrideIndex > headerIndex ? 'changed by the user' : 'changed by the operator/config'
      agent.inject(
        [{ type: 'text', text: `The approval policy changed from "${told}" to "${current}" (${cause}).` }],
-        { source: { kind: 'plugin', plugin: 'approval' } },
+        { source: { kind: 'plugin', plugin: 'user-approval' } },
      )
    })
  }
--- a/packages/approval/approval/tests/approval.spec.ts
+++ b/packages/approval/approval/tests/approval.spec.ts
@@ -5,7 +5,7 @@ import { CallId } from '@deepseek-ai/dsh-llm'
 import { Session, SessionId } from '@deepseek-ai/dsh-session'
 import type { SessionEvent } from '@deepseek-ai/dsh-session'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
-import ApprovalService, { ApprovalOutcome, ApprovalRequest, effectiveApprovalPolicy, setApprovalPolicy } from '@deepseek-ai/dsh-approval'
+import ApprovalService, { ApprovalOutcome, ApprovalRequest, effectiveApprovalPolicy, setApprovalPolicy } from '@deepseek-ai/dsh-user-approval'

 /**
 * A minimal Agent stand-in — the service only reaches `agent.session.append`
@@ -205,6 +205,8 @@ describe('ApprovalService.request', () => {

 describe('approval policy (the approval/policy fold)', () => {
  const NEVER_SENTENCE = 'Approval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`).'
+  const ASK_MARKER = '<!-- dsh-user-approval-policy:ask -->'
+  const NEVER_MARKER = '<!-- dsh-user-approval-policy:never -->'

  /**
   * An agent stand-in over a REAL Session — gate, section, and narrator fold
@@ -304,7 +306,7 @@ describe('approval policy (the approval/policy fold)', () => {
    await expect(ctx.approval.request({ agent, toolName: 'bash' })).resolves.toBe('rejected')
  })

-  it('states never (and only never) in the prompt, per session', async () => {
+  it('states never (and only never) in prose while recording either policy with a source-owned marker', async () => {
    const ctx = new Context()
    await ctx.plugin(SystemPrompt)
    await ctx.plugin(ApprovalService)
@@ -313,8 +315,8 @@ describe('approval policy (the approval/policy fold)', () => {
    setApprovalPolicy(session, 'never')
    const sectionFor = async (context: object) =>
      (await ctx.systemPrompt.assemble(context)).sections.find(s => s.name === 'approval:policy')?.text
-    expect(await sectionFor({ agent: askAgent })).toBe('')
-    expect(await sectionFor({ agent: neverAgent })).toBe(NEVER_SENTENCE)
+    expect(await sectionFor({ agent: askAgent })).toBe(ASK_MARKER)
+    expect(await sectionFor({ agent: neverAgent })).toBe(`${NEVER_SENTENCE}\n${NEVER_MARKER}`)
    // A bare assemble (no agent) has no session to state.
    expect(await sectionFor({})).toBe('')
  })
@@ -344,16 +346,16 @@ describe('approval policy (the approval/policy fold)', () => {
    const ctx = new Context()
    await ctx.plugin(ApprovalService)
    const { agent, session, injected } = sessionAgent('sess-narr-2')
-    appendHeader(session, `persona\n\n${NEVER_SENTENCE}`)
+    appendHeader(session, `persona\n\n${NEVER_SENTENCE}\n${NEVER_MARKER}`)
    await preStep(ctx, agent)
    expect(injected).toEqual(['The approval policy changed from "never" to "ask" (changed by the operator/config).'])
  })

-  it('narrates a config default drift over a sentence-less header (told = ask by absence)', async () => {
+  it('narrates a config default drift from the logged ask marker', async () => {
    const ctx = new Context()
    await ctx.plugin(ApprovalService, { policy: 'never' })
    const { agent, session, injected } = sessionAgent('sess-narr-3')
-    appendHeader(session, 'persona only')
+    appendHeader(session, `persona only\n${ASK_MARKER}`)
    await preStep(ctx, agent)
    expect(injected).toEqual(['The approval policy changed from "ask" to "never" (changed by the operator/config).'])
  })
@@ -362,10 +364,61 @@ describe('approval policy (the approval/policy fold)', () => {
    const ctx = new Context()
    await ctx.plugin(ApprovalService, { policy: 'never' })
    const { agent, session, injected } = sessionAgent('sess-narr-4')
-    appendHeader(session, 'persona only')
+    appendHeader(session, `persona only\n${ASK_MARKER}`)
    setApprovalPolicy(session, 'ask')
-    appendHeader(session, 'persona only')
+    appendHeader(session, `persona only\n${ASK_MARKER}`)
    await preStep(ctx, agent)
    expect(injected).toEqual([])
  })
+
+  it('does not infer never from deployment prose that quotes the never sentence', async () => {
+    const ctx = new Context()
+    await ctx.plugin(ApprovalService)
+    const { agent, session, injected } = sessionAgent('sess-narr-spoof-prose')
+    appendHeader(session, `persona quotes this warning: ${NEVER_SENTENCE}\n${ASK_MARKER}`)
+    await preStep(ctx, agent)
+    expect(injected).toEqual([])
+  })
+
+  it('treats a legacy header with no source-owned marker as untold', async () => {
+    const ctx = new Context()
+    await ctx.plugin(ApprovalService, { policy: 'never' })
+    const { agent, session, injected } = sessionAgent('sess-narr-unmarked-header')
+    appendHeader(session, 'legacy persona-only header')
+    await preStep(ctx, agent)
+    expect(injected).toEqual([])
+  })
+
+  it('uses the service marker after an earlier persona marker', async () => {
+    const ctx = new Context()
+    await ctx.plugin(ApprovalService)
+    const { agent, session, injected } = sessionAgent('sess-narr-spoof-marker')
+    appendHeader(session, `persona quotes ${NEVER_MARKER}\n${ASK_MARKER}`)
+    await preStep(ctx, agent)
+    expect(injected).toEqual([])
+  })
+
+  it('disposes the service prompt section and pre-step narrator together (HMR safety)', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SystemPrompt)
+    const fiber = await ctx.plugin(ApprovalService)
+    const live = sessionAgent('sess-hmr-service-live')
+    const afterDispose = sessionAgent('sess-hmr-service-disposed')
+    const sectionFor = async () =>
+      (await ctx.systemPrompt.assemble({ agent: live.agent })).sections.find(section => section.name === 'approval:policy')
+    expect(await sectionFor()).toBeDefined()
+
+    appendHeader(live.session, `persona\n${ASK_MARKER}`)
+    setApprovalPolicy(live.session, 'never')
+    await preStep(ctx, live.agent)
+    expect(live.injected).toEqual(['The approval policy changed from "ask" to "never" (changed by the user).'])
+
+    appendHeader(afterDispose.session, `persona\n${ASK_MARKER}`)
+    setApprovalPolicy(afterDispose.session, 'never')
+    await fiber.dispose()
+
+    expect(await sectionFor()).toBeUndefined()
+    await preStep(ctx, afterDispose.agent)
+    expect(afterDispose.injected).toEqual([])
+  })
 })
--- a/packages/approval/approval/tsconfig.json
+++ b/packages/approval/approval/tsconfig.json