fix(events): address Codex review — protect post-execute result, purge stale tools/execute refs

Codex's PR-C review found two (A) blockers:

- tools/post-execute could corrupt the protected outcome. postExecute passed the
  mutable `result` to listeners and then read result.callId / spread result on the
  return paths, so a listener mutating the reference (flipping isError, rewriting
  callId, injecting an error) escaped the decision channel. Now the authoritative
  callId/isError/error are SNAPSHOT before the waterfall and the return value is
  rebuilt from the snapshot + the typed PostToolDecision — the decision is the only
  sanctioned way to change the outcome, and callId is always exec.callId. Added a
  regression test that mutates the result reference and asserts it has no effect;
  proven to fail red on the unfixed code.

- Public docs/JSDoc still advertised the removed `tools/execute` waterfall after the
  split. Swept every current-state reference to tools/pre-execute + tools/post-execute:
  the ToolRegistry class JSDoc (and the regenerated catalog), loop.ts's ASCII flow
  (also added the prompt-submit/session-start steps it was missing), the package-map
  READMEs (packages, core, agent-core), core-data-structures core.md/tools.md, the
  bash + acp + invariants src/READMEs (the deferred permission gate is the
  tools/pre-execute deny/ask seam now), the cookbook, and the implemented RFCs whose
  factual seam catalog drifted. codec.ts's totality prose now lists `rejected`.
  Proposed-RFC references are left as-is (frozen proposals, validated when built).

packages/core/README.md

@@ -6,7 +6,7 @@ The packages every harness build is assembled from: the session log, the system-
 |---|---|---|
 | `session/` | Event-sourced session log + in-memory store | `ctx.sessions` |
 | `system-prompt/` | Prompt-section + tool-schema assembly registry | `ctx.systemPrompt` |
-| `tools/` | Tool registry + `tools/execute` waterfall | `ctx.tools` |
+| `tools/` | Tool registry + `tools/pre-execute`/`tools/post-execute` pipeline | `ctx.tools` |
 | `agent/` | Agent interface, registry, `agent/*` event vocabulary | `ctx.agents` |
 | `agent-loop/` | The concrete loop plugin: `ReactLoopAgent` + the loop driver | `ctx.agentLoop` |
 | `agent-core/` | Bundle plugin: the providerless/executor-less/UI-less spine as code | (loads the spine) |

packages/core/agent-core/README.md

@@ -13,7 +13,7 @@ This is the package to read to see **the whole plugin tree at once** — the tea
 @deepseek-ai/dsh-llm              abstract LLM service + content-block vocabulary
 @deepseek-ai/dsh-session          event-sourced session log + store
 @deepseek-ai/dsh-system-prompt    prompt-section + tool-schema assembly
