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.

test(grok): anclar SubagentStart/Stop a la captura real, y alinear CLAUDE.md

Xavi Guardia52942f290ffb
diff --git a/CLAUDE.md b/CLAUDE.md
index 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 list
in 2026-09, once a machine with a logged-in grok session produced real fixtures: context links and
the ⌘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 live
activity yet (the child rollout is on the host; claude's `remote-subagent-tail` has no codex
counterpart — 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 starts
with the slash): `PreToolUse` for `Skill` (skill ∈ loop/schedule/cron), `CronCreate` (→ cron,
diff --git a/docs/grok-agent.md b/docs/grok-agent.md
index 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 rather
than 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 not
decoration: without the pair, `normalizeGrok`'s subagent branches and both raw listeners are
unreachable, which is how the capability first reached review claiming to work while no card could
ever render.
diff --git a/src/shared/agents/__fixtures__/grok/hook-payloads.json b/src/shared/agents/__fixtures__/grok/hook-payloads.json
index 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.ts
index 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.ts
index 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 the
diff --git a/src/shared/agents/normalize.ts b/src/shared/agents/normalize.ts
index 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