PreToolUse additionalContext

PreToolUse additionalContext enables hooks to inject context into model awareness before tool execution.

How It Works

A PreToolUse hook can output JSON containing an additionalContext field, which the runtime injects as a system reminder before passing a tool call to the model. The hook runs synchronously before the tool (e.g., Read, Write) executes, receives no blocking error if the hook fails, and does not prevent tool execution.

hooks:
  PreToolUse:
    - matcher: "Read"
      hooks:
        - type: command
          command: echo '{"additionalContext": "Your message here"}'

The context field must be valid JSON; only the additionalContext key is parsed. Multiple hooks across skill and global scopes can fire for the same tool.

Test Setup and Result

On 2026-01-16, Claude Code 2.1.9 was tested by creating a skill with a PreToolUse hook that echoed JSON containing additionalContext. Triggering a Read call fired the hook, the JSON was parsed, and the injected context appeared as a <system-reminder> block in the model's context window. The test passed.

Four verified behaviors emerged:

1. Hook fires before tool execution
2. JSON must be valid; only additionalContext key is used
3. Context injected as system reminder (non-intrusive, timestamped)
4. Execution is non-blocking (hook failure does not stop the tool)

Use Cases

Security warnings on sensitive file access, dynamic metadata annotation, audit logging with context, and situational instruction injection. A hook might check file path against a policy list and warn the model before Read executes, or log tool invocations with enriched context without blocking them.

Caveats

The hook output must be JSON on stdout. Malformed JSON is silently dropped. Context scales linearly with token cost; frequent injections can accumulate. Skill-scoped and global hooks both fire; no precedence order is defined if both match.