Feature: pre-archive hook to gate session archiving on custom checks

Summary

When archiving a Claude Code session, there is no way to run a blocking pre-archive check. A pre-archive hook would allow teams to enforce that certain steps (e.g. a departure check, commit, or documentation pass) have been completed before the session is closed.

Motivation

In projects using Claude Code worktrees, it's easy to archive a session before doing end-of-session hygiene (committing work, running a departure check, updating docs). There is currently no mechanism to warn or block the archive action if those steps haven't been completed.

Proposed behavior

Add a PreArchive (or SessionStop) hook event to settings.json, consistent with the existing PreToolUse/PostToolUse hook model. If the hook exits non-zero, the archive action is blocked and the user sees the hook's stderr output as a warning.

Example config

{
  "hooks": {
    "PreArchive": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "scripts/pre-archive-check.sh"
          }
        ]
      }
    ]
  }
}

The script could check for uncommitted changes, verify a departure-check commit exists in the current session's branch, etc.

Alternatives considered

• Convention only — rely on the user to always run /departure-check before archiving. Brittle; easy to forget.
• Scheduled agent — a cron agent that flags sessions without a departure check after the fact. Catches mistakes too late.