-@deepseek-ai/dsh-tools            tool registry + tools/execute waterfall
+@deepseek-ai/dsh-tools            tool registry + tools/pre-execute/post-execute
 @deepseek-ai/dsh-agent            agent registry + agent/* event vocabulary
 @deepseek-ai/dsh-invariants       dev-mode event-contract assertions
 @deepseek-ai/dsh-tool-bash        the model-facing bash/bash_output/bash_kill schemas

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

@@ -142,10 +142,13 @@ export interface LoopHandle {
  * The agent loop. One invocation drives one agent for its whole lifetime:
  *
  * ```
+ * create agent → emit agent/session-start(source)    ⟵ once, before turn 1
  * forever:
  *   wait for queued messages (idle)
  *   TURN (error-contained — a throwing plugin ends the turn, never the loop):
- *     drain queued → 'turn/start' → session('user/message'…) → emit agent/turn-start
+ *     'turn/start'; each queued msg: waterfall agent/prompt-submit
+ *       allow → session('user/message'…) (+ inject additionalContext) | block → drop
+ *     every prompt blocked → 'turn/end'(rejected), 0 steps; emit agent/turn-start
  *     STEP loop:
  *       drain steering → session('steering/message')  ⟵ catches late steering
  *       session('step/start')                         ⟵ durable step boundary (no agent/* mirror)
@@ -157,13 +160,17 @@ export interface LoopHandle {
  *       msg = waterfall agent/step-result             ⟵ BEFORE the log append, so the
  *       session('assistant/message' {content, usage?})   session records what actually ran
  *       each tool-call in msg (sequential, abort-checked):
- *         session('tool/call'); ctx.tools.execute()   ⟵ waterfall tools/execute
+ *         session('tool/call'); ctx.tools.execute()   ⟵ tools/pre-execute (allow/deny/ask)
+ *                                                        → dispatch → tools/post-execute
  *         session('tool/result')
+ *       append buffered post-execute additionalContext → session('context/message')(s)
  *       drain steering → session('steering/message'); emit agent/steering
  *       session('step/end')                           ⟵ durable step boundary (no agent/* mirror)
- *       cont = waterfall agent/turn-continuation(default = hadToolCalls || steered)
- *       if !cont && steering arrived from step/end session-event/continuation listeners: cont = true
- *       if !cont: break
+ *       cont = waterfall agent/turn-continuation       ⟵ ContinuationDecision; default
+ *         {action: hadToolCalls||steered ? 'continue':'stop'}; a continue.reason is
+ *         recorded as next-step steering
+ *       if action==stop && steering arrived (step/end/continuation listeners): continue anyway
+ *       if action==stop: break
  *     session('turn/end'); emit agent/turn-end
  *     await ctx.parallel('session/flush', session)    ⟵ durability checkpoint
  *     re-enqueue leftover steering as queued          ⟵ steering is never stranded

packages/core/tools/src/index.ts

@@ -335,8 +335,9 @@ function errorInfo(error: unknown): ToolErrorInfo | undefined {
 
 /**
  * Tool registry (`ctx.tools`): tool plugins register definitions; the agent
- * loop executes calls through the `tools/execute` waterfall. The registry
- * contributes its schemas into the system-prompt assembly.
+ * loop executes calls through the `tools/pre-execute` → dispatch →
+ * `tools/post-execute` pipeline. The registry contributes its schemas into the
+ * system-prompt assembly.
  */
 export class ToolRegistry extends Service {
   static inject = ['systemPrompt']
@@ -464,6 +465,19 @@ export class ToolRegistry extends Service {
    * Runs inside `execute`'s outer try/catch (a throwing listener → isError).
    */
   private async postExecute(exec: ToolExecution, result: ToolExecutionResult): Promise<ToolExecutionResult> {
+    // Snapshot the protected outcome BEFORE the waterfall. A listener receives
+    // the same `result` reference, so a post-waterfall read of `result.callId`/
+    // `.isError`/`.error` could carry a listener's mutation — violating the
+    // authoritative-call-id requirement and the "preserve the dispatched
+    // isError/error" contract. The decision is the ONLY sanctioned channel for a
+    // listener to change the outcome (block, or accept-with-replacement); the
+    // call id is always the authoritative `exec.callId`.
+    const dispatched = {
+      callId: exec.callId,
+      content: result.content,
+      isError: result.isError,
+      ...result.error ? { error: result.error } : {},
+    }
     const decision = await this.ctx.waterfall(
       this, 'tools/post-execute', exec, result,
       () => Promise.resolve<PostToolDecision>({ kind: 'accept' }),
@@ -471,7 +485,7 @@ export class ToolRegistry extends Service {
     const additionalContext = decision.additionalContext
     if (decision.kind === 'block') {
       return {
-        callId: result.callId,
+        callId: dispatched.callId,
         content: decision.feedback,
         isError: true,
         ...additionalContext ? { additionalContext } : {},
@@ -479,7 +493,7 @@ export class ToolRegistry extends Service {
     }
     // accept: replace content if supplied, preserve the dispatched isError/error.
     return {
-      ...result,
+      ...dispatched,
       ...decision.content ? { content: decision.content } : {},
       ...additionalContext ? { additionalContext } : {},
     }

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

@@ -201,6 +201,30 @@ describe('ToolRegistry', () => {
     expect(result.additionalContext).toMatchObject({ content: [{ text: 'fyi' }], source: { kind: 'plugin', plugin: 'test' } })
   })
 
+  it('a post-execute listener mutating the result object cannot corrupt callId/isError/error', async () => {
+    // The decision is the ONLY sanctioned channel to change the outcome. A
+    // listener that reaches in and mutates the passed result reference (flipping
+    // isError, rewriting callId, attaching a bogus error) must NOT affect what
+    // execute() returns — the registry snapshots the authoritative fields before
+    // the waterfall and rebuilds from the snapshot + decision.
+    const ctx = await setup()
+    ctx.tools.register(echoTool)
+
+    ctx.on('tools/post-execute', async (_exec, result, next) => {
+      const mutable = result as { callId: string; isError: boolean; error?: unknown }
+      mutable.callId = 'hijacked'
+      mutable.isError = true
+      mutable.error = { name: 'Evil', code: 'EVIL' }
+      return next() // delegate to the default accept — no decision-level override
+    })
+
+    const result = await ctx.tools.execute({ callId: CallId('c1'), name: 'echo', arguments: { text: 'hi' } })
+    expect(result.callId).toBe(CallId('c1'))   // authoritative exec.callId, not 'hijacked'
+    expect(result.isError).toBe(false)          // the real (successful) dispatch outcome
+    expect(result.error).toBeUndefined()        // no listener-injected error
+    expect(result.content[0]).toMatchObject({ text: 'hi' })
+  })
+
   it('composes pre + post waterfalls around dispatch (sandbox-wrap pattern)', async () => {
     const ctx = await setup()
     ctx.tools.register(echoTool)