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
fix(grok): make the subagent cards actually reachable
Xavi Guardiacfd26d011573
diff --git a/docs/grok-agent.md b/docs/grok-agent.mdindex 57a7ff928..ce956da57 100644--- a/docs/grok-agent.md+++ b/docs/grok-agent.md@@ -164,6 +164,13 @@ observe-only — and interrupted / refused / max-turns turns **skip `Stop` hooksThe configuration uses Grok's canonical `SubagentStop` spelling. Grok also accepts `SubagentEnd` asan 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+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.+---## 3. One hook file we own, and the matcher that must be `.*`diff --git a/src/core/agents/grok-paths.ts b/src/core/agents/grok-paths.tsindex 36a4d06ca..39a892ece 100644--- a/src/core/agents/grok-paths.ts+++ b/src/core/agents/grok-paths.ts@@ -119,8 +119,10 @@ export async function ensureGrokHomeProbed(/*** True when we fell back to `~/.grok` WITHOUT any positive evidence that this is where grok looks —- * i.e. the state in which every grok integration silently does nothing. Exposed so a diagnostic can- * say so instead of leaving the user with a dead node and no explanation.+ * i.e. the state in which every grok integration silently does nothing. Read by+ * `installManagedAgentHooks` (core/agents/hooks/index.ts), which warns with the consequence and the+ * fix; a flag nobody reads would leave the user the dead node and no explanation, which is the+ * failure this whole probe exists to close.*/export function grokHomeFallbackWasSilent(): boolean {return fallbackWasSilentdiff --git a/src/core/agents/hooks/index.ts b/src/core/agents/hooks/index.tsindex 813e72f72..16d5bb8a9 100644--- a/src/core/agents/hooks/index.ts+++ b/src/core/agents/hooks/index.ts@@ -6,7 +6,7 @@ import { installCodexHooks, removeCodexHooks } from './codex'import { installGeminiHooks, removeGeminiHooks } from './gemini'import { installOpencodeHooks, removeOpencodeHooks } from './opencode'import { installGrokHooks, removeGrokHooks } from './grok'-import { ensureGrokHomeProbed, grokHomeDir } from '../grok-paths'+import { ensureGrokHomeProbed, grokHomeDir, grokHomeFallbackWasSilent } from '../grok-paths'import { installCopilotHooks, removeCopilotHooks } from './copilot'type HookInstaller = readonly [string, () => void]@@ -43,6 +43,16 @@ export function installManagedAgentHooks(): void {// that we fell back without evidence, which is the diagnostic this bug never had.const grokHomeAtInstall = grokHomeDir()void ensureGrokHomeProbed().then(() => {+ // The diagnostic the flag exists for. Without this line `grokHomeFallbackWasSilent` promised an+ // explanation the user never saw, which is the very failure it was written to close.+ if (grokHomeFallbackWasSilent()) {+ console.warn(+ `[agent-hooks] grok: could not confirm $GROK_HOME (the login-shell probe returned nothing), ` ++ `so hooks were installed into the default ${grokHomeDir()}. If grok reads a different ` ++ `GROK_HOME, its nodes will show no status, no session name and no notifications, silently. ` ++ `Set GROK_HOME in the environment nodeterm itself is launched from to make this definite.`+ )+ }if (grokHomeDir() === grokHomeAtInstall) returntry {installGrokHooks()diff --git a/src/core/exec-path.ts b/src/core/exec-path.tsindex d7402cd9f..4aa8fc362 100644--- a/src/core/exec-path.ts+++ b/src/core/exec-path.ts@@ -61,8 +61,6 @@ export function resolveShellPath(): Promise<string | null> {return shellPathPromise}-/** The cached login-shell PATH: a string once resolved, null if the probe failed, undefined- * while the async probe is still in flight (callers should then fall back + re-probe later). *//*** One environment VARIABLE, as the user's login+interactive shell sees it. Same spawn shape as* `resolveShellPath` above and for the same reason: a GUI app launched from Finder/Dock/`.desktop`@@ -103,6 +101,8 @@ export function _resetShellEnvVarsForTests(): void {cachedShellVars.clear()}+/** The cached login-shell PATH: a string once resolved, null if the probe failed, undefined+ * while the async probe is still in flight (callers should then fall back + re-probe later). */export function shellPathNow(): string | null | undefined {return cachedShellPath}diff --git a/src/shared/agents/normalize.grok.test.ts b/src/shared/agents/normalize.grok.test.tsindex 81016b36e..f2c734a1f 100644--- a/src/shared/agents/normalize.grok.test.ts+++ b/src/shared/agents/normalize.grok.test.ts@@ -5,8 +5,9 @@ import { grokRawFields, normalizeClaude, normalizeGrok, type RawHookEnvelope } f* Grok's hook envelope is its own dialect: camelCase keys whose `hookEventName` VALUE is* 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. No payload was- * ever captured: a hook fires only inside a logged-in grok session, which was never available here.+ * 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.*/function env(payload: Record<string, unknown>): RawHookEnvelope {return { nodeId: 'n1', agentId: 'grok', payload }@@ -401,3 +402,81 @@ 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.+ *+ * 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+ * feature reached review claiming to work.+ */+describe('normalizeGrok — subagents', () => {+ const START = {+ hookEventName: 'subagent_start',+ sessionId: 'parent-1',+ subagentId: 'child-a',+ subagentType: 'explore',+ description: 'Read a.txt contents'+ }+ const STOP = {+ hookEventName: 'subagent_stop',+ // The captured stop carries the CHILD's own id here, not the parent's.+ sessionId: 'child-a',+ subagentId: 'child-a',+ subagentType: 'explore',+ lastAssistantMessage: 'alfa'+ }++ it('maps subagent_start to a card keyed on subagentId, carrying type and task', () => {+ expect(normalizeGrok(env(START))).toEqual({+ nodeId: 'n1',+ agentId: 'grok',+ kind: 'subagent-start',+ toolUseId: 'child-a',+ subagentType: 'explore',+ task: 'Read a.txt contents'+ })+ })++ it('maps subagent_stop to the end, carrying the last assistant message as the result', () => {+ expect(normalizeGrok(env(STOP))).toEqual({+ nodeId: 'n1',+ agentId: 'grok',+ kind: 'subagent-end',+ toolUseId: 'child-a',+ subagentType: 'explore',+ result: 'alfa'+ })+ })++ it('gives two children of the SAME type different cards — one per instance, not per type', () => {+ const a = normalizeGrok(env(START))+ const b = normalizeGrok(env({ ...START, subagentId: 'child-b' }))+ expect(a?.subagentType).toBe(b?.subagentType)+ expect(a?.toolUseId).not.toBe(b?.toolUseId)+ })++ it('never re-points the node session: neither event carries a sessionId', () => {+ // The stop's own sessionId is the CHILD's; passing it through as `sessionId` would move the+ // node's session onto the child and take the context meter with it.+ expect(normalizeGrok(env(START))).not.toHaveProperty('sessionId')+ expect(normalizeGrok(env(STOP))).not.toHaveProperty('sessionId')+ })++ it('reads the snake_case dialect the SDK path presents', () => {+ expect(+ normalizeGrok(+ env({+ hook_event_name: 'subagent_start',+ subagent_id: 'child-a',+ subagent_type: 'explore'+ })+ )+ ).toMatchObject({ kind: 'subagent-start', toolUseId: 'child-a', subagentType: 'explore' })+ })++ it('returns null for a subagent event with no id, rather than an unkeyable card', () => {+ expect(normalizeGrok(env({ hookEventName: 'subagent_start', subagentType: 'explore' }))).toBeNull()+ })+})diff --git a/src/shared/agents/normalize.ts b/src/shared/agents/normalize.tsindex faf7c6325..7de0d45f1 100644--- a/src/shared/agents/normalize.ts+++ b/src/shared/agents/normalize.ts@@ -764,11 +764,39 @@ export function normalizeGrok(env: RawHookEnvelope): NormalizedAgentEvent | nulllastMessage}}- if (ev === 'subagentstart' || ev === 'subagentstop') {+ // Subagent cards. MEASURED (1.0.13, two parallel `explore` children — the capture is+ // evidence/grok-subagent-payloads.jsonl):+ // 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 {- ...base,- kind: ev === 'subagentstart' ? 'subagent-start' : 'subagent-end',- subagentType: p.subagentType ?? p.subagent_type+ nodeId: env.nodeId,+ agentId: env.agentId,+ kind: 'subagent-end',+ toolUseId: subagentId,+ subagentType,+ result: lastMessage}}if (ev === 'precompact' || ev === 'postcompact') {