Project Starfish DevlogGitHub
2026-11-07

Every yes was a security finding

We set out to answer one question: which of my agent sessions is waiting on me? Wiring the answer turned up a defect. Every time a person approved a tool call in Claude Code, our audit logged it as a no-silent-execution violation.

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.

An approve button that changes nothing is worse than no button. The audit would record a decision nobody made.

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 check was right. It just had no way to know that a person had said yes.

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

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.

Project Starfish · a governance-first, deny-by-default AI ecosystem · Apache-2.0. This devlog is a backdated build journal reconstructed from the project history.