Skip to content

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.

10.2 KB
Raw Blame
// 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'
]