Add event hook system for external tools to subscribe to checkpoint events

[jcleira]

Summary

Allow external tools and scripts to subscribe to Partio checkpoint events (e.g., checkpoint created, session ended) by registering hook scripts in .partio/hooks/. This enables dashboards, notification systems, and automation to react to Partio events without polling the filesystem.

Inspired by entireio/cli#749.

What to implement

Add an event hook dispatch mechanism to Partio's post-commit flow:

1. Hook directory: After a checkpoint is created, look for executables in .partio/hooks/checkpoint-created/ and run them in sequence, passing checkpoint data via environment variables or stdin JSON.

2. Event payload: Each hook receives a JSON payload (via stdin or env vars) with:

   • checkpoint_id — the checkpoint ref/hash
   • commit_sha — the associated git commit
   • session_id — the agent session ID
   • agent — the agent name (e.g., claude-code)
   • branch — current git branch
   • repo — repo root path

3. Hook execution: Non-zero exit from a user hook should emit a warning but not fail the git operation (consistent with Partio's error-resilient hook philosophy).

4. Configuration: Optionally guard behind a config flag hooks_enabled: true in .partio/settings.json.

Why

Users building tools on top of Partio (dashboards, Slack notifications, CI triggers) currently must poll the filesystem for checkpoint branch changes. A structured hook system lets them react in real time without fragile polling, and without requiring modifications to Partio itself.

User Relevance

Teams using Partio for AI audit trails often want to pipe events downstream — notify a Slack channel when a Claude session is checkpointed, trigger a CI job to analyze the session, or update a dashboard. Without event hooks, every integration requires custom polling logic. A standardized hook directory makes Partio a composable part of the developer toolchain.

Target Repos

• cli

Context Hints

• internal/hooks/ — existing git hook implementations
• internal/checkpoint/ — checkpoint creation logic
• internal/session/ — session lifecycle

Acceptance Criteria

• After a checkpoint is created, executables in .partio/hooks/checkpoint-created/ are discovered and run
• Each hook receives a JSON payload with checkpoint_id, commit_sha, session_id, agent, branch, repo
• A non-zero hook exit emits a warning log but does not fail the git commit
• Hooks run in lexicographic order within the directory
• If .partio/hooks/ does not exist, dispatch is a no-op with no error
• partio doctor reports any hooks that are not executable
• Table-driven tests cover hook discovery, execution order, and failure resilience