feat(mode): the session-mode core — logged per-agent policy state (@deepseek-ai/dsh-mode)

Plan mode's stage 1 (RFC 2026-07-07-plan-mode): a new packages/mode/ group with one product package owning the mode/set SessionEventMap vocabulary (log-only, non-surface, whole-value replace), the pure foldMode, and the ctx.modes service (list/get/set). User flips are pending intents flushed at turn/start / step/end — turn enclosure makes an idle append illegal — with one coalesced context/message notice when the flushed mode differs from what the last logged request header told the model; a folded mode the config no longer defines reads as default plus one boundary notice. Enforcement is two covering layers: a system-prompt/assemble wrapper filters the RETURNED assembly's tools to the mode's allowlist (and shows exit_plan_mode IFF the folded mode is plan) beside the mode:policy section at order 50, and a tools/pre-execute gate denies deny-by-default against the same allowlist, judging by the logged mode only. The default mode is the absence of policy — assemblies stay byte-identical to a no-dsh-mode deployment. AgentOptions.mode (declaration-merged) seeds a child's initial mode through the same flush on agent/created; the stdio app gains /mode (print/switch, never sent to the model) over an opportunistic ctx.get('modes'). Config is an explicit resolve step: the built-in plan definition (read-only allowlist; bash/subagent excluded until the sandbox family lands) merges unless overridden, 'default' as a key throws at load, unknown names throw at set() time.
2026-07-10 01:38:39 +08:00
parent ab8dc1ec72
commit 63ced3e0e2
26 changed files with 1179 additions and 5 deletions
--- a/docs/capability-seams.md
+++ b/docs/capability-seams.md
@@ -38,6 +38,8 @@ flowchart LR
  pkg_user_interaction["user-interaction"]
  svc_userInteraction["ctx.userInteraction<br/>Human question/answer seam"]
  pkg_stdio_agent["stdio-agent"]
+  pkg_mode["mode"]
+  svc_modes["ctx.modes<br/>Session-mode policy state"]
  svc_agents["ctx.agents<br/>Agent registry"]
  svc_agentLoop["ctx.agentLoop<br/>Concrete loop driver"]
  pkg_agent_core["agent-core"]
@@ -82,6 +84,7 @@ flowchart LR
  pkg_llm_deepseek --> svc_llm
  pkg_llm_pi_ai --> svc_llm
  pkg_llm_replay --> svc_llm
+  pkg_mode --> svc_modes
  pkg_session --> svc_sessions
  pkg_session_persistence --> svc_sessionPersistence
  pkg_session_persistence_jsonl --> svc_sessionPersistence
@@ -114,6 +117,7 @@ flowchart LR
  svc_fs --> pkg_tool_fs
  svc_llm --> pkg_agent_loop
  svc_llm --> pkg_compact_basic
+  svc_modes --> pkg_stdio_agent
  svc_sessionPersistence --> pkg_acp
  svc_sessionPersistence --> pkg_agent_loop
  svc_sessions --> pkg_agent
