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.

fix(grok): make the subagent cards actually reachable

Xavi Guardiacfd26d011573
diff --git a/docs/grok-agent.md b/docs/grok-agent.md
index 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` hooks
The configuration uses Grok's canonical `SubagentStop` spelling. Grok also accepts `SubagentEnd` as
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
+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.ts
index 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 fallbackWasSilent
diff --git a/src/core/agents/hooks/index.ts b/src/core/agents/hooks/index.ts
index 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) return
try {
installGrokHooks()
diff --git a/src/core/exec-path.ts b/src/core/exec-path.ts
index 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.ts
index 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.ts
index 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 | null
lastMessage
}
}
- 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') {