thinkpool-pair 0.7.232 → 0.7.234

package/claude-session.mjs

@@ -200,10 +200,10 @@ const TP_ROOM_REMINDER = [
   THINKPOOL_DESIGN_DELIVERY_RULE,
   'REMOTE USER: the people here may have no terminal and no access to this host — never ask them to run a local command, open a local file, or check something on the machine. Anything host-side, YOU run, and show the result.',
   'SHOW, don\'t narrate: a picture of the result beats a wall of text on a phone — err toward more screenshots.',
-  'ENSEMBLE: obey your authoritative TERMINAL ROLE. Only conductor-capable roles fan work out with spawn_terminal (visible and steerable here); leaf, Side, and managed Flow lanes work directly. When opening a Cascade conductor, pass cascadeRole="conductor"; that conductor passes cascadeRole="worker" for slice lanes. Never use built-in invisible Task/Agent subagents or hijack a busy sibling.',
+  'TERMINAL HIERARCHY: obey your authoritative TERMINAL ROLE. Conductors are independent main terminals; Ensemble lanes are workers only. When a person explicitly asks to open, launch, start, or spawn a separate Cascade/conductor terminal, use open_main_terminal — NEVER spawn_terminal. If open_main_terminal is unavailable, say so; never substitute an Ensemble child. Only conductor-capable roles fan worker slices out with spawn_terminal. Leaf, worker, Side, and managed Flow lanes work directly. Never use built-in invisible Task/Agent subagents or hijack a busy sibling.',
   'PEER: before substantive work, check what the other lanes are doing (the ROOM NOW snapshot below, read_terminal for detail; list_sessions/read_session across rooms) — coordinate on shared files/branches instead of colliding.',
   'WORKTREES: parallel lanes share one repo — before code edits run `git worktree list`; if linked worktrees exist, take your OWN worktree + branch, never the shared checkout or a branch another lane is on.',
-  'BUILD WORKFLOW (default, no magic word): right-size within your TERMINAL ROLE — a trivial ask or delegated slice you just do; a conductor-capable role with a genuinely decomposable build FIRST writes a short plan in chat, THEN fans independent slices into visible spawn_terminal lanes and verifies them. Leaf/Side/managed Flow roles do not fan out. Never plan-mode/ExitPlanMode; plans live in chat and lanes in the existing list.',
+  'BUILD WORKFLOW (default, no magic word): right-size within your TERMINAL ROLE — a trivial ask or delegated slice you just do; a conductor-capable role with a genuinely decomposable build FIRST writes a short plan in chat, THEN fans worker slices into visible spawn_terminal lanes and verifies them. Worker/leaf/Side/managed Flow roles do not fan out. A requested separate conductor uses open_main_terminal. Never plan-mode/ExitPlanMode; plans live in chat and lanes in the existing list.',
   'Verify before claiming done — show runtime evidence you produced, not "should work, go test it".',
 ].join(' ')
 
@@ -516,25 +516,25 @@ export function startClaudeSession({ cwd, model, effort: initialEffort = 'high',
     if (toolName === 'mcp__thinkpool__close_terminal') {
       return { continue: true, hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'allow', permissionDecisionReason: 'Auto-approved (ThinkPool cross-terminal close — only self-spawned lanes).' } }
     }
-    // ThinkPool cross-terminal SPAWN (Tier C+) — opens a FRESH lane the agent owns
-    // (never touches a sibling). A spawned lane INHERITS the spawner's permission mode
+    // ThinkPool terminal creation — open_main_terminal creates an independent main
+    // conductor; spawn_terminal creates a worker the agent owns. Both inherit mode
     // (`mode` here is THIS lane's current mode) unless an explicit `mode` overrides it.
     // The only thing worth a human card is an ESCALATION: raising a child to
     // bypassPermissions from a non-bypass lane (full unattended access the operator
     // hasn't already opted into). If the spawner is already in bypass, children inherit
     // bypass with NO prompt (you opted in once); a non-bypass child gates itself per
     // action anyway, so no spawn prompt there either. Bridge-side spawnDecision still
-    // enforces the depth-2 hop bound / burst window / machineMax / TP_SPAWN_OFF regardless.
-    if (toolName === 'mcp__thinkpool__spawn_terminal') {
+    // enforces the one-worker-tier bound / burst window / machineMax / TP_SPAWN_OFF regardless.
+    if (toolName === 'mcp__thinkpool__spawn_terminal' || toolName === 'mcp__thinkpool__open_main_terminal') {
       const childMode = toolInput?.mode || mode   // inherit this lane's mode by default
       const escalating = childMode === 'bypassPermissions' && mode !== 'bypassPermissions'
       if (!escalating) {
-        return { continue: true, hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'allow', permissionDecisionReason: `Auto-approved (spawn a fresh lane in ${childMode} mode — inherited, no escalation; bounded by the room caps).` } }
+        return { continue: true, hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'allow', permissionDecisionReason: `Auto-approved (open a fresh ThinkPool terminal in ${childMode} mode — inherited, no escalation; bounded by room caps).` } }
       }
       let decision = 'deny'
       try { decision = await requestPermission?.({ id: randomUUID(), toolName, input: { ...toolInput, mode: childMode }, risk: 'high' }) ?? 'deny' } catch { decision = 'deny' }
       const allowed = decision === 'allow'
-      return { continue: true, hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: allowed ? 'allow' : 'deny', permissionDecisionReason: allowed ? 'Bypass spawn approved in the ThinkPool room — the new lane runs autonomously.' : 'Bypass spawn denied in the room — do not retry as bypass; re-spawn without mode:bypassPermissions to get a gated lane, or ask what to do.' } }
+      return { continue: true, hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: allowed ? 'allow' : 'deny', permissionDecisionReason: allowed ? 'Bypass terminal creation approved in the ThinkPool room — the new terminal runs autonomously.' : 'Bypass terminal creation denied in the room — do not retry as bypass; open it without mode:bypassPermissions or ask what to do.' } }
     }
     // ThinkPool cross-terminal POST (Tier C) WRITES into a sibling agent's lane.
     // First a bridge-side precheck (kill-switch / loop-breaker / per-turn cap) so a