@@ -150,6 +154,7 @@ flowchart LR
 | `ctx.systemPrompt` | `core` | [`system-prompt`](../packages/core/system-prompt) | - | [`agent-loop`](../packages/core/agent-loop), [`tools`](../packages/core/tools), [`tool-fs`](../packages/fs/tool-fs), [`tool-web`](../packages/web/tool-web) | - | Collects prompt sections and model-facing tool schemas for each step. |
 | `ctx.tools` | `core` | [`tools`](../packages/core/tools) | - | [`agent-loop`](../packages/core/agent-loop), [`tool-ask-user`](../packages/ui/tool-ask-user), [`tool-bash`](../packages/bash/tool-bash), [`tool-cordis`](../packages/cordis/tool-cordis), [`tool-fs`](../packages/fs/tool-fs), [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-todo`](../packages/todo/tool-todo), [`tool-web`](../packages/web/tool-web), [`acp`](../packages/ui/acp) | - | Registers tool definitions, exposes schemas to the prompt, and routes calls through tools/pre-execute and tools/post-execute. |
 | `ctx.userInteraction` | `seam` | [`user-interaction`](../packages/ui/user-interaction) | [`stdio-agent`](../packages/ui/stdio-agent), [`acp`](../packages/ui/acp) | [`tool-ask-user`](../packages/ui/tool-ask-user), [`stdio-agent`](../packages/ui/stdio-agent), [`acp`](../packages/ui/acp) | - | UI front doors provide the active human-answer provider; tool-ask-user pauses a tool call on the provider-neutral ask() promise. |
+| `ctx.modes` | `core` | [`mode`](../packages/mode/mode) | - | [`stdio-agent`](../packages/ui/stdio-agent) | - | Folds the logged per-agent mode (mode/set), flushes user flips at turn boundaries, and enforces the mode through the assemble filter and the tools/pre-execute gate. |
 | `ctx.agents` | `core` | [`agent`](../packages/core/agent) | - | [`agent-loop`](../packages/core/agent-loop), [`acp`](../packages/ui/acp), [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`stdio-agent`](../packages/ui/stdio-agent), [`invariants`](../packages/support/invariants) | - | Owns live Agent handles and the create/resume factory seam. |
 | `ctx.agentLoop` | `bundle` | [`agent-loop`](../packages/core/agent-loop) | - | [`agent-core`](../packages/core/agent-core) | - | The one concrete loop plugin; extension packages depend on dsh-agent events and services, not on this package. |
 | `ctx.bash` | `seam` | [`bash`](../packages/bash/bash) | [`bash-local`](../packages/bash/bash-local) | [`tool-bash`](../packages/bash/tool-bash), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) | - | The model-facing bash tools and hook bridges consume this seam; sandboxed or remote executors can replace bash-local. |
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -398,6 +398,35 @@ export interface Config {

 Source: [`packages/support/llm-replay/src/index.ts:429`](../packages/support/llm-replay/src/index.ts)

+## `@deepseek-ai/dsh-mode`
+
+Requires: `tools` · `systemPrompt`
+
+```ts config-catalog
+/**
+ * Plugin config: mode definitions by name. The built-in {@link PLAN_MODE}
+ * definition is merged in unless overridden; {@link DEFAULT_MODE} is rejected
+ * as a key ({@link resolveConfig} throws at load).
+ */
+export interface ModeConfig {
+  /** Mode definitions by name, overriding or extending the built-in `plan`. */
+  modes?: Record<string, ModeDefinition>
+}
+
+/**
+ * One mode's deployment-configured policy: the guidance section the model sees
+ * and the allowlist of tool names that stay visible and executable.
+ */
+export interface ModeDefinition {
+  /** Guidance text rendered as the `mode:policy` prompt section while the mode is in force. */
+  section: string
+  /** Allowlist of tool NAMES; names may reference not-yet-registered tools (registration is dynamic). */
+  tools: string[]
+}
+```
+
+Source: [`packages/mode/mode/src/index.ts:94`](../packages/mode/mode/src/index.ts)
+
 ## `@deepseek-ai/dsh-repeat-tool-guard`

 ```ts config-catalog
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -147,6 +147,20 @@ Types: [GenerateOptions](../core-data-structures/core.md) · [StreamChunk](../co

 Source: [`packages/llm/llm/src/index.ts:88`](../../packages/llm/llm/src/index.ts)

+## `ctx.modes` — `ModesService`
+
+`ctx.modes`: the session-mode service. Owns the `mode/set` vocabulary, the pending-intent flush, the boundary narration, and both policy layers (the assemble filter + `mode:policy` section, and the `tools/pre-execute` gate). UIs read mode flips off `session/event`; there is no live mirror.
+
+```ts cordis-catalog
+list(): string[]
+get(agent: Agent): { current: string, pending?: string }
+set(agent: Agent, mode: string): void
+```
+
+Types: [Agent](../core-data-structures/core.md)
+
+Source: [`packages/mode/mode/src/index.ts:179`](../../packages/mode/mode/src/index.ts)
+
 ## `ctx.sessionPersistence` — `SessionPersistence` (abstract seam)

 Abstract durable session-persistence service. Subclass, implement the abstract methods, and load the subclass as a plugin — it registers as `ctx.sessionPersistence` (one implementation per context; loading a second throws, cordis' standard duplicate-service behavior).
--- a/docs/event-producer-consumer.md
+++ b/docs/event-producer-consumer.md
@@ -7,7 +7,7 @@ This matrix shows which packages dispatch each harness-owned event and which pac

 | Event | Mode | Declared in | Dispatchers | Listeners |
 | --- | --- | --- | --- | --- |
-| `agent/created` | `emit` | [`packages/core/agent/src/types.ts:265`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`emit`) | [`stdio-agent`](../packages/ui/stdio-agent) |
+| `agent/created` | `emit` | [`packages/core/agent/src/types.ts:265`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`emit`) | [`mode`](../packages/mode/mode), [`stdio-agent`](../packages/ui/stdio-agent) |
 | `agent/disposed` | `emit` | [`packages/core/agent/src/types.ts:272`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`emit`) | [`stdio-agent`](../packages/ui/stdio-agent) |
 | `agent/error` | `emit` | [`packages/core/agent/src/types.ts:476`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | - |
 | `agent/pre-step` | `serial` | [`packages/core/agent/src/types.ts:357`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`compact-basic`](../packages/compact/compact-basic) |
@@ -24,17 +24,17 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `fs/write-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:109`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) |
 | `llm/stream` | `waterfall` | [`packages/llm/llm/src/index.ts:39`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`waterfall`) | [`invariants`](../packages/support/invariants), [`llm-replay`](../packages/support/llm-replay) |
 | `session/created` | `emit` | [`packages/core/session/src/index.ts:39`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`emit`) | [`invariants`](../packages/support/invariants), [`session-persistence`](../packages/session-persistence/session-persistence) |
-| `session/event` | `emit` | [`packages/core/session/src/index.ts:47`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`emit`) | [`acp`](../packages/ui/acp), [`invariants`](../packages/support/invariants), [`session-persistence`](../packages/session-persistence/session-persistence), [`stdio-agent`](../packages/ui/stdio-agent) |
+| `session/event` | `emit` | [`packages/core/session/src/index.ts:47`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`emit`) | [`acp`](../packages/ui/acp), [`invariants`](../packages/support/invariants), [`mode`](../packages/mode/mode), [`session-persistence`](../packages/session-persistence/session-persistence), [`stdio-agent`](../packages/ui/stdio-agent) |
 | `session/flush` | `parallel` | [`packages/core/session/src/index.ts:57`](../packages/core/session/src/index.ts) | [`agent-loop`](../packages/core/agent-loop) (`parallel`) | [`session-persistence`](../packages/session-persistence/session-persistence) |
 | `subagent/end` | `emit` | [`packages/subagent/subagent/src/index.ts:98`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude`](../packages/hooks/hooks-claude) |
 | `subagent/provider-added` | `emit` | [`packages/subagent/subagent/src/index.ts:72`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`emit`) | [`tool-subagent`](../packages/subagent/tool-subagent) |
 | `subagent/provider-removed` | `emit` | [`packages/subagent/subagent/src/index.ts:83`](../packages/subagent/subagent/src/index.ts) | - | [`tool-subagent`](../packages/subagent/tool-subagent) |
 | `subagent/start` | `emit` | [`packages/subagent/subagent/src/index.ts:91`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude`](../packages/hooks/hooks-claude) |
-| `system-prompt/assemble` | `waterfall` | [`packages/core/system-prompt/src/index.ts:38`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`waterfall`) | - |
+| `system-prompt/assemble` | `waterfall` | [`packages/core/system-prompt/src/index.ts:38`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`waterfall`) | [`mode`](../packages/mode/mode) |
 | `system-prompt/change` | `emit` | [`packages/core/system-prompt/src/index.ts:44`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`emit`) | - |
 | `tools/change` | `emit` | [`packages/core/tools/src/index.ts:132`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`emit`) | - |
 | `tools/execute` | `waterfall` | [`packages/core/tools/src/index.ts:111`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`timeout-policy`](../packages/timeout/timeout-policy) |
 | `tools/post-execute` | `waterfall` | [`packages/core/tools/src/index.ts:127`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`repeat-tool-guard`](../packages/guard/repeat-tool-guard) |
-| `tools/pre-execute` | `waterfall` | [`packages/core/tools/src/index.ts:91`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
+| `tools/pre-execute` | `waterfall` | [`packages/core/tools/src/index.ts:91`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`mode`](../packages/mode/mode) |

 Maintenance mode: hybrid generated: Cordis event declarations and most producer/listener edges are AST-scanned; dynamic dispatch sites are classified in `scripts/gen-doc-graphs.ts`.
--- a/docs/module-graph.md
+++ b/docs/module-graph.md
@@ -61,6 +61,9 @@ flowchart TD
  subgraph group_todo["packages/todo"]
    pkg_tool_todo["tool-todo"]
  end
+  subgraph group_mode["packages/mode"]
+    pkg_mode["mode"]
+  end
  subgraph group_cordis["packages/cordis"]
    pkg_tool_cordis["tool-cordis"]
  end
@@ -173,6 +176,10 @@ flowchart TD
  pkg_tool_todo --> pkg_agent
  pkg_tool_todo --> pkg_session
  pkg_tool_todo --> pkg_tools
+  pkg_mode --> pkg_agent
+  pkg_mode --> pkg_session
+  pkg_mode --> pkg_system_prompt
+  pkg_mode --> pkg_tools
  pkg_tool_cordis --> pkg_tools
  pkg_hooks_codex --> pkg_agent
  pkg_hooks_codex --> pkg_hook_protocol
@@ -236,6 +243,7 @@ flowchart TD
  pkg_stdio_agent --> pkg_agent_core
  pkg_stdio_agent --> pkg_app_boot
  pkg_stdio_agent --> pkg_llm
+  pkg_stdio_agent --> pkg_mode
  pkg_stdio_agent --> pkg_session
  pkg_stdio_agent --> pkg_session_persistence_jsonl
  pkg_stdio_agent --> pkg_tool_ask_user
@@ -284,6 +292,7 @@ flowchart TD
 | [`tool-web`](../packages/web/tool-web) | `web` | [`llm`](../packages/llm/llm), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`web`](../packages/web/web) |
 | [`timeout-policy`](../packages/timeout/timeout-policy) | `timeout` | [`llm`](../packages/llm/llm), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) |
 | [`tool-todo`](../packages/todo/tool-todo) | `todo` | [`agent`](../packages/core/agent), [`session`](../packages/core/session), [`tools`](../packages/core/tools) |
+| [`mode`](../packages/mode/mode) | `mode` | [`agent`](../packages/core/agent), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
 | [`tool-cordis`](../packages/cordis/tool-cordis) | `cordis` | [`tools`](../packages/core/tools) |
 | [`hooks-codex`](../packages/hooks/hooks-codex) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`tools`](../packages/core/tools) |
 | [`acp`](../packages/ui/acp) | `ui` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`tools`](../packages/core/tools), [`user-interaction`](../packages/ui/user-interaction) |
