feat(spill): bound the durable copy of Code Mode sub-dispatch results

New tools/code-dispatch-log waterfall (run via registry.shapeDispatchLog,
contained — a throwing listener falls back to the unshaped content) lets
listeners reshape the tool/code-dispatch event's content before the
bridge appends it. dsh-spill-policy registers a second arm sharing the
model-facing arm's exact replacement pipeline (same maxInlineBytes cap,
preview + locator, within-cap invariant, best-effort fallbacks), with
artifacts labeled dispatch under the sub-call id. The program's value is
untouched; read sub-calls ARE bounded (a log copy is not model context,
and read produces the biggest logs). Resolves the tools README's
uncapped-dispatch-log Known Limitation.

packages/core/scope/src/scoped-events.generated.ts

@@ -35,6 +35,7 @@ const scopedSubjectResolvers: Readonly<Record<string, ScopedSubjectResolver | nu
   'subagent/end': null,
   'subagent/start': null,
   'system-prompt/assemble': args => (args[1] as Record<string, unknown>)['scope'],
+  'tools/code-dispatch-log': args => (args[0] as Record<string, unknown>)['agent'],
   'tools/execute': args => (args[0] as Record<string, unknown>)['agent'],
   'tools/post-execute': args => (args[0] as Record<string, unknown>)['agent'],
   'tools/pre-execute': args => (args[0] as Record<string, unknown>)['agent'],

packages/core/tools/README.md

@@ -189,5 +189,5 @@ Append-only; newly visible content follows the reusable request prefix and does
 - **Caller-defined subagent and workflow structured outputs remain object-rooted** — this is a consumer-level guard; the shared schema vocabulary and tool outputs support every JSON root.
 - **`timeoutMs` on a definition is declarative only** — the registry never enforces deadlines; enforcement requires the `@deepseek-ai/dsh-timeout-policy` wrapper.
 - **Code Mode is TypeScript-only and the presentation mode is service-wide** — `mode: code`/`both` rejects prompt assembly unless `ctx.codeRuntime.language === 'typescript'`; scoped restrictions/shadows still choose each agent's visible bindings, but one tool cannot be native-only while another is code-only.
-- **Code Mode intermediate values are execution-local and unbounded by bytes** — the canonical typed values cannot be reconstructed from session replay and may exhaust process or worker memory; only the outer `run_code` output has the worker's configurable hard cap. The rendered `content` of every sub-call IS logged verbatim on `tool/code-dispatch`, uncapped and outside spill policy, so programs that read huge files grow the session log by the same bytes (spill integration for the logged copy is deferred work).
+- **Code Mode intermediate values are execution-local and unbounded by bytes** — the canonical typed values cannot be reconstructed from session replay and may exhaust process or worker memory; only the outer `run_code` output has the worker's configurable hard cap. The durable log copy of each sub-call IS bounded: the `tools/code-dispatch-log` waterfall lets the spill policy replace an oversized `tool/code-dispatch` content with a preview + locator ([rationale](../../../.agents/notes/implemented/feature/2026-07-26-code-dispatch-log-spill.md)).
 - **`run_code` state is fresh per run** — a persistent REPL-style kernel is rejected for the MVP (cross-call state would be invisible to the log); see [the Code Mode Agent Note](../../../.agents/notes/implemented/feature/2026-06-15-code-mode.md).

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

