Every yes was a security finding
Starfish decides every tool call a governed Claude Code session makes. Until this week, it could not tell you which sessions were running, or whether one of them was stuck waiting for you. The hooks daemon kept a per-session map for its own bookkeeping and exposed none of it. When the governor answered ask, the question went to Claude Code's own prompt and nowhere else. With four sessions in four windows, the only way to find the stuck one was to look at each window.
We spent some time with herdr, an Apache-2.0 terminal workspace for coding agents. Its whole promise is that you never hunt for the stuck agent. We took two ideas from it and no code: sort sessions by what needs a person, and show state with a shape as well as a colour. Our first mockups showed everything Starfish knows about every session. They were accurate, and they were too much. The screens we kept each answer one question, and the first is does anything need me?
Those screens need data that did not exist. This change is that data.
Five states, none of them stored
The overlay daemon now records every hook event in a session registry and writes a snapshot that the CLI, the sidecar and the desktop app can read. The registry never stores a session's state. It works it out from what it has seen:
◆ blocked an ask is open
✓ done the last turn ended, and nobody has looked since
◐ working a turn is in flight, and something happened in the last 10 minutes
○ idle nothing in flight, or nothing heard for 10 minutes
· ended the session ended
Working it out each time is a choice about missed events. If a Stop never arrives, a stored state would say "working" forever. A derived one says "idle" after ten minutes, which is less specific and still true. Some things cannot be derived. A Claude Code window closed in the middle of a prompt sends nothing at all, so a session that has been quiet for 24 hours is dropped, even with an ask still open.
The order is herdr's: blocked first, oldest ask at the top, then finished, working and idle. In a terminal:
$ starfish sessions
needs you
◆ worker billing-api (fix/retry) 4:10 Edit: src/retry.ts [medium]
Answer in that Claude Code window; Starfish records what happens.
everyone else
◐ worker starfish (main) working · Bash
✓ worker docs-site (main) finished 3m ago
The sidecar serves the same list at GET /v1/sessions and pushes a sessions event on its live stream when the list changes. An operator token sees every session. Any other token sees only its own, the same rule we already apply to pending decisions.
Starfish does not answer these asks
When the governor answers ask, Claude Code shows its own prompt and the person answers there. We now copy that ask into Starfish's approval queue, so one queue shows everything that is waiting. The copy goes on its own channel, and that channel is observe-only.
Two guards keep it honest. The broker's resolve() refuses an ask on that channel, because an "approve" in Starfish would be audited as an operator decision that changed nothing. A new settle() closes the ask with what actually happened, and it refuses every other channel, so watching can never stand in for an operator.
What happened is read from the events that follow the ask:
PostToolUse, same tool_use_id → ran the person approved
Stop, a new prompt, SessionEnd → not-run refused, or the turn ended
another PreToolUse first → superseded refused, or the tool failed
Every yes was a finding
To close an ask as ran, the daemon matches the PostToolUse to the ask by its tool_use_id. Wiring that up meant following an approved ask all the way through the hook session. The same result that settles the ask was also writing a second audit line: an orphan-post failure.
The hook session enforces no silent execution: every PostToolUse has to follow a PreToolUse the governor allowed. A result with no allowed call before it means a tool ran without the governor's say. That is logged as a violation, and the monitor counts it.
From the hook's side, an approved ask never looked allowed. The governor's answer was ask. The person said yes in Claude Code, the tool ran, and its result arrived with no allowed call to match. So the hook session logged it as an orphan.
Every approved ask produced a false security finding. No decision changed, because the hook shim ignores the daemon's reply to a PostToolUse. The monitor did not ignore it. Each sweep that saw an orphan raised a high-severity "possible silent execution" finding and flagged it for a person. The orphan line is also recorded as a denial against the agent, so three approvals in one sweep window tripped the "repeated denials, possible probing" rule as well.
Nothing connected a finding to the approval that caused it. Audit lines carried no session, and the monitor shows a number. A number that goes up every time someone does the right thing is easy to read as background. That is the real cost. A violation alarm that fires on every approval teaches people to ignore the violation alarm.
The fix is narrow on purpose. The hook session remembers the exact tool_use_ids it asked about, up to 256 of them, and accepts one PostToolUse for each. A result with an unknown id is still an orphan. So is a second result reusing an id, and so is a result with no id at all. Treating every asked call as allowed would have been simpler, and it would have made a replayed id invisible. Tests pin both directions: the approved case is clean, and the unknown and reused cases are still flagged.
Every line knows its session
Tool calls and audit events now carry an optional sessionId. The governor's decision line, the hook session's own lines, and the broker's filed and settled lines all record it. A line with no session is byte-for-byte what it was before, so existing hash chains verify unchanged.
This is what would have caught the bug earlier. A finding now points to a session, and the session shows the ask that came just before it.
What it does not record
starfish install --claude-code now also registers SessionStart, UserPromptSubmit, Stop and SessionEnd. These hooks only observe and never block. The hook shim forwards a few descriptive fields: the tool use id, the working folder, the permission mode, the model and the session source. It never forwards the prompt text or the transcript path. Targets are scrubbed for secrets and clipped to 300 characters. Our end-to-end check sends a prompt through the real hook command and confirms that the text appears nowhere in the snapshot or the audit.
The daemon records an event only after it has sent the decision back. Recording cannot change a decision, and if it fails, the failure is swallowed. A test runs the same calls with tracking on and off and requires identical decisions.
Not done yet
- Approving from Starfish. The calm screens put Approve and Deny on the ask, but today you still answer in Claude Code. If Starfish answered, the hook would have to wait for a verdict, and the hook timeout is 10 seconds today. It would also move the place where a person says yes. That is a product decision, not a refactor, so it waits.
- Seen markers. A finished session stays "done" until its next prompt. Marking it seen from a UI needs a small authenticated request to the daemon, which does not exist yet.
- Desktop push. The sidecar stream now carries sessions. The desktop app does not listen to it yet.
- Scope. One daemon serves one project on one machine, and only Claude Code hooks are wired. There are no per-session budgets.
The registry, the observe-only channel, session ids on the audit, and the orphan fix are on master with 1,026 tests passing. They are not in an npm release yet: the current release is 0.27.0. The design note is docs/design/SESSION_REGISTRY.md.