Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
import type { AgentId } from './config'
import type { ObservedClaudeAccount } from '../types'
import { ASK_USER_QUESTION_TOOL, isSafeToolName, readQuestions, type HeldPermission } from './permission-answer'
import {
isClaudeAgentId,
isInjectedSubagentPrompt,
liveBackgroundSubagentIds,
liveBackgroundTaskIds
} from './claude-subagents'
export type AgentState = 'working' | 'waiting' | 'blocked' | 'done'
// The universal event shape every agent normalizer produces. Agent-specific
// field names live only inside the per-agent normalizers below.
export interface NormalizedAgentEvent {
nodeId: string
agentId: AgentId
kind: 'state' | 'subagent-start' | 'subagent-end' | 'recurring' | 'session' | 'background-task'
state?: AgentState
// done only: the turn ended because the user interrupted (Esc/Ctrl-C) — the renderer
// skips the completion alert/unread for these (the user was right there).
interrupted?: boolean
/**
* done only: this turn ended on an API/model ERROR rather than by finishing (issue #521).
*
* An annotation, not a fifth `AgentState`, and the reason is not only that a new state would
* ripple through both raw listeners and the mobile mirror: **errored is a fact about the last
* turn, not a mutually exclusive live state.** A station whose turn 1 errored IS idle — the two
* facts coexist, and only one of them is the station's state.
*
* It is set from the agent's own `StopFailure` hook, which claude and grok both fire INSTEAD of
* `Stop` when the turn dies (`CLAUDE_HOOK_EVENTS`/`GROK_HOOK_EVENTS` already subscribe to it —
* without the subscription the badge would stick on RUNNING). So the source is a real hook, not
* a heuristic: a `Stop` whose turn produced no assistant message was considered and refused on
* the closed-set rule — interrupted and tool-only turns look identical to it, and a false
* attention signal has no later hook to clear it.
*
* Carried on the event so both shells change together by construction: `normalizeClaude` /
* `normalizeGrok` live in `src/shared` and both raw listeners forward what they return.
*
* NO ERROR TEXT accompanies it. Whether claude's `StopFailure` payload carries the failure
* message has not been measured, and `last_assistant_message` is the previous assistant turn
* rather than the error — reporting that as "the error" would be a wrong fact stated
* confidently. The flag says only what the hook said.
*/
errored?: boolean
// done only: this `done` was inferred from the CLI going IDLE at its prompt (Claude's
// `idle_prompt` notification), not from a turn-end hook. It is a RESCUE signal: it may only
// move a node that is still `working` (see reduceEntry / the Canvas listener), because a
// pending approval/question is also "idle at the prompt" and must not be cleared by it.
idle?: boolean
// waiting only (Codex `request_user_input`): the turn ENDS (Stop fires) with this question
// still unanswered — the answer arrives as a fresh UserPromptSubmit, not a tool result — so
// reduceEntry must hold `waiting` through that turn-end `done` instead of letting it flip
// the node to a green "done" over a blocked session. Cleared by the next genuine turn, any
// other tool activity, an interrupt, or a session boundary (see reduceEntry).
awaitingInput?: boolean
/** Claude picker lifecycle, correlated with its transcript tool_result. */
questionId?: string
answeredQuestionId?: string
// true only for a genuine new turn (Claude UserPromptSubmit), so the renderer can
// clear per-turn fan-out without clearing on every mid-turn tool event.
newTurn?: boolean
/**
* Claude only, on the `UserPromptSubmit` that opens a turn: the CLI's own id for that turn
* (`prompt_id`). Claude writes the SAME id as `promptId` on every transcript record of the
* turn, including the `[Request interrupted by user]` marker it appends when the user presses
* Esc / Ctrl+C — the one trace an interrupted turn leaves, because no hook fires for it
* (measured on 2.1.285, `__fixtures__/claude/interrupt-capture.json`). The status mirror keeps
* this id so a marker can be matched to exactly the turn it ends (`recordTurnInterrupt`), never
* to an older one read back from the transcript. `''` when the prompt event has no usable id (none,
* or not a plain token) — which CLEARS the mirror's id; absent on every other event.
*/
turnId?: string
sessionId?: string
lastMessage?: string
// blocked (Claude PermissionRequest) only: the deterministic-approval ticket the managed hook
// generated and is polling for an answer file. Rides from the raw POST body's
// `nodeterm_pending_id` (merged into the payload by the hook server) so the phone/canvas can
// answer the held hook. Absent = no held hook (legacy prompt path). See docs/hook-reply-approvals.md.
pendingId?: string
// needs-you (blocked/waiting) only: how the shell classified this ask AFTER the mirror's
// stash-priority reclassification (see agent-status-mirror.recordAgentEvent). 'question' = an
// AskUserQuestion picker (its `pendingId` is stripped — approve/deny on a question is wrong UX);
// 'approval' = a genuine permission request (its `pendingId`, if any, is kept). Absent on every
// non-needs-you event. Claude also identifies non-picker PermissionRequest hooks here so a
// concurrent parent picker cannot hide their approval tickets. The canvas keys the approve/deny
// buttons off `pendingId`, which is now absent on a question. */
askKind?: 'question' | 'approval'
/** blocked (Claude PermissionRequest with a held hook) only: the answer-file ticket PLUS the tool
* being asked about, so a surface can tell a plan (ExitPlanMode) or question (AskUserQuestion)
* hold from an ordinary permission and offer the right controls (a structured
* `answerPermission`). Deliberately separate from `pendingId`, which the mirror STRIPS from a
* question so no approve/deny button lights on a picker — this field lights nothing by itself.
* Additive and optional: an older consumer ignores it. See docs/hook-reply-approvals.md. */
held?: HeldPermission
// session
sessionTitle?: string
// session lifecycle phase: 'start' resets to idle, 'end' resets + clears loop/fan-out
sessionPhase?: 'start' | 'end'
// subagent
toolUseId?: string
subagentType?: string
/**
* Claude only: WHICH of Claude's two subagent signals produced this subagent event, so
* `core/claude-subagent-lifecycle.ts` can merge them into one card per subagent.
* - `'native'` — Claude's own `SubagentStart`/`SubagentStop` hooks, keyed by `agent_id`.
* - `'tool'` — the older reconstruction from `PreToolUse`/`PostToolUse` on the `Agent`/`Task`
* tool, keyed by `tool_use_id`.
* - `'transcript'` — the synthetic end the shells sniff out of a `<task-notification>`.
* Absent on every other agent's events, which the lifecycle passes through untouched.
*/
subagentSignal?: 'native' | 'tool' | 'transcript'
/**
* subagent-start only (set by the lifecycle, never by a normalizer): this card REPLACES the card
* keyed by this id. Emitted once, when a session proves it sends native hooks while a card built
* from the tool path is already on screen — consumers move that card (its place, its start time)
* to the new key instead of drawing a second one.
*/
supersedes?: string
/** Claude tool-path end only: the exact child `agent_id` its `tool_response.agentId` names. */
subagentAgentId?: string
/** Claude async-launch ack only (a `state: working` event): the exact tool_use_id → agent_id pair
* the ack names, measured to arrive ~1 ms after the child's `SubagentStart`. */
subagentLaunch?: { toolUseId: string; agentId: string }
/**
* Claude `Stop` only: the ids of the BACKGROUND tasks (async subagents, background shells) the
* CLI reports still running at this turn end. Present only when the payload carried the
* inventory — absent from older CLIs, so absent means "unknown", never "none". See
* `liveBackgroundTaskIds`.
*/
backgroundTaskIds?: string[]
/** The async SUBAGENTS among `backgroundTaskIds` (`liveBackgroundSubagentIds`) — the only
* background work plain `--after` holds on. Present exactly when `backgroundTaskIds` is. */
backgroundSubagentIds?: string[]
/** Host-observed start time for display-only renderer reload replay. */
subagentStartedAt?: number
/** Host-observed time of the subagent's last transcript chunk, replayed with the start so a
* reloaded card keeps its remaining silence window (see `WORKING_STALE_MS`). */
subagentLastActivityAt?: number
// grok StopCancelled only: normalized state-less so the mirror can make the session-aware badge
// decision (a subagent cancellation must not end its parent session).
cancelReason?:
| 'user_interrupt'
| 'permission_rejected'
| 'permission_cancelled'
| 'max_turns'
| 'no_progress'
| 'unknown'
// grok compaction lifecycle. These events carry the old/new session ids but do not themselves
// prove the agent is working or idle, so consumers may update identity without moving state.
compactionPhase?: 'pre' | 'post'
taskLabel?: string
durationMs?: number
tokens?: number
toolUses?: number
result?: string
/**
* The POST that produced this event presented a per-node token the running instance had minted
* for THIS node id. Set by the hook server, never by a normalizer.
*
* It is a LABEL, not a permission: `false` covers every client that predates the token, the
* phone, and the documented cross-instance failover, so no consumer may treat it as "reject".
*/
verified?: boolean
/**
* The revision of the managed hook script that posted this event (`MANAGED_SCRIPT_REVISION`,
* sent as `X-Nodeterm-Hook-Client`). Set by the hook server, never by a normalizer.
*
* `undefined` means the client sent no stamp — a script that predates the header, i.e. one that
* also predates per-node identity. That is a DISTINCT state from `verified: false`, and telling
* them apart is the entire point: a session with no token file needs "retry after its next turn",
* a session running an old script needs "reconnect the project / restart the app", and before
* this field the two were indistinguishable on the wire.
*
* Like `verified` it is a LABEL: nothing may refuse a POST because of it.
*/
clientRevision?: number
/**
* Which Claude account the posting session was OBSERVED to run under, derived by the hook server
* from the payload's `transcript_path` (claude events only). Set by the hook server, never by a
* normalizer. A LABEL like `verified`: it drives the per-node account chip and the account-scoped
* transcript readers for nodes that carry no `data.accountId`; nothing may refuse or grant on it.
*/
account?: ObservedClaudeAccount
// recurring
recurringKind?: 'loop' | 'schedule' | 'cron'
/** The recurring job was REMOVED (e.g. CronDelete) — take the card down. */
recurringEnd?: boolean
task?: string
schedule?: string
}
// What the hook server hands a normalizer: the node id, the agent id, and the
// agent's raw hook JSON (parsed) plus the prompt text when present.
export interface RawHookEnvelope {
nodeId: string
agentId: AgentId
payload: Record<string, unknown>
}
const SUBAGENT_TOOLS = new Set(['Agent', 'Task'])
const RECURRING_TOOLS = new Set(['Skill', 'CronCreate', 'ScheduleWakeup'])
/** A Claude turn id (`prompt_id`, a uuid today) as a plain bounded token, else nothing. */
const TURN_ID_RE = /^[A-Za-z0-9_-]{1,128}$/
function turnIdOf(v: unknown): { turnId: string } {
// '' = "a prompt opened a turn, but with no usable id": the mirror then FORGETS the previous
// turn's id instead of keeping it, so no marker can be matched to a turn that has ended.
return { turnId: typeof v === 'string' && TURN_ID_RE.test(v) ? v : '' }
}
interface ClaudePayload {
/** SubagentStart/SubagentStop: the child. Any other event: the child that produced it. */
agent_id?: unknown
agent_type?: string
/** Stop / SubagentStop: the session's background-task inventory (see liveBackgroundTaskIds). */
background_tasks?: unknown
hook_event_name?: string
session_id?: string
/** Deterministic-approval ticket the managed hook script added to its POST body and the hook
* server merged into this payload (PermissionRequest only). */
nodeterm_pending_id?: string
/** Deterministic-approval "answered" signal: the managed hook fired a second POST the instant it
* read a valid allow/deny answer file, tagged nodeterm_answered=<decision>, merged into this
* payload by the hook server. It rides alongside the original PermissionRequest payload, so it is
* matched BEFORE hook_event_name and maps to a synthetic working transition (not a new ask). */
nodeterm_answered?: string
notification_type?: string
is_interrupt?: boolean
last_assistant_message?: string
prompt?: string
/** The CLI's id for the turn this event belongs to (see `NormalizedAgentEvent.turnId`). */
prompt_id?: unknown
tool_name?: string
tool_use_id?: string
tool_input?: {
subagent_type?: string
description?: string
prompt?: string
skill?: string
cron?: string
/** Bash only: the task was launched as a background shell (`run_in_background: true`). */
run_in_background?: boolean
/** AskUserQuestion only — read through `readQuestions`, never trusted as typed. */
questions?: unknown
}
tool_response?: {
status?: string
isAsync?: boolean
/** Agent/Task only: the child's `agent_id` (measured, 2.1.284 — on the async ack and the sync end). */
agentId?: unknown
content?: { type?: string; text?: string }[]
totalDurationMs?: number
totalTokens?: number
totalToolUseCount?: number
}
}
/**
* Claude Code launches subagents async by default: the Task/Agent PostToolUse fires
* ~immediately with a launch acknowledgment, not the finished result. Treating that as the
* subagent's end flips the card to done seconds after it starts, with no output. The real
* end arrives later as a <task-notification> in the parent transcript.
*/
export function isAsyncSubagentLaunch(r: { status?: string; isAsync?: boolean } | undefined): boolean {
return r?.status === 'async_launched' || r?.isAsync === true
}
/** The held request a PermissionRequest names. A question also carries its exact texts (the same
* reader the question card uses), so a surface offers controls only on the card it belongs to. */
function heldOf(pendingId: string, toolName: string, p: ClaudePayload): HeldPermission {
if (toolName !== ASK_USER_QUESTION_TOOL) return { pendingId, toolName }
const qs = readQuestions(p.tool_input)
return qs ? { pendingId, toolName, questions: qs.map((q) => q.question) } : { pendingId, toolName }
}
export function normalizeClaude(env: RawHookEnvelope): NormalizedAgentEvent | null {
const p = env.payload as ClaudePayload
// Child tool activity cannot drive the parent, but permission requests still need a reply.
if (p.agent_id && ['PreToolUse', 'PostToolUse', 'PostToolUseFailure'].includes(p.hook_event_name ?? '')) return null
const base = { nodeId: env.nodeId, agentId: env.agentId, sessionId: p.session_id }
// Deterministic hook-reply "answered" signal (docs/hook-reply-approvals.md): the managed hook
// fires this the instant it reads a valid allow/deny answer file — the agent is about to proceed
// (on 'deny' it typically continues the turn too), so map both to a synthetic 'working' transition
// that clears the NEEDS YOU badge without waiting for the agent's next real hook. Threads the
// pendingId so the mirror's state-leave resolves the open approval. It is NOT a new ask — a
// 'working' state never produces an inbox approval/question. Matched BEFORE hook_event_name because
// it rides alongside the original PermissionRequest payload.
if (p.nodeterm_answered === 'allow' || p.nodeterm_answered === 'deny') {
return {
...base,
kind: 'state',
state: 'working',
...(p.nodeterm_pending_id ? { pendingId: p.nodeterm_pending_id } : {})
}
}
const ev = p.hook_event_name
const tool = p.tool_name ?? ''
// Claude's native subagent hooks (since 2.0.43), keyed by the child's `agent_id`. MEASURED on
// 2.1.284 (fixture __fixtures__/claude/subagent-hook-payloads.json): both carry the PARENT's
// session_id; the start names the child only by agent_id + agent_type (no tool_use_id, no task
// text); the stop adds `last_assistant_message` and `agent_transcript_path`. A stop is the end of
// the child's TURN — sync or async, it arrives before the `<task-notification>` — but a background
// child that stops while its own children run is RESUMED later under the same agent_id (a second
// start). Claude also fires stops for internal side-agents (prompt suggestions) that never
// started: that one is dropped by the lifecycle, by id, not here.
if (ev === 'SubagentStart' || ev === 'SubagentStop') {
if (!isClaudeAgentId(p.agent_id)) return null
const subagentType = typeof p.agent_type === 'string' && p.agent_type ? p.agent_type : undefined
return ev === 'SubagentStart'
? { ...base, kind: 'subagent-start', toolUseId: p.agent_id, subagentType, subagentSignal: 'native' }
: {
...base,
kind: 'subagent-end',
toolUseId: p.agent_id,
subagentType,
subagentSignal: 'native',
result: typeof p.last_assistant_message === 'string' ? p.last_assistant_message : undefined
}
}
if (ev === 'PreToolUse' || ev === 'PostToolUse') {
if (tool === 'AskUserQuestion' && p.tool_use_id) {
return ev === 'PreToolUse'
? { ...base, kind: 'state', state: 'waiting', questionId: p.tool_use_id }
: { ...base, kind: 'state', state: 'working', answeredQuestionId: p.tool_use_id }
}
if (SUBAGENT_TOOLS.has(tool)) {
if (ev === 'PreToolUse') {
return {
...base,
kind: 'subagent-start',
toolUseId: p.tool_use_id,
subagentType: p.tool_input?.subagent_type,
taskLabel: p.tool_input?.description ?? p.tool_input?.prompt,
subagentSignal: 'tool'
}
}
const childId = isClaudeAgentId(p.tool_response?.agentId) ? p.tool_response.agentId : undefined
// Async launch acknowledgment — the subagent just started, it didn't finish. It names the
// exact child, which is what lets the lifecycle pair this tool call with its SubagentStart.
if (isAsyncSubagentLaunch(p.tool_response)) {
return {
...base,
kind: 'state',
state: 'working',
...(childId && p.tool_use_id ? { subagentLaunch: { toolUseId: p.tool_use_id, agentId: childId } } : {})
}
}
return {
...base,
kind: 'subagent-end',
subagentSignal: 'tool',
...(childId ? { subagentAgentId: childId } : {}),
toolUseId: p.tool_use_id,
durationMs: p.tool_response?.totalDurationMs,
tokens: p.tool_response?.totalTokens,
toolUses: p.tool_response?.totalToolUseCount,
result: p.tool_response?.content
?.filter((c) => c.type === 'text' && c.text)
.map((c) => c.text)
.join('\n')
}
}
// A cron outlives turns and sessions — its card leaves the canvas only when the cron
// itself is removed.
if (ev === 'PreToolUse' && tool === 'CronDelete') {
return { ...base, kind: 'recurring', recurringKind: 'cron', recurringEnd: true }
}
if (ev === 'PreToolUse' && RECURRING_TOOLS.has(tool)) {
let recurringKind: NormalizedAgentEvent['recurringKind']
if (tool === 'Skill') {
const sk = (p.tool_input?.skill ?? '').split(':').pop()
if (sk === 'loop' || sk === 'schedule' || sk === 'cron') recurringKind = sk
} else if (tool === 'CronCreate') recurringKind = 'cron'
else if (tool === 'ScheduleWakeup') recurringKind = 'loop'
if (recurringKind) {
return {
...base,
kind: 'recurring',
recurringKind,
schedule: p.tool_input?.cron,
task: p.tool_input?.prompt
}
}
}
// A background shell task lives INSIDE the CLI process: /exit kills it silently. This event
// is the stamp Eco hibernation and the bulk restart exclude on (see hibernation-policy /
// planBulkRestart). PreToolUse only, and `=== true` — an absent or false flag is a foreground
// command, which the generic "working" below already covers. Claude-only: no other dialect
// carries the field (closed set, CLAUDE.md agent rule 7).
if (ev === 'PreToolUse' && tool === 'Bash' && p.tool_input?.run_in_background === true) {
return { ...base, kind: 'background-task' }
}
// Any other tool use is just "working".
return { ...base, kind: 'state', state: 'working' }
}
if (ev === 'UserPromptSubmit') {
// A completed async subagent is delivered back as a queued <task-notification> prompt (and,
// since the SubagentHandback tool, a `[Subagent hand-back]` message before it). Neither is a
// genuine user turn — flagging it newTurn would clear the subagent fan-out at the exact moment
// one of the cards completes.
if (isInjectedSubagentPrompt(p.prompt ?? '')) {
return { ...base, kind: 'state', state: 'working', ...turnIdOf(p.prompt_id) }
}
return { ...base, kind: 'state', state: 'working', task: p.prompt, newTurn: true, ...turnIdOf(p.prompt_id) }
}
if (ev === 'Stop') {
const backgroundTaskIds = liveBackgroundTaskIds(p.background_tasks)
const backgroundSubagentIds = liveBackgroundSubagentIds(p.background_tasks)
return {
...base,
kind: 'state',
state: 'done',
interrupted: p.is_interrupt === true,
lastMessage: p.last_assistant_message,
...(backgroundTaskIds ? { backgroundTaskIds } : {}),
...(backgroundSubagentIds ? { backgroundSubagentIds } : {})
}
}
// The turn died on an API/model error — Claude Code skips the normal Stop hook here,
// so without this the node would sit on "working" forever. `errored` is what keeps this
// distinguishable from an ordinary finish afterwards (issue #521): the station is idle either
// way, and before the flag existed a `--after` dependent fired on a station that produced
// nothing.
if (ev === 'StopFailure') {
return {
...base,
kind: 'state',
state: 'done',
errored: true,
lastMessage: p.last_assistant_message
}
}
// The dedicated permission hook (more direct than Notification's permission_prompt).
if (ev === 'PermissionRequest') {
return {
...base,
kind: 'state',
state: 'blocked',
...(tool && tool !== 'AskUserQuestion' ? { askKind: 'approval' as const } : {}),
lastMessage: p.last_assistant_message,
// Deterministic-approval ticket (present only when the wait-branch of the managed hook ran).
...(p.nodeterm_pending_id ? { pendingId: p.nodeterm_pending_id } : {}),
...(p.nodeterm_pending_id && isSafeToolName(tool) ? { held: heldOf(p.nodeterm_pending_id, tool, p) } : {})
}
}
if (ev === 'Notification') {
// Only the types that genuinely need the user flip the state. Everything else —
// idle_prompt fires AFTER Stop on a normally-finished turn (mapping it to waiting
// stuck NEEDS YOU on done nodes), and auth_success / elicitation_complete /
// elicitation_response / agent_completed are informational — must not touch state,
// so unknown future types default to no-op rather than a sticky badge.
if (p.notification_type === 'permission_prompt') {
return { ...base, kind: 'state', state: 'blocked', lastMessage: p.last_assistant_message }
}
if (p.notification_type === 'elicitation_dialog' || p.notification_type === 'agent_needs_input') {
return { ...base, kind: 'state', state: 'waiting', lastMessage: p.last_assistant_message }
}
// `idle_prompt` = the CLI is sitting at its prompt waiting for you to type. It cannot be true
// while a turn runs, which makes it the ONE signal that rescues a node stuck on `working` when
// no turn-end hook ever fired — the Esc-during-a-tool-call case, where Claude aborts the tool
// and returns to "Interrupted · What should Claude do instead?" without running Stop.
// MEASURED on 2.1.285: it does NOT follow an interrupted turn (it came 60 s after a normal Stop,
// and not in 80 s after an Esc). The interrupt is now ended from the transcript's marker
// instead (`recordTurnInterrupt`, core/agent-status-mirror.ts); this rescue stays for any CLI
// build that does send it.
//
// Marked `idle` (and `interrupted`, since nothing was accomplished) so consumers can apply the
// narrow rule this needs: it may only move a node that is still WORKING. It also fires after a
// normally-finished turn (already `done` → no-op) and can fire while an approval prompt is up
// (`blocked`/`waiting` → must NOT be cleared). Mapping it to `waiting` — the obvious reading —
// is what stuck NEEDS YOU on finished nodes before, hence the deliberate no-op default below.
if (p.notification_type === 'idle_prompt') {
return { ...base, kind: 'state', state: 'done', interrupted: true, idle: true }
}
return null
}
if (ev === 'SessionStart') return { ...base, kind: 'session', sessionPhase: 'start' }
if (ev === 'SessionEnd') return { ...base, kind: 'session', sessionPhase: 'end' }
return null
}
// Codex hook payload. Event name is read defensively; codex emits a session id under
// `session_id`. Tool events carry `tool_name`/`tool_input` (same shape as Claude's —
// codex-rs/hooks serializes them on pre_tool_use/post_tool_use).
interface CodexPayload {
hook_event_name?: string
hookEventName?: string
session_id?: string
prompt?: string
tool_name?: string
tool_input?: { prompt?: string; question?: string; questions?: { question?: string }[] }
// Subagent (spawn_agent collaboration) fields, measured on codex-cli 0.146.0:
// SubagentStart/SubagentStop carry agent_id + agent_type, and a CHILD's own tool events carry
// agent_id/agent_type too (the child runs inside the same codex process, so its hooks fire
// through the parent's subscription). SubagentStop adds last_assistant_message.
agent_id?: string
agent_type?: string
last_assistant_message?: string
}
export function normalizeCodex(env: RawHookEnvelope): NormalizedAgentEvent | null {
const p = env.payload as CodexPayload
const ev = p.hook_event_name ?? p.hookEventName
const base = { nodeId: env.nodeId, agentId: env.agentId, sessionId: p.session_id }
// Subagent fan-out (spawn_agent). Keyed by agent_id — the child's rollout/session uuid —
// NOT tool_use_id: the spawn tool's Pre/PostToolUse and the SubagentStart it launches carry
// different turn ids and nothing correlates them, while agent_id is stable across the child's
// whole life (measured: parallel + nested spawns each get a distinct agent_id, and a nested
// child's Start/Stop fire through the same subscription). No taskLabel: the spawn message is
// encrypted end-to-end (tool_input.message AND the NEW_TASK payload in the child rollout are
// Fernet blobs), so there is no task text to show — the live transcript tail carries the
// readable "Task name:" header instead.
if (ev === 'SubagentStart' && p.agent_id) {
return { ...base, kind: 'subagent-start', toolUseId: p.agent_id, subagentType: p.agent_type }
}
// The real end signal — codex fires SubagentStop when the child's turn completes, so unlike
// claude there is no async-launch-ack trap to dodge here. Duration/token counts are not in the
// payload; the card keeps its live-timer elapsed and the result text.
if (ev === 'SubagentStop' && p.agent_id) {
return { ...base, kind: 'subagent-end', toolUseId: p.agent_id, result: p.last_assistant_message }
}
// A CHILD's own tool events (tagged agent_id) must not drive the PARENT node's state: after an
// async spawn the parent's turn can end (Stop → done) while the child still runs, and a child
// Bash event mapping to 'working' would flip a finished node back to RUNNING with no later
// parent event to clear it. Child activity reaches the card via the rollout tail instead.
if (p.agent_id) return null
// UserPromptSubmit is codex's turn start — flag newTurn so the renderer clears
// per-turn fan-out once per turn, not on every tool event.
if (ev === 'UserPromptSubmit') {
return { ...base, kind: 'state', state: 'working', newTurn: true }
}
// `request_user_input` is Codex's ask-the-user tool, and it is NOT a blocking tool: the
// turn ENDS (Stop fires) with the question still unanswered, and the answer arrives as a
// fresh UserPromptSubmit. Mapping its tool-start to `working` left the node lit green as
// "done" while the agent sat on a question (observed live, codex-cli 0.145.0). Emit
// `waiting` + `awaitingInput` so reduceEntry can hold the ask through the turn-end Stop.
if (p.tool_name === 'request_user_input' && (ev === 'PreToolUse' || ev === 'PostToolUse')) {
// A PostToolUse for the ask itself (an immediate ack) must not clear the ask.
if (ev === 'PostToolUse') return null
const q = p.tool_input
const question = q?.questions?.[0]?.question ?? q?.question ?? q?.prompt
return {
...base,
kind: 'state',
state: 'waiting',
awaitingInput: true,
...(question ? { lastMessage: question } : {})
}
}
// SessionStart + tool events keep the node "working".
if (ev === 'SessionStart' || ev === 'PreToolUse' || ev === 'PostToolUse') {
return { ...base, kind: 'state', state: 'working' }
}
// Under codex's own auto-reviewer (`approvals_reviewer = "auto_review"`) nobody is asked; the
// hook server's codex permission gate (core/agents/codex-permission-gate.ts) reads the rollout
// and drops this event then. The payload alone cannot tell (measured: no reviewer field).
if (ev === 'PermissionRequest') return { ...base, kind: 'state', state: 'waiting' }
if (ev === 'Stop') return { ...base, kind: 'state', state: 'done' }
return null
}
// Gemini hook payload. Its envelope is snake_case and claude-shaped — every event carries
// `session_id`, `transcript_path`, `cwd`, `hook_event_name` and `timestamp` (gemini 0.54.4's own
// `docs/hooks/reference.md:48-58`). The event name is still read defensively (`hookEventName` /
// `event`) because older builds spelled it differently and those payloads cost nothing to accept.
interface GeminiPayload {
hook_event_name?: string
hookEventName?: string
event?: string
session_id?: string
/** Notification only (reference.md:272-285). The documented type is `"ToolPermission"`. */
notification_type?: string
/** Notification only: the alert's summary — shown on the needs-you badge (reference.md:279). */
message?: string
}
export function normalizeGemini(env: RawHookEnvelope): NormalizedAgentEvent | null {
const p = env.payload as GeminiPayload
const ev = p.hook_event_name ?? p.hookEventName ?? p.event
const base = { nodeId: env.nodeId, agentId: env.agentId, sessionId: p.session_id }
// BeforeAgent is gemini's turn start — flag newTurn (mirrors Claude's UserPromptSubmit)
// so per-turn fan-out clears once per turn rather than on every tool event.
if (ev === 'BeforeAgent') {
return { ...base, kind: 'state', state: 'working', newTurn: true }
}
if (ev === 'BeforeTool' || ev === 'AfterTool') {
return { ...base, kind: 'state', state: 'working' }
}
if (ev === 'AfterAgent') return { ...base, kind: 'state', state: 'done' }
// `source` is startup|resume|clear and `reason` is exit|clear|logout|prompt_input_exit|other
// (reference.md:250-251, 265-266). Neither changes what a session boundary MEANS to us, so both
// phases map unconditionally — a `/clear` really is one session ending and another beginning.
if (ev === 'SessionStart') return { ...base, kind: 'session', sessionPhase: 'start' }
if (ev === 'SessionEnd') return { ...base, kind: 'session', sessionPhase: 'end' }
if (ev === 'Notification') {
// Gemini's ONE ask-the-user signal (reference.md:272-285, "for example, Tool Permissions"), and
// the reason this event was worth subscribing to: without it a node waiting on a permission
// answer sat on RUNNING, because the last hook we heard was `BeforeTool`.
//
// `blocked` rather than `waiting` for two reasons: normalizeClaude already uses it for a
// permission ask (every consumer treats the two alike), and BUSY_STATES then refuses an
// in-place restart on this node — correct, since `/quit` typed into a permission prompt would
// ANSWER the prompt instead of quitting. That refusal only became REACHABLE for gemini once
// gemini joined `EXIT_SEQUENCES` (agent-restart.ts): `restartEligibility` returns
// `not-resumable` before it ever consults BUSY_STATES, so until then no gemini node could be
// restarted at all, blocked or otherwise.
//
// A CLOSED match, not a substring: the docs name exactly ONE type (reference.md:278), and an
// unknown future one must stay a no-op — a badge that sticks on a finished node is a failure
// this codebase has shipped before. Grok is the cautionary tale: there, a substring match on
// "permission" turned a notification that fires before every tool call into a strobing NEEDS
// YOU. Widening this "to be safe" is the unsafe direction.
//
// Nothing here can be answered from our side: the hook is observability only and its
// flow-control fields are ignored (reference.md:284-285), so this reports state and no more —
// no `pendingId`, unlike claude's deterministic-approval path.
if (p.notification_type === 'ToolPermission') {
return { ...base, kind: 'state', state: 'blocked', lastMessage: p.message }
}
return null
}
return null
}
// GitHub Copilot CLI hook payload. Its event names and snake_case envelope intentionally resemble
// Claude's, but its event set and notification vocabulary are a separate protocol contract. Keep a
// dedicated normalizer so a future change in one harness cannot silently change the other's state.
interface CopilotPayload {
hook_event_name?: string
session_id?: string
prompt?: string
notification_type?: string
message?: string
last_assistant_message?: string
}
export function normalizeCopilot(env: RawHookEnvelope): NormalizedAgentEvent | null {
const p = env.payload as CopilotPayload
const base = { nodeId: env.nodeId, agentId: env.agentId, sessionId: p.session_id }
if (p.hook_event_name === 'SessionStart') {
return { ...base, kind: 'session', sessionPhase: 'start' }
}
if (p.hook_event_name === 'SessionEnd') {
return { ...base, kind: 'session', sessionPhase: 'end' }
}
if (p.hook_event_name === 'UserPromptSubmit') {
return { ...base, kind: 'state', state: 'working', task: p.prompt, newTurn: true }
}
if (
p.hook_event_name === 'PreToolUse' ||
p.hook_event_name === 'PostToolUse' ||
p.hook_event_name === 'PostToolUseFailure'
) {
return { ...base, kind: 'state', state: 'working' }
}
if (p.hook_event_name === 'Stop') {
return {
...base,
kind: 'state',
state: 'done',
lastMessage: p.last_assistant_message
}
}
if (p.hook_event_name === 'Notification') {
// Closed matches only. Informational/background notification types must never create a sticky
// NEEDS YOU badge on a finished parent session.
if (p.notification_type === 'permission_prompt') {
return { ...base, kind: 'state', state: 'blocked', lastMessage: p.message }
}
if (p.notification_type === 'elicitation_dialog') {
return { ...base, kind: 'state', state: 'waiting', lastMessage: p.message }
}
}
return null
}
// opencode plugin payload (see core/agents/hooks/opencode.ts). The managed plugin forwards
// { event, sessionID?, role? } per hook; field names beyond `event` are read defensively —
// opencode's event payload shapes are not a contract, so the event NAME carries the mapping.
interface OpencodePayload {
event?: string
sessionID?: string
session_id?: string
role?: string
}
export function normalizeOpencode(env: RawHookEnvelope): NormalizedAgentEvent | null {
const p = env.payload as OpencodePayload
const base = { nodeId: env.nodeId, agentId: env.agentId, sessionId: p.sessionID ?? p.session_id }
if (p.event === 'session.created') return { ...base, kind: 'session', sessionPhase: 'start' }
// The plugin forwards message.updated only for user messages — opencode's turn start
// (mirrors Claude's UserPromptSubmit), so per-turn fan-out clears once per turn.
if (p.event === 'message.updated' && p.role === 'user') {
return { ...base, kind: 'state', state: 'working', newTurn: true }
}
if (p.event === 'tool.execute.before') return { ...base, kind: 'state', state: 'working' }
if (p.event === 'permission.asked') return { ...base, kind: 'state', state: 'blocked' }
if (p.event === 'permission.replied') return { ...base, kind: 'state', state: 'working' }
// Question (elicitation) dialog: blocks the turn but the session never idles.
if (p.event === 'question.asked') return { ...base, kind: 'state', state: 'blocked' }
if (p.event === 'question.replied' || p.event === 'question.rejected') {
return { ...base, kind: 'state', state: 'working' }
}
if (p.event === 'session.idle' || p.event === 'session.error') {
return { ...base, kind: 'state', state: 'done' }
}
return null
}
// grok hook payload. Its dialect differs from every other agent here in two ways, both taken from
// the shipped 1.0.0 DOCS: the keys are camelCase, and `hookEventName`'s VALUE is snake_case
// ("pre_tool_use"). NO payload here was ever captured — a hook only fires inside a logged-in grok
// session, and the branch never had one. Hooks registered through the grok SDK convert the top-level keys to
// snake_case instead, so both spellings occur in the wild — hence every field is read twice and
// the event name is CANONICALIZED (lowercased, letters only) rather than compared literally.
// `transcript_path` is deliberately absent from THIS envelope -- but not from the wire. Grok does
// send `transcriptPath` (MEASURED on 1.0.13, 14 of 15 payloads) and it names `updates.jsonl`, the
// file that holds no readable conversation. The transcript is DERIVED from (cwd, sessionId)
// instead, which is why the shells' raw listeners need `grokRawFields` below.
interface GrokPayload {
hookEventName?: string
hook_event_name?: string
sessionId?: string
session_id?: string
cwd?: string
toolName?: string
tool_name?: string
toolUseId?: string
tool_use_id?: string
toolInput?: Record<string, unknown>
tool_input?: Record<string, unknown>
/** SubagentStart/SubagentStop only. MEASURED (1.0.13, two parallel `explore` children): a
* per-INSTANCE id, and the only id both events share — see `grokRawFields`. The snake spelling is
* read alongside the camel one for the same reason every other field here is: grok emits both
* dialects in the same payload, and the SDK path may present only one. */
subagentId?: string
subagent_id?: string
subagentType?: string
subagent_type?: string
/** SubagentStart only: the human task text ("Read a.txt contents"). Absent on the stop. */
description?: string
lastAssistantMessage?: string
last_assistant_message?: string
notificationType?: string
notification_type?: string
/** Notification only, THIRD spelling of the kind. Not from grok's docs — from orca
* (`/root/orca-main`, MIT), a shipping grok integration whose reader is
* `notificationType ?? notification_type ?? type` (`src/shared/agent-hook-listener.ts:2370-2376`).
* Reading a key a shipped integration reads costs nothing and closes a whole dialect. */
type?: string
/** Stop only: 'end_turn' for a genuine turn end; 'channel_closed'/'shutdown' at session close. */
reason?: string
/** StopFailure only: the closed error class tested by its matcher. */
error?: string
/** PreCompact/PostCompact only: `manual` or `auto`. MEASURED on grok 1.0.13 (2026-09-01): the
* wire spells this `source`; `trigger` is Claude's spelling and never appears in a grok payload.
* Both are read because the SDK path may still present the Claude-shaped key, and reading a key
* that never arrives costs nothing — while reading only `trigger` cost us every compaction
* event: the guard below rejected 100% of real ones while the docs-derived test payloads,
* which carried `trigger`, kept it green. */
source?: string
trigger?: string
prompt?: string
}
/**
* ONE canonicalization for every grok VALUE we compare — lowercase, letters only, so all of
* 'pre_tool_use', 'PreToolUse', 'preToolUse' and 'Pre-Tool-Use' land on 'pretooluse'. grok's envelope
* is documented camelCase while its event values are snake_case, and the SDK path flips the keys, so
* one dialect rule shared by every comparison in this file is the point: a second spelling rule is
* how a value gets normalized in one branch and matched raw in another.
*/
const grokCanonical = (v: string | undefined): string => (v ?? '').toLowerCase().replace(/[^a-z]/g, '')
const GROK_CANCEL_REASONS: Record<string, NonNullable<NormalizedAgentEvent['cancelReason']>> = {
userinterrupt: 'user_interrupt',
permissionrejected: 'permission_rejected',
permissioncancelled: 'permission_cancelled',
maxturns: 'max_turns',
noprogress: 'no_progress',
unknown: 'unknown'
}
/** Canonical form of a grok event name: 'pre_tool_use', 'PreToolUse' and 'preToolUse' all → 'pretooluse'. */
const grokEventName = (p: GrokPayload): string =>
grokCanonical(p.hookEventName ?? p.hook_event_name)
/**
* The fields the SHELLS need from a raw grok payload, in nodeterm's own names — one definition
* shared by `src/main` and `src/server` so their raw listeners can never drift. Exported (and
* unit-tested) rather than re-read at each call site, because the two-dialect reading is exactly
* the kind of detail that gets half-copied.
*/
export function grokRawFields(payload: Record<string, unknown>): {
event: string
sessionId?: string
cwd?: string
toolName?: string
toolUseId?: string
toolInput?: Record<string, unknown>
subagentId?: string
subagentType?: string
description?: string
} {
const p = payload as GrokPayload
return {
event: grokEventName(p),
sessionId: p.sessionId ?? p.session_id,
cwd: p.cwd,
toolName: p.toolName ?? p.tool_name,
toolUseId: p.toolUseId ?? p.tool_use_id,
toolInput: p.toolInput ?? p.tool_input,
// MEASURED on 1.0.13 (2026-09-02) by running two `explore` subagents in parallel:
//
// - `subagentId` is a per-INSTANCE id. The two children of the same TYPE came back with
// different ids, so grok keys like codex's `agent_id` and not, as was assumed, by type
// alone — nothing has to be aggregated.
// - It is also the ONLY id common to both events. On `SubagentStart` the `sessionId` is the
// PARENT's (the hook runs in the parent); on `SubagentStop` it is the CHILD's own, equal to
// `subagentId`. Keying on `sessionId` would file the start and the stop under different
// cards, and the started one would never close: a badge lit forever, with no error.
// - `description` arrives ONLY on the start ("Read a.txt contents"); on the stop it is
// absent, so a title resolved at close time has nothing to read.
subagentId: p.subagentId ?? p.subagent_id,
subagentType: p.subagentType ?? p.subagent_type,
description: p.description
}
}
export function normalizeGrok(env: RawHookEnvelope): NormalizedAgentEvent | null {
const p = env.payload as GrokPayload
const base = { nodeId: env.nodeId, agentId: env.agentId, sessionId: p.sessionId ?? p.session_id }
const ev = grokEventName(p)
const lastMessage = p.lastAssistantMessage ?? p.last_assistant_message
if (ev === 'sessionstart') return { ...base, kind: 'session', sessionPhase: 'start' }
if (ev === 'sessionend') return { ...base, kind: 'session', sessionPhase: 'end' }
// grok's turn start. Flagged newTurn so per-turn fan-out clears once per turn, not per tool event.
if (ev === 'userpromptsubmit') {
return { ...base, kind: 'state', state: 'working', task: p.prompt, newTurn: true }
}
// A FAILED tool is still mid-turn: grok fires PostToolUseFailure and carries on, so mapping it
// to anything but `working` would clear RUNNING while the agent is still going.
if (ev === 'pretooluse' || ev === 'posttooluse' || ev === 'posttoolusefailure') {
return { ...base, kind: 'state', state: 'working' }
}
if (ev === 'stop') {
// grok fires a SECOND, observe-only Stop when the session itself closes — and ONLY those two
// reasons, 'channel_closed' and 'shutdown', are that fire. Reporting them as a finished turn
// would pop a "your agent is done" notification every time a session ends, so they are marked
// `interrupted` — the flag the renderer already reads as "skip the completion alert and the
// unread dot" — and their lastAssistantMessage (an earlier turn's text) is dropped.
//
// The test is a DENYLIST of those two, not an allowlist of 'end_turn', so everything else —
// an absent reason, or a genuine turn end grok labels later ('max_tokens', 'refusal', …) —
// reports normally. Stop is the one event the RUNNING badge depends on ending, so an unknown
// dialect must fail towards reporting the badge-clearing event, never towards swallowing it.
const sessionClose = p.reason === 'channel_closed' || p.reason === 'shutdown'
return !sessionClose
? { ...base, kind: 'state', state: 'done', lastMessage }
: { ...base, kind: 'state', state: 'done', interrupted: true }
}
// The turn died on an API error — grok skips Stop entirely here, exactly as Claude does.
//
// THE EVENT IS THE TURN END, whatever its error class. This used to return null for a class
// outside the documented six, on the "closed vocabulary" reasoning applied everywhere else in this
// file. That reasoning is right for a value that DECIDES something and wrong here, because the
// class decides nothing: every branch of it ends the turn. Gating on it meant an absent or
// future-dialect `error` left the node stuck on RUNNING until the idle_prompt backstop, or forever
// if none came — the silent half of the failure, the one nobody reports because nothing looks
// broken. Grok's own docs make `unknown` the catch-all, so a value outside the set can only be a
// dialect we have not seen, and the turn has ended either way.
//
// The documented classes (1.0.13, `10-hooks.md:162`) are `rate_limit`, `authentication_failed`,
// `invalid_request`, `server_error`, `max_output_tokens` and `unknown` — recorded here because
// they are measured and worth keeping, and NOT kept as a Set, because nothing branches on them and
// a set nothing reads is the same dead weight the PostCompact branch was. The day one of them
// earns a distinct badge, that is where the set comes back — and it must still fall through to
// `done`, never to null.
// `errored: true` is NOT decoration: `erroredTurn.ts` is the one definition of "this turn died",
// shared by every agent and by both shells, and dropping it here made grok the only agent whose
// failed turn looked like a clean one. It went missing when this branch's version of the return
// was taken over upstream's without diffing what upstream had — the same "believe the side you
// are holding" that the rest of this comment is about.
if (ev === 'stopfailure')
return { ...base, kind: 'state', state: 'done', errored: true, lastMessage }
if (ev === 'permissiondenied') return { ...base, kind: 'state', state: 'working' }
if (ev === 'stopcancelled') {
const cancelReason = GROK_CANCEL_REASONS[grokCanonical(p.reason)]
if (!cancelReason) return null
// Transport the classified reason state-less: the mirror owns the session-aware transition
// and can ignore a subagent cancellation without losing session identity.
return {
...base,
kind: 'state',
cancelReason,
subagentType: p.subagentType ?? p.subagent_type,
lastMessage
}
}
// Subagent cards. MEASURED (1.0.13, two parallel `explore` children — the capture is
// `__fixtures__/grok/hook-payloads.json`, pinned by `normalize.grok.capture.test.ts`):
// subagent_start sessionId = the PARENT's, subagentId per INSTANCE, subagentType, description
// subagent_stop sessionId = the CHILD's own (identical to its subagentId), lastAssistantMessage
// Two children of the SAME type carried different `subagentId`s, which is why the card is keyed on
// that and not on the type — one card per instance. `toolUseId` is the field the card store keys
// on for every agent (claude correlates by tool_use_id, codex by agent_id); grok has no tool call
// behind a subagent at all, so its per-instance id goes in the same slot rather than adding a
// fourth spelling to `NormalizedAgentEvent`.
//
// The stop's `sessionId` being the CHILD's is the trap here: `base.sessionId` would re-point the
// node's session to the child, so both events are answered with the id the CARD needs and the
// session left alone — the parent's own Stop is what owns that.
if ((ev === 'subagentstart' || ev === 'subagentstop') && (p.subagentId ?? p.subagent_id)) {
const subagentId = p.subagentId ?? p.subagent_id
const subagentType = p.subagentType ?? p.subagent_type
if (ev === 'subagentstart') {
return {
nodeId: env.nodeId,
agentId: env.agentId,
kind: 'subagent-start',
toolUseId: subagentId,
subagentType,
task: p.description
}
}
return {
nodeId: env.nodeId,
agentId: env.agentId,
kind: 'subagent-end',
toolUseId: subagentId,
subagentType,
result: lastMessage
}
}
if (ev === 'precompact' || ev === 'postcompact') {
const trigger = grokCanonical(p.source ?? p.trigger)
if (trigger !== 'manual' && trigger !== 'auto') return null
return {
...base,
kind: 'state',
compactionPhase: ev === 'precompact' ? 'pre' : 'post'
}
}
if (ev === 'notification') {
// Grok 1.0.13 publishes this CLOSED vocabulary in
// `~/.grok/docs/user-guide/10-hooks.md:99`: idle_prompt, permission_prompt, task_complete.
// `:162` is the load-bearing correction to the old orca-derived branch: permission_prompt fires
// ONLY while a permission UI is actually waiting, never routinely before every tool call.
// Exact classification prevents a future permission-like name from sticking NEEDS YOU with no
// later hook guaranteed to clear it.
const type = p.notificationType ?? p.notification_type ?? p.type
// NO ROUTINE-PROMPT SUPPRESSION HERE, and that is a measured decision rather than an omission.
//
// The old orca-derived branch dropped a `permission_prompt` whose message was exactly
// "Tool permission requested" at level `info`, because orca reports grok emitting one before
// EVERY tool call. Captured live on 1.0.13 (2026-09-01), the GENUINE prompt — fired with a real
// permission dialog on screen — is byte-for-byte that same triple:
// notificationType 'permission_prompt' · message 'Tool permission requested' · level 'info'
// and no routine per-tool-call notification was emitted at all. So that filter cannot separate
// the routine case from a real ask on this version: it can only swallow the real one.
//
// Swallowing it is the worse of the two failures. A strobe is loud and obvious; a suppressed ask
// leaves grok waiting for approval with the node showing nothing, and no later hook is
// guaranteed to correct it. If a future grok does emit the routine prompt, it must be told apart
// by something that actually differs — not by a message the real ask also carries.
// What this cannot see is the ANSWER: grok fires no hook when the dialog is approved (until the
// tool finishes) or dismissed (never). The hook server's grok permission gate
// (core/agents/grok-permission-gate.ts) confirms this `blocked` against grok's events.jsonl and
// clears it from there — this function stays a pure mapping of the hook.
if (type === 'permission_prompt') {
return { ...base, kind: 'state', state: 'blocked', lastMessage }
}
if (type === 'idle_prompt') {
return { ...base, kind: 'state', state: 'done', interrupted: true, idle: true }
}
// The spec names task_complete as a user-attention notification, but never says it ends a turn.
// Stop remains the documented turn-end signal, so task_complete and every future type are
// informational no-ops rather than guessed badge transitions.
return null
}
return null
}
// Antigravity CLI (`agy`) hook payload — camelCase, as its protojson writer emits it. Measured on
// agy 1.2.3 (fixture: __fixtures__/antigravity/hook-payloads.json).
//
// THE EVENT NAME IS NOT IN THE PAYLOAD. None of the five events carries it, and PreInvocation and
// PostInvocation are indistinguishable by their keys. The managed hook command exports it as
// NODETERM_AGY_EVENT and the script POSTs it as the `nodeterm_hook_event` form field, which the hook
// server merges into this object AFTER parsing the agent's JSON — so a value planted inside the
// agent's payload never wins.
interface AntigravityPayload {
nodeterm_hook_event?: unknown
conversationId?: unknown
fullyIdle?: unknown
terminationReason?: unknown
invocationNum?: unknown
toolCall?: { name?: unknown } | null
}
/**
* The tool names that put a human in the loop, matched EXACTLY (rule 7: a closed set, never a
* substring). `ask_question` is the only one: `agy`'s own step-type enum (`CORTEX_STEP_TYPE_*`,
* read out of the 1.2.3 binary) has ASK_QUESTION and no ASK_PERMISSION, so there is no
* `ask_permission` tool to match.
*
* What this CANNOT see, and nobody should try to guess: `agy`'s own permission prompt ("Run this
* command?") fires NO hook. A session parked on it looks exactly like a slow tool.
*/
const ANTIGRAVITY_ASK_TOOLS = new Set(['ask_question'])
const antigravityToolName = (p: AntigravityPayload): string | undefined => {
const name = p.toolCall && typeof p.toolCall === 'object' ? p.toolCall.name : undefined
return typeof name === 'string' ? name : undefined
}
/**
* PURE — no state, on purpose. Four decisions carry the whole mapping:
*
* 1. `Stop` always ends the turn (`state: 'done'`), matching Claude Code and every other CLI.
* `agy` sets `fullyIdle === false` whenever ANY background command (`WaitMsBeforeAsync`,
* `IsDaemon: true`, timer or subagent) is still alive after the turn ends and the `>` prompt
* returns to the user. Keeping `state: 'working'` left the card stuck on `RUNNING` and blocked
* `send` delivery for the life of any background process. Instead, `fullyIdle === false` stamps
* `backgroundTaskIds` (just like Claude's `Stop` with a live `Bash(run_in_background: true)`) so
* Eco hibernation and bulk restart do not kill the CLI while a background process runs; when a
* background task finishes and wakes the agent, `agy` fires a new `PreInvocation` (`invocationNum: 0`)
* which transitions back to `working` (`newTurn: true`).
*
* 2. NEEDS YOU is bracketed by the ask tool itself, never by adjacency. `PreToolUse` and
* `PostToolUse` do not alternate: a whole invocation can open and close between them (measured:
* 63 s between the pair while a question sat on screen), and a BACKGROUND tool's `PostToolUse`
* can land in the middle of a pending question. So only the ask tool's own `PostToolUse` clears
* the question (→ `working`); every other tool's `PostToolUse` says nothing we did not already
* know and maps to null, which keeps a finished background ping from wiping a live NEEDS YOU.
* Correlating on `stepIdx` exactly would need state across events; naming the tool gives the
* same answer for the one open question `agy` can have, without it.
*
* 3. `errored` is set only for `terminationReason === 'ERROR'`, UPPER_SNAKE — the real enum
* (12 values, read from the binary; the bundled docs' lowercase example is wrong). It keeps an
* `--after` dependent from launching on a broken turn (#521). NOT produced on a device yet: see
* docs/antigravity-agent.md. `MAX_*`, `USER_CANCELED` and the rest are unhappy ends, not API
* errors, and calling them errors would be a guess.
*
* 4. `newTurn` ONLY on the `PreInvocation` whose `invocationNum === 0`. `PreInvocation` fires per
* MODEL CALL, so flagging every one would be wrong; but agy numbers the calls of one execution
* from 0, and the measurement shows a 0 at the start of every execution — including the one that
* resumes after a background tool finished (log-bg.jsonl: 0, 1, then 0 again). A turn boundary
* IS load-bearing here: `lastTurnError` (#521) is retired only by `newTurn`, so without it one
* errored turn would hold every `--after` dependent QUEUED for the rest of the app run; and the
* done-holdoff drops a non-newTurn `working` that follows a `done` by < 3 s, which is exactly a
* quick follow-up prompt. Strict `=== 0`: a missing or non-numeric value marks nothing. The
* other effects of `newTurn` (fan-out clears, the prompt line) have nothing to act on for agy —
* it emits no subagent events and no prompt text.
*/
export function normalizeAntigravity(env: RawHookEnvelope): NormalizedAgentEvent | null {
const p = env.payload as AntigravityPayload
const ev = typeof p.nodeterm_hook_event === 'string' ? p.nodeterm_hook_event : undefined
const sessionId = typeof p.conversationId === 'string' ? p.conversationId : undefined
const base = { nodeId: env.nodeId, agentId: env.agentId, sessionId }
if (ev === 'PreInvocation') {
return { ...base, kind: 'state', state: 'working', ...(p.invocationNum === 0 ? { newTurn: true } : {}) }
}
if (ev === 'PreToolUse') {
const tool = antigravityToolName(p)
const asks = tool !== undefined && ANTIGRAVITY_ASK_TOOLS.has(tool)
return { ...base, kind: 'state', state: asks ? 'waiting' : 'working' }
}
if (ev === 'PostToolUse') {
const tool = antigravityToolName(p)
if (tool !== undefined && ANTIGRAVITY_ASK_TOOLS.has(tool)) {
return { ...base, kind: 'state', state: 'working' }
}
return null
}
if (ev === 'Stop') {
return {
...base,
kind: 'state',
state: 'done',
...(p.terminationReason === 'ERROR' ? { errored: true } : {}),
...(p.fullyIdle === false ? { backgroundTaskIds: ['agy-bg'] } : {})
}
}
return null
}
// Cursor Agent CLI payload. Every event carries the same envelope, MEASURED on cursor-agent
// 2026.09.28 (src/shared/agents/__fixtures__/cursor/hook-payloads.json): `conversation_id` (the
// chat id `cursor-agent --resume <id>` takes, verified), `session_id` (equal to it in every
// capture), `generation_id`, `model`, `hook_event_name` (camelCase, the ONLY spelling), `cursor_version`,
// `workspace_roots`, `user_email` and `transcript_path` (null until the first turn is written).
// `cwd` exists on tool events only and was "" for Shell, so nothing here reads it.
// `parent_tool_call_id` is the bundle's marker for a tool call made inside a subagent
// (hooks_pb PreToolUseRequestQuery field 10); never seen on the wire, see isCursorChildToolEvent.
// `status` on `stop`: `completed` was captured in the interactive TUI (subagent-payloads.json);
// `aborted` and `error` are from the bundle/docs, never captured.
interface CursorPayload {
hook_event_name?: unknown
conversation_id?: unknown
session_id?: unknown
generation_id?: unknown
parent_tool_call_id?: unknown
status?: unknown
is_background_agent?: unknown
tool_name?: unknown
tool_use_id?: unknown
tool_input?: unknown
}
/**
* A cursor tool event made INSIDE a subagent. MEASURED on 2026.10.01 (interactive TUI, three
* subagent runs, `__fixtures__/cursor/subagent-payloads.json`): a child's tool events carry the
* CHILD's own chat id as `conversation_id` AND as `generation_id`, and no `parent_tool_call_id`.
* A parent tool event carries its TURN's generation id, never the chat id (only `sessionStart`,
* which is no tool event, has the two equal). `parent_tool_call_id` stays as the bundle's marker.
* Wrong-guess cost: a parent tool event read as a child's is dropped; the badge still runs from
* `beforeSubmitPrompt` and `stop`.
*/
export function isCursorChildToolEvent(payload: unknown): boolean {
const p = (payload ?? {}) as CursorPayload
if (typeof p.parent_tool_call_id === 'string' && p.parent_tool_call_id) return true
return typeof p.conversation_id === 'string' && !!p.conversation_id && p.generation_id === p.conversation_id
}
/** A background agent's own lifecycle event (`is_background_agent: true`): never the node's. The
* normalizer, the subagent tracker and the raw step all drop it with this one test. */
export function isCursorBackgroundEvent(payload: unknown): boolean {
return ((payload ?? {}) as CursorPayload).is_background_agent === true
}
/**
* A payload Cursor sent, whichever hook ran it. Cursor also runs nodeterm's `claude.sh` (Claude
* settings import, docs/cursor-agent.md §5), so the claude raw listener sees Cursor's envelope too,
* often a CHILD's. A real Claude payload carries neither key.
*/
export function isCursorPayload(payload: unknown): boolean {
const p = (payload ?? {}) as Record<string, unknown>
return p.cursor_version !== undefined || p.conversation_id !== undefined
}
/**
* PURE. The event name is matched as a closed set of exact strings (rule 7); everything else,
* including the ~16 events we do not subscribe, is null.
*
* - `beforeSubmitPrompt` → `working` + `newTurn` (`newTurn` retires `lastTurnError`, #521).
* - `preToolUse` / `postToolUse` / `postToolUseFailure` → `working`. A subagent's tool call
* (`isCursorChildToolEvent`) returns null: its `conversation_id` IS the child's (measured), and
* child activity must not drive the parent or replace its recorded session id.
* - the parent's `preToolUse` for tool `Task` → `subagent-start`, keyed by `tool_use_id`.
* - `stop` → `done`; `interrupted` only for status `aborted`, `errored` only for `error`. Any
* other status is a plain `done`, because `stop` ends the turn whatever it says.
*
* - `sessionEnd` → `session` phase `end` (SESSION_END_CAPABLE), unless `is_background_agent`.
*
* NEEDS YOU is deliberately absent HERE: the AskQuestion tool fires no tool hook and Cursor's own
* approval prompt has none either (docs/cursor-agent.md §4). The hook server adds a `blocked` from
* up to three pane reads of a still-pending tool call, and a `waiting` from the same reads of a quiet
* turn that ends on the AskQuestion box, instead (core/agents/cursor-approval.ts).
*
* `sessionId` is `conversation_id`, falling back to `session_id`: the resume feature keys on it.
*/
export function normalizeCursor(env: RawHookEnvelope): NormalizedAgentEvent | null {
const p = env.payload as CursorPayload
const ev = typeof p.hook_event_name === 'string' ? p.hook_event_name : undefined
const sessionId =
typeof p.conversation_id === 'string' && p.conversation_id
? p.conversation_id
: typeof p.session_id === 'string' && p.session_id
? p.session_id
: undefined
const base = { nodeId: env.nodeId, agentId: env.agentId, sessionId }
if (ev === 'beforeSubmitPrompt') return { ...base, kind: 'state', state: 'working', newTurn: true }
if (ev === 'preToolUse' || ev === 'postToolUse' || ev === 'postToolUseFailure') {
if (isCursorChildToolEvent(p)) return null
// The card's start. `subagentStart`/`subagentStop` never fired (three measured runs) and the
// parent's `Task` gets a preToolUse but NO postToolUse, so the end is the parent's `stop`,
// emitted by core/cursor-subagents.ts.
if (ev === 'preToolUse' && p.tool_name === 'Task' && typeof p.tool_use_id === 'string' && p.tool_use_id) {
const input = (p.tool_input ?? {}) as { subagent_type?: unknown; description?: unknown; prompt?: unknown }
const str = (v: unknown): string | undefined => (typeof v === 'string' && v ? v : undefined)
return {
...base,
kind: 'subagent-start',
toolUseId: p.tool_use_id,
subagentType: str(input.subagent_type),
taskLabel: str(input.description) ?? str(input.prompt)
}
}
return { ...base, kind: 'state', state: 'working' }
}
if (ev === 'stop') {
return {
...base,
kind: 'state',
state: 'done',
...(p.status === 'aborted' ? { interrupted: true } : {}),
...(p.status === 'error' ? { errored: true } : {})
}
}
// Orderly `/quit` (measured: reason "completed"). A background agent's own end is not this node's.
if (ev === 'sessionEnd') {
if (isCursorBackgroundEvent(p)) return null
return { ...base, kind: 'session', sessionPhase: 'end' }
}
return null
}
export function normalizeFor(agentId: AgentId, env: RawHookEnvelope): NormalizedAgentEvent | null {
if (agentId === 'claude') return normalizeClaude(env)
if (agentId === 'codex') return normalizeCodex(env)
if (agentId === 'gemini') return normalizeGemini(env)
if (agentId === 'opencode') return normalizeOpencode(env)
if (agentId === 'grok') return normalizeGrok(env)
if (agentId === 'copilot') return normalizeCopilot(env)
if (agentId === 'antigravity') return normalizeAntigravity(env)
if (agentId === 'cursor') return normalizeCursor(env)
return null
}