Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

fix(cli): bind hooks from engines that post them outside their own process tree

0xken15e115b675c4ce
diff --git a/cli/src/cli.ts b/cli/src/cli.ts
index ffb987e1b..a29b97ea6 100644
--- a/cli/src/cli.ts
+++ b/cli/src/cli.ts
@@ -48,7 +48,7 @@ import { processRows, type DiscoveredTerminalAgent } from './lib/terminalAgentDi
import { terminalActionNotStarted, type HookTerminalHint, type TerminalActionResult, type TerminalRuntimeRef } from './lib/terminalTypes.js'
import { readTerminalConfigSnapshot, writeTerminalConfigSnapshot } from './lib/terminalConfigSnapshot.js'
import { Watcher, type LineEvent } from './watcher/watcher.js'
-import { startHookServer } from './hookServer.js'
+import { chooseHookAgent, startHookServer } from './hookServer.js'
import { BackendSocket } from './backendSocket.js'
import { foldTranscript, lastTurnTextFromRawLines, lineToEvents, newTurnState, type LiveEvent, type TurnState } from './lib/normalize.js'
import { AnalyticsCollector } from './lib/analytics/collector.js'
@@ -1603,9 +1603,25 @@ async function runForeground(token: string): Promise<void> {
return false
}
const candidates = new Map<string, RegisteredSession>()
+ /**
+ * Agents the hint points at whose ancestry we could NOT confirm.
+ *
+ * Caller ancestry is the strongest evidence and stays the first choice, but it assumes every engine
+ * spawns its hook from inside its own process tree — and Cursor does not. Measured on both
+ * backends: `agent` in a pane registers fine, then every one of its hooks is rejected because the
+ * process that POSTs is not a descendant of the pane's engine, so no session ever binds. It is not
+ * a Herdr problem; tmux fails identically.
+ *
+ * The pane is itself proof: the hook knew a runtime id, that runtime carries exactly one agent of
+ * this engine, and the caller already had to read the 0600 hook credential to be heard at all. So
+ * fall back to that, and only when it is unambiguous.
+ */
+ const onHintedRuntime = new Map<string, RegisteredSession>()
for (const runtime of resolved) {
const candidate = registry.byRuntimeEngine(runtime, engine)
- if (candidate && callerBelongsTo(candidate)) candidates.set(candidate.agentId, candidate)
+ if (!candidate) continue
+ if (callerBelongsTo(candidate)) candidates.set(candidate.agentId, candidate)
+ else onHintedRuntime.set(candidate.agentId, candidate)
}
// A moved Herdr pane may leave an inherited stale route. Caller/process correlation is the
// deterministic fallback, but only within a configured Herdr session named by the hook.
@@ -1622,7 +1638,24 @@ async function runForeground(token: string): Promise<void> {
}
}
}
- return candidates.size === 1 ? [...candidates.values()][0] : null
+ const choice = chooseHookAgent([...candidates.values()], [...onHintedRuntime.values()])
+ if (choice.agent) {
+ if (choice.reason === 'runtime') {
+ console.log(`[hooks] ${engine} hook accepted on runtime evidence alone`
+ + ` · agent=${sid(choice.agent.agentId)} · caller=${callerPid} is outside that engine's process tree`)
+ }
+ return choice.agent
+ }
+ // Say WHY, once per rejected hook. "no_matching_engine_process" alone sent two people down the
+ // wrong path already: the interesting question is never "did it match" but which of the three
+ // gates closed — no runtime resolved from the hint, no registered agent on that runtime, or the
+ // hook's own process is not a descendant of the engine we registered.
+ const onRuntime = resolved.map((runtime) => registry.byRuntimeEngine(runtime, engine)).filter(Boolean)
+ console.log(`[hooks] unmatched ${engine} hook · hints=${(runtimeHints ?? []).map((hint) => `${hint.backend}:${hint.paneId}`).join(',') || 'none'}`
+ + ` · resolvedRuntimes=${resolved.length} · agentsOnRuntime=${onRuntime.length}`
+ + ` · callerPid=${callerPid}${onRuntime.length && !candidates.size ? ' · caller is not a descendant of that engine process' : ''}`
+ + `${candidates.size > 1 ? ` · ambiguous (${candidates.size} candidates)` : ''}`)
+ return null
},
onRegistered: handleRegistered,
onSessionEnd,
diff --git a/cli/src/hookServer.spec.ts b/cli/src/hookServer.spec.ts
index 5fe7bdbb9..e0ec6baca 100644
--- a/cli/src/hookServer.spec.ts
+++ b/cli/src/hookServer.spec.ts
@@ -1,6 +1,6 @@
import type { Server } from 'node:http'
import { afterEach, describe, expect, it, vi } from 'vitest'
-import { startHookServer, type HookServerHandlers } from './hookServer.js'
+import { startHookServer, type HookServerHandlers, chooseHookAgent } from './hookServer.js'
import { env } from './config/env.js'
import { readHookCredential } from './lib/hookAuth.js'
@@ -138,3 +138,24 @@ describe('process-owned hook server', () => {
expect(handler).not.toHaveBeenCalled()
})
})
+
+describe('chooseHookAgent', () => {
+ it('prefers caller ancestry, the evidence that cannot be guessed at', () => {
+ expect(chooseHookAgent(['strong'], ['weak'])).toEqual({ agent: 'strong', reason: 'ancestry' })
+ })
+
+ it('accepts the runtime alone when ancestry is unavailable and the pane is unambiguous', () => {
+ // Cursor posts its hooks from outside the pane's process tree — on tmux and on Herdr alike — so
+ // demanding ancestry rejected every hook it ever sent and no session bound. The pane is the proof:
+ // the hook named a runtime, and that runtime carries exactly one agent of this engine.
+ expect(chooseHookAgent([], ['only-agent-on-that-pane'])).toEqual({
+ agent: 'only-agent-on-that-pane', reason: 'runtime',
+ })
+ })
+
+ it('answers nothing rather than guessing', () => {
+ expect(chooseHookAgent([], [])).toEqual({ agent: null, reason: 'none' })
+ expect(chooseHookAgent([], ['a', 'b'])).toEqual({ agent: null, reason: 'ambiguous' })
+ expect(chooseHookAgent(['a', 'b'], ['c'])).toEqual({ agent: null, reason: 'ambiguous' })
+ })
+})
diff --git a/cli/src/hookServer.ts b/cli/src/hookServer.ts
index 1c09ffefd..5ec7c6eb5 100644
--- a/cli/src/hookServer.ts
+++ b/cli/src/hookServer.ts
@@ -20,6 +20,29 @@ import { hookCredentialMatches, loadOrCreateHookCredential } from './lib/hookAut
import type { HookTerminalHint } from './lib/terminalTypes.js'
import { ENGINES, type AgentEngine } from './engines/types.js'
+/**
+ * Which agent does a hook belong to, given the two grades of evidence?
+ *
+ * Caller ancestry — the hook's process descends from the engine we registered — is the strong one and
+ * always wins. It is not always available: Cursor posts its hooks from outside the pane's process tree,
+ * on tmux and on Herdr alike, so requiring ancestry rejected every hook that engine ever sent and no
+ * session bound at all.
+ *
+ * The weaker grade is the runtime itself: the hook named a pane, and that pane carries exactly one agent
+ * of this engine. Accepted only when it is unambiguous, and only after the caller has already proven it
+ * can read the 0600 hook credential. Two candidates is not a tie to break — it is a question we cannot
+ * answer, so we answer nothing.
+ */
+export function chooseHookAgent<T>(byAncestry: readonly T[], byRuntimeOnly: readonly T[]): {
+ agent: T | null
+ reason: 'ancestry' | 'runtime' | 'ambiguous' | 'none'
+} {
+ if (byAncestry.length === 1) return { agent: byAncestry[0], reason: 'ancestry' }
+ if (byAncestry.length > 1) return { agent: null, reason: 'ambiguous' }
+ if (byRuntimeOnly.length === 1) return { agent: byRuntimeOnly[0], reason: 'runtime' }
+ return { agent: null, reason: byRuntimeOnly.length ? 'ambiguous' : 'none' }
+}
+
export interface PairOutcome {
status: number
body: Record<string, unknown>