Feature request: expose agent lifecycle events / observability surface for external tools

[soyomarvaldezg]

Problem

Crush currently exposes only one hook event: PreToolUse (top-level agent only, no PostToolUse, Stop, Notification, UserPromptSubmit, etc. — the docs explicitly say "please let us know which hooks you'd like to see next").

For people running multiple Crush instances at once (one per project, each in its own terminal pane), there is no supported way to know which agent is busy, which is blocked waiting for a permission decision, and which finished its turn without manually flipping through every pane.

What I built as a workaround

I built crush-tmux: a small Go tool that shows a tmux status-bar summary (working / blocked-on-permission / done-but-unseen, per live instance) plus an fzf popup that jumps to the pane that needs you.

It works, but "vibe-coded" on top of three fragile, unsupported surfaces:

1. Process discovery (ps TTY → tmux pane match) to answer "which instances exist"
2. Screen scraping (tmux capture-pane of the last 15 lines) to detect the Allow/Deny permission barrier and the working spinner — these are Crush TUI internals with no stable surface, so any reworded prompt breaks detection
3. Read-only SQLite probing of <cwd>/.crush/crush.db (MAX(messages.created_at) watermark) to tell "busy" from "done" — the internal DB schema is also not a public API

What would help (feature request)

An official, stable observability/lifecycle surface for external tools, any subset of which would remove the screen-scraping and DB-probing fragility:

• More hook events: at minimum PostToolUse, Stop/TurnComplete, UserPromptSubmit (already planned per docs/hooks/FUTURE.md), and a PermissionRequest/PermissionResponse event carrying the tool/command being approved
• A documented event stream: the existing SSE endpoint (GET /v1/workspaces/{id}/events — payloads message, session, permission_request, agent_event, run_complete) in server mode is exactly the right shape; documenting it as a supported integration point, or exposing an equivalent crush events/crush session events CLI, would let tools like crush-tmux subscribe instead of scraping
• Stable state file or IPC: e.g. a documented, append-only per-session JSONL activity log, or an on_state_change-style notification ("working" / "permission_requested" / "done") — with the session id they already expose (CRUSH_SESSION_ID, /v1 session events) for correlation

Why it matters

Multi-instance orchestration (tmux dashboards, status bars, notification drivers, CI-style supervision of Crush agents, tools like agent-deck/ccmux for other CLIs) is a real emerging use case. A stable lifecycle surface would let the ecosystem build on Crush instead of on its TUI pixels and private DB schema.

I would be happy to port crush-tmux to consume such an API and help validate it.

[meowgorithm]

Wonderful good feedback here, @soyomarvaldezg. A few initial notes:

• There are a bunch more hooks coming; have a look at: feat(hooks): add more lifecycle hooks #3146. Would love to get your thoughts.
• Server-client is still not officially released, but usable and hopefully not too far off. Part of that work will definitely be docs.

[soyomarvaldezg]

Superb! Looking through #3146

[soyomarvaldezg]

Thanks @meowgorithm — just reviewed #3146. The new hooks map directly onto what crush-tmux currently scrapes and probes for:

• PermissionRequest / PermissionResult → replaces the footer grep for Allow/Deny + Requesting permission... (the ✋ blocked state)
• TurnStart / TurnEnd → replaces the watermark-moved heuristic for ● working vs ✓ done
• SessionStart / SessionEnd → replaces ps TTY discovery for "which instances exist"

Once merged I'll port crush-tmux to consume these hooks (likely via a small listener that writes the same crush-tmux-state.json the bar already reads), keeping the current screen-scrape path as a fallback for older Crush versions. Happy to test against the PR branch in the meantime if that helps.

Also added screenshots to the repo: https://github.com/soyomarvaldezg/crush-tmux#screenshots