Greptile Summary

This PR adds three sequential/modifying plugin hooks — before_llm_call, after_llm_call, and before_response_emit — that allow policy plugins to intercept and gate LLM inputs, tool execution, and assistant responses before delivery. After several rounds of review iteration, the implementation is in good shape.

What changed and why it fits:

• The hooks follow the same sequential FIFO merge pattern as before_tool_call and message_sending, keeping the system consistent
• A per-session gate bridge (after-llm-call-gate.ts) decouples the subscription-based after_llm_call event from the synchronous before_tool_call enforcement point, avoiding invasive agent loop restructuring
• Merge semantics are security-first: intersection latch for tools/toolCalls, one-way latch for block, and first-writer-wins for all content fields

Previously raised issues that have been addressed:

• hookCtx and hookIterationRefEarly TDZ issues resolved by early declaration
• block: true in before_response_emit now returns a tagged { blocked: boolean } result (not "" sentinel)
• clearAllAssistantContent now clears entire content arrays to [], removing tool_use blocks that could carry sensitive input data
• allContent splice is bounded to original assistantTexts.length to prevent plugin content injection
• rewriteAllAssistantContent now filters to text-bearing messages only, matching getRunScopedMessages counting
• tools-without-toolCallId allowlist bypass in the gate fixed
• messages/systemPrompt merge uses first-writer-wins semantics
• content/allContent merge uses first-writer-wins with a cross-lock
• PluginHookAfterLlmCallResult is exported from hooks.ts
• allContent field added to PluginHookBeforeResponseEmitEvent type
• latencyMs/tokenUsage JSDoc updated to mark them as reserved/unpopulated
• Duplicate/stale test comment in hooks.extended.test.ts corrected

Remaining concerns:

• rewriteLastAssistantContent uses "content" in m as its filter, while getRunScopedMessages uses a stricter text-bearing (extractAssistantText().length > 0) filter. In edge cases where runMessages ends with a tool-call-only assistant message, the rewrite would silently land on the wrong message and be a no-op, leaving session history out of sync with what was delivered
• The mock in hook-response-emit.test.ts includes stubs for runContextAssembled, runLoopIterationStart, and runLoopIterationEnd which don't exist in the current HookRunner type — these appear to be pre-emptive stubs for hooks from a separate in-progress branch
• Plugin authors returning { messages: [] } from before_llm_call will silently wipe all conversation history for that LLM call; a warn-level log when an explicitly-empty array is passed would reduce this footgun's blast radius

Confidence Score: 4/5

• PR is safe to merge — all critical blocking/filtering and session-history-corruption issues from prior review rounds have been resolved; remaining items are edge cases and style improvements.
• The implementation is architecturally sound and the security-critical paths (block propagation, history clearing on block, merge semantics preventing allowlist widening) have been carefully addressed across multiple review iterations. The remaining issues are minor: a filter inconsistency in rewriteLastAssistantContent that affects only edge-case tool-call-only message sequences, test stubs coupling to unreleased work, and a footgun for plugin authors who pass messages: []. No regressions to existing hooks are introduced since the new code paths are gated behind hasHooks() checks.
• Pay close attention to src/agents/pi-embedded-runner/run/hook-response-emit.ts (filter consistency in rewriteLastAssistantContent) and src/agents/pi-embedded-runner/run/hook-response-emit.test.ts (stubs for unreleased hook methods).

_{Last reviewed commit: a94eed9}

To use Codex here, create an environment for this repo.

You're correct on points 1-3. I was wrong about tools: [] — empty arrays are truthy in JavaScript, so the code correctly filters to an empty tool set. The systemPrompt and content checks also correctly use !== undefined and strict equality respectively.

However, the after_llm_call contradiction remains valid. You say it's "intentional design" to be void/observational, but your PR description explicitly claims the opposite:

• Title: "modifying hooks"
• Table: after_llm_call marked "Modifiable"
• Result payload: { toolCalls?, block?, blockReason? }
• Comparison: "llm_output is void/observation; after_llm_call can filter tool calls"
• Motivation: "requires: Blocking tool calls when context is tainted"

The code comment says interception "doesn't exist yet" — that's acknowledging a limitation, not describing intentional design. If after_llm_call is void like llm_output, then this PR doesn't deliver the security capabilities you described.

Good catch on the history clearing — I see you added clearAssistantContent() in before_response_emit block handling. That fixes the PII leakage concern.

Action items:

1. Update PR description to accurately reflect that after_llm_call is void/observational (remove claims about blocking/filtering)
2. Or implement the blocking/filtering capability the description promises

The mismatch between documentation and implementation will confuse plugin authors who need the blocking capability you described.

Very interested in this! We run a multi-agent setup with 24 specialized agents and have been building our own content sanitization pipeline to scan all external data before it reaches any LLM. These hooks would let us enforce that at the gateway level instead of retrofitting every individual tool — exactly the right abstraction layer for security policy enforcement. The before_llm_call hook is especially compelling for input sanitization, and after_llm_call for tool-call gating based on trust/provenance. Looking forward to seeing this land. 🦞

Split into 3 focused PRs

This PR has been superseded by 3 smaller, stacked PRs:

PR 1: before_llm_call — input interception

#39195 • feat/hook-before-llm-call

Adds the before_llm_call hook. Plugins can inspect/modify messages, system prompt, filter tools, or block the call. Uses streamFn wrapper pattern.

PR 2: after_llm_call — deterministic tool-call gating

#39200 • feat/hook-after-llm-call

Adds the after_llm_call hook with a completely redesigned enforcement mechanism. The original design in this PR used a synchronous mutable ref with monotonic sequence counters ("best-effort"). The new design uses a Promise-based gate that's deterministic — first tool call blocks until the hook resolves.

Key deletions:

• All subscription-based handling from attempt.ts
• Monotonic sequence counters
• Staleness detection logic
• The "best-effort" caveat

PR 3: before_response_emit — output policies

#39203 • feat/hook-before-response-emit

Adds the before_response_emit hook. Plugins can modify, redact (single-message or multi-turn), or block the response.

Merge order: #39195 → #39200 → #39203

Closing this PR in favor of the split PRs.

Updated split: 2 PRs

Superseded by:

1. feat(hooks): add before_llm_call + after_llm_call plugin hooks [claude, human developer oversight] #39206 — before_llm_call + after_llm_call (input interception + deterministic tool-call gating)
2. feat(hooks): add before_response_emit hook for output policies [claude, human developer oversight] #39207 — before_response_emit (output policies)

Merge order: #39206 → #39207

@bmendonca3: NB, the split has taken place; more notes now in #36671