[FEATURE] Add `additionalContext` support to PreToolUse hooks

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

PreToolUse hooks can control permissions and modify tool inputs, but cannot inject context into Claude's conversation. This limits their usefulness for providing contextual guidance at the moment it's needed.

Use case: I have an inject-test-methodology hook that triggers when Claude is about to write test files. I want to inject testing best practices (AAA pattern, naming conventions, edge case requirements) at the exact moment Claude needs them—not loaded globally for every conversation.

Currently, I must choose between:

| Approach | Problem |
|----------|---------|
| Global CLAUDE.md | Always loaded, wastes context on non-test work |
| UserPromptSubmit hook | Fires on every prompt, requires complex filtering |
| PostToolUse hook | Fires AFTER the tool runs, too late to guide behavior |

None of these are ideal. PreToolUse fires at exactly the right moment but can't inject context.

Proposed Solution

Add additionalContext field to PreToolUse's hookSpecificOutput, matching the existing pattern used by:

• UserPromptSubmit
• SessionStart
• PostToolUse

Schema change:

| {
    hookEventName: 'PreToolUse';
    permissionDecision?: 'allow' | 'deny' | 'ask';
    permissionDecisionReason?: string;
    updatedInput?: Record<string, unknown>;
    additionalContext?: string;  // ← NEW FIELD
  }

Behavior: When a PreToolUse hook returns additionalContext, include it in Claude's context for the current tool call decision and subsequent processing.

Alternative Solutions

| Approach | Why Not Ideal |
|----------|---------------|
| Global CLAUDE.md | Loads methodology for every project, even non-test work |
| UserPromptSubmit | Fires on every prompt; complex filtering needed |
| PostToolUse | Too late—tool already executed |
| Project CLAUDE.md | Per-project maintenance burden |

Priority

Critical - Blocking my work

Feature Category

CLI commands and flags

Use Case Example

Scenario: Developer asks Claude to write tests for a new feature.

Current flow:

1. Claude decides to use Write tool for test_feature.py
2. PreToolUse hook fires, detects test file pattern
3. Hook can only: allow/deny/modify inputs
4. Hook CANNOT tell Claude "follow AAA pattern, use descriptive names, test edge cases"
5. Claude writes tests without methodology guidance (unless globally loaded)

Desired flow:

1. Claude decides to use Write tool for test_feature.py
2. PreToolUse hook fires, detects test file pattern
3. Hook returns additionalContext with testing methodology
4. Claude receives methodology at exactly the moment it's needed
5. Claude writes high-quality tests following the injected guidance

Additional Context

Current TypeScript Schema (from official docs)

The limitation is visible in the type definitions but not explicitly documented:

hookSpecificOutput?:
  | {
      hookEventName: 'PreToolUse';
      permissionDecision?: 'allow' | 'deny' | 'ask';
      permissionDecisionReason?: string;
      updatedInput?: Record<string, unknown>;
      // NO additionalContext - this is the gap
    }
  | {
      hookEventName: 'UserPromptSubmit';
      additionalContext?: string;  // HAS IT
    }
  | {
      hookEventName: 'SessionStart';
      additionalContext?: string;  // HAS IT
    }
  | {
      hookEventName: 'PostToolUse';
      additionalContext?: string;  // HAS IT
    };

Documentation Gap

The documentation doesn't explicitly state that PreToolUse cannot inject context—users must infer it from the schema. Even if this feature isn't added, explicitly documenting this limitation would help developers avoid wasted effort.

Why This Matters

PreToolUse is the only hook that fires before a tool runs AND knows which tool is about to run. This makes it uniquely positioned for:

• Injecting tool-specific guidance (testing methodology for test files, security guidelines for auth files)
• Providing context-aware instructions based on file type/path
• Just-in-time documentation injection

Without additionalContext, these use cases require workarounds that either waste context (global loading) or arrive too late (PostToolUse).