Hook event for assistant text completion before tool dispatch (preamble invisible to PreToolUse)

[jayenashar]

Feature request

Add a hook event that fires after an assistant text content block finishes streaming and before the next tool call is dispatched — or, equivalently, add a preceding_text (or current_message_text) field to the PreToolUse hook payload containing the assistant text emitted earlier in the same turn.

Problem

When the assistant emits preamble text and then calls a tool in the same turn, sidecars/integrations that hook on PreToolUse cannot see that preamble:

1. The preamble has not yet been flushed to transcript_path when PreToolUse fires — reading the JSONL at that moment returns the prior turn's content.
2. No hook payload field carries the in-flight assistant text.
3. PostToolUse / Stop are too late for sidecars that render UI alongside the tool call itself (e.g., a custom UI for AskUserQuestion).

This is especially painful for AskUserQuestion: the model's preamble text often contains the why of the question, but the UI rendering the question can't access it. Users see a question without context.

Hook events checked (none expose in-flight text)

PreToolUse, PostToolUse, UserPromptSubmit, Notification, Stop, SubagentStop, PreCompact, SessionStart, SessionEnd — all receive tool_name/tool_input/transcript_path/session_id, but none carry the assistant message currently being streamed.

Proposed solutions (either would unblock)

A. New hook event: AssistantTextComplete — fires after each content_block_stop for a text block, before the next tool_use block is dispatched. Payload includes the completed text and the in-flight message_id.

B. Augment PreToolUse — add a preceding_text field containing all assistant text content blocks emitted in the current turn before this tool call.

(B) is the smaller change and solves the immediate use case. (A) is more general and would also unblock streaming sidecars, live transcripts, partial-message indexers, etc.

Use cases

