Feature Proposal: transform_tool_result plugin hook

Summary

Add a new plugin hook that fires after a tool executes but before the result enters the model's context, allowing plugins to modify what the model sees.

Current state

The plugin hook lifecycle around tool calls:

before_tool_call  →  tool execution  →  result sent to model  →  after_tool_call (observe)
                                                                        ↓
                                                          tool_result_persist (transcript)

• before_tool_call: intercepts before execution. Can modify params, block, require approval. Returns a value.
• after_tool_call: fires after the result has already been sent to the model. Fire-and-forget, runs in parallel, intentionally late. Designed for side effects — telemetry, logging, audit. Returns void.
• tool_result_persist: transforms the result before writing to the session transcript on disk. Synchronous. Returns a value, but only affects persistence — not what the model sees on the current turn.

There's a gap: nothing sits between tool execution and the model receiving the result. Plugins can control what goes into a tool and what gets persisted, but not what the model actually sees.

Proposal

Add transform_tool_result as a new plugin hook:

// Follows the existing plugin hook pattern
transform_tool_result: (
  event: PluginHookTransformToolResultEvent,
  ctx: PluginHookToolContext
) => Promise<PluginHookTransformToolResultResult | void> | PluginHookTransformToolResultResult | void;

type PluginHookTransformToolResultEvent = {
  toolName: string;
  toolCallId?: string;
  result: unknown;
  runId?: string;
};

type PluginHookTransformToolResultResult = {
  result?: unknown;  // modified result to send to model; undefined = pass through
};

Updated lifecycle:

before_tool_call  →  tool execution  →  transform_tool_result (NEW)  →  result sent to model  →  after_tool_call (observe)
                                                                                                        ↓
                                                                                          tool_result_persist (transcript)

If the handler returns void or undefined, the original result passes through unchanged. Fully backwards-compatible with all existing hooks — after_tool_call and tool_result_persist continue to work exactly as they do today.

Why not extend after_tool_call?

after_tool_call is explicitly designed as a fire-and-forget observation hook. It runs in parallel, fires after the result is already sent to the model, and returns void by design. Changing its semantics would alter the contract for existing plugins. A separate hook at a different point in the pipeline is cleaner.

Use cases

• Context dedup: A plugin tracks content the model has already seen and strips duplicate chunks from tool results (e.g., memory search returning the same chunks across multiple calls in a session)
• Result summarization: Compress verbose outputs (long file reads, web page fetches) to save context window budget
• Redaction: Strip sensitive data from the model's view while keeping the full result in the persisted transcript via tool_result_persist
• Annotation: Enrich results with metadata before the model processes them

Scope

• One new hook name added to PLUGIN_HOOK_NAMES
• One new type (PluginHookTransformToolResultEvent + result type), following established patterns
• One new call site in the agent loop, between tool execution and result emission
• No changes to existing hooks — before_tool_call, after_tool_call, and tool_result_persist are untouched
• Backwards-compatible — plugins that don't register for this hook see zero behavior change

Open questions

• Should multiple plugins chain transforms (each seeing the prior plugin's output), or first-write-wins? Chaining (like tool_result_persist) seems more composable.
• Any tool names that should be exempt from transformation for safety reasons?

Happy to submit a PR for this.