diff --git a/AGENTS.md b/AGENTS.md
index 4024eabf70..286b08212b 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -95,9 +95,7 @@ pnpm exec vitest run --config vitest.e2e.config.ts packages/examples/stdio-demo/
 
 ## Agent efficiency
 
-Habits earned by measured session waste.
-
-- **One-round gate runs**: any long command lands its FULL output in a temp file, prints a short summary, and on non-zero exit auto-expands capped failure context (`grep -B3 -A15 -E 'FAIL|ERROR' "$out" | head -60`) in the SAME invocation — never re-run to recover detail a filter discarded.
+- **One-round gate runs**: write full output to a temp file, print a summary, and include failure context (`grep -B3 -A15 -E 'FAIL|ERROR' "$out" | head -60`) in that invocation; never rerun to recover filtered detail.
 
 ## Secrets / .env
 
diff --git a/website/.vitepress/config/api-sidebar.json b/website/.vitepress/config/api-sidebar.json
index cdb6e2bfac..3704068be8 100644
--- a/website/.vitepress/config/api-sidebar.json
+++ b/website/.vitepress/config/api-sidebar.json
@@ -58,6 +58,10 @@
       "text": "ctx.llm",
       "link": "/zh-CN/api/harness/llm"
     },
+    {
+      "text": "ctx.modes",
+      "link": "/zh-CN/api/harness/modes"
+    },
     {
       "text": "ctx.permission",
       "link": "/zh-CN/api/harness/permission"
diff --git a/website/zh-CN/api/harness/bash-env.md b/website/zh-CN/api/harness/bash-env.md
index f8baf32bac..8807a28575 100644
--- a/website/zh-CN/api/harness/bash-env.md
+++ b/website/zh-CN/api/harness/bash-env.md
@@ -6,7 +6,7 @@
 
 Registry (`ctx.bashEnv`) for trusted, per-execution `DSH_*` variables. The namespace is rebuilt for every model bash call: ambient `DSH_*` values are discarded by the executor, then the registry's current snapshot is injected. Built-in shell facts remain owned by the registry itself while plugins can register additional, enumerable facts with effect-scoped disposal.
 
-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/bash/tool-bash/src/index.ts#L102)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/bash/tool-bash/src/index.ts#L109)
 
 ### ctx.bashEnv.register(contributor)
 
@@ -20,7 +20,7 @@ Register one environment contributor. Names and keys are unique; built-in keys a
 
 **Returns** the disposer that unregisters the contribution.
 
-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/bash/tool-bash/src/index.ts#L123)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/bash/tool-bash/src/index.ts#L130)
 
 ### ctx.bashEnv.collect(execution)
 
@@ -34,7 +34,7 @@ Build the trusted `DSH_*` snapshot for one bash tool execution.
 
 **Returns** an immutable environment overlay containing built-ins and current contributions.
 
-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/bash/tool-bash/src/index.ts#L165)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/bash/tool-bash/src/index.ts#L172)
 
 ### ctx.bashEnv.list()
 
@@ -46,4 +46,4 @@ Enumerate plugin-contributed variables without executing their resolvers.
 
 **Returns** declarations sorted by environment variable name.
 
-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/bash/tool-bash/src/index.ts#L197)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/bash/tool-bash/src/index.ts#L204)
diff --git a/website/zh-CN/api/harness/bash.md b/website/zh-CN/api/harness/bash.md
index c3e4173763..0d8ad4fa66 100644
--- a/website/zh-CN/api/harness/bash.md
+++ b/website/zh-CN/api/harness/bash.md
@@ -11,7 +11,7 @@ Implementations must honor these semantics:
 - BashProcess.readOutput is incremental: consecutive reads never repeat output. Lossy reads report truncation and available spill files.
 - Disposal kills all running background processes and awaits their exit.
 
-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/bash/bash/src/index.ts#L49)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/bash/bash/src/index.ts#L69)
 
 ### ctx.bash.sandboxMode
 
@@ -21,7 +21,21 @@ get sandboxMode(): SandboxMode | undefined
 
 The sandbox mode this executor applies by default, or `undefined` when it does not sandbox commands.
 
-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/bash/bash/src/index.ts#L59)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/bash/bash/src/index.ts#L79)
+
+### ctx.bash.resolveMode(session)
+
+```ts website-api
+async resolveMode(session: Session | undefined): Promise<SandboxMode | undefined>
+```
+
+Resolve the sandbox mode a call for `session` runs under: the session's standing override (the `bash/sandbox-mode` fold) falling back to this executor's configured default, dispatched through the `bash/resolve-mode` waterfall so policy plugins can narrow the base per call — read-time composition over independent folds, nothing written back to any store. Returns `undefined` — without consulting the waterfall — when this executor never confines (sandboxMode `undefined`): there is no mode to resolve and nothing would honor one. An escalation grant is not this method's business: the tool layer resolves grants separately and stamps them with higher precedence.
+
+- `session` — the session whose override fold applies; `undefined` for a sessionless caller (the executor default alone seeds the waterfall).
+
+**Returns** the effective mode for a confining executor; `undefined` for one that never confines.
+
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/bash/bash/src/index.ts#L100)
 
 ### ctx.bash.resolve(request)
 
@@ -35,7 +49,7 @@ Apply implementation-owned defaults and caps to a request before execution.
 
 **Returns** the fully-specified spec to hand to `run`/`start`.
 
-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/bash/bash/src/index.ts#L69)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/bash/bash/src/index.ts#L113)
 
 ### ctx.bash.run(spec)
 
@@ -49,7 +63,7 @@ Run a command in the foreground; resolves when it finishes.
 
 **Returns** the outcome; nonzero exits, timeout kills, and abort kills resolve with a descriptive result rather than reject.
 
-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/bash/bash/src/index.ts#L77)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/bash/bash/src/index.ts#L121)
 
 ### ctx.bash.start(spec)
 
@@ -63,4 +77,4 @@ Start a background process and return its handle immediately.
 
 **Returns** the live process handle (reads, kill, quiescence promise).
 
-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/bash/bash/src/index.ts#L84)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/bash/bash/src/index.ts#L128)
diff --git a/website/zh-CN/api/harness/events.md b/website/zh-CN/api/harness/events.md
index dbc778b593..98dc206d08 100644
--- a/website/zh-CN/api/harness/events.md
+++ b/website/zh-CN/api/harness/events.md
@@ -2,7 +2,7 @@
 
 # Harness events
 
-Every event the harness packages declare on the cordis event bus (39 total), grouped by scope. The **mode** is the dispatch semantics (`emit` fire-and-forget, `parallel` awaited, `serial` first-bail, `waterfall` veto-chain — a waterfall listener MUST call `next()` to delegate).
+Every event the harness packages declare on the cordis event bus (40 total), grouped by scope. The **mode** is the dispatch semantics (`emit` fire-and-forget, `parallel` awaited, `serial` first-bail, `waterfall` veto-chain — a waterfall listener MUST call `next()` to delegate).
 
 ## agent/*
 
@@ -229,6 +229,22 @@ Ask composed answerers for one decision. Return an outcome to claim the request
 
 [Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/ui/user-approval/src/index.ts#L31)
 
+## bash/*
+
+### bash/resolve-mode
+
+**Mode:** `waterfall`
+
+```ts website-api
+'bash/resolve-mode'(this: BashExecutor, session: Session | undefined, next: () => Promise<SandboxMode>): Promise<SandboxMode>
+```
+
+Waterfall around BashExecutor.resolveMode's base — the session's standing override falling back to the executor's configured default. A policy plugin narrows the resolution per call by clamping `await next()` (a session mode's `access` cap is the shipped example); returning without `next()` replaces the resolution outright. Dispatched only for a confining executor — a never-confining one resolves `undefined` without consulting listeners, so a listener always receives a real base mode from `next()`.
+
+- `session` — the session the call belongs to (its log carries the override fold and any mode state a listener clamps by); `undefined` for a sessionless caller.
+
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/bash/bash/src/index.ts#L49)
+
 ## fs/*
 
 ### fs/edit-intent
diff --git a/website/zh-CN/api/harness/modes.md b/website/zh-CN/api/harness/modes.md
new file mode 100644
index 0000000000..2e5781506c
--- /dev/null
+++ b/website/zh-CN/api/harness/modes.md
@@ -0,0 +1,58 @@
+<!-- Generated by scripts/gen-website-api.ts — do not edit by hand. Run `pnpm run gen-website-api` to regenerate. -->
+
+# ctx.modes
+
+`ModesService` — provided by `@deepseek-ai/dsh-mode`.
+
+`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.
+
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/mode/mode/src/index.ts#L256)
+
+### ctx.modes.resolved
+
+```ts website-api
+readonly resolved: ResolvedModes
+```
+
+Validated definitions (built-in `plan` merged unless overridden).
+
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/mode/mode/src/index.ts#L260)
+
+### ctx.modes.list()
+
+```ts website-api
+list(): string[]
+```
+
+The selectable mode vocabulary: DEFAULT_MODE first, then the configured definitions — the list a mode picker advertises.
+
+**Returns** Mode names, `default` first.
+
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/mode/mode/src/index.ts#L485)
+
+### ctx.modes.get(agent)
+
+```ts website-api
+get(agent: Agent): { current: string; pending?: string }
+```
+
+The agent's mode state: the folded mode in force (a folded name the config no longer defines reads as DEFAULT_MODE) plus the pending user-selected intent awaiting its boundary flush, when one exists.
+
+- `agent` — The agent to read.
+
+**Returns** The current (effective) mode and the pending intent, if any.
+
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/mode/mode/src/index.ts#L497)
+
+### ctx.modes.set(agent, mode)
+
+```ts website-api
+set(agent: Agent, mode: string): void
+```
+
+Select the agent's mode. Validates the name against list (loud on unknown; `default` is always a valid target), drops a no-op (target equals the pending intent, else the current fold), and otherwise records a pending intent flushed as a `mode/set` at the next turn boundary.
+
+- `agent` — The agent to switch.
+- `mode` — The target mode name.
+
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/mode/mode/src/index.ts#L512)