Feature Request: Session-Scoped In-Memory State for Hooks

Title: Feature Request: Session-Scoped In-Memory State for Hooks

Labels: enhancement, feature-request, hooks, developer-experience

Is your feature request related to a problem? Please describe.

Currently, Claude Code hooks are stateless between invocations within a single session. While the PreToolUse and PostToolUse events are powerful, any hook that needs to maintain state across multiple tool calls must resort to external mechanisms, like writing to temporary files on the filesystem.

This approach has several significant drawbacks:

• Inefficiency: Constant file I/O for state management is slow and resource-intensive.
• Complexity: Hook authors must implement their own file locking, reading, parsing, and writing logic, which complicates what should be simple state updates.
• Race Conditions: With parallel hook execution, managing a shared state file becomes prone to race conditions, requiring complex and potentially unreliable locking mechanisms.
• Security: Writing state to the filesystem can be a security concern, especially if sensitive information is temporarily stored.

This limitation prevents more advanced and powerful use cases for hooks that rely on maintaining context throughout a development session.

Describe the solution you'd like

I propose extending the hook contract to include a session-scoped, in-memory key-value store that is managed by Claude Code itself. This state would persist only for the duration of the claude session and be accessible to all hooks.

This could be implemented by modifying the JSON interface for hook input and output:

1. Modify Hook Input (stdin)

Add a session_state object to the JSON payload sent to every hook's stdin.

• On the first hook invocation in a session, this would be an empty object {}.
• On subsequent invocations, it would contain the state as updated by previous hooks.

Example new input structure (based on the PreToolUse input from the documentation):

{
  "session_id": "abc123",
  "transcript_path": "/path/to/transcript.jsonl",
  "cwd": "/path/to/project",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": { "command": "npm run test" },
  "session_state": {
    "bash_commands_run": 4,
    "last_edited_file": "/path/to/file.js"
  }
}

2. Modify Hook Output (stdout)

Add an optional update_session_state object to the advanced JSON a hook can return via stdout.

• The contents of update_session_state would be shallow-merged into the existing session state after the hook successfully completes.
• If multiple hooks running in parallel for the same event modify the same key, the behavior should be defined (e.g., last write wins) or documented.

Example new output structure (based on the "Advanced: JSON Output" documentation):

{
  "continue": true,
  "update_session_state": {
    "bash_commands_run": 5,
    "last_edited_file": "/path/to/file.js"
  }
}

Describe alternatives you've considered

The primary alternative is the current method of using the filesystem (/tmp or a project-local file) to store session state. As detailed above, this is inefficient, insecure, and adds significant implementation overhead for hook authors.

Additional context & Use Cases

This feature would unlock several powerful use cases:

• Session-wide Metrics: A hook could track metrics like the number of times the Bash tool is used or which files are most frequently edited within a single session.
• Stateful Logic Between Hooks: A PreToolUse hook could record a timestamp in the session state, and a corresponding PostToolUse hook could read it to calculate and log the exact duration of a tool's execution.
• Complex Workflows: A hook could maintain a small state machine within the session, allowing it to behave differently based on previously executed commands or tool results (e.g., "after a test run fails, suggest a debugging command on the next prompt").

This would be a major enhancement to the power and utility of the hook system, making it a more robust platform for extending Claude Code's capabilities. This change would affect the schemas described in the "Hook Input" and "Hook Output" sections of the official Hooks reference documentation.