TL;DR

Adds the before_response_emit sequential / mutating plugin hook — fires before the final assistant response is delivered to the user. Plugins can modify, redact (single-message or multi-turn), or block the response entirely.

Split from #33916. Independent of #39206 — both can merge in any order. Each adds its own hook name to the type union and PLUGIN_HOOK_NAMES array; types.ts merge will be trivial (adjacent lines).

New hook (contract)

Follows the same sequential "merge results across handlers" pattern as before_tool_call / message_sending.

Merge semantics

Capabilities

Single-message modification

return { content: redact(event.content) };

Rewrites only the final assistant message text.

Multi-turn PII redaction (allContent)

return { allContent: event.allContent.map(redact) };

Rewrites all assistant messages from the current run — not just the last one. Enables full multi-turn PII scanning across tool-loop iterations. Bounded to assistantTexts.length from the original snapshot; plugins cannot inject new messages.

Blocking

return { block: true, blockReason: "policy violation" };

Clears all current-run assistant content parts from session history — blocked content does not persist.

Architecture: run-scoped rewrites

The hook only modifies messages from the current run. Prior session history (messages before the user prompt that triggered this run) is untouched.

Session messages:
  [prior history] [user prompt] [assistant msg 1] [tool call] [assistant msg 2]
  ^--- untouched   ^--- run boundary               ^--- allContent[0]            ^--- allContent[1] / content

Compaction safety

preRunMessageCount marks the boundary between prior history and current-run messages. If auto-compaction invalidates this count during the run (messages get compacted mid-turn), the handler falls back to a tail-based scan that finds assistant messages from the end of the snapshot — never corrupting previously-delivered history.

Multi-part assistant messages

When blocking, the handler clears content from all content parts of multi-part assistant messages (not just text parts). Modified content is spliced into the correct content part index, preserving non-text parts.

Review guide (start here)

1. API surface: src/plugins/types.ts — PluginHookBeforeResponseEmitEvent / PluginHookBeforeResponseEmitResult
2. Hook runner semantics: src/plugins/hooks.ts — runBeforeResponseEmit (sequential/FIFO merge, content/allContent mutual exclusion)
3. Implementation: src/agents/pi-embedded-runner/run/hook-response-emit.ts — runResponseEmitHook + getRunScopedMessages helper
4. Integration point: src/agents/pi-embedded-runner/run/attempt.ts — fires after sessionIdUsed assignment, before promptError check

Security / correctness notes

• before_response_emit blocking clears/redacts content from all current-run assistant messages (not just the last) so blocked content does not persist into session history
• Multi-part assistant messages are handled — modified content does not leave stale fragments
• Run-scoped rewrites never corrupt previously-delivered session history, even after compaction
• allContent enables full multi-turn PII redaction across tool-loop iterations
• allContent length is bounded to the original assistantTexts.length — plugins cannot inject messages
• Handler execution order is FIFO (registration order), consistent with registry expectations

Testing

Adds/extends unit & integration tests across:

• Response emit handler: 26 tests (modification, blocking, session-history scrubbing, allContent, run scoping, compaction fallback, multi-part messages)
• getRunScopedMessages: normal path, compaction path, defensive fallback
• Hook runner merge semantics: 4 tests (first-writer-wins, allContent precedence, one-way latch, no-handler paths)

30 total tests, pnpm check clean.

AI-Assisted Development 🤖

This PR was developed with AI assistance (Claude/OpenClaw agent "Tank").

• Degree of testing: Comprehensive — 30 unit tests across 2 test files. pnpm check clean.
• Human oversight: All changes reviewed and directed by Eddie Abrams
• Understanding confirmed: The contributor understands the run-scoped message handling, compaction-safe fallback logic, content-part manipulation, and hook merge semantics