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
test(grok): anclar SubagentStart/Stop a la captura real, y alinear CLAUDE.md
Xavi Guardia52942f290ffb
diff --git a/CLAUDE.md b/CLAUDE.mdindex 420fcd56d..811132bf0 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -1200,9 +1200,12 @@ else, and its context links must keep classifying across restarts).before it can expose the feature.- **Grok** (`@xai-official/grok` 1.0.0, builtin since 2026-08) — in `AGENT_HOOK_TARGETS`,`RESUMABLE_AGENTS`, `RENAME_CAPABLE`, `PERMISSION_MODE_CAPABLE`, `CANVAS_CONTROL_CAPABLE`,- `CONTEXT_LINK_CAPABLE`, `CHAT_CAPABLE`, `TRANSFER_SOURCE_CAPABLE`, `USAGE_CAPABLE` and- `SESSION_ID_CAPABLE`; NOT in `SUBAGENT_CAPABLE` — subagent cards still need the `spawn_subagent`- PreToolUse/PostToolUse payload, which nobody has captured. The other four came off the blocked list+ `CONTEXT_LINK_CAPABLE`, `CHAT_CAPABLE`, `TRANSFER_SOURCE_CAPABLE`, `USAGE_CAPABLE`,+ `SESSION_ID_CAPABLE` and `SUBAGENT_CAPABLE`. Subagent cards come from grok's native+ `SubagentStart`/`SubagentStop` hooks, keyed by `subagentId` — measured on 1.0.13 by launching two+ `explore` children in parallel (same type, different ids; the start's `sessionId` is the PARENT's,+ the stop's is the CHILD's own and equals `subagentId`, so that is the only id both events share).+ The spawn tool call is not the card key. The other four came off the blocked listin 2026-09, once a machine with a logged-in grok session produced real fixtures: context links andthe ⌘M panel read `chat_history.jsonl` (NOT `updates.jsonl` — see below), and the meter reads`signals.json`. Its hook config is a **directory** (`$GROK_HOME/hooks/*.json`, all merged), so nodeterm@@ -1700,6 +1703,21 @@ else, and its context links must keep classifying across restarts).`last_assistant_message` as the card's result. Remote (SSH) codex nodes get cards but no liveactivity yet (the child rollout is on the host; claude's `remote-subagent-tail` has no codexcounterpart — follow-up).+ **Grok** (2026-09) joined via its own native `SubagentStart`/`SubagentStop`, measured on+ grok 1.0.13 by launching two `explore` children in parallel. Keyed by `subagentId` occupying+ the same `toolUseId` slot the store already uses (claude correlates by `tool_use_id`,+ codex by `agent_id`; grok has no tool call behind a subagent). Facts a refactor must not+ lose: **(1)** the start's `sessionId` is the PARENT's and the stop's is the CHILD's own+ (equal to `subagentId`) — keying on it files start and stop under different cards and the+ started one never closes. **(2)** the child's transcript is DERIVED from `subagentId` as+ `chat_history.jsonl` (`core/grok-subagent-format.ts`); the start's `transcriptPath` is the+ PARENT's, and even the stop names `updates.jsonl`, which parses to nothing. **(3)** a+ `session_end` bearing `subagentType` returns early in both raw listeners — without that a+ child finishing tears down the PARENT's session state. **(4)** `description` arrives only+ on the start. The four captured payloads live in+ `src/shared/agents/__fixtures__/grok/hook-payloads.json`, pinned by+ `normalize.grok.capture.test.ts`. Remote (SSH) grok nodes get cards from the hook but no+ live tail yet (the child dir is on the host; same gap as codex).- **/loop, /schedule & /cron node** (agents in `RECURRING_CAPABLE`) — detected from the **tools**the agent invokes (robust; users often phrase it in natural language so the prompt rarely startswith the slash): `PreToolUse` for `Skill` (skill ∈ loop/schedule/cron), `CronCreate` (→ cron,diff --git a/docs/grok-agent.md b/docs/grok-agent.mdindex ce956da57..09c90ecdc 100644--- a/docs/grok-agent.md+++ b/docs/grok-agent.md@@ -166,7 +166,8 @@ an alias, but subscribing twice would only duplicate the same lifecycle signal.`SubagentStart` / `SubagentStop` are also the only two events in that list observed FIRING ratherthan read off the docs (capture: two parallel `explore` children, 1.0.13, 2026-09-02, in-`tasks/grok-full-support/evidence/grok-subagent-payloads.jsonl`). Subscribing them is not+`src/shared/agents/__fixtures__/grok/hook-payloads.json`, pinned by+`normalize.grok.capture.test.ts`). Subscribing them is notdecoration: without the pair, `normalizeGrok`'s subagent branches and both raw listeners areunreachable, which is how the capability first reached review claiming to work while no card couldever render.diff --git a/src/shared/agents/__fixtures__/grok/hook-payloads.json b/src/shared/agents/__fixtures__/grok/hook-payloads.jsonindex 174c9f42b..051cc6258 100644--- a/src/shared/agents/__fixtures__/grok/hook-payloads.json+++ b/src/shared/agents/__fixtures__/grok/hook-payloads.json@@ -1,5 +1,5 @@{- "_provenance": "captured live from grok 1.0.13 (5e9a58528b76) on 2026-09-01, real logged-in account; paths, session ids and tool-call ids redacted, KEYS AND SHAPES UNCHANGED",+ "_provenance": "captured live from grok 1.0.13 (5e9a58528b76) on 2026-09-01, real logged-in account; SubagentStart/SubagentStop added from a second capture on 2026-09-02 (two parallel explore children of the same type); paths, session ids and tool-call ids redacted, KEYS AND SHAPES UNCHANGED","events": [{"hookEventName": "session_start",@@ -285,6 +285,76 @@"session_id": "00000000-0000-4000-8000-000000000001","transcript_path": "/home/user/.grok/sessions/%2Fwork%2Fproject/00000000-0000-4000-8000-000000000001/updates.jsonl","permission_mode": "default"+ },+ {+ "hookEventName": "subagent_start",+ "sessionId": "00000000-0000-4000-8000-000000000010",+ "cwd": "/work/project",+ "workspaceRoot": "/work/project",+ "timestamp": "2026-09-02T12:23:11.567102+00:00",+ "transcriptPath": "/home/user/.grok/sessions/%2Fwork%2Fproject/00000000-0000-4000-8000-000000000010/updates.jsonl",+ "permissionMode": "bypassPermissions",+ "subagentId": "00000000-0000-4000-8000-000000000012",+ "subagentType": "explore",+ "description": "Read b.txt contents",+ "hook_event_name": "subagent_start",+ "session_id": "00000000-0000-4000-8000-000000000010",+ "transcript_path": "/home/user/.grok/sessions/%2Fwork%2Fproject/00000000-0000-4000-8000-000000000010/updates.jsonl",+ "permission_mode": "bypassPermissions"+ },+ {+ "hookEventName": "subagent_start",+ "sessionId": "00000000-0000-4000-8000-000000000010",+ "cwd": "/work/project",+ "workspaceRoot": "/work/project",+ "timestamp": "2026-09-02T12:23:11.589454+00:00",+ "transcriptPath": "/home/user/.grok/sessions/%2Fwork%2Fproject/00000000-0000-4000-8000-000000000010/updates.jsonl",+ "permissionMode": "bypassPermissions",+ "subagentId": "00000000-0000-4000-8000-000000000011",+ "subagentType": "explore",+ "description": "Read a.txt contents",+ "hook_event_name": "subagent_start",+ "session_id": "00000000-0000-4000-8000-000000000010",+ "transcript_path": "/home/user/.grok/sessions/%2Fwork%2Fproject/00000000-0000-4000-8000-000000000010/updates.jsonl",+ "permission_mode": "bypassPermissions"+ },+ {+ "hookEventName": "subagent_stop",+ "sessionId": "00000000-0000-4000-8000-000000000011",+ "cwd": "/work/project",+ "workspaceRoot": "/work/project",+ "timestamp": "2026-09-02T12:23:15.445215+00:00",+ "transcriptPath": "/home/user/.grok/sessions/%2Fwork%2Fproject/00000000-0000-4000-8000-000000000011/updates.jsonl",+ "promptId": "00000000-0000-4000-8000-000000000021",+ "permissionMode": "bypassPermissions",+ "phase": "gate",+ "subagentId": "00000000-0000-4000-8000-000000000011",+ "subagentType": "explore",+ "stopHookActive": false,+ "lastAssistantMessage": "alfa",+ "hook_event_name": "subagent_stop",+ "session_id": "00000000-0000-4000-8000-000000000011",+ "transcript_path": "/home/user/.grok/sessions/%2Fwork%2Fproject/00000000-0000-4000-8000-000000000011/updates.jsonl",+ "permission_mode": "bypassPermissions"+ },+ {+ "hookEventName": "subagent_stop",+ "sessionId": "00000000-0000-4000-8000-000000000012",+ "cwd": "/work/project",+ "workspaceRoot": "/work/project",+ "timestamp": "2026-09-02T12:23:16.099471+00:00",+ "transcriptPath": "/home/user/.grok/sessions/%2Fwork%2Fproject/00000000-0000-4000-8000-000000000012/updates.jsonl",+ "promptId": "00000000-0000-4000-8000-000000000022",+ "permissionMode": "bypassPermissions",+ "phase": "gate",+ "subagentId": "00000000-0000-4000-8000-000000000012",+ "subagentType": "explore",+ "stopHookActive": false,+ "lastAssistantMessage": "beta",+ "hook_event_name": "subagent_stop",+ "session_id": "00000000-0000-4000-8000-000000000012",+ "transcript_path": "/home/user/.grok/sessions/%2Fwork%2Fproject/00000000-0000-4000-8000-000000000012/updates.jsonl",+ "permission_mode": "bypassPermissions"}]}diff --git a/src/shared/agents/normalize.grok.capture.test.ts b/src/shared/agents/normalize.grok.capture.test.tsindex 9bd2a45af..d51966524 100644--- a/src/shared/agents/normalize.grok.capture.test.ts+++ b/src/shared/agents/normalize.grok.capture.test.ts@@ -3,8 +3,9 @@// FIXTURE PROVENANCE: `__fixtures__/grok/hook-payloads.json` was captured live from grok 1.0.13// (build 5e9a58528b76) on 2026-09-01, from a logged-in account, by a temporary capture hook// installed as its OWN file in `$GROK_HOME/hooks/` (grok merges every file in that directory, so-// nothing of ours touched `nodeterm-status.json`). Paths, session ids and tool-call ids are-// redacted; KEYS AND SHAPES ARE UNCHANGED.+// nothing of ours touched `nodeterm-status.json`). SubagentStart/SubagentStop were added from a+// second capture on 2026-09-02 (two parallel `explore` children). Paths, session ids and+// tool-call ids are redacted; KEYS AND SHAPES ARE UNCHANGED.//// Why this file exists at all: every earlier grok test asserted against payloads WE wrote from the// shipped docs, so they pinned our reading of the documentation rather than grok's behaviour — and@@ -92,4 +93,49 @@ describe('normalizeGrok over captured grok 1.0.13 payloads', () => {expect(idle?.interrupted).toBe(true)expect(idle?.idle).toBe(true)})++ it('maps SubagentStart/SubagentStop from the live capture — one card per instance, not per type', () => {+ // Second capture, 2026-09-02: two parallel `explore` children. The payloads live in THIS+ // fixture (not a tasks/ path nobody can open) so the mapping is pinned against grok's+ // behaviour rather than against payloads we wrote from the docs.+ const starts = fixture.events.filter((e) => e.hookEventName === 'subagent_start')+ const stops = fixture.events.filter((e) => e.hookEventName === 'subagent_stop')+ expect(starts, 'the capture is two parallel explore children').toHaveLength(2)+ expect(stops).toHaveLength(2)++ expect(new Set(starts.map((e) => e.subagentType))).toEqual(new Set(['explore']))+ const startIds = starts.map((e) => e.subagentId as string)+ expect(new Set(startIds).size).toBe(2)++ // The trap: start.sessionId is the PARENT's (same for both children); stop.sessionId is+ // the CHILD's own and equals that child's subagentId. Keying the card on sessionId would+ // file start and stop under different cards and never close the started one.+ const parentIds = new Set(starts.map((e) => e.sessionId as string))+ expect(parentIds.size).toBe(1)+ for (const stop of stops) {+ expect(stop.sessionId).toBe(stop.subagentId)+ expect(parentIds.has(stop.sessionId as string)).toBe(false)+ }++ const mappedStarts = starts.map((p) => normalizeGrok(env(p)))+ const mappedStops = stops.map((p) => normalizeGrok(env(p)))+ for (const e of mappedStarts) {+ expect(e?.kind).toBe('subagent-start')+ expect(e).not.toHaveProperty('sessionId')+ }+ for (const e of mappedStops) {+ expect(e?.kind).toBe('subagent-end')+ expect(e).not.toHaveProperty('sessionId')+ }+ expect(new Set(mappedStarts.map((e) => e?.toolUseId))).toEqual(new Set(startIds))+ expect(new Set(mappedStops.map((e) => e?.toolUseId))).toEqual(new Set(startIds))++ const byId = Object.fromEntries(starts.map((p) => [p.subagentId as string, p]))+ for (const stop of stops) {+ const start = byId[stop.subagentId as string]+ expect(start, `stop ${stop.subagentId} has no matching start`).toBeTruthy()+ expect(normalizeGrok(env(stop))?.result).toBe(stop.lastAssistantMessage)+ expect(normalizeGrok(env(start))?.task).toBe(start.description)+ }+ })})diff --git a/src/shared/agents/normalize.grok.test.ts b/src/shared/agents/normalize.grok.test.tsindex 53e683593..94a6a90c1 100644--- a/src/shared/agents/normalize.grok.test.ts+++ b/src/shared/agents/normalize.grok.test.ts@@ -6,8 +6,9 @@ import { grokRawFields, normalizeClaude, normalizeGrok, type RawHookEnvelope } f* snake_case ("pre_tool_use"), and the grok SDK path converts the top-level keys to snake_case.* Both spellings are therefore read, and the event name is canonicalized rather than matched* literally — read out of the shipped 1.0.0 docs, not inferred from claude's shape. Payloads WERE- * captured on 1.0.13 (evidence/grok-hook-payloads.jsonl and grok-subagent-payloads.jsonl); the cases- * below that are built from a capture say so.+ * captured on 1.0.13 (`__fixtures__/grok/hook-payloads.json`); the cases+ * below that are built from a capture say so. The behavioural pin over the live+ * subagent payloads is `normalize.grok.capture.test.ts`, not the hand-built cases here.*/function env(payload: Record<string, unknown>): RawHookEnvelope {return { nodeId: 'n1', agentId: 'grok', payload }@@ -400,7 +401,9 @@ describe('grokRawFields', () => {/*** Subagent cards. Every payload below is copied from the 1.0.13 capture- * (evidence/grok-subagent-payloads.jsonl, two parallel `explore` children), field names and all.+ * (`__fixtures__/grok/hook-payloads.json`, two parallel `explore` children), field names and all.+ * The live-payload pin is `normalize.grok.capture.test.ts`; these cases keep the mapping+ * reachable when someone edits `normalizeGrok` without opening the fixture.** These assert the mapped EVENT, not list membership: a test that only checks `canSubagent('grok')`* passes while `normalizeGrok` returns null and no card can ever render, which is exactly how thediff --git a/src/shared/agents/normalize.ts b/src/shared/agents/normalize.tsindex fe5aed99c..2d3374ee7 100644--- a/src/shared/agents/normalize.ts+++ b/src/shared/agents/normalize.ts@@ -762,7 +762,7 @@ export function normalizeGrok(env: RawHookEnvelope): NormalizedAgentEvent | null}}// Subagent cards. MEASURED (1.0.13, two parallel `explore` children — the capture is- // evidence/grok-subagent-payloads.jsonl):+ // `__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