Feature Request: Introduce `SessionStart` and `SessionEnd` Lifecycle Hooks

Title: Feature Request: Introduce SessionStart and SessionEnd Lifecycle Hooks

Labels: feature-request, enhancement, hooks

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

The current hooks system in Claude Code is powerful for intercepting events within an active session (e.g., PreToolUse, UserPromptSubmit). However, there is no mechanism to execute scripts automatically at the very beginning of a session's lifecycle (i.e., upon startup) or at the very end (i.e., upon clean exit).

This limitation prevents users from automating crucial setup and teardown tasks. For example, developers must manually prepare their environment before each session (like running npm install in a new git worktree) and perform cleanup actions afterward (like archiving transcripts or logging session metrics). This manual overhead reduces efficiency and makes it difficult to ensure consistent environments across sessions and teams.

Describe the solution you'd like

I propose introducing two new top-level hook events, consistent with the existing hooks architecture described in the documentation at en/docs/claude-code/hooks:

1. SessionStart: This hook would trigger once, immediately after a new interactive claude session is successfully initialized and before the first prompt is displayed to the user.
2. SessionEnd: This hook would trigger on clean session termination (e.g., via the /exit command or Ctrl+D), allowing scripts to run before the process fully exits.

These hooks would be configured in settings.json at the top level of the hooks object, similar to UserPromptSubmit, and would not use a matcher.

Example settings.json Configuration:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          { "type": "command", "command": "/path/to/session_setup.sh" }
        ]
      }
    ],
    "SessionEnd": [
      {
        "hooks": [
          { "type": "command", "command": "/path/to/session_cleanup.py" }
        ]
      }
    ]
  }
}

Proposed Hook Input (stdin):

• SessionStart could receive initial session info like session_id and cwd.
• SessionEnd could receive the final transcript_path and session cost data, which would be invaluable for logging, archiving, and analysis.

Describe alternatives you've considered

Wrapping the claude command in a shell script is a possible workaround, but it's brittle. It cannot easily access session-specific information like the final transcript_path or session ID, and it does not integrate with the official hooks system, making it a less robust and less discoverable solution.

Additional context & Use Cases

Introducing session lifecycle hooks would unlock significant automation and integration capabilities for developers and teams.

Key Use Cases:

1. Automated Environment Setup: On SessionStart, a script could run npm install, bundle install, or pip install -r requirements.txt to ensure dependencies are perfectly synced for the session. This is especially useful when using features like Git worktrees, where each worktree might have a slightly different dependency state.

1. Session Logging & Metrics:

• On SessionStart, log the session's start time, cwd, and session_id to a central database or monitoring tool.
• On SessionEnd, push the final session cost (from /cost) and duration to an observability platform like Datadog or an OpenTelemetry collector, aligning with the existing monitoring features.

1. Automated Cleanup: On SessionEnd, a hook could automatically delete temporary files created during the session, stop related background processes, or archive session artifacts to a designated location.

1. Transcript Management: On SessionEnd, a script could use the transcript_path from the hook's input to copy the final conversation to a shared team drive, a personal archive, or a knowledge base.

This feature would formalize session setup and teardown logic, ensuring consistency and enabling more complex, stateful integrations for professional development workflows. Thank you for considering this enhancement.