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
// The hook events each agent's managed installer subscribes to — ONE list per agent, shared by
// every installer (local desktop, Server Edition, and the SSH remote installer).
//
// They used to be declared twice, and the copies had drifted: the remote installer subscribed
// claude to `SessionStart`/`SubagentStop` but NOT to `StopFailure`/`PermissionRequest` (so a
// remote agent's errored turn stuck on "working" and its permission prompts arrived late), and it
// subscribed gemini to CLAUDE's event names, which gemini never fires — remote gemini nodes
// reported no status at all.
//
// The drift also produced a broken settings.json on any machine where two installers ran: each
// rewrites only the events IT knows, so a stale instance's command survived on every event the
// other list lacked. Keeping the lists here is what makes an install a complete rewrite.
/**
* One managed hook subscription: an event name, or an event name PLUS the matcher to write for it.
* Only grok needs the second form — its tool-event `matcher` is a real REGEX
* (`~/.grok/docs/user-guide/10-hooks.md:153`), so a bare `*` is not a valid match-all but an invalid
* pattern, and the expected failure is silence: the tool events simply never fire. We write `.*`.
* claude/codex/gemini stay plain strings, so their emitted config is byte-identical to what it has
* always been.
*/
export type ManagedHookEvent = string | { event: string; matcher?: string; timeout?: number }
/** A subscription's event name, whichever form it was declared in. */
export function managedEventName(e: ManagedHookEvent): string {
return typeof e === 'string' ? e : e.event
}
/**
* The `timeout` (seconds) we write on claude's PermissionRequest handler. Claude's command-hook
* default is 600 s today, but a held plan/question waits up to `PERM_WAIT_SECS_INTERACTIVE` (540 s,
* core/agents/permission-decision.ts) — so the bound the hold is sized against is written down in
* the user's settings instead of borrowed from a CLI default that could change under us. Existing
* installs pick it up at the next install (the managed entry is always rewritten fresh).
*/
export const PERMISSION_REQUEST_HOOK_TIMEOUT_SECS = 600
/** Claude Code hook events. Each maps to a `NormalizedAgentEvent` in shared/agents/normalize.ts. */
export const CLAUDE_HOOK_EVENTS = [
'SessionStart',
'UserPromptSubmit',
'Stop',
// Fires INSTEAD of Stop when the turn ends on an API/model error — without it the
// status badge sticks on "working" after any errored turn.
'StopFailure',
'Notification',
// Dedicated permission-prompt signal (→ blocked), more direct than Notification. Carries an
// explicit timeout because the managed hook HOLDS it (hook-reply approvals, up to 540 s).
{ event: 'PermissionRequest', timeout: PERMISSION_REQUEST_HOOK_TIMEOUT_SECS },
'SessionEnd',
'PreToolUse',
'PostToolUse',
// Claude's own subagent lifecycle (since 2.0.43), keyed by the child's agent_id — the authority
// for subagent cards whenever a session sends it (core/claude-subagent-lifecycle.ts). The
// PreToolUse/PostToolUse pair above stays: it is the fallback for a CLI or hook snapshot without
// these, and the source of the task label. Both are no-ops for the CLI: the managed script prints
// nothing (SubagentStart stdout would be added to the child's context) and exits 0 (a
// SubagentStop decision could block the child from stopping).
'SubagentStart',
'SubagentStop'
] as const satisfies readonly ManagedHookEvent[]
/**
* Gemini CLI hook events (→ normalizeGemini) — its own names, NOT Claude's.
*
* Gemini publishes ELEVEN events; these are the seven we can act on. The four left out are
* deliberate, all per gemini 0.54.4's bundled `docs/hooks/reference.md`:
* - `AfterModel` fires for EVERY streamed chunk (reference.md:236-237, "Fired for every chunk
* generated by the model"; its `fireAfterModelEvent(request, chunk)` runs inside the chunk
* loop), so subscribing would spawn a hook process per chunk. It is also the one that carries
* `llm_response.usageMetadata.totalTokenCount` — the one number worth having — which is why the
* gemini context meter reads the TRANSCRIPT instead of subscribing here (`core/gemini-session.ts`
* `geminiContextParse`, fed by the same tail claude's meter uses). Do not "just add AfterModel"
* to get the tokens: the meter already has them, and this event would cost a process per chunk.
* - `BeforeModel` is NOT per-chunk — it fires once per model request (reference.md:187-190,
* "Fires before sending a request to the LLM"). It is left out for the plain reason the two
* below are: it reports nothing we render. A turn's start is already `BeforeAgent`, and a
* second working→working event per request would only add hook processes.
* - `BeforeToolSelection` (reference.md:204-219) and `PreCompress` (reference.md:287-297) have
* no state we render today.
*
* `Notification` is the important addition: it is gemini's ONLY signal that the user is being
* asked something (`notification_type: "ToolPermission"`, reference.md:272-285). Without it a
* gemini node sat on RUNNING while it waited for a permission answer, because the last event we
* heard was `BeforeTool`.
*/
export const GEMINI_HOOK_EVENTS = [
'BeforeAgent',
'AfterAgent',
'AfterTool',
'BeforeTool',
'Notification',
'SessionStart',
'SessionEnd'
] as const
/**
* GitHub Copilot CLI hook events (→ normalizeCopilot). Copilot uses the same PascalCase event
* names as Claude but a different config-file shape, so the subscription list stays shared while
* its installer lives in core/agents/hooks/copilot.ts.
*
* `PermissionRequest` is deliberately absent. Copilot documents that hook as a decision hook that
* can alter the permission result, whereas nodeterm only observes status. Its `Notification`
* event carries the closed `permission_prompt` / `elicitation_dialog` signals we need without
* participating in authorization. `ErrorOccurred` is also omitted: recoverable API/tool errors
* can occur before a turn continues, so treating one as a terminal state would clear RUNNING early.
*/
export const COPILOT_HOOK_EVENTS = [
'SessionStart',
'UserPromptSubmit',
'PreToolUse',
'PostToolUse',
'PostToolUseFailure',
'Stop',
'Notification',
'SessionEnd'
] as const
/**
* Cursor Agent CLI hook events (→ normalizeCursor), written into `~/.cursor/hooks.json` as flat
* `{command}` entries. Cursor's names are camelCase, and it publishes 21 of them
* (`cursor-agent` 2026.09.28 bundle); these are the five that move the badge, plus `sessionEnd`.
*
* Left out on purpose:
* - `sessionStart`: does not fire on `--resume` (measured), so it cannot be relied on. Measured
* again on 2026.10.01: a plain `cursor-agent` fires it before any prompt (with
* `conversation_id`), but nodeterm launches every node as `--resume <minted id>`, which fired
* nothing until `/quit` (two runs). Subscribing it would not give a fresh node a status.
* (`sessionEnd` IS subscribed: interactive `/quit` fires it, measured; it puts cursor in
* `SESSION_END_CAPABLE`. Dropping it here would make every quit read as a DROPPED crash.)
* - `afterAgentResponse`, `afterAgentThought`, `beforeShellExecution`, `afterShellExecution`,
* `afterFileEdit`, `beforeReadFile`, `beforeMCPExecution`, `afterMCPExecution`: three headless
* runs with all of these subscribed (and a claude-format project file beside them) lost the
* agent stream after the first reply ("Connection lost… WritableIterable is closed"), while a
* run with only the five below plus sessionStart/sessionEnd finished clean. Which of the
* differences broke it is unknown (docs/cursor-agent.md §3), so none is added without a run
* that isolates it.
* - `preToolUse` is a GATE (Cursor reads its stdout as a permission decision), so our command must
* stay silent with exit 0, see `buildManagedHookCommand`'s `silent`.
*/
export const CURSOR_HOOK_EVENTS = [
'beforeSubmitPrompt',
'preToolUse',
'postToolUse',
'postToolUseFailure',
'stop',
'sessionEnd'
] as const
/**
* Antigravity CLI (`agy`) hook events (→ normalizeAntigravity), subscribed in
* `~/.gemini/config/hooks.json` under our own bundle key (core/agents/hooks/antigravity.ts).
*
* `agy` 1.2.3 publishes five events in TWO shapes (its bundled `hooks.md`, "Supported Event
* Types"): the tool events are GROUPED (`{matcher, hooks: [...]}`) and the lifecycle events are a
* FLAT list of handlers. The `{event, matcher}` form here marks the grouped ones; a plain string is
* a flat one. The matcher is `*`, which is the value every capture of agy 1.2.3 ran with
* and saw match every tool.
*
* FOUR of the five, and the choice is a cost the user accepted, not an accident:
* - `PreInvocation` fires before every model call → `working`.
* - `PreToolUse` / `PostToolUse` bracket each tool execution; `ask_question` between them is the
* only NEEDS YOU a hook can see. SUBSCRIBING TO `PreToolUse` MAKES OUR HOOK A SYNCHRONOUS GATE
* IN FRONT OF EVERY TOOL CALL OF EVERY `agy` ON THIS MACHINE, inside and outside nodeterm — see
* `antigravityDecisionFor` for the stdout contract that keeps that gate open.
* - `Stop` ends the loop; `fullyIdle` says whether it really ended.
* - `PostInvocation` is left out: it adds no state the four above do not give, and every
* subscribed event is one more SYNCHRONOUS hook process per occurrence.
*
* COST, measured on Windows 11 (20 runs, dispatched as agy does): the answer reaches stdout in ~100 ms, but agy waits for the PROCESS to exit, and that takes
* ~520 ms per event inside a nodeterm node (Git Bash forks ~55 ms each for the token read, the temp
* file and the path conversion before the POST is backgrounded) and ~155 ms in a plain terminal.
* A tool step fires three of these four events, so ~1.6 s of hook per step inside nodeterm. The
* earlier "~100 ms" figure measured a bare `.cmd` stand-in, not this script. Accepted for
* now; backgrounding everything after the stdin read is a tracked follow-up.
*/
export const ANTIGRAVITY_HOOK_EVENTS: readonly ManagedHookEvent[] = [
'PreInvocation',
{ event: 'PreToolUse', matcher: '*' },
{ event: 'PostToolUse', matcher: '*' },
'Stop'
]