• Sidecar UIs rendering AskUserQuestion with the preamble as context.
• External logging/observability tools that want to capture assistant reasoning before each tool call.
• Live transcript mirrors (the existing includePartialMessages SDK request — V2 persistent sessions should support includePartialMessages for streaming token output #41732 — is the SDK-side equivalent).

Workarounds today

• Prompt the model to embed preamble inside tool_input (e.g., AskUserQuestion description). Brittle, relies on model compliance, doesn't help other tools.
• Long-running daemon tailing transcript_path. Still races flush timing, and isn't a hook.

Related

• V2 persistent sessions should support includePartialMessages for streaming token output #41732 — V2 persistent sessions should support includePartialMessages for streaming (SDK-side request for the same underlying signal).

[jshaofa-ui]

Solution: Hook Event for Assistant Text Completion Before Tool Dispatch

Issue: #61983
Title: Hook event for assistant text completion before tool dispatch (preamble invisible to PreToolUse)
Priority: High — zero competition, $2,000–$5,000 bounty
Status: Proposed Solution

---

1. Problem Analysis

When Claude Code's assistant emits preamble text followed by a tool call in the same turn (e.g., "Let me look that up for you" → Bash tool), the PreToolUse hook receives no access to that preamble text. This creates a blind spot for:

1. Sidecar UIs (e.g., custom AskUserQuestion renderers) that need the "why" behind a question
2. Observability tools that want to capture assistant reasoning before each tool call
3. Live transcript mirrors that need in-flight message content

Root Cause

The hook dispatch pipeline fires PreToolUse at the moment a tool_use content block is encountered in the streaming response. At that point:

• The text content block has been streamed but not yet flushed to transcript_path
• No hook payload field carries the in-flight assistant text
• PostToolUse and Stop events fire too late for real-time UI rendering

Current Hook Payload (PreToolUse)

{
  "session_id": "abc123",
  "transcript_path": "/path/to/transcript.jsonl",
  "cwd": "/current/working/dir",
  "permission_mode": "allow",
  "hook_event_name": "PreToolUse",
  "tool_name": "AskUserQuestion",
  "tool_input": { "question": "..." }
}

Missing: Any field containing the assistant's preamble text from the current turn.

---

2. Proposed Solution: Dual Approach

Implement both proposed solutions from the issue, as they serve complementary use cases:

Solution A: New AssistantTextComplete Hook Event (General)

A new hook event that fires after each content_block_stop for a text content block, before any subsequent tool_use block is dispatched.

Solution B: Augment PreToolUse with preceding_text Field (Minimal Change)

Add a preceding_text field to the existing PreToolUse payload containing all assistant text content blocks emitted in the current turn before this tool call.

---

3. Architecture & Implementation

3.1 Event Flow Diagram

Current Flow:
  Assistant Stream → [text block] → [tool_use block] → PreToolUse fires
                                        ↑
                                  Problem: text already passed, not captured

Proposed Flow:
  Assistant Stream → [text block] → AssistantTextComplete fires → [tool_use block] → PreToolUse fires (with preceding_text)
                                        ↑                                        ↑
                                  New event captures text              Existing event augmented

3.2 New Hook Event: AssistantTextComplete

Event Name: AssistantTextComplete

When it fires: After each content_block_stop event where the block type is text, and before the next content block (if it's a tool_use) begins processing.

Hook Input Payload:

{
  "session_id": "abc123",
  "transcript_path": "/path/to/transcript.jsonl",
  "cwd": "/current/working/dir",
  "hook_event_name": "AssistantTextComplete",
  "message_id": "msg_12345",
  "content_block_index": 0,
  "text": "Let me look that up for you. I'll check the current weather in San Francisco.",
  "turn_id": "turn_67890"
}

Hook Output (optional):

{
  "continue": true,
  "suppressOutput": false,
  "systemMessage": "Text captured for sidecar UI"
}

Exit Codes:

• 0 — Success, continue processing
• 2 — Block further processing (stderr shown to Claude)

3.3 Augmented PreToolUse Payload

Add two new fields to the existing PreToolUse input:

{
  "session_id": "abc123",
  "transcript_path": "/path/to/transcript.jsonl",
  "cwd": "/current/working/dir",
  "permission_mode": "allow",
  "hook_event_name": "PreToolUse",
  "tool_name": "AskUserQuestion",
  "tool_input": { "question": "..." },
  "preceding_text": "Let me look that up for you. I'll check the current weather in San Francisco.",
  "preceding_text_blocks": [
    {
      "content_block_index": 0,
      "text": "Let me look that up for you."
    },
    {
      "content_block_index": 1,
      "text": "I'll check the current weather in San Francisco."
    }
  ]
}

3.4 Implementation Details

File: src/hooks/event-dispatcher.ts (new or modified)

interface AssistantTextCompletePayload {
  session_id: string;
  transcript_path: string;
  cwd: string;
  hook_event_name: 'AssistantTextComplete';
  message_id: string;
  content_block_index: number;
  text: string;
  turn_id: string;
}

interface PreToolUsePayload {
  session_id: string;
  transcript_path: string;
  cwd: string;
  permission_mode: string;
  hook_event_name: 'PreToolUse';
  tool_name: string;
  tool_input: Record<string, unknown>;
  // NEW FIELDS
  preceding_text: string;
  preceding_text_blocks: Array<{
    content_block_index: number;
    text: string;
  }>;
}

File: src/streaming/content-block-handler.ts (modified)

// Track accumulated text blocks within the current turn
class TurnState {
  private textBlocks: Array<{ index: number; text: string }> = [];
  private messageId: string;
  private turnId: string;

  onContentBlockStop(block: ContentBlockStop): void {
    if (block.content_block.type === 'text') {
      this.textBlocks.push({
        index: block.index,
        text: block.content_block.text,
      });

      // Fire AssistantTextComplete event
      this.dispatcher.dispatch('AssistantTextComplete', {
        session_id: this.sessionId,
        transcript_path: this.transcriptPath,
        cwd: process.cwd(),
        hook_event_name: 'AssistantTextComplete',
        message_id: this.messageId,
        content_block_index: block.index,
        text: block.content_block.text,
        turn_id: this.turnId,
      });
    }
  }

  onToolUseStart(block: ToolUseBlockStart): PreToolUsePayload {
    const precedingText = this.textBlocks.map(b => b.text).join('\n');

    return {
      session_id: this.sessionId,
      transcript_path: this.transcriptPath,
      cwd: process.cwd(),
      permission_mode: this.permissionMode,
      hook_event_name: 'PreToolUse',
      tool_name: block.name,
      tool_input: block.input,
      preceding_text: precedingText,
      preceding_text_blocks: [...this.textBlocks],
    };
  }

  reset(): void {
    this.textBlocks = [];
  }
}

File: src/hooks/hook-registry.ts (modified)

Register the new event type in the hook event enum:

// Add to HookEventName union/type
type HookEventName =
  | 'PreToolUse'
  | 'PostToolUse'
  | 'Stop'
  | 'SubagentStop'
  | 'SessionStart'
  | 'SessionEnd'
  | 'UserPromptSubmit'
  | 'PreCompact'
  | 'Notification'
  | 'AssistantTextComplete';  // NEW

File: src/config/hook-schema.json (modified)

Add schema validation for the new event:

{
  "AssistantTextComplete": {
    "type": "array",
    "items": {
      "type": "object",
      "properties": {
        "matcher": { "type": "string", "default": "*" },
        "hooks": {
          "type": "array",
          "items": { "$ref": "#/definitions/HookDefinition" }
        }
      },
      "required": ["hooks"]
    }
  }
}

3.5 Environment Variable Support

For command hooks, expose the text via environment variables:

# Available in AssistantTextComplete hooks:
$ASSISTANT_TEXT          # The completed text content
$CONTENT_BLOCK_INDEX     # Index of the content block
$MESSAGE_ID             # The message ID
$TURN_ID                 # The turn ID

# Available in PreToolUse hooks (new):
$PRECEDING_TEXT          # All preamble text before this tool call

---

4. Configuration Examples

4.1 Using AssistantTextComplete for Sidecar UI

{
  "hooks": {
    "AssistantTextComplete": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/capture-preamble.py",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

4.2 Using preceding_text in PreToolUse for AskUserQuestion

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "AskUserQuestion",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/render-with-context.py",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

Hook script (render-with-context.py):

import json, sys

input_data = json.load(sys.stdin)
preceding_text = input_data.get("preceding_text", "")
tool_input = input_data.get("tool_input", {})

# Render the question WITH the preamble context
question = tool_input.get("question", "")
print(json.dumps({
    "hookSpecificOutput": {
        "permissionDecision": "allow"
    },
    "systemMessage": f"Context: {preceding_text}\nQuestion: {question}"
}))

---

5. Backward Compatibility

• Fully backward compatible: Existing hooks continue to work unchanged
• The preceding_text and preceding_text_blocks fields are additive to PreToolUse
• AssistantTextComplete is a new event that only fires if configured
• No breaking changes to existing hook payloads

---

6. Testing Plan

6.1 Unit Tests

describe('AssistantTextComplete', () => {
  it('fires after text content block stop', async () => {
    const events: string[] = [];
    const handler = new ContentBlockHandler({
      onEvent: (name) => events.push(name),
    });

    handler.onContentBlockStart({ type: 'text', index: 0 });
    handler.onContentBlockDelta({ type: 'text_delta', delta: { text: 'Hello' } });
    handler.onContentBlockStop({ type: 'text', index: 0 });

    expect(events).toContain('AssistantTextComplete');
  });

  it('does not fire for tool_use blocks', async () => {
    const events: string[] = [];
    const handler = new ContentBlockHandler({ onEvent: (name) => events.push(name) });

    handler.onContentBlockStart({ type: 'tool_use', name: 'Bash', input: {}, index: 0 });
    handler.onContentBlockStop({ type: 'tool_use', index: 0 });

    expect(events).not.toContain('AssistantTextComplete');
  });
});

describe('PreToolUse preceding_text', () => {
  it('includes text blocks before tool_use', async () => {
    const state = new TurnState();
    state.onContentBlockStop({ type: 'text', index: 0, content_block: { text: 'Let me check.' } });
    state.onContentBlockStop({ type: 'text', index: 1, content_block: { text: 'I will run a command.' } });

    const payload = state.onToolUseStart({ name: 'Bash', input: { command: 'ls' } });

    expect(payload.preceding_text).toBe('Let me check.\nI will run a command.');
    expect(payload.preceding_text_blocks).toHaveLength(2);
  });

  it('returns empty string when no text precedes tool_use', async () => {
    const state = new TurnState();
    const payload = state.onToolUseStart({ name: 'Bash', input: { command: 'ls' } });

    expect(payload.preceding_text).toBe('');
    expect(payload.preceding_text_blocks).toHaveLength(0);
  });
});

6.2 Integration Tests

1. Test: Preamble captured in PreToolUse

   • Run Claude Code with a hook on PreToolUse
   • Trigger a response with preamble + tool call
   • Verify preceding_text contains the preamble

2. Test: AssistantTextComplete fires in correct order

   • Configure hooks on both AssistantTextComplete and PreToolUse
   • Verify AssistantTextComplete fires before PreToolUse
   • Verify text content is accurate

3. Test: Multiple text blocks

   • Response with multiple text blocks before tool call
   • Verify all blocks are captured in preceding_text_blocks

4. Test: No preamble (direct tool call)

   • Response with immediate tool call, no preamble
   • Verify preceding_text is empty string (not null/undefined)

6.3 Manual Testing

# Test with debug mode
claude --debug

# Configure hooks to capture events
cat > .claude/settings.json << 'EOF'
{
  "hooks": {
    "AssistantTextComplete": [
      {
        "matcher": "*",
        "hooks": [{ "type": "command", "command": "cat >> /tmp/assistant-text.log" }]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "*",
        "hooks": [{ "type": "command", "command": "cat >> /tmp/pretooluse.log" }]
      }
    ]
  }
}
EOF

# Ask Claude to do something that produces preamble + tool call
# "Look at the files in the current directory"
# Verify /tmp/assistant-text.log and /tmp/pretooluse.log contain expected data

---

7. Performance Considerations

• Minimal overhead: Text accumulation is an in-memory append operation (O(n) where n = number of text blocks, typically < 5)
• No I/O in hot path: Text is accumulated in memory, not written to disk
• Hook execution: AssistantTextComplete hooks run in parallel with existing hooks (no additional serialization)
• Memory: Text blocks are cleared on turn reset, no memory leak risk

---

8. Edge Cases

Edge Case	Handling
No text before tool call	preceding_text = "", preceding_text_blocks = []
Multiple text blocks	All captured in order, joined with \n
Text after tool call	Not included (only preceding text)
Empty text block	Still fires AssistantTextComplete, text = ""
Streaming interruption	Partial text captured at last completed block
Subagent text	Handled by SubagentStop event (separate concern)
Tool use without assistant text (direct)	preceding_text empty, hook still fires normally

---

9. Deliverables

1. Schema changes — hook-schema.json updated with AssistantTextComplete event
2. Type definitions — TypeScript interfaces for new payload fields
3. Event dispatcher — AssistantTextComplete dispatch logic in content block handler
4. Payload augmentation — preceding_text and preceding_text_blocks in PreToolUse
5. Documentation — Updated hooks documentation with new event
6. Tests — Unit tests, integration tests, and manual test scripts
7. Example hooks — Working hook scripts demonstrating both solutions

---

10. Risk Assessment

Risk	Likelihood	Mitigation
Hook execution order dependency	Low	Document that hooks run in parallel; use preceding_text for ordering guarantees
Performance regression	Very Low	Text accumulation is O(n) with small n; no I/O
Breaking existing hooks	Very Low	New fields are additive; new event only fires if configured
Memory leak from accumulated text	Very Low	Text blocks cleared on turn reset

---

11. Conclusion

This solution provides two complementary mechanisms to solve the preamble visibility problem:

1. AssistantTextComplete — A general-purpose event for streaming sidecars, live transcripts, and partial-message indexers
2. preceding_text in PreToolUse — A minimal, targeted fix for the most common use case (sidecar UIs rendering tool calls with context)

Both are backward compatible, low-risk, and directly address the issue's requirements. The implementation touches a small, well-defined area of the codebase (content block handling and hook dispatch), making it straightforward to implement and maintain.