Reading agent status out of Claude Code's hooks

I'll pull the source article so the paragraphs stay grounded in what's actually written, not invented figures.A write-up on agent-manager.dev explains how Claude Code hooks still leave gaps when you try to build a trustworthy multi-agent status list. The author needed a terminal view of running agents that shows, without inspecting each pane, which session is working, blocked, or done. Screen capture plus regexes remains the fallback for every CLI tool the project supports, but it is guessing: a spinner can vanish for one frame and look idle, or a tool can print spinner-shaped text and look busy. Claude Code hooks remove most of that guessing for Claude sessions; the post is about the edges where they do not.

The happy path is thin and deliberate. Each managed session gets a generated settings file via --settings and an AGENT_MANAGER_STATUS_FILE path. Every hook is a one-line shell command that writes a single status word into that file, guarded so that if the settings load outside a managed session the unset variable makes the command a no-op and exits 0. A poller reads the file every two seconds. Event mapping covers working, waiting (conditionally), finished, idle, and SessionEnd deleting the file. Notification is ambiguous: it fires both on a permission prompt and after 60 seconds of an idle input box as a nudge. Taking the event at face value marks every walked-away session as blocked; the fix is to read the stdin payload and drop reminders that contain waiting for your input.

Several lifecycle cases never update status correctly. A plain-text question like should I also update the tests? still fires Stop, so the file says finished and the list shows a green check while the session waits forever for a one-word answer. There is no hook for the model asking in prose; that only lives on screen. Esc interrupt also fires nothing, so the last working write sticks until the user types again. Stop is about the main agent loop, not spawned background work: finished can land while subagents keep grinding and changing the repo, and background PreToolUse/PostToolUse can pin working forever because they never fire their own Stop. SessionStart fires on startup, resume, clear, and compact; compact mid-turn will write idle over an active session unless the matcher is limited to startup|resume|clear. A crash or SIGKILL skips SessionEnd, so the status file can keep reporting working for a process that no longer exists and must be cross-checked against a live process.

For engineers building agent dashboards, orchestrators, or multi-session TUIs, the lesson is not that hooks are useless. They are the first-tier source: they see silent tool calls the screen cannot, while the pane still catches questions, interrupts, and errors hooks never emit. agent-manager reconciles both in poller.go: a hook finished is overridden when the pane shows waiting, errored, or working; a hook working is overridden when the pane shows waiting, finished, or errored. The pane only reports a resting state once the newest turn has gone quiet, so reconciliation does not thrash mid-stream. Trusting either source alone produces a status list you cannot leave unwatched, which defeats the product goal.

In market terms this sits next to every multi-agent terminal manager that still scrapes CLIs. agent-manager is a Go, Apache-2.0 tmux TUI that runs Claude Code, Codex, and OpenCode side by side; the hooks path is Claude-specific and lives under internal/hooks for settings generation and status files, with reconciliation in internal/ui/poller.go. Other tools either stay on pure screen parsing or will hit the same incomplete event surface if they adopt Claude Code hooks without a second signal. The post landed on Hacker News under AI Agents with one point and zero comments, so the design notes matter more as engineering documentation than as a viral launch.

The practical takeaway is to treat Claude Code hooks as a high-confidence partial feed, not as a complete state machine: write guarded one-line status updates, filter Notification by payload, match SessionStart carefully, require an independent process check after crashes, and always re-read the pane to correct finished versus working. Watch whether Anthropic adds events for prose questions, interrupts, and subagent lifecycle; until then any reliable agent-status product needs both the hook file and screen reconciliation, which is what agent-manager already ships.