cookbook-bridge 0.1.11 → 0.1.13

package/README.md

@@ -2,6 +2,17 @@
 
 ## Changelog
 
+**0.1.13** (2026-09-02)
+- Pre-flight: the moment a grant this Bridge hosts becomes active, it runs `env`, the doctor, `cli_versions` and the shape of its own config (tokens stripped) once, locally and read-only, and posts the result as a host-initiated `preflight` call, so the visiting agent starts with what the machine already knows. Remembered per grant in `bridge.state.json`; a failed post is retried once per process.
+- One-click plans: a `plan` call carries `why` and an ordered list of steps. The Bridge recomputes the plan hash before running (a step added after the click is refused as `plan hash mismatch`), runs each step through the same authorization wall as a single call, with the plan's approval standing in for each write-class step's click, stops at the first failure, and reports every step with its duration. Plans cannot nest, cannot contain `preflight`, and run one at a time like every other call.
+- Every result leaving the machine is capped at 64 KB, the same cap the server applies.
+
+**0.1.12** (2026-09-02)
+- Kimi Code is the fourth agent: `connect` finds `kimi`, mints a "Kimi" token and writes `~/.kimi-code/mcp.json` (owner-only, other servers kept). Runs use `kimi -p ... --output-format stream-json`; the board gets live text and the work log, resume by session id, and a duration-only receipt (kimi reports no token counts).
+- A headless kimi run approves every tool and has no `--allowedTools` flag, so the Bridge turns the config's `--allowedTools` into a per-run agent file (`--agent-file`, a 0600 temp file) whose tools allowlist is exactly that list. `doctor` fails a Kimi agent that has no `--allowedTools`.
+- Billing protection also hides `KIMI_API_KEY`, `MOONSHOT_API_KEY` and `KIMI_MODEL_API_KEY`.
+- `doctor` gained Kimi rows: version, login (config.toml providers or OAuth credentials), the MCP file, and the two flags a headless run needs.
+
 **0.1.11** (2026-09-02)
 - The Bridge has a home: `~/.cookbook/config.json` (file 0600, folder 0700) for every command. `bridge.state.json`, `local.json` and `bridge.log` sit next to it. Before, the config lived next to `bridge.mjs`, so every `npx cookbook-bridge@latest` landed in a fresh cache folder and lost it. A config found next to `bridge.mjs` is copied to the home once (the old file stays) and the move is announced in one line. `--config <path>` and `COOKBOOK_CONFIG` still win.
 - `connect` runs the Bridge right after the approval (pass `--no-run` to stop at "connected"). With no agent CLI found it prints the doctor instead.
@@ -25,7 +36,7 @@
 - Set `COOKBOOK_NO_BROWSER=1` to stop `login`/`connect` from opening a browser (the URL is still printed).
 
 
-Runs your **own AI agents** (Claude Code, Codex, Gemini) on **your own subscriptions**,
+Runs your **own AI agents** (Claude Code, Codex, Gemini, Kimi Code) on **your own subscriptions**,
 against your Cookbook workspaces — so tasks on the board get done by your agents
 automatically, on your machine, with **no API credits**.
 
@@ -45,7 +56,7 @@ Trust model: your Cookbook's `/security` page.
 
 ```bash
 npx cookbook-bridge@latest connect   # ONE approval connects the Bridge AND every installed
-                                     # agent CLI (claude, codex, agy, openclaw), each with its
+                                     # agent CLI (claude, codex, agy, kimi, openclaw), each with its
                                      # own attributed token, then RUNS the Bridge. Leave it open.
 ```
 
@@ -89,7 +100,7 @@ attribution label, "Claude · via you"), then configures each CLI via its own `m
 **Account → Tokens** page.
 
 Requires **Node 18+** (built-in `fetch`, no npm install) and at least one agent CLI
-installed and logged in (`claude`, `agy` — the Antigravity CLI for Gemini — or the Codex app). Each agent must also be
+installed and logged in (`claude`, `agy` — the Antigravity CLI for Gemini — `kimi`, or the Codex app). Each agent must also be
 connected to Cookbook over MCP — that's how it completes tasks. Run `doctor`; it tells
 you exactly which parts are ready and how to fix the rest.
 
@@ -143,6 +154,8 @@ local files are behind.
     "command": ["claude", "-p", "{prompt}", "--allowedTools", "mcp__cookbook__*", "--output-format", "json"] },
   { "name": "Gemini", "match": ["gemini"], "enabled": true,
     "command": ["agy", "-p", "{prompt}", "--sandbox", "--print-timeout", "3600s"] },
+  { "name": "Kimi", "match": ["kimi"], "enabled": true,
+    "command": ["kimi", "-p", "{prompt}", "--allowedTools", "mcp__cookbook__*", "--output-format", "stream-json"] },
   { "name": "Codex", "match": ["codex", "chatgpt"], "enabled": false, "runner": "app-server",
     "command": ["/Applications/Codex.app/Contents/Resources/codex"] }
 ]
@@ -158,6 +171,13 @@ local files are behind.
   usual cause — `doctor` checks it.
 - **Codex (ChatGPT)** runs through `codex app-server` (its headless `exec` can't call
   MCP tools); see `_setup` in `config.example.json` for the 3-step enable.
+- **Kimi Code** runs `kimi -p` with `--output-format stream-json` (live text, work log,
+  session resume; no token counts, so the receipt is duration only). Its headless mode
+  approves every tool and has no `--allowedTools` flag, so the Bridge turns that value
+  into a per-run agent file (`--agent-file`) whose `tools:` allowlist is exactly the
+  list. Keep it on the command; `doctor` fails a Kimi agent without it. `connect`
+  writes `~/.kimi-code/mcp.json` (kimi has no `mcp add`). Kimi does not stream its
+  thinking, so a long think looks like silence to `livenessTimeoutSeconds`.
 - `"default"`: which agent takes tasks assigned to **any**.
 
 ## What rides into (and out of) every run
@@ -180,9 +200,11 @@ you opt an agent in, and only tasks explicitly posted as goals are ever eligible
 
 ## Safety rails (on by default)
 
-- **Billing protection**: vendor API keys (`ANTHROPIC_API_KEY` etc.) are hidden from
-  agent processes, so a task can never silently bill your API account instead of your
-  subscription. Opt out with `"allowApiKeyBilling": true`.
+- **Billing protection**: vendor API keys (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`,
+  `GEMINI_API_KEY`, `GOOGLE_API_KEY`, `KIMI_API_KEY`, `MOONSHOT_API_KEY`,
+  `KIMI_MODEL_API_KEY`) are hidden from agent processes, so a task can never silently
+  bill your API account instead of your subscription. Opt out with
+  `"allowApiKeyBilling": true`.
 - **Vulnerable-version gate**: gemini-cli below 0.39.1 (the CVSS-10.0 RCE fix) is refused; agy below 1.1.1 (headless MCP) is refused.
 - **Who can use your agents**: `"acceptFrom": "anyone"` (default) or a list of member
   names (e.g. `["dp", "pierre"]`); per-agent overrides supported. Plus the per-person

package/bridge.mjs

@@ -33,7 +33,7 @@ import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawn } from "node:child_process";
-import { callsFromStreamLine, foldCallEvent, wireCalls } from "./live.mjs";
+import { callsFromStreamLine, foldCallEvent, wireCalls, shortTool, argFor } from "./live.mjs";
 import { planFromStreamLine, notePlan, planLine } from "./plan.mjs";
 
 // Node version guard: below 18 there is no global fetch and none of this runs. One
@@ -59,6 +59,7 @@ import { resolveAgentForTask } from "./chef.mjs";
 import { locateConfig, cli, updateLine, configHome } from "./update.mjs";
 let listWorkspaces, listTasks, listOpenWork, getTask, threadResumeContext, completeTaskApi, resolveDelegation, reportTaskUsage, reportTaskProgress, volunteerClaim, dispatchClaim, abandonTask, recallMemories, recallAcrossWorkspaces, creditRecall, getVolunteerSettings, agentsQuery;
 let agentEnv, checkGeminiVersion, isGeminiCommand, GEMINI_MIN_VERSION, checkAgyVersion, isAgyCommand, AGY_MIN_VERSION, withCookbookMcp, isClaudeCommand, withApprovalRelay, materializeMcpConfig;
+let isKimiCommand, kimiFromLine, kimiResultEnvelope, kimiCommand, kimiLoginState, kimiMcpState, checkKimiVersion;
 let extractUsage, displayText;
 let volunteeringEnabled, volunteerCandidates, decisionPrompt, parseDecision, MAX_DECISIONS_PER_POLL, mergeVolunteerSettings, effectiveCapabilities;
 let buildPrompt, buildThreadFollowUpPrompt;
@@ -67,15 +68,16 @@ let hasCodexThread, reapCodexServer, killCodexServer;
 let checkForUpdate, applyUpdate;
 let createLocalServer, toolsForMode, modeForTools, vendorOf;
 let connectAgentsProgrammatic, detectClis;
