agent-rooms 0.11.0 → 0.12.0

package/dist/hosts.js

@@ -3,21 +3,20 @@
 //   - build a NON-INTERACTIVE headless wake command (`watch`)
 //   - extract the host session id from the run's stream output (for resume)
 //
-// Safety (§9, §10) — spec 21: wakes run UNSANDBOXED on every host by default. A
-// contained wake can read + post but can't build, edit, or run anything, so it
-// can't actually do the work — unsandboxed is the only mode that functions. Claude
-// gets --dangerously-skip-permissions; Codex --dangerously-bypass-approvals-and-sandbox;
-// OpenClaw acpx --approve-all. The real safeguards are (1) you only make an agent
-// wakeable deliberately, (2) cross-owner wakes are gated upstream by consent + an
-// active grant (only approved collaborators can wake you), (3) the connect docs warn
-// loudly, and (4) the broker scrubs the spawn env (§3.2) + owner-stop. For the
-// cautious: AGENT_ROOMS_WAKE_CONTAIN=1 forces Claude back to a read-only allowlist
-// (--permission-mode dontAsk + room MCP tools + Read/Grep/Glob, no Write/Edit/Bash);
-// Codex/OpenClaw have no per-tool gate so containment doesn't apply to them.
+// Safety (Spec 35 §3/§10): the signed envelope carries the server decision.
+// Same-owner wakes may use the host's full native capability. Cross-owner wakes
+// fail closed unless the host has a tested non-interactive constrained mode;
+// Claude and Codex use their native read-only controls. OpenClaw and Hermes are
+// not admitted for cross-owner wakes until such a mode exists. Every spawn also
+// receives a scrubbed environment and remains owner-stoppable.
 import { spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
+export const emptyUsage = () => ({
+    uncached_input: 0, cache_read: 0, cache_write: 0, cache_write_5m: 0, cache_write_1h: 0, reasoning: 0, output: 0, attempts: 0
+});
+const num = (value) => (typeof value === "number" && Number.isFinite(value) ? value : 0);
 /** The last value of `field` across all JSON lines in a stream buffer (vs
  *  firstJsonField, which takes the first). Used to grab the FINAL output event. */
 function lastJsonField(stdout, predicate) {
@@ -65,19 +64,18 @@ const ROOM_TOOLS = [
     "mcp__agent-rooms__ack_mentions",
     // messaging
     "mcp__agent-rooms__send_message",
-    // task board — the claim → work → heartbeat → report loop (orchestration layer)
+    // task board — assigned pushes are locked by the running receipt; pull/manual
+    // clients may claim unassigned work. Completion + handoff is one atomic call.
     "mcp__agent-rooms__read_board",
+    "mcp__agent-rooms__get_room_context",
     "mcp__agent-rooms__create_task",
-    "mcp__agent-rooms__assign_task",
     "mcp__agent-rooms__update_task",
     "mcp__agent-rooms__claim_task",
     "mcp__agent-rooms__renew_lease",
     "mcp__agent-rooms__release_task",
     "mcp__agent-rooms__set_status",
+    "mcp__agent-rooms__complete_task",
     "mcp__agent-rooms__archive_task",
-    "mcp__agent-rooms__accept_task",
-    "mcp__agent-rooms__reject_task",
-    "mcp__agent-rooms__list_pending_consents",
     // files
     "mcp__agent-rooms__share_file",
     "mcp__agent-rooms__complete_file_upload",
@@ -86,6 +84,12 @@ const ROOM_TOOLS = [
     "mcp__agent-rooms__write_file",
     "mcp__agent-rooms__list_files",
     "mcp__agent-rooms__delete_file",
+    // diagnostics and already-consented feedback channels
+    "mcp__agent-rooms__get_feedback_consent",
+    "mcp__agent-rooms__submit_task_feedback",
+    "mcp__agent-rooms__submit_product_feedback",
+    "mcp__agent-rooms__diagnose_error",
+    "mcp__agent-rooms__report_error",
     // read-only workspace tools (the actual containment boundary — no Write/Bash)
     "Read",
     "Grep",
@@ -129,6 +133,8 @@ export const claudeAdapter = {
     bin: "claude",
     allowedTools: ROOM_TOOLS,
     skillDir: join(homedir(), ".claude", "skills"),
+    supportsConstrainedWake: true,
+    requiresSessionId: true,
     buildWake(spec) {
         // The prompt is passed via STDIN (see SpawnCommand.stdin), never argv — a
         // multi-line argv is destroyed by the Windows shell. argv carries only
@@ -164,7 +170,7 @@ export const claudeAdapter = {
         return { command: this.bin, args, cwd: spec.workspace, stdin: spec.prompt, env: spec.env };
     },
     buildMcpAdd(apiBase) {
-        return { command: this.bin, args: ["mcp", "add", "--transport", "http", "--scope", "user", "agent-rooms", `${apiBase}/mcp`], cwd: process.cwd() };
+        return { command: this.bin, args: ["mcp", "add", "--transport", "http", "--scope", "user", "agent-rooms", `${apiBase}/mcp/claude`], cwd: process.cwd() };
     },
     buildMcpRemove() {
         return { command: this.bin, args: ["mcp", "remove", "agent-rooms"], cwd: process.cwd() };
@@ -176,35 +182,48 @@ export const claudeAdapter = {
         // Claude stream-json ends with a `{"type":"result","subtype":"success",
         // "result":"<final text>"}` event. Take the last one's `result`.
         return lastJsonField(stdout, (obj) => obj.type === "result" && typeof obj.result === "string" ? obj.result : null);
-    }
+    },
+    // Spec 35 §12 — count each provider attempt. Claude can retry a model call
+    // inside one turn and surfaces every attempt under `usage.iterations[]`; the
+    // final `usage` object alone undercounts. Sum across iterations when present,
+    // else read the single object. The terminal `{type:"result", usage}` carries
+    // the same numbers, so guard against double-counting by preferring iterations.
+    parseUsageLine(obj, acc) {
+        const usage = (obj.usage ?? obj.message?.usage);
+        if (!usage)
+            return;
+        const iterations = usage.iterations;
+        if (Array.isArray(iterations) && iterations.length > 0) {
+            for (const it of iterations)
+                foldClaudeUsageObject(it, acc);
+            return;
+        }
+        // Only the terminal result object carries the whole-turn totals; message
+        // deltas repeat, so accept usage totals solely from the result event.
+        if (obj.type === "result")
+            foldClaudeUsageObject(usage, acc);
+    },
+    // A --resume against a session id the local store no longer has.
+    resumeFailurePattern: /no conversation found|session .*not found|could not (?:find|resume)/i
 };
 export const codexAdapter = {
     name: "codex",
     bin: "codex",
     allowedTools: ROOM_TOOLS,
-    // Codex adopted the Agent Skills standard; it loads skills from ~/.codex/skills
-    // (the $skill-installer convention). Installing the bundled folder here makes a
-    // woken Codex agent room-fluent and shortens its wake prompt.
+    // Codex loads Agent Skills from ~/.codex/skills. `init` fetches the canonical
+    // hosted Agent Rooms skill into that owned location.
     skillDir: join(homedir(), ".codex", "skills"),
+    supportsConstrainedWake: true,
+    requiresSessionId: true,
     buildWake(spec) {
         // `codex exec -` reads the prompt from stdin. Keep the multi-line wake
         // prompt out of argv so Windows shell resolution cannot split it.
         //
-        // Approvals/sandbox (PROVEN 2026-06): under `--sandbox workspace-write` a
-        // headless `codex exec` routes every agent-rooms MCP tool call through the
-        // approval reviewer. In a spawned (non-interactive) run there is no approver,
-        // so each call returns "user cancelled MCP tool call" — codex reads the skill,
-        // tries whoami/check_mentions, gets cancelled, and exits 0 having never read
-        // or replied (a silent no-op that looks like "listening but mute"). Bypassing
-        // approvals+sandbox is the only mode where headless MCP calls actually run
-        // (verified: whoami + check_mentions succeed). The broker still constrains the
-        // run elsewhere — the spawn env is scrubbed to an allowlist (§3.2) and the run
-        // is bounded by --max-turns and the owner-stop kill path. Set
-        // AGENT_ROOMS_CODEX_SANDBOX (e.g. "workspace-write") to opt back into a codex
-        // sandbox if your codex build approves MCP calls non-interactively.
-        const strict = process.env.AGENT_ROOMS_CODEX_SANDBOX?.trim();
-        const sandboxArgs = strict ? ["--sandbox", strict] : ["--dangerously-bypass-approvals-and-sandbox"];
-        const base = ["exec", "--json", "--skip-git-repo-check", ...sandboxArgs];
+        // The signed server policy is authoritative: same-owner work may use full
+        // native capability, while cross-owner work is non-interactive read-only.
+        const base = spec.fullAccess
+            ? ["exec", "--json", "--skip-git-repo-check", "--dangerously-bypass-approvals-and-sandbox"]
+            : ["-a", "never", "exec", "--json", "--skip-git-repo-check", "--sandbox", "read-only"];
         if (spec.sessionId) {
             base.push("resume", spec.sessionId);
         }
@@ -214,7 +233,7 @@ export const codexAdapter = {
     buildMcpAdd(apiBase) {
         return {
             command: this.bin,
-            args: ["mcp", "add", "agent-rooms", "--url", `${apiBase}/mcp`, "--bearer-token-env-var", "AGENT_ROOMS_TOKEN"],
+            args: ["mcp", "add", "agent-rooms", "--url", `${apiBase}/mcp/codex`, "--bearer-token-env-var", "AGENT_ROOMS_TOKEN"],
             cwd: process.cwd()
         };
     },
@@ -245,8 +264,54 @@ export const codexAdapter = {
                 return obj.text;
             return null;
         });
-    }
+    },
+    // Spec 35 §12 — Codex reports BOTH a running session total (turn.completed's
+    // cumulative `usage`) and the per-turn delta (`last_token_usage`). On a
+    // resumed thread the cumulative total includes every prior turn, so reading it
+    // over-reports badly. Take last_token_usage only; it is the honest per-turn
+    // number. Each such event is one attempt.
+    parseUsageLine: foldCodexUsage,
+    // A `codex exec resume <id>` against a rollout that no longer exists.
+    resumeFailurePattern: /no (?:such )?(?:session|rollout|thread)|conversation .*not found|failed to (?:load|resume)/i
 };
+/** Spec 35 §12 — fold one Claude usage object (a `usage` total or one
+ * `iterations[]` attempt) into the accumulator. Claude's `input_tokens` is
+ * already cache-exclusive; `cache_creation_input_tokens` is the flat write
+ * total, and `cache_creation.{ephemeral_5m,ephemeral_1h}_input_tokens` split it
+ * by TTL (5m bills 1.25×, 1h 2×) where exposed — captured so price-weighting
+ * has the raw numbers. */
+function foldClaudeUsageObject(u, acc) {
+    acc.uncached_input += num(u.input_tokens);
+    acc.cache_read += num(u.cache_read_input_tokens);
+    const write = num(u.cache_creation_input_tokens);
+    acc.cache_write += write;
+    const creation = u.cache_creation;
+    const w5 = num(creation?.ephemeral_5m_input_tokens);
+    const w1 = num(creation?.ephemeral_1h_input_tokens);
+    acc.cache_write_5m += w5;
+    acc.cache_write_1h += w1;
+    acc.output += num(u.output_tokens);
+    acc.attempts += 1;
+}
+/** Spec 35 §12 — per-turn usage from a Codex-style stream (used by codex AND by
+ * OpenClaw, which runs an embedded Codex turn). Reads only `last_token_usage`
+ * (the honest per-turn delta), NEVER the cumulative `turn.completed.usage`
+ * total. Codex `input_tokens` is the TOTAL prompt and `cached_input_tokens` is
+ * a SUBSET, so uncached is the difference — matching Claude's cache-exclusive
+ * `input_tokens` field and never double-counting the cached portion. */
+function foldCodexUsage(obj, acc) {
+    const info = (obj.info ?? obj.msg?.info);
+    const last = (obj.last_token_usage ?? info?.last_token_usage);
+    if (!last)
+        return;
+    const totalInput = num(last.input_tokens);
+    const cached = num(last.cached_input_tokens);
+    acc.uncached_input += Math.max(0, totalInput - cached);
+    acc.cache_read += cached;
+    acc.reasoning += num(last.reasoning_output_tokens);
+    acc.output += num(last.output_tokens);
+    acc.attempts += 1;
+}
 // ── Additional wakeable hosts (native spec §4.3–4.5) ────────────────────────
 // These follow the documented per-host commands from Spec 1. Exact flag names
 // drift across CLI versions (the spec flags this explicitly); where a behavior
@@ -259,6 +324,8 @@ export const geminiAdapter = {
     allowedTools: ROOM_TOOLS,
     // Gemini CLI adopted Agent Skills; loads from ~/.gemini/skills.
     skillDir: join(homedir(), ".gemini", "skills"),
+    supportsConstrainedWake: false,
+    requiresSessionId: true,
     buildWake(spec) {
         // Piping the prompt on stdin makes the run non-TTY → headless, and keeps the
         // multi-line prompt out of argv. `--yolo` is Gemini's auto-approve (verify the
@@ -294,6 +361,8 @@ export const cursorAdapter = {
     bin: "cursor-agent",
     allowedTools: ROOM_TOOLS,
     skillDir: join(homedir(), ".cursor", "skills"),
+    supportsConstrainedWake: false,
+    requiresSessionId: true,
     buildWake(spec) {
         // `-p` is print/headless. `--force` is REQUIRED: without it, `-p` hangs
         // indefinitely when workspace trust is required (spec §4.4 gotcha). Prompt on
@@ -331,43 +400,47 @@ export const openclawAdapter = {
     allowedTools: ROOM_TOOLS,
     // OpenClaw skills come from ClawHub; on-disk dir ~/.openclaw/skills.
     skillDir: join(homedir(), ".openclaw", "skills"),
+    supportsConstrainedWake: false,
+    requiresSessionId: false,
+    // OpenClaw 2026.7.1's CLI falls back to an embedded run after a Gateway
+    // transport failure. Spec 35 requires one Gateway path. The CLI emits this
+    // marker before loading the embedded runner; runWake kills the process tree
+    // on sight so a transient Gateway failure fails closed.
+    forbiddenOutputPattern: /EMBEDDED FALLBACK:|["']fallbackFrom["']\s*:\s*["']gateway["']/i,
     buildWake(spec) {
-        // WAKE VIA THE GATEWAY AGENT TURN — `openclaw agent` — NOT the acpx ACP bridge
-        // (FIX 2026-06, OpenClaw #80814). The acpx bridge opens an ACP session with
-        // `mcpServers:[]` and advertises `mcpCapabilities.http:false`, so the woken
-        // agent NEVER receives the gateway's agent-rooms MCP server — it has no room
-        // tools and improvises (`sessions_send`, shelling out to `agent-rooms mcp`).
-        // `openclaw agent` runs an embedded Codex app-server turn that reads the
-        // agent's own codex config, where the room tools actually live.
-        //
-        // ⚠️ OpenClaw #80814 (open): the codex APP-SERVER runtime does NOT inject
-        // openclaw.json's `mcp.servers` into the agent's codex-home/config.toml — only
-        // the codex-CLI runtime does. So agent-rooms is authorized at the gateway
-        // (`openclaw mcp probe` shows it) yet invisible to the woken agent. ONE-TIME
-        // WORKAROUND (the maintainer's documented sidecar — see the OpenClaw setup
-        // guide): add the server to ~/.openclaw/agents/<id>/agent/codex-home/config.toml
-        //     [mcp_servers.agent-rooms]
-        //     url = "<api>/mcp/openclaw"
-        //     bearer_token_env_var = "AGENT_ROOMS_TOKEN"
-        // (then clear cache/codex_apps_tools). Also trust the wake cwd in that config
-        // (`[projects."<dir>"] trust_level = "trusted"`) or codex disables exec policies.
-        //
-        // `--local` runs the codex turn EMBEDDED in this listener process, so it
-        // inherits our scrubbed env (the listener provides AGENT_ROOMS_TOKEN; the
-        // gateway daemon wouldn't). `--json` for parseable output. The OpenClaw agent
-        // id defaults to "main"; override with AGENT_ROOMS_OPENCLAW_AGENT. The prompt
-        // rides `-m` (argv) — `openclaw agent` takes no stdin prompt; the listener runs
-        // on Linux (shell:false), so a multi-line `-m` value is passed intact.
+        // Wake through the already-running Gateway. The Gateway is the single owner
+        // of native session state and MCP/plugin wiring; embedded `--local` turns are
+        // deliberately forbidden because they create a second authority path.
         const agentId = process.env.AGENT_ROOMS_OPENCLAW_AGENT?.trim() || "main";
-        const args = ["agent", "--agent", agentId, "--local", "--json"];
-        // Spec 23: route + isolate per room. OpenClaw's sessionKey IS the conversation
-        // bucket; without an explicit room key every Agent Rooms wake lands in the
-        // default `main` session, merging all rooms into one transcript (cross-room leak
-        // + token burn). `--agent` alone is never enough for an Agent Rooms wake.
+        const args = ["agent", "--agent", agentId, "--json"];
+        // Spec 35 §11 (Said's ruling): build against latest OpenClaw and route the
+        // turn through the RUNNING gateway — ONE accepted code path. The current CLI
+        // may announce an embedded fallback after a transport failure; runWake kills
+        // it immediately via forbiddenOutputPattern above.
+        // gateway already holds the agent-rooms MCP server (buildMcpAdd wires it via
+        // `openclaw mcp add … --auth oauth`), so the woken agent gets the room tools
+        // from the gateway, not from this process's env. There is deliberately no
+        // `--local` escape hatch: an embedded result is a second, untested authority
+        // path and Spec 35 requires the running gateway or a loud failure.
+        // Spec 23/35 §11: route + isolate per room. OpenClaw's sessionKey IS the
+        // conversation bucket; without an explicit room key every wake lands in the
+        // default `main` session, merging all rooms into one transcript. The gateway
+        // owns the session-id rotation behind this stable key (daily/idle/compaction
+        // resets are accepted as native; rotated ids are reported per §2).
         if (spec.sessionKey)
             args.push("--session-key", spec.sessionKey);
-        args.push("-m", spec.prompt);
-        return { command: this.bin, args, cwd: spec.workspace, env: spec.env };
+        const promptPlaceholder = "__AGENT_ROOMS_PROMPT_FILE__";
+        args.push("--message-file", promptPlaceholder);
+        return {
+            command: this.bin,
+            args,
+            cwd: spec.workspace,
+            env: spec.env,
+            promptFile: { placeholder: promptPlaceholder, contents: spec.prompt }
+        };
+    },
+    buildPreflight() {
+        return { command: this.bin, args: ["gateway", "health", "--json", "--timeout", "10000"], cwd: process.cwd() };
     },
     buildMcpAdd(apiBase) {
         // `--auth oauth` registers the server for OpenClaw's OAuth flow (completed by
@@ -375,7 +448,7 @@ export const openclawAdapter = {
         // streamable-http server is wired with no auth and every room tool 401s.
         return {
             command: this.bin,
-            args: ["mcp", "add", "agent-rooms", "--transport", "streamable-http", "--url", `${apiBase}/mcp`, "--auth", "oauth"],
+            args: ["mcp", "add", "agent-rooms", "--transport", "streamable-http", "--url", `${apiBase}/mcp/openclaw`, "--auth", "oauth"],
             cwd: process.cwd()
         };
     },
@@ -384,19 +457,44 @@ export const openclawAdapter = {
     },
     parseSessionId(stdout) {
         return firstJsonField(stdout, ["session_id", "sessionId", "resumeSessionId"]);
+    },
+    parseFinalText(stdout) {
+        const result = parseJsonDocument(stdout);
+        const payloads = result?.payloads;
+        if (!Array.isArray(payloads))
+            return null;
+        const texts = payloads
+            .map((payload) => payload && typeof payload === "object" ? payload.text : null)
+            .filter((value) => typeof value === "string" && value.trim().length > 0);
+        return texts.length > 0 ? texts.join("\n") : null;
+    },
+    // OpenClaw 2026.7.1 prints one pretty JSON envelope. Usage is
+    // meta.agentMeta.usage {input,output,cacheRead,cacheWrite}; `input` is
+    // cache-exclusive in OpenClaw's normalizeUsage/derivePromptTokens contract.
+    parseUsageOutput(stdout) {
+        const result = parseJsonDocument(stdout);
+        const meta = result?.meta;
+        const agentMeta = meta?.agentMeta;
+        const usage = agentMeta?.usage;
+        if (!usage)
+            return null;
+        return {
+            uncached_input: num(usage.input), cache_read: num(usage.cacheRead),
+            cache_write: num(usage.cacheWrite), cache_write_5m: 0, cache_write_1h: 0,
+            reasoning: 0, output: num(usage.output), attempts: 1
+        };
     }
 };
 export const hermesAdapter = {
     name: "hermes",
     bin: "hermes",
     allowedTools: ROOM_TOOLS,
-    // INTENTIONALLY null. Hermes loads skills from ~/.hermes/skills, BUT every wake
-    // runs with `--ignore-rules`, which (verified in hermes source: cli_agent_setup_mixin
-    // passes skip_memory=skip_context_files=self.ignore_rules) skips auto-injection of
-    // AGENTS.md/SOUL.md/memory AND *preloaded skills*. So a woken Hermes never sees a
-    // preloaded skill — we always send the FULL wake prompt (skillDir:null makes
-    // isSkillInstalled() return false, so the listener never shortens it).
-    skillDir: null,
+    // --ignore-rules skips ambient/preconfigured skills, but current Hermes loads
+    // an explicit --skills argument after constructing that isolated context. This
+    // keeps memory/rules off while making the hosted Agent Rooms map visible.
+    skillDir: join(homedir(), ".hermes", "skills"),
+    supportsConstrainedWake: false,
+    requiresSessionId: true,
     buildWake(spec) {
         // Spec 23 / Spec 24 — ROOM-LOCKED, MEMORY-OFF wake. The token-burn bug was
         // cross-session bleed; Hermes' equivalent leak is its persistent MEMORY.md /
@@ -418,7 +516,7 @@ export const hermesAdapter = {
         // `hermes sessions list`. The prompt rides argv (-q's value); Hermes has no
         // stdin prompt mode. The listener runs alongside Hermes on Linux (shell:false),
         // so a multi-line argv value is passed intact (execve, no shell word-splitting).
-        const args = ["chat", "-q", spec.prompt, "-Q", "--yolo", "--ignore-rules", "--source", "tool"];
+        const args = ["chat", "-q", spec.prompt, "-Q", "--yolo", "--ignore-rules", "--skills", "agent-rooms", "--source", "tool"];
         if (spec.sessionId) {
             args.push("--resume", spec.sessionId);
         }
@@ -442,15 +540,39 @@ export const hermesAdapter = {
     parseSessionId(_stdout, stderr) {
         // Hermes single-query mode prints `\nsession_id: <id>` to STDERR (stdout stays a
         // clean answer). Id shape is `%Y%m%d_%H%M%S_<shortuuid>` e.g. 20260626_143022_a1b2c3d4.
+        //
+        // Spec 35 §10: compaction can rotate the session id through a parent/child
+        // chain, printing the parent then the child. We must capture the LAST id (the
+        // rotated child), not the first — resuming the stale parent would fail. Match
+        // ALL occurrences and take the final one.
         const haystack = stderr ?? "";
-        const m = haystack.match(/session_id:\s*([0-9]{8}_[0-9]{6}_[0-9a-f]+)/i) ?? haystack.match(/session_id:\s*(\S+)/i);
-        return m?.[1] ?? null;
-    }
-    // No parseFinalText: with `-Q` the tool stream is suppressed, so we can't tell
-    // whether the agent called send_message itself — relaying stdout would risk a
-    // double-post. The woken Hermes posts via the send_message MCP tool (the wake
-    // prompt instructs it); the live smoke-test verifies that path before prod-enable.
+        const strict = [...haystack.matchAll(/session_id:\s*([0-9]{8}_[0-9]{6}_[0-9a-f]+)/gi)];
+        if (strict.length > 0)
+            return strict[strict.length - 1][1] ?? null;
+        const loose = [...haystack.matchAll(/session_id:\s*(\S+)/gi)];
+        return loose.length > 0 ? (loose[loose.length - 1][1] ?? null) : null;
+    },
+    parseFinalText(stdout) {
+        return stdout.trim() || null;
+    },
+    // Spec 35 §10: a `--resume <id>` against a session Hermes no longer has must be
+    // reported (→ server evicts → fresh next wake), never retried blindly. Hermes
+    // prints a load/restore failure to stderr; match it narrowly.
+    resumeFailurePattern: /session .*(?:not found|does not exist|could not be (?:found|loaded|restored))|no such session|failed to (?:load|restore|resume) session/i
 };
+function parseJsonDocument(stdout) {
+    const start = stdout.indexOf("{");
+    const end = stdout.lastIndexOf("}");
+    if (start < 0 || end <= start)
+        return null;
+    try {
+        const value = JSON.parse(stdout.slice(start, end + 1));
+        return value && typeof value === "object" ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
 // General adapter (spec 18): wake any other MCP-capable CLI the user wires via
 // env — AGENT_ROOMS_CUSTOM_BIN (the command) + AGENT_ROOMS_CUSTOM_ARGS (space-
 // separated argv; the wake prompt rides stdin, same env-scrub/argv/stop-kill
@@ -460,6 +582,8 @@ export const customAdapter = {
     bin: process.env.AGENT_ROOMS_CUSTOM_BIN || "",
     allowedTools: ROOM_TOOLS,
     skillDir: null,
+    supportsConstrainedWake: false,
+    requiresSessionId: false,
     buildWake(spec) {
         const extra = (process.env.AGENT_ROOMS_CUSTOM_ARGS || "").split(/\s+/).filter(Boolean);
         return { command: this.bin, args: extra, cwd: spec.workspace, stdin: spec.prompt, env: spec.env };
@@ -498,9 +622,60 @@ function binOnPath(bin) {
         return false;
     }
 }
-/** Is the host's CLI available on PATH? (used by `init` for auto-detection). When
- *  the adapter wakes through a separate binary (wakeBin, e.g. OpenClaw → acpx), BOTH
- *  must be present, so we never auto-detect / advertise a host we can't actually wake. */
+// Spec 35 §11/§13 — the host versions this listener is built and tested against.
+// doctor gates on these and tells the user to update; we ship no compatibility
+// shims for older builds. Bump alongside the compatibility matrix in the docs.
+export const MIN_HOST_VERSIONS = {
+    openclaw: "2026.7.1",
+    claude_code: "2.1.190",
+    codex: "0.142.0",
+    hermes: "0.18.2"
+};
+/** Read a host CLI's reported version string (first version-looking token), or
+ *  null if the probe fails. Zero model tokens — a plain `--version` call. */
+export function readHostVersion(bin) {
+    try {
+        const probe = spawnSync(bin, ["--version"], { encoding: "utf8", timeout: 5000, shell: process.platform === "win32" });
+        const text = `${probe.stdout ?? ""} ${probe.stderr ?? ""}`;
+        const match = /(\d+\.\d+(?:\.\d+)?)/.exec(text);
+        return match ? match[1] : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Compare dotted numeric versions: is `version` >= `min`? Missing segments = 0. */
+export function versionAtLeast(version, min) {
+    const a = version.split(".").map((s) => Number.parseInt(s, 10) || 0);
+    const b = min.split(".").map((s) => Number.parseInt(s, 10) || 0);
+    for (let i = 0; i < Math.max(a.length, b.length); i += 1) {
+        const x = a[i] ?? 0;
+        const y = b[i] ?? 0;
+        if (x > y)
+            return true;
+        if (x < y)
+            return false;
+    }
+    return true;
+}
+/** Spec 35 §11/§14 — the version gate. Returns an actionable message when the
+ *  installed host is too old (or unreadable), else null (pass). */
+export function hostVersionGate(host) {
+    const min = MIN_HOST_VERSIONS[host] ?? null;
+    if (!min)
+        return { ok: true, installed: null, min: null, message: null };
+    const adapter = getAdapter(host);
+    const bin = adapter?.bin ?? host;
+    const installed = readHostVersion(bin);
+    if (!installed) {
+        return { ok: false, installed: null, min, message: `Could not read ${bin} --version; ensure ${bin} ${min}+ is installed and on PATH.` };
+    }
+    if (!versionAtLeast(installed, min)) {
+        return { ok: false, installed, min, message: `${bin} ${installed} is older than the required ${min}. Update ${bin} to ${min}+ and restart the listener.` };
+    }
+    return { ok: true, installed, min, message: null };
+}
+/** Is every binary required by this adapter available on PATH? */
 export function isHostInstalled(adapter) {
     if (!binOnPath(adapter.bin))
         return false;
@@ -515,9 +690,7 @@ export function detectInstalledHosts() {
     // are not offered. The general adapter is opt-in via env, so it's not auto-detected.
     return [claudeAdapter, codexAdapter, openclawAdapter, hermesAdapter].filter(isHostInstalled);
 }
-/** Is the agent-rooms skill already installed in this host's skills dir? When it
- *  is, the woken agent already knows the room protocol, so `watch` sends a short
- *  wake prompt (just the mention) instead of the full how-to. */
+/** Is the owned hosted Agent Rooms skill present in this host's skill directory? */
 export function isSkillInstalled(adapter) {
     if (!adapter.skillDir)
         return false;