@@ -331,19 +331,29 @@ export function createRunCodeTool(registry: ToolRegistry, requireRuntime: () =>
               for (const context of result.additionalContexts ?? []) {
                 exec.deferContext(context)
               }
-              exec.agent?.session.append('tool/code-dispatch', {
-                parentCallId: exec.callId,
-                subCallId,
-                name,
-                // The SIBLING parse of the dispatched value: byte-identical JSON,
-                // but a separate object — a tool mutating its args cannot desync
-                // this record from what it actually received.
-                arguments: normalized.logged,
-                isError: result.isError,
-                // The registry deep-froze this projection at result finalization;
-                // append snapshots it again, so the log copy stays detached.
-                content: result.content,
-              })
+              if (exec.agent !== undefined) {
+                // The durable copy may be reshaped (e.g. spilled to a preview +
+                // locator) by the log-shaping waterfall; the program's value and
+                // the model contract are untouched.
+                const logged = await registry.shapeDispatchLog({
+                  exec, agent: exec.agent, subCallId, name, isError: result.isError,
+                  // The registry deep-froze this projection at result
+                  // finalization; append snapshots the final copy again, so the
+                  // log stays detached.
+                  content: result.content,
+                })
+                exec.agent.session.append('tool/code-dispatch', {
+                  parentCallId: exec.callId,
+                  subCallId,
+                  name,
+                  // The SIBLING parse of the dispatched value: byte-identical JSON,
+                  // but a separate object — a tool mutating its args cannot desync
+                  // this record from what it actually received.
+                  arguments: normalized.logged,
+                  isError: result.isError,
+                  content: logged,
+                })
+              }
               resolve(result.isError
                 ? { isError: true, message: result.error.message }
                 : { isError: false, value: result.value })

packages/core/tools/src/index.ts

@@ -123,6 +123,19 @@ declare module 'cordis' {
      * @mode waterfall
      */
     'tools/post-execute'(this: Scoped<ToolRegistry>, exec: ToolExecution, result: Readonly<ToolExecutionResult>, next: () => Promise<PostToolDecision>): Promise<PostToolDecision>
+    /**
+     * Shape the DURABLE LOG COPY of one `run_code` sub-dispatch outcome before
+     * the bridge appends its `tool/code-dispatch` event. `next()` keeps the
+     * content unchanged; a listener may return replacement blocks (e.g. the
+     * spill policy's preview + locator for an oversized text result). Only the
+     * logged copy is affected — the program already received the complete
+     * value, and the model sees neither. A throwing listener is contained:
+     * the bridge falls back to logging the unshaped content.
+     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's dispatches.
+     * @param dispatch - the parent execution, sub-call identity, and the settled content to log.
+     * @mode waterfall
+     */
+    'tools/code-dispatch-log'(this: Scoped<ToolRegistry>, dispatch: CodeDispatchLog, next: () => Promise<ContentBlock[]>): Promise<ContentBlock[]>
     /**
      * Observe the frozen, lossless-JSON final outcome. Listener failures are contained.
      * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): keyed by `exec.agent`.
@@ -272,6 +285,28 @@ export type ToolExecutionMode =
   | { kind: 'parallel' }
   | { kind: 'exclusive' }
 
+/**
+ * One settled `run_code` sub-dispatch about to be logged, as seen by the
+ * `tools/code-dispatch-log` waterfall: the parent execution (session owner,
+ * outer call identity), the sub-call identity, and the outcome whose durable
+ * copy a listener may reshape. The complete `content` is what the program
+ * already received; only the `tool/code-dispatch` event's copy changes.
+ */
+export interface CodeDispatchLog {
+  /** The outer `run_code` execution. */
+  readonly exec: ToolExecution
+  /** The calling agent (the scope routing key and the spill owner), when the outer call has one. */
+  readonly agent?: Agent
+  /** Deterministic sub-call id (`<parent>:code:<n>`). */
+  readonly subCallId: CallId
+  /** The dispatched sub-tool name. */
+  readonly name: string
+  /** Whether the sub-call settled as an error. */
+  readonly isError: boolean
+  /** The sub-call's complete model-facing content (the settle event's default payload). */
+  readonly content: ContentBlock[]
+}
+
 /**
  * One pending tool call inside the registry pipeline. Parsed arguments cross
  * one lossless-JSON materialization boundary before policy and are deep-frozen;
@@ -932,6 +967,26 @@ export class ToolRegistry extends Service {
     }
   }
 
+  /**
+   * Run the `tools/code-dispatch-log` waterfall over one settled sub-dispatch
+   * and return the content the bridge should log on `tool/code-dispatch`.
+   * Contained: a throwing listener falls back to the unshaped content — log
+   * shaping must never fail the dispatch or lose the settle event.
+   * @param dispatch - the sub-dispatch identity and its default logged content.
+   * @returns the (possibly reshaped) content for the durable event.
+   */
+  async shapeDispatchLog(dispatch: CodeDispatchLog): Promise<ContentBlock[]> {
+    try {
+      return await this.ctx.waterfall(
+        scopeTarget(this, dispatch.agent), 'tools/code-dispatch-log', dispatch,
+        () => Promise.resolve(dispatch.content),
+      )
+    } catch (error: unknown) {
+      this.ctx.logger.warn(`tools: code-dispatch-log listener failed for ${dispatch.name}: ${String(error)}; logging the unshaped content`)
+      return dispatch.content
+    }
+  }
+
   /**
    * Execute through pre-policy, guards, around-dispatch, post-policy,
    * definition-owned content finalization, and final notification. Tool and