Merge origin/master into session-query-trace

packages/README.md

@@ -13,16 +13,17 @@ Packages live at `packages/<group>/<pkg>/`; groups are containers, while names r
 | [`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 |
-| [`fs/`](fs/README.md) | Filesystem capability family: the abstract seam, a local impl, and the model-facing file tools | Product — stable surface |
+| [`fs/`](fs/README.md) | Filesystem capability family: the abstract seam, a local impl, the model-facing file tools, and the bash-backed discovery tools | Product — stable surface |
 | [`skill/`](skill/README.md) | Skill capability family: the provider registry, local provider, and model-facing catalog/loader | Product — stable surface |
 | [`compact/`](compact/README.md) | Compaction capability family: the abstract seam + a basic backend (tool deferred) | Product — stable surface |
-| [`context/`](context/README.md) | Opt-in request-context enrichment | Product — stable surface |
+| [`context/`](context/README.md) | Model-visible request context, including workspace instructions and time context | Product — stable surface |
 | [`subagent/`](subagent/README.md) | Subagent capability family: the provider-registry seam and the model-facing delegation tool | Product — stable surface |
 | [`tasks/`](tasks/README.md) | Generic background-task runtime and model-facing `task_*` control tools | Product — stable surface |
 | [`workflow/`](workflow/README.md) | Workflow capability family: the script-engine seam, the worker-thread engine, and the model-facing `workflow` tool | Product — stable surface |
 | [`web/`](web/README.md) | Web capability family: the abstract seam, search/fetch provider impls, and the model-facing web tools | Product — stable surface |
-| [`timeout/`](timeout/README.md) | Tool-call timeout policy: the `tools/execute` deadline enforcer | Product — stable surface |
+| [`spill/`](spill/README.md) | Spill capability family: the storage seam, a local impl, and the tool-result spill policy | Product — stable surface |
 | [`todo/`](todo/README.md) | Todo/planning family: the model-facing `todo_write` tool | Product — stable surface |
+| [`timeout/`](timeout/README.md) | Tool-call timeout policy: the `tools/execute` deadline enforcer | Product — stable surface |
 | [`guard/`](guard/README.md) | Loop-hygiene guards: advisory repeat-call reminders | Product — stable surface |
 | [`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 |
@@ -31,14 +32,14 @@ Packages live at `packages/<group>/<pkg>/`; groups are containers, while names r
 | [`sdk/`](sdk/README.md) | Project SDK tooling | Product — stable surface |
 | [`ui/`](ui/README.md) | Editor/client integration surfaces: ACP bridge, JSON-RPC SDK server, user-approval/user-interaction seams, ask-user tool | Product — stable surface |
 | [`examples/`](examples/README.md) | Demo bundles (agent-spine + stdio/ACP/JSON-RPC bins) the leaves load | Support — example infra |
-| [`support/`](support/README.md) | Support infrastructure (invariants, replay, Loader smokes) | 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 |
+| [`support/`](support/README.md) | Support infrastructure (invariants, replay, Loader smokes, subagent mock) | Support — lower compatibility expectations |
+| [`util/`](util/README.md) | Low-level zero-dependency utilities shared across groups (`Branded<B>`, path helpers, timeout, retention) | Support — small, stable, harness-dep-free |
 
 Groups distinguish product API from support infrastructure. New packages join an existing group; a new group updates its README and this table.
 
 ## Dependencies
 
-The inter-package dependency graph is generated: [docs/module-graph.md](../docs/module-graph.md) (`pnpm run gen-module-graph`, freshness-gated in CI).
+The dependency graph is generated: [docs/module-graph.md](../docs/module-graph.md) (`pnpm run gen-module-graph`, freshness-gated in CI).
 
 The rule it must obey: **extension plugins depend on interfaces, never on the concrete loop.** `dsh-agent-loop` is swappable — UI/hook/tool plugins keep working against the `dsh-agent` vocabulary if the loop is replaced. The sanctioned exception is a **composition/bundle** package like `dsh-agent-spine-demo`, whose whole job is to assemble the concrete spine: it depends on `dsh-agent-loop` (and the other concrete spine plugins) on purpose. The rule constrains plugins that EXTEND the system, not the bundle that COMPOSES it. A swappable capability splits into interface / implementation / consumer packages (the bash trio is the template — see [capability seams](../docs/rfc/implemented/architecture/2026-06-13-capability-seams.md)).
 

packages/bash/bash-local/README.md

@@ -23,7 +23,7 @@ Design surveyed against the bash tools of Claude Code, OpenCode, Codex, and pi;
 
 - **Spawn per call, no shell state** — every call is a fresh non-login `bash -c` (deterministic; no rc files). All four surveyed tools spawn per call. `XXX(stateful-shell)` in `src/run.ts` records the two proven stateful designs (Claude Code's cwd-only persistence; Codex's PTY exec sessions) for when real workflows demand them.
 - **Process-group kills with escalation** — children are spawned `detached` (own process group); kills send SIGTERM to the group, then SIGKILL after the `graceMs` grace (default 3s — OpenCode's escalation; pipelines and subshells die with the parent). ESRCH is tolerated; daemons that re-parent away from the group can still survive — same caveat as the surveyed tools.
-- **Tail-keep truncation + spill files** — output beyond `maxOutputBytes` keeps the in-memory TAIL (errors/results cluster at the end — pi/OpenCode rationale) while the FULL stream is appended to a temp file whose path is reported when available. If the final spill close reports a delayed writeback failure, the executor still returns the tail but withholds the path rather than advertising a possibly incomplete file.
+- **Tail-keep truncation + spill files** — output beyond `maxOutputBytes` keeps the in-memory TAIL (errors/results cluster at the end — pi/OpenCode rationale) while the FULL stream is appended to a temp file whose path is reported when available. A foreground `BashExecRequest.stdoutMaxBytes` can raise stdout's capture budget for one trusted caller; stderr and background tasks still use `maxOutputBytes`. If the final spill close reports a delayed writeback failure, the executor still returns the tail but withholds the path rather than advertising a possibly incomplete file.
 - **Model-friendly env + credential scrub** — `process.env` minus credential-shaped vars (`*KEY*`/`*SECRET*`/`*TOKEN*`), then `NO_COLOR=1 TERM=dumb PAGER=cat GIT_PAGER=cat` (Codex's hardcoded set) so pagers and ANSI color don't garble results. This scrub is the security control that keeps the harness's *ambient* credentials out of a spawned command. A spec's `env` is merged LAST (after the scrub), so a caller's explicit entry — a value it already holds — wins even on a credential-shaped name. The spec's `stdin`, when supplied, is written to the child and closed; with none supplied, fd 0 is `/dev/null` — the exact pre-seam default, so a command that probes stdin's file type is unaffected. Both `env`/`stdin` are set by in-process plugins (the hooks bridges); the model-facing tool doesn't expose them. See [the bash-stdin-env RFC](../../../docs/rfc/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md).
 - **Background processes** — `start()` returns a live `BashProcess` handle immediately, no timeout applies (Claude Code detaches timeouts when backgrounding), the handle's `readOutput()` is incremental with whole-stream byte offsets, and disposal kills every running process and awaits its exit. Everything task-shaped (ids, ownership, polling, notices) lives in the generic [`ctx.tasks` runtime](../../tasks/tasks/README.md), which the tool layer registers the handle with — this executor never sees a session or a registry.
 

packages/bash/bash-local/src/index.ts

@@ -92,10 +92,13 @@ export class LocalBashExecutor extends BashExecutor {
       this.config.maxTimeoutMs,
       'bash-local: request.timeoutMs',
     )
+    const stdoutMaxBytes = request.stdoutMaxBytes ?? this.config.maxOutputBytes
+    assertPositiveFinite('request.stdoutMaxBytes', stdoutMaxBytes)
     return {
       command: request.command,
       workdir: request.workdir ?? this.config.cwd ?? process.cwd(),
       timeoutMs,
+      stdoutMaxBytes,
       ...request.signal ? { signal: request.signal } : {},
       // Explicit environment values are merged after credential scrubbing in run.ts.
       ...request.stdin !== undefined ? { stdin: request.stdin } : {},
@@ -111,7 +114,8 @@ export class LocalBashExecutor extends BashExecutor {
     const outcome = await runBash({
       command: spec.command,
       cwd: spec.workdir,
-      maxOutputBytes: this.config.maxOutputBytes,
+      stdoutMaxBytes: spec.stdoutMaxBytes,
+      stderrMaxBytes: this.config.maxOutputBytes,
       graceMs: this.config.graceMs,
       signal: d.signal,
       stdin: spec.stdin,
@@ -128,7 +132,8 @@ export class LocalBashExecutor extends BashExecutor {
     const running = runBash({
       command: spec.command,
       cwd: spec.workdir,
-      maxOutputBytes: this.config.maxOutputBytes,
+      stdoutMaxBytes: this.config.maxOutputBytes,
+      stderrMaxBytes: this.config.maxOutputBytes,
       graceMs: this.config.graceMs,
       signal: spec.signal,
       stdin: spec.stdin,

packages/bash/bash-local/src/run.ts

@@ -52,8 +52,10 @@ export function childEnv(extra?: Record<string, string>): NodeJS.ProcessEnv {
 export interface SpawnSpec {
   command: string
   cwd: string
-  /** Per-stream in-memory cap; overflow spills to disk (tail kept in memory). */
-  maxOutputBytes: number
+  /** Stdout in-memory cap; overflow spills to disk (tail kept in memory). */
+  stdoutMaxBytes: number
+  /** Stderr in-memory cap; overflow spills to disk (tail kept in memory). */
+  stderrMaxBytes: number
   /** Grace period between the SIGTERM and the SIGKILL escalation on a kill. */
   graceMs: number
   /**
@@ -283,8 +285,8 @@ export function runBash(spec: SpawnSpec, internals: RunInternals = {}): RunningB
     ? spawn('bash', ['-c', spec.command], { cwd: spec.cwd, env, stdio: ['pipe', 'pipe', 'pipe'], detached: true })
     : spawn('bash', ['-c', spec.command], { cwd: spec.cwd, env, stdio: ['ignore', 'pipe', 'pipe'], detached: true })
 
-  const stdout = new OutputCollector(spec.maxOutputBytes, 'stdout', spillDir)
-  const stderr = new OutputCollector(spec.maxOutputBytes, 'stderr', spillDir)
+  const stdout = new OutputCollector(spec.stdoutMaxBytes, 'stdout', spillDir)
+  const stderr = new OutputCollector(spec.stderrMaxBytes, 'stderr', spillDir)
   child.stdout.on('data', (chunk: Buffer) => { stdout.push(chunk) })
   child.stderr.on('data', (chunk: Buffer) => { stderr.push(chunk) })
 

packages/bash/bash-local/tests/executor.spec.ts

@@ -71,6 +71,23 @@ describe('LocalBashExecutor.run', () => {
     const { bash } = await setup()
     expect(() => bash.resolve({ command: 'true', timeoutMs: Number.NaN })).toThrow(/request\.timeoutMs/)
     expect(() => bash.resolve({ command: 'true', timeoutMs: -1 })).toThrow(/request\.timeoutMs/)
+    expect(() => bash.resolve({ command: 'true', stdoutMaxBytes: Number.NaN })).toThrow(/request\.stdoutMaxBytes/)
+    expect(() => bash.resolve({ command: 'true', stdoutMaxBytes: -1 })).toThrow(/request\.stdoutMaxBytes/)
+  })
+
+  it('defaults stdoutMaxBytes to maxOutputBytes and lets foreground callers raise stdout only', async () => {
+    const { bash } = await setup({ maxOutputBytes: 100 })
+    expect(bash.resolve({ command: 'true' }).stdoutMaxBytes).toBe(100)
+
+    const result = await bash.run(bash.resolve({
+      command: 'printf "%.0sx" $(seq 1 500); printf "%.0se" $(seq 1 500) >&2',
+      stdoutMaxBytes: 500,
+    }))
+
+    expect(result.stdout.truncated).toBe(false)
+    expect(result.stdout.text).toBe('x'.repeat(500))
+    expect(result.stderr.truncated).toBe(true)
+    expect(result.stderr.text.length).toBeLessThanOrEqual(100)
   })
 
   it('per-call timeout takes precedence under the cap and kills on expiry', async () => {

packages/bash/bash-local/tests/run.spec.ts

@@ -26,7 +26,8 @@ function spec(command: string, overrides: Partial<Parameters<typeof runBash>[0]>
   return {
     command,
     cwd: process.cwd(),
-    maxOutputBytes: 64_000,
+    stdoutMaxBytes: 64_000,
+    stderrMaxBytes: 64_000,
     graceMs: 3_000,
     ...overrides,
   }
@@ -224,10 +225,24 @@ describe('stdin and extra env (set by in-process plugins)', () => {
 })
 
 describe('output truncation and spill', () => {
+  it('applies stdout and stderr caps independently', async () => {
+    const result = await runBash(
+      spec('printf "%.0sx" $(seq 1 500); printf "%.0se" $(seq 1 500) >&2', {
+        stdoutMaxBytes: 500,
+        stderrMaxBytes: 100,
+      }),
+      { spillDir },
+    ).done
+    expect(result.stdout.truncated).toBe(false)
+    expect(result.stdout.text).toBe('x'.repeat(500))
+    expect(result.stderr.truncated).toBe(true)
+    expect(result.stderr.text.length).toBeLessThanOrEqual(100)
+  })
+
   it('keeps the tail and spills the full stream to disk', async () => {
     // 200 numbered lines of ~10 bytes; cap at 500 bytes keeps a late tail.
     const result = await runBash(
-      spec('for i in $(seq 1 200); do printf "line-%04d\\n" $i; done', { maxOutputBytes: 500 }),
+      spec('for i in $(seq 1 200); do printf "line-%04d\\n" $i; done', { stdoutMaxBytes: 500, stderrMaxBytes: 500 }),
       { spillDir },
     ).done
     expect(result.stdout.truncated).toBe(true)
@@ -242,7 +257,7 @@ describe('output truncation and spill', () => {
 
   it('does not truncate output exactly at the cap', async () => {
     const result = await runBash(
-      spec('printf "%.0sx" $(seq 1 500)', { maxOutputBytes: 500 }),
+      spec('printf "%.0sx" $(seq 1 500)', { stdoutMaxBytes: 500, stderrMaxBytes: 500 }),
       { spillDir },
     ).done
     expect(result.stdout.truncated).toBe(false)
@@ -253,7 +268,7 @@ describe('output truncation and spill', () => {
   it('settles with the tail and no spill path when final spill close fails', async () => {
     failNextClose.value = true
     const result = await runBash(
-      spec('for i in $(seq 1 200); do printf "line-%04d\\n" $i; done', { maxOutputBytes: 500 }),
+      spec('for i in $(seq 1 200); do printf "line-%04d\\n" $i; done', { stdoutMaxBytes: 500, stderrMaxBytes: 500 }),
       { spillDir },
     ).done
     expect(failNextClose.value).toBe(false)
@@ -364,7 +379,7 @@ describe('environment and spill-file hardening', () => {
 
   it('creates spill files with owner-only permissions and random names', async () => {
     const result = await runBash(
-      spec('for i in $(seq 1 200); do printf "line-%04d\\n" $i; done', { maxOutputBytes: 500 }),
+      spec('for i in $(seq 1 200); do printf "line-%04d\\n" $i; done', { stdoutMaxBytes: 500, stderrMaxBytes: 500 }),
       { spillDir },
     ).done
     const path = result.stdout.spillPath!
@@ -375,7 +390,7 @@ describe('environment and spill-file hardening', () => {
 
   it('defaults spills into a private per-process directory', async () => {
     const result = await runBash(
-      spec('for i in $(seq 1 200); do printf "line-%04d\\n" $i; done', { maxOutputBytes: 500 }),
+      spec('for i in $(seq 1 200); do printf "line-%04d\\n" $i; done', { stdoutMaxBytes: 500, stderrMaxBytes: 500 }),
     ).done
     const dir = dirname(result.stdout.spillPath!)
     expect(dir).toMatch(/dsh-bash-/)

packages/bash/bash/README.md

@@ -27,7 +27,7 @@ Implementations subclass `BashExecutor` and implement the abstract methods. Disp
 
 ## Vocabulary
 
-`BashExecRequest` (command, workdir?, timeoutMs?, signal?, stdin?, env?, sandboxMode?) resolves to `BashExecSpec` (command, workdir, timeoutMs, signal?, stdin?, env?, sandboxMode) before execution. `sandboxMode` is optional on the request and required-but-nullable on the resolved spec: it carries an approved one-shot escalation or the session's standing override; a sandboxing executor stamps its configured default when absent, while a non-sandboxing executor carries the field and confines nothing.
+`BashExecRequest` (command, workdir?, timeoutMs?, stdoutMaxBytes?, signal?, stdin?, env?, sandboxMode?) resolves to `BashExecSpec` (command, workdir, timeoutMs, stdoutMaxBytes, signal?, stdin?, env?, sandboxMode) before execution. `stdoutMaxBytes` is a trusted foreground-run capture budget for consumers that must parse complete bounded stdout; the model-facing bash tool does not expose it. `sandboxMode` is optional on the request and required-but-nullable on the resolved spec: it carries an approved one-shot escalation or the session's standing override; a sandboxing executor stamps its configured default when absent, while a non-sandboxing executor carries the field and confines nothing.
 
 The seam also owns the per-session mode override vocabulary: the log-only `'bash/sandbox-mode'` session event, the pure `effectiveSandboxMode(events)` fold, and the `setSandboxMode(session, mode)` write path. `run()` returns `BashRunResult`; `start()` returns `BashProcess`, whose incremental read and kill methods are adapted by `dsh-tool-bash` into a generic task registration. A sandboxing executor stamps `BashSandboxInfo` on foreground results and settled process handles. See `src/types.ts` and [core-data-structures/bash.md](../../../docs/core-data-structures/bash.md).
 

packages/bash/bash/src/types.ts

@@ -34,6 +34,13 @@ export interface BashExecRequest {
   workdir?: string | undefined
   /** Timeout override in milliseconds (implementations cap it). */
   timeoutMs?: number | undefined
+  /**
+   * Foreground stdout capture budget in bytes. Absent uses the executor's
+   * default output cap. Trusted in-process consumers use this when they must
+   * parse complete stdout up to their own bounded limit; the model-facing bash
+   * tool does not expose it as a parameter.
+   */
+  stdoutMaxBytes?: number | undefined
   /** Abort signal — implementations kill the command when it fires. */
   signal?: AbortSignal | undefined
   /**
@@ -67,6 +74,11 @@ export interface BashExecSpec {
   command: string
   workdir: string
   timeoutMs: number
+  /**
+   * Resolved foreground stdout capture budget in bytes. `run()` uses it for
+   * stdout; background tasks and stderr keep the executor's own output cap.
+   */
+  stdoutMaxBytes: number
   /** Abort signal — implementations kill the command when it fires. */
   signal?: AbortSignal | undefined
   /** Bytes to write to stdin before closing it; absent means no stdin. */
@@ -96,9 +108,19 @@ export interface BashRunResult {
   exitCode: number | null
   /** Terminating signal (e.g. 'SIGTERM'); null on normal exit. */
   signal: NodeJS.Signals | null
-  /** True when the executor's own timeout killed the command. */
+  /**
+   * True when the executor's own timeout was the FIRST cause to cut the command
+   * short. Mutually exclusive with {@link aborted}: one fused deadline drives
+   * both the timeout and the caller's cancellation, so a timeout and an abort
+   * racing before process close report the single first-abort cause, not both
+   * (see the [timeout-library RFC](../../../../docs/rfc/implemented/architecture/2026-07-06-timeout-deadline-library.md)).
+   */
   timedOut: boolean
-  /** True when the caller's AbortSignal killed the command. */
+  /**
+   * True when the caller's `AbortSignal` was the FIRST cause to kill the command
+   * (and it was not the executor's own timeout). Mutually exclusive with
+   * {@link timedOut} — see there for the first-cause classification.
+   */
   aborted: boolean
   /** The effective timeout applied to this run (after defaulting/capping). */
   timeoutMs: number

packages/bash/bash/tests/service.spec.ts

@@ -15,6 +15,7 @@ class StubExecutor extends BashExecutor {
       command: request.command,
       workdir: request.workdir ?? '/stub',
       timeoutMs: request.timeoutMs ?? 1000,
+      stdoutMaxBytes: request.stdoutMaxBytes ?? 64_000,
       ...request.signal ? { signal: request.signal } : {},
       sandboxMode: request.sandboxMode,
     }
@@ -54,7 +55,7 @@ describe('BashExecutor service seam', () => {
     const ctx = new Context()
     await ctx.plugin(StubExecutor)
     const spec = ctx.bash.resolve({ command: 'echo hi' })
-    expect(spec).toEqual({ command: 'echo hi', workdir: '/stub', timeoutMs: 1000, sandboxMode: undefined })
+    expect(spec).toEqual({ command: 'echo hi', workdir: '/stub', timeoutMs: 1000, stdoutMaxBytes: 64_000, sandboxMode: undefined })
 
     const result = await ctx.bash.run(spec)
     expect(result.exitCode).toBe(0)

packages/bash/tool-bash/README.md

@@ -34,7 +34,7 @@ The tool owns its `presentCall`/`presentResult` render intent. A foreground call
 
 ## The tool builds its request from named args only
 
-The `BashExecRequest` seam carries optional `stdin` and `env`, used by trusted in-process plugins. This tool does **not** expose or forward them: it builds requests from named command/workdir/timeout/signal/sandbox fields only. This is not a trust boundary; the local executor's ambient credential scrub is the security control.
+The `BashExecRequest` seam carries optional `stdoutMaxBytes`, `stdin`, and `env`, used by trusted in-process plugins. This tool does **not** expose or forward them: it builds requests from named command/workdir/timeout/signal/sandbox fields only. This is not a trust boundary; the local executor's ambient credential scrub is the security control.
 
 ## Permissions and escalation
 

packages/bash/tool-bash/tests/tools.spec.ts

@@ -101,6 +101,7 @@ class RecordingSandboxExecutor extends BashExecutor {
     return {
       command: request.command,
       workdir: request.workdir ?? process.cwd(),
+      stdoutMaxBytes: request.stdoutMaxBytes ?? 64_000,
       timeoutMs: request.timeoutMs ?? 1000,
       ...request.signal ? { signal: request.signal } : {},
       sandboxMode: request.sandboxMode ?? 'read-only',
@@ -140,7 +141,13 @@ class CountingStartExecutor extends BashExecutor {
   starts = 0
 
   resolve(request: BashExecRequest): BashExecSpec {
-    return { command: request.command, workdir: request.workdir ?? '/x', timeoutMs: request.timeoutMs ?? 0, sandboxMode: request.sandboxMode }
+    return {
+      command: request.command,
+      workdir: request.workdir ?? '/x',
+      timeoutMs: request.timeoutMs ?? 0,
+      stdoutMaxBytes: request.stdoutMaxBytes ?? 64_000,
+      sandboxMode: request.sandboxMode,
+    }
   }
 
   run(): Promise<BashRunResult> { return Promise.reject(new Error('unused')) }
@@ -927,11 +934,12 @@ describe('the model-facing bash tool builds its request from named args only (no
   /**
    * Records every {@link BashExecRequest} the consumer hands to `resolve()`, so a
    * test can assert what the model-facing tool DID and DID NOT forward. The `bash`
-   * tool does not expose `stdin`/`env` as parameters (bash syntax already gives a
-   * model that power), so it must build its request from named args only and
+   * tool does not expose trusted-plugin fields (`stdoutMaxBytes`, `stdin`, or
+   * `env`) as parameters, so it must build its request from named args only and
    * never spread unknown tool-call keys into it. This guard's job is to catch a
    * future refactor that blindly forwards `...args` — which would silently thread
-   * model input into the post-scrub `env` merge — NOT to defend a trust boundary
+   * model input into the post-scrub `env` merge or per-run capture budget — NOT
+   * to defend a trust boundary
    * (the credential scrub in dsh-bash-local is the security control; see the
    * bash-stdin-env RFC). Foreground `run()` returns a canned result; `start()`
    * hands back an already-settled fake handle so the task registration completes.
@@ -944,6 +952,7 @@ describe('the model-facing bash tool builds its request from named args only (no
         command: request.command,
         workdir: request.workdir ?? process.cwd(),
         timeoutMs: request.timeoutMs ?? 0,
+        stdoutMaxBytes: request.stdoutMaxBytes ?? 64_000,
         ...request.signal ? { signal: request.signal } : {},
         ...request.stdin !== undefined ? { stdin: request.stdin } : {},
         ...request.env !== undefined ? { env: request.env } : {},
@@ -980,7 +989,7 @@ describe('the model-facing bash tool builds its request from named args only (no
     return { ctx, bash: ctx.bash as RecordingBashExecutor }
   }
 
-  it('does not forward env/stdin even when the model includes them as extra arguments', async () => {
+  it('does not forward trusted-only fields even when the model includes them as extra arguments', async () => {
     const { ctx, bash } = await setupRecording()
     // Unknown `env` and `stdin` keys are ignored by the schema and named request construction.
     // This preserves the request shape; it is not a security boundary because shell syntax can
@@ -993,6 +1002,7 @@ describe('the model-facing bash tool builds its request from named args only (no
         description: 'echo',
         env: { SNEAKY_API_KEY: 'leak' },
         stdin: 'malicious payload',
+        stdoutMaxBytes: 999_999,
       },
     })
     expect(bash.requests).toHaveLength(1)
@@ -1000,9 +1010,10 @@ describe('the model-facing bash tool builds its request from named args only (no
     expect(request.command).toBe('echo hi')
     expect('env' in request).toBe(false)
     expect('stdin' in request).toBe(false)
+    expect('stdoutMaxBytes' in request).toBe(false)
   })
 
-  it('a background bash call likewise carries no env/stdin', async () => {
+  it('a background bash call likewise carries no trusted-only fields', async () => {
     const { ctx, bash } = await setupRecording()
     const result = await ctx.tools.execute({
       callId: CallId('no-forward-2'),
@@ -1013,6 +1024,7 @@ describe('the model-facing bash tool builds its request from named args only (no
         run_in_background: true,
         env: { TOKEN: 'leak' },
         stdin: 'x',
+        stdoutMaxBytes: 999_999,
       },
     })
     // The call really went down the background path (the recorder sees the real
@@ -1024,5 +1036,6 @@ describe('the model-facing bash tool builds its request from named args only (no
     expect(request.command).toBe('sleep 1')
     expect('env' in request).toBe(false)
     expect('stdin' in request).toBe(false)
+    expect('stdoutMaxBytes' in request).toBe(false)
   })
 })

packages/context/README.md

@@ -1,7 +1,10 @@
-# context/ — optional request context
+# context/ — request-context extensions
 
-Opt-in plugins that add bounded model-visible request context without defining a tool or service. The default `dsh-agent-spine-demo` bundle excludes them.
+Product plugins that add bounded model-visible request context without defining a tool or service. `workspace-context` is included by the default `dsh-agent-spine-demo` bundle and can be disabled through bundle config; `time-context` is opt-in.
 
 | Package | Role | ctx key |
 |---|---|---|
 | `time-context/` | Current time and elapsed-time system-prompt context | (none) |
+| `workspace-context/` | `AGENTS.md`/`CLAUDE.md` workspace context loader | (listens on `agent/session-prefix` + `tools/post-execute`) |
+
+The [`workspace-context` decision record](../../docs/rfc/implemented/feature/2026-06-24-workspace-context.md) explains its per-agent/session isolation and lifecycle split.

packages/context/time-context/tests/fixtures/cordis.yml

@@ -15,3 +15,4 @@
     persona: 'Test the time-context plugin.'
     welcome: 'time-context e2e ready.'
     persistenceRoot: './.sessions'
+    workspaceContext: false

packages/context/workspace-context/README.md

@@ -0,0 +1,140 @@
+# @deepseek-ai/dsh-workspace-context
+
+Per-session workspace instruction loading for `AGENTS.md`-compatible files. The plugin freezes the initial user-global and project instruction chain into the request prefix, then discovers nested files and reports later changes or removals through durable context messages after successful filesystem tool calls.
+
+## Lifecycle
+
+The baseline is composed once per agent-loop instance on `agent/session-prefix`. It reads `$DSH_HOME/AGENTS.md` followed by one configured instruction candidate in each directory from the project root to `agent.session.header.cwd`. The prefix is placed before all derived history, recorded in `EpochHeader.messagePrefix`, and reused verbatim for that loop instance. Because the plugin prepends its contribution before delegating, a later-registered skills catalog appears after workspace instructions.
+
+The plugin also listens on `tools/post-execute` for successful first-party `read`, `write`, and `edit` calls. Each touch checks newly reached descendant scopes and every previously loaded scope. A new file is attached through the result's `additionalContexts`; a changed file or candidate switch appends a replacement; a missing final candidate appends a removal notice. Native calls and Code Mode sub-dispatches share this path: `run_code` defers each nested context until its outer result, so the loop still appends updates after tool-call/result adjacency is complete. This follows structured filesystem activity rather than shell `cd`, because each local bash call starts a fresh shell and parsing arbitrary shell syntax would be unreliable.
+
+Instruction reads use the optional `ctx.fs` provider. The plugin does not statically inject `fs`, so providerless product trees still boot and instruction loading becomes a no-op until a provider is present. It calls `ctx.fs.lstat` before resolving a candidate, rejecting a final-component symlink instead of following repository-owned links across the trust boundary. Once `lstat` identifies the winning regular-file candidate, a later resolve/stat failure makes that scope temporarily unavailable instead of falling through to a lower-priority name. Prefix cancellation and dynamic tool cancellation propagate through resolution, metadata probes, and streaming reads. A provider failure after a file was loaded is treated as temporarily unavailable, not as proof that the file was deleted.
+
+## Prompt Shape
+
+Baseline instructions are request-only user-role prefix messages framed with the familiar system-reminder pattern:
+
+```md
+<system-reminder>
+The following workspace instructions may be relevant to your work. Use them as guidance when applicable. More specific instructions take precedence over broader ones. They do not override system, developer, or direct user instructions.
+
+Instructions from: ~/.dsh/AGENTS.md
+
+...
+
+Instructions from: AGENTS.md
+
+...
+</system-reminder>
+```
+
+Newly reached scopes use a durable raw `context/message`:
+
+```md
+<system-reminder>
+Additional instructions from: packages/app/AGENTS.md
+
+These instructions apply to work under `packages/app`. Use them as guidance when relevant; more specific instructions take precedence. They do not override system, developer, or direct user instructions.
+
+...
+</system-reminder>
+```
+
+A same-file edit starts with `Updated instructions from: <path>` and says to use the new content instead of the previously loaded content. A candidate switch additionally names the old path. When no candidate remains, the message is `Instructions removed: <path>` followed by `The previously loaded instructions from this file no longer apply.` Literal `</system-reminder>` text inside an instruction file is escaped so file content cannot close the plugin-owned frame.
+
+The core `context/message` envelope is disabled for these messages because the plugin already owns the complete `<system-reminder>` framing. This is caller-selected with `envelope: 'raw'`; ordinary injected context still receives the canonical `<context source="...">` envelope.
+
+## State And Refresh
+
+Model-visible text contains no hidden state markers. Each dynamic context event instead carries JSON metadata with a versioned list of `{ action, scope, path, previousPath?, digest? }` changes. On every relevant tool touch, the plugin reconstructs loaded state from its visible session events and overlays a short in-memory pending window for context present on the immutable top-level `tools/result` but not yet appended by the loop. A matching durable `context/message` confirms the pending transition. If the owning `step/end` arrives first because a later tool aborted the step and the loop discarded its context buffer, the plugin clears the pending transition and its version fast path so the next successful touch can load it again. Nested Code Mode results stage pending changes under the outer execution token for same-run duplicate suppression; the outer result rolls that state back and recommits only contexts that survived outer policy.
+
+An unchanged path and SHA-1 content digest is not injected again. A per-session, per-scope metadata cache stores only `{ path, version, digest }`: when the provider's opaque `FsVersion` and the effective visible state both match, reconciliation skips the content read; a changed version triggers a bounded read and SHA-1 confirmation before any model-visible update. Resume works because SHA-1 state is persisted in the session log, while an empty in-memory version cache merely causes one confirming read. Compaction re-arms a scope after its context event leaves the visible surface even when the cached version is unchanged. A removal is a tombstone, so a later candidate reappearance is loaded again. Only model-visible changes actually rendered within the byte budget enter metadata, pending state, and the version cache; an omitted change remains eligible for a later touch, while a same-digest version refresh updates metadata only.
+
+The frozen baseline itself is not rewritten mid-instance. Its initial path/digest map is retained as comparison state; the next successful filesystem touch appends any baseline replacement or removal. A resumed loop recomposes the current baseline and also reconciles still-visible dynamic scopes during prefix composition. There is no file watcher, so an on-disk change becomes visible at the next successful `read`, `write`, or `edit` touch, or when a resumed loop composes its prefix.
+
+## Configuration
+
+```ts
+export interface Config {
+  dshHome?: string
+  projectRootMarkers?: string[]
+  maxBytes: number
+  maxSourceBytes?: number
+  instructionFileCandidates?: string[]
+}
+```
+
+`maxBytes` is required so each deployment makes its prompt-budget choice explicitly. `maxSourceBytes` limits each source instruction file before rendering and defaults to 1 MiB. `projectRootMarkers` defaults to `['.git']`, and `instructionFileCandidates` defaults to `['AGENTS.md', 'CLAUDE.md']`. In each project directory, the first existing candidate wins; with defaults, `AGENTS.md` is native and `CLAUDE.md` is the compatibility fallback. Candidate entries must be same-directory file names, so empty entries, `.`/`..`, and entries containing `/` or `\` are ignored.
+
+The user-global file is always `$DSH_HOME/AGENTS.md`; the candidate list only controls project scopes. `$DSH_HOME` defaults to `~/.dsh`, and configured `~`, `~/...`, and Windows-style `~\...` prefixes are expanded against the operating-system home directory. A non-positive or non-finite render budget disables both baseline and dynamic loading; configured `maxSourceBytes` must be a positive integer.
+
+## Budgeting And Bounded Reads
+
+Rendering preserves the most specific instruction files first. It drops whole broader files before truncating the most-specific file and emits a visible `Workspace instruction budget ...` notice naming omitted and truncated paths. The rendered bytes never exceed `maxBytes`.
+
+Instruction content is read through `streamText()` under `maxSourceBytes`, even when provider metadata omits size or a file grows after its metadata probe. An oversized file is ignored without falling through to a lower-priority same-directory candidate; during dynamic reconciliation it is temporarily unavailable rather than removed. The plugin keeps no process-wide cache and never caches instruction prose. Its session-local scope cache uses provider versions only as a fast invalidation signal; after invalidation, SHA-1 over the bounded read remains the cross-provider content identity stored in structured session metadata.
+
+## Model Experience
+
+### Baseline session prefix
+
+**What the model sees**: At the first request of each loop instance, the model receives one user-role prefix message containing the bounded user-global and project instruction chain in broad-to-specific order.
+
+**Token effect**: The rendered baseline is frozen and resent on every request in that loop instance. `maxBytes` bounds the complete message, broader files are omitted before the most-specific file is truncated, and an empty chain contributes zero tokens.
+
+#### Baseline instruction template
+
+```markdown
+<system-reminder>
+The following workspace instructions may be relevant to your work. Use them as guidance when applicable. More specific instructions take precedence over broader ones. They do not override system, developer, or direct user instructions.
+
+Instructions from: ~/.dsh/AGENTS.md
+
+<user-global-instructions>
+
+Instructions from: AGENTS.md
+
+<project-instructions>
+</system-reminder>
+```
+
+### Newly discovered scope context
+
+**What the model sees**: After a successful first-party filesystem call reaches a deeper directory, the next request includes one retained raw `context/message` with the newly applicable instruction file.
+
+**Token effect**: Each discovered scope adds bounded history tokens until compaction. Unchanged content is suppressed by visible session state plus version/digest comparison, and Code Mode defers the same message until after the outer `run_code` result.
+
+#### Additional instruction template
+
+```markdown
+<system-reminder>
+Additional instructions from: packages/app/AGENTS.md
+
+These instructions apply to work under `packages/app`. Use them as guidance when relevant; more specific instructions take precedence. They do not override system, developer, or direct user instructions.
+
+<nested-instructions>
+</system-reminder>
+```
+
+### Changed or removed instruction context
+
+**What the model sees**: A changed file produces `Updated instructions from: <path>` plus its replacement content; a candidate switch also names the previous path. A removed final candidate produces the removal notice below.
+
+**Token effect**: Each confirmed change or removal is one retained history message bounded by `maxBytes`. Provider failures add no message, and an update omitted by the budget remains eligible for a later filesystem touch.
+
+#### Removal notice
+
+```markdown
+<system-reminder>
+Instructions removed: packages/app/AGENTS.md
+
+The previously loaded instructions from this file no longer apply.
+</system-reminder>
+```
+
+## Known Limitations and Deferred Work
+
+- **Discovery follows structured fs tools, not shell navigation** — a `bash` command that changes directories does not trigger nested instruction discovery because shell syntax and per-call shell state are not a reliable filesystem seam.
+- **Refresh is touch-driven** — there is no watcher; external edits become visible on the next successful first-party `read`, `write`, or `edit`, or when a resumed loop recomposes its prefix.
+- **Candidate semantics stay intentionally small** — lowercase names, `.claude/rules/`, and `@path` imports are not interpreted; same-directory names such as `CLAUDE.local.md` require explicit `instructionFileCandidates` configuration.
+- **Instruction content is bounded, not summarized** — over-budget broad files are omitted and the most-specific file may be truncated; the plugin never asks a model to compress instruction prose.

packages/context/workspace-context/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@deepseek-ai/dsh-workspace-context",
+  "description": "Workspace context loader for AGENTS.md/CLAUDE.md instruction files",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-agent": "^0.0.1",
+    "@deepseek-ai/dsh-fs": "^0.0.1",
+    "@deepseek-ai/dsh-llm": "^0.0.1",
+    "@deepseek-ai/dsh-paths": "^0.0.1",
+    "@deepseek-ai/dsh-session": "^0.0.1",
+    "@deepseek-ai/dsh-tools": "^0.0.1",
+    "cordis": "^4.0.0-rc.6"
+  },
+  "dependencies": {
+    "schemastery": "^3.18.0"
+  },
+  "devDependencies": {
+    "@cordisjs/plugin-loader": "workspace:^",
+    "@deepseek-ai/dsh-agent": "workspace:^",
+    "@deepseek-ai/dsh-agent-loop": "workspace:^",
+    "@deepseek-ai/dsh-fs": "workspace:^",
+    "@deepseek-ai/dsh-fs-local": "workspace:^",
+    "@deepseek-ai/dsh-llm": "workspace:^",
+    "@deepseek-ai/dsh-llm-deepseek": "workspace:^",
+    "@deepseek-ai/dsh-paths": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
+    "@deepseek-ai/dsh-system-prompt": "workspace:^",
+    "@deepseek-ai/dsh-tool-fs": "workspace:^",
+    "@deepseek-ai/dsh-tools": "workspace:^",
+    "cordis": "^4.0.0-rc.6"
+  }
+}

packages/context/workspace-context/src/config.ts

@@ -0,0 +1,82 @@
+/**
+ * Configuration normalization for workspace instruction discovery and rendering.
+ *
+ * @module @deepseek-ai/dsh-workspace-context/config
+ */
+
+import z from 'schemastery'
+import { resolveDshHome } from '@deepseek-ai/dsh-paths'
+
+const DEFAULT_PROJECT_ROOT_MARKERS = ['.git'] as const
+const DEFAULT_INSTRUCTION_FILE_CANDIDATES = ['AGENTS.md', 'CLAUDE.md'] as const
+const DEFAULT_MAX_SOURCE_BYTES = 1_048_576
+const RESERVED_PATH_SEGMENTS = new Set(['', '.', '..'])
+
+/** User-facing workspace instruction loader configuration. */
+export interface Config {
+  /** Harness home containing the fixed user-global `AGENTS.md`; defaults to `$DSH_HOME` or `~/.dsh`. */
+  dshHome?: string
+  /** Directory entries that identify the project root while walking upward from the session cwd. */
+  projectRootMarkers?: string[]
+  /** UTF-8 byte cap for one rendered baseline or dynamic batch; non-positive or non-finite disables loading. */
+  maxBytes: number
+  /** Maximum UTF-8 bytes read from one instruction file; larger files are ignored. */
+  maxSourceBytes?: number
+  /** Ordered same-directory project candidates; the first existing regular file wins in each scope. */
+  instructionFileCandidates?: string[]
+}
+
+export const Config: z<Config> = z.object({
+  dshHome: z.string(),
+  projectRootMarkers: z.array(z.string()).default([...DEFAULT_PROJECT_ROOT_MARKERS]),
+  maxBytes: z.number().required(),
+  maxSourceBytes: z.number().step(1).min(1).default(DEFAULT_MAX_SOURCE_BYTES),
+  instructionFileCandidates: z.array(z.string()).default([...DEFAULT_INSTRUCTION_FILE_CANDIDATES]),
+})
+
+/** Normalized instruction discovery configuration. */
+export interface ResolvedDiscoveryConfig {
+  dshHome: string
+  projectRootMarkers: string[]
+  instructionFileCandidates: string[]
+}
+
+/** Normalized configuration used by discovery and reconciliation. */
+export interface ResolvedConfig extends ResolvedDiscoveryConfig {
+  maxBytes: number
+  maxSourceBytes: number
+}
+
+/**
+ * Resolve defaults, the harness home, and valid same-directory candidates.
+ * @param config - user-facing plugin configuration.
+ * @returns normalized runtime configuration.
+ */
+export function resolveConfig(config: Config): ResolvedConfig {
+  return {
+    ...resolveDiscoveryConfig(config),
+    maxBytes: config.maxBytes,
+    maxSourceBytes: config.maxSourceBytes ?? DEFAULT_MAX_SOURCE_BYTES,
+  }
+}
+
+/**
+ * Resolve the subset of configuration used before instruction content is rendered.
+ * @param config - optional discovery controls.
+ * @returns normalized home, root markers, and instruction candidates.
+ */
+export function resolveDiscoveryConfig(
+  config: Pick<Config, 'dshHome' | 'projectRootMarkers' | 'instructionFileCandidates'>,
+): ResolvedDiscoveryConfig {
+  return {
+    dshHome: resolveDshHome(config.dshHome),
+    projectRootMarkers: config.projectRootMarkers ?? [...DEFAULT_PROJECT_ROOT_MARKERS],
+    instructionFileCandidates: resolveInstructionFileCandidates(config.instructionFileCandidates),
+  }
+}
+
+function resolveInstructionFileCandidates(candidates: string[] | undefined): string[] {
+  return (candidates ?? [...DEFAULT_INSTRUCTION_FILE_CANDIDATES]).filter(candidate => (
+    !RESERVED_PATH_SEGMENTS.has(candidate) && !/[\\/]/.test(candidate)
+  ))
+}

packages/context/workspace-context/src/digest.ts

@@ -0,0 +1,16 @@
+/**
+ * Content identity for workspace instruction duplicate suppression.
+ *
+ * @module @deepseek-ai/dsh-workspace-context/digest
+ */
+
+import { createHash } from 'node:crypto'
+
+/**
+ * Compute the content identity used across instruction loading and session state.
+ * @param content - exact UTF-8 instruction text.
+ * @returns lowercase SHA-1 digest in hexadecimal form.
+ */
+export function instructionContentSha1(content: string): string {
+  return createHash('sha1').update(content).digest('hex')
+}

packages/context/workspace-context/src/files.ts

@@ -0,0 +1,473 @@
+/**
+ * Instruction-file discovery and bounded, abort-aware provider reads.
+ *
+ * @module @deepseek-ai/dsh-workspace-context/files
+ */
+
+import { createReadStream } from 'node:fs'
+import { lstat, stat } from 'node:fs/promises'
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path'
+import type { FileSystem, FsInfo, FsPathInfo, FsTarget, FsVersion } from '@deepseek-ai/dsh-fs'
+import { assertNever } from '@deepseek-ai/dsh-llm'
+import { DEFAULT_DSH_HOME_DISPLAY, defaultDshHome } from '@deepseek-ai/dsh-paths'
+import { resolveConfig, resolveDiscoveryConfig, type ResolvedConfig } from './config.ts'
+import { renderWorkspaceContext, type RenderedWorkspaceContext } from './render.ts'
+
+/** An instruction candidate identified by absolute and model-facing paths. */
+export interface InstructionFile {
+  absolutePath: string
+  displayPath: string
+}
+
+/** An instruction file whose UTF-8 content was read successfully. */
+export interface LoadedInstructionFile extends InstructionFile {
+  content: string
+  /** Provider freshness token when the file was loaded through `ctx.fs`. */
+  version?: FsVersion
+}
+
+interface DiscoveredInstructionFile extends InstructionFile {
+  target?: FsTarget
+  size?: number
+  version?: FsVersion
+}
+
+/** Provider metadata for a winning scope candidate before its content is read. */
+export interface ProbedInstructionFile extends InstructionFile {
+  target: FsTarget
+  version: FsVersion
+  size?: number
+}
+
+interface DiscoverOptions {
+  cwd: string
+  dshHome?: string
+  projectRootMarkers?: string[]
+  instructionFileCandidates?: string[]
+  signal?: AbortSignal
+}
+
+interface LoadOptions extends DiscoverOptions {
+  maxBytes: number
+  maxSourceBytes?: number
+}
+
+/** Rendered baseline plus the files that survived byte budgeting. */
+export interface RenderedInstructionSet {
+  rendered: RenderedWorkspaceContext
+  included: LoadedInstructionFile[]
+}
+
+/** Tri-state scope probe that distinguishes confirmed absence from provider failure. */
+export type ScopeInstructionProbe =
+  | { kind: 'present'; file: ProbedInstructionFile }
+  | { kind: 'absent' }
+  | { kind: 'unavailable' }
+
+interface StatFileInfo {
+  target?: FsTarget
+  size?: number
+  version?: FsVersion
+}
+
+type StatFileProbe =
+  | { kind: 'present'; info: StatFileInfo }
+  | { kind: 'absent' }
+  | { kind: 'unavailable' }
+
+function signalOptions(signal?: AbortSignal): { signal: AbortSignal } | undefined {
+  return signal === undefined ? undefined : { signal }
+}
+
+function isMissingPathError(error: unknown): boolean {
+  return error instanceof Error && 'code' in error && (error.code === 'ENOENT' || error.code === 'ENOTDIR')
+}
+
+async function nodeStatFile(path: string, signal?: AbortSignal): Promise<StatFileProbe> {
+  try {
+    signal?.throwIfAborted()
+    const info = await lstat(path)
+    signal?.throwIfAborted()
+    if (!info.isFile()) return { kind: 'absent' }
+    return { kind: 'present', info: { size: info.size } }
+  } catch (error: unknown) {
+    signal?.throwIfAborted()
+    return isMissingPathError(error) ? { kind: 'absent' } : { kind: 'unavailable' }
+  }
+}
+
+async function fsStatFile(
+  path: string,
+  fileSystem: FileSystem,
+  signal?: AbortSignal,
+): Promise<StatFileProbe> {
+  // TODO(instruction-symlink-race): replace this lstat -> resolve -> read
+  // protocol, including probeScopeInstruction below, with a provider-owned
+  // atomic no-follow read so the final component cannot change after validation.
+  let pathInfo: FsPathInfo | undefined
+  try {
+    pathInfo = await fileSystem.lstat(path, undefined, signal)
+    signal?.throwIfAborted()
+  } catch {
+    signal?.throwIfAborted()
+    return { kind: 'unavailable' }
+  }
+  if (pathInfo?.type !== 'file') return { kind: 'absent' }
+
+  try {
+    const target = await fileSystem.resolve(path, signalOptions(signal))
+    signal?.throwIfAborted()
+    const info = await fileSystem.stat(target, signal)
+    signal?.throwIfAborted()
+    if (info?.type !== 'file') return { kind: 'unavailable' }
+    return {
+      kind: 'present',
+      info: { target, version: info.version, ...info.size === undefined ? {} : { size: info.size } },
+    }
+  } catch {
+    signal?.throwIfAborted()
+    return { kind: 'unavailable' }
+  }
+}
+
+async function statFile(
+  path: string,
+  fileSystem?: FileSystem,
+  signal?: AbortSignal,
+): Promise<StatFileProbe> {
+  return fileSystem === undefined ? nodeStatFile(path, signal) : fsStatFile(path, fileSystem, signal)
+}
+
+async function existsAsMarker(path: string, fileSystem?: FileSystem, signal?: AbortSignal): Promise<boolean> {
+  if (fileSystem !== undefined) {
+    try {
+      const target = await fileSystem.resolve(path, signalOptions(signal))
+      return await fileSystem.stat(target, signal) !== undefined
+    } catch {
+      signal?.throwIfAborted()
+      // TODO(root-marker-unavailable): preserve provider failure separately from
+      // absence and stop discovery; continuing upward can cross into an ancestor project.
+      return false
+    }
+  }
+  try {
+    signal?.throwIfAborted()
+    await stat(path)
+    signal?.throwIfAborted()
+    return true
+  } catch {
+    signal?.throwIfAborted()
+    return false
+  }
+}
+
+/**
+ * Walk upward to the first directory containing a configured root marker.
+ * @param cwd - absolute session working directory where the walk begins.
+ * @param markers - child names that identify a project root.
+ * @param fileSystem - optional provider used instead of host filesystem probes.
+ * @param signal - cancellation for provider and host probes.
+ * @returns the discovered project root, or `cwd` when no marker exists.
+ */
+export async function findProjectRoot(
+  cwd: string,
+  markers: readonly string[],
+  fileSystem?: FileSystem,
+  signal?: AbortSignal,
+): Promise<string> {
+  let current = resolve(cwd)
+  for (;;) {
+    for (const marker of markers) {
+      if (await existsAsMarker(join(current, marker), fileSystem, signal)) return current
+    }
+    const parent = dirname(current)
+    if (parent === current) return resolve(cwd)
+    current = parent
+  }
+}
+
+/**
+ * Build the inclusive root-to-cwd directory chain.
+ * @param root - root directory expected to contain or equal `cwd`.
+ * @param cwd - most-specific directory in the chain.
+ * @returns directories ordered from broadest to most specific.
+ */
+export function ancestorChain(root: string, cwd: string): string[] {
+  const chain: string[] = []
+  let current = resolve(cwd)
+  const resolvedRoot = resolve(root)
+  while (current !== resolvedRoot) {
+    chain.push(current)
+    const parent = dirname(current)
+    /* v8 ignore next -- discovery always supplies cwd or an ancestor root. */
+    if (parent === current) break
+    current = parent
+  }
+  chain.push(resolvedRoot)
+  return chain.reverse()
+}
+
+/**
+ * Find descendant directories crossed between a cwd and a touched file.
+ * @param root - session cwd that bounds nested discovery.
+ * @param touchedPath - absolute path or path relative to `root`.
+ * @returns descendant directories from shallowest through the touched file's parent.
+ */
+export function descendantDirsBetween(root: string, touchedPath: string): string[] {
+  const resolvedRoot = resolve(root)
+  const targetPath = isAbsolute(touchedPath) ? resolve(touchedPath) : resolve(resolvedRoot, touchedPath)
+  const targetDir = dirname(targetPath)
+  const rel = relative(resolvedRoot, targetDir)
+  if (rel.length === 0 || rel.startsWith('..') || isAbsolute(rel)) return []
+  return ancestorChain(resolvedRoot, targetDir).slice(1)
+}
+
+/**
+ * Convert an absolute instruction path to its project-root-relative display form.
+ * @param root - project root used as the display base.
+ * @param path - absolute path to display.
+ * @returns the root-relative path.
+ */
+export function relativeDisplay(root: string, path: string): string {
+  return relative(root, path)
+}
+
+async function firstExistingInstructionFile(
+  dir: string,
+  root: string,
+  instructionFileCandidates: readonly string[],
+  fileSystem?: FileSystem,
+  signal?: AbortSignal,
+): Promise<DiscoveredInstructionFile | undefined> {
+  for (const candidate of instructionFileCandidates) {
+    const path = join(dir, candidate)
+    const probe = await statFile(path, fileSystem, signal)
+    switch (probe.kind) {
+      case 'present':
+        return {
+          absolutePath: path,
+          displayPath: relativeDisplay(root, path),
+          ...probe.info,
+        }
+      case 'absent':
+        continue
+      case 'unavailable':
+        return undefined
+      /* v8 ignore next 2 -- StatFileProbe is closed; this arm only makes adding a kind a compile error. */
+      default:
+        return assertNever(probe, 'StatFileProbe')
+    }
+  }
+  return undefined
+}
+
+async function discoverInstructionFiles(
+  options: DiscoverOptions,
+  fileSystem?: FileSystem,
+): Promise<DiscoveredInstructionFile[]> {
+  const config = resolveDiscoveryConfig(options)
+  const files: DiscoveredInstructionFile[] = []
+  const seen = new Set<string>()
+  const addFile = (file: DiscoveredInstructionFile): void => {
+    if (seen.has(file.absolutePath)) return
+    seen.add(file.absolutePath)
+    files.push(file)
+  }
+
+  const userGlobal = join(config.dshHome, 'AGENTS.md')
+  const userGlobalProbe = await statFile(userGlobal, fileSystem, options.signal)
+  switch (userGlobalProbe.kind) {
+    case 'present':
+      addFile({
+        absolutePath: userGlobal,
+        displayPath: userGlobalDisplayPath(config.dshHome),
+        ...userGlobalProbe.info,
+      })
+      break
+    case 'absent':
+    case 'unavailable':
+      break
+    /* v8 ignore next 2 -- StatFileProbe is closed; this arm only makes adding a kind a compile error. */
+    default:
+      assertNever(userGlobalProbe, 'StatFileProbe')
+  }
+
+  const cwd = resolve(options.cwd)
+  const projectRoot = await findProjectRoot(cwd, config.projectRootMarkers, fileSystem, options.signal)
+  for (const dir of ancestorChain(projectRoot, cwd)) {
+    const file = await firstExistingInstructionFile(dir, projectRoot, config.instructionFileCandidates, fileSystem, options.signal)
+    if (file !== undefined) addFile(file)
+  }
+  return files
+}
+
+/**
+ * Discover host-visible user-global and root-to-cwd instruction candidates.
+ * @param options - cwd, home, root marker, and candidate configuration.
+ * @returns de-duplicated instruction paths in model precedence order.
+ */
+export async function discoverBaselineInstructionFiles(options: DiscoverOptions): Promise<InstructionFile[]> {
+  return (await discoverInstructionFiles(options)).map(({ absolutePath, displayPath }) => ({ absolutePath, displayPath }))
+}
+
+async function* nodeTextChunks(path: string, signal?: AbortSignal): AsyncIterable<string> {
+  const stream = createReadStream(path, { encoding: 'utf8', signal })
+  for await (const chunk of stream) yield String(chunk)
+}
+
+async function readBounded(
+  file: DiscoveredInstructionFile,
+  maxSourceBytes: number,
+  fileSystem?: FileSystem,
+  signal?: AbortSignal,
+): Promise<string | undefined> {
+  // TODO(total-instruction-read-bound): enforce an aggregate source budget
+  // across a complete baseline or reconciliation batch; the render budget is
+  // applied only after every accepted file has been read under this per-file cap.
+  signal?.throwIfAborted()
+  if (file.size !== undefined && file.size > maxSourceBytes) return undefined
+  try {
+    const chunks = fileSystem === undefined || file.target === undefined
+      ? nodeTextChunks(file.absolutePath, signal)
+      : await fileSystem.streamText(file.target, signal)
+    const parts: string[] = []
+    let bytes = 0
+    for await (const chunk of chunks) {
+      signal?.throwIfAborted()
+      bytes += Buffer.byteLength(chunk, 'utf8')
+      if (bytes > maxSourceBytes) return undefined
+      parts.push(chunk)
+    }
+    signal?.throwIfAborted()
+    return parts.join('')
+  } catch {
+    signal?.throwIfAborted()
+    // A file may disappear or become unreadable after its metadata probe.
+    return undefined
+  }
+}
+
+/**
+ * Discover, read, and render the baseline instruction chain.
+ * @param options - discovery, source-size, byte-budget, and cancellation configuration.
+ * @param fileSystem - optional provider used instead of host filesystem reads.
+ * @returns rendered baseline context, or undefined when nothing can be loaded.
+ */
+export async function loadBaselineInstructions(
+  options: LoadOptions,
+  fileSystem?: FileSystem,
+): Promise<RenderedWorkspaceContext | undefined> {
+  return (await loadBaselineInstructionSet(options, fileSystem))?.rendered
+}
+
+/**
+ * Load a baseline together with the files retained after rendering.
+ * @param options - discovery, source-size, byte-budget, and cancellation configuration.
+ * @param fileSystem - optional provider used instead of host filesystem reads.
+ * @returns rendered context and retained files, or undefined when empty or disabled.
+ */
+export async function loadBaselineInstructionSet(
+  options: LoadOptions,
+  fileSystem?: FileSystem,
+): Promise<RenderedInstructionSet | undefined> {
+  const config = resolveConfig(options)
+  if (config.maxBytes <= 0 || !Number.isFinite(config.maxBytes)) return undefined
+  if (config.maxSourceBytes <= 0 || !Number.isFinite(config.maxSourceBytes)) return undefined
+  const discovered = await discoverInstructionFiles(options, fileSystem)
+  const loaded: LoadedInstructionFile[] = []
+  for (const file of discovered) {
+    const content = await readBounded(file, config.maxSourceBytes, fileSystem, options.signal)
+    if (content !== undefined) {
+      loaded.push({
+        absolutePath: file.absolutePath,
+        displayPath: file.displayPath,
+        content,
+        ...file.version === undefined ? {} : { version: file.version },
+      })
+    }
+  }
+  if (loaded.length === 0) return undefined
+  const rendered = renderWorkspaceContext(loaded, { maxBytes: config.maxBytes })
+  const omitted = new Set(rendered.omitted.map(file => file.absolutePath))
+  return { rendered, included: loaded.filter(file => !omitted.has(file.absolutePath)) }
+}
+
+/**
+ * Probe the current first-winning instruction candidate for one logical scope.
+ * @param scope - `user-global`, `.`, or a project-relative directory.
+ * @param projectRoot - project root used to resolve and display project scopes.
+ * @param resolved - normalized plugin configuration.
+ * @param fileSystem - provider used for no-follow probing.
+ * @param signal - cancellation for provider probes.
+ * @returns present metadata, confirmed absence, or temporary unavailability.
+ */
+export async function probeScopeInstruction(
+  scope: string,
+  projectRoot: string,
+  resolved: ResolvedConfig,
+  fileSystem: FileSystem,
+  signal?: AbortSignal,
+): Promise<ScopeInstructionProbe> {
+  const dir = scope === 'user-global'
+    ? resolved.dshHome
+    : scope === '.' ? projectRoot : join(projectRoot, scope)
+  const candidates = scope === 'user-global' ? ['AGENTS.md'] : resolved.instructionFileCandidates
+  for (const candidate of candidates) {
+    const absolutePath = join(dir, candidate)
+    let pathInfo: FsPathInfo | undefined
+    try {
+      pathInfo = await fileSystem.lstat(absolutePath, undefined, signal)
+    } catch {
+      signal?.throwIfAborted()
+      return { kind: 'unavailable' }
+    }
+    if (pathInfo === undefined || pathInfo.type !== 'file') continue
+    let target: FsTarget
+    let info: FsInfo | undefined
+    try {
+      target = await fileSystem.resolve(absolutePath, signalOptions(signal))
+      info = await fileSystem.stat(target, signal)
+    } catch {
+      signal?.throwIfAborted()
+      return { kind: 'unavailable' }
+    }
+    if (info?.type !== 'file') return { kind: 'unavailable' }
+    const file: ProbedInstructionFile = {
+      absolutePath,
+      displayPath: scope === 'user-global' ? userGlobalDisplayPath(resolved.dshHome) : relativeDisplay(projectRoot, absolutePath),
+      target,
+      version: info.version,
+      ...info.size === undefined ? {} : { size: info.size },
+    }
+    return { kind: 'present', file }
+  }
+  return { kind: 'absent' }
+}
+
+/**
+ * Read one already-probed scope candidate under the configured source cap.
+ * @param file - winning provider candidate and its metadata snapshot.
+ * @param maxSourceBytes - maximum UTF-8 bytes accepted from the source.
+ * @param fileSystem - provider used for the streaming read.
+ * @param signal - cancellation for provider streaming.
+ * @returns loaded content with the probed version, or undefined when unavailable.
+ */
+export async function readScopeInstruction(
+  file: ProbedInstructionFile,
+  maxSourceBytes: number,
+  fileSystem: FileSystem,
+  signal?: AbortSignal,
+): Promise<LoadedInstructionFile | undefined> {
+  const content = await readBounded(file, maxSourceBytes, fileSystem, signal)
+  if (content === undefined) return undefined
+  return {
+    absolutePath: file.absolutePath,
+    displayPath: file.displayPath,
+    content,
+    version: file.version,
+  }
+}
+
+function userGlobalDisplayPath(dshHome: string): string {
+  return dshHome === resolve(defaultDshHome()) ? `${DEFAULT_DSH_HOME_DISPLAY}/AGENTS.md` : '$DSH_HOME/AGENTS.md'
+}

packages/context/workspace-context/src/index.ts

@@ -0,0 +1,173 @@
+/**
+ * Workspace instruction loader for AGENTS.md-compatible files.
+ *
+ * Baseline instructions are frozen into `agent/session-prefix`; successful fs
+ * tool touches reconcile nested, changed, and removed instructions through
+ * `tools/post-execute` for the next model request. Plugin lifecycle reads use
+ * the optional `ctx.fs` provider, so providerless products mount it as a no-op.
+ *
+ * @module @deepseek-ai/dsh-workspace-context
+ */
+
+import type { Context } from 'cordis'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import type { Message } from '@deepseek-ai/dsh-llm'
+import type { PostToolDecision, ToolExecution, ToolExecutionResult, ToolExecutionToken } from '@deepseek-ai/dsh-tools'
+import { Config, resolveConfig, type ResolvedConfig } from './config.ts'
+import { loadBaselineInstructionSet } from './files.ts'
+import {
+  applyInstructionVersionUpdates,
+  baselineInstructionState,
+  commitPendingInstructionContexts,
+  dynamicInstructionContext,
+  name,
+  observeInstructionSessionEvent,
+  reconcileInstructionContext,
+  retainedInstructionVersionUpdates,
+  rollbackPendingInstructionChanges,
+  workspaceContextMessage,
+  type InstructionVersionCache,
+  type InstructionVersionUpdate,
+  type PendingInstructionChange,
+} from './state.ts'
+import type { WorkspaceInstructionChange } from './render.ts'
+
+export { Config, name }
+export {
+  discoverBaselineInstructionFiles,
+  loadBaselineInstructions,
+} from './files.ts'
+export type {
+  InstructionFile,
+  LoadedInstructionFile,
+} from './files.ts'
+export { renderWorkspaceContext } from './render.ts'
+export type { RenderedWorkspaceContext, TruncatedInstruction } from './render.ts'
+
+export function apply(ctx: Context, config: Config): void {
+  const resolved: ResolvedConfig = resolveConfig(config)
+  const pendingNestedChanges = new WeakMap<object, Map<string, PendingInstructionChange>>()
+  const baselineInstructionStates = new WeakMap<object, Map<string, WorkspaceInstructionChange>>()
+  const instructionVersions: InstructionVersionCache = new WeakMap()
+  const pendingVersionUpdates = new Map<ToolExecutionToken, InstructionVersionUpdate[]>()
+  const pendingByParent = new Map<ToolExecutionToken, {
+    agent: Agent
+    changes: WorkspaceInstructionChange[]
+    versionUpdates: InstructionVersionUpdate[]
+  }>()
+
+  ctx.on('session/event', (session, event) => {
+    observeInstructionSessionEvent(session, event, pendingNestedChanges, instructionVersions)
+  })
+
+  ctx.on('agent/session-prefix', async (agent: Agent, _prefix, signal, next): Promise<Message[]> => {
+    const rest = await next()
+    if (resolved.maxBytes <= 0 || !Number.isFinite(resolved.maxBytes)) return rest
+    const fileSystem = ctx.get('fs')
+    if (fileSystem === undefined) return rest
+    /* v8 ignore next -- normal agents carry an absolute session cwd. */
+    const cwd = agent.session.header.cwd ?? process.cwd()
+    const instructions = await loadBaselineInstructionSet({
+      cwd,
+      dshHome: resolved.dshHome,
+      projectRootMarkers: resolved.projectRootMarkers,
+      maxBytes: resolved.maxBytes,
+      maxSourceBytes: resolved.maxSourceBytes,
+      instructionFileCandidates: resolved.instructionFileCandidates,
+      signal,
+    }, fileSystem)
+    const baseline = baselineInstructionState(instructions?.included ?? [])
+    baselineInstructionStates.set(agent.session, baseline.changes)
+    instructionVersions.set(agent.session, baseline.versions)
+
+    const update = await reconcileInstructionContext(
+      agent,
+      resolved,
+      pendingNestedChanges,
+      baselineInstructionStates,
+      instructionVersions,
+      fileSystem,
+      { includeBaselineScopes: false, signal },
+    )
+    if (update !== undefined) {
+      agent.inject(update.context.content, {
+        source: update.context.source,
+        envelope: update.context.envelope,
+        meta: update.context.meta,
+      })
+      applyInstructionVersionUpdates(agent.session, update.versionUpdates, instructionVersions)
+    }
+    if (instructions === undefined || instructions.rendered.text.length === 0) return rest
+    return [workspaceContextMessage(instructions.rendered.text), ...rest]
+  })
+
+  ctx.on('tools/post-execute', async (
+    exec: ToolExecution,
+    result: ToolExecutionResult,
+    next,
+  ): Promise<PostToolDecision> => {
+    const downstream = await next()
+    // A downstream listener/policy blocked this call: the registry turns it
+    // into a final `isError` result, so treat it like a failed fs touch and
+    // load nothing. Reconciling here would surface workspace instructions from
+    // a call the pipeline rejected, violating the "successful fs tool touches"
+    // contract, and would advance the nested/baseline tracking state off a
+    // touch that never really happened.
+    if (downstream.kind === 'block') return downstream
+    const fileSystem = ctx.get('fs')
+    if (fileSystem === undefined) return downstream
+    const update = await dynamicInstructionContext(
+      exec.agent,
+      exec,
+      result,
+      resolved,
+      pendingNestedChanges,
+      baselineInstructionStates,
+      instructionVersions,
+      fileSystem,
+    )
+    if (update === undefined) return downstream
+    pendingVersionUpdates.set(exec.token, update.versionUpdates)
+    return {
+      kind: 'accept',
+      ...downstream.content !== undefined ? { content: downstream.content } : {},
+      additionalContexts: [update.context, ...downstream.additionalContexts ?? []],
+    }
+  })
+
+  ctx.on('tools/result', (exec: ToolExecution, result: ToolExecutionResult) => {
+    const ownVersionUpdates = pendingVersionUpdates.get(exec.token) ?? []
+    pendingVersionUpdates.delete(exec.token)
+    if (exec.parent !== undefined) {
+      if (exec.agent === undefined) return
+      // Child contexts participate in duplicate suppression within one composite
+      // run, but remain provisional until the parent reaches its final policy.
+      const changes = commitPendingInstructionContexts(exec.agent, result.additionalContexts, pendingNestedChanges)
+      if (changes.length === 0) return
+      const versionUpdates = retainedInstructionVersionUpdates(ownVersionUpdates, changes)
+      const staged = pendingByParent.get(exec.parent)
+      if (staged === undefined) pendingByParent.set(exec.parent, { agent: exec.agent, changes, versionUpdates })
+      else {
+        staged.changes.push(...changes)
+        staged.versionUpdates.push(...versionUpdates)
+      }
+      return
+    }
+
+    // The parent result is authoritative: remove every provisional child change,
+    // then commit only contexts that survived outer post-execute policy.
+    const staged = pendingByParent.get(exec.token)
+    if (staged !== undefined) {
+      pendingByParent.delete(exec.token)
+      rollbackPendingInstructionChanges(staged.agent, staged.changes, pendingNestedChanges)
+    }
+    if (exec.agent === undefined) return
+    const committed = commitPendingInstructionContexts(exec.agent, result.additionalContexts, pendingNestedChanges)
+    const stagedVersionUpdates = staged?.versionUpdates ?? []
+    const versionUpdates = retainedInstructionVersionUpdates(
+      [...stagedVersionUpdates, ...ownVersionUpdates],
+      committed,
+    )
+    applyInstructionVersionUpdates(exec.agent.session, versionUpdates, instructionVersions)
+  })
+}

packages/context/workspace-context/src/render.ts

@@ -0,0 +1,255 @@
+/**
+ * Model-facing workspace instruction rendering within an explicit byte budget.
+ *
+ * @module @deepseek-ai/dsh-workspace-context/render
+ */
+
+import { dirname } from 'node:path'
+import type { InstructionFile, LoadedInstructionFile } from './files.ts'
+
+const SYSTEM_REMINDER_OPEN = '<system-reminder>'
+const SYSTEM_REMINDER_CLOSE = '</system-reminder>'
+const WORKSPACE_CONTEXT_INTRO = 'The following workspace instructions may be relevant to your work. '
+  + 'Use them as guidance when applicable. More specific instructions take precedence over broader ones. '
+  + 'They do not override system, developer, or direct user instructions.'
+const COMPACT_WORKSPACE_CONTEXT_INTRO = 'Workspace instructions were omitted or truncated to fit the configured byte budget.'
+
+/** Byte-accounting record for one truncated instruction file. */
+export interface TruncatedInstruction {
+  displayPath: string
+  originalBytes: number
+  includedBytes: number
+}
+
+/** Model-facing text plus omitted and truncated source records. */
+export interface RenderedWorkspaceContext {
+  text: string
+  omitted: InstructionFile[]
+  truncated: TruncatedInstruction[]
+}
+
+/** Structured dynamic state persisted outside model-visible prompt prose. */
+export interface WorkspaceInstructionChange {
+  action: 'set' | 'replace' | 'remove'
+  scope: string
+  path: string
+  previousPath?: string
+  digest?: string
+}
+
+/** One state transition paired with the content used to render it. */
+export interface ChangeRenderItem {
+  change: WorkspaceInstructionChange
+  file: LoadedInstructionFile
+}
+
+interface RenderStyle {
+  intro: string
+  section(file: LoadedInstructionFile): string
+}
+
+function byteLength(value: string): number {
+  return Buffer.byteLength(value, 'utf8')
+}
+
+function truncateUtf8(value: string, maxBytes: number): string {
+  let truncated = Buffer.from(value, 'utf8').subarray(0, Math.max(0, maxBytes)).toString('utf8')
+  while (byteLength(truncated) > maxBytes) {
+    truncated = truncated.slice(0, -1)
+  }
+  return truncated
+}
+
+function escapeInstructionContent(content: string): string {
+  // TODO(instruction-frame-paths): apply the same delimiter neutralization to
+  // every interpolated path, scope, and previous path; repository-controlled
+  // names can otherwise close the plugin-owned system-reminder frame.
+  return content.replaceAll(SYSTEM_REMINDER_CLOSE, '<\\/system-reminder>')
+}
+
+function sectionText(file: LoadedInstructionFile): string {
+  return `Instructions from: ${file.displayPath}\n\n${escapeInstructionContent(file.content)}`
+}
+
+/**
+ * Derive the logical instruction scope from a model-facing path.
+ * @param displayPath - project-relative or user-global instruction path.
+ * @returns `user-global`, `.`, or the containing project-relative directory.
+ */
+export function scopeForDisplayPath(displayPath: string): string {
+  if (displayPath === '~/.dsh/AGENTS.md' || displayPath === '$DSH_HOME/AGENTS.md') return 'user-global'
+  return dirname(displayPath)
+}
+
+function additionalSectionText(file: LoadedInstructionFile): string {
+  const scope = scopeForDisplayPath(file.displayPath)
+  return [
+    `Additional instructions from: ${file.displayPath}`,
+    '',
+    `These instructions apply to work under \`${scope}\`. Use them as guidance when relevant; more specific instructions take precedence. They do not override system, developer, or direct user instructions.`,
+    '',
+    escapeInstructionContent(file.content),
+  ].join('\n')
+}
+
+const BASELINE_RENDER_STYLE: RenderStyle = { intro: WORKSPACE_CONTEXT_INTRO, section: sectionText }
+
+function changedSectionText(item: ChangeRenderItem): string {
+  const { change, file } = item
+  if (change.action === 'set') return additionalSectionText(file)
+  if (change.action === 'remove') {
+    return `Instructions removed: ${change.path}\n\nThe previously loaded instructions from this file no longer apply.`
+  }
+  const description = change.previousPath === undefined
+    ? 'This file changed after it was loaded. Use the following content instead of the previously loaded instructions from this file.'
+    : `The instructions previously loaded from \`${change.previousPath}\` no longer apply. Use the following content for \`${change.scope}\` instead.`
+  return [
+    `Updated instructions from: ${change.path}`,
+    '',
+    description,
+    '',
+    escapeInstructionContent(file.content),
+  ].join('\n')
+}
+
+/**
+ * Render one reconciliation batch and retain only transitions that fit.
+ * @param items - ordered state transitions and current file contents.
+ * @param maxBytes - maximum UTF-8 bytes allowed in the rendered batch.
+ * @returns bounded prompt text and the transitions actually represented by it.
+ */
+export function renderInstructionChanges(
+  items: ChangeRenderItem[],
+  maxBytes: number,
+): { text: string; changes: WorkspaceInstructionChange[] } {
+  const byAbsolutePath = new Map(items.map(item => [item.file.absolutePath, item]))
+  const style: RenderStyle = {
+    intro: '',
+    section(file) {
+      const item = byAbsolutePath.get(file.absolutePath)
+      /* v8 ignore next -- the renderer receives exactly the files used to construct this map. */
+      return item === undefined ? '' : changedSectionText({ ...item, file })
+    },
+  }
+  const rendered = renderInstructionContext(items.map(item => item.file), maxBytes, style)
+  const omitted = new Set(rendered.omitted.map(file => file.absolutePath))
+  return {
+    text: rendered.text,
+    // TODO(rendered-change-proof): retain a transition only when its semantic
+    // notice survived rendering; a tiny compact budget can currently return
+    // unrelated notice text while still committing the full state transition.
+    changes: items.filter(item => !omitted.has(item.file.absolutePath)).map(item => item.change),
+  }
+}
+
+function markerText(maxBytes: number, omitted: InstructionFile[], truncated: TruncatedInstruction[]): string {
+  if (omitted.length === 0 && truncated.length === 0) return ''
+  const parts: string[] = []
+  if (omitted.length > 0) {
+    parts.push(`omitted ${omitted.map(file => file.displayPath).join(', ')}`)
+  }
+  if (truncated.length > 0) {
+    parts.push(`truncated ${truncated.map(item => `${item.displayPath} from ${item.originalBytes} to ${item.includedBytes} bytes`).join(', ')}`)
+  }
+  return `Workspace instruction budget ${maxBytes} bytes: ${parts.join('; ')}`
+}
+
+function buildInstructionText(
+  files: LoadedInstructionFile[],
+  maxBytes: number,
+  omitted: InstructionFile[],
+  truncated: TruncatedInstruction[],
+  style: RenderStyle,
+): string {
+  const marker = markerText(maxBytes, omitted, truncated)
+  const body = [marker, style.intro, ...files.map(file => style.section(file))].filter(block => block.length > 0)
+  return [SYSTEM_REMINDER_OPEN, body.join('\n\n'), SYSTEM_REMINDER_CLOSE].join('\n')
+}
+
+function withTruncatedContent(file: LoadedInstructionFile, includedBytes: number): LoadedInstructionFile {
+  return { ...file, content: truncateUtf8(file.content, includedBytes) }
+}
+
+function truncateToFit(
+  file: LoadedInstructionFile,
+  includedFiles: LoadedInstructionFile[],
+  maxBytes: number,
+  omitted: InstructionFile[],
+  style: RenderStyle,
+): LoadedInstructionFile {
+  const originalBytes = byteLength(file.content)
+  let low = 0
+  let high = originalBytes
+  let best = withTruncatedContent(file, 0)
+  while (low <= high) {
+    const mid = Math.floor((low + high) / 2)
+    const candidate = withTruncatedContent(file, mid)
+    const truncated = [{ displayPath: file.displayPath, originalBytes, includedBytes: byteLength(candidate.content) }]
+    const text = buildInstructionText([...includedFiles, candidate], maxBytes, omitted, truncated, style)
+    if (byteLength(text) <= maxBytes) {
+      best = candidate
+      low = mid + 1
+    } else {
+      high = mid - 1
+    }
+  }
+  return best
+}
+
+function renderInstructionContext(
+  files: LoadedInstructionFile[],
+  maxBytes: number,
+  style: RenderStyle,
+): RenderedWorkspaceContext {
+  if (maxBytes <= 0 || !Number.isFinite(maxBytes)) return { text: '', omitted: files, truncated: [] }
+
+  const fullText = buildInstructionText(files, maxBytes, [], [], style)
+  if (byteLength(fullText) <= maxBytes) return { text: fullText, omitted: [], truncated: [] }
+
+  for (let start = 1; start < files.length; start += 1) {
+    const included = files.slice(start)
+    const omitted = files.slice(0, start).map(file => ({ absolutePath: file.absolutePath, displayPath: file.displayPath }))
+    const suffixText = buildInstructionText(included, maxBytes, omitted, [], style)
+    if (byteLength(suffixText) <= maxBytes) return { text: suffixText, omitted, truncated: [] }
+  }
+
+  const mostSpecific = files.at(-1)
+  /* v8 ignore next -- callers only reach this after a non-empty fullText was built. */
+  if (mostSpecific === undefined) return { text: '', omitted: [], truncated: [] }
+  const omitted = files.slice(0, -1).map(file => ({ absolutePath: file.absolutePath, displayPath: file.displayPath }))
+
+  for (const candidateStyle of [style, { ...style, intro: COMPACT_WORKSPACE_CONTEXT_INTRO }]) {
+    const truncatedFile = truncateToFit(mostSpecific, [], maxBytes, omitted, candidateStyle)
+    const truncated = [{
+      displayPath: mostSpecific.displayPath,
+      originalBytes: byteLength(mostSpecific.content),
+      includedBytes: byteLength(truncatedFile.content),
+    }]
+    const text = buildInstructionText([truncatedFile], maxBytes, omitted, truncated, candidateStyle)
+    if (byteLength(text) <= maxBytes) return { text, omitted, truncated }
+  }
+
+  const truncated = [{
+    displayPath: mostSpecific.displayPath,
+    originalBytes: byteLength(mostSpecific.content),
+    includedBytes: 0,
+  }]
+  const compactNotice = markerText(maxBytes, omitted, truncated)
+  const compactWithHeading = [compactNotice, style.section(withTruncatedContent(mostSpecific, 0))].join('\n\n')
+  if (byteLength(compactWithHeading) <= maxBytes) return { text: compactWithHeading, omitted, truncated }
+  const text = byteLength(compactNotice) <= maxBytes ? compactNotice : truncateUtf8(compactNotice, maxBytes)
+  return { text, omitted, truncated }
+}
+
+/**
+ * Render the baseline instruction chain with deterministic precedence budgeting.
+ * @param files - loaded files ordered from broadest to most specific.
+ * @param options - required rendering byte budget.
+ * @returns bounded baseline prompt text and budget diagnostics.
+ */
+export function renderWorkspaceContext(
+  files: LoadedInstructionFile[],
+  options: { maxBytes: number },
+): RenderedWorkspaceContext {
+  return renderInstructionContext(files, options.maxBytes, BASELINE_RENDER_STYLE)
+}

packages/context/workspace-context/src/state.ts

@@ -0,0 +1,507 @@
+/**
+ * Session-visible workspace instruction state and dynamic reconciliation.
+ *
+ * @module @deepseek-ai/dsh-workspace-context/state
+ */
+
+import type { Agent, HookContext } from '@deepseek-ai/dsh-agent'
+import type { Message } from '@deepseek-ai/dsh-llm'
+import type { JsonValue, Session, SessionEvent } from '@deepseek-ai/dsh-session'
+import type { FileSystem, FsVersion } from '@deepseek-ai/dsh-fs'
+import type { ToolExecution, ToolExecutionResult } from '@deepseek-ai/dsh-tools'
+import type { ResolvedConfig } from './config.ts'
+import { instructionContentSha1 } from './digest.ts'
+import {
+  ancestorChain,
+  descendantDirsBetween,
+  findProjectRoot,
+  probeScopeInstruction,
+  readScopeInstruction,
+  relativeDisplay,
+  type LoadedInstructionFile,
+} from './files.ts'
+import {
+  renderInstructionChanges,
+  scopeForDisplayPath,
+  type ChangeRenderItem,
+  type WorkspaceInstructionChange,
+} from './render.ts'
+
+export const name = 'workspace-context'
+
+const PLUGIN_SOURCE = { kind: 'plugin', plugin: name } as const
+const FILE_TOUCH_TOOL_NAMES = new Set(['read', 'write', 'edit'])
+
+/** Dynamic state waiting for the loop to append its returned context event. */
+export interface PendingInstructionChange {
+  change: WorkspaceInstructionChange
+  afterSeq: number
+  step?: { turn: number; step: number }
+}
+
+/** Per-scope metadata cache; instruction prose is deliberately not retained. */
+export interface InstructionVersionState {
+  path: string
+  version: FsVersion
+  digest: string
+}
+
+/** Session-isolated fast-path state keyed by logical instruction scope. */
+export type InstructionVersionCache = WeakMap<Session, Map<string, InstructionVersionState>>
+
+/** A cache transition coupled to the model-visible change that authorizes it. */
+export interface InstructionVersionUpdate {
+  change: WorkspaceInstructionChange
+  state?: InstructionVersionState
+}
+
+/** Rendered reconciliation plus cache transitions awaiting final policy. */
+export interface ReconciledInstructionContext {
+  context: WorkspaceHookContext
+  versionUpdates: InstructionVersionUpdate[]
+}
+
+/** Plugin-owned raw context with required replay metadata. */
+export interface WorkspaceHookContext extends HookContext {
+  envelope: 'raw'
+  meta: JsonValue
+}
+
+function workspaceContextHook(text: string, changes: WorkspaceInstructionChange[]): WorkspaceHookContext {
+  const serializedChanges: JsonValue[] = changes.map(change => ({
+    action: change.action,
+    scope: change.scope,
+    path: change.path,
+    ...change.previousPath !== undefined ? { previousPath: change.previousPath } : {},
+    ...change.digest !== undefined ? { digest: change.digest } : {},
+  }))
+  const meta: JsonValue = { kind: 'workspace-instructions', version: 1, changes: serializedChanges }
+  return { content: [{ type: 'text', text }], source: PLUGIN_SOURCE, envelope: 'raw', meta }
+}
+
+/**
+ * Build the request-prefix message for a rendered baseline.
+ * @param text - complete plugin-owned system-reminder text.
+ * @returns a user-role prefix message.
+ */
+export function workspaceContextMessage(text: string): Message {
+  return { role: 'user', content: [{ type: 'text', text }] }
+}
+
+function filePathFromExecution(exec: ToolExecution): string | undefined {
+  if (!FILE_TOUCH_TOOL_NAMES.has(exec.name)) return undefined
+  if (typeof exec.arguments !== 'object' || exec.arguments === null) return undefined
+  if (!('file_path' in exec.arguments) || typeof exec.arguments.file_path !== 'string') return undefined
+  const filePath = exec.arguments.file_path.trim()
+  return filePath.length > 0 ? filePath : undefined
+}
+
+function isWorkspaceContextSource(source: unknown): source is typeof PLUGIN_SOURCE {
+  return typeof source === 'object' && source !== null
+    && 'kind' in source && source.kind === 'plugin'
+    && 'plugin' in source && source.plugin === name
+}
+
+function isRecord(value: JsonValue | undefined): value is { [key: string]: JsonValue } {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function workspaceInstructionChanges(meta: JsonValue | undefined): WorkspaceInstructionChange[] {
+  if (!isRecord(meta) || meta.kind !== 'workspace-instructions' || meta.version !== 1 || !Array.isArray(meta.changes)) return []
+  const changes: WorkspaceInstructionChange[] = []
+  for (const value of meta.changes) {
+    if (!isRecord(value)) continue
+    if (value.action !== 'set' && value.action !== 'replace' && value.action !== 'remove') continue
+    if (typeof value.scope !== 'string' || typeof value.path !== 'string') continue
+    if (value.previousPath !== undefined && typeof value.previousPath !== 'string') continue
+    if (value.digest !== undefined && typeof value.digest !== 'string') continue
+    changes.push({
+      action: value.action,
+      scope: value.scope,
+      path: value.path,
+      ...value.previousPath !== undefined ? { previousPath: value.previousPath } : {},
+      ...value.digest !== undefined ? { digest: value.digest } : {},
+    })
+  }
+  return changes
+}
+
+function sameInstructionChange(a: WorkspaceInstructionChange, b: WorkspaceInstructionChange): boolean {
+  return a.action === b.action
+    && a.scope === b.scope
+    && a.path === b.path
+    && a.previousPath === b.previousPath
+    && a.digest === b.digest
+}
+
+function visibleInstructionChanges(
+  agent: Agent,
+  pending: Map<string, PendingInstructionChange>,
+): Map<string, WorkspaceInstructionChange> {
+  const visibleSeqs = new Set(agent.session.surface.nodes.map(node => node.seq))
+  const visible = new Map<string, WorkspaceInstructionChange>()
+  for (const [seq, event] of agent.session.events.entries()) {
+    if (event.type !== 'context/message' || !isWorkspaceContextSource(event.data.source)) continue
+    const changes = workspaceInstructionChanges(event.data.meta)
+    for (const change of changes) {
+      const waiting = pending.get(change.scope)
+      if (waiting !== undefined && seq >= waiting.afterSeq && sameInstructionChange(waiting.change, change)) {
+        pending.delete(change.scope)
+      }
+      if (visibleSeqs.has(seq)) visible.set(change.scope, change)
+    }
+  }
+  for (const { change } of pending.values()) visible.set(change.scope, change)
+  return visible
+}
+
+/**
+ * Convert retained baseline files into comparison and metadata-cache state.
+ * @param files - baseline files that survived rendering.
+ * @returns latest baseline changes and provider versions keyed by logical scope.
+ */
+export function baselineInstructionState(files: LoadedInstructionFile[]): {
+  changes: Map<string, WorkspaceInstructionChange>
+  versions: Map<string, InstructionVersionState>
+} {
+  const changes = new Map<string, WorkspaceInstructionChange>()
+  const versions = new Map<string, InstructionVersionState>()
+  for (const file of files) {
+    const digest = instructionContentSha1(file.content)
+    const change: WorkspaceInstructionChange = {
+      action: 'set',
+      scope: scopeForDisplayPath(file.displayPath),
+      path: file.displayPath,
+      digest,
+    }
+    changes.set(change.scope, change)
+    if (file.version !== undefined) {
+      versions.set(change.scope, { path: file.displayPath, version: file.version, digest })
+    }
+  }
+  return { changes, versions }
+}
+
+function versionStatesFor(session: Session, cache: InstructionVersionCache): Map<string, InstructionVersionState> {
+  let states = cache.get(session)
+  if (states === undefined) {
+    states = new Map()
+    cache.set(session, states)
+  }
+  return states
+}
+
+/**
+ * Keep only cache updates whose model-visible changes survived final policy.
+ * @param updates - proposed updates from one or more reconciliations.
+ * @param committedChanges - transitions retained on the authoritative result.
+ * @returns updates authorized by an exact retained transition.
+ */
+export function retainedInstructionVersionUpdates(
+  updates: readonly InstructionVersionUpdate[],
+  committedChanges: readonly WorkspaceInstructionChange[],
+): InstructionVersionUpdate[] {
+  return updates.filter(update => committedChanges.some(change => sameInstructionChange(update.change, change)))
+}
+
+/**
+ * Apply authorized metadata-cache transitions without retaining instruction prose.
+ * @param session - owning session.
+ * @param updates - ordered set/delete transitions.
+ * @param cache - session-isolated metadata cache.
+ */
+export function applyInstructionVersionUpdates(
+  session: Session,
+  updates: readonly InstructionVersionUpdate[],
+  cache: InstructionVersionCache,
+): void {
+  if (updates.length === 0) return
+  const states = versionStatesFor(session, cache)
+  for (const update of updates) {
+    if (update.state === undefined) states.delete(update.change.scope)
+    else states.set(update.change.scope, update.state)
+  }
+  if (states.size === 0) cache.delete(session)
+}
+
+function pendingChangesFor(
+  session: object,
+  pendingBySession: WeakMap<object, Map<string, PendingInstructionChange>>,
+): Map<string, PendingInstructionChange> {
+  let pending = pendingBySession.get(session)
+  if (pending === undefined) {
+    pending = new Map()
+    pendingBySession.set(session, pending)
+  }
+  return pending
+}
+
+function openStep(session: Session): { turn: number; step: number } | undefined {
+  const boundary = session.events.findLast(event => event.type === 'step/start' || event.type === 'step/end')
+  return boundary?.type === 'step/start' ? boundary.data : undefined
+}
+
+function invalidateInstructionVersions(
+  session: Session,
+  scopes: readonly string[],
+  cache: InstructionVersionCache,
+): void {
+  const states = cache.get(session)
+  if (states === undefined) return
+  for (const scope of scopes) states.delete(scope)
+  if (states.size === 0) cache.delete(session)
+}
+
+/**
+ * Settle provisional tool-result state against durable session events.
+ * A matching context event confirms the transition. If its owning step closes
+ * first, the loop discarded its context buffer, so both duplicate suppression
+ * and the metadata fast path must be re-armed for the next successful touch.
+ * @param session - session whose append-only log emitted `event`.
+ * @param event - newly committed session event.
+ * @param pendingBySession - provisional transitions awaiting log confirmation.
+ * @param versionCache - metadata fast path coupled to those transitions.
+ */
+export function observeInstructionSessionEvent(
+  session: Session,
+  event: SessionEvent,
+  pendingBySession: WeakMap<object, Map<string, PendingInstructionChange>>,
+  versionCache: InstructionVersionCache,
+): void {
+  const pending = pendingBySession.get(session)
+  if (pending === undefined) return
+
+  switch (event.type) {
+    case 'context/message': {
+      if (!isWorkspaceContextSource(event.data.source)) return
+      for (const change of workspaceInstructionChanges(event.data.meta)) {
+        const waiting = pending.get(change.scope)
+        if (waiting !== undefined && event.seq >= waiting.afterSeq && sameInstructionChange(waiting.change, change)) {
+          pending.delete(change.scope)
+        }
+      }
+      if (pending.size === 0) pendingBySession.delete(session)
+      return
+    }
+    case 'step/end': {
+      const discardedScopes: string[] = []
+      for (const [scope, waiting] of pending) {
+        const step = waiting.step
+        if (step === undefined || step.turn !== event.data.turn || step.step !== event.data.step) continue
+        pending.delete(scope)
+        discardedScopes.push(scope)
+      }
+      if (pending.size === 0) pendingBySession.delete(session)
+      invalidateInstructionVersions(session, discardedScopes, versionCache)
+      return
+    }
+    default:
+      // SessionEventMap is merge-extensible; unrelated events do not settle workspace state.
+      return
+  }
+}
+
+/**
+ * Commit only workspace contexts that survived the complete tool pipeline.
+ * The observe-only `tools/result` notification calls this before the loop can
+ * append the returned contexts, closing that short pending window without
+ * trusting an intermediate post-execute decision.
+ * @param agent - session that will receive the final result contexts.
+ * @param contexts - immutable contexts on the authoritative top-level result.
+ * @param pendingBySession - per-session pending transition maps.
+ * @returns transitions committed into the short pending window.
+ */
+export function commitPendingInstructionContexts(
+  agent: Agent,
+  contexts: readonly HookContext[] | undefined,
+  pendingBySession: WeakMap<object, Map<string, PendingInstructionChange>>,
+): WorkspaceInstructionChange[] {
+  const committed: WorkspaceInstructionChange[] = []
+  const step = openStep(agent.session)
+  for (const context of contexts ?? []) {
+    if (!isWorkspaceContextSource(context.source)) continue
+    const changes = workspaceInstructionChanges(context.meta)
+    if (changes.length === 0) continue
+    const pending = pendingChangesFor(agent.session, pendingBySession)
+    for (const change of changes) {
+      pending.set(change.scope, {
+        change,
+        afterSeq: agent.session.seq,
+        ...step === undefined ? {} : { step },
+      })
+      committed.push(change)
+    }
+  }
+  return committed
+}
+
+/**
+ * Roll back parent-token state when an enclosing tool result discards deferred
+ * contexts. A newer transition for the same scope is left intact.
+ * @param agent - session whose pending state was staged.
+ * @param changes - exact staged transitions to remove when still current.
+ * @param pendingBySession - per-session pending transition maps.
+ */
+export function rollbackPendingInstructionChanges(
+  agent: Agent,
+  changes: readonly WorkspaceInstructionChange[],
+  pendingBySession: WeakMap<object, Map<string, PendingInstructionChange>>,
+): void {
+  const pending = pendingBySession.get(agent.session)
+  if (pending === undefined) return
+  for (const change of changes) {
+    const current = pending.get(change.scope)
+    if (current !== undefined && sameInstructionChange(current.change, change)) pending.delete(change.scope)
+  }
+  if (pending.size === 0) pendingBySession.delete(agent.session)
+}
+
+function relativeScope(projectRoot: string, dir: string): string {
+  const scope = relativeDisplay(projectRoot, dir)
+  return scope.length === 0 ? '.' : scope
+}
+
+/**
+ * Compare visible/pending state with provider-visible files and render transitions.
+ * @param agent - session owner whose visible surface supplies durable state.
+ * @param resolved - normalized plugin configuration.
+ * @param pendingBySession - short pending window before returned context is logged.
+ * @param baselineBySession - frozen baseline comparison state per session.
+ * @param versionCache - per-session scope metadata used to skip unchanged reads.
+ * @param fileSystem - provider used for current file probes.
+ * @param options - touched path and whether baseline scopes should be checked.
+ * @returns rendered context plus deferred cache updates, or undefined when unchanged/unavailable.
+ */
+export async function reconcileInstructionContext(
+  agent: Agent,
+  resolved: ResolvedConfig,
+  pendingBySession: WeakMap<object, Map<string, PendingInstructionChange>>,
+  baselineBySession: WeakMap<object, Map<string, WorkspaceInstructionChange>>,
+  versionCache: InstructionVersionCache,
+  fileSystem: FileSystem,
+  options: { touchedPath?: string; includeBaselineScopes: boolean; signal?: AbortSignal },
+): Promise<ReconciledInstructionContext | undefined> {
+  const session = agent.session
+  const pending = pendingChangesFor(session, pendingBySession)
+  const visible = visibleInstructionChanges(agent, pending)
+  const effective = new Map(baselineBySession.get(session) ?? [])
+  for (const [scope, change] of visible) effective.set(scope, change)
+  /* v8 ignore next -- normal agents carry an absolute session cwd. */
+  const cwd = session.header.cwd ?? process.cwd()
+  // TODO(frozen-project-root): retain the baseline root for the loop instance;
+  // recomputing it after marker edits reinterprets the existing relative scope keys.
+  const projectRoot = await findProjectRoot(cwd, resolved.projectRootMarkers, fileSystem, options.signal)
+  const scopes = new Set<string>()
+  if (options.includeBaselineScopes) {
+    scopes.add('user-global')
+    for (const dir of ancestorChain(projectRoot, cwd)) scopes.add(relativeScope(projectRoot, dir))
+  }
+  for (const scope of effective.keys()) scopes.add(scope)
+  if (options.touchedPath !== undefined) {
+    for (const dir of descendantDirsBetween(cwd, options.touchedPath)) scopes.add(relativeScope(projectRoot, dir))
+  }
+
+  const versions = versionStatesFor(session, versionCache)
+  const seenAbsolutePaths = new Set<string>()
+  const items: ChangeRenderItem[] = []
+  const versionUpdates: InstructionVersionUpdate[] = []
+  for (const scope of scopes) {
+    const previous = effective.get(scope)
+    const probe = await probeScopeInstruction(scope, projectRoot, resolved, fileSystem, options.signal)
+    if (probe.kind === 'unavailable') continue
+    if (probe.kind === 'absent') {
+      if (previous === undefined || previous.action === 'remove') {
+        versions.delete(scope)
+        continue
+      }
+      const change: WorkspaceInstructionChange = { action: 'remove', scope, path: previous.path }
+      items.push({
+        change,
+        file: { absolutePath: `removed:${scope}`, displayPath: previous.path, content: '' },
+      })
+      versionUpdates.push({ change })
+      continue
+    }
+    const { file: probedFile } = probe
+    if (seenAbsolutePaths.has(probedFile.absolutePath)) continue
+    seenAbsolutePaths.add(probedFile.absolutePath)
+    const cached = versions.get(scope)
+    if (
+      cached !== undefined
+      && cached.path === probedFile.displayPath
+      && cached.version === probedFile.version
+      && previous !== undefined
+      && previous.action !== 'remove'
+      && previous.path === cached.path
+      && previous.digest === cached.digest
+    ) continue
+
+    const file = await readScopeInstruction(probedFile, resolved.maxSourceBytes, fileSystem, options.signal)
+    if (file === undefined) continue
+    const currentDigest = instructionContentSha1(file.content)
+    const nextVersion: InstructionVersionState = {
+      path: file.displayPath,
+      version: probedFile.version,
+      digest: currentDigest,
+    }
+    if (previous !== undefined && previous.action !== 'remove' && previous.path === file.displayPath && previous.digest === currentDigest) {
+      versions.set(scope, nextVersion)
+      continue
+    }
+    const action = previous === undefined || previous.action === 'remove' ? 'set' : 'replace'
+    const previousPath = action === 'replace' && previous !== undefined && previous.path !== file.displayPath
+      ? previous.path
+      : undefined
+    const change: WorkspaceInstructionChange = {
+      action,
+      scope,
+      path: file.displayPath,
+      ...previousPath === undefined ? {} : { previousPath },
+      digest: currentDigest,
+    }
+    items.push({ change, file })
+    versionUpdates.push({ change, state: nextVersion })
+  }
+  if (items.length === 0) return undefined
+  const rendered = renderInstructionChanges(items, resolved.maxBytes)
+  if (rendered.text.length === 0 || rendered.changes.length === 0) return undefined
+  return {
+    context: workspaceContextHook(rendered.text, rendered.changes),
+    versionUpdates: retainedInstructionVersionUpdates(versionUpdates, rendered.changes),
+  }
+}
+
+/**
+ * Validate a successful structured file touch and reconcile its applicable scopes.
+ * @param agent - optional agent attached to the tool execution.
+ * @param exec - completed tool execution descriptor.
+ * @param result - original tool result before post-execute decisions.
+ * @param resolved - normalized plugin configuration.
+ * @param pendingNestedChanges - per-session pending transition maps.
+ * @param baselineInstructionStates - retained baseline comparison state.
+ * @param versionCache - per-session scope metadata used to skip unchanged reads.
+ * @param fileSystem - provider used for current file probes.
+ * @returns rendered context plus deferred cache updates, or undefined for irrelevant/failed/unchanged calls.
+ */
+export async function dynamicInstructionContext(
+  agent: Agent | undefined,
+  exec: ToolExecution,
+  result: ToolExecutionResult,
+  resolved: ResolvedConfig,
+  pendingNestedChanges: WeakMap<object, Map<string, PendingInstructionChange>>,
+  baselineInstructionStates: WeakMap<object, Map<string, WorkspaceInstructionChange>>,
+  versionCache: InstructionVersionCache,
+  fileSystem: FileSystem,
+): Promise<ReconciledInstructionContext | undefined> {
+  if (agent === undefined || result.isError) return undefined
+  const touchedPath = filePathFromExecution(exec)
+  if (touchedPath === undefined) return undefined
+  return reconcileInstructionContext(
+    agent, resolved, pendingNestedChanges, baselineInstructionStates, versionCache, fileSystem,
+    {
+      touchedPath,
+      includeBaselineScopes: baselineInstructionStates.has(agent.session),
+      ...exec.signal === undefined ? {} : { signal: exec.signal },
+    },
+  )
+}

packages/context/workspace-context/tests/workspace-context.e2e.ts

@@ -0,0 +1,124 @@
+import { mkdtemp, mkdir, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import LlmService from '@deepseek-ai/dsh-llm'
+import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import ToolRegistry from '@deepseek-ai/dsh-tools'
+import AgentRegistry, { AgentId } from '@deepseek-ai/dsh-agent'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import AgentLoop from '@deepseek-ai/dsh-agent-loop'
+import * as LlmDeepSeek from '@deepseek-ai/dsh-llm-deepseek'
+import * as WorkspaceContext from '@deepseek-ai/dsh-workspace-context'
+import LocalFileSystem from '@deepseek-ai/dsh-fs-local'
+import * as ToolFs from '@deepseek-ai/dsh-tool-fs'
+import type { SessionEvent } from '@deepseek-ai/dsh-session'
+
+const PROBE = 'banana-271828'
+const NESTED_PROBE = 'papaya-314159'
+const UPDATED_PROBE = 'guava-161803'
+
+let ctx: Context | undefined
+let workdir: string | undefined
+
+afterEach(async () => {
+  await ctx?.fiber.dispose()
+  ctx = undefined
+  if (workdir !== undefined) await rm(workdir, { recursive: true, force: true })
+  workdir = undefined
+})
+
+async function harness(): Promise<{ ctx: Context; agent: Agent }> {
+  workdir = await mkdtemp(join(tmpdir(), 'dsh-workspace-context-e2e-'))
+  await mkdir(join(workdir, '.git'), { recursive: true })
+  await writeFile(join(workdir, 'AGENTS.md'), `If the user asks for the workspace context handshake, reply with exactly this string and nothing else: ${PROBE}.\n`)
+  ctx = new Context()
+  await ctx.plugin(LlmService)
+  await ctx.plugin(SessionStore)
+  await ctx.plugin(SystemPrompt, { persona: 'Answer the user exactly and concisely.' })
+  await ctx.plugin(ToolRegistry)
+  await ctx.plugin(AgentRegistry)
+  await ctx.plugin(LocalFileSystem, { cwd: '/' })
+  await ctx.plugin(ToolFs)
+  await ctx.plugin(WorkspaceContext, { maxBytes: 65536 })
+  await ctx.plugin(AgentLoop, { agents: [] })
+  await ctx.plugin(LlmDeepSeek, { models: ['deepseek-v4-flash'] })
+  const handle = await ctx.agents.create({
+    agentId: AgentId('workspace-context-e2e'),
+    sessionId: SessionId('workspace-context-e2e-session'),
+    meta: { cwd: workdir },
+    agentOptions: { model: 'deepseek-v4-flash' },
+  })
+  return { ctx, agent: handle.agent }
+}
+
+function waitForIdle(ctx: Context, agent: Agent): Promise<void> {
+  return new Promise((resolve) => {
+    const dispose = ctx.on('agent/status', (subject, status) => {
+      if (subject === agent && status === 'idle') {
+        dispose()
+        resolve()
+      }
+    })
+  })
+}
+
+function finalText(events: SessionEvent[]): string {
+  const message = events.findLast(event => event.type === 'assistant/message')
+  if (message?.type !== 'assistant/message') return ''
+  return message.data.content
+    .filter(block => block.type === 'text')
+    .map(block => block.text)
+    .join('')
+}
+
+describe.skipIf(!process.env.DEEPSEEK_API_KEY)('workspace context e2e: real model sees AGENTS.md baseline', () => {
+  it('obeys a probe instruction loaded from the workspace', async () => {
+    const live = await harness()
+
+    live.agent.send([{ type: 'text', text: 'Workspace context handshake?' }])
+    await waitForIdle(live.ctx, live.agent)
+
+    expect(finalText([...live.agent.session.events])).toContain(PROBE)
+  }, 120_000)
+
+  it('loads a nested AGENTS.md after the real read tool touches a descendant file', async () => {
+    const live = await harness()
+    await mkdir(join(workdir!, 'pkg/deep'), { recursive: true })
+    await writeFile(join(workdir!, 'pkg/AGENTS.md'), `If the user asks for the nested instruction handshake, reply with exactly this string and nothing else: ${NESTED_PROBE}.\n`)
+    await writeFile(join(workdir!, 'pkg/deep/file.txt'), 'This file exists only to trigger nested workspace instructions.\n')
+
+    live.agent.send([{ type: 'text', text: 'Use the read tool to inspect pkg/deep/file.txt. After reading it, answer: nested instruction handshake?' }])
+    await waitForIdle(live.ctx, live.agent)
+
+    expect(finalText([...live.agent.session.events])).toContain(NESTED_PROBE)
+  }, 120_000)
+
+  it('appends changed baseline instructions after a real file-tool touch without rewriting the frozen prefix', async () => {
+    const live = await harness()
+    await writeFile(join(workdir!, 'trigger.txt'), 'This file triggers workspace instruction reconciliation.\n')
+    live.agent.send([{ type: 'text', text: 'Workspace context handshake?' }])
+    await waitForIdle(live.ctx, live.agent)
+    await writeFile(join(workdir!, 'AGENTS.md'), `The old workspace handshake no longer applies. If the user asks for the updated workspace context handshake, reply with exactly this string and nothing else: ${UPDATED_PROBE}.\n`)
+
+    live.agent.send([{ type: 'text', text: 'You must use the read tool to inspect trigger.txt. After reading it, answer: updated workspace context handshake?' }])
+    await waitForIdle(live.ctx, live.agent)
+
+    const events = [...live.agent.session.events]
+    const update = events.find(event => event.type === 'context/message'
+      && typeof event.data.meta === 'object'
+      && event.data.meta !== null
+      && !Array.isArray(event.data.meta)
+      && event.data.meta.kind === 'workspace-instructions')
+    expect(update?.type === 'context/message' && update.data.meta).toMatchObject({
+      changes: [{ action: 'replace', scope: '.', path: 'AGENTS.md' }],
+    })
+    const updateText = update?.type === 'context/message'
+      ? update.data.content.filter(block => block.type === 'text').map(block => block.text).join('')
+      : ''
+    expect(updateText).toContain('Updated instructions from: AGENTS.md')
+    expect(finalText(events)).toContain(UPDATED_PROBE)
+  }, 120_000)
+})

packages/context/workspace-context/tsconfig.json

@@ -0,0 +1,36 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../../vendor/schemastery"
+    },
+    {
+      "path": "../../llm/llm"
+    },
+    {
+      "path": "../../core/agent"
+    },
+    {
+      "path": "../../core/session"
+    },
+    {
+      "path": "../../core/tools"
+    },
+    {
+      "path": "../../fs/fs"
+    },
+    {
+      "path": "../../util/paths"
+    }
+  ]
+}

packages/cordis/tool-cordis/src/api-catalog.ts

@@ -110,8 +110,9 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
     key: 'fs',
     summary: 'Abstract filesystem provider.',
     methods: [
-      'abstract resolve(path: string, opts?: { cwd?: string }): Promise<FsTarget>',
+      'abstract resolve(path: string, opts?: { cwd?: string; signal?: AbortSignal }): Promise<FsTarget>',
       'abstract stat(target: FsTarget, signal?: AbortSignal): Promise<FsInfo | undefined>',
+      'abstract lstat(path: string, opts?: { cwd?: string }, signal?: AbortSignal): Promise<FsPathInfo | undefined>',
       'abstract readText(target: FsTarget, signal?: AbortSignal): Promise<string>',
       'abstract streamText(target: FsTarget, signal?: AbortSignal): Promise<AsyncIterable<string>>',
       'abstract listDir(target: FsTarget, signal?: AbortSignal): Promise<FsDirEntry[]>',
@@ -190,6 +191,13 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
       'async get(name: string, options: SkillLookupOptions = {}): Promise<SkillDefinition | undefined>',
     ],
   },
+  {
+    key: 'spillStore',
+    summary: 'Abstract spill storage service.',
+    methods: [
+      'abstract saveText(input: SaveTextSpill): Promise<SpillRef>',
+    ],
+  },
   {
     key: 'subagents',
     summary: 'Named provider registry and capability-checked start surface.',
@@ -505,7 +513,7 @@ export const EVENT_API: readonly EventApiEntry[] = [
 export const TYPE_API: readonly TypeApiEntry[] = [
   {
     name: 'Agent',
-    declaration: 'export interface Agent {\n    readonly id: AgentId;\n    readonly options: AgentOptions;\n    readonly session: Session;\n    readonly status: AgentStatus;\n    readonly ctx: Context;\n    send(content: ContentBlock[], options?: SendOptions): void;\n    steer(content: ContentBlock[], options?: SendOptions): void;\n    inject(content: ContentBlock[], options?: SendOptions): void;\n    cancel(reason?: string): void;\n    whenIdle(): Promise<void>;\n}',
+    declaration: 'export interface Agent {\n    readonly id: AgentId;\n    readonly options: AgentOptions;\n    readonly session: Session;\n    readonly status: AgentStatus;\n    readonly ctx: Context;\n    send(content: ContentBlock[], options?: SendOptions): void;\n    steer(content: ContentBlock[], options?: SendOptions): void;\n    inject(content: ContentBlock[], options?: InjectOptions): void;\n    cancel(reason?: string): void;\n    whenIdle(): Promise<void>;\n}',
   },
   {
     name: 'AgentFactory',
@@ -569,11 +577,11 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'BashExecRequest',
-    declaration: 'export interface BashExecRequest {\n    command: string;\n    workdir?: string | undefined;\n    timeoutMs?: number | undefined;\n    signal?: AbortSignal | undefined;\n    stdin?: string | undefined;\n    env?: Record<string, string> | undefined;\n    sandboxMode?: SandboxMode | undefined;\n}',
+    declaration: 'export interface BashExecRequest {\n    command: string;\n    workdir?: string | undefined;\n    timeoutMs?: number | undefined;\n    stdoutMaxBytes?: number | undefined;\n    signal?: AbortSignal | undefined;\n    stdin?: string | undefined;\n    env?: Record<string, string> | undefined;\n    sandboxMode?: SandboxMode | undefined;\n}',
   },
   {
     name: 'BashExecSpec',
-    declaration: 'export interface BashExecSpec {\n    command: string;\n    workdir: string;\n    timeoutMs: number;\n    signal?: AbortSignal | undefined;\n    stdin?: string | undefined;\n    env?: Record<string, string> | undefined;\n    sandboxMode: SandboxMode | undefined;\n}',
+    declaration: 'export interface BashExecSpec {\n    command: string;\n    workdir: string;\n    timeoutMs: number;\n    stdoutMaxBytes: number;\n    signal?: AbortSignal | undefined;\n    stdin?: string | undefined;\n    env?: Record<string, string> | undefined;\n    sandboxMode: SandboxMode | undefined;\n}',
   },
   {
     name: 'BashProcess',
@@ -651,6 +659,10 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'ContentBlockType',
     declaration: 'export type ContentBlockType = keyof ContentBlockMap;',
   },
+  {
+    name: 'ContextEnvelope',
+    declaration: 'export type ContextEnvelope = \'context\' | \'raw\';',
+  },
   {
     name: 'CreateAgentOptions',
     declaration: 'export interface CreateAgentOptions {\n    readonly agentId: AgentId;\n    readonly sessionId: SessionId;\n    readonly meta?: {\n        readonly cwd?: string;\n        readonly parentSession?: SessionId;\n        readonly seedLength?: number;\n    };\n    readonly seed?: readonly SessionEvent[];\n    readonly agentOptions?: AgentOptions;\n    readonly signal?: AbortSignal;\n    readonly setup?: (agentCtx: Context) => Promise<void> | void;\n}',
@@ -699,6 +711,10 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'FsInfo',
     declaration: 'export interface FsInfo {\n    version: FsVersion;\n    type: \'file\' | \'directory\' | \'other\';\n    size?: number;\n}',
   },
+  {
+    name: 'FsPathInfo',
+    declaration: 'export interface FsPathInfo {\n    version: FsVersion;\n    type: \'file\' | \'directory\' | \'symlink\' | \'other\';\n    size?: number;\n}',
+  },
   {
     name: 'FsTarget',
     declaration: 'export interface FsTarget {\n    targetKey: FsTargetKey;\n    displayPath: string;\n}',
@@ -733,7 +749,15 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'HookContext',
-    declaration: 'export interface HookContext {\n    content: ContentBlock[];\n    source: MessageSource;\n}',
+    declaration: 'export interface HookContext {\n    content: ContentBlock[];\n    source: MessageSource;\n    envelope?: ContextEnvelope;\n    meta?: JsonValue;\n}',
+  },
+  {
+    name: 'InjectOptions',
+    declaration: 'export interface InjectOptions extends SendOptions {\n    envelope?: ContextEnvelope;\n    meta?: JsonValue;\n}',
+  },
+  {
+    name: 'JsonValue',
+    declaration: 'export type JsonValue = null | boolean | number | string | JsonValue[] | {\n    [key: string]: JsonValue;\n};',
   },
   {
     name: 'Message',
@@ -783,6 +807,10 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'SandboxPolicy',
     declaration: 'export interface SandboxPolicy {\n    mode: ConfinedSandboxMode;\n    workspaceRoot: string;\n}',
   },
+  {
+    name: 'SaveTextSpill',
+    declaration: 'export interface SaveTextSpill {\n    owner: SpillOwner;\n    source: SpillSource;\n    suggestedName: string;\n    content: string;\n}',
+  },
   {
     name: 'ScopeKey',
     declaration: 'export type ScopeKey = object;',
@@ -797,7 +825,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'SessionEventMap',
-    declaration: 'export interface SessionEventMap {\n    \'turn/start\': {\n        turn: number;\n        trigger: TurnTrigger;\n    };\n    \'turn/end\': {\n        turn: number;\n        reason: TurnEndReason;\n    };\n    \'step/start\': {\n        turn: number;\n        step: number;\n    };\n    \'step/end\': {\n        turn: number;\n        step: number;\n    };\n    \'user/message\': {\n        content: ContentBlock[];\n        source: MessageSource;\n    };\n    \'prompt/blocked\': {\n        content: ContentBlock[];\n        source: MessageSource;\n        reason: string;\n    };\n    \'context/message\': {\n        content: ContentBlock[];\n        source: MessageSource;\n    };\n    \'assistant/chunk\': {\n        turn: number;\n        step: number;\n        chunk: StreamChunk;\n    };\n    \'assistant/message\': {\n        turn: number;\n        step: number;\n        content: ContentBlock[];\n        usage?: TokenUsage;\n    };\n    \'tool/call\': {\n        turn: number;\n        step: number;\n        callId: CallId;\n        name: string;\n        arguments: string;\n    };\n    \'tool/result\': {\n        turn: number;\n        step: number;\n        callId: CallId;\n        content: ContentBlock[];\n        isError: boolean;\n        error?: {\n            name: string;\n            code: string;\n        };\n        meta?: unknown;\n    };\n    \'steering/message\': {\n        turn: number;\n        content: ContentBlock[];\n        source: MessageSource;\n    };\n    \'todo/write\': {\n        todos: TodoItem[];\n    };\n    \'request/header\': {\n        header: E /* …truncated — full shape in source */',
+    declaration: 'export interface SessionEventMap {\n    \'turn/start\': {\n        turn: number;\n        trigger: TurnTrigger;\n    };\n    \'turn/end\': {\n        turn: number;\n        reason: TurnEndReason;\n    };\n    \'step/start\': {\n        turn: number;\n        step: number;\n    };\n    \'step/end\': {\n        turn: number;\n        step: number;\n    };\n    \'user/message\': {\n        content: ContentBlock[];\n        source: MessageSource;\n    };\n    \'prompt/blocked\': {\n        content: ContentBlock[];\n        source: MessageSource;\n        reason: string;\n    };\n    \'context/message\': {\n        content: ContentBlock[];\n        source: MessageSource;\n        envelope?: ContextEnvelope;\n        meta?: JsonValue;\n    };\n    \'assistant/chunk\': {\n        turn: number;\n        step: number;\n        chunk: StreamChunk;\n    };\n    \'assistant/message\': {\n        turn: number;\n        step: number;\n        content: ContentBlock[];\n        usage?: TokenUsage;\n    };\n    \'tool/call\': {\n        turn: number;\n        step: number;\n        callId: CallId;\n        name: string;\n        arguments: string;\n    };\n    \'tool/result\': {\n        turn: number;\n        step: number;\n        callId: CallId;\n        content: ContentBlock[];\n        isError: boolean;\n        error?: {\n            name: string;\n            code: string;\n        };\n        meta?: unknown;\n    };\n    \'steering/message\': {\n        turn: number;\n        content: ContentBlock[];\n        source: MessageSource;\n    };\n    \'todo/write\': {\n        todos /* …truncated — full shape in source */',
   },
   {
     name: 'SessionEventReadRequest',
@@ -883,6 +911,22 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'SkillSummary',
     declaration: 'export interface SkillSummary {\n    readonly name: string;\n    readonly description: string;\n    readonly whenToUse?: string;\n    readonly disableModelInvocation?: boolean;\n    readonly source: SkillSource;\n    readonly provider: string;\n    readonly resourceBase?: SkillResourceBase;\n}',
   },
+  {
+    name: 'SpillLocator',
+    declaration: 'export type SpillLocator = Branded<\'SpillLocator\'>;',
+  },
+  {
+    name: 'SpillOwner',
+    declaration: 'export interface SpillOwner {\n    sessionId: SessionId;\n}',
+  },
+  {
+    name: 'SpillRef',
+    declaration: 'export interface SpillRef {\n    locator: SpillLocator;\n    bytes: number;\n    retrievalHint: string;\n}',
+  },
+  {
+    name: 'SpillSource',
+    declaration: 'export interface SpillSource {\n    toolName: string;\n    callId: CallId;\n    label: string;\n}',
+  },
   {
     name: 'StreamChunk',
     declaration: 'export type StreamChunk = {\n    type: \'block-start\';\n    index: number;\n    blockType: ContentBlockType;\n} | {\n    type: \'text-delta\';\n    index: number;\n    text: string;\n} | {\n    type: \'reasoning-delta\';\n    index: number;\n    text: string;\n} | {\n    type: \'tool-call-delta\';\n    index: number;\n    id: CallId;\n    name?: string;\n    argumentsDelta: string;\n} | {\n    type: \'block-end\';\n    index: number;\n    block: ContentBlock;\n} | {\n    type: \'usage\';\n    usage: TokenUsage;\n} | {\n    type: \'finish\';\n    reason: FinishReason;\n};',
@@ -987,10 +1031,6 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'TerminalResultView',
     declaration: 'export interface TerminalResultView {\n    card: \'terminal\';\n    title?: string;\n    output?: string;\n    exitCode?: number;\n    signal?: string;\n}',
   },
-  {
-    name: 'TodoItem',
-    declaration: 'export interface TodoItem {\n    content: string;\n    status: \'pending\' | \'in_progress\' | \'completed\';\n}',
-  },
   {
     name: 'TokenUsage',
     declaration: 'export interface TokenUsage {\n    inputTokens: number;\n    outputTokens: number;\n    cacheReadTokens?: number;\n    cacheWriteTokens?: number;\n    reasoningTokens?: number;\n}',
@@ -1009,7 +1049,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'ToolDefinition',
-    declaration: 'export interface ToolDefinition extends ToolSchema {\n    execute(args: unknown, exec: ToolExecution): Promise<ToolExecuteReturn>;\n    timeoutMs?: number;\n    presentCall?(args: unknown): ToolCallView | undefined;\n    presentResult?(args: unknown, result: ToolResult): ToolResultView | undefined;\n}',
+    declaration: 'export interface ToolDefinition extends ToolSchema {\n    execute(args: unknown, exec: ToolRunContext): Promise<ToolExecuteReturn>;\n    timeoutMs?: number;\n    presentCall?(args: unknown): ToolCallView | undefined;\n    presentResult?(args: unknown, result: ToolResult): ToolResultView | undefined;\n}',
   },
   {
     name: 'ToolErrorInfo',
@@ -1029,7 +1069,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'ToolExecutionResult',
-    declaration: 'export interface ToolExecutionResult {\n    content: ContentBlock[];\n    isError: boolean;\n    error?: ToolErrorInfo;\n    additionalContext?: HookContext;\n    meta?: unknown;\n}',
+    declaration: 'export interface ToolExecutionResult {\n    content: ContentBlock[];\n    isError: boolean;\n    error?: ToolErrorInfo;\n    additionalContexts?: HookContext[];\n    meta?: unknown;\n}',
   },
   {
     name: 'ToolExecutionToken',
@@ -1059,6 +1099,10 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'ToolResultView',
     declaration: 'export type ToolResultView = GenericResultView | TerminalResultView | DiffResultView;',
   },
+  {
+    name: 'ToolRunContext',
+    declaration: 'export interface ToolRunContext extends ToolExecution {\n    deferContext(context: HookContext): void;\n}',
+  },
   {
     name: 'ToolSchema',
     declaration: 'export interface ToolSchema {\n    name: string;\n    description: string;\n    parameters: Record<string, unknown>;\n}',

packages/core/README.md

@@ -15,4 +15,4 @@ The session log, system-prompt assembly, tool registry, agent vocabulary, and co
 
 `agent-loop` is the one concrete implementation of the `agent` seam and lives here because it is the harness's default product loop; everything else in `core/` is interface/vocabulary. Plugins depend on the `agent` vocabulary, never on `agent-loop` directly, so the loop stays swappable.
 
-The default composition that wires this spine into a runnable agent lives in [`examples/agent-spine-demo`](../examples/agent-spine-demo/README.md): one bundle plugin that loads the control spine plus selected default capabilities (`timer` + `llm` + sessions + system-prompt + tools + agents + invariants + the local [skill family](../skill/README.md) + `tool-bash` + `agent-loop`) and forwards `agent-loop`'s `agents` list as its own config. It sits in `examples/` — ready-to-run demo/reference bundles — not in `core/`: `core/` ships the swappable spine pieces, while a demo bundle picks one concrete composition of them and adds a front door.
+The default composition that wires this spine into a runnable agent lives in [`examples/agent-spine-demo`](../examples/agent-spine-demo/README.md): one bundle plugin that loads the control spine plus selected default capabilities (`timer` + `llm` + sessions + system-prompt + tools + agents + invariants + the local [skill family](../skill/README.md) + `tool-bash` + workspace-context + `agent-loop`) and forwards `agent-loop`'s `agents` list as its own config. It sits in `examples/` — ready-to-run demo/reference bundles — not in `core/`: `core/` ships the swappable spine pieces, while a demo bundle picks one concrete composition of them and adds a front door.

packages/core/agent-loop/src/agent.ts

@@ -8,7 +8,7 @@
 
 import type { Context } from 'cordis'
 import { agentEvents } from '@deepseek-ai/dsh-agent'
-import type { AgentId, AgentOptions, AgentStatus, SendOptions } from '@deepseek-ai/dsh-agent'
+import type { AgentId, AgentOptions, AgentStatus, InjectOptions, SendOptions } from '@deepseek-ai/dsh-agent'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import { deepFreeze } from '@deepseek-ai/dsh-llm'
 import type { ContentBlock, MessageSource } from '@deepseek-ai/dsh-llm'
@@ -225,14 +225,20 @@ export class ReactLoopAgent implements Agent {
     agentEvents(this.loopCtx, this).emit('agent/queued', accepted.content, info)
   }
 
-  inject(content: ContentBlock[], options?: SendOptions): void {
+  inject(content: ContentBlock[], options?: InjectOptions): void {
     this.assertNotDisposed()
     const source = this.resolveSource(options)
+    const context = {
+      content,
+      source,
+      ...options?.envelope !== undefined ? { envelope: options.envelope } : {},
+      ...options?.meta !== undefined ? { meta: options.meta } : {},
+    }
     if (isTurnOpen(this.session)) {
       // A turn is open in the LOG (decided from the log, not agent status —
       // status can be `running` with no turn open): the context/message is
       // turn-enclosed by that turn, so append it directly.
-      this.session.append('context/message', { content, source }, { surfaceOp: 'append' })
+      this.session.append('context/message', context, { surfaceOp: 'append' })
       return
     }
     // No turn open: wrap the injection in a one-shot turn so every event stays
@@ -244,7 +250,7 @@ export class ReactLoopAgent implements Agent {
     // are contained by Session and cannot create a false append failure.
     try {
       this.session.append('turn/start', { turn, trigger: { kind: 'injection', source } })
-      this.session.append('context/message', { content, source }, { surfaceOp: 'append' })
+      this.session.append('context/message', context, { surfaceOp: 'append' })
     } finally {
       // Close the turn if turn/start made it into the log. A pre-commit veto
       // must escape rather than being mistaken for a committed turn/end.

packages/core/agent-loop/src/loop.ts

@@ -234,10 +234,15 @@ async function runTurn(
       // `allow.content` REPLACES the prompt bytes (a rewrite); absent keeps them.
       const content = decision.content ?? message.content
       session.append('user/message', { content, source: message.source }, { surfaceOp: 'append' })
-      // `allow.additionalContext` is a SEPARATE context/message the next request
-      // also sees. The turn is open, so inject() appends it into THIS turn.
-      if (decision.additionalContext) {
-        agent.inject(decision.additionalContext.content, { source: decision.additionalContext.source })
+      // Every `allow.additionalContexts` entry is a separate context/message the
+      // next request also sees. The turn is open, so inject() appends each one
+      // into THIS turn without flattening provenance, framing, or metadata.
+      for (const context of decision.additionalContexts ?? []) {
+        agent.inject(context.content, {
+          source: context.source,
+          ...context.envelope !== undefined ? { envelope: context.envelope } : {},
+          ...context.meta !== undefined ? { meta: context.meta } : {},
+        })
       }
     }
 
@@ -587,7 +592,7 @@ async function runStep(
       // Persist tool-owned presentation data for replay.
       ...result.meta !== undefined ? { meta: result.meta } : {},
     }, { surfaceOp: 'append', sourceEventSeqs: [callEvent.seq] })
-    if (result.additionalContext) pendingContext.push(result.additionalContext)
+    pendingContext.push(...result.additionalContexts ?? [])
     // The signal may flip while the tool is awaited.
     /* v8 ignore start -- signal.reason default unreachable: cancel()/disposal always set it */
     // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
@@ -597,7 +602,11 @@ async function runStep(
 
   // Append buffered context after the complete result batch.
   for (const context of pendingContext) {
-    agent.inject(context.content, { source: context.source })
+    agent.inject(context.content, {
+      source: context.source,
+      ...context.envelope !== undefined ? { envelope: context.envelope } : {},
+      ...context.meta !== undefined ? { meta: context.meta } : {},
+    })
   }
 
   return { hadToolCalls: toolCalls.length > 0, finish: assembler.finish }

packages/core/agent-loop/tests/interception.spec.ts

@@ -17,7 +17,7 @@ import { MockAdapter, textResponse, toolCallResponse } from './mock-adapter.ts'
  * The interception seams introduced by the hooks taxonomy: `agent/prompt-submit`,
  * `agent/session-start`, the reshaped `agent/turn-continuation`
  * ({@link ContinuationDecision}), and the `tools/pre-execute` / `tools/post-execute`
- * split with `additionalContext` buffering. These verify the canonical event
+ * split with `additionalContexts` buffering. These verify the canonical event
  * surface a hook bridge (or a native plugin) programs against, WITHOUT any
  * external protocol — a native plugin uses the typed decisions directly.
  */
@@ -91,15 +91,21 @@ describe('agent/prompt-submit', () => {
     expect(JSON.stringify(adapter.requests[0]!.messages)).not.toContain('original')
   })
 
-  it('allow with additionalContext injects a separate context/message into the turn', async () => {
+  it('allow with additionalContexts injects separate context/message events into the turn', async () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
     const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
 
+    const meta = { kind: 'prompt-context', version: 1 }
     ctx.on('agent/prompt-submit', async (): Promise<PromptDecision> =>
       ({
         kind: 'allow',
-        additionalContext: { content: [{ type: 'text', text: 'extra ctx' }], source: { kind: 'plugin', plugin: 'test' } },
+        additionalContexts: [{
+          content: [{ type: 'text', text: '<system-reminder>extra ctx</system-reminder>' }],
+          source: { kind: 'plugin', plugin: 'test' },
+          envelope: 'raw',
+          meta,
+        }],
       }))
 
     send(agent, 'go')
@@ -109,14 +115,16 @@ describe('agent/prompt-submit', () => {
     const userMsg = log.find(e => e.type === 'user/message')
     const ctxMsg = log.find(e => e.type === 'context/message')
     expect(userMsg).toBeDefined()
-    expect(ctxMsg?.type === 'context/message' && ctxMsg.data.content).toEqual([{ type: 'text', text: 'extra ctx' }])
+    expect(ctxMsg?.type === 'context/message' && ctxMsg.data.content).toEqual([{ type: 'text', text: '<system-reminder>extra ctx</system-reminder>' }])
     expect(ctxMsg?.type === 'context/message' && ctxMsg.data.source).toEqual({ kind: 'plugin', plugin: 'test' })
+    expect(ctxMsg?.type === 'context/message' && ctxMsg.data.envelope).toBe('raw')
+    expect(ctxMsg?.type === 'context/message' && ctxMsg.data.meta).toEqual(meta)
     // both the prompt and the injected context reach the model
     const sent = JSON.stringify(adapter.requests[0]!.messages)
     expect(sent).toContain('extra ctx')
   })
 
-  it('a prompt-submit rewrite + additionalContext is VISIBLE to the agent/pre-step seam (merged ordering)', async () => {
+  it('a prompt-submit rewrite + additionalContexts is VISIBLE to the agent/pre-step seam (merged ordering)', async () => {
     // Prompt rewrites and injected context land before `agent/pre-step`, so a
     // compaction listener measures the current surface before the single derive.
     const adapter = new MockAdapter([textResponse('ok')])
@@ -127,7 +135,7 @@ describe('agent/prompt-submit', () => {
       ({
         kind: 'allow',
         content: [{ type: 'text', text: 'REWRITTEN prompt' }],
-        additionalContext: { content: [{ type: 'text', text: 'injected ctx' }], source: { kind: 'plugin', plugin: 'test' } },
+        additionalContexts: [{ content: [{ type: 'text', text: 'injected ctx' }], source: { kind: 'plugin', plugin: 'test' } }],
       }))
 
     // The pre-step seam (where compaction lives) derives the surface it would act
@@ -538,8 +546,8 @@ describe('agent/turn-continuation (ContinuationDecision)', () => {
   })
 })
 
-describe('tools/post-execute additionalContext buffering across a multi-call step', () => {
-  it('appends each call\'s additionalContext only AFTER all tool/results, preserving adjacency', async () => {
+describe('tool additionalContexts buffering across a step', () => {
+  it('appends each call\'s contexts only AFTER all tool/results, preserving adjacency', async () => {
     // One assistant step with TWO tool calls; the second model response stops.
     const twoCalls = [
       { type: 'block-start' as const, index: 0, blockType: 'tool-call' as const },
@@ -557,9 +565,17 @@ describe('tools/post-execute additionalContext buffering across a multi-call ste
     }))
     const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
 
-    // Each call attaches additionalContext naming itself.
+    // Each call attaches one context naming itself.
     ctx.on('tools/post-execute', async (exec, _result): Promise<PostToolDecision> =>
-      ({ kind: 'accept', additionalContext: { content: [{ type: 'text', text: `ctx-${exec.callId}` }], source: { kind: 'plugin', plugin: 'p' } } }))
+      ({
+        kind: 'accept',
+        additionalContexts: [{
+          content: [{ type: 'text', text: `ctx-${exec.callId}` }],
+          source: { kind: 'plugin', plugin: 'p' },
+          envelope: 'raw',
+          meta: { callId: exec.callId },
+        }],
+      }))
 
     send(agent, 'go')
     await waitForIdle(ctx, agent)
@@ -579,6 +595,37 @@ describe('tools/post-execute additionalContext buffering across a multi-call ste
       .flatMap(e => (e.type === 'context/message' ? e.data.content : []))
       .map(b => (b.type === 'text' ? b.text : ''))
     expect(ctxTexts).toEqual(['ctx-c1', 'ctx-c2'])
+    const contextEvents = events(agent).filter(e => e.type === 'context/message')
+    expect(contextEvents.map(e => e.type === 'context/message' && e.data.envelope)).toEqual(['raw', 'raw'])
+    expect(contextEvents.map(e => e.type === 'context/message' && e.data.meta)).toEqual([{ callId: 'c1' }, { callId: 'c2' }])
+  })
+
+  it('appends multiple contexts deferred by one composite tool after its outer result', async () => {
+    const adapter = new MockAdapter([toolCallResponse('c1', 'composite', {}), textResponse('done')])
+    const ctx = await harness(adapter)
+    ctx.tools.register(defineTool({
+      name: 'composite', description: 'composite', parameters: {},
+      async execute(_args, exec) {
+        exec.deferContext({ content: [{ type: 'text', text: 'nested-a' }], source: { kind: 'plugin', plugin: 'a' }, meta: { order: 1 } })
+        exec.deferContext({ content: [{ type: 'text', text: 'nested-b' }], source: { kind: 'plugin', plugin: 'b' }, envelope: 'raw', meta: { order: 2 } })
+        return [{ type: 'text', text: 'outer result' }]
+      },
+    }))
+    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+
+    send(agent, 'go')
+    await waitForIdle(ctx, agent)
+
+    const log = events(agent)
+    const resultIndex = log.findIndex(event => event.type === 'tool/result')
+    const contextEvents = log.filter(event => event.type === 'context/message')
+    expect(resultIndex).toBeGreaterThanOrEqual(0)
+    expect(log.findIndex(event => event === contextEvents[0])).toBeGreaterThan(resultIndex)
+    expect(contextEvents.map(event => event.type === 'context/message' && event.data.source)).toEqual([
+      { kind: 'plugin', plugin: 'a' },
+      { kind: 'plugin', plugin: 'b' },
+    ])
+    expect(contextEvents.map(event => event.type === 'context/message' && event.data.meta)).toEqual([{ order: 1 }, { order: 2 }])
   })
 })
 
@@ -638,7 +685,7 @@ describe('worked example: a native hook plugin is just a cordis plugin on the se
       ctx.on('tools/post-execute', async (_exec, _result, next): Promise<PostToolDecision> => {
         const decision = await next()
         if (decision.kind === 'accept') {
-          return { kind: 'accept', additionalContext: { content: [{ type: 'text', text: 'audited' }], source: { kind: 'plugin', plugin: 'native-guard' } } }
+          return { kind: 'accept', additionalContexts: [{ content: [{ type: 'text', text: 'audited' }], source: { kind: 'plugin', plugin: 'native-guard' } }] }
         }
         return decision
       })

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

@@ -383,6 +383,32 @@ describe('agent loop', () => {
     expect(flat).toContain('<context source=\\"plugin\\">')
   })
 
+  it('inject() can persist raw structured context without the generic context envelope', async () => {
+    const adapter = new MockAdapter([textResponse('ok')])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create(AgentId('raw-context'), { model: 'mock' })
+    const text = '<system-reminder>Additional instructions from: pkg/AGENTS.md</system-reminder>'
+    const meta = {
+      kind: 'workspace-instructions',
+      version: 1,
+      changes: [{ action: 'set', scope: 'pkg', path: 'pkg/AGENTS.md', digest: 'abc123' }],
+    }
+
+    agent.inject([{ type: 'text', text }], {
+      source: { kind: 'plugin', plugin: 'workspace-context' },
+      envelope: 'raw',
+      meta,
+    })
+    send(agent, 'go')
+    await waitForIdle(ctx, agent)
+
+    const contextEvent = agent.session.events.find(event => event.type === 'context/message')
+    expect(contextEvent?.type === 'context/message' && contextEvent.data).toMatchObject({ envelope: 'raw', meta })
+    const requestText = JSON.stringify(adapter.requests[0]!.messages)
+    expect(requestText).toContain('Additional instructions from: pkg/AGENTS.md')
+    expect(requestText).not.toContain('<context source=')
+  })
+
   it('inject() while running appends into the open turn (no extra synthetic turn)', async () => {
     const adapter = new MockAdapter([
       toolCallResponse('c1', 'noticer', {}, 'calling'),

packages/core/agent/README.md

@@ -33,6 +33,8 @@ The loop plugin registers `AgentFactory`, keeping consumers independent of its c
 
 Most interception points are cooperative waterfalls returning seam-specific decisions. `agent/pre-step` is a serial surface-mutation checkpoint, while `agent/turn-stop` is the terminal serial fold: it runs after ordinary continuation and steering folding, and a returned stop remains in force through turn close and flush so later steering cannot create an extra step or turn. Ordinary queued prompts remain intact. The full rationale is in the [agent-scope runtime-design RFC](../../../docs/rfc/implemented/architecture/2026-07-12-agent-scope-runtime-design.md#three-execution-boundaries-are-deliberately-one-way).
 
+`PromptDecision.additionalContexts` is an array so every injected context keeps its own source, envelope, and metadata. A `ContinuationDecision` reason is narrower: it becomes a `steering/message`, not a `context/message`, and therefore carries only content and source.
+
 Turn and step boundaries and the model token stream are durable `session/event` facts rather than mirrored `agent/*` notifications. Consumers read `turn/*`, `step/*`, and `assistant/chunk` from the session feed; tool policy and outcome observation belong to the complete pipeline documented by [`dsh-tools`](../tools/README.md).
 
 ### Agent interface (`types.ts`)
@@ -41,7 +43,7 @@ The handle every plugin programs against:
 
 - `agent.send(content, options?)` — queue a message; starts a turn when idle. Content and resolved source become one detached, deeply frozen lossless-JSON record before `agent/queued` and enqueue; invalid data throws synchronously, and caller or notification-listener in-place mutation cannot change the log or model input (`agent/prompt-submit` still rewrites by returning replacement content).
 - `agent.steer(content, options?)` — steer a running turn (inject between steps); uses the same owned acceptance boundary and behaves like `send` when idle
-- `agent.inject(content, options?)` — inject in-session context (context/message event); the next request sees it. Does not run the model. While a turn is open it joins that turn; while idle it is wrapped in a one-shot `injection` turn so every event stays turn-enclosed ([the turn-enclosure invariant](../../../docs/rfc/implemented/architecture/2026-06-15-turn-enclosure-invariant.md))
+- `agent.inject(content, options?)` — inject in-session context (`context/message` event); the next request sees it. `options.envelope` defaults to the canonical `<context>` framing and may be `'raw'` when the caller owns a complete familiar frame; `options.meta` persists opaque JSON state without rendering it. Does not run the model. While a turn is open it joins that turn; while idle it is wrapped in a one-shot `injection` turn so every event stays turn-enclosed ([the turn-enclosure invariant](../../../docs/rfc/implemented/architecture/2026-06-15-turn-enclosure-invariant.md))
 - `agent.cancel(reason?)` — cancel ALL pending work: clears the queued + steering FIFOs, aborts the in-flight step, and drops a turn about to start (the pre-step window) so a queued-but-not-started prompt never runs. A UI/ACP `session/cancel` maps to this. The single public stop primitive. Idle with nothing pending → a safe no-op.
 - `agent.whenIdle()` — resolve once the agent reaches quiescence after settling out of `running` (idle → immediately; disposed → awaits the loop exit). A non-owner's quiescence-observation hook: it observes the work settling WITHOUT tearing the agent down. Teardown is separate — a lifecycle owner stops and unregisters via `AgentHandle.dispose()`, which awaits the loop exit directly.
 - `agent.session`, `agent.status`, `agent.options`, `agent.id`

packages/core/agent/src/types.ts

@@ -22,7 +22,7 @@ export type AgentId = Branded<'AgentId'>
 export function AgentId(id: string): AgentId {
   return id as AgentId
 }
-import type { Session } from '@deepseek-ai/dsh-session'
+import type { ContextEnvelope, JsonValue, Session } from '@deepseek-ai/dsh-session'
 
 declare module '@deepseek-ai/dsh-system-prompt' {
   interface AssembleContext {
@@ -42,6 +42,14 @@ export interface SendOptions {
   source?: MessageSource
 }
 
+/** Options specific to durable synthetic context injection. */
+export interface InjectOptions extends SendOptions {
+  /** Keep the canonical context tag, or send caller-owned framing verbatim. */
+  envelope?: ContextEnvelope
+  /** Opaque JSON state retained in the session event but hidden from the model. */
+  meta?: JsonValue
+}
+
 /**
  * An agent's lifecycle state, emitted on every transition as `agent/status`:
  * `idle` (parked, waiting for queued work), `running` (a turn is in progress),
@@ -54,21 +62,25 @@ export type AgentStatus = 'idle' | 'running' | 'disposed'
 export interface HookContext {
   content: ContentBlock[]
   source: MessageSource
+  /** Keep the canonical context tag, or use caller-owned framing verbatim. */
+  envelope?: ContextEnvelope
+  /** Opaque JSON state retained in the session event but hidden from the model. */
+  meta?: JsonValue
 }
 
 /**
- * Prompt interception result. `allow.content` replaces the prompt and
- * `additionalContext` becomes a separate context message. `block` records a
+ * Prompt interception result. `allow.content` replaces the prompt and each
+ * `additionalContexts` entry becomes a separate context message. `block` records a
  * durable `prompt/blocked`; an all-blocked batch ends a zero-step rejected turn.
  */
 export type PromptDecision =
-  | { kind: 'allow'; content?: ContentBlock[]; additionalContext?: HookContext }
+  | { kind: 'allow'; content?: ContentBlock[]; additionalContexts?: HookContext[] }
   | { kind: 'block'; reason: string }
 
 /** Turn continuation override; a continue reason is recorded as next-step steering in the same turn. */
 export type ContinuationDecision =
   | { action: 'stop' }
-  | { action: 'continue'; reason?: HookContext }
+  | { action: 'continue'; reason?: { content: ContentBlock[]; source: MessageSource } }
 
 /**
  * The terminal subset of {@link ContinuationDecision}. A listener on
@@ -108,7 +120,7 @@ export interface Agent {
    * turn joins it at the current log position. Disposal awaits idle checkpoints;
    * flush failures are reported through `agent/error`, not thrown to the caller.
    */
-  inject(content: ContentBlock[], options?: SendOptions): void
+  inject(content: ContentBlock[], options?: InjectOptions): void
 
   /**
    * Clear queued and steering work, including work waiting to start, and abort

packages/core/session/README.md

@@ -56,6 +56,8 @@ Durable values need one accepted representation, not a check followed by a secon
 
 `request/header` and `request/header-delta` make the non-history request envelope reconstructable from the log. `foldRequestHeader()` reconstructs the active header, `diffHeader()` encodes changes, and `applyHeaderDelta()` replays them; unsupported deltas fall back to a full snapshot. `messagePrefix` remains separate from derived history. See the [reconstructable-requests RFC](../../../docs/rfc/implemented/architecture/2026-07-05-reconstructable-requests.md).
 
+`context/message` defaults to the canonical tagged context projection. A producer may set `envelope: 'raw'` when its `content` already contains the complete model-facing frame, and may attach JSON `meta` for replayable plugin state; metadata remains durable but is excluded from `deriveMessages()`.
+
 ### Session event vocabulary (`types.ts`)
 
 The append-only log's event types, enumerated member by member — payloads, surface badges, provenance — in the generated [persistence log event catalog](../../../docs/persistence-catalog.md). Token usage rides on `assistant/message.usage`; an operational error's step is on `turn/end.reason` for `kind: 'error'`.

packages/core/session/src/index.ts

@@ -13,7 +13,7 @@ import { scopeOf, scopeTarget } from '@deepseek-ai/dsh-scope'
 import type { Scoped } from '@deepseek-ai/dsh-scope'
 import type { ContentBlock, Message, MessageSource } from '@deepseek-ai/dsh-llm'
 import { SESSION_FORMAT_VERSION, SessionId } from './types.ts'
-import type { CreateSessionOptions, EpochHeader, SessionEvent, SessionEventMap, SessionEventType, SessionHeader, SurfaceIntent, SurfaceEventType } from './types.ts'
+import type { ContextEnvelope, CreateSessionOptions, EpochHeader, SessionEvent, SessionEventMap, SessionEventType, SessionHeader, SurfaceIntent, SurfaceEventType } from './types.ts'
 import { snapshotJsonValue } from './json.ts'
 import { SurfaceManager } from './surface.ts'
 import { foldRequestHeader } from './request-header.ts'
@@ -189,6 +189,22 @@ interface SessionEntry {
 /** Store attachment for the append path; module-private to keep Session store-agnostic publicly. */
 const attachments = new WeakMap<Session, SessionEntry>()
 
+/**
+ * Render one context contribution exactly as it will appear in model history.
+ * @param content - content blocks supplied by the context producer.
+ * @param source - attribution used by the canonical context envelope.
+ * @param envelope - canonical tagged framing or caller-owned raw framing.
+ * @returns a detached block list ready for the derived model transcript.
+ */
+export function renderContextContent(
+  content: ContentBlock[],
+  source: MessageSource,
+  envelope: ContextEnvelope = 'context',
+): ContentBlock[] {
+  const cloned = structuredClone(content)
+  return envelope === 'raw' ? cloned : renderTagged('context', cloned, source)
+}
+
 /**
  * An event-sourced session: an append-only log of {@link SessionEvent}s.
  *
@@ -474,8 +490,8 @@ export class Session {
         }
       }
       case 'context/message': {
-        const { content, source } = event.data
-        return { role: 'user', content: renderTagged('context', content, source) }
+        const { content, source, envelope } = event.data
+        return { role: 'user', content: renderContextContent(content, source, envelope) }
       }
       case 'steering/message': {
         const { content, source } = event.data

packages/core/session/src/types.ts

@@ -1,5 +1,9 @@
 import type { Branded } from '@deepseek-ai/dsh-brand'
 import type { CallId, ContentBlock, LlmCallConfig, Message, MessageSource, StreamChunk, TokenUsage, ToolSchema } from '@deepseek-ai/dsh-llm'
+import type { JsonValue } from './json.ts'
+
+/** Canonical context-tag framing, or caller-owned framing rendered verbatim. */
+export type ContextEnvelope = 'context' | 'raw'
 
 /** Identifies one session in the store (and its persistence artifacts). */
 export type SessionId = Branded<'SessionId'>
@@ -235,9 +239,16 @@ export interface SessionEventMap {
   /**
    * In-session context injection (file-change notices, subdir AGENTS.md,
    * skill content, cron notifications, …). Rendered into the derived history
-   * as tagged synthetic context — NOT a user prompt.
+   * as synthetic context — NOT a user prompt. `envelope: 'raw'` lets a caller
+   * own the complete model-facing frame; `meta` is durable JSON state omitted
+   * from the model projection.
    */
-  'context/message': { content: ContentBlock[]; source: MessageSource }
+  'context/message': {
+    content: ContentBlock[]
+    source: MessageSource
+    envelope?: ContextEnvelope
+    meta?: JsonValue
+  }
   /** Raw stream chunk — token-level replay fidelity. */
   'assistant/chunk': { turn: number; step: number; chunk: StreamChunk }
   /**

packages/core/session/tests/session.spec.ts

@@ -59,6 +59,28 @@ describe('Session', () => {
     expect(steeringMessage!.content[0]).toMatchObject({ type: 'text', text: '<steering source="user">' })
   })
 
+  it('renders raw context without a generic envelope while preserving structured metadata', () => {
+    const session = new Session(SessionId('s2-raw'))
+    const meta = {
+      kind: 'workspace-instructions',
+      version: 1,
+      changes: [{ action: 'set', scope: 'pkg', path: 'pkg/AGENTS.md', digest: 'abc123' }],
+    }
+    session.append('context/message', {
+      content: [{ type: 'text', text: '<system-reminder>Additional instructions from: pkg/AGENTS.md</system-reminder>' }],
+      source: { kind: 'plugin', plugin: 'workspace-context' },
+      envelope: 'raw',
+      meta,
+    }, { surfaceOp: 'append' })
+
+    expect(session.deriveMessages()).toEqual([{
+      role: 'user',
+      content: [{ type: 'text', text: '<system-reminder>Additional instructions from: pkg/AGENTS.md</system-reminder>' }],
+    }])
+    const event = session.events[0]
+    expect(event?.type === 'context/message' && event.data.meta).toEqual(meta)
+  })
+
   it('replays identically from a seeded event log', () => {
     const original = new Session(SessionId('s3'))
     original.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })

packages/core/tools/README.md

@@ -36,9 +36,10 @@ The live registry pipeline has three transformable waterfalls followed by the ob
 - `ToolExecutionInput` — the caller-supplied call description: `{ callId, name, arguments, agent?, parent?, signal? }`; callers may pass an enclosing execution's opaque token as `parent` but never choose the new execution's own token.
 - `ToolExecutionToken` — a fresh branded `Symbol` assigned by the registry. It supports equality correlation only and never crosses a model, log, or worker boundary.
 - `ToolExecution` — the pipeline-owned call: immutable `{ token, callId, name, arguments, agent?, parent? }` identity plus optional operational `signal`, which an around wrapper may add, replace, remove, and restore. A nested call's `parent` is a `ToolExecutionToken`, not an execution object.
-- `ToolExecutionResult` — losslessly JSON-serializable outcome: `{ content, isError, error?, additionalContext?, meta? }`. Call identity stays on the immutable `ToolExecution` supplied alongside the result instead of being duplicated on the outcome. The registry materializes and freezes the complete post-policy value before final observation. On failure with a `HarnessError`, `error: { name, code }` carries the structured failure class alongside the model-facing text.
+- `ToolRunContext` — the execution passed to a tool body, extending `ToolExecution` with `deferContext(context)`. Composite tools use it to ferry context produced by nested dispatches to the outer result even when the tool later throws; it never injects immediately.
+- `ToolExecutionResult` — losslessly JSON-serializable outcome: `{ content, isError, error?, additionalContexts?, meta? }`. Call identity stays on the immutable `ToolExecution` supplied alongside the result instead of being duplicated on the outcome. The registry materializes and freezes the complete post-policy value before final observation. On failure with a `HarnessError`, `error: { name, code }` carries the structured failure class alongside the model-facing text. `additionalContexts` preserves each deferred or post-execute `HookContext` with its own source, envelope, and durable JSON metadata; the loop buffers the array and appends each entry as a `context/message` after all `tool/result`s in the step.
 - `PreToolDecision` — `{kind:'allow'}` | `{kind:'deny', reason}` | `{kind:'ask', reason?}`. Input rewrite is deliberately not offered; `ask` is serviced by [`ctx.approval`](../../ui/user-approval/README.md) when mounted and otherwise degrades to deny.
-- `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.
+- `PostToolDecision` — `{kind:'accept', content?, additionalContexts?}` (keep the call successful, optionally replacing the model-facing content) | `{kind:'block', feedback, additionalContexts?}` (turn it into an `isError` whose content is the corrective feedback). Accept preserves tool-deferred contexts before decision contexts; block discards tool-deferred contexts and exposes only contexts explicitly supplied by the blocking decision.
 - `ToolGuard` — `(execution) => string | undefined`; the returned string is a final monotonic denial reason evaluated after the reorderable pre-execute waterfall and before dispatch.
 - `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").
 
@@ -47,7 +48,7 @@ The live registry pipeline has three transformable waterfalls followed by the ob
 - Tool plugins call `ctx.tools.register()` — schemas flow into the assembly automatically.
 - `tools/pre-execute` is the reorderable allow/deny/ask gate; `ctx.tools.guard()` adds monotonic owner policy after it.
 - `tools/execute` wraps normalized core dispatch for timeout, retry, or metrics. Wrappers may replace only the operational signal.
-- `tools/post-execute` may replace content, block with feedback, or attach context; `tools/result` observes the immutable final outcome.
+- `tools/post-execute` may replace content, block with feedback, or attach ordered contexts; `tools/result` observes the immutable final outcome.
 - Exact signatures and ordering live in the generated [event catalog](../../../docs/cordis-catalog/events.md) and [pipeline](../../../docs/tool-execution-pipeline.md).
 - MCP servers: one plugin per server, discover tools, call `ctx.tools.register()` with the server's schemas.
 
@@ -101,7 +102,11 @@ Returning `undefined` selects generic fallback. Presenters depend only on their
 
 ### Code Mode
 
-Under `code` or `both`, the registry exposes the reserved `run_code` transport and a deterministic TypeScript SDK for the current scope; only program output re-enters model context. Each JSON-normalized binding re-enters the complete tool pipeline sequentially with logged correlation to the outer call. Denials reject that binding, ordinary side effects are not rolled back, and mid-run `additionalContext` is omitted to preserve call/result adjacency. Run settlement aborts and drains outstanding bindings; failures surface as `CodeRunFailedError`. See the [Code Mode RFC](../../../docs/rfc/implemented/feature/2026-06-15-code-mode.md) and [code-runtime seam](../../code-runtime/README.md). Try `pnpm run demo:code-mode`.
+Under `code` or `both`, the registry exposes the reserved `run_code` transport and a deterministic TypeScript SDK for the current scope; only program output re-enters model context. Each JSON-normalized binding re-enters the complete tool pipeline sequentially with logged correlation to the outer call. Denials reject that binding, ordinary side effects are not rolled back, and sub-call `additionalContexts` are deferred through the parent result to preserve call/result adjacency. Run settlement aborts and drains outstanding bindings; failures surface as `CodeRunFailedError`. See the [Code Mode RFC](../../../docs/rfc/implemented/feature/2026-06-15-code-mode.md) and [code-runtime seam](../../code-runtime/README.md). Try `pnpm run demo:code-mode`.
+
+- **The SDK section** (`tools:sdk`, order 150): a lazy prompt section regenerating, at each assembly, a `declare const tools: {...}` TypeScript declaration of the calling scope's visible end capabilities (exotic names via quoted keys), plus fixed usage instructions. Deterministic — lexicographic tool order, byte-identical text for an unchanged tool set (prefix-cache-friendly). The codegen (`jsonSchemaToTs`, exported) is total: constructs outside the `defineTool` subset degrade to `unknown`, never throw.
+- **The dispatch bridge** (`run_code`'s execute): every binding call is JSON-normalized before dispatch (a value that does not survive — `BigInt`, circulars — rejects that one call, so the dispatched form and logged form are the same JSON value by construction), serialized through a per-run queue (even `Promise.all` executes underlying calls one at a time in submission order), given the outer execution's opaque token as `parent`, and run through the complete pre-execute → guards → execute → post-execute → result pipeline. A denial reaches the program as a binding rejection, and each sub-call is logged as a `tool/code-dispatch` session event with deterministic id `<parent>:code:<n>`; `deriveMessages()` does not surface that event. Token correlation lets commit-style observers defer an inner success until the final `run_code` result without exposing the live outer execution; ordinary tool side effects are not rolled back. Every sub-call `additionalContexts` entry is deferred through the outer `ToolRunContext` in dispatch order; the loop appends those contexts only after the parent `run_code` result, preserving adjacency and retaining each source/envelope/meta even when the program later fails.
+- **Settlement discipline**: the bridge owns a run-scoped abort that follows the outer signal in and fires when the run settles for any reason, so a budget expiry aborts an in-flight sub-tool instead of orphaning it; the bridge then drains its queue BEFORE returning, so every `tool/code-dispatch` lands inside the open turn. A failed run throws `CodeRunFailedError` (`code: 'CODE_RUN_FAILED'`, message = the failure kind + captured logs), which the pipeline converts to a structured `isError` the model self-corrects from.
 
 ## Model Experience
 

packages/core/tools/src/code-mode.ts

@@ -5,6 +5,7 @@
  * @module @deepseek-ai/dsh-tools/src/code-mode
  */
 
+import { parse } from 'node:path'
 import { inspect } from 'node:util'
 import { CallId, HarnessError } from '@deepseek-ai/dsh-llm'
 import type { ContentBlock } from '@deepseek-ai/dsh-llm'
@@ -16,11 +17,19 @@ import type { ToolDefinition, ToolRegistry } from './index.ts'
 declare module '@deepseek-ai/dsh-session' {
   interface SessionEventMap {
     /**
-     * One bridged sub-dispatch from a `run_code` program: the parent `run_code` call id, the
-     * deterministic sub-call id (`<parent>:code:<n>`), the tool `name` with its
-     * JSON-normalized `arguments` — the exact value dispatched, normalized before dispatch, so
-     * this append can never fail on payload shape — whether the sub-call errored, and a
-     * bounded `resultSummary` of its model-facing text.
+     * One bridged sub-dispatch from a `run_code` program: the parent
+     * `run_code` call id, the deterministic sub-call id
+     * (`<parent>:code:<n>`), the tool `name` with its JSON-normalized
+     * `arguments` — the exact value dispatched, normalized BEFORE dispatch,
+     * so this append can never fail on payload shape — whether the sub-call
+     * errored, and a bounded `resultSummary` of its model-facing text. Before
+     * bounding, occurrences of a non-root session workspace path are
+     * normalized to `.` so host-specific absolute path lengths cannot change
+     * the summary.
+     * Log-only: `deriveMessages()` ignores it, so sub-calls never re-enter
+     * model context; persistence and UIs get every call. Appended inside the
+     * parent `run_code`'s execution (the bridge drains its queue before
+     * returning), so the turn-enclosure invariant holds by construction.
      */
     'tool/code-dispatch': { parentCallId: CallId; subCallId: CallId; name: string; arguments: unknown; isError: boolean; resultSummary: string }
   }
@@ -70,9 +79,12 @@ function textOf(content: ContentBlock[]): string {
     .join('\n')
 }
 
-/** Bound a sub-call's model-facing text for the log event's `resultSummary`. */
-function summarize(text: string): string {
-  return text.length > SUMMARY_MAX_CHARS ? `${text.slice(0, SUMMARY_MAX_CHARS)}…` : text
+/** Normalize workspace paths, then bound a sub-call's model-facing text for its durable log summary. */
+function summarize(text: string, cwd: string | undefined): string {
+  const stableText = cwd === undefined || cwd === parse(cwd).root
+    ? text
+    : text.replaceAll(cwd, '.')
+  return stableText.length > SUMMARY_MAX_CHARS ? `${stableText.slice(0, SUMMARY_MAX_CHARS)}…` : stableText
 }
 
 /**
@@ -189,10 +201,10 @@ export function createRunCodeTool(registry: ToolRegistry, requireRuntime: () =>
             parent: exec.token,
             signal: runController.signal,
           })
+          for (const context of result.additionalContexts ?? []) {
+            exec.deferContext(context)
+          }
           const text = textOf(result.content)
-          // Sub-call `additionalContext` is deliberately DROPPED here: the loop's buffering
-          // (append after the step's tool/results) has no safe analogue from inside a running
-          // run_code — injecting now would break tool-call/result adjacency.
           exec.agent?.session.append('tool/code-dispatch', {
             parentCallId: exec.callId,
             subCallId,
@@ -202,7 +214,7 @@ export function createRunCodeTool(registry: ToolRegistry, requireRuntime: () =>
             // this record from what it actually received.
             arguments: normalized.logged,
             isError: result.isError,
-            resultSummary: summarize(text),
+            resultSummary: summarize(text, exec.agent.session.header.cwd),
           })
           return { text, isError: result.isError }
         })

packages/core/tools/src/index.ts

@@ -125,7 +125,7 @@ export type ToolExecuteReturn = ContentBlock[] | { content: ContentBlock[]; meta
 
 /** A registered tool: its schema plus the execution function. */
 export interface ToolDefinition extends ToolSchema {
-  execute(args: unknown, exec: ToolExecution): Promise<ToolExecuteReturn>
+  execute(args: unknown, exec: ToolRunContext): Promise<ToolExecuteReturn>
   /**
    * Cooperative tool-call timeout budget in milliseconds. Omit for no deadline.
    * Enforced by `@deepseek-ai/dsh-timeout-policy` (a `tools/execute` wrapper); it
@@ -207,6 +207,21 @@ export interface ToolExecution extends ToolExecutionInput {
   readonly token: ToolExecutionToken
 }
 
+/**
+ * Runtime context handed to a tool implementation after the registry has
+ * accepted a {@link ToolExecution}. A composite tool uses
+ * {@link deferContext} to ferry context produced by nested dispatches back to
+ * the outer result; the loop appends it only after the outer `tool/result`.
+ */
+export interface ToolRunContext extends ToolExecution {
+  /**
+   * Defer one nested-dispatch context until this tool's final result reaches
+   * the agent loop. Contexts retain their individual source, envelope, and
+   * metadata and are emitted in call order.
+   */
+  deferContext(context: HookContext): void
+}
+
 /** Structured error metadata for a failed tool call (alongside the model-facing text). */
 export interface ToolErrorInfo {
   name: string
@@ -240,7 +255,7 @@ export interface ToolExecutionResult {
    * Model-facing context for the next request, separate from this tool result.
    * The loop buffers it until all step results are logged, preserving pairing.
    */
-  additionalContext?: HookContext
+  additionalContexts?: HookContext[]
   /**
    * The tool-private presentation payload from a successful `execute` (the object
    * return form). Threaded onto the `tool/result` session event and back into
@@ -266,8 +281,8 @@ export type PreToolDecision =
  * request, or block by turning corrective feedback into an error result.
  */
 export type PostToolDecision =
-  | { kind: 'accept'; content?: ContentBlock[]; additionalContext?: HookContext }
-  | { kind: 'block'; feedback: ContentBlock[]; additionalContext?: HookContext }
+  | { kind: 'accept'; content?: ContentBlock[]; additionalContexts?: HookContext[] }
+  | { kind: 'block'; feedback: ContentBlock[]; additionalContexts?: HookContext[] }
 
 /**
  * Best-effort human-readable message from an arbitrary thrown value: Error
@@ -677,6 +692,7 @@ export class ToolRegistry extends Service {
    * @returns the materialized final result.
    */
   async execute(exec: ToolExecutionInput): Promise<ToolExecutionResult> {
+    const deferredContexts: HookContext[] = []
     const token = createExecutionToken()
     const callId = exec.callId
     const name = exec.name
@@ -690,8 +706,11 @@ export class ToolRegistry extends Service {
       ...agent !== undefined ? { agent } : {},
       ...parent !== undefined ? { parent } : {},
       ...signal !== undefined ? { signal } : {},
+      deferContext(context: HookContext): void {
+        deferredContexts.push(context)
+      },
     }
-    let execution: ToolExecution
+    let execution: ToolRunContext
     try {
       const detached = snapshotJsonValue(exec.arguments)
       if (detached === undefined) {
@@ -709,7 +728,7 @@ export class ToolRegistry extends Service {
     }
     let result: ToolExecutionResult
     try {
-      result = this.materializeFinalResult(await this.executePipeline(execution))
+      result = this.materializeFinalResult(await this.executePipeline(execution, deferredContexts))
     } catch (error: unknown) {
       // Outer backstop: a throwing pre/post-execute listener, guard, or the
       // waterfall machinery becomes an isError result, never a turn failure.
@@ -720,7 +739,7 @@ export class ToolRegistry extends Service {
   }
 
   /** Run the transformable pipeline; {@link execute} owns final normalization and notification. */
-  private async executePipeline(exec: ToolExecution): Promise<ToolExecutionResult> {
+  private async executePipeline(exec: ToolRunContext, deferredContexts: HookContext[]): Promise<ToolExecutionResult> {
     // --- Gate: tools/pre-execute. An `ask` resolves through the optional
     // approval seam (or degrades to deny) before the monotonic guards run. The
     // carrier keys dispatch by exec.agent, so an `agent.ctx` listener gates only
@@ -774,7 +793,16 @@ export class ToolRegistry extends Service {
         }
       },
     )
-    return await this.postExecute(exec, result)
+    const resultWithDeferredContexts: ToolExecutionResult = deferredContexts.length === 0
+      ? result
+      : {
+        ...result,
+        additionalContexts: [
+          ...deferredContexts,
+          ...result.additionalContexts ?? [],
+        ],
+      }
+    return await this.postExecute(exec, resultWithDeferredContexts)
   }
 
   /** Notify final-result observers without giving them a mutation/error channel into the outcome. */
@@ -836,8 +864,11 @@ export class ToolRegistry extends Service {
    * Run the `tools/post-execute` waterfall over a dispatched `result` and apply
    * its {@link PostToolDecision}: `accept` keeps the call successful (replacing
    * `content` when given), `block` turns it into an `isError` whose content is
-   * the corrective `feedback`. Either decision may attach `additionalContext`,
-   * which is ferried on the returned result for the loop's per-step buffer.
+   * the corrective `feedback`. Either decision may attach `additionalContexts`,
+   * which are ferried on the returned result for the loop's per-step buffer.
+   * Context deferred by the tool body survives an accepted result but is
+   * discarded when the outer call is blocked; a block exposes only context the
+   * blocking decision explicitly supplied.
    * Runs inside `execute`'s outer try/catch (a throwing listener → isError).
    */
   private async postExecute(exec: ToolExecution, result: ToolExecutionResult): Promise<ToolExecutionResult> {
@@ -845,19 +876,24 @@ export class ToolRegistry extends Service {
       scopeTarget(this, exec.agent), 'tools/post-execute', exec, result,
       () => Promise.resolve<PostToolDecision>({ kind: 'accept' }),
     )
-    const additionalContext = decision.additionalContext
+    const decisionContexts = decision.additionalContexts ?? []
     if (decision.kind === 'block') {
       return {
         content: decision.feedback,
         isError: true,
-        ...additionalContext ? { additionalContext } : {},
+        ...decisionContexts.length > 0 ? { additionalContexts: decisionContexts } : {},
       }
     }
-    // Accept: replace content if supplied and preserve the dispatched outcome.
+    // Accept: replace content if supplied, preserve the dispatched outcome, and
+    // append decision contexts after contexts deferred by the tool body.
+    const additionalContexts = [
+      ...result.additionalContexts ?? [],
+      ...decisionContexts,
+    ]
     return {
       ...result,
       ...decision.content ? { content: decision.content } : {},
-      ...additionalContext ? { additionalContext } : {},
+      ...additionalContexts.length > 0 ? { additionalContexts } : {},
     }
   }
 

packages/core/tools/src/schema.ts

@@ -1,7 +1,7 @@
 /** Typed tool-parameter DSL with argument inference and JSON Schema output. @module dsh-tools/schema */
 
 import { assertNever, HarnessError } from '@deepseek-ai/dsh-llm'
-import type { ToolDefinition, ToolExecuteReturn, ToolExecution, ToolResult } from './index.ts'
+import type { ToolDefinition, ToolExecuteReturn, ToolRunContext, ToolResult } from './index.ts'
 import type { ToolCallView, ToolResultView } from './presentation.ts'
 
 // ---------------------------------------------------------------------------
@@ -289,7 +289,7 @@ export interface DefineToolOptions<S extends SchemaSpec> {
    * content only) or a `{ content, meta }` object to also attach a tool-private
    * presentation payload (see {@link ToolExecuteReturn}).
    */
-  execute(args: InferArgs<S>, exec: ToolExecution): Promise<ToolExecuteReturn>
+  execute(args: InferArgs<S>, exec: ToolRunContext): Promise<ToolExecuteReturn>
   /**
    * Optional: how to present the PENDING state of one call in a UI (an editor
    * tool-call card, a CLI log line). `args` is the typed, schema-validated
@@ -333,7 +333,7 @@ export function defineTool<S extends SchemaSpec>(options: DefineToolOptions<S>):
     description: options.description,
     parameters: schemaSpecToJsonSchema(options.parameters) as unknown as Record<string, unknown>,
     ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
-    async execute(args: unknown, exec: ToolExecution): Promise<ToolExecuteReturn> {
+    async execute(args: unknown, exec: ToolRunContext): Promise<ToolExecuteReturn> {
       // Validate the model-generated args before the typed body runs. On
       // mismatch we throw ToolArgsError; the registry turns it into an
       // isError result so the model can self-correct. After this guard, the

packages/core/tools/tests/code-mode.spec.ts

@@ -82,10 +82,11 @@ function registerEcho(ctx: Context, name = 'echo'): unknown[] {
 }
 
 /** A structural fake of the owning agent: captures session appends. */
-function fakeAgent(): { agent: Agent; events: { type: string; data: unknown }[] } {
+function fakeAgent(options: { cwd?: string } = { cwd: '/workspace' }): { agent: Agent; events: { type: string; data: unknown }[] } {
   const events: { type: string; data: unknown }[] = []
   const agent = {
     session: {
+      header: options.cwd === undefined ? {} : { cwd: options.cwd },
       append: (type: string, data: unknown) => { events.push({ type, data }) },
     },
   } as unknown as Agent
@@ -477,27 +478,71 @@ describe('the run_code dispatch bridge', () => {
     expect(dispatch.arguments).toEqual({ value: 'x', when: '1970-01-01T00:00:00.000Z' })
   })
 
-  it('suppresses sub-call additionalContext (deliberately; pinned)', async () => {
+  it('defers sub-call additionalContexts onto the outer run_code result', async () => {
     const { ctx, runtime } = await setup({ mode: 'code' })
     registerEcho(ctx)
     ctx.on('tools/post-execute', (exec, _result, next): Promise<PostToolDecision> => {
       if (exec.name === 'echo') {
         return Promise.resolve({
           kind: 'accept' as const,
-          additionalContext: { content: [{ type: 'text' as const, text: 'context for the next request' }], source: { kind: 'plugin' as const, plugin: 'test' } },
+          additionalContexts: [{
+            content: [{ type: 'text' as const, text: `context for ${exec.callId}` }],
+            source: { kind: 'plugin' as const, plugin: 'test' },
+            envelope: 'raw' as const,
+            meta: { callId: exec.callId },
+          }],
         })
       }
       return next()
     })
     runtime.behavior = async (request) => {
       await request.bindings[0]!.functions.echo!({ value: 'x' })
+      await request.bindings[0]!.functions.echo!({ value: 'y' })
       return { logs: [], value: 'done' }
     }
     const result = await runCode(ctx, 'program')
     expect(result.isError).toBe(false)
-    // The sub-call's context has no safe outlet mid-run; the parent result
-    // must not carry it either.
-    expect(result.additionalContext).toBeUndefined()
+    expect(result.additionalContexts).toEqual([
+      {
+        content: [{ type: 'text', text: 'context for call-1:code:1' }],
+        source: { kind: 'plugin', plugin: 'test' },
+        envelope: 'raw',
+        meta: { callId: 'call-1:code:1' },
+      },
+      {
+        content: [{ type: 'text', text: 'context for call-1:code:2' }],
+        source: { kind: 'plugin', plugin: 'test' },
+        envelope: 'raw',
+        meta: { callId: 'call-1:code:2' },
+      },
+    ])
+  })
+
+  it('keeps sub-call contexts when run_code fails after the nested dispatch', async () => {
+    const { ctx, runtime } = await setup({ mode: 'both' })
+    registerEcho(ctx)
+    ctx.on('tools/post-execute', (exec, _result, next): Promise<PostToolDecision> => {
+      if (exec.name !== 'echo') return next()
+      return Promise.resolve({
+        kind: 'accept',
+        additionalContexts: [{
+          content: [{ type: 'text', text: 'nested context' }],
+          source: { kind: 'plugin', plugin: 'test' },
+        }],
+      })
+    })
+    runtime.behavior = async (request) => {
+      await request.bindings[0]!.functions.echo!({ value: 'x' })
+      return { logs: [], error: { kind: 'exception', message: 'program failed later' } }
+    }
+
+    const result = await runCode(ctx, 'program')
+
+    expect(result.isError).toBe(true)
+    expect(result.additionalContexts).toEqual([{
+      content: [{ type: 'text', text: 'nested context' }],
+      source: { kind: 'plugin', plugin: 'test' },
+    }])
   })
 
   it('converts a failed run into a structured isError result carrying kind, message, and captured logs', async () => {
@@ -671,6 +716,52 @@ describe('the run_code dispatch bridge', () => {
     expect(dispatch.resultSummary.endsWith('…')).toBe(true)
   })
 
+  it('normalizes the session workspace root before bounding durable result summaries', async () => {
+    const { ctx, runtime } = await setup({ mode: 'code' })
+    ctx.tools.register(defineTool({
+      name: 'workspace_path',
+      description: 'Return a path beneath the session workspace.',
+      parameters: {},
+      execute(_args, exec) {
+        const cwd = exec.agent?.session.header.cwd ?? ''
+        return Promise.resolve([{ type: 'text' as const, text: `<path>${cwd}/nested/task.txt</path>\n${'x'.repeat(240)}` }])
+      },
+    }))
+    runtime.behavior = async request => ({
+      logs: [],
+      value: await request.bindings[0]!.functions.workspace_path!({}),
+    })
+
+    const short = fakeAgent({ cwd: '/tmp/workspace' })
+    const long = fakeAgent({ cwd: `/tmp/${'long-segment/'.repeat(30)}workspace` })
+    const shortResult = await runCode(ctx, 'program', { agent: short.agent })
+    const longResult = await runCode(ctx, 'program', { agent: long.agent })
+    const shortDispatch = short.events[0]!.data as SessionEventMap['tool/code-dispatch']
+    const longDispatch = long.events[0]!.data as SessionEventMap['tool/code-dispatch']
+
+    expect(shortResult.content).not.toEqual(longResult.content)
+    expect(shortDispatch.resultSummary).toBe(longDispatch.resultSummary)
+    expect(shortDispatch.resultSummary).toHaveLength(201)
+    expect(shortDispatch.resultSummary).toMatch(/^<path>\.\/nested\/task\.txt<\/path>\n.+…$/)
+  })
+
+  it('leaves result summaries unchanged when a session cwd is absent or is the filesystem root', async () => {
+    const { ctx, runtime } = await setup({ mode: 'code' })
+    registerEcho(ctx)
+    runtime.behavior = async request => ({
+      logs: [],
+      value: await request.bindings[0]!.functions.echo!({ value: '/workspace/value' }),
+    })
+
+    const absent = fakeAgent({})
+    const root = fakeAgent({ cwd: '/' })
+    await runCode(ctx, 'program', { agent: absent.agent })
+    await runCode(ctx, 'program', { agent: root.agent })
+
+    expect((absent.events[0]!.data as SessionEventMap['tool/code-dispatch']).resultSummary).toBe('echo:/workspace/value')
+    expect((root.events[0]!.data as SessionEventMap['tool/code-dispatch']).resultSummary).toBe('echo:/workspace/value')
+  })
+
   it('rejects undefined, JSON-throwing, and JSON-unrepresentable binding arguments BEFORE dispatch', async () => {
     const { ctx, runtime } = await setup({ mode: 'code' })
     const calls = registerEcho(ctx)

packages/core/tools/tests/gen-tool-catalog.spec.ts

@@ -23,7 +23,7 @@ describe('gen-tool-catalog collectToolCatalog', () => {
   it('boots every shipped tool package and harvests its model-facing schemas', async () => {
     const catalog = await collectToolCatalog()
     const names = catalog.flatMap(entry => entry.schemas.map(s => s.name)).sort()
-    expect(names).toEqual(['ask_user_question', 'bash', 'cordis_inspect', 'cordis_mount', 'cordis_unmount', 'edit', 'read', 'run_code', 'skill', 'subagent', 'task_kill', 'task_list', 'task_output', 'todo_write', 'web_fetch', 'web_search', 'workflow', 'write'])
+    expect(names).toEqual(['ask_user_question', 'bash', 'cordis_inspect', 'cordis_mount', 'cordis_unmount', 'edit', 'glob', 'grep', 'read', 'run_code', 'skill', 'subagent', 'task_kill', 'task_list', 'task_output', 'todo_write', 'web_fetch', 'web_search', 'workflow', 'write'])
     // Every tool carries a JSON-Schema `parameters` object (what the model sees).
     for (const entry of catalog) {
       for (const schema of entry.schemas) {

packages/core/tools/tests/tools.spec.ts

@@ -348,7 +348,7 @@ describe('ToolRegistry', () => {
     expect(result.content[0]).toMatchObject({ text: 'output rejected: try again' })
   })
 
-  it('a block decision can ALSO attach additionalContext', async () => {
+  it('a block decision can ALSO attach additionalContexts', async () => {
     const ctx = await setup()
     ctx.tools.register(echoTool)
 
@@ -356,24 +356,95 @@ describe('ToolRegistry', () => {
       ({
         kind: 'block',
         feedback: [{ type: 'text', text: 'rejected' }],
-        additionalContext: { content: [{ type: 'text', text: 'why it was rejected' }], source: { kind: 'plugin', plugin: 'test' } },
+        additionalContexts: [{ content: [{ type: 'text', text: 'why it was rejected' }], source: { kind: 'plugin', plugin: 'test' } }],
       }))
 
     const result = await ctx.tools.execute({ callId: CallId('c1'), name: 'echo', arguments: { text: 'hi' } })
     expect(result.isError).toBe(true)
     expect(result.content[0]).toMatchObject({ text: 'rejected' })
-    expect(result.additionalContext).toMatchObject({ content: [{ text: 'why it was rejected' }], source: { kind: 'plugin', plugin: 'test' } })
+    expect(result.additionalContexts).toMatchObject([{ content: [{ text: 'why it was rejected' }], source: { kind: 'plugin', plugin: 'test' } }])
   })
 
-  it('a post-execute additionalContext rides on the result for the loop to buffer', async () => {
+  it('post-execute additionalContexts ride on the result for the loop to buffer', async () => {
     const ctx = await setup()
     ctx.tools.register(echoTool)
 
     ctx.on('tools/post-execute', async (_exec, _result, _next): Promise<PostToolDecision> =>
-      ({ kind: 'accept', additionalContext: { content: [{ type: 'text', text: 'fyi' }], source: { kind: 'plugin', plugin: 'test' } } }))
+      ({ kind: 'accept', additionalContexts: [{ content: [{ type: 'text', text: 'fyi' }], source: { kind: 'plugin', plugin: 'test' } }] }))
 
     const result = await ctx.tools.execute({ callId: CallId('c1'), name: 'echo', arguments: { text: 'hi' } })
-    expect(result.additionalContext).toMatchObject({ content: [{ text: 'fyi' }], source: { kind: 'plugin', plugin: 'test' } })
+    expect(result.additionalContexts).toMatchObject([{ content: [{ text: 'fyi' }], source: { kind: 'plugin', plugin: 'test' } }])
+  })
+
+  it('preserves tool-deferred, execute-wrapper, and post-execute contexts in order', async () => {
+    const ctx = await setup()
+    ctx.tools.register(defineTool({
+      name: 'composite',
+      description: 'composite',
+      parameters: {},
+      async execute(_args, exec) {
+        exec.deferContext({ content: [{ type: 'text', text: 'nested-1' }], source: { kind: 'plugin', plugin: 'nested-1' }, meta: { n: 1 } })
+        exec.deferContext({ content: [{ type: 'text', text: 'nested-2' }], source: { kind: 'plugin', plugin: 'nested-2' }, envelope: 'raw' })
+        return [{ type: 'text', text: 'done' }]
+      },
+    }))
+    ctx.on('tools/execute', async (_exec, next) => {
+      const result = await next()
+      return {
+        ...result,
+        additionalContexts: [
+          ...result.additionalContexts ?? [],
+          { content: [{ type: 'text', text: 'wrapper' }], source: { kind: 'plugin', plugin: 'wrapper' } },
+        ],
+      }
+    })
+    ctx.on('tools/post-execute', async (_exec, _result, next): Promise<PostToolDecision> => {
+      const downstream = await next()
+      return {
+        ...downstream,
+        additionalContexts: [
+          { content: [{ type: 'text', text: 'post' }], source: { kind: 'plugin', plugin: 'post' } },
+          ...downstream.additionalContexts ?? [],
+        ],
+      }
+    })
+
+    const result = await ctx.tools.execute({ callId: CallId('composite'), name: 'composite', arguments: {} })
+
+    expect(result.additionalContexts?.map(context => context.source)).toEqual([
+      { kind: 'plugin', plugin: 'nested-1' },
+      { kind: 'plugin', plugin: 'nested-2' },
+      { kind: 'plugin', plugin: 'wrapper' },
+      { kind: 'plugin', plugin: 'post' },
+    ])
+    expect(result.additionalContexts?.[0]?.meta).toEqual({ n: 1 })
+    expect(result.additionalContexts?.[1]?.envelope).toBe('raw')
+  })
+
+  it('keeps deferred contexts when a composite tool throws, but drops them when the outer call is blocked', async () => {
+    const ctx = await setup()
+    ctx.tools.register(defineTool({
+      name: 'failing-composite',
+      description: 'failing composite',
+      parameters: {},
+      async execute(_args, exec) {
+        exec.deferContext({ content: [{ type: 'text', text: 'nested' }], source: { kind: 'plugin', plugin: 'nested' } })
+        throw new Error('outer failure')
+      },
+    }))
+
+    const failed = await ctx.tools.execute({ callId: CallId('failed'), name: 'failing-composite', arguments: {} })
+    expect(failed.isError).toBe(true)
+    expect(failed.additionalContexts?.map(context => context.source)).toEqual([{ kind: 'plugin', plugin: 'nested' }])
+
+    ctx.on('tools/post-execute', async (): Promise<PostToolDecision> => ({
+      kind: 'block',
+      feedback: [{ type: 'text', text: 'blocked' }],
+      additionalContexts: [{ content: [{ type: 'text', text: 'block-only' }], source: { kind: 'plugin', plugin: 'blocker' } }],
+    }))
+    const blocked = await ctx.tools.execute({ callId: CallId('blocked'), name: 'failing-composite', arguments: {} })
+    expect(blocked.isError).toBe(true)
+    expect(blocked.additionalContexts?.map(context => context.source)).toEqual([{ kind: 'plugin', plugin: 'blocker' }])
   })
 
   it('composes pre + post waterfalls around dispatch (sandbox-wrap pattern)', async () => {
@@ -532,25 +603,25 @@ describe('ToolRegistry', () => {
     expect(result.content[0]).toMatchObject({ text: 'short-circuited' })
   })
 
-  it('preserves additionalContext supplied by an around-dispatch result', async () => {
+  it('preserves additionalContexts supplied by an around-dispatch result', async () => {
     const ctx = await setup()
     ctx.tools.register(echoTool)
     ctx.on('tools/execute', async () => ({
       content: [{ type: 'text', text: 'short-circuited with context' }],
       isError: false,
-      additionalContext: {
+      additionalContexts: [{
         content: [{ type: 'text', text: 'from around dispatch' }],
         source: { kind: 'plugin', plugin: 'test' },
-      },
+      }],
     }))
 
     const result = await ctx.tools.execute({
       callId: CallId('around-context'), name: 'echo', arguments: {},
     })
-    expect(result.additionalContext).toEqual({
+    expect(result.additionalContexts).toEqual([{
       content: [{ type: 'text', text: 'from around dispatch' }],
       source: { kind: 'plugin', plugin: 'test' },
-    })
+    }])
   })
 
   it('returns an isError result when a tools/execute listener throws', async () => {

packages/examples/README.md

@@ -4,7 +4,7 @@ Pre-composed plugin bundles a thin leaf `cordis.yml` loads instead of assembling
 
 | Package | npm name | Role |
 |---|---|---|
-| `agent-spine-demo/` | `@deepseek-ai/dsh-agent-spine-demo` | The executor-less/UI-less agent spine as one bundle plugin (`timer` + `llm` + sessions + system-prompt + tools + skills + agents + invariants + `tool-bash` + `tool-skill` + `agent-loop`) |
+| `agent-spine-demo/` | `@deepseek-ai/dsh-agent-spine-demo` | The executor-less/UI-less agent spine as one bundle plugin (`timer` + `llm` + sessions + system-prompt + tools + skills + agents + invariants + `tool-bash` + workspace-context + `tool-skill` + `agent-loop`) |
 | `stdio-demo/` | `@deepseek-ai/dsh-stdio-demo` | Terminal stdio chat app: the spine + console logger + readline UI + a pre-created `main` agent, with a boot `bin` |
 | `acp-demo/` | `@deepseek-ai/dsh-acp-demo` | ACP server app: the spine + JSONL persistence + the [`acp`](../ui/acp/README.md) bridge (no stdout logger), with a boot `bin` |
 | `jsonrpc-demo/` | `@deepseek-ai/dsh-jsonrpc-demo` | Bin-only runtime that boots an external `cordis.yml` for the stdio JSON-RPC SDK client |

packages/examples/acp-demo/package.json

@@ -35,6 +35,7 @@
     "@deepseek-ai/dsh-app-boot": "^0.0.1",
     "@deepseek-ai/dsh-acp": "^0.0.1",
     "@deepseek-ai/dsh-agent-spine-demo": "^0.0.1",
+    "@deepseek-ai/dsh-workspace-context": "^0.0.1",
     "@deepseek-ai/dsh-session-persistence-jsonl": "^0.0.1",
     "@deepseek-ai/dsh-tools": "^0.0.1",
     "@deepseek-ai/dsh-user-interaction": "^0.0.1",
@@ -50,6 +51,7 @@
     "@deepseek-ai/dsh-agent-spine-demo": "workspace:^",
     "@deepseek-ai/dsh-tools": "workspace:^",
     "@deepseek-ai/dsh-system-prompt": "workspace:^",
+    "@deepseek-ai/dsh-workspace-context": "workspace:^",
     "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:^",
     "@deepseek-ai/dsh-user-interaction": "workspace:^",
     "cordis": "^4.0.0-rc.7",

packages/examples/acp-demo/src/index.ts

@@ -13,6 +13,7 @@ import type { Context } from 'cordis'
 import z from 'schemastery'
 import * as acp from '@deepseek-ai/dsh-acp'
 import * as agentCore from '@deepseek-ai/dsh-agent-spine-demo'
+import * as workspaceContext from '@deepseek-ai/dsh-workspace-context'
 import ToolRegistry, { type Config as ToolsConfig } from '@deepseek-ai/dsh-tools'
 import SessionPersistenceJsonl from '@deepseek-ai/dsh-session-persistence-jsonl'
 import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
@@ -39,6 +40,8 @@ export interface Config {
   tools?: ToolsConfig
   /** Directory the JSONL session backend writes under. Defaults to `./.sessions`. */
   persistenceRoot?: string
+  /** Controls automatic AGENTS.md/CLAUDE.md loading; configure a byte budget or set `false`. */
+  workspaceContext: agentCore.Config['workspaceContext']
   /** Skill registry, local-provider, and model-facing consumer config forwarded to agent-spine-demo. */
   skills?: agentCore.SkillConfig
   /** Model-facing bash tool config forwarded through agent-core. */
@@ -61,6 +64,7 @@ export const Config: z<Config> = z.object({
   // TODO(single-default-literal): share this schema default and the defensive
   // apply() fallback through one named constant while retaining both boundaries.
   persistenceRoot: z.string().default('./.sessions'),
+  workspaceContext: z.union([z.const(false), workspaceContext.Config]).required(),
   skills: agentCore.SkillConfigSchema,
   toolBash: agentCore.ToolBashConfigSchema,
   toolTasks: agentCore.ToolTasksConfigSchema,
@@ -75,14 +79,7 @@ export const Config: z<Config> = z.object({
  * from `model`. No logger, no `hmr` — stdout stays pure.
  */
 export function apply(ctx: Context, config: Config): void {
-  ctx.plugin(agentCore, {
-    ...config.persona !== undefined ? { persona: config.persona } : {},
-    ...config.toolOrder !== undefined ? { toolOrder: config.toolOrder } : {},
-    ...config.tools !== undefined ? { tools: config.tools } : {},
-    ...config.skills !== undefined ? { skills: config.skills } : {},
-    ...config.toolBash !== undefined ? { toolBash: config.toolBash } : {},
-    ...config.toolTasks !== undefined ? { toolTasks: config.toolTasks } : {},
-  })
+  ctx.plugin(agentCore, agentCore.pickSpineConfig(config))
   ctx.plugin(UserInteractionService)
   ctx.plugin(SessionPersistenceJsonl, { root: config.persistenceRoot ?? './.sessions' })
   ctx.plugin(acp, { model: config.model })

packages/examples/acp-demo/tests/acp-agent.spec.ts

@@ -11,7 +11,7 @@ import * as acpAgent from '../src/index.ts'
 
 /**
  * In-process unit coverage for the @deepseek-ai/dsh-acp-demo composition:
- * mounting it brings up the agent-core spine + JSONL persistence + the ACP
+ * mounting it brings up the agent-spine-demo spine + JSONL persistence + the ACP
  * bridge in one `ctx.plugin`. Unlike the stdio app, this one loads NO
  * Loader-only plugin (no hmr), so it mounts in a plain Context.
  *
@@ -70,7 +70,7 @@ async function withIsolatedSkillHomes<T>(run: () => Promise<T>): Promise<T> {
 
 describe('dsh-acp-demo composition', () => {
   it('brings up the spine + persistence + the ACP bridge', async () => {
-    const ctx = await mount({ model: 'mock', persona: 'hi', persistenceRoot: '/tmp/dsh-acp-demo-test', skills: await isolatedSkillsConfig() })
+    const ctx = await mount({ model: 'mock', persona: 'hi', persistenceRoot: '/tmp/dsh-acp-demo-test', skills: await isolatedSkillsConfig(), workspaceContext: false })
     expect(ctx.get('agents')).toBeDefined()
     expect(ctx.get('sessions')).toBeDefined()
     expect(ctx.get('sessionPersistence')).toBeDefined()
@@ -89,16 +89,28 @@ describe('dsh-acp-demo composition', () => {
     // persistenceRoot, so the runtime fallback is the one that fires.
     const ctx = new Context()
     // No persona: covers the omitted-persona forwarding branch too.
-    acpAgent.apply(ctx, { model: 'mock', skills: await isolatedSkillsConfig() })
+    acpAgent.apply(ctx, { model: 'mock', skills: await isolatedSkillsConfig(), workspaceContext: false })
     await new Promise(resolve => setTimeout(resolve, 50))
     expect(ctx.get('sessionPersistence')).toBeDefined()
     await ctx.fiber.dispose()
   })
 
+  it('forwards explicit project-instruction controls to the bundled spine', async () => {
+    const ctx = await mount({
+      model: 'mock',
+      persona: 'hi',
+      persistenceRoot: '/tmp/dsh-acp-demo-workspace-context',
+      workspaceContext: false,
+    })
+    expect(ctx.get('agents')).toBeDefined()
+    expect(ctx.get('agentLoop')).toBeDefined()
+    await ctx.fiber.dispose()
+  })
+
   it('uses default skill config when apply is called directly without skills', async () => {
     await withIsolatedSkillHomes(async () => {
       const ctx = new Context()
-      acpAgent.apply(ctx, { model: 'mock' })
+      acpAgent.apply(ctx, { model: 'mock', workspaceContext: false })
       await new Promise(resolve => setTimeout(resolve, 50))
       expect(ctx.skills).toBeDefined()
       expect(await ctx.skills.list()).toEqual([])
@@ -106,8 +118,8 @@ describe('dsh-acp-demo composition', () => {
     })
   })
 
-  it('forwards skill config into agent-core', async () => {
-    const ctx = await mount({ model: 'mock', persona: 'hi', skills: await isolatedSkillsConfig(6) })
+  it('forwards skill config into agent-spine-demo', async () => {
+    const ctx = await mount({ model: 'mock', persona: 'hi', skills: await isolatedSkillsConfig(6), workspaceContext: false })
     ctx.skills.register({ name: 'acp-skill', description: 'ACP skill', source: 'runtime', content: 'body' })
     expect(JSON.stringify(await composePrefix(ctx))).toContain('- `acp-skill`: ACP...')
     await ctx.fiber.dispose()
@@ -116,6 +128,7 @@ describe('dsh-acp-demo composition', () => {
   it('forwards bundled tool config into agent-core', async () => {
     const ctx = await mount({
       model: 'mock',
+      workspaceContext: false,
       toolBash: { enableRunInBackground: false },
       toolTasks: { waitTimeoutMs: 7, maxWaitTimeoutMs: 11 },
       skills: await isolatedSkillsConfig(),
@@ -131,11 +144,12 @@ describe('dsh-acp-demo composition', () => {
     expect(acpAgent.Config).toBeDefined()
   })
 
-  it('forwards toolOrder through agent-core to the system-prompt assembly', async () => {
+  it('forwards toolOrder through agent-spine-demo to the system-prompt assembly', async () => {
     const ctx = await mount({
       model: 'mock',
       toolOrder: ['zulu', TOOL_ORDER_REST],
       persistenceRoot: '/tmp/dsh-acp-demo-test-tool-order',
+      workspaceContext: false,
     })
     // The bundle's own bash tools pend on the absent `ctx.bash` executor in
     // this providerless mount, so register two plain tools to order.

packages/examples/acp-demo/tests/built-bin.e2e.ts

@@ -30,9 +30,9 @@ const acpBin = join(repoRoot, 'packages/examples/acp-demo/lib/bin.js')
 const dshPackages = [
   'examples/agent-spine-demo', 'core/agent', 'core/session', 'core/system-prompt',
   'core/tools', 'core/agent-loop', 'llm/llm', 'llm/llm-deepseek', 'bash/bash',
-  'bash/bash-local', 'bash/tool-bash', 'support/invariants', 'ui/app-boot',
+  'bash/bash-local', 'bash/tool-bash', 'context/workspace-context', 'support/invariants', 'ui/app-boot',
   'session-persistence/session-persistence',
-  'session-persistence/session-persistence-jsonl', 'ui/acp', 'examples/acp-demo',
+  'session-persistence/session-persistence-jsonl', 'ui/acp', 'examples/acp-demo', 'util/paths',
 ]
 const vendorPackages = [
   'cordis', 'loader', 'include', 'timer', 'hmr', 'logger-console',
@@ -86,6 +86,7 @@ async function makeConsumer(): Promise<string> {
     '  config:',
     '    model: deepseek-v4-flash',
     '    persona: \'test agent\'',
+    '    workspaceContext: false',
     '',
   ].join('\n'))
   return dir

packages/examples/acp-demo/tests/load-path.e2e.ts

@@ -44,6 +44,7 @@ const CORDIS_YML = `
   config:
     model: deepseek-v4-flash
     persona: 'You are a test agent.'
+    workspaceContext: false
 `
 
 interface Spawned {

packages/examples/acp-demo/tsconfig.json

@@ -29,6 +29,9 @@
     {
       "path": "../agent-spine-demo"
     },
+    {
+      "path": "../../context/workspace-context"
+    },
     {
       "path": "../../ui/user-interaction"
     },

packages/examples/agent-spine-demo/README.md

@@ -20,6 +20,7 @@ Read this package for the whole plugin tree and its composition order.
 @deepseek-ai/dsh-tasks            generic background-task registry
 @deepseek-ai/dsh-invariants       dev-mode event-contract assertions
 @deepseek-ai/dsh-tool-bash        the model-facing bash schema
+@deepseek-ai/dsh-workspace-context  AGENTS.md/CLAUDE.md workspace context loader
 @deepseek-ai/dsh-tool-skill       session-prefix skill catalog + model-facing loader schema
 @deepseek-ai/dsh-tool-tasks       task_output/task_list/task_kill schemas + completion notices
 @deepseek-ai/dsh-agent-loop       THE concrete loop (gets the forwarded `agents`)
@@ -41,12 +42,11 @@ This is the [interface/implementation/consumer seam](../../../docs/rfc/implement
 
 ```ts
 import type { Config } from '@deepseek-ai/dsh-agent-spine-demo'
-// { agents?, persona?, toolOrder?, tools?, skills?, toolBash?, toolTasks? }
-// The schema intersects the owner schemas,
-// so validation and defaulting can never drift from the owners.
+// { agents?, persona?, toolOrder?, tools?, skills?, workspaceContext, toolBash?, toolTasks? }
+// workspaceContext requires { maxBytes } or false; the other owner schemas supply defaults.
 ```
 
-The bundle FORWARDS each field to the child that owns it: `agents` to `agent-loop` (default `[]`), so each app supplies its own pre-created agents — a stdio app pre-creates a `main`; the ACP app pre-creates none (it creates agents on demand at `session/new`) — `persona` and `toolOrder` to `dsh-system-prompt`; `tools` to the tool registry for its presentation mode; `skills.registry`, `skills.local`, and `skills.tool` to the skill registry, local provider, and model-facing consumer; and `toolBash`/`toolTasks` to the two model-facing tool plugins the bundle owns. `toolBash.enableRunInBackground` controls only the bash producer, while `toolTasks` controls generic `task_output` wait bounds; independently loaded producers keep their own config. Forwarding is exactly why the owners can live in the shared spine even though the apps disagree on what to configure.
+The bundle FORWARDS each field to the child that owns it: `agents` to `agent-loop` (default `[]`), so each app supplies its own pre-created agents — a stdio app pre-creates a `main`; the ACP app pre-creates none (it creates agents on demand at `session/new`) — `persona` and `toolOrder` to `dsh-system-prompt`; `tools` to the tool registry for its presentation mode; `skills.registry`, `skills.local`, and `skills.tool` to the skill registry, local provider, and model-facing consumer; the required `workspaceContext` choice to `dsh-workspace-context` (`{ maxBytes }` enables loading and `false` disables it); and `toolBash`/`toolTasks` to the two model-facing tool plugins the bundle owns. `toolBash.enableRunInBackground` controls only the bash producer, while `toolTasks` controls generic `task_output` wait bounds; independently loaded producers keep their own config. Workspace instructions register before the skill catalog so their session-prefix message renders first. App packages use `pickSpineConfig()` to copy only these bundle-owned fields.
 
 ## Why a code bundle, not a shared YAML include
 

packages/examples/agent-spine-demo/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepseek-ai/dsh-agent-spine-demo",
-  "description": "The default executor-less/UI-less agent spine as one Cordis bundle plugin (timer + llm + sessions + system-prompt + tools + skills + agents + tasks + invariants + tool-bash + tool-skill + tool-tasks + agent-loop)",
+  "description": "The default executor-less/UI-less agent spine as one Cordis bundle plugin (timer + llm + sessions + system-prompt + tools + skills + agents + tasks + invariants + tool-bash + workspace-context + tool-skill + tool-tasks + agent-loop)",
   "version": "0.0.1",
   "private": true,
   "type": "module",
@@ -27,6 +27,7 @@
     "@deepseek-ai/dsh-agent-loop": "^0.0.1",
     "@deepseek-ai/dsh-invariants": "^0.0.1",
     "@deepseek-ai/dsh-llm": "^0.0.1",
+    "@deepseek-ai/dsh-workspace-context": "^0.0.1",
     "@deepseek-ai/dsh-session": "^0.0.1",
     "@deepseek-ai/dsh-skill": "^0.0.1",
     "@deepseek-ai/dsh-skill-local": "^0.0.1",
@@ -42,8 +43,10 @@
     "@cordisjs/plugin-timer": "workspace:^",
     "@deepseek-ai/dsh-agent": "workspace:^",
     "@deepseek-ai/dsh-agent-loop": "workspace:^",
+    "@deepseek-ai/dsh-fs-local": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
+    "@deepseek-ai/dsh-workspace-context": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",
     "@deepseek-ai/dsh-skill": "workspace:^",
     "@deepseek-ai/dsh-skill-local": "workspace:^",

packages/examples/agent-spine-demo/src/index.ts

@@ -1,8 +1,8 @@
 /**
  * Default executor-less, UI-less agent spine. It bundles the common services,
- * background-task registry and controls, concrete loop, local skill provider,
- * and model-facing bash/skill consumers; deployments still choose the LLM
- * adapter, bash executor, and presentation.
+ * background-task registry and controls, concrete loop, local skill and
+ * workspace-context providers, and model-facing bash/skill consumers;
+ * deployments still choose the LLM adapter, bash executor, and presentation.
  * The plugin intentionally exposes named exports only because Loader default
  * unwrapping would discard its `Config` schema (see docs/postmortem/0001).
  * @module @deepseek-ai/dsh-agent-spine-demo
@@ -21,6 +21,7 @@ import AgentRegistry from '@deepseek-ai/dsh-agent'
 import TaskService from '@deepseek-ai/dsh-tasks'
 import * as invariants from '@deepseek-ai/dsh-invariants'
 import * as toolBash from '@deepseek-ai/dsh-tool-bash'
+import * as workspaceContext from '@deepseek-ai/dsh-workspace-context'
 import * as toolSkill from '@deepseek-ai/dsh-tool-skill'
 import * as toolTasks from '@deepseek-ai/dsh-tool-tasks'
 import AgentLoop, { type Config as AgentLoopConfig } from '@deepseek-ai/dsh-agent-loop'
@@ -43,14 +44,13 @@ export interface SkillConfig {
  * bridge, simply omits it), `persona` and `toolOrder` to the system-prompt
  * plugin (the deployment's persona section and the explicit model-facing tool
  * order), the `tools` object to the tool registry (its presentation `mode`),
- * and `toolBash`/`toolTasks` to the two model-facing tool plugins this bundle
- * owns. Producer opt-in stays producer-local: `toolBash` configures bash only;
- * future background-capable tools remain independently composed plugins.
- * Every field is optional INPUT here because each owner's schema
- * supplies the default (`[]` / `''` / absent — lexicographic / `native`); the
- * schema is the INTERSECTION of the owners' own schemas (the registry's
- * nested under its `tools` key), so validation and defaulting can never
- * drift from them.
+ * `skills` to the skill registry/local provider/tool consumer,
+ * `workspaceContext` to the workspace-context loader, and
+ * `toolBash`/`toolTasks` to the model-facing tool plugins this bundle owns.
+ * Owner schemas supply defaults for optional input; workspace context instead
+ * requires an explicit byte budget or `false` because it changes model-visible
+ * input. Producer opt-in stays producer-local: `toolBash` configures bash only;
+ * independently composed producers keep their own config.
  */
 export interface Config {
   /** The agent-loop `agents` list (see dsh-agent-loop's `Config`). */
@@ -61,6 +61,8 @@ export interface Config {
   toolOrder?: SystemPromptConfig['toolOrder']
   /** The tool registry's config — its presentation `mode` (see dsh-tools' `Config`). */
   tools?: ToolsConfig
+  /** Workspace-context loader controls with an explicit byte budget; set `false` for hermetic prompts. */
+  workspaceContext: workspaceContext.Config | false
   /** Skill registry, local provider, and model-facing consumer config. */
   skills?: SkillConfig
   /** Model-facing bash tool config, including this producer's background opt-in. */
@@ -89,19 +91,38 @@ export const Config = z.intersect([
   z.object({
     tools: ToolRegistry.Config,
     skills: SkillConfigSchema,
+    workspaceContext: z.union([z.const(false), workspaceContext.Config]).required(),
     toolBash: ToolBashConfigSchema,
     toolTasks: ToolTasksConfigSchema,
-  }),
+  }) as unknown as z<Pick<Config, 'tools' | 'skills' | 'workspaceContext' | 'toolBash' | 'toolTasks'>>,
 ]) as unknown as z<Config>
 
+/**
+ * Copy the bundle-owned fields from an app config without leaking front-door settings.
+ * @param config - App config containing the shared spine fields.
+ * @returns The fields accepted by this bundle, preserving optional absence.
+ */
+export function pickSpineConfig(config: Omit<Config, 'agents'>): Omit<Config, 'agents'> {
+  return {
+    ...config.persona !== undefined ? { persona: config.persona } : {},
+    ...config.toolOrder !== undefined ? { toolOrder: config.toolOrder } : {},
+    ...config.tools !== undefined ? { tools: config.tools } : {},
+    workspaceContext: config.workspaceContext,
+    ...config.skills !== undefined ? { skills: config.skills } : {},
+    ...config.toolBash !== undefined ? { toolBash: config.toolBash } : {},
+    ...config.toolTasks !== undefined ? { toolTasks: config.toolTasks } : {},
+  }
+}
+
 /**
  * Load the spine. Each `ctx.plugin(...)` mounts one child of the bundle fiber;
  * `agent-loop` receives the forwarded `agents` list and `system-prompt` the
- * forwarded `persona` and `toolOrder`. Load order is irrelevant (cordis pends
- * each fiber on its `inject` until the services it needs exist), but the
+ * forwarded `persona` and `toolOrder`. Workspace-context receives its own
+ * explicitly forwarded config. Load order is irrelevant (cordis
+ * pends each fiber on its `inject` until the services it needs exist), but the
  * listing mirrors the dependency layering for readability: the LLM vocabulary
- * and core registries first, then the dev tripwire and the bash tool consumer,
- * then the loop that drives them.
+ * and core registries first, then extension plugins that wrap request/tool
+ * seams, then the loop that drives them.
  */
 export function apply(ctx: Context, config: Config): void {
   ctx.plugin(Timer)
@@ -119,6 +140,11 @@ export function apply(ctx: Context, config: Config): void {
   ctx.plugin(TaskService)
   ctx.plugin(invariants)
   ctx.plugin(toolBash, config.toolBash ?? {})
+  if (config.workspaceContext !== false) {
+    ctx.plugin(workspaceContext, config.workspaceContext)
+  }
+  // Both plugins prepend session-prefix messages. Registration order is the
+  // rendered order, so workspace instructions must precede the skill catalog.
   ctx.plugin(toolSkill, config.skills?.tool ?? {})
   ctx.plugin(toolTasks, config.toolTasks ?? {})
   ctx.plugin(AgentLoop, { agents: config.agents ?? [] })

packages/examples/agent-spine-demo/tests/agent-core.spec.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it, vi } from 'vitest'
-import { mkdir, mkdtemp, writeFile } from 'node:fs/promises'
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import { tmpdir } from 'node:os'
 import { Context } from 'cordis'
@@ -7,6 +7,9 @@ import Loader from '@cordisjs/plugin-loader'
 import { TOOL_ORDER_REST } from '@deepseek-ai/dsh-system-prompt'
 import * as agentCore from '../src/index.ts'
 import { AgentId, agentEvents, type Agent } from '@deepseek-ai/dsh-agent'
+import { SessionId } from '@deepseek-ai/dsh-session'
+import LocalFileSystem from '@deepseek-ai/dsh-fs-local'
+import { MockAdapter, textResponse } from '../../../core/agent-loop/tests/mock-adapter.ts'
 import { CallId, type Message } from '@deepseek-ai/dsh-llm'
 
 declare module '@deepseek-ai/dsh-tasks' {
@@ -34,7 +37,7 @@ async function composePrefix(ctx: Context, cwd: string): Promise<Message[]> {
  * Loader-path guard (export shape, `unwrapExports`) is the app packages' keyless
  * bin smokes; here we assert the composition + config forwarding.
  */
-async function mount(config?: agentCore.Config, withBash = false): Promise<Context> {
+async function mount(config: agentCore.Config, withBash = false): Promise<Context> {
   const oldDshHome = process.env.DSH_HOME
   const oldAgentsHome = process.env.DSH_AGENTS_HOME
   process.env.DSH_HOME = await mkdtemp(join(tmpdir(), 'dsh-agent-spine-demo-home-'))
@@ -82,9 +85,24 @@ async function withIsolatedSkillHomes<T>(run: () => Promise<T>): Promise<T> {
   }
 }
 
+function waitForMainIdle(ctx: Context): Promise<void> {
+  return new Promise((resolve) => {
+    const dispose = ctx.on('agent/status', (agent, status) => {
+      if (agent.id === 'main' && status === 'idle') {
+        dispose()
+        resolve()
+      }
+    })
+  })
+}
+
+function messageText(message: Message | undefined): string {
+  return message?.content.map(block => block.type === 'text' ? block.text : '').join('\n') ?? ''
+}
+
 describe('dsh-agent-spine-demo bundle', () => {
   it('brings up the full default spine', async () => {
-    const ctx = await mount()
+    const ctx = await mount({ workspaceContext: false })
     // One service from each layer of the spine proves the children loaded.
     expect(ctx.get('timer')).toBeDefined()
     expect(ctx.get('llm')).toBeDefined()
@@ -99,7 +117,7 @@ describe('dsh-agent-spine-demo bundle', () => {
   })
 
   it('includes the skill registry, local provider, and skill tool without builtin skills', async () => {
-    const ctx = await mount()
+    const ctx = await mount({ workspaceContext: false })
 
     expect(ctx.skills).toBeDefined()
     expect(ctx.tools.schemas().map(tool => tool.name)).toContain('skill')
@@ -109,7 +127,7 @@ describe('dsh-agent-spine-demo bundle', () => {
   })
 
   it('defaults the agents list to empty (no pre-created agents)', async () => {
-    const ctx = await mount()
+    const ctx = await mount({ workspaceContext: false })
     expect(ctx.get('agents')?.get(AgentId('main'))).toBeUndefined()
     await ctx.fiber.dispose()
   })
@@ -118,6 +136,7 @@ describe('dsh-agent-spine-demo bundle', () => {
     const ctx = await mount({
       agents: [{ id: AgentId('main'), model: 'mock' }],
       persona: 'You are main.',
+      workspaceContext: false,
     })
     expect(ctx.get('agents')?.get(AgentId('main'))).toBeDefined()
     const assembly = await ctx.get('systemPrompt')!.assemble()
@@ -129,7 +148,7 @@ describe('dsh-agent-spine-demo bundle', () => {
     // ctx.plugin validates + defaults the bundle config first; a direct apply
     // skips the schema, so the forwarding `?? []` / `?? ''` are what fire.
     const ctx = new Context()
-    agentCore.apply(ctx, {})
+    agentCore.apply(ctx, { workspaceContext: false })
     await new Promise(resolve => setTimeout(resolve, 50))
     expect(ctx.get('agentLoop')).toBeDefined()
     expect(ctx.get('agents')?.list()).toHaveLength(0)
@@ -138,6 +157,64 @@ describe('dsh-agent-spine-demo bundle', () => {
     await ctx.fiber.dispose()
   })
 
+  it('loads workspace instructions into requests through the bundled spine', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'dsh-agent-spine-demo-workspace-context-'))
+    try {
+      await mkdir(join(root, '.git'), { recursive: true })
+      await writeFile(join(root, 'AGENTS.md'), 'bundled project rule')
+      const adapter = new MockAdapter([textResponse('ok')])
+      const ctx = await mount({ workspaceContext: { maxBytes: 65536 } })
+      await ctx.plugin(LocalFileSystem, { cwd: '/' })
+      ctx.llm.registerAdapter(['mock'], adapter)
+      const handle = await ctx.agents.create({
+        agentId: AgentId('main'),
+        sessionId: SessionId('main-session'),
+        meta: { cwd: root },
+        agentOptions: { model: 'mock' },
+      })
+      const agent = handle.agent
+
+      agent.send([{ type: 'text', text: 'hi' }])
+      await waitForMainIdle(ctx)
+
+      const sentText = adapter.requests[0]?.messages.map(messageText).join('\n')
+      expect(sentText).toContain('hi')
+      expect(sentText).toContain('bundled project rule')
+      expect(adapter.requests[0]?.system).toContain('You are an AI agent powered by the DeepSeek Harness SDK.')
+      expect(adapter.requests[0]?.system).not.toContain('bundled project rule')
+      await handle.dispose()
+      await ctx.fiber.dispose()
+    } finally {
+      await rm(root, { recursive: true, force: true })
+    }
+  })
+
+  it('forwards workspace-context config to the bundled loader', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'dsh-agent-spine-demo-workspace-context-disabled-'))
+    try {
+      await mkdir(join(root, '.git'), { recursive: true })
+      await writeFile(join(root, 'AGENTS.md'), 'must not be injected')
+      const adapter = new MockAdapter([textResponse('ok')])
+      const ctx = await mount({ workspaceContext: { maxBytes: 0 } })
+      ctx.llm.registerAdapter(['mock'], adapter)
+      const handle = await ctx.agents.create({
+        agentId: AgentId('main'),
+        sessionId: SessionId('main-disabled-session'),
+        meta: { cwd: root },
+        agentOptions: { model: 'mock' },
+      })
+
+      handle.agent.send([{ type: 'text', text: 'hi' }])
+      await waitForMainIdle(ctx)
+
+      expect(adapter.requests[0]?.messages).toEqual([{ role: 'user', content: [{ type: 'text', text: 'hi' }] }])
+      await handle.dispose()
+      await ctx.fiber.dispose()
+    } finally {
+      await rm(root, { recursive: true, force: true })
+    }
+  })
+
   it('forwards skill config to the registry, local provider, and model-facing consumer', async () => {
     const home = await mkdtemp(join(tmpdir(), 'dsh-agent-spine-demo-skill-home-'))
     const agentsHome = await mkdtemp(join(tmpdir(), 'dsh-agent-spine-demo-skill-agents-'))
@@ -146,6 +223,7 @@ describe('dsh-agent-spine-demo bundle', () => {
     await writeFile(join(custom, 'custom-skill.md'), '---\nname: custom-skill\ndescription: Custom skill\n---\n\nCustom body.\n')
     const ctx = await mount({
       agents: [],
+      workspaceContext: false,
       skills: {
         registry: { collectCacheMaxEntries: 4 },
         local: {
@@ -161,8 +239,43 @@ describe('dsh-agent-spine-demo bundle', () => {
     await ctx.fiber.dispose()
   })
 
+  it('places workspace instructions before the skill catalog in the session prefix', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'dsh-agent-spine-demo-prefix-order-'))
+    try {
+      await mkdir(join(root, '.git'), { recursive: true })
+      await writeFile(join(root, 'AGENTS.md'), 'workspace rule before skills')
+      const adapter = new MockAdapter([textResponse('ok')])
+      const ctx = await mount({ workspaceContext: { maxBytes: 65536 } })
+      await ctx.plugin(LocalFileSystem, { cwd: '/' })
+      ctx.llm.registerAdapter(['mock'], adapter)
+      ctx.skills.register({
+        name: 'prefix-order-skill',
+        description: 'Skill catalog after workspace rules',
+        source: 'runtime',
+        content: 'body',
+      })
+      const handle = await ctx.agents.create({
+        agentId: AgentId('main'),
+        sessionId: SessionId('prefix-order-session'),
+        meta: { cwd: root },
+        agentOptions: { model: 'mock' },
+      })
+
+      handle.agent.send([{ type: 'text', text: 'hi' }])
+      await waitForMainIdle(ctx)
+
+      expect(messageText(adapter.requests[0]?.messages[0])).toContain('workspace rule before skills')
+      expect(messageText(adapter.requests[0]?.messages[1])).toContain('prefix-order-skill')
+      await handle.dispose()
+      await ctx.fiber.dispose()
+    } finally {
+      await rm(root, { recursive: true, force: true })
+    }
+  })
+
   it('forwards its bundled tool configs to tool-bash and tool-tasks', async () => {
     const ctx = await mount({
+      workspaceContext: false,
       toolBash: { enableRunInBackground: false },
       toolTasks: { waitTimeoutMs: 7, maxWaitTimeoutMs: 11 },
     }, true)
@@ -188,10 +301,34 @@ describe('dsh-agent-spine-demo bundle', () => {
     await ctx.fiber.dispose()
   })
 
+  it('picks shared spine config without leaking front-door fields', () => {
+    const appConfig = {
+      model: 'front-door-only',
+      persona: 'You are merged.',
+      toolOrder: ['zulu'],
+      tools: { mode: 'native' as const },
+      workspaceContext: false as const,
+      skills: {},
+      toolBash: { enableRunInBackground: false },
+      toolTasks: { waitTimeoutMs: 7, maxWaitTimeoutMs: 11 },
+    }
+
+    expect(agentCore.pickSpineConfig(appConfig)).toEqual({
+      persona: appConfig.persona,
+      toolOrder: appConfig.toolOrder,
+      tools: appConfig.tools,
+      workspaceContext: false,
+      skills: {},
+      toolBash: appConfig.toolBash,
+      toolTasks: appConfig.toolTasks,
+    })
+    expect(agentCore.pickSpineConfig({ workspaceContext: false })).toEqual({ workspaceContext: false })
+  })
+
   it('uses the default skill config when apply is called directly without skills', async () => {
     await withIsolatedSkillHomes(async () => {
       const ctx = new Context()
-      agentCore.apply(ctx, { agents: [] })
+      agentCore.apply(ctx, { agents: [], workspaceContext: false })
       await new Promise(resolve => setTimeout(resolve, 50))
       expect(ctx.skills).toBeDefined()
       expect(await ctx.skills.list()).toEqual([])
@@ -200,7 +337,7 @@ describe('dsh-agent-spine-demo bundle', () => {
   })
 
   it('forwards toolOrder to the system-prompt assembly', async () => {
-    const ctx = await mount({ toolOrder: ['zulu', TOOL_ORDER_REST] })
+    const ctx = await mount({ toolOrder: ['zulu', TOOL_ORDER_REST], workspaceContext: false })
     // The bundle's own bash tools pend on the absent `ctx.bash` executor in
     // this providerless mount, so register two plain tools to order.
     for (const name of ['alpha', 'zulu']) {
@@ -216,6 +353,16 @@ describe('dsh-agent-spine-demo bundle', () => {
     await ctx.fiber.dispose()
   })
 
+  it('supports direct apply with workspace instructions disabled and no forwarded agents', async () => {
+    const ctx = new Context()
+    agentCore.apply(ctx, { workspaceContext: false })
+    await new Promise(resolve => setTimeout(resolve, 50))
+
+    expect(ctx.get('agents')?.list()).toEqual([])
+    expect(ctx.get('systemPrompt')).toBeDefined()
+    await ctx.fiber.dispose()
+  })
+
   it('re-exports the loop config schema as its own', () => {
     expect(agentCore.Config).toBeDefined()
     expect(agentCore.name).toBe('agent-spine-demo')

packages/examples/agent-spine-demo/tsconfig.json

@@ -41,6 +41,9 @@
     {
       "path": "../../core/agent"
     },
+    {
+      "path": "../../context/workspace-context"
+    },
     {
       "path": "../../core/agent-loop"
     },

packages/examples/stdio-demo/README.md

@@ -19,7 +19,7 @@ A terminal chat always wants the same cluster, so the package owns it rather tha
 
 `@cordisjs/plugin-hmr` (the dev/demo edit-reload loop) is deliberately a **leaf** entry, NOT baked in here: it is a Loader-only, subprocess-only dev plugin — its constructor throws without `node --expose-internals` + a live `loader`, and the in-process test tier cannot even import it (so a package whose `apply` statically pulled it in could never carry the per-file coverage gate). Unlike the console logger, a stray `hmr` is not a stdout-purity footgun, so leaving it at the leaf costs no safety. The `demo:echo` / `demo:repl` leaves load it and pass `--expose-internals`.
 
-The leaf `cordis.yml` supplies only the **swappable backends** — an LLM adapter (`llm-deepseek` for the real model, or the mock `mock-llm` for a demo) and a bash executor (`bash-local`) — `hmr`, plus this app's [`Config`](#config). The whole plugin tree a run loads is therefore: this app's cluster, the spine inside `agent-core`, `hmr`, and the two leaf backends.
+The leaf `cordis.yml` supplies only the **swappable backends** — an LLM adapter (`llm-deepseek` for the real model, or the mock `mock-llm` for a demo) and a bash executor (`bash-local`) — `hmr`, plus this app's [`Config`](#config). The whole plugin tree a run loads is therefore: this app's cluster, the spine inside `agent-spine-demo`, `hmr`, and the two leaf backends.
 
 ## Config
 

packages/examples/stdio-demo/package.json

@@ -37,6 +37,7 @@
     "@deepseek-ai/dsh-agent": "^0.0.1",
     "@deepseek-ai/dsh-llm": "^0.0.1",
     "@deepseek-ai/dsh-agent-spine-demo": "^0.0.1",
+    "@deepseek-ai/dsh-workspace-context": "^0.0.1",
     "@deepseek-ai/dsh-session": "^0.0.1",
     "@deepseek-ai/dsh-session-persistence-jsonl": "^0.0.1",
     "@deepseek-ai/dsh-stdio": "^0.0.1",
@@ -55,6 +56,7 @@
     "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-agent-spine-demo": "workspace:^",
     "@deepseek-ai/dsh-system-prompt": "workspace:^",
+    "@deepseek-ai/dsh-workspace-context": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",
     "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:^",
     "@deepseek-ai/dsh-stdio": "workspace:^",

packages/examples/stdio-demo/src/index.ts

@@ -16,6 +16,7 @@ import { AgentId } from '@deepseek-ai/dsh-agent'
 import { SessionId } from '@deepseek-ai/dsh-session'
 import ToolRegistry, { type Config as ToolsConfig } from '@deepseek-ai/dsh-tools'
 import * as agentCore from '@deepseek-ai/dsh-agent-spine-demo'
+import * as workspaceContext from '@deepseek-ai/dsh-workspace-context'
 import SessionPersistenceJsonl from '@deepseek-ai/dsh-session-persistence-jsonl'
 import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
 import * as toolAskUser from '@deepseek-ai/dsh-tool-ask-user'
@@ -58,6 +59,8 @@ export interface Config {
    * (`resumeSessionId: !!js process.env.RESUME_SESSION_ID`).
    */
   resumeSessionId?: string
+  /** Controls automatic AGENTS.md/CLAUDE.md loading; configure a byte budget or set `false`. */
+  workspaceContext: agentCore.Config['workspaceContext']
 }
 
 export const Config: z<Config> = z.object({
@@ -76,6 +79,7 @@ export const Config: z<Config> = z.object({
   toolBash: agentCore.ToolBashConfigSchema,
   toolTasks: agentCore.ToolTasksConfigSchema,
   resumeSessionId: z.string(),
+  workspaceContext: z.union([z.const(false), workspaceContext.Config]).required(),
 })
 
 /**
@@ -88,18 +92,13 @@ export const Config: z<Config> = z.object({
 export function apply(ctx: Context, config: Config): void {
   ctx.plugin(ConsoleExporter)
   ctx.plugin(agentCore, {
-    ...config.persona !== undefined ? { persona: config.persona } : {},
-    ...config.toolOrder !== undefined ? { toolOrder: config.toolOrder } : {},
-    ...config.tools !== undefined ? { tools: config.tools } : {},
+    ...agentCore.pickSpineConfig(config),
     agents: [{
       id: AgentId('main'),
       model: config.model,
       cwd: process.cwd(),
       ...config.resumeSessionId !== undefined ? { resumeSessionId: SessionId(config.resumeSessionId) } : {},
     }],
-    ...config.skills !== undefined ? { skills: config.skills } : {},
-    ...config.toolBash !== undefined ? { toolBash: config.toolBash } : {},
-    ...config.toolTasks !== undefined ? { toolTasks: config.toolTasks } : {},
   })
   ctx.plugin(SessionPersistenceJsonl, { root: config.persistenceRoot ?? './.sessions' })
   ctx.plugin(UserInteractionService)

packages/examples/stdio-demo/tests/built-bin.e2e.ts

@@ -21,9 +21,9 @@ const stdioBin = join(repoRoot, 'packages/examples/stdio-demo/lib/bin.js')
 const dshPackages = [
   'examples/agent-spine-demo', 'core/agent', 'core/session', 'core/system-prompt',
   'core/tools', 'core/agent-loop', 'llm/llm', 'bash/bash', 'bash/bash-local',
-  'bash/tool-bash', 'support/invariants', 'ui/app-boot',
+  'bash/tool-bash', 'context/workspace-context', 'support/invariants', 'ui/app-boot',
   'session-persistence/session-persistence',
-  'session-persistence/session-persistence-jsonl', 'examples/stdio-demo',
+  'session-persistence/session-persistence-jsonl', 'examples/stdio-demo', 'util/paths',
   'ui/stdio', 'ui/tool-ask-user', 'ui/user-interaction',
 ]
 const vendorPackages = [
@@ -36,20 +36,37 @@ async function pkgName(absDir: string): Promise<string> {
   return json.name
 }
 
+async function installWorkspacePackageCopy(absDir: string, target: string): Promise<void> {
+  await mkdir(dirname(target), { recursive: true })
+  await cp(absDir, target, {
+    recursive: true,
+    filter: source => !source.split('/').includes('node_modules'),
+  })
+}
+
 /**
  * Build a temporary external consumer with built workspace/vendor links and a mock-backed config.
  * The optional missing-but-disabled plugin verifies load guards accept intentionally fiber-less
  * entries rather than treating them as import failures.
  */
-async function makeConsumer(welcome: string, disabledBrokenEntry = false): Promise<string> {
+async function makeConsumer(
+  welcome: string,
+  disabledBrokenEntry = false,
+  extraDshPackages: string[] = [],
+  extraEntries: string[] = [],
+): Promise<string> {
   const dir = await mkdtemp(join(tmpdir(), 'stdio-built-bin-'))
   const nm = join(dir, 'node_modules')
-  for (const rel of dshPackages) {
+  for (const rel of [...dshPackages, ...extraDshPackages]) {
     const abs = join(repoRoot, 'packages', rel)
     const name = await pkgName(abs)
     const target = join(nm, name)
-    await mkdir(dirname(target), { recursive: true })
-    await symlink(abs, target)
+    if (extraDshPackages.includes(rel)) {
+      await installWorkspacePackageCopy(abs, target)
+    } else {
+      await mkdir(dirname(target), { recursive: true })
+      await symlink(abs, target)
+    }
   }
   for (const v of vendorPackages) {
     const abs = join(repoRoot, 'vendor', v)
@@ -75,7 +92,9 @@ async function makeConsumer(welcome: string, disabledBrokenEntry = false): Promi
     '  config:',
     '    model: mock-echo',
     '    persona: \'demo\'',
+    '    workspaceContext: false',
     `    welcome: '${welcome}'`,
+    ...extraEntries,
     ...disabledBrokenEntry
       ? ['- id: off', '  name: \'./src/does-not-exist.ts\'', '  disabled: true']
       : [],
@@ -147,6 +166,27 @@ describe.skipIf(!existsSync(stdioBin))('dsh-stdio-demo BUILT bin (node lib/bin.j
     expect(code).toBe(0)
   }, 30_000)
 
+  it('boots when optional spill plugins are loaded from a built consumer install', async () => {
+    consumer = await makeConsumer(
+      'SPILL-OK ready.',
+      false,
+      ['spill/spill', 'spill/spill-local', 'spill/spill-policy', 'util/retention'],
+      [
+        '- id: spill-local',
+        '  name: \'@deepseek-ai/dsh-spill-local\'',
+        '- id: spill-policy',
+        '  name: \'@deepseek-ai/dsh-spill-policy\'',
+        '  config:',
+        '    maxInlineBytes: 50000',
+      ],
+    )
+    const { stdout, code, stderr } = await runBuiltBin(consumer, './cordis.yml', '')
+    expect(stderr).not.toContain('failed to load')
+    expect(stderr).not.toContain('Cannot find package')
+    expect(stdout).toContain('SPILL-OK ready.')
+    expect(code).toBe(0)
+  }, 30_000)
+
   it('fails LOUD (non-zero exit + stderr) on a config whose directory does not exist', async () => {
     // boot() pre-resolves the bootstrap include to an absolute URL, so a nonexistent config
     // directory cannot break its import; the include plugin's own read must fail loud instead.

packages/examples/stdio-demo/tests/stdio-agent.spec.ts

@@ -11,7 +11,7 @@ import * as stdioAgent from '../src/index.ts'
 
 /**
  * Unit coverage for app composition and config forwarding: console logger, pre-created main agent,
- * agent-core spine, JSONL backend, and readline UI. HMR is a Loader-only leaf concern covered by the
+ * agent-spine-demo spine, JSONL backend, and readline UI. HMR is a Loader-only leaf concern covered by the
  * keyless echo smoke; this tier pins the export shape because an inject-less app could otherwise
  * survive namespace collapse while silently losing its schema.
  */
@@ -66,8 +66,8 @@ async function withIsolatedSkillHomes<T>(run: () => Promise<T>): Promise<T> {
 
 describe('dsh-stdio-demo app', () => {
   it('composes the spine + front-door cluster and pre-creates the main agent', async () => {
-    const ctx = await mount({ model: 'mock', persona: 'hi', persistenceRoot: '/tmp/dsh-stdio-demo-spec', skills: await isolatedSkillsConfig() })
-    // The spine services (brought up by the agent-core bundle) are all present.
+    const ctx = await mount({ model: 'mock', persona: 'hi', persistenceRoot: '/tmp/dsh-stdio-demo-spec', skills: await isolatedSkillsConfig(), workspaceContext: false })
+    // The spine services (brought up by the agent-spine-demo bundle) are all present.
     expect(ctx.get('agents')).toBeDefined()
     expect(ctx.get('agentLoop')).toBeDefined()
     expect(ctx.get('sessionPersistence')).toBeDefined()
@@ -87,17 +87,28 @@ describe('dsh-stdio-demo app', () => {
     // schema-bypassing direct-mount caller.
     const ctx = new Context()
     // No persona: covers the omitted-persona forwarding branch too.
-    stdioAgent.apply(ctx, { model: 'mock', skills: await isolatedSkillsConfig() })
+    stdioAgent.apply(ctx, { model: 'mock', skills: await isolatedSkillsConfig(), workspaceContext: false })
     await new Promise(resolve => setTimeout(resolve, 80))
     expect(ctx.get('sessionPersistence')).toBeDefined()
     expect(ctx.get('agents')?.get(AgentId('main'))).toBeDefined()
     await ctx.fiber.dispose()
   })
 
+  it('forwards explicit project-instruction controls to the bundled spine', async () => {
+    const ctx = await mount({
+      model: 'mock',
+      persona: 'hi',
+      persistenceRoot: '/tmp/dsh-stdio-demo-spec-workspace-context',
+      workspaceContext: false,
+    })
+    expect(ctx.get('agents')?.get(AgentId('main'))).toBeDefined()
+    await ctx.fiber.dispose()
+  })
+
   it('uses default skill config when apply is called directly without skills', async () => {
     await withIsolatedSkillHomes(async () => {
       const ctx = new Context()
-      stdioAgent.apply(ctx, { model: 'mock' })
+      stdioAgent.apply(ctx, { model: 'mock', workspaceContext: false })
       await new Promise(resolve => setTimeout(resolve, 80))
       expect(ctx.skills).toBeDefined()
       expect(await ctx.skills.list()).toEqual([])
@@ -115,13 +126,14 @@ describe('dsh-stdio-demo app', () => {
       persistenceRoot: '/tmp/dsh-stdio-demo-spec-resume',
       resumeSessionId: 'no-such-session',
       skills: await isolatedSkillsConfig(),
+      workspaceContext: false,
     })
     expect(ctx.get('agents')?.get(AgentId('main'))).toBeUndefined()
     await ctx.fiber.dispose()
   })
 
-  it('forwards skill config into agent-core', async () => {
-    const ctx = await mount({ model: 'mock', persona: 'hi', skills: await isolatedSkillsConfig(6) })
+  it('forwards skill config into agent-spine-demo', async () => {
+    const ctx = await mount({ model: 'mock', persona: 'hi', skills: await isolatedSkillsConfig(6), workspaceContext: false })
     ctx.skills.register({ name: 'stdio-skill', description: 'Stdio skill', source: 'runtime', content: 'body' })
     expect(JSON.stringify(await composePrefix(ctx))).toContain('- `stdio-skill`: Std...')
     await ctx.fiber.dispose()
@@ -130,6 +142,7 @@ describe('dsh-stdio-demo app', () => {
   it('forwards bundled tool config into agent-core', async () => {
     const ctx = await mount({
       model: 'mock',
+      workspaceContext: false,
       toolBash: { enableRunInBackground: false },
       toolTasks: { waitTimeoutMs: 7, maxWaitTimeoutMs: 11 },
       skills: await isolatedSkillsConfig(),
@@ -145,11 +158,12 @@ describe('dsh-stdio-demo app', () => {
     expect(stdioAgent.Config).toBeDefined()
   })
 
-  it('forwards toolOrder through agent-core to the system-prompt assembly', async () => {
+  it('forwards toolOrder through agent-spine-demo to the system-prompt assembly', async () => {
     const ctx = await mount({
       model: 'mock',
       toolOrder: ['zulu', TOOL_ORDER_REST],
       persistenceRoot: '/tmp/dsh-stdio-demo-spec-tool-order',
+      workspaceContext: false,
     })
     // The bundle's own bash tools pend on the absent `ctx.bash` executor in
     // this providerless mount, so register two plain tools to order.

packages/examples/stdio-demo/tsconfig.json

@@ -32,6 +32,9 @@
     {
       "path": "../agent-spine-demo"
     },
+    {
+      "path": "../../context/workspace-context"
+    },
     {
       "path": "../../ui/user-interaction"
     },

packages/fs/README.md

@@ -1,6 +1,6 @@
 # fs/ - filesystem capability family
 
-The filesystem stack: a provider seam (text IO + atomic mutation with an optional version guard), a local implementation, a policy gate plugin (observed-state + read-before-edit + version-guarded write/edit), and the model-facing file tools + executor. All **product** packages.
+The filesystem stack: a provider seam (text IO + atomic mutation with an optional version guard), a local implementation, a policy gate plugin (observed-state + read-before-edit + version-guarded write/edit), the model-facing file tools + executor, and the bash-backed discovery tools. All **product** packages.
 
 | Package | Role | ctx key |
 |---|---|---|
@@ -8,9 +8,10 @@ The filesystem stack: a provider seam (text IO + atomic mutation with an optiona
 | `fs-local/` | Local-filesystem `FileSystem` implementation | (registers `ctx.fs`) |
 | `fs-policy/` | Policy gate plugin: observed-state + read-before-edit + version-guarded write/edit, via the `fs/*` event gate | (no service — `fs/*` listeners) |
 | `tool-fs/` | Model-facing `read`/`write`/`edit` tools AND the executor (reads via `ctx.fs`, owns read windowing, dispatches `fs/*`) | (registers on `ctx.tools`) |
+| `tool-fs-search/` | Model-facing `glob`/`grep` discovery tools, backed by fixed ripgrep commands through the bash seam (`ctx.bash`), NOT by `ctx.fs` provider methods | (registers on `ctx.tools`) |
 
-The interface lives at `fs/fs/`. A sandboxed, remote, or project-scoped filesystem backend can replace `fs-local` without touching the seam, the policy gate, or the model-facing tool schemas. The policy (`fs-policy/`) is a plugin that participates only through the `fs/*` event gate, not a service the tool injects — so dropping it gracefully loses the policy and leaves the unconstrained bare provider rather than breaking the tool. A deployment that loads `tool-fs/` is expected to also load it.
+The interface lives at `fs/fs/`. A sandboxed, remote, or project-scoped filesystem backend can replace `fs-local` without touching the seam, the policy gate, or the model-facing tool schemas. The policy (`fs-policy/`) is a plugin that participates only through the `fs/*` event gate, not a service the tool injects — so dropping it gracefully loses the policy and leaves the unconstrained bare provider rather than breaking the tool. A deployment that loads `tool-fs/` is expected to also load it. Discovery (`tool-fs-search/`) deliberately does NOT extend the provider seam: search is a process-backed `rg` workflow on the bash executor, so filesystem backends stay free of a universal search contract; its results are follow-up-readable when the bash workdir and the `read` root are the same workspace (the co-located deployment its README documents).
 
 ## No timeouts on file IO
 
-`read`/`write`/`edit` take **no** `timeoutMs`, and the provider seam arms no deadline — unlike bash and web, which consume [`@deepseek-ai/dsh-timeout`](../util/timeout/README.md). A local syscall is best-effort-abortable at most: a timeout could not force an in-progress `fsync`/`rename` to stop, so a deadline here would be a knob that cannot deliver on its promise. Adding one would also be an implicit default in the exact place explicit-over-implicit forbids. Both reference agents (Claude Code, Codex) leave file IO untimed for the same reason; cancellation still propagates through the tool-execution signal for best-effort abort at syscall boundaries.
+`read`/`write`/`edit` take **no** `timeoutMs`, and the provider seam arms no deadline — unlike bash and web (which consume [`@deepseek-ai/dsh-timeout`](../util/timeout/README.md)) and the bash-backed `glob`/`grep` (whose declared `timeoutMs` is enforced by `@deepseek-ai/dsh-timeout-policy`): those are process-backed, where a deadline can really kill the work. A local syscall is best-effort-abortable at most: a timeout could not force an in-progress `fsync`/`rename` to stop, so a deadline here would be a knob that cannot deliver on its promise. Adding one would also be an implicit default in the exact place explicit-over-implicit forbids. Both reference agents (Claude Code, Codex) leave file IO untimed for the same reason; cancellation still propagates through the tool-execution signal for best-effort abort at syscall boundaries.

packages/fs/fs-local/README.md

@@ -1,6 +1,6 @@
 # @deepseek-ai/dsh-fs-local
 
-The **local-filesystem implementation** of the `ctx.fs` provider seam ([`@deepseek-ai/dsh-fs`](../fs)). Backs the seven `FileSystem` primitives with the host filesystem; loading it as a plugin populates `ctx.fs`.
+The **local-filesystem implementation** of the `ctx.fs` provider seam ([`@deepseek-ai/dsh-fs`](../fs)). Backs the eight `FileSystem` primitives with the host filesystem; loading it as a plugin populates `ctx.fs`.
 
 ```ts ignore-check
 import { LocalFileSystem } from '@deepseek-ai/dsh-fs-local'
@@ -12,8 +12,8 @@ await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
 
 ## Behavior
 
-- **`resolve(path, opts?)`** — a relative `path` resolves against `opts.cwd` when the caller supplies one (the model-facing tools pass the calling agent's session cwd — see [the per-session cwd RFC](../../../docs/rfc/implemented/architecture/2026-07-02-fs-per-session-cwd.md)), else `config.cwd` (default `process.cwd()`); an absolute `path` ignores both. The `targetKey` is the file's `realpath`, so two input paths reaching the same file through symlinks share one identity, and writes/edits land on the link target (preserving the link). A not-yet-existing path uses the realpathed parent directory plus basename when the parent exists; only an unresolvable parent falls back to the absolute path. `displayPath` is the absolute (un-resolved) path.
-- **`stat`** — returns `FsInfo` (`version` = `mtimeMs:size`, `type` of `file`/`directory`/`other`, byte `size`) or `undefined` when the target is absent.
+- **`resolve(path, opts?)`** — a relative `path` resolves against `opts.cwd` when the caller supplies one (the model-facing tools pass the calling agent's session cwd — see [the per-session cwd RFC](../../../docs/rfc/implemented/architecture/2026-07-02-fs-per-session-cwd.md)), else `config.cwd` (default `process.cwd()`); an absolute `path` ignores both. `opts.signal` is checked before and after local resolution, while a remote sibling backend may use it to abort its round-trip. The `targetKey` is the file's `realpath`, so two input paths reaching the same file through symlinks share one identity, and writes/edits land on the link target (preserving the link). A not-yet-existing path uses the realpathed parent directory plus basename when the parent exists; only an unresolvable parent falls back to the absolute path. `displayPath` is the absolute (un-resolved) path.
+- **`stat` / `lstat`** — return target metadata or `undefined` when absent. `stat` reports `FsInfo` for an already resolved target (`version` = an opaque token derived from bigint `dev:ino:size:mtimeNs:ctimeNs`, `type` of `file`/`directory`/`other`, byte `size`); path-shaped `lstat` reports `FsPathInfo` without following the final symlink and can therefore return `symlink`. Both check cancellation before and after their asynchronous metadata probe, so an abort that lands in flight reports `FS_ABORTED` rather than stale absence.
 - **`readText` / `streamText`** — UTF-8 only. `readText` reads the whole file; `streamText` streams it in chunks (cross-chunk decoding) so a huge file never has to be held whole in memory. Both reject invalid UTF-8 and NUL-byte binary samples (`FS_NOT_TEXT`) and non-regular targets. The `read` tool (`@deepseek-ai/dsh-tool-fs`) decides which to call by size and owns the line windowing.
 - **`listDir`** — lists one directory level in stable `name.localeCompare()` order. Each entry carries the child basename, type, resolved child target (`displayPath` under the listed directory, `targetKey` as the realpath identity), and cheap stat metadata (`version`, plus `size` for regular files). It never opens or decodes file contents. Missing targets report `FS_NOT_FOUND`, file/special-file targets report `FS_NOT_DIRECTORY`, aborted calls report `FS_ABORTED`, permission failures report `FS_PERMISSION_DENIED`, and other listing or child metadata I/O failures report `FS_IO_ERROR`. Broken/disappeared children are returned as `other` without metadata, but permission/IO failures while resolving a child fail the whole listing with a structured `FsError`.
 - **`writeText`** — atomic: writes to a temp file opened exclusively (`wx`, `0o600`) inside a randomly-named private staging dir (`0o700`) next to the target, fsyncs, then renames over the target. An existing file's mode is preserved, while new files default to `0o600`. The `expected` guard is OPTIONAL: omitting it unconditionally creates-or-overwrites; `createIfAbsent` creates a missing target and rejects an existing one (`FS_NOT_OBSERVED`); `replaceIfVersion` replaces only at the observed version (a missing target or mismatch is `FS_STALE_VERSION`).

packages/fs/fs-local/src/fsio.ts

@@ -7,8 +7,8 @@
 
 import { randomUUID } from 'node:crypto'
 import { createReadStream } from 'node:fs'
-import { chmod, mkdir, open, readFile, realpath, readdir, rename, rm, stat } from 'node:fs/promises'
-import type { Dirent, Stats } from 'node:fs'
+import { chmod, lstat, mkdir, open, readFile, realpath, readdir, rename, rm, stat } from 'node:fs/promises'
+import type { BigIntStats, Dirent, Stats } from 'node:fs'
 import { basename, dirname, join, resolve } from 'node:path'
 import { TextDecoder } from 'node:util'
 import { FsError, FsTargetKey, FsVersion } from '@deepseek-ai/dsh-fs'
@@ -63,9 +63,9 @@ async function readFileAbortable(absolutePath: string, verb: 'read' | 'edit', si
   }
 }
 
-/** Opaque version token from a stat: mtime (ns precision) + size. */
-function versionOf(info: Stats): FsVersion {
-  return FsVersion(`${info.mtimeMs}:${info.size}`)
+/** Opaque version token from high-resolution identity and freshness metadata. */
+function versionOf(info: BigIntStats): FsVersion {
+  return FsVersion(`${info.dev}:${info.ino}:${info.size}:${info.mtimeNs}:${info.ctimeNs}`)
 }
 
 /**
@@ -98,6 +98,14 @@ export interface PathInfo {
   size: number
 }
 
+/** Result of probing a path without following the final symlink component. */
+export interface PathLinkInfo {
+  version: FsVersion
+  mode: number
+  type: 'file' | 'directory' | 'symlink' | 'other'
+  size: number
+}
+
 /** One local directory child with a resolved target and cheap metadata. */
 export interface LocalDirEntry {
   name: string
@@ -150,22 +158,62 @@ export async function resolveLocalTarget(cwd: string, path: string): Promise<Loc
   }
 }
 
+function pathType(info: Stats | BigIntStats): PathInfo['type'] {
+  if (info.isFile()) return 'file'
+  if (info.isDirectory()) return 'directory'
+  return 'other'
+}
+
+function pathLinkType(info: Stats | BigIntStats): PathLinkInfo['type'] {
+  if (info.isSymbolicLink()) return 'symlink'
+  return pathType(info)
+}
+
+async function probeStats<T extends Stats | BigIntStats>(
+  absolutePath: string,
+  readStats: (path: string) => Promise<T>,
+): Promise<T | null> {
+  try {
+    return await readStats(absolutePath)
+  } catch (error: unknown) {
+    // ENOENT (no such file) and ENOTDIR (a parent segment is a file) both mean
+    // the target is absent; any other metadata failure is a real permission/IO
+    // fault.
+    /* v8 ignore next -- a non-ENOENT/ENOTDIR metadata failure needs a permission/IO fault; surface it. */
+    if (!isENOENT(error) && !isENOTDIR(error)) throw error
+    return null
+  }
+}
+
 /**
  * Probe a path for its version, mode, type, and size. Null if absent.
  * @param absolutePath - the path to stat (typically a target key; symlinks are followed).
  * @returns the metadata, or null when the path — or a parent segment — does not exist.
  */
 export async function probe(absolutePath: string): Promise<PathInfo | null> {
-  try {
-    const info = await stat(absolutePath)
-    const type = info.isFile() ? 'file' : info.isDirectory() ? 'directory' : 'other'
-    return { version: versionOf(info), mode: info.mode & 0o777, type, size: info.size }
-  } catch (error: unknown) {
-    // ENOENT (no such file) and ENOTDIR (a parent segment is a file) both mean
-    // the target is absent; any other stat failure is a real permission/IO fault.
-    /* v8 ignore next -- a non-ENOENT/ENOTDIR stat failure needs a permission/IO fault; surface it. */
-    if (!isENOENT(error) && !isENOTDIR(error)) throw error
-    return null
+  const info = await probeStats(absolutePath, path => stat(path, { bigint: true }))
+  if (!info) return null
+  return {
+    version: versionOf(info),
+    mode: Number(info.mode & 0o777n),
+    type: pathType(info),
+    size: Number(info.size),
+  }
+}
+
+/**
+ * Probe a path without following the final symlink component.
+ * @param absolutePath - the path entry to inspect with `lstat` semantics.
+ * @returns path-entry metadata, or null when the entry is absent.
+ */
+export async function probeNoFollow(absolutePath: string): Promise<PathLinkInfo | null> {
+  const info = await probeStats(absolutePath, path => lstat(path, { bigint: true }))
+  if (!info) return null
+  return {
+    version: versionOf(info),
+    mode: Number(info.mode & 0o777n),
+    type: pathLinkType(info),
+    size: Number(info.size),
   }
 }
 

packages/fs/fs-local/src/index.ts

@@ -5,6 +5,7 @@
  */
 
 import { Context } from 'cordis'
+import { resolve } from 'node:path'
 import z from 'schemastery'
 import { FileSystem, FsError, FsVersion } from '@deepseek-ai/dsh-fs'
 import type {
@@ -12,6 +13,7 @@ import type {
   FsEditOutcome,
   FsEditRequest,
   FsInfo,
+  FsPathInfo,
   FsTarget,
   FsWriteIntent,
   FsWriteOutcome,
@@ -21,6 +23,7 @@ import {
   listDirectory,
   normalizeLineEndings,
   probe,
+  probeNoFollow,
   readForEdit,
   readTextForDiff,
   readWholeText,
@@ -80,14 +83,26 @@ export class LocalFileSystem extends FileSystem {
     }
   }
 
-  override async resolve(path: string, opts?: { cwd?: string }): Promise<FsTarget> {
+  override async resolve(path: string, opts?: { cwd?: string; signal?: AbortSignal }): Promise<FsTarget> {
+    if (opts?.signal?.aborted) throw new FsError('resolve aborted', 'FS_ABORTED')
     const local = await resolveLocalTarget(opts?.cwd ?? this.config.cwd, path)
+    if (opts?.signal?.aborted) throw new FsError('resolve aborted', 'FS_ABORTED')
     return { targetKey: local.targetKey, displayPath: local.displayPath }
   }
 
   override async stat(target: FsTarget, signal?: AbortSignal): Promise<FsInfo | undefined> {
     if (signal?.aborted) throw new FsError('stat aborted', 'FS_ABORTED')
     const info = await probe(target.targetKey)
+    if (signal?.aborted) throw new FsError('stat aborted', 'FS_ABORTED')
+    if (!info) return undefined
+    return { version: info.version, type: info.type, size: info.size }
+  }
+
+  override async lstat(path: string, opts?: { cwd?: string }, signal?: AbortSignal): Promise<FsPathInfo | undefined> {
+    if (signal?.aborted) throw new FsError('lstat aborted', 'FS_ABORTED')
+    if (path.trim().length === 0) throw new FsError('file_path must be a non-empty string', 'FS_NOT_FOUND')
+    const info = await probeNoFollow(resolve(opts?.cwd ?? this.config.cwd, path))
+    if (signal?.aborted) throw new FsError('lstat aborted', 'FS_ABORTED')
     if (!info) return undefined
     return { version: info.version, type: info.type, size: info.size }
   }

packages/fs/fs-local/tests/filesystem.spec.ts

@@ -6,8 +6,8 @@
  * `dsh-fs-policy`, so it is not exercised here.
  */
 
-import { afterEach, beforeEach, describe, expect, it } from 'vitest'
-import { mkdir, mkdtemp, readFile, realpath, rm, stat, symlink, writeFile, unlink } from 'node:fs/promises'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { mkdir, mkdtemp, readFile, realpath, rm, stat, symlink, unlink, utimes, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { Context } from 'cordis'
@@ -73,6 +73,18 @@ describe('resolve', () => {
     const target = await fs.resolve(join(dir, 'abs.txt'), { cwd: '/nonexistent-base' })
     expect(await fs.readText(target)).toBe('absolute')
   })
+
+  it('honors a pre-aborted signal', async () => {
+    await expect(fs.resolve('a.txt', { signal: AbortSignal.abort() })).rejects.toMatchObject({ code: 'FS_ABORTED' })
+  })
+
+  it('honors a signal aborted while resolution is in flight', async () => {
+    const controller = new AbortController()
+    const pending = fs.resolve('a.txt', { signal: controller.signal })
+    controller.abort()
+
+    await expect(pending).rejects.toMatchObject({ code: 'FS_ABORTED' })
+  })
 })
 
 describe('stat', () => {
@@ -87,11 +99,104 @@ describe('stat', () => {
     expect(await fs.stat(await fs.resolve('missing.txt'))).toBeUndefined()
   })
 
+  it('changes version after a same-size rewrite even when mtime is restored', async () => {
+    const path = join(dir, 'same-size.txt')
+    await writeFile(path, 'first')
+    const target = await fs.resolve(path)
+    const beforeInfo = await stat(path)
+    const beforeVersion = await versionOf(target)
+
+    await fs.writeText(target, 'other')
+    await utimes(path, beforeInfo.atime, beforeInfo.mtime)
+
+    expect((await stat(path)).size).toBe(beforeInfo.size)
+    expect(await versionOf(target)).not.toBe(beforeVersion)
+  })
+
   it('honors a pre-aborted signal', async () => {
     await expect(fs.stat(await fs.resolve('a.txt'), AbortSignal.abort())).rejects.toMatchObject({ code: 'FS_ABORTED' })
   })
 })
 
+describe('lstat', () => {
+  it('reports path metadata without following the final symlink component', async () => {
+    await writeFile(join(dir, 'real.txt'), 'hello')
+    await symlink(join(dir, 'real.txt'), join(dir, 'link.txt'))
+
+    expect((await fs.lstat('real.txt'))?.type).toBe('file')
+    expect((await fs.lstat('link.txt'))?.type).toBe('symlink')
+    expect(await fs.lstat('missing.txt')).toBeUndefined()
+  })
+
+  it('resolves relative paths against opts.cwd and honors a pre-aborted signal', async () => {
+    const other = await mkdtemp(join(tmpdir(), 'dsh-fs-other-'))
+    try {
+      await writeFile(join(other, 'x.txt'), 'in other')
+      expect((await fs.lstat('x.txt', { cwd: other }))?.type).toBe('file')
+      await expect(fs.lstat('x.txt', { cwd: other }, AbortSignal.abort())).rejects.toMatchObject({ code: 'FS_ABORTED' })
+      await expect(fs.lstat('   ')).rejects.toMatchObject({ code: 'FS_NOT_FOUND' })
+    } finally {
+      await rm(other, { recursive: true, force: true })
+    }
+  })
+})
+
+describe('metadata cancellation', () => {
+  it('rejects stat and lstat when their signals abort while the metadata probes are in flight', async () => {
+    await writeFile(join(dir, 'slow.txt'), 'hello')
+    const statStarted = Promise.withResolvers<undefined>()
+    const statRelease = Promise.withResolvers<undefined>()
+    const lstatStarted = Promise.withResolvers<undefined>()
+    const lstatRelease = Promise.withResolvers<undefined>()
+    let isolatedCtx: Context | undefined
+    vi.resetModules()
+    vi.doMock('node:fs/promises', async (importOriginal) => {
+      const actual = await importOriginal<typeof import('node:fs/promises')>()
+      return {
+        ...actual,
+        async stat(path: string) {
+          statStarted.resolve(undefined)
+          await statRelease.promise
+          return actual.stat(path, { bigint: true })
+        },
+        async lstat(path: string) {
+          lstatStarted.resolve(undefined)
+          await lstatRelease.promise
+          return actual.lstat(path, { bigint: true })
+        },
+      }
+    })
+
+    try {
+      const { LocalFileSystem: IsolatedLocalFileSystem } = await import('../src/index.ts')
+      isolatedCtx = new Context()
+      await isolatedCtx.plugin(IsolatedLocalFileSystem, { cwd: dir })
+      const isolatedFs = isolatedCtx.fs as InstanceType<typeof IsolatedLocalFileSystem>
+      const target = await isolatedFs.resolve('slow.txt')
+      const statController = new AbortController()
+      const lstatController = new AbortController()
+      const pendingStat = isolatedFs.stat(target, statController.signal)
+      const pendingLstat = isolatedFs.lstat('slow.txt', undefined, lstatController.signal)
+
+      await Promise.all([statStarted.promise, lstatStarted.promise])
+      statController.abort()
+      lstatController.abort()
+      const statRejected = expect(pendingStat).rejects.toMatchObject({ code: 'FS_ABORTED' })
+      const lstatRejected = expect(pendingLstat).rejects.toMatchObject({ code: 'FS_ABORTED' })
+      statRelease.resolve(undefined)
+      lstatRelease.resolve(undefined)
+
+      await Promise.all([statRejected, lstatRejected])
+    } finally {
+      statRelease.resolve(undefined)
+      lstatRelease.resolve(undefined)
+      await isolatedCtx?.fiber.dispose()
+      vi.doUnmock('node:fs/promises')
+      vi.resetModules()
+    }
+  })
+})
+
 describe('readText / streamText', () => {
   it('reads whole-file text', async () => {
     await writeFile(join(dir, 'a.txt'), 'one\ntwo\nthree')
@@ -292,9 +397,6 @@ describe('writeText', () => {
     await writeFile(join(dir, 'a.txt'), 'v1')
     const target = await fs.resolve('a.txt')
     const before = await versionOf(target)
-    // Change the byte length so the mtimeMs:size token provably differs (a
-    // same-size same-tick rewrite can collide — the documented version-token
-    // limitation; not what this test is about).
     const outcome = await fs.writeText(target, 'a much longer replacement body', { kind: 'replaceIfVersion', version: before })
     expect(outcome.version).not.toBe(before)
     expect(outcome.version).toBe(await versionOf(target))

packages/fs/fs-local/tests/fsio.spec.ts

@@ -14,6 +14,7 @@ import {
   applyLiteralEdit,
   listDirectory,
   probe,
+  probeNoFollow,
   readForEdit,
   readWholeText,
   resolveLocalTarget,
@@ -146,6 +147,27 @@ describe('probe', () => {
   })
 })
 
+describe('probeNoFollow', () => {
+  it('reports symlinks without following them', async () => {
+    const real = join(dir, 'real.txt')
+    const link = join(dir, 'link.txt')
+    await writeFile(real, 'hi')
+    await symlink(real, link)
+
+    expect((await probeNoFollow(real))?.type).toBe('file')
+    const linkInfo = await probeNoFollow(link)
+    expect(linkInfo?.type).toBe('symlink')
+    expect(typeof linkInfo?.version).toBe('string')
+    expect(linkInfo?.size).toBeGreaterThan(0)
+  })
+
+  it('returns null for a missing path or a file-valued ancestor path segment', async () => {
+    expect(await probeNoFollow(join(dir, 'missing'))).toBeNull()
+    await writeFile(join(dir, 'afile'), 'i am a file')
+    expect(await probeNoFollow(join(dir, 'afile', 'child.txt'))).toBeNull()
+  })
+})
+
 describe('listDirectory', () => {
   it('lists direct children in stable order without reading content', async () => {
     const root = join(dir, 'skills')

packages/fs/fs/README.md

@@ -1,6 +1,6 @@
 # @deepseek-ai/dsh-fs
 
-The **filesystem provider seam**: an abstract `FileSystem` service (`ctx.fs`) defining the storage primitives a backend provides — resolve a path, stat metadata, read/stream text, list directories, write atomically, and apply a literal edit — without saying HOW. Both mutations take their version guard **optionally**, so `ctx.fs` on its own is a complete, unconstrained text-storage seam. This package also owns the `fs/*` policy event vocabulary the tool dispatches and the policy plugin listens for.
+The **filesystem provider seam**: an abstract `FileSystem` service (`ctx.fs`) defining the storage primitives a backend provides — resolve a path, stat metadata, no-follow path metadata, read/stream text, list directories, write atomically, and apply a literal edit — without saying HOW. Both mutations take their version guard **optionally**, so `ctx.fs` on its own is a complete, unconstrained text-storage seam. This package also owns the `fs/*` policy event vocabulary the tool dispatches and the policy plugin listens for.
 
 This package is the provider-seam layer of the four-layer filesystem stack, split so each concern can evolve (and be swapped) independently (see [the capability-seam RFC](../../../docs/rfc/implemented/architecture/2026-06-13-capability-seams.md), [the filesystem capability-seam RFC](../../../docs/rfc/implemented/architecture/2026-06-17-filesystem-capability-seam.md), [the split-the-filesystem-seam RFC](../../../docs/rfc/implemented/simplification/2026-06-26-fsspec-style-fs-seam.md), and [the file-context event-gate RFC](../../../docs/rfc/implemented/architecture/2026-06-26-file-context-as-event-gate.md)):
 
@@ -15,12 +15,13 @@ A future sandboxed, virtual, or remote backend implements this interface and the
 
 ## Service API (`ctx.fs`)
 
-A backend subclasses `FileSystem` and implements seven primitives.
+A backend subclasses `FileSystem` and implements eight primitives.
 
 | Member | Semantics |
 |---|---|
-| `resolve(path, opts?)` | Resolve a path into a stable `FsTarget` (opaque `targetKey`, `displayPath`). `opts.cwd` is the base a relative `path` resolves against (a caller supplies its session workspace; absolute paths ignore it; omitted ⇒ the backend default). Async — a remote backend may need I/O. The same file via different paths must yield the same `targetKey`. |
+| `resolve(path, opts?)` | Resolve a path into a stable `FsTarget` (opaque `targetKey`, `displayPath`). `opts.cwd` is the base a relative `path` resolves against (a caller supplies its session workspace; absolute paths ignore it; omitted ⇒ the backend default), while `opts.signal` aborts a backend round-trip. Async — a remote backend may need I/O. The same file via different paths must yield the same `targetKey`. |
 | `stat(target, signal?)` | Return `FsInfo` metadata (`version`, `type`, optional `size`), or `undefined` when the target is absent. Never content. |
+| `lstat(path, opts?, signal?)` | Return `FsPathInfo` metadata without following the final path component when it is a symlink. This is path-shaped so consumers can reject repository-owned symlinks before `resolve` follows them into a target. |
 | `readText(target, signal?)` | Read the whole regular text file as one decoded string. Owns regular-file checks, UTF-8 decoding, binary/NUL rejection (`FS_NOT_TEXT`). |
 | `streamText(target, signal?)` | Stream the same text as decoded chunks for large files (cross-chunk UTF-8 decoding stays here). |
 | `listDir(target, signal?)` | List direct directory children in stable name order. Returns entry names, entry types, resolved child targets, and cheap metadata (`version`/file `size` when available); never reads file contents. Missing targets throw `FS_NOT_FOUND`, non-directories throw `FS_NOT_DIRECTORY`, permission failures throw `FS_PERMISSION_DENIED`, and other backend I/O failures throw `FS_IO_ERROR`. Broken/disappeared children may be returned as `other` without metadata; child permission/IO failures fail the whole listing with the same structured codes. |
@@ -41,7 +42,7 @@ This package declares three events (see the generated [events catalog](../../../
 
 ## Vocabulary
 
-`FsTargetKey` / `FsVersion` are branded opaque ids ([the branded-ids RFC](../../../docs/rfc/implemented/architecture/2026-06-20-branded-ids.md)) — consumers must not parse `targetKey` or interpret `version`; only `displayPath` is for model/UI output. `FsWriteIntent` is the explicit GUARDED write intent (`createIfAbsent` creates a missing target and rejects an existing one with `FS_NOT_OBSERVED`; `replaceIfVersion` replaces only at the observed version, else `FS_STALE_VERSION`); omitting it from `writeText` is the third, unconditional state. Failures throw `FsError` (extends `HarnessError`, [the structured error taxonomy RFC](../../../docs/rfc/implemented/architecture/2026-06-11-structured-error-taxonomy.md)) carrying a stable `FsErrorCode` (`FS_NOT_FOUND`, `FS_NOT_DIRECTORY`, `FS_NOT_TEXT`, `FS_NOT_REGULAR_FILE`, `FS_PERMISSION_DENIED`, `FS_IO_ERROR`, `FS_STALE_VERSION`, `FS_NOT_OBSERVED`, `FS_AMBIGUOUS_EDIT`, `FS_EDIT_NOT_FOUND`, `FS_ABORTED`); the tool registry surfaces `{ name, code }` on `isError` results. See `src/types.ts` for the full contracts.
+`FsTargetKey` / `FsVersion` are branded opaque ids ([the branded-ids RFC](../../../docs/rfc/implemented/architecture/2026-06-20-branded-ids.md)) — consumers must not parse `targetKey` or interpret `version`; only `displayPath` is for model/UI output. `FsWriteIntent` is the explicit GUARDED write intent (`createIfAbsent` creates a missing target and rejects an existing one with `FS_NOT_OBSERVED`; `replaceIfVersion` replaces only at the observed version, else `FS_STALE_VERSION`); omitting it from `writeText` is the third, unconditional state. `FsPathInfo` is the no-follow metadata shape that can report `symlink`, unlike target-level `FsInfo`. Failures throw `FsError` (extends `HarnessError`, [the structured error taxonomy RFC](../../../docs/rfc/implemented/architecture/2026-06-11-structured-error-taxonomy.md)) carrying a stable `FsErrorCode` (`FS_NOT_FOUND`, `FS_NOT_DIRECTORY`, `FS_NOT_TEXT`, `FS_NOT_REGULAR_FILE`, `FS_PERMISSION_DENIED`, `FS_IO_ERROR`, `FS_STALE_VERSION`, `FS_NOT_OBSERVED`, `FS_AMBIGUOUS_EDIT`, `FS_EDIT_NOT_FOUND`, `FS_ABORTED`); the tool registry surfaces `{ name, code }` on `isError` results. See `src/types.ts` for the full contracts.
 
 ## Model Experience
 
@@ -50,6 +51,6 @@ Indirectly, through `dsh-tool-fs`, which renders provider text and errors as bou
 ## Known Limitations and Deferred Work
 
 - **Text-only by contract** — backends reject binary/non-UTF-8 content with `FS_NOT_TEXT`; binary-safe operations are a deliberate deferral of [the tool-schemas RFC](../../../docs/rfc/implemented/feature/2026-06-17-filesystem-tool-schemas.md).
-- **Seven primitives only** — no delete, rename/move, copy, or watch; `listDir` is single-level, with recursion, globbing, pagination, and search out of scope per [the directory-listing RFC](../../../docs/rfc/implemented/architecture/2026-07-03-filesystem-directory-listing-seam.md).
+- **Eight primitives only** — no delete, rename/move, copy, or watch; `listDir` is single-level, with recursion, globbing, pagination, and search out of scope per [the directory-listing RFC](../../../docs/rfc/implemented/architecture/2026-07-03-filesystem-directory-listing-seam.md).
 - **No IO deadline** — the seam arms no timeout; cancellation is a best-effort optional `AbortSignal` per primitive (the deliberate [fs-family stance](../README.md)).
 - **Resolve-then-operate costs a remote backend two round-trips per tool call** — folding or caching resolution is left to such a backend.

packages/fs/fs/src/index.ts

@@ -12,6 +12,7 @@ import type {
   FsEditOutcome,
   FsEditRequest,
   FsInfo,
+  FsPathInfo,
   FsTarget,
   FsVersion,
   FsWriteIntent,
@@ -29,6 +30,7 @@ export type {
   FsDirEntry,
   FsErrorCode,
   FsInfo,
+  FsPathInfo,
   FsTarget,
   FsWriteIntent,
   FsWriteOutcome,
@@ -86,10 +88,10 @@ export abstract class FileSystem extends Service {
    * async even though the local backend only normalizes + realpaths.
    *
    * @param path - the path to resolve; relative paths resolve against `opts.cwd`.
-   * @param opts - `cwd` overrides the backend's default base for relative paths.
+   * @param opts - optional cwd override and cancellation signal.
    * @returns the stable target; the same file yields the same `targetKey`.
    */
-  abstract resolve(path: string, opts?: { cwd?: string }): Promise<FsTarget>
+  abstract resolve(path: string, opts?: { cwd?: string; signal?: AbortSignal }): Promise<FsTarget>
 
   /**
    * Return target metadata, or `undefined` when the target does not exist.
@@ -99,6 +101,22 @@ export abstract class FileSystem extends Service {
    */
   abstract stat(target: FsTarget, signal?: AbortSignal): Promise<FsInfo | undefined>
 
+  /**
+   * Return path metadata without following the final path component when it is a
+   * symbolic link. This is intentionally path-shaped, not target-shaped:
+   * {@link resolve} follows symlinks to produce the stable identity used by
+   * normal reads/writes, while `lstat` lets a consumer reject the path itself
+   * before that follow happens.
+   *
+   * `opts.cwd` follows {@link resolve}'s cwd rules. `undefined` means the path is
+   * absent.
+   * @param path - the path to inspect; relative paths resolve against `opts.cwd`.
+   * @param opts - `cwd` overrides the backend's default base for relative paths.
+   * @param signal - aborts the metadata round-trip.
+   * @returns metadata only, never content; undefined for an absent path.
+   */
+  abstract lstat(path: string, opts?: { cwd?: string }, signal?: AbortSignal): Promise<FsPathInfo | undefined>
+
   /**
    * Read the whole regular text file as a single decoded string.
    * @param target - the resolved target to read.

packages/fs/fs/src/types.ts

@@ -27,16 +27,17 @@ export function FsTargetKey(key: string): FsTargetKey {
 
 /**
  * Opaque file-version token — the freshness token a write/edit guards against.
- * The local backend derives it from mtime+size; a remote backend might use a
- * revision id. The policy layer records it for stale checks; consumers may
- * display related metadata but MUST NOT interpret this token.
+ * The local backend derives it from high-resolution stat identity and freshness
+ * fields; a remote backend might use a revision id. The policy layer records it
+ * for stale checks; consumers may display related metadata but MUST NOT
+ * interpret this token.
  */
 export type FsVersion = Branded<'FsVersion'>
 
 /**
  * Brand a string as an {@link FsVersion}. For backend use only — a consumer
  * never manufactures a version, it receives one from `stat`/write/edit outcomes.
- * @param v - the backend's raw version string (the local backend derives it from mtime+size).
+ * @param v - the backend's raw version string.
  * @returns the same string, branded; no validation is performed.
  */
 export function FsVersion(v: string): FsVersion {
@@ -72,6 +73,21 @@ export interface FsInfo {
   size?: number
 }
 
+/**
+ * Metadata about a path without following the final path component when it is a
+ * symbolic link. Unlike {@link FsInfo}, this path-level probe can report
+ * `symlink` so consumers with trust-boundary rules can reject repository-owned
+ * links before resolving a target.
+ */
+export interface FsPathInfo {
+  /** Opaque freshness token of the path entry right now. */
+  version: FsVersion
+  /** Whether the path entry is a regular file, directory, symlink, or other. */
+  type: 'file' | 'directory' | 'symlink' | 'other'
+  /** Byte size of the path entry, when the backend can report it. */
+  size?: number
+}
+
 /**
  * One direct child returned by {@link FileSystem.listDir}. Listing returns
  * metadata and resolved targets only; it must not read file contents.

packages/fs/fs/tests/service.spec.ts

@@ -13,12 +13,13 @@ import type {
   FsEditOutcome,
   FsEditRequest,
   FsInfo,
+  FsPathInfo,
   FsTarget,
   FsWriteIntent,
   FsWriteOutcome,
 } from '@deepseek-ai/dsh-fs'
 
-/** A minimal in-memory fake implementing the seven provider primitives. */
+/** A minimal in-memory fake implementing the eight provider primitives. */
 class FakeFileSystem extends FileSystem {
   files = new Map<string, string>()
 
@@ -30,6 +31,11 @@ class FakeFileSystem extends FileSystem {
     if (content === undefined) return undefined
     return { version: FsVersion('v1'), type: 'file', size: content.length }
   }
+  override async lstat(path: string): Promise<FsPathInfo | undefined> {
+    const content = this.files.get(path)
+    if (content === undefined) return undefined
+    return { version: FsVersion('v1'), type: 'file', size: content.length }
+  }
   override async readText(target: FsTarget): Promise<string> {
     const content = this.files.get(target.targetKey)
     if (content === undefined) throw new FsError(`not found: ${target.displayPath}`, 'FS_NOT_FOUND')
@@ -120,6 +126,15 @@ describe('FileSystem provider seam', () => {
     const fs = ctx.fs as FakeFileSystem
     expect(await fs.stat(await fs.resolve('missing.txt'))).toBeUndefined()
   })
+
+  it('lstat returns path metadata before resolving a target', async () => {
+    const ctx = new Context()
+    await ctx.plugin(FakeFileSystem)
+    const fs = ctx.fs as FakeFileSystem
+    fs.files.set('a.txt', 'hi')
+    expect(await fs.lstat('a.txt')).toEqual({ version: 'v1', type: 'file', size: 2 })
+    expect(await fs.lstat('missing.txt')).toBeUndefined()
+  })
 })
 
 describe('branded id factories', () => {

packages/fs/tool-fs-search/README.md

@@ -0,0 +1,90 @@
+# @deepseek-ai/dsh-tool-fs-search
+
+The **model-facing filesystem discovery tools** — `glob`, `grep` — backed by the **bash executor seam**, not by `ctx.fs` provider methods. Each call assembles a fixed ripgrep command (every model-controlled value through one package-private shell-quoting helper), runs it via `ctx.bash.resolve(request)` → `ctx.bash.run(spec)` as an ordinary foreground tool call, parses the raw `rg` output, and returns a bounded, workdir-relative result. The package injects `tools`, `systemPrompt`, and `bash` — deliberately **not** `fs`; `ctx.spillStore` is read opportunistically with `ctx.get()` because formatted-result spill is optional.
+
+```ts ignore-check
+// Default deployment: a bash executor, then the discovery tools.
+await ctx.plugin(LocalBashExecutor, { cwd: process.cwd() }) // @deepseek-ai/dsh-bash-local
+await ctx.plugin(ToolFsSearch)                              // this package — registers glob/grep
+// Optional: a spill backend makes capped results fully recoverable.
+await ctx.plugin(LocalSpillStore)                           // @deepseek-ai/dsh-spill-local
+```
+
+Why bash-backed: local workspace discovery is naturally a process-backed `rg` workflow, and putting search on `ctx.fs` would force every filesystem backend to grow a search API. The bash executor owns request defaulting/capping, subprocess execution, process-group termination, environment scrubbing, raw output capture, and backend substitution (local, sandboxed, remote); this package owns schemas, argument validation, shell quoting, parsing, retention, formatted-result spill, and timeout declaration. The tools never call `ctx.bash.start()` and never expose a bash task id — the call returns only after `rg` exits, times out, is aborted, or fails.
+
+## Deployment requirement: co-located bash + filesystem
+
+Returned paths are displayed relative to the resolved bash workdir (the calling agent's session cwd when present, else the executor's configured default) and are follow-up-readable with `read` only when the bash workdir and the filesystem root are the same workspace. v1 documents that requirement and performs no runtime cross-service validation; remote or virtual filesystem search waits for a shared workspace contract or a provider-specific search backend.
+
+## Config
+
+All keys are optional; the defaults are the shipped search caps.
+
+| Key | Default | Meaning |
+|---|---|---|
+| `globMaxResults` | `100` | Max paths one `glob` call retains inline (matches Claude Code's `GlobTool` limit); later paths go to the formatted spill artifact. |
+| `grepMaxMatches` | `250` | Max flat matches one `grep` call retains inline (matches Claude Code's `GrepTool` `head_limit`); later matches go to the formatted spill artifact. |
+| `grepMaxLineBytes` | `2000` | Byte cap per matched-line preview; the cut preserves UTF-8 boundaries and is marked `(line truncated)`. |
+| `rawOutputMaxBytes` | `20000000` | Max complete raw `rg` stdout a search will parse (matches Claude Code's ripgrep raw buffer); larger raw output fails with `SEARCH_RAW_OUTPUT_OVERFLOW`. |
+| `timeoutMs` | `30000` | Cooperative tool-call budget attached to both tool definitions, enforced by `@deepseek-ai/dsh-timeout-policy` through `exec.signal`; the bash backend's own timeout stays a second safety cap. |
+
+## Tools
+
+| Tool | Arguments | Behavior |
+|---|---|---|
+| `glob` | `pattern`, `path?` | `rg --files --glob <pattern> --sort=modified --no-ignore --hidden` plus VCS metadata excludes (`.git`, `.svn`, `.hg`, `.bzr`, `.jj`, `.sl`). `path` is an optional **directory** search root; omitted means the resolved bash workdir. Returns one path per line, modification-time ordered. |
+| `grep` | `pattern`, `path?`, `include?` | Line-oriented `rg --json` parse (no colon-splitting ambiguity). `pattern` is a ripgrep regex; `path` is an optional **file or directory** target; `include` is ONE positive glob filter — a comma-separated list or a negated (`!…`) value is rejected up front (brace alternation like `*.{ts,tsx}` is fine). Returns matches grouped by file as `Line N: <preview>`. |
+
+Routine budgets stay out of the model-facing schema (no `head_limit`/`offset`/`case_insensitive`/output modes): a model that needs surrounding context reads the matched file with `read`; one that needs later results follows the returned spill locator's retrieval hint.
+
+## Two budgets, two artifacts
+
+Raw `rg` stdout is an internal transport detail. Each search requests `stdoutMaxBytes: rawOutputMaxBytes` from the bash seam and parses only complete retained stdout; if the executor still returns `stdout.truncated`, the search fails with `SEARCH_RAW_OUTPUT_OVERFLOW` and tells the model to narrow the query. The model-facing recovery artifact is different: when a search yields more logical results than the inline cap, the tool saves the COMPLETE formatted result through `ctx.spillStore.saveText()` (suggested names `glob-results.txt` / `grep-results.txt`, owner = the calling session, source = the tool execution identity) and appends a footer naming the returned locator and retrieval hint. This is the first tool-owned spill call in the codebase — deliberate, because retention here is item-level: the generic `@deepseek-ai/dsh-spill-policy` only sees the final text on `tools/post-execute`, by which point a capped search has already omitted later paths/matches. A missing spill backend, a call with no session owner, or a `saveText()` failure keeps the inline page and reports that the complete result could not be saved — never an `isError`.
+
+## Errors
+
+Search failures carry the package-owned `SearchError` (a `HarnessError` subclass), surfaced as `{ name, code }` on `isError` results: `SEARCH_INVALID_PATTERN` (ripgrep rejected the regex/glob), `SEARCH_FAILED` (missing `rg`, inaccessible target, signal kill, malformed `--json` output), `SEARCH_RAW_OUTPUT_OVERFLOW` (raw output over `rawOutputMaxBytes`, or still truncated after the requested stdout capture budget), and `SEARCH_ABORTED` (tool timeout, caller cancellation, or the bash executor's own timeout). ripgrep exit semantics are tool-owned: exit 0 is success with results, exit 1 is a successful empty search (`No files found` / `No matches found`), and only other exits are failures. Model argument mistakes (blank pattern, a list-valued `include`) stay ordinary tool argument errors.
+
+## Model Experience
+
+### System prompt
+
+**What the model sees**: Every request in this plugin's registration scope contains the independently registered glob and grep guidance below. Agent-scoped tool restrictions can hide either schema without removing its prompt section.
+
+**Token effect**: Fixed guidance cost per request while the plugin is active.
+
+#### Glob guidance
+
+```markdown
+Use the glob tool — not shell find or ls — to discover files by path pattern. Results are sorted by modification time and include hidden and ignored files.
+```
+
+#### Grep guidance
+
+```markdown
+Use the grep tool — not shell grep or rg — to search file contents. Use read on a matched file when you need surrounding context.
+```
+
+### Tool schemas
+
+**What the model sees**: The generated [`glob` and `grep` schemas](../../../docs/tool-catalog.md#deepseek-aidsh-tool-fs-search) while this surface is visible.
+
+**Token effect**: Fixed schema cost on every request where the tools are visible.
+
+### Results and spill notices
+
+**What the model sees**: `glob` returns one path per line; `grep` groups `Line <line>: <preview>` matches beneath each path. Empty searches return `No files found` or `No matches found`. A capped result ends with its omission count plus the spill locator and backend retrieval hint, or says the complete result could not be saved.
+
+**Token effect**: Inline paths and matches are bounded by `globMaxResults`, `grepMaxMatches`, and `grepMaxLineBytes`; the call and retained result remain in history until compaction.
+
+### Tool errors
+
+**What the model sees**: Failures are normalized as `Error: <message>` with structured `SEARCH_INVALID_PATTERN`, `SEARCH_FAILED`, `SEARCH_RAW_OUTPUT_OVERFLOW`, or `SEARCH_ABORTED` metadata for callers.
+
+**Token effect**: Only a failing call adds these retained tokens.
+
+## Known Limitations and Deferred Work
+
+- **Search and file access have no shared-workspace proof** — returned paths are follow-up-readable only when the bash workdir and filesystem root denote the same workspace; the package performs no runtime cross-service validation.
+- **Ripgrep is a deployment dependency** — a missing or incompatible `rg` executable fails calls with `SEARCH_FAILED`; remote or virtual filesystems need a co-located executor or another search consumer.
+- **The schemas expose one bounded page** — offset pagination, case-mode switches, alternate output modes, and provider-backed discovery remain outside this package; capped complete output requires a spill backend.

packages/fs/tool-fs-search/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@deepseek-ai/dsh-tool-fs-search",
+  "description": "Model-facing filesystem discovery tools (glob, grep) backed by the DeepSeek Harness bash seam (ctx.bash)",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "dependencies": {
+    "schemastery": "^3.18.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-bash": "^0.0.1",
+    "@deepseek-ai/dsh-llm": "^0.0.1",
+    "@deepseek-ai/dsh-retention": "^0.0.1",
+    "@deepseek-ai/dsh-session": "^0.0.1",
+    "@deepseek-ai/dsh-spill": "^0.0.1",
+    "@deepseek-ai/dsh-system-prompt": "^0.0.1",
+    "@deepseek-ai/dsh-tools": "^0.0.1",
+    "cordis": "^4.0.0-rc.6"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-agent": "workspace:^",
+    "@deepseek-ai/dsh-bash": "workspace:^",
+    "@deepseek-ai/dsh-bash-local": "workspace:^",
+    "@deepseek-ai/dsh-llm": "workspace:^",
+    "@deepseek-ai/dsh-retention": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
+    "@deepseek-ai/dsh-spill": "workspace:^",
+    "@deepseek-ai/dsh-system-prompt": "workspace:^",
+    "@deepseek-ai/dsh-tools": "workspace:^",
+    "cordis": "^4.0.0-rc.6"
+  }
+}

packages/fs/tool-fs-search/src/glob.ts

@@ -0,0 +1,179 @@
+/**
+ * The model-facing `glob` tool: discover files whose paths match a glob
+ * pattern, sorted by modification time. Execution goes through the bash seam
+ * (`ctx.bash`) with a fixed `rg --files` command — this module owns the
+ * model-facing schema, argument validation, shell-safe command construction,
+ * result parsing, retention, and formatting; process concerns (defaulting,
+ * scrubbing, kill, backend substitution) stay behind `ctx.bash`.
+ *
+ * @module @deepseek-ai/dsh-tool-fs-search/glob
+ */
+
+import type { Context } from 'cordis'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { GenericCallView } from '@deepseek-ai/dsh-tools'
+import type { ContentBlock } from '@deepseek-ai/dsh-llm'
+import { ItemRetainer } from '@deepseek-ai/dsh-retention'
+import type { RetainedItems } from '@deepseek-ai/dsh-retention'
+import type { SpillRef } from '@deepseek-ai/dsh-spill'
+import type {} from '@deepseek-ai/dsh-bash'
+import type {} from '@deepseek-ai/dsh-system-prompt'
+import { runRipgrep, toWorkdirRelative, trySaveFormattedResult } from './search-core.ts'
+import { singleQuote } from './shell-quote.ts'
+
+/**
+ * Default cap on paths retained inline by one `glob` call (the `globMaxResults`
+ * config), matching Claude Code's default `GlobTool` result limit.
+ */
+export const GLOB_MAX_RESULTS = 100
+
+/**
+ * Directory names ripgrep must never descend into for a discovery listing: VCS
+ * metadata stores. `--no-ignore --hidden` would otherwise surface them in every
+ * broad search. Each name is excluded with TWO negated `--glob`s (see
+ * {@link buildGlobCommand}): an any-depth directory glob that matches — and
+ * prunes — the directory during traversal, and a contents glob that still
+ * excludes the internals when the search root itself is at or inside the
+ * directory (an explicit `path` of `.git` or `sub/.git`), where the prune glob
+ * alone never matches.
+ */
+export const GLOB_VCS_EXCLUDES: readonly string[] = ['.git', '.svn', '.hg', '.bzr', '.jj', '.sl']
+
+/** Resolved glob-tool caps — plugin config after defaulting (see `Config` in index.ts). */
+export interface GlobToolCaps {
+  /** Max paths retained inline; later paths go to the formatted spill file. */
+  maxResults: number
+  /** Cap on the complete raw `rg` stdout the tool will parse. */
+  rawOutputMaxBytes: number
+  /** Cooperative tool-call budget (ms) attached as `ToolDefinition.timeoutMs`. */
+  timeoutMs: number
+}
+
+/** Validated `glob` arguments. */
+export interface GlobInput {
+  pattern: string
+  path?: string
+}
+
+/**
+ * Validate value constraints the schema DSL can't express: a non-blank
+ * `pattern`, and a non-blank `path` when given. Throws a plain `Error` (an
+ * ordinary tool argument error) otherwise.
+ *
+ * @param args - the schema-validated `glob` arguments.
+ * @returns the accepted input, unchanged.
+ */
+export function parseGlobArgs(args: { pattern: string; path?: string }): GlobInput {
+  if (args.pattern.trim().length === 0) throw new Error('pattern must be a non-empty string')
+  if (args.path !== undefined && args.path.trim().length === 0) throw new Error('path must be a non-empty string when given')
+  return { pattern: args.pattern, ...args.path !== undefined ? { path: args.path } : {} }
+}
+
+/**
+ * Build the fixed `rg --files` command for one `glob` call. Every
+ * model-controlled value ({@link GlobInput.pattern}, {@link GlobInput.path})
+ * passes through {@link singleQuote}; the search root rides behind `--` so a
+ * leading-dash path can never be parsed as a flag. `--sort=modified` orders by
+ * modification time, `--no-ignore --hidden` searches ignored and hidden files,
+ * and {@link GLOB_VCS_EXCLUDES} keeps VCS metadata out.
+ *
+ * @param input - the validated arguments.
+ * @returns the complete, shell-safe command string.
+ */
+export function buildGlobCommand(input: GlobInput): string {
+  const parts = [
+    'rg --files',
+    `--glob=${singleQuote(input.pattern)}`,
+    '--sort=modified --no-ignore --hidden',
+    // Two negated globs per VCS name: the bare form prunes the directory
+    // during traversal; the /** form still excludes the contents when the
+    // search root is AT or INSIDE the directory (where the bare form,
+    // matched against root-prefixed paths, never fires).
+    ...GLOB_VCS_EXCLUDES.flatMap(name => [
+      `--glob=${singleQuote(`!**/${name}`)}`,
+      `--glob=${singleQuote(`!**/${name}/**`)}`,
+    ]),
+  ]
+  if (input.path !== undefined) parts.push('--', singleQuote(input.path))
+  return parts.join(' ')
+}
+
+/**
+ * Format the model-facing `glob` result: the retained paths, then — when the
+ * result was capped — a footer carrying either the formatted-spill recovery
+ * locator or the could-not-save explanation. The omitted count is a budget fact:
+ * the search itself completed.
+ *
+ * @param retained - the retention outcome over every discovered path.
+ * @param spillRef - the saved complete-result reference, or `undefined` when unsaved.
+ * @returns the model-facing text.
+ */
+export function formatGlobOutput(retained: RetainedItems<string>, spillRef: SpillRef | undefined): string {
+  const body = retained.items.join('\n')
+  if (!retained.truncated) return body
+  const recovery = spillRef !== undefined
+    ? `Full sorted result stored at: ${spillRef.locator}. ${spillRef.retrievalHint}`
+    : 'The complete result could not be saved; narrow pattern or path to see more.'
+  return `${body}\n\n(Showing ${retained.kept} of ${retained.seen} paths. ${recovery})`
+}
+
+/**
+ * Pending-call presentation: a search card titled by the pattern (and root).
+ *
+ * @param args - the raw tool arguments; `pattern` and `path` feed the title.
+ * @returns the generic card view (`kind: 'search'`) shown while the call runs.
+ */
+export function presentGlobCall(args: { pattern: string; path?: string }): GenericCallView {
+  const where = args.path !== undefined ? ` in ${args.path}` : ''
+  return { card: 'generic', title: `Glob ${args.pattern}${where}`, kind: 'search', rawInput: args.pattern }
+}
+
+/**
+ * Register the `glob` tool and its system-prompt guidance.
+ *
+ * @param ctx - the plugin context; registrations are effects scoped to it, and
+ *   execution uses its `bash` service.
+ * @param caps - the deployment's resolved glob caps (plugin config after defaulting).
+ */
+export function applyGlobTool(ctx: Context, caps: GlobToolCaps): void {
+  ctx.systemPrompt.section({
+    name: 'tool:glob',
+    order: 103,
+    text: 'Use the glob tool — not shell find or ls — to discover files by path pattern. Results are sorted by modification time and include hidden and ignored files.',
+  })
+
+  ctx.tools.register(defineTool({
+    name: 'glob',
+    description: 'Find files whose paths match a glob pattern. Returns matching paths sorted by modification time, '
+      + 'including hidden and ignored files (VCS metadata directories are excluded). '
+      + `Returns the first ${caps.maxResults} paths inline; a capped result reports where the complete list was saved.`,
+    parameters: {
+      pattern: { type: 'string', required: true, description: 'Glob pattern to match file paths against (e.g. "**/*.ts", "src/**/*.test.js").' },
+      path: { type: 'string', description: 'Directory to search in. Defaults to the session workspace; a relative path resolves against it.' },
+    },
+    timeoutMs: caps.timeoutMs,
+    async execute(args, exec): Promise<ContentBlock[]> {
+      const input = parseGlobArgs(args)
+      const run = await runRipgrep(ctx, exec, 'glob', buildGlobCommand(input), caps.rawOutputMaxBytes)
+      if (run.noMatches) return [{ type: 'text', text: 'No files found' }]
+
+      const retainer = new ItemRetainer<string>({ kind: 'head', maxItems: caps.maxResults })
+      const all: string[] = []
+      for (const line of run.stdout.split('\n')) {
+        if (line.length === 0) continue
+        const displayPath = toWorkdirRelative(line, run.workdir)
+        all.push(displayPath)
+        retainer.push(displayPath)
+      }
+      const retained = retainer.finish()
+
+      // The complete sorted list is the recovery artifact; save it only when
+      // the inline page omitted paths (an uncapped result needs no spill file).
+      const spillRef = retained.truncated
+        ? await trySaveFormattedResult(ctx, exec, 'glob-results.txt', all.join('\n'))
+        : undefined
+      return [{ type: 'text', text: formatGlobOutput(retained, spillRef) }]
+    },
+    presentCall: presentGlobCall,
+  }))
+}

packages/fs/tool-fs-search/src/grep.ts

@@ -0,0 +1,315 @@
+/**
+ * The model-facing `grep` tool: search file contents with a ripgrep regular
+ * expression. Execution goes through the bash seam (`ctx.bash`) with a fixed
+ * line-oriented `rg --json` command so file path, line number, and line text
+ * parse without colon-splitting ambiguity — this module owns the model-facing
+ * schema, argument validation, shell-safe command construction, `--json`
+ * record parsing, per-line preview retention, match retention, grouping, and
+ * formatting; process concerns stay behind `ctx.bash`.
+ *
+ * @module @deepseek-ai/dsh-tool-fs-search/grep
+ */
+
+import type { Context } from 'cordis'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { GenericCallView } from '@deepseek-ai/dsh-tools'
+import type { ContentBlock } from '@deepseek-ai/dsh-llm'
+import { ItemRetainer, TextRetainer } from '@deepseek-ai/dsh-retention'
+import type { RetainedItems } from '@deepseek-ai/dsh-retention'
+import type { SpillRef } from '@deepseek-ai/dsh-spill'
+import type {} from '@deepseek-ai/dsh-bash'
+import type {} from '@deepseek-ai/dsh-system-prompt'
+import { SearchError, runRipgrep, toWorkdirRelative, trySaveFormattedResult } from './search-core.ts'
+import { singleQuote } from './shell-quote.ts'
+
+/**
+ * Default cap on flat matches retained inline by one `grep` call (the
+ * `grepMaxMatches` config), matching Claude Code's default `GrepTool`
+ * `head_limit`.
+ */
+export const GREP_MAX_MATCHES = 250
+
+/**
+ * Default cap in bytes on one matched-line preview (the `grepMaxLineBytes`
+ * config); the cut preserves UTF-8 boundaries.
+ */
+export const GREP_MAX_LINE_BYTES = 2000
+
+/** Resolved grep-tool caps — plugin config after defaulting (see `Config` in index.ts). */
+export interface GrepToolCaps {
+  /** Max flat matches retained inline; later matches go to the formatted spill file. */
+  maxMatches: number
+  /** Max bytes retained per matched-line preview. */
+  maxLineBytes: number
+  /** Cap on the complete raw `rg` stdout the tool will parse. */
+  rawOutputMaxBytes: number
+  /** Cooperative tool-call budget (ms) attached as `ToolDefinition.timeoutMs`. */
+  timeoutMs: number
+}
+
+/** Validated `grep` arguments. */
+export interface GrepInput {
+  pattern: string
+  path?: string
+  include?: string
+}
+
+/** One parsed match: the file, the 1-based line number, and the (possibly previewed) line text. */
+export interface GrepMatch {
+  path: string
+  lineNumber: number
+  line: string
+}
+
+/**
+ * Reject an `include` that is not ONE positive glob filter: blank strings,
+ * negated patterns (`!…`), and comma-separated lists. A comma inside a brace
+ * group is fine — `*.{ts,tsx}` is one glob with alternation, not a list.
+ */
+function validateInclude(include: string): void {
+  if (include.trim().length === 0) throw new Error('include must be a non-empty glob when given')
+  if (include.startsWith('!')) throw new Error('include must be a positive glob filter; negated patterns ("!…") are not supported')
+  let braceDepth = 0
+  for (const char of include) {
+    if (char === '{') braceDepth++
+    else if (char === '}') braceDepth = Math.max(0, braceDepth - 1)
+    else if (char === ',' && braceDepth === 0) {
+      throw new Error('include must be one glob, not a comma-separated list (use {a,b} alternation instead)')
+    }
+  }
+}
+
+/**
+ * Validate value constraints the schema DSL can't express: a non-EMPTY
+ * `pattern` (whitespace is a legitimate regex), a non-blank `path` when given,
+ * and a single positive `include` glob ({@link GrepInput}). Throws a plain
+ * `Error` (an ordinary tool argument error) otherwise.
+ *
+ * @param args - the schema-validated `grep` arguments.
+ * @returns the accepted input, unchanged.
+ */
+export function parseGrepArgs(args: { pattern: string; path?: string; include?: string }): GrepInput {
+  if (args.pattern.length === 0) throw new Error('pattern must be a non-empty string')
+  if (args.path !== undefined && args.path.trim().length === 0) throw new Error('path must be a non-empty string when given')
+  if (args.include !== undefined) validateInclude(args.include)
+  return {
+    pattern: args.pattern,
+    ...args.path !== undefined ? { path: args.path } : {},
+    ...args.include !== undefined ? { include: args.include } : {},
+  }
+}
+
+/**
+ * Build the fixed line-oriented `rg --json` command for one `grep` call. Every
+ * model-controlled value ({@link GrepInput.pattern}, {@link GrepInput.path},
+ * {@link GrepInput.include}) passes through {@link singleQuote}; the pattern
+ * and include ride in `--flag=value` form and the target behind `--`, so a
+ * leading-dash value can never be parsed as a flag.
+ *
+ * @param input - the validated arguments.
+ * @returns the complete, shell-safe command string.
+ */
+export function buildGrepCommand(input: GrepInput): string {
+  const parts = ['rg --json', `--regexp=${singleQuote(input.pattern)}`]
+  if (input.include !== undefined) parts.push(`--glob=${singleQuote(input.include)}`)
+  if (input.path !== undefined) parts.push('--', singleQuote(input.path))
+  return parts.join(' ')
+}
+
+/**
+ * The uniform malformed-output failure: raw `rg --json` is an internal
+ * transport, so a shape surprise is a search failure, not a partial result.
+ */
+function malformedRecord(detail: string, cause?: unknown): SearchError {
+  return new SearchError(`grep received malformed ripgrep --json output (${detail})`, 'SEARCH_FAILED', cause !== undefined ? { cause } : undefined)
+}
+
+/**
+ * Parse one `rg --json` NDJSON line into a match, `undefined` for the
+ * non-match record types (`begin`/`end`/`context`/`summary`). A line that is
+ * not JSON, or a `match` record missing its path / line number / line content,
+ * throws {@link SearchError} `SEARCH_FAILED`. A match whose line is not valid
+ * UTF-8 (ripgrep sends base64 `bytes` instead of `text`) yields a placeholder
+ * preview rather than failing the whole search.
+ */
+function parseRecord(line: string): GrepMatch | undefined {
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(line)
+  } catch (error: unknown) {
+    throw malformedRecord('a line is not JSON', error)
+  }
+  if (typeof parsed !== 'object' || parsed === null) throw malformedRecord('a record is not an object')
+  const record = parsed as { type?: unknown; data?: unknown }
+  // Non-match record types (begin/end/context/summary — and any future type)
+  // are transport framing, not results: skipped, not malformed.
+  if (record.type !== 'match') return undefined
+  if (typeof record.data !== 'object' || record.data === null) throw malformedRecord('a match record has no data')
+  const data = record.data as { path?: unknown; line_number?: unknown; lines?: unknown }
+  const pathText = typeof data.path === 'object' && data.path !== null ? (data.path as { text?: unknown }).text : undefined
+  if (typeof pathText !== 'string') throw malformedRecord('a match record has no path text')
+  if (typeof data.line_number !== 'number') throw malformedRecord('a match record has no line number')
+  if (typeof data.lines !== 'object' || data.lines === null) throw malformedRecord('a match record has no line content')
+  const lines = data.lines as { text?: unknown; bytes?: unknown }
+  if (typeof lines.text === 'string') {
+    return { path: pathText, lineNumber: data.line_number, line: lines.text.replace(/\r?\n$/, '') }
+  }
+  if (typeof lines.bytes === 'string') {
+    return { path: pathText, lineNumber: data.line_number, line: '(line is not valid UTF-8)' }
+  }
+  throw malformedRecord('a match record has neither line text nor bytes')
+}
+
+/**
+ * Parse complete `rg --json` stdout into flat matches, in output order (ripgrep
+ * emits one file's matches contiguously). Only `match` records are consumed.
+ *
+ * @param stdout - the complete raw `rg --json` stdout.
+ * @returns the flat matches; empty for output with no match records.
+ */
+export function parseGrepMatches(stdout: string): GrepMatch[] {
+  const matches: GrepMatch[] = []
+  for (const line of stdout.split('\n')) {
+    if (line.length === 0) continue
+    const match = parseRecord(line)
+    if (match !== undefined) matches.push(match)
+  }
+  return matches
+}
+
+/**
+ * Bound one matched-line preview to `maxBytes` (UTF-8 boundary preserved) and
+ * mark the cut. The cap is a per-line budget fact; the complete line stays in
+ * the searched file for `read`.
+ *
+ * @param line - the matched line text (trailing newline already stripped).
+ * @param maxBytes - the preview budget in bytes.
+ * @returns the preview, suffixed with ` (line truncated)` when bytes were cut.
+ */
+export function previewLine(line: string, maxBytes: number): string {
+  const retainer = new TextRetainer({ kind: 'head', maxBytes })
+  retainer.push(line)
+  const kept = retainer.finish()
+  return kept.truncated ? `${kept.text} (line truncated)` : kept.text
+}
+
+/** `match` / `matches` for a count. */
+function matchNoun(count: number): string {
+  return count === 1 ? 'match' : 'matches'
+}
+
+/**
+ * Group flat matches by file (first-seen order) into the model-facing body:
+ * each file's display path, then one `Line N: <text>` row per match.
+ *
+ * @param matches - the flat matches to render.
+ * @returns the grouped body text.
+ */
+export function formatGrepMatches(matches: GrepMatch[]): string {
+  const byFile = new Map<string, GrepMatch[]>()
+  for (const match of matches) {
+    const group = byFile.get(match.path)
+    if (group !== undefined) group.push(match)
+    else byFile.set(match.path, [match])
+  }
+  const sections: string[] = []
+  for (const [path, group] of byFile) {
+    sections.push(`${path}\n${group.map(m => `Line ${m.lineNumber}: ${m.line}`).join('\n')}`)
+  }
+  return sections.join('\n\n')
+}
+
+/**
+ * Format the model-facing `grep` result: a found-count header, the retained
+ * matches grouped by file, then — when the result was capped — a footer
+ * carrying either the formatted-spill recovery locator or the could-not-save
+ * explanation. The omitted count is a budget fact: the search itself completed.
+ *
+ * @param retained - the retention outcome over every parsed match.
+ * @param spillRef - the saved complete-result reference, or `undefined` when unsaved.
+ * @returns the model-facing text.
+ */
+export function formatGrepOutput(retained: RetainedItems<GrepMatch>, spillRef: SpillRef | undefined): string {
+  const header = retained.truncated
+    ? `Found ${retained.kept} of ${retained.seen} matches`
+    : `Found ${retained.seen} ${matchNoun(retained.seen)}`
+  const body = formatGrepMatches(retained.items)
+  if (!retained.truncated) return `${header}\n\n${body}`
+  const recovery = spillRef !== undefined
+    ? `Full grep result stored at: ${spillRef.locator}. ${spillRef.retrievalHint}`
+    : 'The complete result could not be saved; narrow pattern, path, or include to see more.'
+  return `${header}\n\n${body}\n\n(${recovery})`
+}
+
+/**
+ * Pending-call presentation: a search card titled by the pattern (and target /
+ * include filter).
+ *
+ * @param args - the raw tool arguments; `pattern`, `path`, and `include` feed the title.
+ * @returns the generic card view (`kind: 'search'`) shown while the call runs.
+ */
+export function presentGrepCall(args: { pattern: string; path?: string; include?: string }): GenericCallView {
+  const where = args.path !== undefined ? ` in ${args.path}` : ''
+  const filter = args.include !== undefined ? ` (${args.include})` : ''
+  return { card: 'generic', title: `Grep ${args.pattern}${where}${filter}`, kind: 'search', rawInput: args.pattern }
+}
+
+/**
+ * Register the `grep` tool and its system-prompt guidance.
+ *
+ * @param ctx - the plugin context; registrations are effects scoped to it, and
+ *   execution uses its `bash` service.
+ * @param caps - the deployment's resolved grep caps (plugin config after defaulting).
+ */
+export function applyGrepTool(ctx: Context, caps: GrepToolCaps): void {
+  ctx.systemPrompt.section({
+    name: 'tool:grep',
+    order: 104,
+    text: 'Use the grep tool — not shell grep or rg — to search file contents. Use read on a matched file when you need surrounding context.',
+  })
+
+  ctx.tools.register(defineTool({
+    name: 'grep',
+    description: 'Search file contents with a ripgrep regular expression. Returns matching lines with line numbers, grouped by file. '
+      + `Returns the first ${caps.maxMatches} matches inline; a capped result reports where the complete match list was saved. `
+      + 'Use read on a matched file for surrounding context.',
+    parameters: {
+      pattern: { type: 'string', required: true, description: 'Regular expression to search for (ripgrep syntax).' },
+      path: { type: 'string', description: 'File or directory to search. Defaults to the session workspace; a relative path resolves against it.' },
+      include: { type: 'string', description: 'One glob filter for which files to search (e.g. "*.ts", "*.{js,jsx}"). Not a list; negation is not supported.' },
+    },
+    timeoutMs: caps.timeoutMs,
+    async execute(args, exec): Promise<ContentBlock[]> {
+      const input = parseGrepArgs(args)
+      const run = await runRipgrep(ctx, exec, 'grep', buildGrepCommand(input), caps.rawOutputMaxBytes)
+      if (run.noMatches) return [{ type: 'text', text: 'No matches found' }]
+
+      const retainer = new ItemRetainer<GrepMatch>({ kind: 'head', maxItems: caps.maxMatches })
+      const all: GrepMatch[] = []
+      for (const raw of parseGrepMatches(run.stdout)) {
+        const match: GrepMatch = {
+          path: toWorkdirRelative(raw.path, run.workdir),
+          lineNumber: raw.lineNumber,
+          line: previewLine(raw.line, caps.maxLineBytes),
+        }
+        all.push(match)
+        retainer.push(match)
+      }
+      const retained = retainer.finish()
+
+      // The spill file stores the FULL formatted match list (same grouped,
+      // per-line-previewed shape the model saw), so read offset/limit pages the
+      // same logical result; save only when the inline page omitted matches.
+      const spillRef = retained.truncated
+        ? await trySaveFormattedResult(
+          ctx,
+          exec,
+          'grep-results.txt',
+          `Found ${all.length} ${matchNoun(all.length)}\n\n${formatGrepMatches(all)}`,
+        )
+        : undefined
+      return [{ type: 'text', text: formatGrepOutput(retained, spillRef) }]
+    },
+    presentCall: presentGrepCall,
+  }))
+}

packages/fs/tool-fs-search/src/index.ts

@@ -0,0 +1,110 @@
+/**
+ * The model-facing filesystem discovery tool suite (`glob`, `grep`) over the
+ * bash executor seam (`ctx.bash`). This single plugin registers both tools.
+ *
+ * ## Bash-backed, not a `ctx.fs` provider method
+ *
+ * Local workspace discovery is a process-backed `rg` workflow, so these tools
+ * execute through `ctx.bash.resolve(request)` → `ctx.bash.run(spec)` with fixed
+ * ripgrep command templates — never `ctx.bash.start()`, never a model-visible
+ * background task. The tool layer owns schemas, argument validation, shell
+ * quoting ({@link module:@deepseek-ai/dsh-tool-fs-search/shell-quote}), result
+ * parsing, retention, formatted-result spill, and timeout declaration; the
+ * bash executor owns request defaulting/capping, subprocess execution,
+ * process-group termination, environment scrubbing, raw output capture, and
+ * backend substitution. The package injects `tools`, `systemPrompt`, and
+ * `bash` — deliberately NOT `fs`, and `ctx.spillStore` is read opportunistically
+ * with `ctx.get()` because formatted-result spill is optional.
+ *
+ * Returned paths are displayed relative to the resolved bash workdir and are
+ * follow-up-readable only in co-located deployments where the bash workdir and
+ * the filesystem `read` root are the same workspace — a documented v1
+ * deployment requirement, not runtime-validated.
+ *
+ * @module @deepseek-ai/dsh-tool-fs-search
+ */
+
+import type { Context } from 'cordis'
+import z from 'schemastery'
+import { GLOB_MAX_RESULTS, applyGlobTool } from './glob.ts'
+import { GREP_MAX_LINE_BYTES, GREP_MAX_MATCHES, applyGrepTool } from './grep.ts'
+import { RAW_OUTPUT_MAX_BYTES, SEARCH_TIMEOUT_MS } from './search-core.ts'
+
+export { GLOB_MAX_RESULTS, GLOB_VCS_EXCLUDES, applyGlobTool, buildGlobCommand, formatGlobOutput, parseGlobArgs, presentGlobCall } from './glob.ts'
+export type { GlobInput, GlobToolCaps } from './glob.ts'
+export {
+  GREP_MAX_LINE_BYTES,
+  GREP_MAX_MATCHES,
+  applyGrepTool,
+  buildGrepCommand,
+  formatGrepMatches,
+  formatGrepOutput,
+  parseGrepArgs,
+  parseGrepMatches,
+  presentGrepCall,
+  previewLine,
+} from './grep.ts'
+export type { GrepInput, GrepMatch, GrepToolCaps } from './grep.ts'
+export { RAW_OUTPUT_MAX_BYTES, SEARCH_TIMEOUT_MS, SearchError, runRipgrep, toWorkdirRelative, trySaveFormattedResult } from './search-core.ts'
+export type { RipgrepRun, SearchErrorCode } from './search-core.ts'
+export { singleQuote } from './shell-quote.ts'
+
+/** Cordis plugin name used by loader diagnostics. */
+export const name = 'tool-fs-search'
+
+/** Services required by the search tool suite (`spillStore` is optional, read via `ctx.get()`). */
+export const inject = ['tools', 'systemPrompt', 'bash']
+
+/** Plugin config (all optional — `Config` supplies the defaults). */
+export interface Config {
+  /** Max paths one `glob` call retains inline; later paths go to the formatted spill file. */
+  globMaxResults?: number
+  /** Max flat matches one `grep` call retains inline; later matches go to the formatted spill file. */
+  grepMaxMatches?: number
+  /** Max bytes retained for one matched-line preview (the cut preserves UTF-8 boundaries). */
+  grepMaxLineBytes?: number
+  /** Max complete raw `rg` stdout bytes a search will parse; larger raw output fails with `SEARCH_RAW_OUTPUT_OVERFLOW`. */
+  rawOutputMaxBytes?: number
+  /** Cooperative tool-call timeout budget (ms) on both tools, enforced by `@deepseek-ai/dsh-timeout-policy` through `exec.signal`. */
+  timeoutMs?: number
+}
+
+export const Config: z<Config> = z.object({
+  globMaxResults: z.number().default(GLOB_MAX_RESULTS),
+  grepMaxMatches: z.number().default(GREP_MAX_MATCHES),
+  grepMaxLineBytes: z.number().default(GREP_MAX_LINE_BYTES),
+  rawOutputMaxBytes: z.number().default(RAW_OUTPUT_MAX_BYTES),
+  timeoutMs: z.number().default(SEARCH_TIMEOUT_MS),
+})
+
+/** The shape after schemastery applied the defaults. */
+type ResolvedConfig = Required<Config>
+
+/** Every search cap counts items/bytes/milliseconds — a positive integer, or retention and timeout arithmetic misbehaves silently. */
+function assertPositiveInteger(name: string, value: number): void {
+  if (!Number.isInteger(value) || value < 1) {
+    throw new Error(`tool-fs-search: ${name} must be a positive integer`)
+  }
+}
+
+/** Register the `glob`/`grep` filesystem discovery tool suite. */
+export function apply(ctx: Context, config: Config): void {
+  // schemastery (Config) has already filled every defaulted field.
+  const resolved = config as ResolvedConfig
+  assertPositiveInteger('globMaxResults', resolved.globMaxResults)
+  assertPositiveInteger('grepMaxMatches', resolved.grepMaxMatches)
+  assertPositiveInteger('grepMaxLineBytes', resolved.grepMaxLineBytes)
+  assertPositiveInteger('rawOutputMaxBytes', resolved.rawOutputMaxBytes)
+  assertPositiveInteger('timeoutMs', resolved.timeoutMs)
+  applyGlobTool(ctx, {
+    maxResults: resolved.globMaxResults,
+    rawOutputMaxBytes: resolved.rawOutputMaxBytes,
+    timeoutMs: resolved.timeoutMs,
+  })
+  applyGrepTool(ctx, {
+    maxMatches: resolved.grepMaxMatches,
+    maxLineBytes: resolved.grepMaxLineBytes,
+    rawOutputMaxBytes: resolved.rawOutputMaxBytes,
+    timeoutMs: resolved.timeoutMs,
+  })
+}

packages/fs/tool-fs-search/src/search-core.ts

@@ -0,0 +1,262 @@
+/**
+ * Shared execution plumbing for the `glob` / `grep` search tools: the
+ * package-owned `SEARCH_*` error vocabulary, one bash-seam run helper that
+ * turns a fixed `rg` command into complete raw stdout, the best-effort
+ * formatted-result spill handoff, and workdir-relative path display.
+ *
+ * Both tools execute through `ctx.bash.resolve(request)` → `ctx.bash.run(spec)`
+ * as ordinary foreground tool calls — never `ctx.bash.start()`, never a
+ * model-visible background task. Raw `rg` stdout is an internal transport
+ * detail: the tools request a per-run stdout capture budget from the bash seam,
+ * parse only complete in-memory stdout within `rawOutputMaxBytes`, and never
+ * read executor spill files. The model-facing recovery artifact is the
+ * formatted result saved through `ctx.spillStore.saveText()`
+ * ({@link trySaveFormattedResult}).
+ *
+ * @module @deepseek-ai/dsh-tool-fs-search/search-core
+ */
+
+import { isAbsolute, relative, sep } from 'node:path'
+import type { Context } from 'cordis'
+import { HarnessError } from '@deepseek-ai/dsh-llm'
+import type { BashRunResult, CollectedOutput } from '@deepseek-ai/dsh-bash'
+import type { SaveTextSpill, SpillRef } from '@deepseek-ai/dsh-spill'
+import type { ToolExecution } from '@deepseek-ai/dsh-tools'
+
+/**
+ * Default cap on the complete raw `rg` stdout the tools will parse (the
+ * `rawOutputMaxBytes` config), matching Claude Code's ripgrep raw buffer.
+ */
+export const RAW_OUTPUT_MAX_BYTES = 20_000_000
+
+/**
+ * Default cooperative tool-call timeout budget in milliseconds (the `timeoutMs`
+ * config), attached to both tool definitions for
+ * `@deepseek-ai/dsh-timeout-policy` to enforce through `exec.signal`.
+ */
+export const SEARCH_TIMEOUT_MS = 30_000
+
+/**
+ * Stable, machine-routable codes for search failures. Package-owned (not
+ * `FsErrorCode`) because these tools are bash-backed discovery, not `ctx.fs`
+ * provider operations: `SEARCH_INVALID_PATTERN` — ripgrep rejected the regex or
+ * glob; `SEARCH_FAILED` — the search could not run or its output could not be
+ * parsed (missing `rg`, inaccessible target, signal kill, malformed `--json`);
+ * `SEARCH_RAW_OUTPUT_OVERFLOW` — raw `rg` output exceeded `rawOutputMaxBytes`
+ * or stayed truncated after that requested stdout budget; `SEARCH_ABORTED` — the tool
+ * timeout, caller cancellation, or the bash executor's own timeout cut the
+ * search short.
+ */
+export type SearchErrorCode =
+  | 'SEARCH_INVALID_PATTERN'
+  | 'SEARCH_FAILED'
+  | 'SEARCH_RAW_OUTPUT_OVERFLOW'
+  | 'SEARCH_ABORTED'
+
+/**
+ * Typed search failure. Extends {@link HarnessError} so it carries a stable
+ * {@link SearchErrorCode} and chains `cause`; the tool registry surfaces
+ * `{ name, code }` on `isError` results so retry/permission/UI layers can
+ * branch without parsing messages.
+ */
+export class SearchError extends HarnessError {
+  override readonly code: SearchErrorCode
+
+  constructor(message: string, code: SearchErrorCode, options?: ErrorOptions) {
+    super(message, code, options)
+    this.code = code
+  }
+}
+
+/** The completed acquisition of one `rg` run: complete stdout plus the resolved workdir. */
+export interface RipgrepRun {
+  /** Complete raw stdout retained by the bash executor within the requested cap. */
+  stdout: string
+  /** True when ripgrep exited 1: a successful search with zero results. */
+  noMatches: boolean
+  /** The resolved working directory the command ran in (the display-relativization base). */
+  workdir: string
+}
+
+/**
+ * The retained stderr tail as a diagnostic excerpt, with a truncation note when
+ * the executor dropped bytes (the tool never reads `stderr.spillPath`).
+ */
+function stderrExcerpt(stderr: CollectedOutput): string {
+  const text = stderr.text.trim()
+  if (text.length === 0) return ''
+  return stderr.truncated ? `${text} [stderr truncated]` : text
+}
+
+/** Classify a nonzero-exit `rg` run into the search error vocabulary (invalid pattern vs missing `rg` vs everything else). */
+function classifyRunFailure(toolName: string, result: BashRunResult): SearchError {
+  const stderr = stderrExcerpt(result.stderr)
+  if (/regex parse error|error parsing glob/i.test(stderr)) {
+    return new SearchError(`${toolName} pattern rejected by ripgrep: ${stderr}`, 'SEARCH_INVALID_PATTERN')
+  }
+  if (result.exitCode === 127 || /command not found/i.test(stderr)) {
+    return new SearchError(`${toolName} requires ripgrep (rg) on the bash executor's PATH${stderr.length > 0 ? `: ${stderr}` : ''}`, 'SEARCH_FAILED')
+  }
+  return new SearchError(`${toolName} search failed (exit ${result.exitCode})${stderr.length > 0 ? `: ${stderr}` : ''}`, 'SEARCH_FAILED')
+}
+
+/**
+ * Acquire the COMPLETE raw stdout of a finished run, enforcing
+ * `rawOutputMaxBytes` on the in-memory transport. A truncated result means the
+ * bash backend could not retain complete stdout within the requested budget, so
+ * the tool fails clearly instead of parsing a silently-partial stream.
+ */
+function completeStdout(toolName: string, result: BashRunResult, rawOutputMaxBytes: number): string {
+  const narrow = 'narrow pattern, path, or include and retry'
+  if (!result.stdout.truncated) {
+    const inlineBytes = Buffer.byteLength(result.stdout.text, 'utf8')
+    if (inlineBytes > rawOutputMaxBytes) {
+      throw new SearchError(
+        `${toolName} produced ${inlineBytes} bytes of raw output, over the ${rawOutputMaxBytes}-byte cap; ${narrow}`,
+        'SEARCH_RAW_OUTPUT_OVERFLOW',
+      )
+    }
+    return result.stdout.text
+  }
+  throw new SearchError(
+    `${toolName} produced more raw output than the bash executor retained within the ${rawOutputMaxBytes}-byte cap; ${narrow}`,
+    'SEARCH_RAW_OUTPUT_OVERFLOW',
+  )
+}
+
+/**
+ * Run one fixed `rg` command through the bash seam and return its complete raw
+ * stdout. The bash request workdir is the calling agent's session cwd
+ * (`exec.agent.session.header.cwd`) when available — mirroring `dsh-tool-bash` /
+ * `dsh-tool-fs` — else omitted so the implementation's `resolve()` applies its
+ * configured default. `exec.signal` is forwarded so the cooperative tool
+ * timeout (`@deepseek-ai/dsh-timeout-policy`) and caller cancellation kill the
+ * command; the bash backend's own timeout stays a second safety cap.
+ *
+ * Exit semantics are tool-owned: exit 0 is success with results, exit 1 is
+ * success with zero results (`noMatches`), anything else throws a
+ * {@link SearchError} (abort/timeout → `SEARCH_ABORTED`, invalid pattern →
+ * `SEARCH_INVALID_PATTERN`, the rest → `SEARCH_FAILED` /
+ * `SEARCH_RAW_OUTPUT_OVERFLOW`). A `run()` REJECTION — the seam's
+ * infrastructure failures (pre-aborted signal, unusable workdir, missing
+ * shell) — is translated into the same taxonomy: a pre-aborted signal becomes
+ * `SEARCH_ABORTED`, everything else `SEARCH_FAILED`, with the original as
+ * `cause`.
+ *
+ * @param ctx - the plugin context; execution uses its `bash` service.
+ * @param exec - the tool-execution context; supplies the session cwd and the abort signal.
+ * @param toolName - `glob` or `grep`, used in error messages.
+ * @param command - the fully-quoted `rg` command string (every model value already through `singleQuote`).
+ * @param rawOutputMaxBytes - cap on the complete raw stdout the tool will parse.
+ * @returns the complete stdout, the zero-result flag, and the resolved workdir.
+ */
+export async function runRipgrep(
+  ctx: Context,
+  exec: ToolExecution,
+  toolName: string,
+  command: string,
+  rawOutputMaxBytes: number,
+): Promise<RipgrepRun> {
+  const cwd = exec.agent?.session.header.cwd
+  const spec = ctx.bash.resolve({
+    command,
+    stdoutMaxBytes: rawOutputMaxBytes,
+    ...cwd !== undefined ? { workdir: cwd } : {},
+    ...exec.signal ? { signal: exec.signal } : {},
+  })
+  let result: BashRunResult
+  try {
+    result = await ctx.bash.run(spec)
+  } catch (error: unknown) {
+    // The seam contract: run() REJECTS only for infrastructure failures — a
+    // pre-aborted signal, an unusable workdir, a missing shell. Translate them
+    // so these failures stay machine-routable under the SEARCH_* taxonomy.
+    if (spec.signal?.aborted === true) {
+      throw new SearchError(`${toolName} was aborted before completion (tool timeout or caller cancellation)`, 'SEARCH_ABORTED', { cause: error })
+    }
+    throw new SearchError(`${toolName} could not start its search command (unusable working directory or missing shell)`, 'SEARCH_FAILED', { cause: error })
+  }
+  if (result.aborted) {
+    throw new SearchError(`${toolName} was aborted before completion (tool timeout or caller cancellation)`, 'SEARCH_ABORTED')
+  }
+  if (result.timedOut) {
+    throw new SearchError(`${toolName} timed out after ${result.timeoutMs}ms in the bash executor; narrow pattern, path, or include and retry`, 'SEARCH_ABORTED')
+  }
+  if (result.signal !== null || result.exitCode === null) {
+    throw new SearchError(`${toolName} search command was killed by signal ${result.signal ?? '(unknown)'}`, 'SEARCH_FAILED')
+  }
+  if (result.exitCode !== 0 && result.exitCode !== 1) {
+    throw classifyRunFailure(toolName, result)
+  }
+  const stdout = completeStdout(toolName, result, rawOutputMaxBytes)
+  return { stdout, noMatches: result.exitCode === 1, workdir: spec.workdir }
+}
+
+/**
+ * Map an `rg` output path to its display form: absolute paths inside the
+ * resolved bash workdir become workdir-relative; everything else (relative
+ * output, paths outside the workdir) passes through unchanged. Display-only —
+ * returned paths are follow-up-readable in co-located bash/filesystem
+ * deployments where both resolve the same workspace (the documented v1
+ * deployment requirement).
+ *
+ * @param path - one path as ripgrep printed it.
+ * @param workdir - the resolved bash workdir the command ran in.
+ * @returns the workdir-relative display path when possible, else `path` unchanged.
+ */
+export function toWorkdirRelative(path: string, workdir: string): string {
+  if (!isAbsolute(path)) return path
+  const rel = relative(workdir, path)
+  if (rel.length === 0) return '.'
+  if (rel === '..' || rel.startsWith(`..${sep}`)) return path
+  return rel
+}
+
+/**
+ * Best-effort save of one COMPLETE formatted search result through
+ * `ctx.spillStore.saveText()` — the model-facing recovery path for a capped
+ * result. `spillStore` is read with `ctx.get()` (not static inject) because
+ * formatted-result spill is optional; the spill owner is the calling agent's
+ * session header id and the source is the tool execution identity. A missing
+ * backend, a call with no session owner, or a `saveText()` rejection logs a
+ * warning and returns `undefined` — the caller keeps the inline result and
+ * reports that the complete result could not be saved; search success never
+ * turns into `isError` because spill storage is unavailable.
+ *
+ * @param ctx - the plugin context; `spillStore` is looked up opportunistically.
+ * @param exec - the tool-execution context; supplies the owning session, tool name, and call id.
+ * @param suggestedName - the backend-sanitized filename hint (e.g. `grep-results.txt`).
+ * @param content - the complete formatted result to persist.
+ * @returns the saved spill reference, or `undefined` when the result could not be saved.
+ */
+export async function trySaveFormattedResult(
+  ctx: Context,
+  exec: ToolExecution,
+  suggestedName: string,
+  content: string,
+): Promise<SpillRef | undefined> {
+  const sessionId = exec.agent?.session.header.id
+  if (sessionId === undefined) {
+    ctx.logger.warn(`tool-fs-search: no session owner for ${exec.name} result; complete result not saved`)
+    return undefined
+  }
+  const spillStore = ctx.get('spillStore')
+  if (!spillStore) {
+    ctx.logger.warn(`tool-fs-search: no ctx.spillStore backend loaded; complete ${exec.name} result not saved`)
+    return undefined
+  }
+  const save: SaveTextSpill = {
+    owner: { sessionId },
+    source: { toolName: exec.name, callId: exec.callId, label: 'result' },
+    suggestedName,
+    content,
+  }
+  try {
+    return await spillStore.saveText(save)
+  } catch (error: unknown) {
+    // Best-effort: a storage failure must never fail the search or hide the
+    // inline result — the footer reports the unsaved remainder instead.
+    ctx.logger.warn(`tool-fs-search: saveText failed for ${exec.name}: ${String(error)}; complete result not saved`)
+    return undefined
+  }
+}

packages/fs/tool-fs-search/src/shell-quote.ts

@@ -0,0 +1,27 @@
+/**
+ * The one shell-quoting helper both search tools MUST route every
+ * model-controlled value through before it enters an `rg` command string. The
+ * bash seam (`ctx.bash`) accepts a command STRING, not an argv vector, so this
+ * is the safety boundary that stops a `pattern`, `path`, or `include` from
+ * breaking out of its argument and injecting shell syntax.
+ *
+ * Command builders in `glob.ts` / `grep.ts` must never hand-roll quoting or
+ * concatenate an unquoted model value — they call {@link singleQuote}.
+ *
+ * @module @deepseek-ai/dsh-tool-fs-search/shell-quote
+ */
+
+/**
+ * POSIX single-quote a string for safe use as ONE shell word. Wraps the value
+ * in single quotes and rewrites every embedded single quote as `'\''` (close
+ * quote, an escaped literal quote, reopen quote). Inside single quotes the shell
+ * treats every other byte literally — spaces, newlines, `$`, backticks, `;`,
+ * `|`, `&`, glob metacharacters, and a leading `-` are all inert — so the result
+ * is a single, injection-safe argument regardless of the input.
+ *
+ * @param value - the raw, possibly model-controlled string to quote.
+ * @returns the value wrapped as one safe single-quoted shell word.
+ */
+export function singleQuote(value: string): string {
+  return `'${value.replaceAll("'", "'\\''")}'`
+}

packages/fs/tool-fs-search/tests/integration.spec.ts

@@ -0,0 +1,190 @@
+/**
+ * Integration tests: the REAL local bash executor (`dsh-bash-local`) plus a
+ * REAL ripgrep binary, exercised through `ctx.tools.execute()`. These verify
+ * the WORLD — actual files on disk are discovered and grepped, hostile
+ * patterns stay inert in a real shell, and real `rg` stderr classifies into
+ * the `SEARCH_*` vocabulary. The whole suite self-skips when `rg` is not on
+ * PATH (a CI accommodation mirroring the keyless e2e skip); the fake-executor
+ * suite (tools.spec.ts) carries the coverage gate.
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { spawnSync } from 'node:child_process'
+import { mkdir, mkdtemp, rm, utimes, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { Context } from 'cordis'
+import { CallId } from '@deepseek-ai/dsh-llm'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import ToolRegistry from '@deepseek-ai/dsh-tools'
+import { LocalBashExecutor } from '@deepseek-ai/dsh-bash-local'
+import * as ToolFsSearch from '@deepseek-ai/dsh-tool-fs-search'
+
+const hasRg = spawnSync('rg', ['--version'], { encoding: 'utf8' }).status === 0
+
+let dir: string
+let ctx: Context
+
+let callCounter = 0
+function call(name: string, args: unknown, agentObj?: object) {
+  return ctx.tools.execute({
+    callId: CallId(`it-${++callCounter}`),
+    name,
+    arguments: args,
+    ...agentObj ? { agent: agentObj as never } : {},
+  })
+}
+
+function text(result: { content: { type: string; text?: string }[] }): string {
+  return result.content.filter(b => b.type === 'text').map(b => b.text).join('')
+}
+
+describe.skipIf(!hasRg)('search tools over the real bash executor + real rg', () => {
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), 'dsh-search-int-'))
+    await mkdir(join(dir, 'src'), { recursive: true })
+    await mkdir(join(dir, '.git'), { recursive: true })
+    await mkdir(join(dir, 'spaced dir'), { recursive: true })
+    await writeFile(join(dir, 'src', 'alpha.ts'), 'export const alpha = 1\n// TODO: refit alpha\n')
+    await writeFile(join(dir, 'src', 'beta.ts'), 'export const beta = 2\n')
+    await writeFile(join(dir, 'notes.md'), 'alpha appears here too\n')
+    await writeFile(join(dir, '.hidden.ts'), 'export const hidden = 3\n')
+    await writeFile(join(dir, '.git', 'config.ts'), 'never listed\n')
+    await writeFile(join(dir, 'spaced dir', "wei'rd \"name\".ts"), 'const inside = true\n')
+    // Deterministic --sort=modified order: alpha oldest, beta newest.
+    await utimes(join(dir, 'src', 'alpha.ts'), new Date(2000, 0, 1), new Date(2000, 0, 1))
+    await utimes(join(dir, 'src', 'beta.ts'), new Date(2020, 0, 1), new Date(2020, 0, 1))
+
+    ctx = new Context()
+    await ctx.plugin(SystemPrompt)
+    await ctx.plugin(ToolRegistry)
+    await ctx.plugin(LocalBashExecutor, { cwd: dir, timeoutMs: 20_000 })
+    await ctx.plugin(ToolFsSearch)
+  })
+
+  afterEach(async () => {
+    await rm(dir, { recursive: true, force: true })
+  })
+
+  describe('glob', () => {
+    it('discovers files by pattern, sorted by modification time, hidden included, .git excluded', async () => {
+      const result = await call('glob', { pattern: '**/*.ts' })
+      expect(result.isError).toBe(false)
+      const paths = text(result).split('\n')
+      expect(paths.indexOf('src/alpha.ts')).toBeLessThan(paths.indexOf('src/beta.ts'))
+      expect(paths).toContain('.hidden.ts')
+      expect(paths).toContain("spaced dir/wei'rd \"name\".ts")
+      expect(paths).not.toContain('.git/config.ts')
+      expect(paths).not.toContain('notes.md')
+    })
+
+    it('scopes to a directory search root (path arg)', async () => {
+      const result = await call('glob', { pattern: '*.ts', path: 'src' })
+      expect(text(result).split('\n').sort()).toEqual(['src/alpha.ts', 'src/beta.ts'])
+    })
+
+    it('reports zero discoveries as No files found', async () => {
+      expect(text(await call('glob', { pattern: '*.nomatch' }))).toBe('No files found')
+    })
+
+    it('excludes VCS internals even when the search root IS the VCS directory', async () => {
+      // The prune glob alone never matches root-prefixed paths when rg is
+      // rooted at .git; the paired contents glob keeps the exclusion airtight.
+      expect(text(await call('glob', { pattern: '*', path: '.git' }))).toBe('No files found')
+    })
+
+    it('classifies an invalid glob as SEARCH_INVALID_PATTERN', async () => {
+      const result = await call('glob', { pattern: '[' })
+      expect(result.isError).toBe(true)
+      expect(result.error).toMatchObject({ name: 'SearchError', code: 'SEARCH_INVALID_PATTERN' })
+    })
+  })
+
+  describe('grep', () => {
+    it('greps a directory tree with grouped, line-numbered output', async () => {
+      const result = await call('grep', { pattern: 'alpha' })
+      expect(result.isError).toBe(false)
+      const output = text(result)
+      expect(output).toContain('Found 3 matches')
+      expect(output).toContain('src/alpha.ts\nLine 1: export const alpha = 1\nLine 2: // TODO: refit alpha')
+      expect(output).toContain('notes.md\nLine 1: alpha appears here too')
+    })
+
+    it('greps a single FILE target', async () => {
+      const result = await call('grep', { pattern: 'alpha', path: 'notes.md' })
+      expect(text(result)).toBe('Found 1 match\n\nnotes.md\nLine 1: alpha appears here too')
+    })
+
+    it('greps a directory target with an include filter', async () => {
+      const result = await call('grep', { pattern: 'alpha', path: '.', include: '*.ts' })
+      const output = text(result)
+      expect(output).toContain('alpha.ts')
+      expect(output).not.toContain('notes.md')
+    })
+
+    it('a hostile pattern stays inert (no command substitution, the world untouched)', async () => {
+      const canary = join(dir, 'pwned')
+      const result = await call('grep', { pattern: `$(touch ${canary})` })
+      expect(result.isError).toBe(false) // exit 1: found nothing, executed nothing
+      expect(text(result)).toBe('No matches found')
+      expect(spawnSync('test', ['-e', canary]).status).not.toBe(0)
+    })
+
+    it('a leading-dash pattern is a pattern, not a flag', async () => {
+      await writeFile(join(dir, 'dashes.txt'), 'value --flag value\n')
+      const result = await call('grep', { pattern: '--flag', path: 'dashes.txt' })
+      expect(text(result)).toBe('Found 1 match\n\ndashes.txt\nLine 1: value --flag value')
+    })
+
+    it('classifies a real rg regex error as SEARCH_INVALID_PATTERN', async () => {
+      const result = await call('grep', { pattern: '(unclosed' })
+      expect(result.isError).toBe(true)
+      expect(result.error).toMatchObject({ code: 'SEARCH_INVALID_PATTERN' })
+    })
+
+    it('classifies a missing target as SEARCH_FAILED', async () => {
+      const result = await call('grep', { pattern: 'x', path: 'no-such-dir' })
+      expect(result.isError).toBe(true)
+      expect(result.error).toMatchObject({ code: 'SEARCH_FAILED' })
+    })
+  })
+
+  describe('per-session cwd', () => {
+    it('resolves the search in the SESSION workspace, not the executor config cwd', async () => {
+      const sessionDir = await mkdtemp(join(tmpdir(), 'dsh-search-session-'))
+      try {
+        await writeFile(join(sessionDir, 'only-here.ts'), 'const sessionFile = true\n')
+        const agentObj = { session: { header: { id: 'session-int', cwd: sessionDir } } }
+        const globbed = await call('glob', { pattern: '*.ts' }, agentObj)
+        expect(text(globbed)).toBe('only-here.ts')
+        const grepped = await call('grep', { pattern: 'sessionFile' }, agentObj)
+        expect(text(grepped)).toContain('only-here.ts\nLine 1: const sessionFile = true')
+      } finally {
+        await rm(sessionDir, { recursive: true, force: true })
+      }
+    })
+  })
+
+  describe('bash-start infrastructure failures stay in the SEARCH_* taxonomy', () => {
+    it('a pre-aborted exec.signal (real executor rejects before spawn) is SEARCH_ABORTED', async () => {
+      const controller = new AbortController()
+      controller.abort()
+      const result = await ctx.tools.execute({
+        callId: CallId(`it-${++callCounter}`),
+        name: 'grep',
+        arguments: { pattern: 'x' },
+        signal: controller.signal,
+      })
+      expect(result.isError).toBe(true)
+      expect(result.error).toMatchObject({ name: 'SearchError', code: 'SEARCH_ABORTED' })
+    })
+
+    it('an unusable session cwd (spawn failure) is SEARCH_FAILED', async () => {
+      const gone = join(dir, 'deleted-session-dir')
+      const result = await call('glob', { pattern: '*' }, { session: { header: { id: 'session-int', cwd: gone } } })
+      expect(result.isError).toBe(true)
+      expect(result.error).toMatchObject({ name: 'SearchError', code: 'SEARCH_FAILED' })
+      expect(text(result)).toContain('could not start')
+    })
+  })
+})

packages/fs/tool-fs-search/tests/load-path.spec.ts

@@ -0,0 +1,50 @@
+/**
+ * Real-load-path guard for @deepseek-ai/dsh-tool-fs-search. `tool-fs-search` is
+ * a NAMESPACE plugin with `inject` — so a stray `export default apply` would
+ * make the cordis Loader's `unwrapExports` (`exports.default ?? exports`)
+ * collapse the module to the bare `apply` function, DROPPING `inject`. The
+ * plugin would then read `ctx.bash` without having injected it and throw
+ * `cannot get property … without inject` the moment it loads (postmortem 0001).
+ *
+ * A hand-built `ctx.plugin({ apply, inject })` mount CANNOT catch that — it
+ * bypasses `unwrapExports`. So this test unwraps the module through the REAL
+ * `Loader.prototype.unwrapExports` and mounts the result over a bash executor,
+ * exercising the exact path the Loader uses. Prove the guard bites: add
+ * `export default apply` to `src/index.ts`, watch this go red, revert.
+ */
+
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import Loader from '@cordisjs/plugin-loader'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import ToolRegistry from '@deepseek-ai/dsh-tools'
+import { LocalBashExecutor } from '@deepseek-ai/dsh-bash-local'
+import * as toolFsSearch from '@deepseek-ai/dsh-tool-fs-search'
+
+describe('dsh-tool-fs-search real-load-path guard', () => {
+  it('has no default export and keeps name/inject/Config through unwrapExports', () => {
+    expect('default' in toolFsSearch).toBe(false)
+
+    const loader = Object.create(Loader.prototype) as Loader
+    const unwrapped = loader.unwrapExports(toolFsSearch) as Record<string, unknown>
+    expect(unwrapped).toBe(toolFsSearch)
+    expect(unwrapped.name).toBe('tool-fs-search')
+    expect(unwrapped.inject).toEqual(['tools', 'systemPrompt', 'bash'])
+    expect(typeof unwrapped.Config).toBe('function')
+    expect(typeof unwrapped.apply).toBe('function')
+  })
+
+  it('boots over ctx.bash through the unwrapped module without an inject error', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SystemPrompt)
+    await ctx.plugin(ToolRegistry)
+    await ctx.plugin(LocalBashExecutor, {})
+
+    const loader = Object.create(Loader.prototype) as Loader
+    const unwrapped = loader.unwrapExports(toolFsSearch) as Parameters<Context['plugin']>[0]
+    // A collapsed export shape (dropped inject) would throw "without inject" here.
+    const fiber = await ctx.plugin(unwrapped)
+    expect(ctx.tools.schemas().map(s => s.name)).toEqual(expect.arrayContaining(['glob', 'grep']))
+    await fiber.dispose()
+  })
+})

packages/fs/tool-fs-search/tests/shell-quote.spec.ts

@@ -0,0 +1,59 @@
+/**
+ * Unit tests for the shell-quoting safety boundary, plus a REAL round-trip:
+ * every adversarial value, quoted, must survive `bash -c "printf '%s' <quoted>"`
+ * byte-for-byte — proving the quoting is inert in an actual shell, not just
+ * against a mental model of one.
+ */
+
+import { describe, expect, it } from 'vitest'
+import { spawnSync } from 'node:child_process'
+import { singleQuote } from '@deepseek-ai/dsh-tool-fs-search'
+
+/** Adversarial values a model could pass as pattern / path / include. */
+const HOSTILE: readonly string[] = [
+  'plain',
+  'with spaces',
+  "it's got 'quotes'",
+  '"double quoted"',
+  '$(rm -rf /tmp/nope)',
+  '`touch /tmp/nope`',
+  '$HOME and ${PATH}',
+  'semi;colon && chain || pipe | bg &',
+  'newline\nin the middle',
+  '-leading-dash',
+  '--leading-double-dash',
+  '*?[a-z]{x,y}',
+  '!bang',
+  '\\backslash\\',
+  '~tilde',
+  '# not a comment',
+  '>redirect <input 2>&1',
+]
+
+describe('singleQuote', () => {
+  it('wraps a plain value in single quotes', () => {
+    expect(singleQuote('abc')).toBe("'abc'")
+  })
+
+  it("rewrites embedded single quotes as '\\''", () => {
+    expect(singleQuote("a'b")).toBe("'a'\\''b'")
+    expect(singleQuote("''")).toBe("''\\'''\\'''")
+  })
+
+  it.each(HOSTILE.map(value => [JSON.stringify(value), value] as const))(
+    'round-trips %s through a real bash -c unchanged',
+    (_label, value) => {
+      const result = spawnSync('bash', ['-c', `printf '%s' ${singleQuote(value)}`], { encoding: 'utf8' })
+      expect(result.status).toBe(0)
+      expect(result.stdout).toBe(value)
+    },
+  )
+
+  it('a quoted command substitution does not execute (the world stays untouched)', () => {
+    const canary = `/tmp/dsh-quote-canary-${process.pid}`
+    const result = spawnSync('bash', ['-c', `printf '%s' ${singleQuote(`$(touch ${canary})`)}`], { encoding: 'utf8' })
+    expect(result.stdout).toBe(`$(touch ${canary})`)
+    // The canary file must NOT exist — the substitution stayed literal.
+    expect(spawnSync('test', ['-e', canary]).status).not.toBe(0)
+  })
+})

packages/fs/tool-fs-search/tests/tools.spec.ts

@@ -0,0 +1,632 @@
+/**
+ * Consumer-surface tests for the search tools over a FAKE bash executor and a
+ * FAKE spill backend, exercised through `ctx.tools.execute()` so nothing
+ * bypasses the tool registry. The fake executor makes every seam outcome
+ * scriptable — truncated stdout with/without a raw spill path, abort/timeout,
+ * signal kills, ripgrep exit codes — so these tests verify schemas, argument
+ * validation, shell-safe command construction, workdir derivation, signal
+ * forwarding, `SEARCH_*` error classification, retention, formatted-result
+ * spill handoff, and the no-background-task invariant. Real-`rg` behavior is
+ * pinned separately in integration.spec.ts.
+ */
+
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import { CallId } from '@deepseek-ai/dsh-llm'
+import SystemPrompt, { renderPrompt } from '@deepseek-ai/dsh-system-prompt'
+import ToolRegistry from '@deepseek-ai/dsh-tools'
+import { BashExecutor } from '@deepseek-ai/dsh-bash'
+import type { BashExecRequest, BashExecSpec, BashProcess, BashRunResult } from '@deepseek-ai/dsh-bash'
+import { SpillLocator, SpillStore } from '@deepseek-ai/dsh-spill'
+import type { SaveTextSpill, SpillRef } from '@deepseek-ai/dsh-spill'
+import * as ToolFsSearch from '@deepseek-ai/dsh-tool-fs-search'
+import {
+  buildGlobCommand,
+  buildGrepCommand,
+  formatGrepMatches,
+  parseGrepMatches,
+  presentGlobCall,
+  presentGrepCall,
+  previewLine,
+  toWorkdirRelative,
+} from '@deepseek-ai/dsh-tool-fs-search'
+
+/** A successful run result over the given stdout; overrides script the failure shapes. */
+function runResult(stdout: string, overrides?: Partial<BashRunResult>): BashRunResult {
+  return {
+    exitCode: 0,
+    signal: null,
+    timedOut: false,
+    aborted: false,
+    timeoutMs: 60_000,
+    stdout: { text: stdout, truncated: false },
+    stderr: { text: '', truncated: false },
+    ...overrides,
+  }
+}
+
+/**
+ * A scriptable fake executor: `resolve()` mirrors the real request→spec
+ * defaulting (workdir falls back to `/work`), `run()` returns whatever the
+ * test armed via `handler`, and `start()` throws — the search tools must NEVER
+ * create a background task.
+ */
+class FakeBash extends BashExecutor {
+  requests: BashExecRequest[] = []
+  specs: BashExecSpec[] = []
+  startCalls = 0
+  handler: (spec: BashExecSpec) => BashRunResult = () => runResult('')
+
+  override resolve(request: BashExecRequest): BashExecSpec {
+    this.requests.push(request)
+    return {
+      command: request.command,
+      workdir: request.workdir ?? '/work',
+      timeoutMs: request.timeoutMs ?? 60_000,
+      stdoutMaxBytes: request.stdoutMaxBytes ?? 64_000,
+      signal: request.signal,
+      sandboxMode: request.sandboxMode,
+    }
+  }
+  override run(spec: BashExecSpec): Promise<BashRunResult> {
+    this.specs.push(spec)
+    return Promise.resolve(this.handler(spec))
+  }
+  override start(): BashProcess {
+    this.startCalls++
+    throw new Error('search tools must never start a background task')
+  }
+}
+
+/** A recording spill backend; arm `failWith` to script a storage failure. */
+class FakeSpill extends SpillStore {
+  saves: SaveTextSpill[] = []
+  failWith?: Error
+
+  override saveText(input: SaveTextSpill): Promise<SpillRef> {
+    if (this.failWith) return Promise.reject(this.failWith)
+    this.saves.push(input)
+    return Promise.resolve({
+      locator: SpillLocator(`/spill/${input.suggestedName}`),
+      bytes: Buffer.byteLength(input.content, 'utf8'),
+      retrievalHint: 'Use the fake retrieval hint.',
+    })
+  }
+}
+
+interface SetupOptions {
+  config?: ToolFsSearch.Config
+  spill?: boolean
+}
+
+async function setup(options: SetupOptions = {}) {
+  const ctx = new Context()
+  await ctx.plugin(SystemPrompt)
+  await ctx.plugin(ToolRegistry)
+  await ctx.plugin(FakeBash)
+  if (options.spill === true) await ctx.plugin(FakeSpill)
+  const fiber = await ctx.plugin(ToolFsSearch, options.config)
+  const bash = ctx.bash as FakeBash
+  const spill = options.spill === true ? ctx.get('spillStore') as FakeSpill : undefined
+  return { ctx, bash, spill, fiber }
+}
+
+/** A stand-in agent whose session header carries the given cwd (and a stable id). */
+const agent = (cwd?: string) => ({ session: { header: { id: 'session-1', ...cwd !== undefined ? { cwd } : {} } } })
+
+let callCounter = 0
+function call(ctx: Context, name: string, args: unknown, options: { agent?: object; signal?: AbortSignal } = {}) {
+  return ctx.tools.execute({
+    callId: CallId(`call-${++callCounter}`),
+    name,
+    arguments: args,
+    ...options.agent ? { agent: options.agent as never } : {},
+    ...options.signal ? { signal: options.signal } : {},
+  })
+}
+
+function text(result: { content: { type: string; text?: string }[] }): string {
+  return result.content.filter(b => b.type === 'text').map(b => b.text).join('')
+}
+
+/** One rg --json match record line. */
+function matchLine(path: string, lineNumber: number, lineText: string): string {
+  return JSON.stringify({ type: 'match', data: { path: { text: path }, lines: { text: lineText }, line_number: lineNumber, absolute_offset: 0, submatches: [] } })
+}
+
+describe('registration', () => {
+  it('registers glob and grep with their prompt sections', async () => {
+    const { ctx } = await setup()
+    expect(ctx.tools.schemas().map(s => s.name).sort()).toEqual(['glob', 'grep'])
+    const prompt = renderPrompt(await ctx.systemPrompt.assemble())
+    expect(prompt).toContain('Use the glob tool')
+    expect(prompt).toContain('Use the grep tool')
+  })
+
+  it('stays pending until ctx.bash exists (inject)', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SystemPrompt)
+    await ctx.plugin(ToolRegistry)
+    await ctx.plugin(ToolFsSearch) // no bash executor
+    expect(ctx.tools.schemas()).toHaveLength(0)
+  })
+
+  it('unregisters everything on fiber disposal (HMR safety)', async () => {
+    const { ctx, fiber } = await setup()
+    expect(ctx.tools.schemas()).toHaveLength(2)
+    await fiber.dispose()
+    expect(ctx.tools.schemas()).toHaveLength(0)
+    const sections = (await ctx.systemPrompt.assemble()).sections.map(s => s.name)
+    expect(sections).not.toContain('tool:glob')
+    expect(sections).not.toContain('tool:grep')
+  })
+
+  it('attaches the configured timeoutMs to both tool definitions', async () => {
+    const { ctx } = await setup({ config: { timeoutMs: 5000 } })
+    expect(ctx.tools.get('glob')?.timeoutMs).toBe(5000)
+    expect(ctx.tools.get('grep')?.timeoutMs).toBe(5000)
+  })
+
+  it('defaults the timeout budget to 30 seconds', async () => {
+    const { ctx } = await setup()
+    expect(ctx.tools.get('glob')?.timeoutMs).toBe(30_000)
+    expect(ctx.tools.get('grep')?.timeoutMs).toBe(30_000)
+  })
+})
+
+describe('config validation', () => {
+  it.each([
+    ['globMaxResults', { globMaxResults: 0 }],
+    ['grepMaxMatches', { grepMaxMatches: -1 }],
+    ['grepMaxLineBytes', { grepMaxLineBytes: 1.5 }],
+    ['rawOutputMaxBytes', { rawOutputMaxBytes: 0 }],
+    ['timeoutMs', { timeoutMs: -100 }],
+  ] as const)('rejects a non-positive or fractional %s at load', async (name, config) => {
+    const ctx = new Context()
+    await ctx.plugin(SystemPrompt)
+    await ctx.plugin(ToolRegistry)
+    await ctx.plugin(FakeBash)
+    await expect(ctx.plugin(ToolFsSearch, config)).rejects.toThrow(new RegExp(`tool-fs-search: ${name} must be a positive integer`))
+  })
+})
+
+describe('command construction (shell-safe)', () => {
+  it('glob: fixed rg --files template with quoted pattern and paired VCS excludes', () => {
+    const command = buildGlobCommand({ pattern: '**/*.ts' })
+    expect(command).toBe(
+      "rg --files --glob='**/*.ts' --sort=modified --no-ignore --hidden "
+      + "--glob='!**/.git' --glob='!**/.git/**' --glob='!**/.svn' --glob='!**/.svn/**' "
+      + "--glob='!**/.hg' --glob='!**/.hg/**' --glob='!**/.bzr' --glob='!**/.bzr/**' "
+      + "--glob='!**/.jj' --glob='!**/.jj/**' --glob='!**/.sl' --glob='!**/.sl/**'",
+    )
+  })
+
+  it('glob: the search root rides behind -- and is quoted', () => {
+    const command = buildGlobCommand({ pattern: '*.md', path: 'docs dir' })
+    expect(command).toContain("-- 'docs dir'")
+  })
+
+  it('grep: fixed rg --json template with the pattern in --regexp= form', () => {
+    expect(buildGrepCommand({ pattern: 'foo.*bar' })).toBe("rg --json --regexp='foo.*bar'")
+  })
+
+  it('grep: include and path are quoted, include in --glob= form, path behind --', () => {
+    const command = buildGrepCommand({ pattern: 'x', path: '-leading-dash', include: '*.{ts,tsx}' })
+    expect(command).toBe("rg --json --regexp='x' --glob='*.{ts,tsx}' -- '-leading-dash'")
+  })
+
+  it.each([
+    ['a command-substitution pattern', '$(rm -rf /)', "'$(rm -rf /)'"],
+    ['a backtick pattern', '`touch pwned`', "'`touch pwned`'"],
+    ['a pattern with double quotes and spaces', 'say "hi there"', '\'say "hi there"\''],
+    ['a pattern with single quotes', "it's", '\'it\'\\\'\'s\''],
+    ['a pattern with newlines', 'a\nb', "'a\nb'"],
+    ['a leading-dash pattern', '--flag', "'--flag'"],
+    ['glob metacharacters', '*?[a-z]{x,y}', "'*?[a-z]{x,y}'"],
+  ])('quotes %s into one inert shell word', (_label, raw, quoted) => {
+    expect(buildGrepCommand({ pattern: raw })).toBe(`rg --json --regexp=${quoted}`)
+  })
+})
+
+describe('workdir derivation and signal forwarding', () => {
+  it('forwards the session cwd as the request workdir', async () => {
+    const { ctx, bash } = await setup()
+    bash.handler = () => runResult('a.ts\n')
+    await call(ctx, 'glob', { pattern: '*' }, { agent: agent('/sessions/s1') })
+    expect(bash.requests[0]?.workdir).toBe('/sessions/s1')
+    expect(bash.specs[0]?.workdir).toBe('/sessions/s1')
+  })
+
+  it('omits the request workdir without a session cwd so resolve() defaults apply', async () => {
+    const { ctx, bash } = await setup()
+    bash.handler = () => runResult('a.ts\n')
+    await call(ctx, 'glob', { pattern: '*' }, { agent: agent() })
+    expect(bash.requests[0]).not.toHaveProperty('workdir')
+    expect(bash.specs[0]?.workdir).toBe('/work')
+    // A non-agent caller takes the same default path.
+    await call(ctx, 'grep', { pattern: 'x' })
+    expect(bash.requests[1]).not.toHaveProperty('workdir')
+  })
+
+  it('forwards exec.signal into the bash spec (the abort reaches the backend)', async () => {
+    const { ctx, bash } = await setup()
+    const controller = new AbortController()
+    controller.abort()
+    bash.handler = spec => runResult('', { aborted: spec.signal?.aborted === true })
+    const result = await call(ctx, 'grep', { pattern: 'x' }, { signal: controller.signal })
+    expect(bash.specs[0]?.signal).toBe(controller.signal)
+    expect(result.isError).toBe(true)
+    expect(result.error).toMatchObject({ name: 'SearchError', code: 'SEARCH_ABORTED' })
+    expect(text(result)).toContain('aborted')
+  })
+
+  it('reports the bash executor timeout as SEARCH_ABORTED with the budget', async () => {
+    const { ctx, bash } = await setup()
+    bash.handler = () => runResult('', { timedOut: true, timeoutMs: 1234, exitCode: null, signal: 'SIGTERM' })
+    const result = await call(ctx, 'glob', { pattern: '*' })
+    expect(result.isError).toBe(true)
+    expect(result.error).toMatchObject({ code: 'SEARCH_ABORTED' })
+    expect(text(result)).toContain('timed out after 1234ms')
+  })
+
+  it('translates a run() rejection under a pre-aborted signal into SEARCH_ABORTED', async () => {
+    // The seam contract: run() REJECTS for a pre-aborted signal (it never
+    // spawns). The plain rejection must not escape the SEARCH_* taxonomy.
+    const { ctx, bash } = await setup()
+    const controller = new AbortController()
+    controller.abort()
+    bash.handler = () => { throw new Error('aborted before spawn') }
+    const result = await call(ctx, 'grep', { pattern: 'x' }, { signal: controller.signal })
+    expect(result.isError).toBe(true)
+    expect(result.error).toMatchObject({ name: 'SearchError', code: 'SEARCH_ABORTED' })
+  })
+
+  it('translates a run() rejection without an abort (unusable workdir) into SEARCH_FAILED', async () => {
+    const { ctx, bash } = await setup()
+    bash.handler = () => { throw new Error('spawn bash ENOENT') }
+    const result = await call(ctx, 'glob', { pattern: '*' })
+    expect(result.isError).toBe(true)
+    expect(result.error).toMatchObject({ name: 'SearchError', code: 'SEARCH_FAILED' })
+    expect(text(result)).toContain('could not start')
+  })
+})
+
+describe('exit semantics and failure classification', () => {
+  it('exit 1 is a successful empty search', async () => {
+    const { ctx, bash } = await setup()
+    bash.handler = () => runResult('', { exitCode: 1 })
+    const glob = await call(ctx, 'glob', { pattern: '*.nope' })
+    expect(glob.isError).toBe(false)
+    expect(text(glob)).toBe('No files found')
+    const grep = await call(ctx, 'grep', { pattern: 'nope' })
+    expect(grep.isError).toBe(false)
+    expect(text(grep)).toBe('No matches found')
+  })
+
+  it('a regex parse error classifies as SEARCH_INVALID_PATTERN', async () => {
+    const { ctx, bash } = await setup()
+    bash.handler = () => runResult('', { exitCode: 2, stderr: { text: 'rg: regex parse error:\n    (\nerror: unclosed group', truncated: false } })
+    const result = await call(ctx, 'grep', { pattern: '(' })
+    expect(result.error).toMatchObject({ code: 'SEARCH_INVALID_PATTERN' })
+    expect(text(result)).toContain('regex parse error')
+  })
+
+  it('a glob parse error classifies as SEARCH_INVALID_PATTERN', async () => {
+    const { ctx, bash } = await setup()
+    bash.handler = () => runResult('', { exitCode: 2, stderr: { text: 'rg: error parsing glob \'[\': unclosed character class', truncated: false } })
+    const result = await call(ctx, 'glob', { pattern: '[' })
+    expect(result.error).toMatchObject({ code: 'SEARCH_INVALID_PATTERN' })
+  })
+
+  it('a missing rg binary classifies as SEARCH_FAILED naming ripgrep', async () => {
+    const { ctx, bash } = await setup()
+    bash.handler = () => runResult('', { exitCode: 127, stderr: { text: 'bash: line 1: rg: command not found', truncated: false } })
+    const result = await call(ctx, 'glob', { pattern: '*' })
+    expect(result.error).toMatchObject({ code: 'SEARCH_FAILED' })
+    expect(text(result)).toContain('requires ripgrep (rg)')
+    // The same classification holds from either evidence alone: the 127 exit
+    // with silent stderr, or a shell's command-not-found text on another exit.
+    bash.handler = () => runResult('', { exitCode: 127 })
+    expect(text(await call(ctx, 'glob', { pattern: '*' }))).toContain('requires ripgrep (rg)')
+    bash.handler = () => runResult('', { exitCode: 2, stderr: { text: 'sh: rg: command not found', truncated: false } })
+    expect(text(await call(ctx, 'grep', { pattern: 'x' }))).toContain('requires ripgrep (rg)')
+  })
+
+  it('other nonzero exits are SEARCH_FAILED carrying the stderr excerpt', async () => {
+    const { ctx, bash } = await setup()
+    bash.handler = () => runResult('', { exitCode: 2, stderr: { text: 'rg: missing.dir: IO error: no such file or directory', truncated: false } })
+    const result = await call(ctx, 'grep', { pattern: 'x', path: 'missing.dir' })
+    expect(result.error).toMatchObject({ code: 'SEARCH_FAILED' })
+    expect(text(result)).toContain('IO error')
+  })
+
+  it('a nonzero exit with EMPTY stderr still reports the exit code', async () => {
+    const { ctx, bash } = await setup()
+    bash.handler = () => runResult('', { exitCode: 3 })
+    const result = await call(ctx, 'glob', { pattern: '*' })
+    expect(result.error).toMatchObject({ code: 'SEARCH_FAILED' })
+    expect(text(result)).toContain('exit 3')
+  })
+
+  it('truncated stderr gains a truncation note and stderr.spillPath is never read', async () => {
+    const { ctx, bash } = await setup()
+    bash.handler = () => runResult('', {
+      exitCode: 2,
+      stderr: { text: 'tail of diagnostics', truncated: true, spillPath: '/does/not/exist-and-never-read' },
+    })
+    const result = await call(ctx, 'grep', { pattern: 'x' })
+    expect(text(result)).toContain('tail of diagnostics [stderr truncated]')
+  })
+
+  it('a signal kill (not timeout, not abort) is SEARCH_FAILED', async () => {
+    const { ctx, bash } = await setup()
+    bash.handler = () => runResult('', { exitCode: null, signal: 'SIGKILL' })
+    const result = await call(ctx, 'grep', { pattern: 'x' })
+    expect(result.error).toMatchObject({ code: 'SEARCH_FAILED' })
+    expect(text(result)).toContain('SIGKILL')
+  })
+
+  it('a null exit with no signal (defensive) is SEARCH_FAILED', async () => {
+    const { ctx, bash } = await setup()
+    bash.handler = () => runResult('', { exitCode: null, signal: null })
+    const result = await call(ctx, 'glob', { pattern: '*' })
+    expect(result.error).toMatchObject({ code: 'SEARCH_FAILED' })
+  })
+})
+
+describe('raw output acquisition', () => {
+  it('passes rawOutputMaxBytes to bash as the stdout capture budget', async () => {
+    const { ctx, bash } = await setup({ config: { rawOutputMaxBytes: 1234 } })
+    bash.handler = () => runResult('', { exitCode: 1 })
+    await call(ctx, 'glob', { pattern: '*.ts' })
+    await call(ctx, 'grep', { pattern: 'needle' })
+    expect(bash.requests.map(request => request.stdoutMaxBytes)).toEqual([1234, 1234])
+    expect(bash.specs.map(spec => spec.stdoutMaxBytes)).toEqual([1234, 1234])
+  })
+
+  it('fails with SEARCH_RAW_OUTPUT_OVERFLOW when truncated stdout has a raw spill path', async () => {
+    const { ctx, bash } = await setup({ config: { rawOutputMaxBytes: 16 } })
+    bash.handler = () => runResult('', { stdout: { text: 'x', truncated: true, spillPath: '/does/not/get-read' } })
+    const result = await call(ctx, 'glob', { pattern: '*' })
+    expect(result.error).toMatchObject({ code: 'SEARCH_RAW_OUTPUT_OVERFLOW' })
+    expect(text(result)).toContain('narrow pattern, path, or include')
+  })
+
+  it('fails with SEARCH_RAW_OUTPUT_OVERFLOW when UNTRUNCATED inline stdout exceeds the cap', async () => {
+    // An executor retaining more inline than this package's cap (or a
+    // deployment lowering rawOutputMaxBytes below the bash retention) must not
+    // smuggle an over-cap parse through the untruncated path.
+    const { ctx, bash } = await setup({ config: { rawOutputMaxBytes: 16 } })
+    bash.handler = () => runResult(`${'x'.repeat(64)}\n`)
+    const result = await call(ctx, 'grep', { pattern: 'x' })
+    expect(result.error).toMatchObject({ name: 'SearchError', code: 'SEARCH_RAW_OUTPUT_OVERFLOW' })
+    expect(text(result)).toContain('narrow pattern, path, or include')
+  })
+
+  it('fails with SEARCH_RAW_OUTPUT_OVERFLOW when truncated stdout has no spill path', async () => {
+    const { ctx, bash } = await setup()
+    bash.handler = () => runResult('', { stdout: { text: 'partial', truncated: true } })
+    const result = await call(ctx, 'grep', { pattern: 'x' })
+    expect(result.error).toMatchObject({ code: 'SEARCH_RAW_OUTPUT_OVERFLOW' })
+  })
+})
+
+describe('glob results', () => {
+  it('lists workdir-relative paths (absolute output under the workdir is relativized)', async () => {
+    const { ctx, bash } = await setup()
+    bash.handler = () => runResult('/sessions/s1/src/a.ts\n/elsewhere/b.ts\nrel/c.ts\n')
+    const result = await call(ctx, 'glob', { pattern: '*' }, { agent: agent('/sessions/s1') })
+    expect(text(result)).toBe('src/a.ts\n/elsewhere/b.ts\nrel/c.ts')
+  })
+
+  it('validates arguments (blank pattern, blank path)', async () => {
+    const { ctx } = await setup()
+    expect(text(await call(ctx, 'glob', { pattern: '  ' }))).toContain('pattern must be a non-empty string')
+    expect(text(await call(ctx, 'glob', { pattern: '*', path: ' ' }))).toContain('path must be a non-empty string')
+  })
+
+  it('threads a valid path through to the command as the quoted search root', async () => {
+    const { ctx, bash } = await setup()
+    bash.handler = () => runResult('sub/a.ts\n')
+    const result = await call(ctx, 'glob', { pattern: '*.ts', path: 'sub' })
+    expect(result.isError).toBe(false)
+    expect(bash.specs[0]?.command).toContain("-- 'sub'")
+  })
+
+  it('caps at globMaxResults and saves the FULL sorted list through spillStore', async () => {
+    const { ctx, bash, spill } = await setup({ config: { globMaxResults: 2 }, spill: true })
+    bash.handler = () => runResult('a.ts\nb.ts\nc.ts\nd.ts\n')
+    const result = await call(ctx, 'glob', { pattern: '*.ts' }, { agent: agent('/w') })
+    expect(result.isError).toBe(false)
+    expect(text(result)).toBe('a.ts\nb.ts\n\n(Showing 2 of 4 paths. Full sorted result stored at: /spill/glob-results.txt. Use the fake retrieval hint.)')
+    expect(spill?.saves).toHaveLength(1)
+    expect(spill?.saves[0]).toMatchObject({
+      owner: { sessionId: 'session-1' },
+      source: { toolName: 'glob', label: 'result' },
+      suggestedName: 'glob-results.txt',
+      content: 'a.ts\nb.ts\nc.ts\nd.ts',
+    })
+    expect(spill?.saves[0]?.source.callId).toBeDefined()
+  })
+
+  it('does not create a spill file when the result fits inline', async () => {
+    const { ctx, bash, spill } = await setup({ spill: true })
+    bash.handler = () => runResult('a.ts\nb.ts\n')
+    const result = await call(ctx, 'glob', { pattern: '*' }, { agent: agent('/w') })
+    expect(text(result)).toBe('a.ts\nb.ts')
+    expect(spill?.saves).toHaveLength(0)
+  })
+
+  it.each([
+    ['no spill backend loaded', { fail: false, spill: false, ownerless: false }],
+    ['saveText fails', { fail: true, spill: true, ownerless: false }],
+    ['no session owner', { fail: false, spill: true, ownerless: true }],
+  ])('keeps the inline page and reports the unsaved remainder when %s', async (_label, mode) => {
+    const { ctx, bash, spill } = await setup({ config: { globMaxResults: 1 }, spill: mode.spill })
+    if (mode.fail && spill) spill.failWith = new Error('disk full')
+    bash.handler = () => runResult('a.ts\nb.ts\n')
+    const result = await call(ctx, 'glob', { pattern: '*' }, mode.ownerless ? {} : { agent: agent('/w') })
+    expect(result.isError).toBe(false) // spill unavailability never fails the search
+    expect(text(result)).toBe('a.ts\n\n(Showing 1 of 2 paths. The complete result could not be saved; narrow pattern or path to see more.)')
+  })
+})
+
+describe('grep results', () => {
+  it('groups matches by file with line numbers', async () => {
+    const { ctx, bash } = await setup()
+    bash.handler = () => runResult([
+      JSON.stringify({ type: 'begin', data: { path: { text: 'a.ts' } } }),
+      matchLine('a.ts', 3, 'const x = 1\n'),
+      matchLine('a.ts', 9, 'const y = 2\n'),
+      JSON.stringify({ type: 'end', data: { path: { text: 'a.ts' } } }),
+      matchLine('b.ts', 1, 'const z = 3'),
+      JSON.stringify({ type: 'summary', data: {} }),
+      '',
+    ].join('\n'))
+    const result = await call(ctx, 'grep', { pattern: 'const' })
+    expect(result.isError).toBe(false)
+    expect(text(result)).toBe('Found 3 matches\n\na.ts\nLine 3: const x = 1\nLine 9: const y = 2\n\nb.ts\nLine 1: const z = 3')
+  })
+
+  it('reports a single match in the singular', async () => {
+    const { ctx, bash } = await setup()
+    bash.handler = () => runResult(`${matchLine('a.ts', 1, 'hit')}\n`)
+    expect(text(await call(ctx, 'grep', { pattern: 'hit' }))).toBe('Found 1 match\n\na.ts\nLine 1: hit')
+  })
+
+  it('relativizes absolute match paths against the resolved workdir', async () => {
+    const { ctx, bash } = await setup()
+    bash.handler = () => runResult(`${matchLine('/sessions/s1/deep/a.ts', 2, 'hit')}\n`)
+    const result = await call(ctx, 'grep', { pattern: 'hit', path: '/sessions/s1' }, { agent: agent('/sessions/s1') })
+    expect(text(result)).toContain('deep/a.ts\nLine 2: hit')
+  })
+
+  it('previews a long matched line at grepMaxLineBytes preserving UTF-8', async () => {
+    const { ctx, bash } = await setup({ config: { grepMaxLineBytes: 7 } })
+    // 'héllo wörld' cut at 7 bytes lands mid-'é'? h(1)é(2)l(1)l(1)o(1)=6, space=7 → clean cut at 7.
+    // Use a multibyte straddle instead: 'aé' repeated — cut at 7 bytes: a(1)é(2)a(1)é(2)=6 +a(1)=7 → next é straddles: trimmed.
+    bash.handler = () => runResult(`${matchLine('a.txt', 1, 'aéaéaéaé')}\n`)
+    const result = await call(ctx, 'grep', { pattern: 'a' })
+    expect(text(result)).toContain('Line 1: aéaéa (line truncated)')
+  })
+
+  it('renders a non-UTF-8 line (rg bytes form) as a placeholder instead of failing', async () => {
+    const { ctx, bash } = await setup()
+    const record = JSON.stringify({ type: 'match', data: { path: { text: 'bin.dat' }, lines: { bytes: 'AAECww==' }, line_number: 4 } })
+    bash.handler = () => runResult(`${record}\n`)
+    expect(text(await call(ctx, 'grep', { pattern: 'x' }))).toContain('Line 4: (line is not valid UTF-8)')
+  })
+
+  it('strips a CRLF terminator from the matched line text', () => {
+    const matches = parseGrepMatches(`${matchLine('a.txt', 1, 'windows line\r\n')}\n`)
+    expect(matches[0]?.line).toBe('windows line')
+  })
+
+  it('caps at grepMaxMatches and spills the full formatted match list', async () => {
+    const { ctx, bash, spill } = await setup({ config: { grepMaxMatches: 2 }, spill: true })
+    bash.handler = () => runResult([
+      matchLine('a.ts', 1, 'one'),
+      matchLine('a.ts', 2, 'two'),
+      matchLine('b.ts', 3, 'three'),
+      '',
+    ].join('\n'))
+    const result = await call(ctx, 'grep', { pattern: 'e' }, { agent: agent('/w') })
+    expect(text(result)).toBe('Found 2 of 3 matches\n\na.ts\nLine 1: one\nLine 2: two\n\n(Full grep result stored at: /spill/grep-results.txt. Use the fake retrieval hint.)')
+    expect(spill?.saves[0]).toMatchObject({
+      source: { toolName: 'grep', label: 'result' },
+      suggestedName: 'grep-results.txt',
+      content: 'Found 3 matches\n\na.ts\nLine 1: one\nLine 2: two\n\nb.ts\nLine 3: three',
+    })
+  })
+
+  it('reports the unsaved remainder when capped with no spill backend', async () => {
+    const { ctx, bash } = await setup({ config: { grepMaxMatches: 1 } })
+    bash.handler = () => runResult(`${matchLine('a.ts', 1, 'one')}\n${matchLine('a.ts', 2, 'two')}\n`)
+    const result = await call(ctx, 'grep', { pattern: 'o' }, { agent: agent('/w') })
+    expect(result.isError).toBe(false)
+    expect(text(result)).toBe('Found 1 of 2 matches\n\na.ts\nLine 1: one\n\n(The complete result could not be saved; narrow pattern, path, or include to see more.)')
+  })
+
+  it('validates arguments (empty pattern, blank path, bad include)', async () => {
+    const { ctx } = await setup()
+    expect(text(await call(ctx, 'grep', { pattern: '' }))).toContain('pattern must be a non-empty string')
+    expect(text(await call(ctx, 'grep', { pattern: 'x', path: '  ' }))).toContain('path must be a non-empty string')
+    expect(text(await call(ctx, 'grep', { pattern: 'x', include: '  ' }))).toContain('include must be a non-empty glob')
+    expect(text(await call(ctx, 'grep', { pattern: 'x', include: '!*.ts' }))).toContain('negated patterns')
+    expect(text(await call(ctx, 'grep', { pattern: 'x', include: '*.ts,*.js' }))).toContain('comma-separated list')
+  })
+
+  it('accepts a whitespace-only pattern (a legitimate regex) and brace alternation in include', async () => {
+    const { ctx, bash } = await setup()
+    bash.handler = () => runResult('', { exitCode: 1 })
+    const result = await call(ctx, 'grep', { pattern: '  ', include: '*.{ts,tsx}' })
+    expect(result.isError).toBe(false)
+  })
+})
+
+describe('rg --json transport failures (SEARCH_FAILED)', () => {
+  it.each([
+    ['a non-JSON line', 'not json at all'],
+    ['a non-object record', '42'],
+    ['a match record with no data', JSON.stringify({ type: 'match' })],
+    ['a match record with no path text', JSON.stringify({ type: 'match', data: { path: {}, lines: { text: 'x' }, line_number: 1 } })],
+    ['a match record with a non-object path', JSON.stringify({ type: 'match', data: { path: 'a.ts', lines: { text: 'x' }, line_number: 1 } })],
+    ['a match record with no line number', JSON.stringify({ type: 'match', data: { path: { text: 'a.ts' }, lines: { text: 'x' } } })],
+    ['a match record with no line content', JSON.stringify({ type: 'match', data: { path: { text: 'a.ts' }, line_number: 1 } })],
+    ['a match record with neither text nor bytes', JSON.stringify({ type: 'match', data: { path: { text: 'a.ts' }, lines: {}, line_number: 1 } })],
+  ])('%s fails the search', async (_label, line) => {
+    const { ctx, bash } = await setup()
+    bash.handler = () => runResult(`${line}\n`)
+    const result = await call(ctx, 'grep', { pattern: 'x' })
+    expect(result.isError).toBe(true)
+    expect(result.error).toMatchObject({ name: 'SearchError', code: 'SEARCH_FAILED' })
+  })
+})
+
+describe('the no-background-task invariant', () => {
+  it('never calls ctx.bash.start() across successful and failed searches', async () => {
+    const { ctx, bash } = await setup()
+    bash.handler = () => runResult('a.ts\n')
+    await call(ctx, 'glob', { pattern: '*' })
+    bash.handler = () => runResult('', { exitCode: 2, stderr: { text: 'boom', truncated: false } })
+    await call(ctx, 'grep', { pattern: 'x' })
+    expect(bash.startCalls).toBe(0)
+  })
+})
+
+describe('presentation', () => {
+  it('glob titles carry the pattern and optional root', () => {
+    expect(presentGlobCall({ pattern: '**/*.ts' })).toMatchObject({ card: 'generic', title: 'Glob **/*.ts', kind: 'search' })
+    expect(presentGlobCall({ pattern: '*.md', path: 'docs' }).title).toBe('Glob *.md in docs')
+  })
+
+  it('grep titles carry the pattern, target, and include filter', () => {
+    expect(presentGrepCall({ pattern: 'todo' })).toMatchObject({ card: 'generic', title: 'Grep todo', kind: 'search' })
+    expect(presentGrepCall({ pattern: 'todo', path: 'src', include: '*.ts' }).title).toBe('Grep todo in src (*.ts)')
+  })
+})
+
+describe('helpers', () => {
+  it('toWorkdirRelative maps inside-workdir absolutes and passes everything else through', () => {
+    expect(toWorkdirRelative('/w/a/b.ts', '/w')).toBe('a/b.ts')
+    expect(toWorkdirRelative('/w', '/w')).toBe('.')
+    expect(toWorkdirRelative('/other/b.ts', '/w')).toBe('/other/b.ts')
+    expect(toWorkdirRelative('/w-sibling/b.ts', '/w')).toBe('/w-sibling/b.ts')
+    expect(toWorkdirRelative('rel/b.ts', '/w')).toBe('rel/b.ts')
+    // Normalization makes this land OUTSIDE the workdir → original path kept.
+    expect(toWorkdirRelative('/w/../up.ts', '/w')).toBe('/w/../up.ts')
+  })
+
+  it('previewLine keeps a within-budget line untouched', () => {
+    expect(previewLine('short', 100)).toBe('short')
+  })
+
+  it('formatGrepMatches groups by first-seen file order', () => {
+    const grouped = formatGrepMatches([
+      { path: 'b.ts', lineNumber: 2, line: 'x' },
+      { path: 'a.ts', lineNumber: 1, line: 'y' },
+      { path: 'b.ts', lineNumber: 5, line: 'z' },
+    ])
+    expect(grouped).toBe('b.ts\nLine 2: x\nLine 5: z\n\na.ts\nLine 1: y')
+  })
+})

packages/fs/tool-fs-search/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": ["src"],
+  "references": [
+    { "path": "../../../vendor/cosmokit" },
+    { "path": "../../../vendor/cordis" },
+    { "path": "../../../vendor/schemastery" },
+    { "path": "../../util/retention" },
+    { "path": "../../llm/llm" },
+    { "path": "../../core/session" },
+    { "path": "../../core/tools" },
+    { "path": "../../core/system-prompt" },
+    { "path": "../../bash/bash" },
+    { "path": "../../spill/spill" }
+  ]
+}

packages/fs/tool-fs/README.md

@@ -34,7 +34,7 @@ Field names are snake_case to match Claude Code and existing harness tool schema
 
 ## The tool is the executor; policy is an event gate
 
-The tools do **not** inject a policy service or inspect any cache. Each tool resolves the path via `ctx.fs.resolve(path, { cwd })` — passing the calling agent's session cwd (`exec.agent.session.header.cwd`) so a relative path resolves against the session's workspace, matching `dsh-tool-bash` (see [the per-session cwd RFC](../../../docs/rfc/implemented/architecture/2026-07-02-fs-per-session-cwd.md)) — then:
+The tools do **not** inject a policy service or inspect any cache. Each tool resolves the path via `ctx.fs.resolve(path, { cwd, signal })` — passing the calling agent's session cwd (`exec.agent.session.header.cwd`) so a relative path resolves against the session's workspace, matching `dsh-tool-bash`, and forwarding tool cancellation through resolution (see [the per-session cwd RFC](../../../docs/rfc/implemented/architecture/2026-07-02-fs-per-session-cwd.md)) — then:
 
 - **read** — one `ctx.fs.stat` (type + size routing + version), then `readText`/`streamText`, then builds the line window, then emits `fs/observed` with a plain `ctx.emit`. (1 stat.)
 - **write** — `ctx.waterfall('fs/write-intent', target, exec, () => undefined)` for the optional guard, then `ctx.fs.writeText(target, content, intent)`, then `fs/observed`. (0 stat.)
@@ -100,6 +100,6 @@ Use the edit tool for targeted changes to existing UTF-8 text files. It replaces
 
 ## Known Limitations and Deferred Work
 
-- **No directory-listing, glob, grep, or search tools ship** — a deferral of [the tool-schemas RFC](../../../docs/rfc/implemented/feature/2026-06-17-filesystem-tool-schemas.md); `ctx.fs.listDir` serves provider code such as skill discovery but still has no model-facing consumer, so models fall back to `bash`.
+- **No model-facing directory listing ships** — `ctx.fs.listDir` serves provider code such as skill discovery, while the sibling [`dsh-tool-fs-search`](../tool-fs-search/) package supplies bash-backed `glob` and `grep` rather than extending the filesystem seam.
 - **`read` handles UTF-8 text files only** — binary-safe reads and PDF/image/multimodal content are deferred; a directory target is `FS_NOT_REGULAR_FILE`.
 - **No timeout surface** — `read`/`write`/`edit` take no timeout argument and declare no `timeout-policy` budget; cancellation rides `exec.signal` only (the deliberate [fs-family stance](../README.md)).

packages/fs/tool-fs/src/edit.ts

@@ -12,7 +12,7 @@ import type { ContentBlock } from '@deepseek-ai/dsh-llm'
 import type {} from '@deepseek-ai/dsh-fs'
 import type {} from '@deepseek-ai/dsh-system-prompt'
 import { computeHunkDiffs, diffsFromMeta, type FsDiffMeta } from './diff.ts'
-import { sessionCwd } from './session-cwd.ts'
+import { sessionResolveOptions } from './session-cwd.ts'
 
 /** Validated `edit` arguments after defaulting. */
 interface EditInput {
@@ -75,8 +75,7 @@ export function applyEditTool(ctx: Context): void {
     },
     async execute(args, exec): Promise<{ content: ContentBlock[]; meta?: FsDiffMeta }> {
       const input = parseEditArgs(args)
-      const cwd = sessionCwd(exec)
-      const target = await ctx.fs.resolve(input.filePath, cwd !== undefined ? { cwd } : undefined)
+      const target = await ctx.fs.resolve(input.filePath, sessionResolveOptions(exec))
       // Single-slot decision: the policy plugin returns { version: vObserved } or
       // throws FS_NOT_OBSERVED; the bare default is undefined (unconditional edit).
       // No stat — the bare default never manufactures a version basis.

packages/fs/tool-fs/src/read.ts

@@ -13,7 +13,7 @@ import type {} from '@deepseek-ai/dsh-fs'
 import type {} from '@deepseek-ai/dsh-system-prompt'
 import { buildWindow, formatReadOutput } from './read-render.ts'
 import type { FileReadOutcome } from './read-render.ts'
-import { sessionCwd } from './session-cwd.ts'
+import { sessionResolveOptions } from './session-cwd.ts'
 
 /** Default and maximum number of lines returned by one `read` call (the `readLimit` config). */
 export const READ_LIMIT = 2000
@@ -86,8 +86,7 @@ export function applyReadTool(ctx: Context, caps: ReadToolCaps): void {
     },
     async execute(args, exec): Promise<ContentBlock[]> {
       const input = parseReadArgs(args, caps.limit)
-      const cwd = sessionCwd(exec)
-      const target = await ctx.fs.resolve(input.filePath, cwd !== undefined ? { cwd } : undefined)
+      const target = await ctx.fs.resolve(input.filePath, sessionResolveOptions(exec))
 
       // One stat: type check + size routing + the version recorded as observed.
       // A concurrent write can only make a later guarded mutation fail stale and require reread.

packages/fs/tool-fs/src/session-cwd.ts

@@ -18,3 +18,16 @@ import type { ToolExecution } from '@deepseek-ai/dsh-tools'
 export function sessionCwd(exec: ToolExecution): string | undefined {
   return exec.agent?.session.header.cwd
 }
+
+/**
+ * Resolution options shared by all model-facing filesystem tools.
+ * @param exec - the tool-execution context supplying session cwd and cancellation.
+ * @returns provider resolution options for the current tool call.
+ */
+export function sessionResolveOptions(exec: ToolExecution): { cwd?: string; signal?: AbortSignal } {
+  const cwd = sessionCwd(exec)
+  return {
+    ...cwd !== undefined ? { cwd } : {},
+    ...exec.signal !== undefined ? { signal: exec.signal } : {},
+  }
+}

packages/fs/tool-fs/src/write.ts

@@ -13,7 +13,7 @@ import type { FsWriteOutcome } from '@deepseek-ai/dsh-fs'
 import type {} from '@deepseek-ai/dsh-fs'
 import type {} from '@deepseek-ai/dsh-system-prompt'
 import { computeHunkDiffs, diffsFromMeta, type FsDiffMeta } from './diff.ts'
-import { sessionCwd } from './session-cwd.ts'
+import { sessionResolveOptions } from './session-cwd.ts'
 
 /**
  * Validate value constraints the schema DSL can't express: only a non-blank
@@ -61,8 +61,7 @@ export function applyWriteTool(ctx: Context): void {
     },
     async execute(args, exec): Promise<{ content: ContentBlock[]; meta?: FsDiffMeta }> {
       const input = parseWriteArgs(args)
-      const cwd = sessionCwd(exec)
-      const target = await ctx.fs.resolve(input.filePath, cwd !== undefined ? { cwd } : undefined)
+      const target = await ctx.fs.resolve(input.filePath, sessionResolveOptions(exec))
       // Single-slot decision: the policy plugin produces createIfAbsent/
       // replaceIfVersion; the bare default is undefined (unconditional). No stat.
       const intent = await ctx.waterfall('fs/write-intent', target, exec, () => undefined)

packages/fs/tool-fs/tests/tools.spec.ts

@@ -14,6 +14,7 @@ import type {
   FsEditOutcome,
   FsEditRequest,
   FsInfo,
+  FsPathInfo,
   FsTarget,
   FsWriteIntent,
   FsWriteOutcome,
@@ -44,6 +45,11 @@ class FakeFs extends FileSystem {
     if (content === undefined) return undefined
     return { version: FsVersion('v1'), type: 'file', size: content.length }
   }
+  override async lstat(path: string): Promise<FsPathInfo | undefined> {
+    const content = this.files.get(`key:${path}`)
+    if (content === undefined) return undefined
+    return { version: FsVersion('v1'), type: 'file', size: content.length }
+  }
   override async readText(target: FsTarget): Promise<string> {
     return this.files.get(target.targetKey) ?? ''
   }

packages/guard/README.md

@@ -6,4 +6,4 @@ Behavioral guard plugins that watch the agent loop for unproductive patterns and
 |---|---|---|
 | `repeat-tool-guard/` | Advisory reminders when an agent loops on identical tool calls | (listens on `ctx.tools`' waterfalls) |
 
-Reminders travel as `additionalContext` on the `tools/post-execute` decision; the agent loop appends them as logged `context/message` events after the step's tool results (see [the tools package](../core/tools)), so everything a guard says to the model is reconstructable from the session log.
+Reminders travel as `additionalContexts` on the `tools/post-execute` decision; the agent loop appends them as logged `context/message` events after the step's tool results (see [the tools package](../core/tools)), so everything a guard says to the model is reconstructable from the session log.

packages/guard/repeat-tool-guard/README.md

@@ -30,7 +30,7 @@ The chain key is `(tool name, canonical arguments)` — canonicalization is a de
 
 ## Reminder delivery
 
-Reminders use source-attributed `additionalContext`, preserving the tool's original result. The loop records them after the step's results as reconstructable `context/message` events. The guard always delegates and folds its reminder onto downstream context, including blocked calls.
+Reminders ride the post-execute decision's `additionalContexts` (source `{kind: 'plugin', plugin: 'repeat-tool-guard'}`), never a `content` replacement: the `tool/result` event stays the tool's own output for audit. The loop buffers the context and appends it as a `context/message` after the step's tool results, which the session renders as the tagged synthetic-user envelope — so the reminder is model-visible, source-attributed, and reconstructable from the session log with no new session event. The guard always delegates via `next()` and prepends its reminder to the downstream decision's context array (both variants — a blocked call still gets the nudge); every entry retains its own source, envelope, and metadata.
 
 ## Testing
 

packages/guard/repeat-tool-guard/src/index.ts

@@ -140,16 +140,11 @@ function validateThresholds(values: number[]): number[] {
 }
 
 /**
- * Concatenate the guard's reminder context with a downstream listener's
- * optional one so folding drops neither. The merged block carries the guard's
- * `source` — a `HookContext` holds one `MessageSource` and the seam cannot
- * represent mixed provenance; the rendered `context/message` only
- * distinguishes by `source.kind`, so a downstream plugin's text is still
- * correctly framed as plugin context.
+ * Prepend the guard's reminder while preserving every downstream context's
+ * source, envelope, and metadata.
  */
-function concatContext(ours: HookContext, theirs: HookContext | undefined): HookContext {
-  if (!theirs) return ours
-  return { content: [...ours.content, ...theirs.content], source: ours.source }
+function prependContext(ours: HookContext, theirs: HookContext[] | undefined): HookContext[] {
+  return [ours, ...theirs ?? []]
 }
 
 /** One agent's consecutive-repeat chain: the last tracked call's identity key and its run length. */
@@ -211,19 +206,19 @@ export function apply(ctx: Context, config: Config): void {
 
   // Observe-and-enrich, never veto: count first (state advances regardless of
   // the downstream outcome), DELEGATE so a later listener can still block or
-  // replace, then fold the reminder onto whatever came back — additionalContext
+  // replace, then fold the reminder onto whatever came back — additionalContexts
   // rides both decision variants, so a blocked call still gets the nudge.
   ctx.on('tools/post-execute', async (exec, _result, next): Promise<PostToolDecision> => {
     const reminder = observe(exec)
     const downstream = await next()
     if (!reminder) return downstream
     if (downstream.kind === 'block') {
-      return { kind: 'block', feedback: downstream.feedback, additionalContext: concatContext(reminder, downstream.additionalContext) }
+      return { kind: 'block', feedback: downstream.feedback, additionalContexts: prependContext(reminder, downstream.additionalContexts) }
     }
     return {
       kind: 'accept',
       ...downstream.content !== undefined ? { content: downstream.content } : {},
-      additionalContext: concatContext(reminder, downstream.additionalContext),
+      additionalContexts: prependContext(reminder, downstream.additionalContexts),
     }
   })
 

packages/guard/repeat-tool-guard/tests/repeat-tool-guard.spec.ts

@@ -309,7 +309,7 @@ describe('fold onto the downstream decision', () => {
     ctx.on('tools/post-execute', async () => ({
       kind: 'block' as const,
       feedback: [{ type: 'text' as const, text: 'nope' }],
-      additionalContext: { content: [{ type: 'text' as const, text: 'downstream-ctx' }], source: { kind: 'plugin' as const, plugin: 'test' } },
+      additionalContexts: [{ content: [{ type: 'text' as const, text: 'downstream-ctx' }], source: { kind: 'plugin' as const, plugin: 'test' } }],
     }))
     const adapter = new MockAdapter([
       toolCallResponse('c1', 'probe', { q: 1 }),
@@ -322,14 +322,14 @@ describe('fold onto the downstream decision', () => {
     await waitForIdle(ctx, agent)
 
     const found = reminders(agent)
-    expect(found).toHaveLength(2)
+    expect(found).toHaveLength(3)
     // Call 1: below threshold — the downstream context passes through untouched.
     expect(found[0]!.text).toBe('downstream-ctx')
     expect(found[0]!.source).toEqual({ kind: 'plugin', plugin: 'test' })
-    // Call 2: reminder folded in front, single merged context, the guard's source.
+    // Call 2: reminder and downstream context retain separate provenance.
     expect(found[1]!.text).toContain('repeating the exact same tool call')
-    expect(found[1]!.text).toContain('|downstream-ctx')
     expect(found[1]!.source).toEqual(GUARD_SOURCE)
+    expect(found[2]).toEqual({ text: 'downstream-ctx', source: { kind: 'plugin', plugin: 'test' } })
     // The block's feedback reached the tool result unchanged.
     const results = [...agent.session.events].filter((e): e is SessionEvent<'tool/result'> => e.type === 'tool/result')
     expect(results.every(r => r.data.isError)).toBe(true)

packages/hooks/hook-protocol/tests/runner.spec.ts

@@ -22,6 +22,7 @@ function recordingBash(run: (spec: BashExecSpec) => Promise<BashRunResult>): {
         command: request.command,
         workdir: request.workdir ?? '/stub',
         timeoutMs: request.timeoutMs ?? 0,
+        stdoutMaxBytes: request.stdoutMaxBytes ?? 64_000,
         ...request.signal ? { signal: request.signal } : {},
         ...request.stdin !== undefined ? { stdin: request.stdin } : {},
         ...request.env !== undefined ? { env: request.env } : {},

packages/hooks/hooks-claude/README.md

@@ -35,9 +35,9 @@ The hooks **themselves** run in the agent's session workspace: for the agent-sco
 | CC hook | Harness seam | Mapping |
 |---|---|---|
 | `SessionStart` | `agent/session-start` (emit) | additionalContext → `agent.inject()` into the new session (cannot block) |
-| `UserPromptSubmit` | `agent/prompt-submit` (waterfall) | `deny` → `PromptDecision.block`; additionalContext-only → delegate via `next()` then fold context onto the downstream decision (a later listener can still block/rewrite) |
+| `UserPromptSubmit` | `agent/prompt-submit` (waterfall) | `deny` → `PromptDecision.block`; additionalContext-only → delegate via `next()` then prepend a separately sourced context to downstream `additionalContexts` (a later listener can still block/rewrite) |
 | `PreToolUse` | `tools/pre-execute` (waterfall) | `deny` → `PreToolDecision.deny`; `ask` → `PreToolDecision.ask` |
-| `PostToolUse` | `tools/post-execute` (waterfall) | `deny` → `block` with feedback; additionalContext-only → delegate via `next()` then fold context onto the downstream decision (a Code Mode sub-call’s context is dropped by the run_code bridge — see [the pipeline doc](../../../docs/tool-execution-pipeline.md)) |
+| `PostToolUse` | `tools/post-execute` (waterfall) | `deny` → `block` with feedback; additionalContext-only → delegate via `next()` then prepend a separately sourced context to the downstream decision; Code Mode defers sub-call contexts until the outer `run_code` result |
 | `Stop` | `agent/turn-continuation` (waterfall) | a blocking Stop hook forces `continue`, feeding its reason as next-step steering |
 | `SubagentStart` | `subagent/start` (emit) | additionalContext → `agent.inject()` into a live in-process child; a remote child has no local injection target |
 | `SubagentStop` | `subagent/end` (emit) | observe-only |

packages/hooks/hooks-claude/src/index.ts

@@ -188,10 +188,9 @@ export function apply(ctx: Context, config: Config): void {
     return { content, source: PLUGIN_SOURCE }
   }
 
-  /** Merge hook context while retaining this bridge's plugin-level source. */
-  function concatContext(ours: HookContext, theirs: HookContext | undefined): HookContext {
-    if (!theirs) return ours
-    return { content: [...ours.content, ...theirs.content], source: ours.source }
+  /** Prepend one context without flattening downstream provenance or metadata. */
+  function prependContext(ours: HookContext, theirs: HookContext[] | undefined): HookContext[] {
+    return [ours, ...theirs ?? []]
   }
 
   // SessionStart injects context when its detached hook resolves; a slow hook
@@ -224,7 +223,7 @@ export function apply(ctx: Context, config: Config): void {
     return {
       kind: 'allow',
       ...downstream.content !== undefined ? { content: downstream.content } : {},
-      additionalContext: concatContext(ours, downstream.additionalContext),
+      additionalContexts: prependContext(ours, downstream.additionalContexts),
     }
   })
 
@@ -243,19 +242,19 @@ export function apply(ctx: Context, config: Config): void {
     const merged = await runPoint('PostToolUse', exec.name, postToolPayload(exec, result), { ...exec.agent ? { agent: exec.agent } : {}, turn, ...exec.signal ? { signal: exec.signal } : {} })
     const context = contextFrom(merged)
     if (merged.decision === 'deny') {
-      return { kind: 'block', feedback: [{ type: 'text', text: merged.reason ?? 'blocked by PostToolUse hook' }], ...context ? { additionalContext: context } : {} }
+      return { kind: 'block', feedback: [{ type: 'text', text: merged.reason ?? 'blocked by PostToolUse hook' }], ...context ? { additionalContexts: [context] } : {} }
     }
     // Our hooks did not block. DELEGATE so a later listener can still block/replace,
     // then fold our context onto its decision (a downstream block carries it too).
     const downstream = await next()
     if (!context) return downstream
     if (downstream.kind === 'block') {
-      return { ...downstream, additionalContext: concatContext(context, downstream.additionalContext) }
+      return { ...downstream, additionalContexts: prependContext(context, downstream.additionalContexts) }
     }
     return {
       kind: 'accept',
       ...downstream.content !== undefined ? { content: downstream.content } : {},
-      additionalContext: concatContext(context, downstream.additionalContext),
+      additionalContexts: prependContext(context, downstream.additionalContexts),
     }
   })
 

packages/hooks/hooks-claude/tests/coverage.spec.ts

@@ -475,9 +475,9 @@ describe('hooks-claude coverage — continue:false, context arm, no-cwd', () =>
     expect(turnEnd?.type === 'turn/end' && turnEnd.data.reason).toMatchObject({ kind: 'rejected', reason: 'policy veto' })
   })
 
-  it('folds the bridge additionalContext WITH a downstream listener that also adds context', async () => {
+  it('preserves separate bridge and downstream prompt contexts with framing and metadata', async () => {
     // Both the bridge hook and a later prompt-submit listener attach context; the
-    // request must see BOTH (concatContext keeps the downstream one too).
+    // request must see both as separately sourced durable events.
     const d = dir()
     const s = sh(d, 'ctx.sh', '#!/usr/bin/env bash\necho \'{"hookSpecificOutput":{"hookEventName":"UserPromptSubmit","additionalContext":"from-bridge"}}\'\n')
     const path = hooks(d, { UserPromptSubmit: [{ hooks: [{ type: 'command', command: s }] }] })
@@ -486,7 +486,12 @@ describe('hooks-claude coverage — continue:false, context arm, no-cwd', () =>
     ctx.on('agent/prompt-submit', async () => ({
       kind: 'allow' as const,
       content: [{ type: 'text' as const, text: 'rewritten-prompt' }],
-      additionalContext: { content: [{ type: 'text' as const, text: 'from-downstream' }], source: { kind: 'plugin' as const, plugin: 'policy' } },
+      additionalContexts: [{
+        content: [{ type: 'text' as const, text: 'from-downstream' }],
+        source: { kind: 'plugin' as const, plugin: 'policy' },
+        envelope: 'raw' as const,
+        meta: { owner: 'policy' },
+      }],
     }))
     const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
     agent.send([{ type: 'text', text: 'go' }])
@@ -498,6 +503,13 @@ describe('hooks-claude coverage — continue:false, context arm, no-cwd', () =>
     // the original prompt was replaced by the downstream rewrite
     const userMsg = events(agent).find(e => e.type === 'user/message')
     expect(userMsg?.type === 'user/message' && userMsg.data.content.some(b => b.type === 'text' && b.text === 'rewritten-prompt')).toBe(true)
+    const contexts = events(agent).filter(event => event.type === 'context/message')
+    expect(contexts.map(event => event.type === 'context/message' && event.data.source)).toEqual([
+      { kind: 'plugin', plugin: 'hooks-claude' },
+      { kind: 'plugin', plugin: 'policy' },
+    ])
+    expect(contexts[1]?.type === 'context/message' && contexts[1].data.envelope).toBe('raw')
+    expect(contexts[1]?.type === 'context/message' && contexts[1].data.meta).toEqual({ owner: 'policy' })
   })
 
   it('folds the bridge PostToolUse context onto a downstream ACCEPT that replaces content', async () => {
@@ -518,6 +530,35 @@ describe('hooks-claude coverage — continue:false, context arm, no-cwd', () =>
     expect(events(agent).some(e => e.type === 'context/message' && e.data.content.some(b => b.type === 'text' && b.text.includes('bridge-note')))).toBe(true)
   })
 
+  it('keeps bridge and downstream PostToolUse contexts as separate sourced events', async () => {
+    const d = dir()
+    const s = sh(d, 'ctx.sh', '#!/usr/bin/env bash\necho \'{"hookSpecificOutput":{"hookEventName":"PostToolUse","additionalContext":"bridge-note"}}\'\n')
+    const path = hooks(d, { PostToolUse: [{ hooks: [{ type: 'command', command: s }] }] })
+    const adapter = new MockAdapter([toolCallResponse('c1', 'echo', {}), textResponse('done')])
+    const ctx = await harness(path, adapter)
+    ctx.tools.register(defineTool({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
+    ctx.on('tools/post-execute', async () => ({
+      kind: 'accept' as const,
+      additionalContexts: [{
+        content: [{ type: 'text' as const, text: 'downstream-note' }],
+        source: { kind: 'plugin' as const, plugin: 'policy' },
+        envelope: 'raw' as const,
+        meta: { owner: 'policy' },
+      }],
+    }))
+    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    agent.send([{ type: 'text', text: 'go' }])
+    await waitForIdle(ctx, agent)
+
+    const contexts = events(agent).filter(event => event.type === 'context/message')
+    expect(contexts.map(event => event.type === 'context/message' && event.data.source)).toEqual([
+      { kind: 'plugin', plugin: 'hooks-claude' },
+      { kind: 'plugin', plugin: 'policy' },
+    ])
+    expect(contexts[1]?.type === 'context/message' && contexts[1].data.envelope).toBe('raw')
+    expect(contexts[1]?.type === 'context/message' && contexts[1].data.meta).toEqual({ owner: 'policy' })
+  })
+
   it('folds the bridge PostToolUse context onto a downstream listener BLOCK', async () => {
     // The bridge hook only adds context; a later post-execute listener blocks the
     // result. The block wins AND carries the bridge context (concatContext on the

packages/hooks/hooks-codex/README.md

@@ -41,9 +41,9 @@ The hooks themselves run in the agent's session workspace: for the agent-scoped
 | Codex hook | Harness seam | Mapping |
 |---|---|---|
 | `SessionStart` | `agent/session-start` (emit) | a plain-stdout hook's output → additionalContext → `agent.inject()` |
-| `UserPromptSubmit` | `agent/prompt-submit` (waterfall) | `block` (exit 2) → `PromptDecision.block`; additionalContext-only → delegate via `next()` then fold context onto the downstream decision |
+| `UserPromptSubmit` | `agent/prompt-submit` (waterfall) | `block` (exit 2) → `PromptDecision.block`; additionalContext-only → delegate via `next()` then prepend a separately sourced context to downstream `additionalContexts` |
 | `PreToolUse` | `tools/pre-execute` (waterfall) | `block` → `PreToolDecision.deny` (no `allow`/`ask`) |
-| `PostToolUse` | `tools/post-execute` (waterfall) | `block` → `block` with feedback; additionalContext-only → delegate via `next()` then fold context onto the downstream decision (a Code Mode sub-call’s context is dropped by the run_code bridge — see [the pipeline doc](../../../docs/tool-execution-pipeline.md)) |
+| `PostToolUse` | `tools/post-execute` (waterfall) | `block` → `block` with feedback; additionalContext-only → delegate via `next()` then prepend a separately sourced context to the downstream decision; Code Mode defers sub-call contexts until the outer `run_code` result |
 | `Stop` | `agent/turn-continuation` (waterfall) | a blocking Stop hook forces `continue` with the reason as next-step steering |
 
 A tool call's payload carries the real `tool_name` (the same value the matcher tests) and Codex's `tool_input: { command }` shape (the `command` arg when present, else `''`). The matcher subject is the tool name (`PreToolUse`/`PostToolUse`) or the session source (`SessionStart`); `UserPromptSubmit`/`Stop` ignore matchers.

packages/hooks/hooks-codex/src/index.ts

@@ -163,10 +163,9 @@ export function apply(ctx: Context, config: Config): void {
     return { content, source: PLUGIN_SOURCE }
   }
 
-  /** Merge hook context while retaining this bridge's plugin-level source. */
-  function concatContext(ours: HookContext, theirs: HookContext | undefined): HookContext {
-    if (!theirs) return ours
-    return { content: [...ours.content, ...theirs.content], source: ours.source }
+  /** Prepend one context without flattening downstream provenance or metadata. */
+  function prependContext(ours: HookContext, theirs: HookContext[] | undefined): HookContext[] {
+    return [ours, ...theirs ?? []]
   }
 
   // SessionStart injects plain stdout when its detached hook resolves; a slow
@@ -196,7 +195,7 @@ export function apply(ctx: Context, config: Config): void {
     return {
       kind: 'allow',
       ...downstream.content !== undefined ? { content: downstream.content } : {},
-      additionalContext: concatContext(ours, downstream.additionalContext),
+      additionalContexts: prependContext(ours, downstream.additionalContexts),
     }
   })
 
@@ -216,19 +215,19 @@ export function apply(ctx: Context, config: Config): void {
     const merged = await runPoint('PostToolUse', exec.name, postToolPayload(exec, result, model), { ...exec.agent ? { agent: exec.agent } : {}, turn, ...exec.signal ? { signal: exec.signal } : {} })
     const context = contextFrom(merged)
     if (merged.decision === 'deny') {
-      return { kind: 'block', feedback: [{ type: 'text', text: merged.reason ?? 'blocked by PostToolUse hook' }], ...context ? { additionalContext: context } : {} }
+      return { kind: 'block', feedback: [{ type: 'text', text: merged.reason ?? 'blocked by PostToolUse hook' }], ...context ? { additionalContexts: [context] } : {} }
     }
     // Context alone is not a veto: DELEGATE, then fold our context onto the
     // downstream decision (a downstream block carries it too).
     const downstream = await next()
     if (!context) return downstream
     if (downstream.kind === 'block') {
-      return { ...downstream, additionalContext: concatContext(context, downstream.additionalContext) }
+      return { ...downstream, additionalContexts: prependContext(context, downstream.additionalContexts) }
     }
     return {
       kind: 'accept',
       ...downstream.content !== undefined ? { content: downstream.content } : {},
-      additionalContext: concatContext(context, downstream.additionalContext),
+      additionalContexts: prependContext(context, downstream.additionalContexts),
     }
   })
 

packages/hooks/hooks-codex/tests/coverage.spec.ts

@@ -85,7 +85,7 @@ describe('hooks-codex coverage — decision mapping paths', () => {
     expect(te?.type === 'turn/end' && te.data.reason).toMatchObject({ kind: 'rejected', reason: 'policy veto' })
   })
 
-  it('folds the bridge additionalContext WITH a downstream listener that also adds context', async () => {
+  it('preserves separate bridge and downstream prompt contexts with framing and metadata', async () => {
     const d = dir()
     hooks(d, { UserPromptSubmit: [{ hooks: [{ type: 'command', command: sh(d, 'c.sh', '#!/usr/bin/env bash\necho \'{"hookSpecificOutput":{"hookEventName":"UserPromptSubmit","additionalContext":"from-bridge"}}\'\n') }] }] })
     const adapter = new MockAdapter([textResponse('ok')])
@@ -93,7 +93,12 @@ describe('hooks-codex coverage — decision mapping paths', () => {
     ctx.on('agent/prompt-submit', async () => ({
       kind: 'allow' as const,
       content: [{ type: 'text' as const, text: 'rewritten-prompt' }],
-      additionalContext: { content: [{ type: 'text' as const, text: 'from-downstream' }], source: { kind: 'plugin' as const, plugin: 'policy' } },
+      additionalContexts: [{
+        content: [{ type: 'text' as const, text: 'from-downstream' }],
+        source: { kind: 'plugin' as const, plugin: 'policy' },
+        envelope: 'raw' as const,
+        meta: { owner: 'policy' },
+      }],
     }))
     const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
     agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
@@ -101,6 +106,13 @@ describe('hooks-codex coverage — decision mapping paths', () => {
     expect(req).toContain('from-bridge')
     expect(req).toContain('from-downstream')
     expect(req).toContain('rewritten-prompt')
+    const contexts = events(agent).filter(event => event.type === 'context/message')
+    expect(contexts.map(event => event.type === 'context/message' && event.data.source)).toEqual([
+      { kind: 'plugin', plugin: 'hooks-codex' },
+      { kind: 'plugin', plugin: 'policy' },
+    ])
+    expect(contexts[1]?.type === 'context/message' && contexts[1].data.envelope).toBe('raw')
+    expect(contexts[1]?.type === 'context/message' && contexts[1].data.meta).toEqual({ owner: 'policy' })
   })
 
   it('folds the bridge PostToolUse context onto a downstream ACCEPT that replaces content', async () => {
@@ -117,6 +129,33 @@ describe('hooks-codex coverage — decision mapping paths', () => {
     expect(events(agent).some(e => e.type === 'context/message' && e.data.content.some(b => b.type === 'text' && b.text.includes('bridge-note')))).toBe(true)
   })
 
+  it('keeps bridge and downstream PostToolUse contexts as separate sourced events', async () => {
+    const d = dir()
+    hooks(d, { PostToolUse: [{ hooks: [{ type: 'command', command: sh(d, 'pc.sh', '#!/usr/bin/env bash\necho \'{"hookSpecificOutput":{"hookEventName":"PostToolUse","additionalContext":"bridge-note"}}\'\n') }] }] })
+    const adapter = new MockAdapter([toolCallResponse('c1', 'echo', {}), textResponse('done')])
+    const ctx = await harness(join(d, 'hooks.json'), adapter)
+    ctx.tools.register(defineTool({ name: 'echo', description: 'e', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
+    ctx.on('tools/post-execute', async () => ({
+      kind: 'accept' as const,
+      additionalContexts: [{
+        content: [{ type: 'text' as const, text: 'downstream-note' }],
+        source: { kind: 'plugin' as const, plugin: 'policy' },
+        envelope: 'raw' as const,
+        meta: { owner: 'policy' },
+      }],
+    }))
+    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    agent.send([{ type: 'text', text: 'go' }]); await waitForIdle(ctx, agent)
+
+    const contexts = events(agent).filter(event => event.type === 'context/message')
+    expect(contexts.map(event => event.type === 'context/message' && event.data.source)).toEqual([
+      { kind: 'plugin', plugin: 'hooks-codex' },
+      { kind: 'plugin', plugin: 'policy' },
+    ])
+    expect(contexts[1]?.type === 'context/message' && contexts[1].data.envelope).toBe('raw')
+    expect(contexts[1]?.type === 'context/message' && contexts[1].data.meta).toEqual({ owner: 'policy' })
+  })
+
   it('folds the bridge PostToolUse context onto a downstream listener BLOCK', async () => {
     const d = dir()
     hooks(d, { PostToolUse: [{ hooks: [{ type: 'command', command: sh(d, 'pc.sh', '#!/usr/bin/env bash\necho \'{"hookSpecificOutput":{"hookEventName":"PostToolUse","additionalContext":"bridge-note"}}\'\n') }] }] })
@@ -394,7 +433,7 @@ describe('hooks-codex coverage — decision mapping paths', () => {
     const { CallId } = await import('@deepseek-ai/dsh-llm')
     const result = await ctx.tools.execute({ callId: CallId('c1'), name: 'Bash', arguments: { command: 'x' } })
     expect(result.isError).toBeFalsy()
-    expect(result.additionalContext?.content.some(b => b.type === 'text' && b.text === 'x')).toBe(true)
+    expect(result.additionalContexts?.[0]?.content.some(b => b.type === 'text' && b.text === 'x')).toBe(true)
   })
 
   it('when the bash executor REJECTS, the hook/result omits exitCode (non-blocking)', async () => {