-let serveCalls, describeCall, hostingMode, whichExec, argvForSpawn, redactText, resolveCmdShim, killTree;
+let serveCalls, describeCall, hostingMode, whichExec, argvForSpawn, redactText, resolveCmdShim, killTree, runPreflight, grantsNeedingPreflight;
 let fetchHands, claimHandsCall, reportHandsResult;
 
 async function loadRuntime() {
   ({ createLocalServer, toolsForMode, modeForTools, vendorOf } = await import("./local.mjs"));
   ({ connectAgentsProgrammatic, detectClis } = await import("./device.mjs"));
   ({ listWorkspaces, listTasks, listOpenWork, getTask, threadResumeContext, completeTaskApi, resolveDelegation, reportTaskUsage, reportTaskProgress, volunteerClaim, dispatchClaim, abandonTask, recallMemories, recallAcrossWorkspaces, creditRecall, getVolunteerSettings, fetchHands, claimHandsCall, reportHandsResult, agentsQuery } = await import("./cookbook.mjs"));
-  ({ serveCalls, describeCall, hostingMode, which: whichExec, argvForSpawn, redact: redactText, resolveCmdShim, killTree } = await import("./hands.mjs"));
-  ({ agentEnv, checkGeminiVersion, isGeminiCommand, GEMINI_MIN_VERSION, checkAgyVersion, isAgyCommand, AGY_MIN_VERSION, withCookbookMcp, isClaudeCommand, withApprovalRelay, materializeMcpConfig } = await import("./harden.mjs"));
+  ({ serveCalls, describeCall, hostingMode, which: whichExec, argvForSpawn, redact: redactText, resolveCmdShim, killTree, runPreflight, grantsNeedingPreflight } = await import("./hands.mjs"));
+  ({ agentEnv, checkGeminiVersion, isGeminiCommand, GEMINI_MIN_VERSION, checkAgyVersion, isAgyCommand, AGY_MIN_VERSION, withCookbookMcp, isClaudeCommand, withApprovalRelay, materializeMcpConfig,
+    isKimiCommand, kimiFromLine, kimiResultEnvelope, kimiCommand, kimiLoginState, kimiMcpState, checkKimiVersion } = await import("./harden.mjs"));
   ({ extractUsage, displayText } = await import("./usage.mjs"));
   ({ volunteeringEnabled, volunteerCandidates, decisionPrompt, parseDecision, MAX_DECISIONS_PER_POLL, mergeVolunteerSettings, effectiveCapabilities } = await import("./volunteer.mjs"));
   ({ buildPrompt, buildThreadFollowUpPrompt } = await import("./prompt.mjs"));
@@ -123,6 +125,7 @@ function ensureAgentPath() {
   if (home) {
     dirs.push(path.join(home, ".claude/local")); // claude CLI local install
     dirs.push(path.join(home, ".bun/bin"), path.join(home, ".local/bin"));
+    dirs.push(path.join(process.env.KIMI_CODE_HOME || path.join(home, ".kimi-code"), "bin")); // kimi's install-script binary
     try {
       const base = path.join(home, ".nvm/versions/node");
       const vers = fs.readdirSync(base).sort();
@@ -405,20 +408,30 @@ export function shouldKill({ streaming, startedAt, lastActivityAt, now, liveness
 export function withModel(command, model) {
   if (!Array.isArray(command) || !model) return command;
   const base = String(command[0] ?? "").split(/[\\/]/).pop().toLowerCase();
-  if (base !== "claude") return command;
+  // Kimi: `-m <alias>` (an alias from ~/.kimi-code/config.toml). Same replace rule.
+  const kimi = base === "kimi" || base === "kimi.exe";
+  if (base !== "claude" && !kimi) return command;
+  const flags = kimi ? ["-m", "--model"] : ["--model"];
   const out = [];
   for (let i = 0; i < command.length; i++) {
-    if (command[i] === "--model") { i++; continue; }
+    if (flags.includes(command[i])) { i++; continue; }
     if (String(command[i]).startsWith("--model=")) continue;
     out.push(command[i]);
   }
-  out.push("--model", model);
+  out.push(kimi ? "-m" : "--model", model);
   return out;
 }
 
 export function resumeCommand(command, sessionId) {
   if (!Array.isArray(command) || !sessionId) return { command, resumed: false };
   const base = String(command[0] ?? "").split(/[\\/]/).pop().toLowerCase();
+  if (base === "kimi" || base === "kimi.exe") {
+    // Kimi resumes with `-S <id>` (the id its session.resume_hint line carried).
+    // kimiCommand drops the --allowedTools jail on a resume: the session keeps
+    // the agent file it was created with, and kimi refuses --agent-file here.
+    if (command.some((a) => a === "-S" || a === "--session" || a === "-r" || a === "--resume")) return { command, resumed: true };
+    return { command: [command[0], "-S", sessionId, ...command.slice(1)], resumed: true };
+  }
   if (base !== "claude") return { command, resumed: false };
   if (command.includes("--resume")) return { command, resumed: true };
   return { command: [command[0], "--resume", sessionId, ...command.slice(1)], resumed: true };
@@ -438,7 +451,14 @@ function spawnAgent(agent, prompt, timeoutSeconds, env, onProgress, opts = {}) {
     // The bearer token leaves argv here: an inline --mcp-config JSON becomes a 0600
     // temp file (harden.mjs materializeMcpConfig), removed when the run ends.
     const mat = materializeMcpConfig ? materializeMcpConfig(command) : { command, cleanup: () => {} };
-    const [cmd, ...rawArgs] = mat.command;
+    // KIMI JAIL: `--allowedTools X` becomes a per-run agent file (0600) whose tools
+    // allowlist is X, because kimi's headless mode approves every tool and has no
+    // such flag (harden.mjs kimiCommand). Dropped on a resume, where the session
+    // already carries it. Identity for every other CLI.
+    const jail = kimiCommand ? kimiCommand(mat.command) : { command: mat.command, cleanup: () => {} };
+    const kimi = isKimiCommand ? isKimiCommand(jail.command) : false;
+    const cleanupRun = () => { jail.cleanup(); mat.cleanup(); };
+    const [cmd, ...rawArgs] = jail.command;
     // PROMPT DELIVERY. claude reads the prompt from stdin when `-p` has no
     // positional prompt (synthesis.mjs relies on the same). That keeps workspace
     // text out of argv: no argument-length ceiling, and on Windows no cmd.exe
@@ -459,7 +479,7 @@ function spawnAgent(agent, prompt, timeoutSeconds, env, onProgress, opts = {}) {
       // or refuse with the fix (hands.mjs resolveCmdShim).
       const script = resolveCmdShim ? resolveCmdShim(bare) : null;
       if (!script) {
-        mat.cleanup();
+        cleanupRun();
         reject(new Error(`refusing to pass a prompt through the ${path.basename(bare)} shell shim on Windows (cmd.exe quoting is not safe for workspace text). Point this agent's command at the CLI's .js entry or its real executable instead.`));
         return;
       }
@@ -476,7 +496,7 @@ function spawnAgent(agent, prompt, timeoutSeconds, env, onProgress, opts = {}) {
         ...(agent.cwd ? { cwd: agent.cwd } : {}),
       });
     } catch (e) {
-      mat.cleanup();
+      cleanupRun();
       reject(new Error(`could not launch \`${cmd}\`: ${e.message}`));
       return;
     }
@@ -499,13 +519,19 @@ function spawnAgent(agent, prompt, timeoutSeconds, env, onProgress, opts = {}) {
     let partialText = "";
     // Live CALLS (show the work): tool_use/tool_result folded into a capped list.
     let calls = [];
+    // Kimi: the last assistant text is the run's answer (no result line exists);
+    // it becomes a claude-shaped envelope on close (harden.mjs kimiResultEnvelope).
+    let kimiText = "";
+    let kimiTurns = 0;
     const liveText = () => {
       const full = partialText ? `${turnsText}${turnsText ? "\n\n" : ""}${partialText}` : turnsText;
       return full.length > LIVE_TEXT_CAP ? "…" + full.slice(-LIVE_TEXT_CAP) : full;
     };
     const emit = () => {
       const text = liveText();
-      if (!onProgress || (acc.input_tokens === 0 && acc.output_tokens === 0 && !text)) return;
+      // A tick with only calls (a run that reads before it speaks; every kimi run,
+      // whose stream carries no token counts) is still worth showing.
+      if (!onProgress || (acc.input_tokens === 0 && acc.output_tokens === 0 && !text && !calls.length)) return;
       lastEmit = Date.now();
       // session_ref rides every tick once known: the server-visible resume handle that
       // lets a Composer-thread follow-up continue THIS conversation (0064), surviving
@@ -541,6 +567,24 @@ function spawnAgent(agent, prompt, timeoutSeconds, env, onProgress, opts = {}) {
         // text throttle (still ≥300ms apart so a burst of reads is one tick).
         let touched = false;
         for (const ev of callsFromStreamLine(line)) { calls = foldCallEvent(calls, ev); touched = true; }
+        if (kimi) {
+          // Kimi's lines are keyed by `role` (claude's by `type`), so the claude
+          // parsers above ignore them and this is the only reader.
+          const kev = kimiFromLine(line);
+          if (kev) {
+            if (kev.sessionId && !sessionId) sessionId = kev.sessionId;
+            if (kev.text) {
+              turnsText += (turnsText ? "\n\n" : "") + kev.text;
+              kimiText = kev.text;
+              kimiTurns++;
+            }
+            for (const c of kev.calls) {
+              calls = foldCallEvent(calls, c.kind === "call" ? { kind: "call", id: c.id, name: shortTool(c.name), arg: argFor(c.input) } : c);
+              touched = true;
+            }
+            if (kev.retry) log(`  ↳ ${agent.name}: kimi is retrying its API (${kev.retry.attempt}/${kev.retry.max}): ${kev.retry.error}`);
+          }
+        }
         // The CLI also says where the member's plan stands (claude: rate_limit_event).
         // Remembered per vendor; the next heartbeat carries it (bridge/plan.mjs).
         const plan = planFromStreamLine(line);
@@ -577,15 +621,18 @@ function spawnAgent(agent, prompt, timeoutSeconds, env, onProgress, opts = {}) {
 
     child.on("error", (e) => {
       clearInterval(watchdog);
-      mat.cleanup();
+      cleanupRun();
       reject(new Error(`could not launch \`${cmd}\` (is it installed + on PATH?): ${e.message}`));
     });
     child.on("close", (code) => {
       clearInterval(watchdog);
-      mat.cleanup();
+      cleanupRun();
       // In streaming mode, hand back the final result line (json-mode-identical); fall
       // back to the raw buffer if the run died before emitting one.
-      resolve({ code, out: streaming ? (resultLine || lineBuf || out) : out, err, sessionId });
+      const kimiOut = kimi && streaming
+        ? kimiResultEnvelope({ text: kimiText, sessionId, durationMs: Date.now() - startedAt, code, err, numTurns: kimiTurns })
+        : null;
+      resolve({ code, out: kimiOut ?? (streaming ? (resultLine || lineBuf || out) : out), err, sessionId });
     });
   });
 }
@@ -694,6 +741,11 @@ function failureHint(result) {
   const tail = tailSrc.split("\n").slice(-2).join(" ").slice(0, 240);
   if (infra.includes("not logged in") || infra.includes("please log in"))
     return "the agent CLI isn't logged in → run `claude auth login`";
+  // Kimi's own error strings (stderr: "error: failed to run prompt: provider.connection_error: …").
+  if (infra.includes("provider.connection_error") || infra.includes("connection error"))
+    return "the agent CLI can't reach its API (a network or DNS block on the vendor's hosts) → check the connection, then try `kimi -p hi` by hand";
+  if (infra.includes("no provider") || infra.includes("default_model") || infra.includes("no model configured"))
+    return "kimi has no provider configured → run `kimi login`";
   if (infra.includes("no mcp") || infra.includes("requires authentication"))
     return `the agent can't reach the Cookbook MCP → run \`${cli("doctor")}\``;
   if (infra.includes("not allowed") || infra.includes("allowedtools"))
@@ -763,6 +815,7 @@ function loadRunState() {
     for (const [id, n] of Object.entries(raw.attempts ?? {})) attempts.set(id, Number(n) || 0);
     for (const id of raw.givenUp ?? []) givenUp.add(id);
     for (const [id, ctx] of Object.entries(raw.retryCtx ?? {})) retryCtx.set(id, ctx);
+    for (const id of raw.preflighted ?? []) if (typeof id === "string") preflighted.add(id);
   } catch { /* first run / unreadable — start clean */ }
 }
 function saveRunState() {
@@ -771,11 +824,15 @@ function saveRunState() {
     const attEntries = [...attempts.entries()].slice(-500);
     const given = [...givenUp].slice(-500);
     const retries = [...retryCtx.entries()].slice(-200);
-    fs.writeFileSync(statePath(), JSON.stringify({ attempts: Object.fromEntries(attEntries), givenUp: given, retryCtx: Object.fromEntries(retries) }));
+    const flown = [...preflighted].slice(-500);
+    fs.writeFileSync(statePath(), JSON.stringify({ attempts: Object.fromEntries(attEntries), givenUp: given, retryCtx: Object.fromEntries(retries), preflighted: flown }));
   } catch { /* best-effort — never let state persistence break a run */ }
 }
 
 const attempts = new Map(); // taskId -> count
+// Grants this host has already pre-flighted (hands section). Persisted: a restart
+// must not post a second pre-flight for a grant the visitor already read.
+const preflighted = new Set();
 // Retry context (Phase 1): what the LAST failed attempt knew — the claude session
 // to resume and the failure to feed back — so a retry continues instead of redoing.
 const retryCtx = new Map(); // taskId -> { sessionId, reason }
@@ -947,7 +1004,8 @@ function detectAgentsForStatus(cfg) {
   const rows = cfg.agents.map((a) => {
     const cmd = Array.isArray(a.command) ? a.command[0] : null;
     const binary = resolveBin(cmd);
-    return { name: a.name, vendor: vendorOf ? vendorOf(a) : "other", binary, found: !!binary, enabled: true, runner: a.runner ?? "cli", configured: true };
+    const vendor = isKimiCommand && isKimiCommand(a.command) ? "kimi" : (vendorOf ? vendorOf(a) : "other");
+    return { name: a.name, vendor, binary, found: !!binary, enabled: true, runner: a.runner ?? "cli", configured: true };
   });
   try {
     for (const cli of detectClis ? detectClis() : []) {
@@ -1554,30 +1612,36 @@ function noteAwaiting(awaiting) {
   if (announcedAwaiting.size > 500) announcedAwaiting.clear();
 }
 
+/** The host context every hands path shares: serveCalls (visitor calls, plans) and
+ *  runPreflight (the host's own first call on a new grant). */
+function handsContext(cfg) {
+  return {
+    cfg,
+    cfgPath: CONFIG_PATH,
+    home: os.homedir(),
+    // The host's OWN folder list. A granted folder is honoured only if it is here
+    // (or inside one), so the server can never hand a visitor a directory.
+    hostFolders: cfg.hosting?.folders ?? [],
+    doctor: () => doctorReport(["--config", CONFIG_PATH]),
+    claim: (id) => claimHandsCall(cfg, id),
+    report: (id, r) => reportHandsResult(cfg, id, r),
+    // Repair templates reach the same machinery the desktop app's buttons use, so
+    // a fix an agent performs is exactly the fix the host could have clicked.
+    restart: () => reexecSelf(),
+    startConnect: () => connectAgentsProgrammatic({ cfgPath: CONFIG_PATH, baseUrl: cfg.cookbookUrl }),
+    applyConfig: () => applyConfigFromDisk(cfg),
+    log,
+    stopped: () => stopped,
+    visitorLabel: (c) => c.visitor ?? "a visiting agent",
+    onCall: emitHands,
+  };
+}
+
 async function serveHands(cfg, calls) {
   if (hostingMode(cfg) === "off" || handsBusy || !calls || calls.length === 0) return;
   handsBusy = true;
   try {
-    await serveCalls(calls, {
-      cfg,
-      cfgPath: CONFIG_PATH,
-      home: os.homedir(),
-      // The host's OWN folder list. A granted folder is honoured only if it is here
-      // (or inside one), so the server can never hand a visitor a directory.
-      hostFolders: cfg.hosting?.folders ?? [],
-      doctor: () => doctorReport(["--config", CONFIG_PATH]),
-      claim: (id) => claimHandsCall(cfg, id),
-      report: (id, r) => reportHandsResult(cfg, id, r),
-      // Repair templates reach the same machinery the desktop app's buttons use, so
-      // a fix an agent performs is exactly the fix the host could have clicked.
-      restart: () => reexecSelf(),
-      startConnect: () => connectAgentsProgrammatic({ cfgPath: CONFIG_PATH, baseUrl: cfg.cookbookUrl }),
-      applyConfig: () => applyConfigFromDisk(cfg),
-      log,
-      stopped: () => stopped,
-      visitorLabel: (c) => c.visitor ?? "a visiting agent",
-      onCall: emitHands,
-    });
+    await serveCalls(calls, handsContext(cfg));
   } catch (e) {
     log(`! hands error: ${e.message}`);
   } finally {
@@ -1585,6 +1649,51 @@ async function serveHands(cfg, calls) {
   }
 }
 
+/** Open a HOST-initiated call row on a grant (the pre-flight). Same bearer, same
+ *  route the claim uses; the server answers { call_id }. */
+async function createHostCall(cfg, grantId, verb) {
+  const res = await fetch(`${cfg.cookbookUrl}/api/bridge/hands`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${cfg.token}`, "Content-Type": "application/json" },
+    body: JSON.stringify({ grant_id: grantId, verb, host_initiated: true }),
+  });
+  if (!res.ok) throw new Error(`hands ${res.status}`);
+  const j = await res.json().catch(() => ({}));
+  return typeof j.call_id === "string" ? j.call_id : typeof j.call?.id === "string" ? j.call.id : null;
+}
+
+// ── PRE-FLIGHT: the first thing a new grant gets is what the machine already knows.
+// When a grant this Bridge hosts becomes active, the host runs env + doctor +
+// cli_versions + its own config's shape (tokens stripped) once, locally, read-only,
+// and posts it as a host-initiated `preflight` call. The visitor reads it from
+// grant_get before asking anything the machine already answered. Persisted per
+// grant (bridge.state.json); at most two tries per grant per process.
+const preflightTries = new Map(); // grantId -> attempts this process
+async function preflightNewGrants(cfg) {
+  if (hostingMode(cfg) === "off" || handsBusy || !runPreflight) return;
+  const fresh = grantsNeedingPreflight(hands.activeGrants, { preflighted, tried: preflightTries });
+  if (fresh.length === 0) return;
+  handsBusy = true; // never alongside a visitor's call
+  try {
+    for (const grantId of fresh) {
+      if (stopped) break;
+      const n = (preflightTries.get(grantId) ?? 0) + 1;
+      preflightTries.set(grantId, n);
+      log(`◇ pre-flight for grant ${grantId.slice(0, 8)}: env, doctor, CLI versions, config shape`);
+      try {
+        const { callId } = await runPreflight(grantId, { ...handsContext(cfg), create: (gid) => createHostCall(cfg, gid, "preflight") });
+        preflighted.add(grantId);
+        saveRunState();
+        log(`  ↳ pre-flight posted (call ${String(callId).slice(0, 8)})`);
+      } catch (e) {
+        log(`! pre-flight for grant ${grantId.slice(0, 8)} failed: ${e.message}${n >= 2 ? " (not retrying until the Bridge restarts)" : " (will retry once)"}`);
+      }
+    }
+  } finally {
+    handsBusy = false;
+  }
+}
+
 /** Poll for granted calls (the net under the push channel, and the whole story on a
  *  server or network without SSE). No-ops entirely when not hosting. */
 async function pollHands(cfg) {
@@ -1598,6 +1707,7 @@ async function pollHands(cfg) {
     }
     hands.activeGrants = r.grants ?? [];
     noteAwaiting(r.awaiting ?? []);
+    await preflightNewGrants(cfg);
     await serveHands(cfg, r.calls);
   } catch (e) {
     if (!/40[13]/.test(e.message)) log(`! couldn't check for granted work: ${e.message}`);
@@ -1635,7 +1745,7 @@ async function pullOnce(cfg, { boot = false } = {}) {
   if (j.hands && typeof j.hands === "object") {
     hands.activeGrants = j.hands.grants ?? hands.activeGrants;
     noteAwaiting(j.hands.awaiting ?? []);
-    if (hostingMode(cfg) !== "off") void serveHands(cfg, j.hands.calls ?? []);
+    if (hostingMode(cfg) !== "off") void preflightNewGrants(cfg).then(() => serveHands(cfg, j.hands.calls ?? []));
   }
   // 0092: synthesis (summary, caption, vision, answer) thinks HERE, on this
   // member's subscription. Each job carries kind, model and image straight
@@ -1762,7 +1872,7 @@ async function socketLoop(cfg) {
               const j = JSON.parse(ev.data);
               hands.activeGrants = j.grants ?? hands.activeGrants;
               noteAwaiting(j.awaiting ?? []);
-              void serveHands(cfg, j.calls ?? []);
+              void preflightNewGrants(cfg).then(() => serveHands(cfg, j.calls ?? []));
             } catch { /* malformed frame — the poll covers it */ }
           }
         }
@@ -2550,6 +2660,30 @@ async function doctorReport(args) {
         }
       }
 
+      // Kimi Code: version (no gate), login (config.toml providers / credentials),
+      // the user-level mcp.json the Bridge writes, and the two flags a headless
+      // run needs (the jail and the stream).
+      if (isKimiCommand && isKimiCommand(cmd)) {
+        const { version } = await checkKimiVersion([bin]);
+        if (version) ok(`${agent.name}: kimi ${version}`);
+        else warn(`${agent.name}: couldn't read kimi version`, "run `kimi --version` by hand");
+        const login = kimiLoginState();
+        if (login.loggedIn) ok(`${agent.name}: logged in (${login.providers.length ? `provider ${login.providers.join(", ")}` : `${login.credentials} OAuth credential(s)`})`);
+        else bad(`${agent.name}: no Kimi login found (no provider with a key in ${login.configPath}, nothing under credentials/)`, "run `kimi login` (device code), or `/login` inside `kimi`");
+        const mcp = kimiMcpState({ cookbookUrl: cfg.cookbookUrl });
+        if (mcp.server && mcp.matches && mcp.hasAuth) ok(`${agent.name}: Cookbook MCP configured (${mcp.file})`);
+        else if (mcp.server) warn(`${agent.name}: MCP server 'cookbook' in ${mcp.file} points at ${mcp.url || "(no url)"}${mcp.hasAuth ? "" : " with no Authorization header"}`, `expected ${cfg.cookbookUrl}/api/mcp with a bearer token; re-run \`${cli("connect")}\``);
+        else bad(`${agent.name}: no 'cookbook' server in ${mcp.file}`, `run \`${cli("connect")}\` (kimi has no \`mcp add\`; the Bridge writes this file)`);
+        const cmdArgs = agent.command || [];
+        if (!cmdArgs.includes("--allowedTools")) {
+          bad(`${agent.name}: no --allowedTools in the command; kimi's headless mode auto-approves EVERY tool (Bash included) and has no flag of its own`,
+            `add "--allowedTools", "mcp__cookbook__*" to this agent's command (the Bridge turns it into a per-run agent file)`);
+        } else if (cmdArgs.includes("-S") || cmdArgs.includes("--session") || cmdArgs.includes("-c")) {
+          warn(`${agent.name}: the command resumes a session by hand, so --allowedTools is ignored on that run (kimi binds the agent at session creation)`);
+        }
+        if (!cmdArgs.includes("stream-json")) warn(`${agent.name}: no --output-format stream-json; the board gets no live progress and no work log from this agent`, `add "--output-format", "stream-json" to this agent's command`);
+      }
+
       if (isClaudeCommand && isClaudeCommand(agent.command)) {
         if (agent.token) ok(`${agent.name}: runs carry their own Cookbook connection (per-agent token) — identity is this Bridge's member`);
         else warn(`${agent.name}: no per-agent token — runs use the claude CLI's OWN Cookbook login, which may be a different account and inherits stale claude.ai connectors`,

package/chef-persona.md

@@ -7,3 +7,5 @@ What you know: Cookbook is the shared brain a team's AI agents plug into. Every
 How you work: the message you receive carries the rules for this conversation (a grant id, whether you may ask for machine access, and Cookbook Help notes that match the question). Follow those rules exactly; they override anything here. Use the Cookbook tools only. When the answer depends on the person's machine, ask for access the way the rules describe. Never send them to a terminal.
 
 You are running on this person's own machine and subscription as their agent. You can see their workspaces. When you need to look at or change their setup, ask for a hands grant in the usual way; every action still waits for their click.
+
+When a fix needs more than one change, do not ask for each one. Submit ONE hands_plan with a plain `why` and the steps in order, then wait for the person's single approval; the Bridge runs the steps one at a time and stops at the first failure. Before you ask about the machine, read the pre-flight the host posted on the grant (grant_get): what is installed, the doctor rows, CLI versions and the shape of the Bridge config are already there. Never ask for something the machine has already answered.

package/config.example.json

@@ -8,7 +8,7 @@
   "livenessTimeoutSeconds": 300,
   "_concurrency": "How many task runs may be in flight at once. Runs launch in parallel up to this cap; the atomic pre-claim keeps every task single-runner.",
   "maxConcurrentRuns": 3,
-  "_billing": "Agents run on the CLI subscriptions you already pay for. The Bridge hides ANTHROPIC_API_KEY / OPENAI_API_KEY / GEMINI_API_KEY / GOOGLE_API_KEY from agent processes so a task can never silently bill your API account instead. Set allowApiKeyBilling to true ONLY if you explicitly want API-key billing.",
+  "_billing": "Agents run on the CLI subscriptions you already pay for. The Bridge hides ANTHROPIC_API_KEY / OPENAI_API_KEY / GEMINI_API_KEY / GOOGLE_API_KEY / KIMI_API_KEY / MOONSHOT_API_KEY / KIMI_MODEL_API_KEY from agent processes so a task can never silently bill your API account instead. Set allowApiKeyBilling to true ONLY if you explicitly want API-key billing.",
   "allowApiKeyBilling": false,
   "_volunteering": "STIGMERGY (off by default): an agent with volunteer:true watches tasks posted as open GOALS (to:'goal' on the board) and may claim ones matching its capabilities — decided by one cheap call to the agent's own CLI, gated by your delegation policy (ask parks it in your approvals inbox), claimed atomically, capped per poll. Flip volunteering:false to kill it globally without touching agents.",
   "volunteering": true,
@@ -57,6 +57,25 @@
       "_allowedTools": "The prefix matches HOW your Claude is connected to Cookbook: a CLI-added server (claude mcp add ... cookbook ...) exposes mcp__cookbook__*; the claude.ai/desktop CONNECTOR exposes mcp__claude_ai_Cookbook__*. If tasks run but never complete, this mismatch is the usual cause; `npx cookbook-bridge@latest doctor` (tarball: `node bridge/bridge.mjs doctor`) checks it.",
       "_output": "json output lets the Bridge report what each task cost (tokens/$) back to the board — text works too, you just lose the usage report"
     },
+    {
+      "name": "Kimi",
+      "match": [
+        "kimi",
+        "moonshot"
+      ],
+      "enabled": true,
+      "command": [
+        "kimi",
+        "-p",
+        "{prompt}",
+        "--allowedTools",
+        "mcp__cookbook__*",
+        "--output-format",
+        "stream-json"
+      ],
+      "_setup": "Kimi Code CLI (install: curl -fsSL https://code.kimi.com/kimi-code/install.sh | bash, or npm i -g @moonshot-ai/kimi-code; needs 0.39+). Auth: `kimi login` (device code) or /login inside `kimi`; providers live in ~/.kimi-code/config.toml. MCP: `npx cookbook-bridge@latest connect` (tarball: `node bridge/bridge.mjs connect`) writes ~/.kimi-code/mcp.json owner-only (kimi has no `mcp add`). Headless `-p` refuses --yolo/--auto and ALWAYS runs with every tool auto-approved, so --allowedTools is required here: kimi has no such flag, the Bridge turns it into a per-run agent file (--agent-file) whose tools allowlist is exactly this list. Without it, a task's text could run Bash on this machine.",
+      "_usage": "kimi's stream-json carries no token counts; the board shows wall-clock duration for its runs. Thinking is not streamed either, so a long think looks like silence: keep livenessTimeoutSeconds generous on a Kimi-heavy board."
+    },
     {
       "name": "Codex",
       "match": [

package/device.mjs

@@ -12,7 +12,7 @@
  *
  * `connect-agents` runs the same flow but asks for one attributed token per agent
  * CLI found on this machine, then configures each CLI (Claude, Gemini/agy, Codex,
- * OpenClaw). The pieces are exported separately so Bridge Local (local.mjs) can run
+ * OpenClaw, Kimi). The pieces are exported separately so Bridge Local (local.mjs) can run
  * the identical flow behind a button: beginDeviceFlow → waitForDeviceToken →
  * saveLoginConfig → configureClis.
  *
@@ -31,6 +31,7 @@ import { spawn, spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { listWorkspaces } from "./cookbook.mjs";
 import { which, argvForSpawn } from "./hands.mjs";
+import { kimiHome } from "./harden.mjs";
 import { locateConfig, writeConfigFile, cli, updateLine, checkForUpdate } from "./update.mjs";
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
@@ -157,6 +158,7 @@ function exampleAgentVendor(a) {
   if (base === "claude") return "claude";
   if (base === "agy" || base === "gemini") return "gemini";
   if (base === "codex") return "codex";
+  if (base === "kimi" || base === "kimi.exe") return "kimi";
   return "other";
 }
 
@@ -184,7 +186,7 @@ export function seedConfigFromExample(example, found, { log = () => {} } = {}) {
     if (a.runner === "app-server" && hit?.path) a.command = [hit.path];
   }
   cfg.agents = kept;
-  const preferred = ["claude", "codex", "gemini", "openclaw"];
+  const preferred = ["claude", "codex", "gemini", "kimi", "openclaw"];
   const enabled = kept.filter((a) => a.enabled !== false);
   const dflt = preferred.map((v) => enabled.find((a) => exampleAgentVendor(a) === v)).find(Boolean) ?? enabled[0] ?? kept[0] ?? null;
   if (dflt) cfg.default = dflt.name; else delete cfg.default;
@@ -230,6 +232,36 @@ export function findCodexBinary() {
   return which("codex");
 }
 
+/** Kimi's install script puts the binary at $KIMI_CODE_HOME/bin/kimi (~/.kimi-code/bin),
+ *  which a GUI-launched Bridge's PATH does not have; an npm install lands on PATH. */
+export function findKimiBinary({ home = os.homedir(), env = process.env } = {}) {
+  const onPath = which("kimi");
+  if (onPath) return onPath;
+  const c = path.join(kimiHome({ home, env }), "bin", process.platform === "win32" ? "kimi.exe" : "kimi");
+  try { fs.accessSync(c, fs.constants.X_OK); return c; } catch { return null; }
+}
+
+/**
+ * Kimi Code has no `mcp add`; merge-write its user-level mcp.json (docs: mcpServers.<name>
+ * with `url` + `headers` for HTTP). Other servers are kept; the cookbook entry keeps
+ * harmless tuning (timeouts, tool lists) and gets exactly one way in: this bearer.
+ * The file carries a token, so it is owner-only like config.json.
+ */
+export function kimiConfigure(url, token, { home = os.homedir(), env = process.env } = {}) {
+  const cfgPath = path.join(kimiHome({ home, env }), "mcp.json");
+  let current = {};
+  try { current = JSON.parse(fs.readFileSync(cfgPath, "utf8")) ?? {}; } catch { /* fresh file */ }
+  if (typeof current !== "object" || Array.isArray(current)) current = {};
+  const servers = current.mcpServers && typeof current.mcpServers === "object" && !Array.isArray(current.mcpServers) ? current.mcpServers : {};
+  const prev = servers.cookbook && typeof servers.cookbook === "object" ? servers.cookbook : {};
+  const { headers: _h, bearerTokenEnvVar: _b, transport: _t, url: _u, serverUrl: _s, command: _c, args: _a, env: _e, cwd: _w, enabled: _en, ...rest } = prev;
+  current.mcpServers = { ...servers, cookbook: { ...rest, url, headers: { Authorization: `Bearer ${token}` } } };
+  fs.mkdirSync(path.dirname(cfgPath), { recursive: true });
+  fs.writeFileSync(cfgPath, JSON.stringify(current, null, 2) + "\n", { mode: 0o600 });
+  try { fs.chmodSync(cfgPath, 0o600); } catch { /* best-effort on platforms without chmod */ }
+  return cfgPath;
+}
+
 /** agy (Antigravity) has no `mcp add`; merge-write its documented config file. */
 function agyConfigure(url, token) {
   const cfgPath = path.join(process.env.HOME || os.homedir(), ".gemini", "config", "mcp_config.json");
@@ -312,6 +344,8 @@ export function detectClis() {
   if (agy) out.push({ agent: "Gemini", vendor: "gemini", path: agy, kind: "file" });
   const codex = findCodexBinary();
   if (codex) out.push({ agent: "Codex", vendor: "codex", path: codex, kind: "codex" });
+  const kimi = findKimiBinary();
+  if (kimi) out.push({ agent: "Kimi", vendor: "kimi", path: kimi, kind: "kimi" });
   const openclaw = which("openclaw");
   if (openclaw) out.push({ agent: "OpenClaw", vendor: "openclaw", path: openclaw, kind: "openclaw" });
   return out;
@@ -355,6 +389,9 @@ export function configureClis(found, { baseUrl, agentTokens, cfgPath }) {
       } else if (cli.kind === "openclaw") {
         const wrote = openclawConfigure(mcpUrl, token);
         results.push({ agent: cli.agent, ok: true, detail: `connected (${wrote}, streamable-http)` });
+      } else if (cli.kind === "kimi") {
+        const wrote = kimiConfigure(mcpUrl, token);
+        results.push({ agent: cli.agent, ok: true, detail: `connected (${wrote})` });
       }
     } catch (e) {
       results.push({ agent: cli.agent, ok: false, detail: String(e?.message || e).slice(0, 200) });
@@ -542,14 +579,14 @@ function probeAgent(cmd) {
 /**
  * connect-agents — one command, one human approval, every installed agent CLI
  * connected to Cookbook with CORRECT ATTRIBUTION. Detects Claude, Gemini (agy),
- * Codex (ChatGPT app) and OpenClaw; mints one named token per agent in the same
+ * Codex (ChatGPT app), Kimi and OpenClaw; mints one named token per agent in the same
  * approval as the Bridge token; configures each via its official path.
  */
 export async function connectAgents(argv, { willRun = false } = {}) {
   const cfgPath = configPath(argv);
   const found = detectClis();
   if (found.length === 0) {
-    console.log("\nNo agent CLIs found (looked for: claude, agy, codex/ChatGPT.app, openclaw).");
+    console.log("\nNo agent CLIs found (looked for: claude, agy, codex/ChatGPT.app, kimi, openclaw).");
     console.log(`Install one, then re-run: ${cli("connect")}\n`);
     return { ok: false, reason: "no-agents", cfgPath };
   }

package/hands.mjs

@@ -28,8 +28,10 @@
  */
 import fs from "node:fs";
 import os from "node:os";
+import { kimiLoginState } from "./harden.mjs";
 import path from "node:path";
 import { spawn, spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
 
 // ─────────────────────────────────────────────────────────────────────────────
 // REDACTION
@@ -138,6 +140,7 @@ export const SETUP_FILES = Object.freeze([
   ".codex-bridge/config.toml",                     // the Bridge's own Codex home
   ".gemini/config/mcp_config.json",                // agy's MCP config (agy has no `mcp add`)
   ".gemini/antigravity-cli/settings.json",
+  ".kimi-code/mcp.json",                           // kimi's MCP servers (kimi has no `mcp add`)
   ".openclaw/openclaw.json",
   ".cookbook/config.json",                          // Bridge config (projected: tokens stripped)
   ".cookbook/bridge.state.json",                    // attempt counters (projected)
@@ -173,6 +176,8 @@ const NEVER_READ = Object.freeze([
   /(^|\/)\.codex\/auth\.json$/i,
   /(^|\/)\.codex-bridge\/auth\.json$/i,
   /(^|\/)\.gemini\/oauth_creds\.json$/i,
+  /(^|\/)\.kimi-code\/credentials(\/|$)/i,          // kimi OAuth credentials (dir + files)
+  /(^|\/)\.kimi-code\/config\.toml$/i,             // kimi keeps provider API keys HERE, not in env
   /(^|\/)\.openclaw\/(auth|credentials)[^/]*$/i,
   /(^|\/)\.ssh(\/|$)/i,
   /(^|\/)\.gnupg(\/|$)/i,
@@ -310,6 +315,17 @@ const PROJECTIONS = Object.freeze({
 const MAX_FILE_BYTES = 256 * 1024;
 const MAX_OUTPUT_CHARS = 40_000;
 const MAX_DIR_ENTRIES = 400;
+/** The most a single call result may weigh when it leaves this machine. The server
+ *  applies the same cap (src/lib/workspaces/grants.ts MAX_OUTPUT_BYTES); doing it
+ *  here too means a plan of twenty steps or a pre-flight cannot outgrow a receipt. */
+export const MAX_UPLOAD_BYTES = 64 * 1024;
+/** Trim an output to MAX_UPLOAD_BYTES the same way the server does. Pure. */
+export function capOutput(output) {
+  if (output === null || output === undefined) return output;
+  const json = JSON.stringify(output);
+  if (typeof json !== "string" || json.length <= MAX_UPLOAD_BYTES) return output;
+  return { truncated: true, bytes: json.length, preview: json.slice(0, MAX_UPLOAD_BYTES) };
+}
 
 // ─────────────────────────────────────────────────────────────────────────────
 // THE LOCAL CEILING — what this machine will EVER do, regardless of what it is told
@@ -325,7 +341,10 @@ const MAX_DIR_ENTRIES = 400;
  * hand a visitor a directory — only the host's OWN config can (cfg.hosting.folders).
  */
 export const LOCAL_CEILING = Object.freeze({
-  verbs: Object.freeze(["doctor", "env", "read_file", "list_dir", "run", "write_file", "restore_backup", "open_url"]),
+  // `plan` is a container, not a capability: its steps are each checked on their own
+  // (executePlan), so listing it here widens nothing. `preflight` is deliberately
+  // absent: the host runs it on its own initiative and never accepts it as a call.
+  verbs: Object.freeze(["doctor", "env", "read_file", "list_dir", "run", "write_file", "restore_backup", "open_url", "plan"]),
   run_allow: Object.freeze([
     // read
     "node_version", "claude_mcp_list", "cli_versions", "tail_log",
@@ -397,6 +416,11 @@ export const VERB_RISK = Object.freeze({
   write_file: "write",
   restore_backup: "write",
   open_url: "login",
+  // A plan always waits for the host's single click, whatever its steps: "write"
+  // is the label that makes the generic wall say so. Pre-flight is read-only by
+  // construction (env, doctor, CLI versions, the config's shape).
+  plan: "write",
+  preflight: "read",
 });
 
 export const RUN_TEMPLATE_RISK = Object.freeze({
@@ -812,6 +836,7 @@ const VERBS = {
         claude: marker(".claude/.credentials.json"),
         codex: marker(".codex/auth.json"),
         gemini: marker(".gemini/oauth_creds.json"),
+        kimi: kimiLoginState({ home }).loggedIn,
         openclaw: marker(".openclaw"),
       },
       setup_files_present: SETUP_FILES.filter((rel) => marker(rel)),
@@ -949,9 +974,27 @@ const VERBS = {
       stderr: String(res.stderr).slice(0, 4000),
     };
   },
+
+  /**
+   * PRE-FLIGHT: everything a visiting agent would otherwise spend its first four
+   * calls asking. Read-only by construction. The host runs it on its own initiative
+   * the moment a grant becomes active (runPreflight) and posts it as a
+   * host-initiated call; a queued `preflight` from the server is refused by the wall.
+   */
+  async preflight(_args, ctx) {
+    return collectPreflight(ctx);
+  },
+
+  /** A plan is executed by executePlan, never as a bare verb: executeCall routes
+   *  it there before this is reached. Kept in the table so the wall knows the name. */
+  async plan() {
+    return { error: "A plan runs through executePlan, one step at a time." };
+  },
 };
 
 export const VERB_NAMES = Object.freeze(Object.keys(VERBS));
+/** Verbs that contain or replace other calls. Never allowed inside a plan. */
+export const META_VERBS = Object.freeze(["plan", "preflight"]);
 
 // ─────────────────────────────────────────────────────────────────────────────
 // EXECUTION
@@ -962,11 +1005,21 @@ export const VERB_NAMES = Object.freeze(Object.keys(VERBS));
  * whole authorization decision is unit-testable without a machine to break.
  * Returns { ok: true, risk } or { ok: false, error }.
  */
-export function authorizeCall(call, scope) {
+export function authorizeCall(call, scope, opts = {}) {
   if (!call || typeof call.verb !== "string") return { ok: false, error: "Malformed call." };
   if (!scope || typeof scope !== "object") return { ok: false, error: "No grant scope." };
   const verb = call.verb;
   if (!VERBS[verb]) return { ok: false, error: `This Bridge has no verb '${verb}'.` };
+  // The host runs its own pre-flight; it is never something a visitor queues.
+  if (verb === "preflight") return { ok: false, error: "Pre-flight runs on the host's own initiative, never as a queued call." };
+  // A PLAN is a container. Its permission is exactly the permission of its steps,
+  // each of which is checked on its own inside executePlan, so the plan row itself
+  // needs only the one thing a container can carry: the host's click.
+  if (verb === "plan") {
+    if (opts.approvedByPlan) return { ok: false, error: "A plan can't contain another plan." };
+    if (call.status !== "approved") return { ok: false, error: "A plan needs the host's approval before it can run here." };
+    return { ok: true, risk: VERB_RISK.plan };
+  }
   if (!Array.isArray(scope.verbs) || !scope.verbs.includes(verb)) {
     return { ok: false, error: `The grant doesn't allow '${verb}'.` };
   }
@@ -986,8 +1039,10 @@ export function authorizeCall(call, scope) {
   }
   // THE CONSENT WALL: when the grant says a class needs a human, this machine runs
   // it only if the host has already flipped the row to `approved`. A UI bug, or a
-  // server that sends it as `queued`, is refused here.
-  if (policy === "ask" && call.status !== "approved") {
+  // server that sends it as `queued`, is refused here. Inside a plan the host's one
+  // click on the plan row is the click for every step (`approvedByPlan`), and
+  // executePlan sets that flag only when the plan row itself said `approved`.
+  if (policy === "ask" && call.status !== "approved" && opts.approvedByPlan !== true) {
     return { ok: false, error: `That needs the host's approval before it can run here.` };
   }
   return { ok: true, risk };
@@ -998,12 +1053,13 @@ export function authorizeCall(call, scope) {
  * ALWAYS resolves — a thrown verb becomes a failed call, never a crashed Bridge.
  */
 export async function executeCall(call, ctx) {
+  if (call?.verb === "plan") return executePlan(call, ctx);
   const home = ctx.home ?? os.homedir();
   // NEVER the server's scope as sent — always its intersection with what this
   // machine will do at all. This is the line that makes "a lying server cannot make
   // your laptop run something you didn't grant" a true statement instead of a hope.
   const scope = effectiveScope(call.scope ?? ctx.scope, { hostFolders: ctx.hostFolders ?? [], home });
-  const auth = authorizeCall(call, scope);
+  const auth = authorizeCall(call, scope, { approvedByPlan: ctx.approvedByPlan === true });
   if (!auth.ok) return { status: "denied", output: null, error: auth.error };
 
   const args = call.args && typeof call.args === "object" ? call.args : {};
@@ -1015,12 +1071,204 @@ export async function executeCall(call, ctx) {
       // the visitor should see it as such and try something else.
       return { status: "failed", output: null, error: clean.error };
     }
-    return { status: "done", output: clean, error: null };
+    return { status: "done", output: capOutput(clean), error: null };
   } catch (e) {
     return { status: "failed", output: null, error: redact(String(e?.message ?? e), { home }).slice(0, 500) };
   }
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// PLANS — one click, several steps, the same wall for each
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** The most steps one click may cover. A fix needs three or four; twenty is a script. */
+export const PLAN_MAX_STEPS = 20;
+
+/** The hash the server stamps on a plan row: sha256 of the steps EXACTLY as sent.
+ *  Recomputed here before a plan runs, so nothing can be appended after the click. Pure. */
+export function planHash(steps) {
+  return createHash("sha256").update(JSON.stringify(steps)).digest("hex");
+}
+
+/**
+ * Is this plan the plan the host clicked? Structure, size, no nested containers, and
+ * the hash. Returns { ok: true, steps, why } or { ok: false, error }. Pure.
+ */
+export function validatePlan(call) {
+  const args = call?.args && typeof call.args === "object" ? call.args : {};
+  const steps = args.steps;
+  if (!Array.isArray(steps) || steps.length === 0) return { ok: false, error: "A plan needs at least one step." };
+  if (steps.length > PLAN_MAX_STEPS) return { ok: false, error: `A plan may have at most ${PLAN_MAX_STEPS} steps; this one has ${steps.length}.` };
+  for (let i = 0; i < steps.length; i++) {
+    const step = steps[i];
+    if (!step || typeof step !== "object" || typeof step.verb !== "string") return { ok: false, error: `Step ${i + 1} is malformed (needs a verb).` };
+    if (META_VERBS.includes(step.verb)) return { ok: false, error: `Step ${i + 1} is '${step.verb}', which can't be inside a plan.` };
+    if (step.args !== undefined && (step.args === null || typeof step.args !== "object" || Array.isArray(step.args))) {
+      return { ok: false, error: `Step ${i + 1} has malformed args.` };
+    }
+  }
+  // THE HASH: the server cannot append a step after the host clicked, because the
+  // click was on this exact list. A missing hash is a mismatch too.
+  if (typeof call.plan_hash !== "string" || planHash(steps) !== call.plan_hash) return { ok: false, error: "plan hash mismatch" };
+  return { ok: true, steps, why: typeof args.why === "string" ? args.why : "" };
+}
+
+/** The word for a step in the log: the template for a run, the verb otherwise. */
+function stepLabel(step) {
+  if (step?.verb === "run") return String(step.args?.template ?? "run");
+  return String(step?.verb ?? "?");
+}
+
+/**
+ * Run an approved plan step by step, through the SAME authorizeCall + executeCall
+ * path a single call takes. The one difference is `approvedByPlan`: the host's click
+ * on the plan row is the click for every write-class step inside it, and it is set
+ * only when the plan row itself is `approved`. Every step is still measured against
+ * effectiveScope and LOCAL_CEILING on its own, so a step the ceiling forbids fails
+ * the plan at that index. Stops at the first failure. ALWAYS resolves.
+ * `ctx.executeStep` (tests) replaces executeCall for the steps.
+ */
+export async function executePlan(call, ctx) {
+  const home = ctx.home ?? os.homedir();
+  const scope = effectiveScope(call.scope ?? ctx.scope, { hostFolders: ctx.hostFolders ?? [], home });
+  const auth = authorizeCall(call, scope, { approvedByPlan: ctx.approvedByPlan === true });
+  if (!auth.ok) return { status: "denied", output: null, error: auth.error };
+  const v = validatePlan(call);
+  if (!v.ok) return { status: "denied", output: null, error: v.error };
+
+  const runStep = typeof ctx.executeStep === "function" ? ctx.executeStep : executeCall;
+  const total = v.steps.length;
+  const steps = [];
+  let stoppedAt;
+  for (let i = 0; i < total; i++) {
+    if (ctx.stopped?.()) { stoppedAt = i; steps.push({ verb: v.steps[i].verb, ok: false, error: "The Bridge is stopping.", duration_ms: 0 }); break; }
+    const step = v.steps[i];
+    // A step never inherits the row's status: the plan's click reaches it ONLY as
+    // approvedByPlan, which is what the wall is written to look at.
+    const stepCall = {
+      id: `${call.id ?? "plan"}#${i + 1}`,
+      grant_id: call.grant_id,
+      workspace_id: call.workspace_id,
+      visitor: call.visitor,
+      verb: step.verb,
+      args: step.args && typeof step.args === "object" ? step.args : {},
+      status: "queued",
+      scope: call.scope ?? ctx.scope,
+    };
+    const t0 = Date.now();
+    let r;
+    try {
+      r = await runStep(stepCall, { ...ctx, approvedByPlan: call.status === "approved" });
+    } catch (e) {
+      r = { status: "failed", output: null, error: String(e?.message ?? e).slice(0, 500) };
+    }
+    const duration_ms = Date.now() - t0;
+    const ok = r?.status === "done";
+    const row = { verb: step.verb, ...(step.verb === "run" ? { template: stepLabel(step) } : {}), ok, duration_ms };
+    if (ok) row.output = r.output ?? null;
+    else row.error = String(r?.error ?? `step ${r?.status ?? "failed"}`);
+    steps.push(row);
+    ctx.log?.(`◇ plan step ${i + 1}/${total}: ${stepLabel(step)} ... ${ok ? "ok" : `failed: ${row.error}`} (${(duration_ms / 1000).toFixed(1)}s)`);
+    if (!ok) { stoppedAt = i; break; }
+  }
+  const output = capOutput(redactDeep({ steps, ...(stoppedAt !== undefined ? { stopped_at: stoppedAt } : {}) }, { home }));
+  if (stoppedAt !== undefined) {
+    const failed = steps[stoppedAt];
+    return { status: "failed", output, error: redact(`Stopped at step ${stoppedAt + 1} of ${total} (${stepLabel(v.steps[stoppedAt])}): ${failed?.error ?? "failed"}`, { home }).slice(0, 500) };
+  }
+  return { status: "done", output, error: null };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// PRE-FLIGHT — what the host tells a visitor before it asks
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * The four read-only pieces of a pre-flight. Each is a function of the host ctx so a
+ * test can swap one (cli_versions spawns every vendor CLI, which is slow and machine
+ * dependent). Every piece fails on its own: a doctor that throws still leaves env.
+ */
+export const PREFLIGHT_PARTS = Object.freeze({
+  env: (ctx) => VERBS.env({}, ctx),
+  doctor: async (ctx) => {
+    if (typeof ctx.doctor !== "function") return { error: "This Bridge can't run its doctor." };
+    const report = await ctx.doctor();
+    const rows = Array.isArray(report?.rows) ? report.rows : [];
+    return {
+      rows: rows.map((r) => ({ label: String(r?.label ?? ""), ok: r?.level === "ok", detail: typeof r?.fix === "string" ? r.fix : null })),
+      fails: Number(report?.fails ?? rows.filter((r) => r?.level === "bad").length),
+      warns: Number(report?.warns ?? rows.filter((r) => r?.level === "warn").length),
+    };
+  },
+  cli_versions: async (ctx) => {
+    const spec = RUN_TEMPLATES.cli_versions({}, ctx);
+    return spec.local ? spec.local() : { error: spec.error ?? "cli_versions is unavailable" };
+  },
+  bridge_config: (ctx) => {
+    if (!ctx.cfgPath) return { error: "This Bridge has no config path." };
+    let text;
+    try { text = fs.readFileSync(ctx.cfgPath, "utf8"); } catch (e) { return { error: `can't read the config: ${e.code || e.message}` }; }
+    return projectedConfig(text);
+  },
+});
+
+/**
+ * Gather the pre-flight: env, doctor rows, CLI versions and this Bridge's own config
+ * with every token stripped, then redacted and capped exactly like any other result.
+ * Read-only. ALWAYS resolves.
+ */
+export async function collectPreflight(ctx, parts = PREFLIGHT_PARTS) {
+  const home = ctx.home ?? os.homedir();
+  const out = {};
+  for (const key of ["env", "doctor", "cli_versions", "bridge_config"]) {
+    try {
+      out[key] = await parts[key]({ ...ctx, home });
+    } catch (e) {
+      out[key] = { error: String(e?.message ?? e).slice(0, 300) };
+    }
+  }
+  out.at = new Date().toISOString();
+  return capOutput(redactDeep(out, { home }));
+}
+
+/**
+ * Which active grants still owe a pre-flight from this host. A grant counts once it
+ * is `active`, has verbs (a conversation-only grant has no machine), and is neither
+ * already pre-flighted (persisted) nor out of attempts for this process. Pure.
+ */
+export function grantsNeedingPreflight(grants, { preflighted, tried, maxAttempts = 2 } = {}) {
+  const done = preflighted ?? new Set();
+  const attempts = tried ?? new Map();
+  const out = [];
+  for (const g of Array.isArray(grants) ? grants : []) {
+    const id = g?.id;
+    if (typeof id !== "string" || !id) continue;
+    if (g.status && g.status !== "active") continue;
+    if (g.conversation_only === true) continue;
+    if (Array.isArray(g.scope?.verbs) && g.scope.verbs.length === 0) continue;
+    if (done.has(id)) continue;
+    if ((attempts.get(id) ?? 0) >= maxAttempts) continue;
+    out.push(id);
+  }
+  return out;
+}
+
+/**
+ * Run the pre-flight for one grant and post it as a host-initiated call:
+ * `ctx.create(grantId)` asks the server for a call row (POST /api/bridge/hands with
+ * { grant_id, verb: "preflight", host_initiated: true }) and returns its id;
+ * `ctx.report(callId, result)` posts the output through the same route every other
+ * call uses. Throws when the server refuses, so the caller can count the attempt.
+ */
+export async function runPreflight(grantId, ctx) {
+  const output = await collectPreflight(ctx, ctx.preflightParts ?? PREFLIGHT_PARTS);
+  const callId = await ctx.create(grantId);
+  if (typeof callId !== "string" || !callId) throw new Error("the server didn't open a pre-flight call");
+  const posted = await ctx.report(callId, { status: "done", output, error: null });
+  if (posted === false) throw new Error("the server refused the pre-flight result");
+  return { callId, output };
+}
+
 /**
  * The host loop: claim each pending call (CAS server-side), run it, post the result.
  * Serialized per grant — one visiting agent, one pair of hands, one thing at a time,
@@ -1052,6 +1300,12 @@ export function describeCall(call) {
     case "run": return `run ${a.template}`;
     case "doctor": return "run the setup doctor";
     case "env": return "look at what's installed";
+    case "preflight": return "pre-flight: what's installed, the doctor, CLI versions, the config's shape";
+    case "plan": {
+      const steps = Array.isArray(a.steps) ? a.steps : [];
+      const why = typeof a.why === "string" && a.why.trim() ? a.why.trim().slice(0, 120) : "a plan";
+      return `plan: ${why} (${steps.length} step${steps.length === 1 ? "" : "s"}: ${steps.map(stepLabel).join(", ").slice(0, 200)})`;
+    }
     // The three verbs a host must approve are the three that used to render as a
     // bare verb name (ultrareview #123, bug_007). Say WHAT, not just which.
     case "write_file": return `write ${a.path}${typeof a.content === "string" ? ` (${a.content.length} chars)` : ""}`;

package/harden.mjs

@@ -19,6 +19,12 @@
  * 3. AGY VERSION GATE — Antigravity CLI (gemini's successor) below 1.1.1 cannot call
  *    MCP tools in headless -p mode: the run LOOKS fine but complete_task never lands,
  *    burning every attempt. Confirmed-old versions are refused with a clear message.
+ *
+ * 4. KIMI CODE CONTRACT (0.1.12): the fourth vendor's CLI shape lives at the bottom
+ *    of this file: stream parsing, the per-run tool jail (kimi has no --allowedTools),
+ *    login and MCP state. Kept here rather than in a new module so the shipped file
+ *    lists (BRIDGE_RUNTIME_FILES, next.config tracing, package.json files) stay as
+ *    they are.
  */
 import fs from "node:fs";
 import os from "node:os";
@@ -26,7 +32,15 @@ import path from "node:path";
 import { spawn } from "node:child_process";
 
 /** Env vars that flip the official CLIs from subscription auth to API-key billing. */
-export const API_BILLING_KEYS = ["ANTHROPIC_API_KEY", "OPENAI_API_KEY", "GEMINI_API_KEY", "GOOGLE_API_KEY"];
+export const API_BILLING_KEYS = [
+  "ANTHROPIC_API_KEY", "OPENAI_API_KEY", "GEMINI_API_KEY", "GOOGLE_API_KEY",
+  // Kimi Code reads provider keys from config.toml, not the shell, EXCEPT the
+  // env-defined model (KIMI_MODEL_NAME + KIMI_MODEL_API_KEY), which would put a
+  // Bridge run on an API key. KIMI_API_KEY / MOONSHOT_API_KEY are the names the
+  // docs and the Moonshot SDKs use; hidden too, so a future CLI that reads them
+  // cannot flip billing either.
+  "KIMI_API_KEY", "MOONSHOT_API_KEY", "KIMI_MODEL_API_KEY",
+];
 
 /**
  * The environment agent processes get. By default: the parent env MINUS vendor billing
@@ -225,3 +239,228 @@ export function withCookbookMcp(command, { token, cookbookUrl } = {}) {
   });
   return { command: [command[0], "--strict-mcp-config", "--mcp-config", cfg, ...command.slice(1)], injected: true, reason: null };
 }
+
+// ─────────────────────────────────────────────────────────────────────────────
+// KIMI CODE (the fourth vendor, 0.1.12): the CLI contract, pinned empirically
+// ─────────────────────────────────────────────────────────────────────────────
+//
+// Read off `kimi --help` (0.39.1), the prompt-mode emitter in the binary, and the
+// docs at moonshotai.github.io/kimi-code (2026-09-02):
+//
+//  - Headless: `kimi -p "<prompt>" --output-format stream-json`. `-p` takes the
+//    prompt as an argument (there is no stdin mode). `-p` REFUSES --yolo, --auto
+//    and --plan: prompt mode always runs in "auto" permission (every tool call is
+//    approved; static deny rules still apply). There is no --allowedTools flag.
+//    The jail is an agent file: `--agent-file <md>` whose frontmatter `tools:` is
+//    an allowlist (`mcp__cookbook__*` globs work). kimiCommand() below writes one
+//    per run from the command's `--allowedTools` value, so config.json keeps the
+//    same shape as the Claude entry and localizeCommand keeps working.
+//  - stream-json: one JSON object per stdout line, keyed by `role`:
+//      {"role":"meta","type":"system.version","version":"0.39.1"}
+//      {"role":"assistant","content":"..."}                       a finished turn's text
+//      {"role":"assistant","tool_calls":[{"type":"function","id":"...",
+//         "function":{"name":"Read","arguments":"{\"path\":\"...\"}"}}]}
+//      {"role":"tool","tool_call_id":"...","content":"..."}         the tool's output
+//      {"role":"meta","type":"turn.step.retrying","failed_attempt":1,"next_attempt":2,
+//         "max_attempts":10,"delay_ms":557.5,"error_name":"APIConnectionError",
+//         "error_message":"Connection error."}
+//      {"role":"meta","type":"session.resume_hint","session_id":"session_<uuid>",
+//         "command":"kimi -r session_<uuid>","content":"To resume this session: ..."}
+//    Thinking is never written to stdout; tool progress and notices go to stderr.
+//    No usage line exists, so the receipt is duration-only.
+//  - Resume: `-S <id>` (hidden alias `-r`), legal with `-p`, illegal with
+//    `--agent-file` (a resumed session keeps the agent it was created with).
+//  - Model: `-m <alias>`; aliases come from ~/.kimi-code/config.toml.
+//  - MCP: ~/.kimi-code/mcp.json ($KIMI_CODE_HOME/mcp.json): mcpServers.<name> with
+//    `url` (+ `headers`) for HTTP. A project-level .kimi-code/mcp.json exists but
+//    sits behind the workspace-trust prompt, so the Bridge writes the user file.
+//    Tools are named mcp__<server>__<tool>.
+//  - Login: [providers.<name>] in config.toml (api_key, or an oauth table written
+//    by `kimi login`); OAuth credentials under ~/.kimi-code/credentials/.
+
+/** Kimi's data root: $KIMI_CODE_HOME, else ~/.kimi-code. */
+export function kimiHome({ home = process.env.HOME || os.homedir(), env = process.env } = {}) {
+  return env.KIMI_CODE_HOME || path.join(home, ".kimi-code");
+}
+
+/** True when this command (argv array or bare string) runs the kimi CLI. */
+export function isKimiCommand(command) {
+  const first = Array.isArray(command) ? command[0] : command;
+  const base = String(first ?? "").split(/[\\/]/).pop().toLowerCase();
+  return base === "kimi" || base === "kimi.exe";
+}
+
+/** Probe `kimi --version` (e.g. "0.39.1"). No gate: nothing is refused, doctor prints it. */
+export async function checkKimiVersion(argv, timeoutMs = 10_000) {
+  return { version: await probeVersion(argv, timeoutMs) };
+}
+
+/** Kimi built-in tool names the live work log should read as verbs (live.mjs
+ *  already knows Read/Write/Edit/Bash/Grep/Glob/WebSearch by their lowercase). */
+const KIMI_TOOL_VERBS = { fetchurl: "fetch", readmediafile: "read", todolist: "todo", agent: "agent", agentswarm: "agent", skill: "skill" };
+
+/**
+ * One stream-json line → what the Bridge shows. Null for non-kimi lines (a claude
+ * line has `type`, never a top-level `role`). Pure.
+ *   { role, text, calls: [{kind:'call', id, name, input} | {kind:'result', id, err}],
+ *     sessionId, retry: {attempt, max, error} | null }
+ */
+export function kimiFromLine(line) {
+  let j;
+  try { j = JSON.parse(line); } catch { return null; }
+  if (!j || typeof j !== "object" || typeof j.role !== "string") return null;
+  const ev = { role: j.role, text: null, calls: [], sessionId: null, retry: null };
+  if (j.role === "assistant") {
+    if (typeof j.content === "string" && j.content.trim()) ev.text = j.content;
+    for (const tc of Array.isArray(j.tool_calls) ? j.tool_calls : []) {
+      const raw = String(tc?.function?.name ?? tc?.name ?? "").trim();
+      if (!raw) continue;
+      let input = tc?.function?.arguments ?? tc?.arguments;
+      if (typeof input === "string") { try { input = JSON.parse(input); } catch { /* partial or plain text: keep the string */ } }
+      const name = raw.startsWith("mcp__") ? raw : (KIMI_TOOL_VERBS[raw.toLowerCase()] ?? raw);
+      ev.calls.push({ kind: "call", id: String(tc?.id ?? ""), name, input });
+    }
+  } else if (j.role === "tool") {
+    ev.calls.push({ kind: "result", id: String(j.tool_call_id ?? ""), err: kimiToolFailed(j.content) });
+  } else if (j.role === "meta") {
+    if (j.type === "session.resume_hint" && typeof j.session_id === "string" && j.session_id) ev.sessionId = j.session_id;
+    if (j.type === "turn.step.retrying") {
+      ev.retry = {
+        attempt: Number(j.failed_attempt) || 0,
+        max: Number(j.max_attempts) || 0,
+        error: `${j.error_name ?? "error"}${j.error_message ? `: ${j.error_message}` : ""}`,
+      };
+    }
+  }
+  return ev;
+}
+
+/** Best-effort: a tool result that reads as a failure (kimi has no is_error flag). */
+function kimiToolFailed(content) {
+  const text = typeof content === "string" ? content : (content == null ? "" : JSON.stringify(content));
+  return /^\s*(error\b|tool error|permission denied|denied\b|command failed|failed to)/i.test(text);
+}
+
+/**
+ * The claude-shaped result envelope for a finished kimi run, so displayText,
+ * resultError, failureHint and extractUsage need no kimi branch. Pure.
+ */
+export function kimiResultEnvelope({ text = "", sessionId = null, durationMs = 0, code = 0, err = "", numTurns = 0 } = {}) {
+  const failed = typeof code === "number" && code !== 0;
+  const tail = String(err ?? "").trim().split("\n").filter(Boolean).slice(-2).join(" ").slice(0, 300);
+  return JSON.stringify({
+    type: "result",
+    subtype: failed ? "error_during_execution" : "success",
+    is_error: failed,
+    result: String(text ?? ""),
+    duration_ms: Math.max(0, Math.round(Number(durationMs) || 0)),
+    num_turns: numTurns,
+    ...(sessionId ? { session_id: sessionId } : {}),
+    ...(failed ? { errors: [tail || `kimi exited ${code}`] } : {}),
+    runner: "kimi",
+  });
+}
+
+/** Claude tool names that appear in Bridge configs → the kimi name of the same tool. */
+export const KIMI_TOOL_ALIASES = Object.freeze({ WebFetch: "FetchURL", TodoWrite: "TodoList", Task: "Agent" });
+
+/** "Bash,Read,mcp__cookbook__*" → ["Bash", "Read", "mcp__cookbook__*"], kimi names, deduped. */
+export function kimiTools(spec) {
+  const out = [];
+  for (const raw of String(spec ?? "").split(",")) {
+    const t = raw.trim();
+    // Tool names are plain tokens; anything else is not a tool and never reaches YAML.
+    if (!t || !/^[A-Za-z0-9_*.:-]+$/.test(t)) continue;
+    const name = KIMI_TOOL_ALIASES[t] ?? t;
+    if (!out.includes(name)) out.push(name);
+  }
+  return out;
+}
+
+/** The agent file that jails one run: same system prompt, only these tools.
+ *  An empty list means NO tools (kimi: `tools: []`), which is what a summary wants. */
+export function kimiAgentFile(spec) {
+  const tools = kimiTools(spec);
+  const list = tools.length ? "\n" + tools.map((t) => `  - ${t}`).join("\n") : " []";
+  return [
+    "---",
+    "name: cookbook-bridge",
+    "description: A Cookbook Bridge run. Only the tools this task was given.",
+    `tools:${list}`,
+    "---",
+    "${base_prompt}",
+    "",
+  ].join("\n");
+}
+
+/**
+ * Turn a Bridge-shaped kimi command into what the CLI accepts: `--allowedTools X`
+ * (which kimi does not have) becomes `--agent-file <0600 temp file>` carrying X as
+ * the tools allowlist. On a resume (-S/-r/-c) the flag is simply dropped: kimi
+ * refuses --agent-file there and the session already carries the jail it was
+ * created with. Identity for non-kimi commands and commands without the flag.
+ * Returns { command, file, cleanup, tools }. IO; tested.
+ */
+export function kimiCommand(command, { dir = os.tmpdir() } = {}) {
+  const noop = { command, file: null, cleanup: () => {}, tools: null };
+  if (!Array.isArray(command) || !isKimiCommand(command)) return noop;
+  const i = command.indexOf("--allowedTools");
+  if (i < 0) return noop;
+  const spec = i + 1 < command.length ? String(command[i + 1]) : "";
+  const rest = command.filter((_, k) => k !== i && k !== i + 1);
+  const resuming = rest.some((a) => ["-S", "--session", "-r", "--resume", "-c", "-C", "--continue"].includes(String(a)));
+  if (resuming || rest.includes("--agent-file") || rest.includes("--agent")) return { ...noop, command: rest };
+  const privDir = fs.mkdtempSync(path.join(dir, "cookbook-bridge-kimi-"));
+  try { fs.chmodSync(privDir, 0o700); } catch { /* best effort on platforms without modes */ }
+  const file = path.join(privDir, "agent.md");
+  fs.writeFileSync(file, kimiAgentFile(spec), { mode: 0o600 });
+  try { fs.chmodSync(file, 0o600); } catch { /* best effort */ }
+  liveMcpDirs.add(privDir);
+  installMcpExitHook();
+  const cleanup = () => {
+    liveMcpDirs.delete(privDir);
+    try { fs.rmSync(privDir, { recursive: true, force: true }); } catch { /* best effort */ }
+  };
+  return { command: [rest[0], "--agent-file", file, ...rest.slice(1)], file, cleanup, tools: kimiTools(spec) };
+}
+
+/**
+ * Is kimi logged in? Reads what `kimi login` / `/login` write: a [providers.<name>]
+ * section in config.toml with an api_key (or a [providers.<name>.env] key, or an
+ * oauth sub-table), or an OAuth credential file under credentials/. Never throws.
+ */
+export function kimiLoginState({ home = process.env.HOME || os.homedir(), env = process.env } = {}) {
+  const root = kimiHome({ home, env });
+  const configPath = path.join(root, "config.toml");
+  let toml = "";
+  try { toml = fs.readFileSync(configPath, "utf8"); } catch { /* not installed or never run */ }
+  const providers = new Set();
+  let section = null; // "providers.<name>" or "providers.<name>.env" / ".oauth"
+  for (const raw of toml.split(/\r?\n/)) {
+    const line = raw.trim();
+    const head = line.match(/^\[+\s*([^\]]+?)\s*\]+$/);
+    if (head) {
+      const name = head[1].replace(/"/g, "");
+      section = name.startsWith("providers.") ? name : null;
+      if (section && /^providers\.[^.]+\.oauth$/.test(section)) providers.add(section.split(".")[1]);
+      continue;
+    }
+    if (!section) continue;
+    if (/^(api_key|KIMI_API_KEY|MOONSHOT_API_KEY|ANTHROPIC_API_KEY|OPENAI_API_KEY|GOOGLE_API_KEY)\s*=\s*"[^"]+"/.test(line)) providers.add(section.split(".")[1]);
+  }
+  let credentials = 0;
+  try { credentials = fs.readdirSync(path.join(root, "credentials")).filter((f) => f.endsWith(".json")).length; } catch { /* none */ }
+  return { root, configPath, loggedIn: providers.size > 0 || credentials > 0, providers: [...providers], credentials };
+}
+
+/** The Cookbook entry in kimi's user-level mcp.json, judged against this Bridge's URL. */
+export function kimiMcpState({ home = process.env.HOME || os.homedir(), env = process.env, cookbookUrl = null } = {}) {
+  const file = path.join(kimiHome({ home, env }), "mcp.json");
+  let json = null;
+  try { json = JSON.parse(fs.readFileSync(file, "utf8")); } catch { /* absent or unparseable */ }
+  const srv = json && typeof json === "object" && json.mcpServers && typeof json.mcpServers === "object" ? json.mcpServers.cookbook ?? null : null;
+  const url = srv && typeof srv === "object" ? (srv.url ?? srv.serverUrl ?? null) : null;
+  const want = cookbookUrl ? `${String(cookbookUrl).replace(/\/$/, "")}/api/mcp` : null;
+  const hasAuth = !!(srv && typeof srv === "object" && ((srv.headers && srv.headers.Authorization) || srv.bearerTokenEnvVar));
+  return { file, exists: json !== null, server: srv, url, matches: !!url && (!want || url === want), hasAuth };
+}

package/local.mjs

@@ -52,7 +52,7 @@ export function modeForTools(allowedTools) {
  *  vendors' own state). Relative to home. */
 const DENIED_UNDER_HOME = [
   "Library", ".ssh", ".gnupg", ".aws", ".config", ".claude", ".codex", ".codex-bridge",
-  ".gemini", ".openclaw", ".cursor", ".npm", ".nvm", ".Trash",
+  ".gemini", ".kimi-code", ".openclaw", ".cursor", ".npm", ".nvm", ".Trash",
 ];
 
 /**
@@ -100,6 +100,7 @@ export function vendorOf(agent) {
   if (base === "claude") return "claude";
   if (base === "codex" || /ChatGPT\.app|Codex\.app/.test(cmd) || agent.runner === "app-server") return "codex";
   if (base === "agy" || base === "gemini") return "gemini";
+  if (base === "kimi") return "kimi";
   if (base === "openclaw") return "openclaw";
   return "other";
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cookbook-bridge",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "description": "Run your own Claude, Codex and Gemini subscriptions against your Cookbook workspaces. One approval connects every agent CLI on your machine, with a receipt for every run.",
   "type": "module",
   "bin": {
@@ -40,7 +40,7 @@
     "node": ">=18"
   },
   "scripts": {
-    "test": "node --test test/local.test.mjs test/review.test.mjs test/home.test.mjs"
+    "test": "node --test test/local.test.mjs test/review.test.mjs test/home.test.mjs test/kimi.test.mjs test/hands.test.mjs"
   },
   "keywords": [
     "cookbook",