Event hooks: run a command when a session blocks, finishes, exits or a run fails #170

This was generated by AI during triage.

Summary

Event hooks: run a user-configured command when something happens to a session. For example: session becomes blocked or waiting for approval, an agent finishes, a run command fails, a session exits.

Motivation

A frequent want is "ping my phone when an agent needs me". Today that needs CSM to grow a feature per destination: Telegram, Slack, ntfy, a sound.

Herdr's plugin system is the heavy version:

• a manifest of actions, event hooks, panes and link handlers;
• distribution from GitHub, plus a marketplace;
• the cookbook includes agent-telegram-notify.

The event hook is the piece that gives most of the value for least cost.

Proposal (deliberately smaller than plugins)

• Configuration. Settings ▸ Hooks: a list of { event, command }. The command is an argv array, run without a shell (CLAUDE.md, "Never interpolate a value into a command line").
• Events.
  • session.waitingForInput, session.waitingForApproval;
  • session.done (once Show which sessions have an agent actively working, plus an activity timeline across sessions #154 or self-reported state exists);
  • session.exited, run.failed, run.succeeded.
• Context. Passed as environment variables plus a JSON payload on stdin: session id, name, folder, alert message, and for runs the run label and exit code.
  • Not as argv substitution: the alert text comes from terminal output and is untrusted.
• Execution.
  • Off the UI thread (Task.Run), with a timeout (e.g. 10 s), so output can't stall CSM.
  • Debounced per session and event.
  • Failures logged to crash.log.
• --clean. Hooks are disabled in --clean runs.

Out of scope

• Plugin manifests and installing from GitHub. Revisit once there's a socket/MCP API (Host one MCP server for all sessions: self-control, fleet overview, and orchestration #132), because Herdr's plugins are "commands that call the CLI".
• Custom panes and link handlers (Clickable links in terminal output (OSC 8 + plain-text URLs), opened in the default browser #133 covers links).

Related: #149, the clickable-notifications issue filed alongside this one, #154.