@@ -702,15 +702,15 @@ export function startClaudeSession({ cwd, model, effort: initialEffort = 'high',
       // no summon word. The agent INFERS build intent and runs plan→(optional)fan-out→build→self-verify,
       // right-sized to the task, surfaced in the room's EXISTING surfaces (chat + lane list) — never a new panel,
       // never plan-mode's approval card. Trivial asks stay single-lane with zero ceremony.
-      'DEFAULT BUILD WORKFLOW (this IS your standard behaviour — no keyword and no "flow" word is ever required to trigger it; you infer it from the request itself). RIGHT-SIZE to the task within the authoritative TERMINAL ROLE, always: a TRIVIAL ask — a one-line fix, a small tweak, a question — you just do it directly, with no plan and no extra lanes (never tax small work with ceremony). A NON-TRIVIAL build that genuinely decomposes, when your role permits delegation — you FIRST write a short plan as a normal chat message (the approach, the concrete slices, and what you will verify), THEN fan the independent slices out into their own visible lanes with spawn_terminal(cascadeRole="worker"), build, and self-verify each slice before calling it done. Worker, leaf, Side, and managed Flow lanes complete their assigned work directly and do not fan out.',
+      'DEFAULT BUILD WORKFLOW (this IS your standard behaviour — no keyword and no "flow" word is ever required to trigger it; you infer it from the request itself). RIGHT-SIZE to the task within the authoritative TERMINAL ROLE, always: a TRIVIAL ask — a one-line fix, a small tweak, a question — you just do it directly, with no plan and no extra lanes (never tax small work with ceremony). A NON-TRIVIAL build that genuinely decomposes, when your role permits delegation — you FIRST write a short plan as a normal chat message (the approach, the concrete slices, and what you will verify), THEN fan worker slices into visible Ensemble lanes with spawn_terminal, build, and self-verify each slice before calling it done. When the person explicitly asks you to launch a SEPARATE Cascade/conductor terminal, call open_main_terminal instead; never represent that request with spawn_terminal. Worker, leaf, Side, and managed Flow lanes complete their assigned work directly and do not fan out.',
       'CRUCIAL RECONCILIATION for that workflow: it is NOT plan mode. Never call ExitPlanMode and never make the room wait behind a "plan ready — approve to start" card — your plan lives in the CHAT as a message, and your lanes live in the room\'s EXISTING terminal/lane list. Reuse only those two surfaces; there is no new Flow panel or mode to switch into, and you must not ask for one. Keep the plan and the lanes VISIBLE — that shared visibility is the whole point (it is the pair differentiator, and it catches bugs a single silent lane would hide); never collapse a decomposable build into one hidden lane just to look tidy.',
       ...THINKPOOL_REMOTE_DELIVERY_RULES,
       'CROSS-TERMINAL AWARENESS: this room may have other terminals open alongside yours — other agents working, or shells the people are driving. You have a READ-ONLY tool, read_terminal: call it with no arguments to list the other open terminals, or with a terminal ref/id/command to read that terminal\'s recent activity. Reach for it when your work depends on what another terminal is doing (e.g. someone says "see what the other terminal hit", or you need to coordinate with a sibling agent before acting). It only ever reads — it never changes another terminal. Identify a terminal by its NAME or its ref/id from the roster, never by an on-screen number like "Terminal 2" — those positional labels renumber when a terminal is closed, so they do not reliably point at a lane.',
       'CROSS-TERMINAL HAND-OFF: you also have post_to_terminal(terminal, text) to send a message or task to ANOTHER AGENT terminal in this room (not a plain shell). Use it sparingly and only when the people clearly want the lanes to coordinate — e.g. "tell the backend terminal the API is ready", or to hand a sibling agent a concrete task. Every post requires a person in the room to approve a card before it is delivered, and an agent that was itself reached via a cross-post cannot post onward — so do not rely on it for chit-chat or loops. Prefer read_terminal to understand a sibling before you ever post to it.',
-      'CROSS-TERMINAL SPAWN: only when your authoritative TERMINAL ROLE permits delegation, open YOUR OWN fresh lanes with spawn_terminal(name?, task?, model?, cascadeRole?). Declare cascadeRole="conductor" when the new visible terminal must decompose a Cascade and dispatch its own crew; declare cascadeRole="worker" for every direct slice lane. The bridge injects that identity before the child\'s first turn. Never ask a worker, leaf, Side, or managed Flow lane to pretend it is a conductor. Do not dump work into siblings that are already busy (a sibling is mid-task unless read_terminal shows it idle, and hijacking it derails their work). spawn_terminal opens a brand-new Claude lane and, if you pass `task`, hands it that task immediately; it appears as a new terminal in the room. A spawned lane INHERITS your current permission mode by default — so if you are in bypass, your lanes run autonomously with no per-action clicking; pass `mode` only to override. Raising a lane to bypass from a non-bypass lane asks the room to confirm once (everything else spawns without a prompt). Collect each lane\'s result later with read_terminal (a spawned lane cannot post back to you). CLOSING IS PART OF THE JOB, not housekeeping you get to skip: the moment you have read a lane\'s result and acted on it, close_terminal it. A finished lane left open holds a slot against the room\'s machine cap and against your dispatch ceiling, so the NEXT fan-out — yours, or a person\'s — gets refused; rooms silt up with dead lanes exactly this way. Before each new wave of spawns, list your open lanes (read_terminal with no argument) and close the finished ones first. If a spawn is refused for capacity, the refusal names your own idle lanes so you do not have to hunt. You may only close lanes you spawned yourself — never close a sibling\'s, and never close one that is mid-turn. You are bounded: a sliding spawn-burst window, a per-plan dispatch ceiling on concurrent spawned lanes (Free 3 / Plus 6) that is separate from the human terminals so it never blocks them, an overall machine cap on live lanes, and a DEPTH bound — a lane opened by a person may spawn workers, and those workers may spawn one further level (a conductor dispatching its crew), but that second level can never spawn onward (so no runaway). This is how you "open the terminals yourself" instead of asking a person to.',
+      'TERMINAL CREATION CONTRACT: conductors and workers use different tools. When a person explicitly asks to open, launch, start, or spawn a separate Cascade/conductor terminal, use open_main_terminal(name?, task?, model?) — it creates an independent MAIN terminal with no Ensemble owner. Never use spawn_terminal for that request, and if open_main_terminal is unavailable say so instead of substituting. Use spawn_terminal(name?, task?, model?, sliceType?) only for bounded WORKER SUB-TERMINALS when your authoritative role permits delegation. Workers never receive the creation tools and never conduct. Do not dump work into busy siblings. Spawned workers inherit your permission mode by default; raising one to bypass asks the room once. Collect each worker with read_terminal and close_terminal immediately after using its result. Main conductors are independent terminals and are not owned/closed through Ensemble. Room caps and the kill-switch bind both creation paths.',
       'CROSS-SESSION AWARENESS: the Ensemble reaches across your SESSIONS, not just the terminals in this room. list_sessions() lists your OTHER ThinkPool Code rooms — both your own rooms running on this machine AND your partner\'s rooms in the same pair, reachable over the per-pair bus (a room on the partner\'s machine shows its host). read_session(session, terminal?) reads recent activity inside one (omit `terminal` to list that room\'s terminals, or pass a ref/name to read that lane). Both are READ-ONLY — they never change another session, and they reach ONLY your own rooms and rooms you share with your partner, never a stranger\'s. Reach for them when work spans rooms — "what\'s the other project up to", "pick up where the other session left off", or to check a long-running task elsewhere before you act here.',
       'CROSS-SESSION HAND-OFF: post_to_session(session, text, terminal?) sends a task or message to an agent in ANOTHER of your rooms — your own, or your partner\'s over the pair bus. Use it sparingly and only when the people clearly want the rooms to coordinate — e.g. hand the API room\'s agent a concrete follow-up once the frontend is ready. It is dual-consent: a person in YOUR room approves sending, and a person in the TARGET room approves receiving, before anything is delivered — so never rely on it for chit-chat or loops, and an agent that was itself reached via a cross-room post cannot post onward to a third room. It spends real model tokens in the other room (maybe on the other person\'s machine), so prefer read_session to understand a room before you ever post into it, and only post one concrete hand-off at a time. All of this works only under the ThinkPool account bridge; a standalone room sees just its own terminals.',
-      'SUBAGENT POLICY: in this room, delegated work goes through the Ensemble only from a conductor-capable TERMINAL ROLE. When such a role fans out research, parallel sub-tasks, reviews, or substantive multi-step work, open visible spawn_terminal lanes with explicit cascadeRole metadata. Worker, leaf, Side, and managed Flow lanes do their assigned work directly. Do NOT reach for the built-in Task/Agent subagents: an in-process subagent is invisible to the room, cannot be peered at or steered, and its work is lost to the Ensemble.',
+      'SUBAGENT POLICY: in this room, a main conductor delegates worker slices through visible spawn_terminal Ensemble lanes. A requested separate conductor is created with open_main_terminal, never Ensemble. Worker, leaf, Side, and managed Flow lanes do their assigned work directly. Do NOT reach for built-in Task/Agent subagents: an in-process subagent is invisible to the room, cannot be peered at or steered, and its work is lost to the Ensemble.',
       'RESEARCH LANE: you have a `research` tool that runs a REAL multi-source web search + adversarial verification and returns each claim marked HELD or REJECTED with citations. Reach for it when the people would genuinely benefit from looking something external up or settling a question of current fact — pricing, "is X still maintained / deprecated", "is that benchmark real", a debate over facts you are not sure of. Do NOT run it unprompted or for things you already know: first OFFER in plain language ("want me to spawn a research lane on that and check it?"), and only call `research(question)` once they agree — it spends real budget (plan-gated Free 5 / Plus 100 runs a month) and takes ~a minute. When it returns, present the held/rejected findings clearly and invite both people to weigh the sources, flagging any held claim that rests on a source they might not trust — that shared scrutiny is the point.',
       'PEER FIRST: other lanes may be working in the same repo as you, right now. Before starting substantive work — and before any code edit that could overlap another lane — check what the room is doing: the ROOM NOW snapshot appended to your latest turn, or read_terminal for detail; list_sessions/read_session when the question spans your other rooms. If a sibling is touching the same files or branch, coordinate (read its lane, or raise it in chat) instead of colliding.',
       'WORKTREES: parallel lanes share one machine and usually one repo. Run `git worktree list` before your first code edit; if linked worktrees exist, the shared main checkout is contended (and may be guard-blocked) — do your work in your OWN worktree on your OWN branch (`git worktree add <dir> -b <branch>`), and never edit a checkout or ride a branch another lane is using.',

package/codex-session.mjs

@@ -210,7 +210,7 @@ export function codexPublishAccess({ cwd, env = process.env, tmpdir = os.tmpdir(
 }
 
 export const CODEX_ROOM_CASCADE_REMINDER = [
-  'THINKPOOL ROOM WORKFLOW: obey the authoritative TERMINAL ROLE above. Only a role permitted to delegate may open visible spawn_terminal lanes; leaf, Side, and managed Flow lanes must do their assigned work directly. Never use hidden in-process subagents. When opening a Cascade conductor, pass cascadeRole="conductor"; that conductor must pass cascadeRole="worker" for its slice lanes so each child receives the correct identity in its first system preamble. Each delegated lane owns its own worktree. For a genuinely decomposable task in a conductor-capable role, state a short plan in chat, use sliceType scaffold for mechanical work, feature/fix for builders, and review for adversarial verification; review must use a balanced model tier. Read results, verify the integrated outcome, and close every lane you spawned so it does not consume room capacity.',
+  'THINKPOOL ROOM WORKFLOW: obey the authoritative TERMINAL ROLE above. Conductors are independent main terminals; Ensemble lanes are workers only. When a person explicitly asks to open, launch, start, or spawn a separate Cascade/conductor terminal, use open_main_terminal — NEVER spawn_terminal. Use spawn_terminal only for worker slices from a role permitted to delegate. If open_main_terminal is unavailable, say so; never substitute an Ensemble child. Leaf, worker, Side, and managed Flow lanes work directly and must not delegate. Never use hidden in-process subagents. Each worker owns its own worktree. For a genuinely decomposable task in a conductor-capable role, state a short plan in chat, use sliceType scaffold for mechanical work, feature/fix for builders, and review for adversarial verification; review must use a balanced model tier. Read results, verify the integrated outcome, and close every worker you spawned.',
 ].join(' ')
 
 export function buildCodexPrompt({ text, terminalRolePrompt, rolePrompt, roomContext, firstTurn = false }) {

package/cross-terminal.mjs

@@ -301,8 +301,9 @@ export const crossPostNeedsCard = ({ mode = 'default', spawnedByMe = false } = {
 // OWN lanes. spawn_terminal gives it fresh lanes; this gate keeps that from
 // becoming a fork bomb. Bounds, in order:
 //   • kill-switch (TP_SPAWN_OFF)
-//   • hop — a lane REACHED via cross-post/spawn (hop ≥ 1) cannot spawn onward, so
-//     a spawned agent can't recursively spawn (the loop breaker, mirrors CROSSPOST)
+//   • hop — a lane REACHED via cross-post/spawn (hop ≥ 1) cannot spawn onward.
+//     Cascade conductors now use the independent main-terminal lifecycle; every
+//     Ensemble-spawned lane is a worker (the loop breaker mirrors CROSSPOST).
 //   • machineMax — overall hard cap on LIVE lanes (sessions+terms): the runaway /
 //     don't-melt-the-laptop backstop, plan-INDEPENDENT.
 //   • dispatch ceiling — a SEPARATE, plan-tiered budget counting ONLY spawned lanes
@@ -323,12 +324,9 @@ export const crossPostNeedsCard = ({ mode = 'default', spawnedByMe = false } = {
 // this stays a PURE function (no Date.now inside; the clock is injected, like
 // spawnCount was before).
 export const SPAWN = {
-  maxHop: 2,               // human turn = hop 0; its spawned lane (hop 1, a "conductor") MAY spawn
-                           // workers (hop 2); hop ≥ 2 can never spawn onward. Depth-2 cascades,
-                           // fork-bomb still impossible by construction — every level also passes
-                           // machineMax + the plan ceiling + the burst window + the kill-switch.
-                           // Was 1 until 2026-07-10 (docs/specs/2026-07-10-cascade-spawn-depth.md):
-                           // conductors dispatched by a person's lane could not dispatch at all.
+  maxHop: 1,               // main terminal/conductor = hop 0 and may dispatch workers;
+                           // Ensemble worker = hop 1 and can never spawn onward. Conductors
+                           // are created via open_main_terminal, not spawn_terminal.
   perWindowCap: 6,         // spawn_terminal calls allowed per rolling window (burst breaker);
                            // 6 matches plusMaxSpawned so one wave can open a full crew (was 4)
   windowMs: 10 * 60 * 1000, // sliding window over which perWindowCap applies (10 min)

package/hermes-delegation-guard.mjs

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+// Hermes shell hook: the ACP toolset currently includes delegate_task and ACP
+// has no per-session tool exclusion. Block it before execution so all delegated
+// work remains a visible ThinkPool lane.
+let input = ''
+process.stdin.setEncoding('utf8')
+process.stdin.on('data', (chunk) => { input += chunk })
+process.stdin.on('end', () => {
+  let payload = null
+  try { payload = JSON.parse(input) } catch { /* malformed hook input fails closed below */ }
+  const blocking = !payload || payload.tool_name === 'delegate_task'
+  process.stdout.write(JSON.stringify(blocking
+    ? { action: 'block', message: 'ThinkPool blocks hidden Hermes delegation. Open visible ThinkPool lanes instead.' }
+    : {}) + '\n')
+})

package/hermes-event-mapper.mjs

@@ -0,0 +1,131 @@
+const textOf = (content) => {
+  if (typeof content === 'string') return content
+  if (content?.type === 'text') return String(content.text || '')
+  if (content?.type === 'content') return textOf(content.content)
+  return ''
+}
+const outputText = (update) => {
+  if (typeof update?.rawOutput === 'string') return update.rawOutput
+  const text = (update?.content || []).map(textOf).filter(Boolean).join('\n')
+  if (text) return text
+  if (update?.rawOutput != null) {
+    try { return JSON.stringify(update.rawOutput) } catch { return String(update.rawOutput) }
+  }
+  return ''
+}
+
+export function hermesToolFor(update = {}) {
+  const kind = String(update.kind || '').toLowerCase()
+  const title = String(update.title || '')
+  const raw = update.rawInput && typeof update.rawInput === 'object' ? update.rawInput : {}
+  const terminal = (update.content || []).find((part) => part?.type === 'terminal')
+  const shellText = (update.content || []).map(textOf).find((text) => text.trim().startsWith('$ '))
+  const location = update.locations?.[0]?.path
+  if (kind === 'execute' || terminal || shellText) return { name: 'Bash', input: { ...raw, command: raw.command || shellText?.trim().slice(2) || title } }
+  if (kind === 'edit') return { name: title.toLowerCase().includes('write') ? 'Write' : 'Edit', input: { ...raw, file_path: raw.path || location || '', path: raw.path || location || '' } }
+  if (kind === 'read') return { name: 'Read', input: { ...raw, file_path: raw.path || location || '', path: raw.path || location || '' } }
+  if (kind === 'search') return { name: 'Grep', input: raw }
+  if (kind === 'fetch') return { name: 'WebFetch', input: raw }
+  return { name: title || 'HermesTool', input: raw }
+}
+
+export class HermesEventMapper {
+  constructor({ onEvent, sessionId = null, model = null } = {}) {
+    this.onEvent = onEvent
+    this.sessionId = sessionId
+    this.model = model
+    this.tools = new Map()
+    this.text = ''
+    this.thought = ''
+    this.textCid = null
+  }
+
+  _emit(event) { try { this.onEvent?.(event) } catch { /* consumer isolation */ } }
+
+  startSession({ sessionId, models, modes, commands = [] } = {}) {
+    this.sessionId = sessionId || this.sessionId
+    this.model = models?.currentModelId || this.model
+    const list = (models?.availableModels || []).map((item) => ({ value: item.modelId, displayName: item.name || item.modelId, description: item.description || '' }))
+    this._emit({ kind: 'system', sessionId: this.sessionId, model: this.model, commands, models: list, modes })
+    if (list.length) this._emit({ kind: 'models', models: list, model: this.model })
+  }
+
+  push(params = {}) {
+    if (params.sessionId && this.sessionId && params.sessionId !== this.sessionId) return
+    const update = params.update || params
+    switch (update.sessionUpdate) {
+      case 'agent_message_chunk': {
+        const chunk = textOf(update.content)
+        if (!chunk) return
+        this.text += chunk
+        this.textCid ||= `hermes-stream:${this.sessionId || 'session'}:${Date.now()}`
+        this._emit({ kind: 'assistant_stream', cid: this.textCid, text: this.text, streaming: true })
+        return
+      }
+      case 'agent_thought_chunk':
+        this.thought += textOf(update.content)
+        return
+      case 'tool_call': {
+        const tool = hermesToolFor(update)
+        this.tools.set(update.toolCallId, { ...update, ...tool, startedAt: Date.now() })
+        this._emit({ kind: 'assistant', blocks: [{ type: 'tool_use', id: update.toolCallId, name: tool.name, input: tool.input }], parentToolUseId: null })
+        return
+      }
+      case 'tool_call_update': {
+        const prior = this.tools.get(update.toolCallId) || {}
+        const merged = { ...prior, ...update }
+        this.tools.set(update.toolCallId, merged)
+        if (!['completed', 'failed'].includes(update.status)) return
+        this._emit({
+          kind: 'tool_result', toolUseId: update.toolCallId,
+          content: [{ type: 'text', text: outputText(merged) }],
+          isError: update.status === 'failed',
+          durationMs: prior.startedAt ? Date.now() - prior.startedAt : undefined,
+          parentToolUseId: null,
+        })
+        this.tools.delete(update.toolCallId)
+        return
+      }
+      case 'usage_update': {
+        const used = Number(update.used) || 0
+        const max = Number(update.size) || 0
+        this._emit({ kind: 'usage', ctx: { used, max, pct: max ? Math.min(100, Math.round((used / max) * 100)) : 0, over: max > 0 && used > max, model: this.model } })
+        return
+      }
+      case 'available_commands_update':
+        this._emit({ kind: 'system', sessionId: this.sessionId, model: this.model, commands: (update.availableCommands || []).map((command) => `/${command.name}`) })
+        return
+      case 'current_mode_update':
+        this._emit({ kind: 'mode', mode: update.currentModeId })
+        return
+      case 'plan': {
+        const todos = (update.entries || []).map((entry) => ({ content: entry.content || '', activeForm: entry.content || '', status: entry.status === 'in_progress' ? 'in_progress' : entry.status === 'completed' ? 'completed' : 'pending' }))
+        this._emit({ kind: 'assistant', blocks: [{ type: 'tool_use', id: `hermes-plan:${this.sessionId}`, name: 'TodoWrite', input: { todos } }], parentToolUseId: null })
+        return
+      }
+      default:
+        return
+    }
+  }
+
+  finishTurn({ stopReason = 'end_turn', usage = null } = {}) {
+    const blocks = []
+    if (this.thought) blocks.push({ type: 'thinking', text: this.thought })
+    if (this.text) blocks.push({ type: 'text', text: this.text })
+    if (blocks.length) this._emit({ kind: 'assistant', blocks, parentToolUseId: null, ...(this.textCid ? { replacesCid: this.textCid } : {}) })
+    this._emit({
+      kind: 'result', subtype: stopReason === 'cancelled' ? 'aborted' : stopReason === 'end_turn' ? 'success' : 'error_during_execution',
+      sessionId: this.sessionId, model: this.model, costUsd: null,
+      usage: usage ? {
+        input_tokens: Number(usage.inputTokens) || 0,
+        cache_read_input_tokens: Number(usage.cachedReadTokens) || 0,
+        cache_creation_input_tokens: 0,
+        output_tokens: (Number(usage.outputTokens) || 0) + (Number(usage.thoughtTokens) || 0),
+      } : null,
+      numTurns: 1, durationMs: undefined, denials: 0, resultText: this.text || null,
+    })
+    this.text = ''
+    this.thought = ''
+    this.textCid = null
+  }
+}

package/hermes-probe.mjs

@@ -0,0 +1,20 @@
+import { execFileSync } from 'node:child_process'
+
+const clean = (value) => String(value || '').replace(/[\r\n]+/g, ' ').trim()
+
+export function probeHermesRuntime({ command = 'thinkpool', execFile = execFileSync, env = process.env } = {}) {
+  try {
+    const versionOutput = execFile(command, ['--version'], { encoding: 'utf8', env, timeout: 10_000, stdio: ['ignore', 'pipe', 'pipe'] })
+    const version = clean(versionOutput).match(/Hermes Agent v([^\s]+)/i)?.[1] || null
+    execFile(command, ['acp', '--check'], { encoding: 'utf8', env, timeout: 15_000, stdio: ['ignore', 'pipe', 'pipe'] })
+    const hooksOutput = execFile(command, ['hooks', 'list'], { encoding: 'utf8', env, timeout: 10_000, stdio: ['ignore', 'pipe', 'pipe'] })
+    const guardOutput = execFile(command, ['hooks', 'test', 'pre_tool_call', '--for-tool', 'delegate_task'], { encoding: 'utf8', env, timeout: 10_000, stdio: ['ignore', 'pipe', 'pipe'] })
+    const delegationBlocked = /(?:action|decision)["']?\s*[:=]\s*["']block/i.test(guardOutput)
+      && /ThinkPool blocks hidden Hermes delegation/i.test(guardOutput)
+      && /pre_tool_call[\s\S]*delegate_task[\s\S]*(?:✓ allowed|allowed)/i.test(hooksOutput)
+    if (!delegationBlocked) return { available: false, version, reason: 'delegate_task is not structurally blocked by the dedicated Hermes profile' }
+    return { available: true, version, acpProtocol: 1, delegationBlocked: true }
+  } catch (error) {
+    return { available: false, version: null, reason: clean(error?.stderr || error?.message || error) }
+  }
+}

package/hermes-session.mjs

@@ -0,0 +1,246 @@
+// Hermes Agent structured runtime over the official ACP stdio transport.
+// Implements the same narrow session contract as claude-session/codex-session.
+import fs from 'node:fs'
+import path from 'node:path'
+import { randomUUID } from 'node:crypto'
+import { AcpClient } from './acp-client.mjs'
+import { HermesEventMapper, hermesToolFor } from './hermes-event-mapper.mjs'
+import { probeHermesRuntime } from './hermes-probe.mjs'
+import { startCodexMcpHttp } from './codex-mcp-http.mjs'
+import { classifyRisk } from './claude-session.mjs'
+
+export const HERMES_COMMAND = 'thinkpool'
+export const HERMES_ACP_PROTOCOL_VERSION = 1
+export const HERMES_SUPPORTED_MODES = new Set(['default', 'acceptEdits'])
+
+const HERMES_SECRET_ENV_KEY = /(?:TOKEN|SECRET|PASSWORD|PRIVATE_KEY|API_KEY|ACCESS_KEY|CREDENTIAL)/i
+export const hermesChildEnv = (env = {}) => Object.fromEntries(
+  Object.entries(env).filter(([key]) => !HERMES_SECRET_ENV_KEY.test(key)),
+)
+
+const imageBlock = (imagePath) => {
+  const ext = path.extname(imagePath).toLowerCase()
+  const mimeType = ext === '.png' ? 'image/png' : ext === '.webp' ? 'image/webp' : ext === '.gif' ? 'image/gif' : 'image/jpeg'
+  return { type: 'image', mimeType, data: fs.readFileSync(imagePath).toString('base64') }
+}
+
+const modelList = (state) => (state?.availableModels || []).map((item) => ({ value: item.modelId, displayName: item.name || item.modelId, description: item.description || '' }))
+
+const mcpDescriptor = (url) => ({ type: 'http', name: 'thinkpool', url, headers: [] })
+const createAcpClient = (options) => new AcpClient(options)
+
+const permissionOutcome = (decision, options = []) => {
+  if (decision === 'deny' || !decision) return { outcome: 'cancelled' }
+  const preferred = decision === 'always'
+    ? ['allow_always', 'allow_session', 'allow_once']
+    : ['allow_once', 'allow_session', 'allow_always']
+  const option = preferred.map((kind) => options.find((item) => item.kind === kind || item.optionId === kind)).find(Boolean)
+    || options.find((item) => String(item.kind || '').startsWith('allow'))
+  return option ? { outcome: 'selected', optionId: option.optionId } : { outcome: 'cancelled' }
+}
+
+export function startHermesSession({
+  cwd, model, resume, env = process.env, mode = 'default', onEvent, requestPermission,
+  roomContext, terminalRolePrompt, rolePrompt, mcpServers, prepareCwd = null,
+  command = HERMES_COMMAND, args = ['acp'], clientFactory = createAcpClient,
+  mcpHttpFactory = startCodexMcpHttp, lazy = false,
+} = {}) {
+  let activeCwd = cwd
+  const requestedModel = model || null
+  let activeModel = requestedModel
+  let activeMode = HERMES_SUPPORTED_MODES.has(mode) ? mode : 'default'
+  let sessionId = resume || null
+  let client = null
+  let mapper = null
+  let mcpHttp = null
+  let starting = null
+  let ended = false
+  let turnActive = false
+  let started = false
+  let crashed = false
+  let firstTurn = true
+  let stderrTail = ''
+  let promptChain = Promise.resolve()
+
+  const emit = (event) => { try { onEvent?.(event) } catch { /* consumer isolation */ } }
+
+  async function onRequest(method, params, requestId) {
+    if (method !== 'session/request_permission') throw Object.assign(new Error(`Unsupported ACP client method: ${method}`), { code: -32601 })
+    const tool = hermesToolFor(params.toolCall || mapper?.tools.get(params.toolCallId) || {})
+    const card = {
+      id: `hermes-perm:${requestId}`,
+      toolName: tool.name,
+      input: tool.input,
+      risk: classifyRisk(tool.name, tool.input),
+    }
+    let decision = 'deny'
+    try { decision = await requestPermission?.(card) } catch { /* fail closed */ }
+    return { outcome: permissionOutcome(decision, params.options) }
+  }
+
+  function onNotification(method, params) {
+    if (method === 'session/update') mapper?.push(params)
+  }
+
+  async function boot() {
+    if (ended) throw new Error('Hermes session is closed')
+    if (crashed) throw new Error('Hermes ACP process crashed; this lane must be restarted before sending another turn')
+    if (client?.alive && mapper) return
+    if (starting) return starting
+    starting = (async () => {
+      if (!started && prepareCwd) {
+        try { activeCwd = prepareCwd() || activeCwd } catch { /* retain original cwd */ }
+      }
+      const thinkpool = mcpServers?.thinkpool
+      if (thinkpool && !mcpHttp) mcpHttp = await mcpHttpFactory({ sdkServer: thinkpool })
+      const childEnv = hermesChildEnv(env)
+      // The bridge advertises Hermes only after this probe, but lazy lanes may
+      // boot much later. Re-check immediately before every real ACP process so
+      // a removed/changed delegation hook cannot ride a stale startup verdict.
+      if (command === HERMES_COMMAND && clientFactory === createAcpClient) {
+        const profile = probeHermesRuntime({ command, env: childEnv })
+        if (!profile.available) throw new Error(`Hermes profile safety check failed: ${profile.reason || 'runtime unavailable'}`)
+      }
+      client = clientFactory({
+        command, args, cwd: activeCwd, env: childEnv,
+        onNotification,
+        onRequest,
+        onStderr: (text) => { stderrTail = (stderrTail + text).slice(-2000) },
+        onClose: (error) => {
+          if (ended || crashed) return
+          crashed = true
+          turnActive = false
+          emit({ kind: 'error', message: `Hermes ACP closed unexpectedly: ${error?.message || error}`, recoverable: true })
+        },
+      })
+      client.start()
+      const initialized = await client.request('initialize', {
+        protocolVersion: HERMES_ACP_PROTOCOL_VERSION,
+        clientCapabilities: { fs: { readTextFile: false, writeTextFile: false }, terminal: false },
+        clientInfo: { name: 'thinkpool-pair', title: 'ThinkPool Code', version: '1' },
+      })
+      if (initialized?.protocolVersion !== HERMES_ACP_PROTOCOL_VERSION) {
+        throw new Error(`Unsupported Hermes ACP protocol ${initialized?.protocolVersion ?? 'unknown'}; expected ${HERMES_ACP_PROTOCOL_VERSION}`)
+      }
+      const params = { cwd: path.resolve(activeCwd), mcpServers: mcpHttp ? [mcpDescriptor(mcpHttp.url)] : [] }
+      mapper = new HermesEventMapper({ onEvent: emit, sessionId, model: activeModel })
+      let state
+      if (sessionId) {
+        if (!initialized?.agentCapabilities?.sessionCapabilities?.resume) {
+          throw new Error(`Hermes session ${sessionId} cannot be resumed by this ACP release; no fresh session was substituted`)
+        }
+        try { state = await client.request('session/resume', { ...params, sessionId }, 30_000) }
+        catch (error) {
+          throw new Error(`Hermes session ${sessionId} is not available; no fresh session was substituted (${error?.message || error})`)
+        }
+      } else state = await client.request('session/new', params, 30_000)
+      if (!sessionId) sessionId = state?.sessionId || null
+      if (!sessionId) throw new Error('Hermes ACP did not return a session id')
+      const serverModel = state?.models?.currentModelId || null
+      activeModel = requestedModel || serverModel || activeModel
+      mapper.startSession({ sessionId, models: state?.models, modes: state?.modes, commands: [] })
+      started = true
+      if (requestedModel && serverModel && requestedModel !== serverModel) {
+        await client.request('session/set_model', { sessionId, modelId: activeModel })
+      }
+      const acpMode = activeMode === 'acceptEdits' ? 'accept_edits' : 'default'
+      if (state?.modes?.availableModes?.some((item) => item.id === acpMode) && state.modes.currentModeId !== acpMode) {
+        await client.request('session/set_mode', { sessionId, modeId: acpMode })
+      }
+      emit({ kind: 'capabilities', runtime: 'hermes', protocol: 'acp', protocolVersion: initialized?.protocolVersion, capabilities: initialized?.agentCapabilities || {}, models: modelList(state?.models), flow: false })
+    })().catch((error) => {
+      crashed = true
+      client?.end()
+      void mcpHttp?.close().catch(() => {})
+      emit({ kind: 'error', message: `Hermes ACP startup failed: ${error?.message || error}${stderrTail ? `: ${stderrTail.trim().slice(-240)}` : ''}`, recoverable: true })
+      throw error
+    }).finally(() => { starting = null })
+    return starting
+  }
+
+  function promptBlocks(text, options = {}) {
+    const rawText = String(text)
+    // Hermes handles /steer, /queue, /compact and /reset only when the slash is
+    // the first character of a pure-text prompt.
+    if (/^\s*\//.test(rawText)) return [{ type: 'text', text: rawText }]
+    const context = typeof roomContext === 'function' ? roomContext() : roomContext
+    const preamble = firstTurn ? [terminalRolePrompt, rolePrompt, context].filter(Boolean).join('\n\n') : context
+    const blocks = [{ type: 'text', text: preamble ? `${preamble}\n\n${rawText}` : rawText }]
+    for (const imagePath of (Array.isArray(options.images) ? options.images : [])) {
+      try { blocks.push(imageBlock(imagePath)) } catch { /* quoted host path remains in text */ }
+    }
+    return blocks
+  }
+
+  async function runPrompt(text, options = {}) {
+    await boot()
+    const steering = turnActive
+    const body = steering ? `/steer ${String(text)}` : String(text)
+    if (!steering) turnActive = true
+    const result = await client.request('session/prompt', {
+      sessionId,
+      prompt: promptBlocks(body, options),
+      messageId: randomUUID(),
+    }, 0)
+    if (!steering) {
+      turnActive = false
+      firstTurn = false
+      mapper.finishTurn({ stopReason: result?.stopReason, usage: result?.usage })
+    }
+    return result
+  }
+
+  if (!lazy) queueMicrotask(() => { void boot().catch(() => {}) })
+
+  return {
+    get sessionId() { return sessionId },
+    get turnActive() { return turnActive },
+    get canSteer() { return !!client?.alive },
+    get started() { return started },
+    get models() { return [] },
+    sendTurn(text, options = {}) {
+      if (ended || crashed) return false
+      // A busy prompt is a genuine ACP /steer call and may run concurrently.
+      if (turnActive) { void runPrompt(text, options).catch((error) => emit({ kind: 'error', message: `Hermes steering failed: ${error?.message || error}`, recoverable: true })); return true }
+      promptChain = promptChain.then(() => runPrompt(text, options)).catch((error) => {
+        turnActive = false
+        emit({ kind: 'error', message: `Hermes turn failed: ${error?.message || error}`, recoverable: true })
+      })
+      return true
+    },
+    abort() {
+      if (!sessionId || !client?.alive) return
+      void client.notify('session/cancel', { sessionId }).catch(() => { /* process already closed */ })
+    },
+    end() {
+      ended = true
+      turnActive = false
+      if (sessionId && client?.alive) void client.request('session/close', { sessionId }, 1500).catch(() => {}).finally(() => client?.end())
+      else client?.end()
+      void mcpHttp?.close().catch(() => {})
+    },
+    setModel(nextModel) {
+      if (!nextModel || turnActive) return false
+      void boot().then(() => client.request('session/set_model', { sessionId, modelId: String(nextModel) })).then(() => {
+        activeModel = String(nextModel)
+        if (mapper) mapper.model = activeModel
+        emit({ kind: 'note', text: `model → ${activeModel}` })
+      }).catch((error) => emit({ kind: 'error', message: `Hermes model switch failed: ${error?.message || error}`, recoverable: true }))
+      return true
+    },
+    setMode(nextMode) {
+      if (turnActive || !HERMES_SUPPORTED_MODES.has(nextMode)) return false
+      void boot().then(() => client.request('session/set_mode', { sessionId, modeId: nextMode === 'acceptEdits' ? 'accept_edits' : 'default' })).then(() => {
+        activeMode = nextMode
+        emit({ kind: 'mode', mode: activeMode })
+      }).catch((error) => emit({ kind: 'error', message: `Hermes mode switch failed: ${error?.message || error}`, recoverable: true }))
+      return true
+    },
+    setEffort() { return false },
+    clearContext() {
+      if (turnActive) return false
+      return this.sendTurn('/reset')
+    },
+    warm() { void boot().catch(() => {}) },
+  }
+}

package/interrupted-resume.mjs

@@ -52,12 +52,24 @@ export function isMissingResumeError(message) {
   return /No conversation found|no rollout found for thread id|thread\/resume[^\n]*failed[^\n]*no rollout/i.test(String(message || ''))
 }
 
+export function shouldAttemptNativeResume(record, { canResume = () => false, codexThreadCanResume = () => true } = {}) {
+  if (!record?.sessionId) return false
+  // Hermes has an explicit, non-replaying ACP resume request that fails loudly
+  // when identity is gone. Always ask the runtime instead of silently aging the
+  // identity out under Claude's historical local freshness heuristic.
+  if (record.runtime === 'hermes') return true
+  return canResume(record) && (record.runtime !== 'codex' || codexThreadCanResume(record.sessionId))
+}
+
 // Bound the stale-native-thread self-heal at the ownership seam. The old entry is
 // marked before teardown/reopen so duplicate error delivery can never fork another
 // process. `reopen` returns the new structured entry; Codex consumes the recap
 // immediately because a fresh exec has no idle init event.
 export function recoverMissingResumeOnce(entry, { message, recap = '', reopen } = {}) {
-  if (!entry || entry.recovered || !isMissingResumeError(message)) return { recovered: false, delivery: 'ignored' }
+  // Hermes ACP session identity is part of the lane contract. If native resume
+  // fails, surfacing that failure is safer than silently replacing the session
+  // with a recap-backed fresh identity.
+  if (!entry || entry.runtime === 'hermes' || entry.recovered || !isMissingResumeError(message)) return { recovered: false, delivery: 'ignored' }
   entry.recovered = true
   try { entry.session?.end?.() } catch { /* already dead */ }
   let recovered = null

package/launcher.mjs

@@ -27,6 +27,7 @@ const VERSION = (() => { try { return JSON.parse(fs.readFileSync(new URL('./pack
 export const KNOWN_AGENTS = [
   { label: 'Claude Code', cmd: 'claude', resume: ['--continue'] },
   { label: 'Codex CLI',   cmd: 'codex' },
+  { label: 'Hermes Agent', cmd: 'thinkpool' },
   { label: 'Gemini CLI',  cmd: 'gemini' },
   { label: 'Aider',       cmd: 'aider' },
   { label: 'Cursor CLI',  cmd: 'cursor-agent' },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thinkpool-pair",
-  "version": "0.7.232",
+  "version": "0.7.234",
   "description": "Share a local coding-agent CLI (Claude Code, Codex, Gemini, Aider, …) into a ThinkPool Code room, live.",
   "type": "module",
   "bin": {
@@ -20,6 +20,13 @@
     "codex-mcp-http.mjs",
     "lane-worktree.mjs",
     "codex-event-mapper.mjs",
+    "acp-client.mjs",
+    "hermes-session.mjs",
+    "hermes-event-mapper.mjs",
+    "hermes-probe.mjs",
+    "hermes-delegation-guard.mjs",
+    "runtime-registry.mjs",
+    "runtime-session.mjs",
     "turn-stall.mjs",
     "update-gate.mjs",
     "agent-notify.mjs",
@@ -70,6 +77,7 @@
     "node": ">=18"
   },
   "dependencies": {
+    "@agentclientprotocol/sdk": "1.2.1",
     "@anthropic-ai/claude-agent-sdk": "^0.3.198",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@supabase/supabase-js": "^2.45.0",