[FEATURE] PostToolUse hook for agent-based large output summarization

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

Every tool invocation in Claude Code appends its full output to the conversation context. As the session progresses, the context window fills up with stale tool outputs — test results, build logs, file listings, diffs, grep outputs. This is the single biggest practical issue with long Claude Code sessions.

The community plugin context-mode tries to solve this by intercepting tool calls before execution via PreToolUse hooks and redirecting them to a sandbox where output is indexed for BM25 keyword search. This works in isolation but has significant limitations:

1. BM25 search is keyword-based and dumb — it can't reason about what's relevant to the current task. If you run pytest and 2 of 1400 tests fail, BM25 can't extract just the failures unless you know the exact keywords to search for.

1. PreToolUse interception breaks subagents — the hook redirects Read → ctx_execute_file, but background subagents can't prompt for interactive permission approval on the redirected tool. Every denial message points to another tool that's also denied, creating a circular permission block:

• Hook says "don't use Read, use ctx_execute_file" → subagent tries ctx_execute_file → denied
• Hook says "don't use Bash, use ctx_execute" → subagent tries ctx_execute → denied
• Every tool redirects to another denied tool → subagent gives up

1. It's solving the wrong problem — the issue isn't the tool call itself, it's the output size. We don't want to prevent the call, we want to handle the result intelligently.

Proposed Solution

Add a PostToolUse hook that can intercept large tool output and auto-delegate summarization to a lightweight agent before the output enters the main context.

Flow:

1. Tool runs normally, produces output
2. PostToolUse hook fires, checks output size against a configurable threshold
3. If over threshold → automatically spawn a lightweight agent with the full output + current task context
4. Agent returns a focused summary of only what's relevant
5. Summary replaces the raw output in the main context window — the raw output never touches the conversation

This could be exposed as:

• A setting like autoSummarizeLargeOutput: true with a configurable line/token threshold
• A new hook type (PostToolUse) that plugins can implement
• Both — a built-in handler plus the hook type for custom implementations

What the hook needs:

• Access to the full tool output (to check size and pass to an agent)
• Ability to replace/transform the output before it enters the conversation
• Ability to spawn an agent for summarization
• This would also enable other useful PostToolUse plugins beyond just output summarization

Alternative Solutions

| Approach | How it works | Limitation |
|----------|-------------|-----------|
| context-mode plugin (PreToolUse + BM25) | Intercepts before execution, indexes output for keyword search | Breaks subagent permissions (circular tool redirects); keyword search can't reason about relevance |
| Dedicated wrapper agents (e.g., test-runner) | Custom agent per use case that runs command and returns summary | Must manually create one per scenario; pattern is always the same — should be built in |
| Retroactive compression (#25967) | Model summarizes tool output after consuming it, replaces in history | Output already entered context and was processed; prevention is cheaper than cleanup |
| Tiered context compression (#26539) | Smarter compression with priority tiers when hitting context limit | Different problem — that's conversation history management, not point-of-output interception |
| Just truncating output | Cut off after N lines | Loses potentially important information buried later in output |
| Reading files in chunks | Manual pagination with offset/limit | Tedious, slow, requires multiple round trips |

Why agent-based PostToolUse is better than all of these:

• Prevention > cleanup — it's cheaper and simpler to never add the bloat than to compress it later
• Agent summarization is task-aware — unlike BM25 or generic compression, the agent knows what the current task needs and extracts only that
• No risk of losing important info during compaction — the agent summarizes with full task context at the moment of output, not later when conversation state has moved on
• No circular permission issues — the tool runs normally, the hook processes the output, no tool redirection needed

Priority

High - Significant impact on productivity

Feature Category

Performance and speed

Use Case Example

Scenario 1: Parallel PR review

1. Running a PR review with 4 parallel subagents (code reviewer, test analyzer, error handling auditor, simplification reviewer)
2. Each agent needs to read a 1000-line diff + several source files
3. When agents return results, each result can be 200-500 lines of structured findings
4. After 2-3 PR reviews in one session, the context is bloated with old tool outputs from earlier reviews
5. With PostToolUse agent delegation: each large output gets auto-summarized to ~50 lines of relevant findings before entering context. Session stays fast through multiple reviews.

Scenario 2: Test output
Running pytest with 1400 tests passing and 2 failing. Today the full output (hundreds of lines of dots, warnings, and collection info) enters context. With this feature, an agent extracts just the 2 failures and relevant tracebacks — maybe 20 lines instead of 500.

Scenario 3: Build logs
Running a build command that produces 300 lines of output. Only the errors matter. Agent returns "Build failed: 2 errors in src/auth.py (line 45: missing import, line 89: type mismatch)" instead of the full log.

Additional Context

Environment: We use Claude Code CLI extensively with subagents for parallel code review, test execution, and codebase exploration. The subagent pattern (spawn agent → agent does work → returns summary) is already the best workaround for context management, but it requires manually creating a specialized agent for every possible large-output scenario. The proposed PostToolUse hook would generalize this pattern into the platform.

Note on #25967 and #26539: This is not a duplicate of either. Those issues address conversation history compression — what happens to context after it's been consumed (#25967) or when approaching the context limit (#26539). This issue is about intercepting output at the point of generation, before it ever enters the conversation. Different problem, different solution, complementary goals.