@@ -298,4 +307,4 @@ flowchart TD
 | [`subagent-fork`](../packages/subagent/subagent-fork) | `subagent` | [`agent`](../packages/core/agent), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) |
 | [`subagent-spawn`](../packages/subagent/subagent-spawn) | `subagent` | [`subagent`](../packages/subagent/subagent), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) |
 | [`acp-agent`](../packages/ui/acp-agent) | `ui` | [`acp`](../packages/ui/acp), [`agent-core`](../packages/core/agent-core), [`app-boot`](../packages/ui/app-boot), [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl), [`tools`](../packages/core/tools), [`user-interaction`](../packages/ui/user-interaction) |
-| [`stdio-agent`](../packages/ui/stdio-agent) | `ui` | [`agent`](../packages/core/agent), [`agent-core`](../packages/core/agent-core), [`app-boot`](../packages/ui/app-boot), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl), [`tool-ask-user`](../packages/ui/tool-ask-user), [`tools`](../packages/core/tools), [`user-interaction`](../packages/ui/user-interaction) |
+| [`stdio-agent`](../packages/ui/stdio-agent) | `ui` | [`agent`](../packages/core/agent), [`agent-core`](../packages/core/agent-core), [`app-boot`](../packages/ui/app-boot), [`llm`](../packages/llm/llm), [`mode`](../packages/mode/mode), [`session`](../packages/core/session), [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl), [`tool-ask-user`](../packages/ui/tool-ask-user), [`tools`](../packages/core/tools), [`user-interaction`](../packages/ui/user-interaction) |
--- a/docs/persistence-catalog.md
+++ b/docs/persistence-catalog.md
@@ -107,6 +107,18 @@ A hook command's outcome — log-only, paired with a prior `hook/invoked` (same

 Source: [`packages/hooks/hook-protocol/src/types.ts:45`](../packages/hooks/hook-protocol/src/types.ts)

+### `mode/*`
+
+#### `mode/set` — log-only
+
+The session mode in force from this point on: log-only, non-surface, whole-value replace — the last `mode/set` in the log wins (see foldMode). A log with none folds to DEFAULT_MODE.
+
+```ts persistence-catalog
+'mode/set': { mode: string }
+```
+
+Source: [`packages/mode/mode/src/index.ts:39`](../packages/mode/mode/src/index.ts)
+
 ### `prompt/*`

 #### `prompt/blocked` — log-only