gaslamp 1.0.0 → 1.1.0

package/README.md

@@ -63,11 +63,21 @@ A Codex→Claude consult with no `sandbox` arg runs with your own Claude config
 would. Per-call overrides: `read-only` (advisory, no edits) or `danger-full-access`
 (full read/write). Claude has no filesystem sandbox, so there's no `workspace-write`.
 
+## Recursion
+
+A consult is **one hop** by default: a Claude reached through gaslamp can't turn
+around and consult Codex, and a Codex reached through gaslamp can't consult Claude
+back. (The Claude→Codex registration tags the consulted Codex with
+`GASLAMP_NESTED=1`, and the spawned Claude is denied the bridge with
+`--disallowedTools mcp__gaslamp`.) Only the top-level agent you drive can open a
+consult. Set `GASLAMP_ALLOW_RECURSION=1` to restore unbounded, symmetric handoffs.
+
 ## Env knobs
 
 | var | default | meaning |
 |-----|---------|---------|
 | `GASLAMP_ALLOWED_TOOLS` | `Read Grep Glob WebFetch WebSearch` | tools the `read-only` override permits |
+| `GASLAMP_ALLOW_RECURSION` | unset | allow a consulted agent to consult back (off = one hop) |
 | `GASLAMP_LOGFILE` | `~/.codex/gaslamp.log` | transcript path; `off` to disable |
 | `GASLAMP_DEBUG` | unset | verbose stderr (raw JSON-RPC) |
 | `CLAUDE_BIN` | autodetected | path to the `claude` binary |

package/bin/gaslamp.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// gaslamp — pass the lamp between Claude Code and Codex over MCP.
+// gaslamp: Minimal MCP server that lets Claude and Codex talk to each other.
 //
 //   gaslamp            run the MCP server on stdio (what Codex spawns)
 //   gaslamp serve      same as above, explicit
@@ -18,7 +18,7 @@ import { fileURLToPath } from "node:url";
 const HERE = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(HERE, "..", "package.json"), "utf8"));
 
-const HELP = `gaslamp ${pkg.version} — pass the lamp between Claude Code and Codex over MCP
+const HELP = `gaslamp ${pkg.version}: Minimal MCP server that lets Claude and Codex talk to each other.
 
 Usage:
   gaslamp [serve]        Run the MCP server on stdio (what Codex spawns).

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "gaslamp",
-  "version": "1.0.0",
-  "description": "Pass the lamp between Claude Code and Codex over MCP — either agent can hand work to the other for a review, a second opinion, or a fix. Zero dependencies.",
+  "version": "1.1.0",
+  "description": "Minimal MCP server that lets Claude and Codex talk to each other.",
   "type": "module",
   "bin": {
     "gaslamp": "bin/gaslamp.mjs"

package/src/server.mjs

@@ -10,8 +10,14 @@
 //   - Per-call `sandbox` arg; OMITTING it defers to the user's own Claude config
 //     (~/.claude settings: permission defaultMode, allow/deny rules, model, MCP,
 //     CLAUDE.md), the mirror of Codex deferring to `sandbox_mode` in config.toml.
-//   - No bespoke timeout and no recursion isolation — a consulted Claude loads
-//     the user's full config/MCP, exactly as a consulted Codex does.
+//   - No bespoke timeout — a consulted Claude loads the user's full config/MCP,
+//     exactly as a consulted Codex does.
+//   - Recursion guard (default on): a consult is one hop. The Claude we spawn is
+//     denied the Claude→Codex bridge (`--disallowedTools mcp__gaslamp`, a deny
+//     rule that holds even under --dangerously-skip-permissions), and if THIS
+//     server is itself running under a consulted Codex (GASLAMP_NESTED, set on
+//     the Claude→Codex registration by `gaslamp setup`) it refuses the call.
+//     GASLAMP_ALLOW_RECURSION=1 restores the old unbounded symmetric handoff.
 //   - The lone Claude-only step (no Codex analog, so not an asymmetry):
 //     ANTHROPIC_API_KEY is stripped from the child env so keychain OAuth is
 //     authoritative. A stale env key 401s every call otherwise.
@@ -57,6 +63,14 @@ const ALLOWED_TOOLS = (process.env.GASLAMP_ALLOWED_TOOLS || "Read Grep Glob WebF
   .split(/[\s,]+/).filter(Boolean).join(",");
 const DEBUG = !!process.env.GASLAMP_DEBUG;
 
+// Recursion guard: a consult is one hop unless explicitly opted out of.
+//   ALLOW_RECURSION — restore the old symmetric, unbounded handoff.
+//   NESTED          — this server is running under a Codex that is itself a
+//                     gaslamp consult (tagged GASLAMP_NESTED=1 on the
+//                     Claude→Codex registration); refuse to hand work back.
+const ALLOW_RECURSION = !!process.env.GASLAMP_ALLOW_RECURSION;
+const NESTED = !!process.env.GASLAMP_NESTED && !ALLOW_RECURSION;
+
 // Persistent consultation transcript (the lightweight "watch them talk" log).
 // Defaults to ~/.codex/gaslamp.log; set GASLAMP_LOGFILE=off to disable.
 const LOGFILE = process.env.GASLAMP_LOGFILE === "off" ? null
@@ -78,6 +92,20 @@ function send(msg) { process.stdout.write(JSON.stringify(msg) + "\n"); }
 function reply(id, result) { send({ jsonrpc: "2.0", id, result }); }
 function fail(id, code, message) { send({ jsonrpc: "2.0", id, error: { code, message } }); }
 
+// Refuse a consult that would be a second hop: this server runs under a Codex
+// that is itself a gaslamp consult. Returned as a readable tool result (not a
+// protocol error) so the consulting Codex sees why, mirroring the claude-error
+// shape in runClaude.
+function refuseNested(id, name) {
+  const text =
+    "Recursive gaslamp consultation is disabled. This Codex is itself a gaslamp " +
+    "consult (GASLAMP_NESTED is set), so it can't hand work back to Claude — a " +
+    "consult is one hop. Set GASLAMP_ALLOW_RECURSION=1 to allow nested handoffs.";
+  log("refuse nested", name);
+  transcript(`← refused ${name} (nested; recursion disabled)`);
+  reply(id, { content: [{ type: "text", text }], structuredContent: { sessionId: null, content: text }, isError: true });
+}
+
 // Mirrors codex's `{ threadId, content }` outputSchema. sessionId may be null on
 // a hard failure, so only `content` is required.
 const OUTPUT_SCHEMA = {
@@ -99,10 +127,12 @@ const TOOLS = [
   {
     name: "gaslamp",
     title: "Claude",
+    // Mirrors codex mcp-server's `codex` description ("Run a Codex session.
+    // Accepts configuration parameters matching the Codex Config struct.") so the
+    // two directions read as twins. "config" (not "Config struct") because Claude
+    // Code has no such struct and gaslamp takes no `config` param — honest mirror.
     description:
-      "Start a Claude Code session for a code review, second opinion, or fix. Claude works in " +
-      "`cwd` and returns a summary of what it found or changed. Returns a sessionId; pass it to " +
-      "gaslamp-reply to continue the same thread with full context.",
+      "Run a Claude session. Accepts configuration parameters matching the Claude Code config.",
     inputSchema: {
       type: "object",
       additionalProperties: false,
@@ -119,7 +149,9 @@ const TOOLS = [
   {
     name: "gaslamp-reply",
     title: "Claude Reply",
-    description: "Continue a Claude consultation by providing the sessionId and prompt, preserving its context.",
+    // Mirrors codex's `codex-reply`: "Continue a Codex conversation by providing
+    // the thread id and prompt." (thread id → session id).
+    description: "Continue a Claude conversation by providing the session id and prompt.",
     inputSchema: {
       type: "object",
       additionalProperties: false,
@@ -150,6 +182,12 @@ function runClaude({ prompt, cwd, model, sandbox, resume }, id) {
   }
   // else (omitted): pass no permission flag — the consulted Claude uses the
   // user's own ~/.claude config, mirroring Codex deferring to config.toml.
+
+  // Recursion guard: deny the consulted Claude the Claude→Codex bridge so it
+  // can't open a further sub-session. A bare server name removes all of
+  // gaslamp's tools from its context, and deny rules hold even under
+  // --dangerously-skip-permissions. GASLAMP_ALLOW_RECURSION=1 opts back in.
+  if (!ALLOW_RECURSION) args.push("--disallowedTools", "mcp__gaslamp");
   if (resume) args.push("--resume", resume);
   if (model) args.push("--model", model);
 
@@ -204,6 +242,7 @@ function handle(msg) {
   } else if (method === "tools/call") {
     const name = params?.name;
     const a = params?.arguments || {};
+    if (NESTED && (name === "gaslamp" || name === "gaslamp-reply")) return refuseNested(id, name);
     if (name === "gaslamp") {
       if (!a.prompt) return fail(id, -32602, "missing required arg: prompt");
       runClaude({ prompt: a.prompt, cwd: a.cwd, model: a.model, sandbox: a.sandbox }, id);

package/src/setup.mjs

@@ -16,6 +16,8 @@
 //                            the package is published, or for from-source dev.
 
 import { spawnSync } from "node:child_process";
+import { readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { which } from "./which.mjs";
@@ -26,6 +28,45 @@ function run(label, cmd, args) {
   return r.status === 0;
 }
 
+// `codex mcp add` cannot persist per-server timeouts (its `-c` flag is a runtime
+// override that never lands in the block), so we patch ~/.codex/config.toml
+// directly. Without this, Codex's MCP client kills any tools/call that runs past
+// its default tool_timeout_sec — a substantial consult (30-45 min) dies with
+// `timed out awaiting tools/call after 120s` while the gaslamp child keeps
+// working, orphaned. The server itself has no timeout; this is the client side.
+// Idempotent: sets the keys in-place if present, inserts them if not.
+function patchCodexTimeouts() {
+  const tool = process.env.GASLAMP_TOOL_TIMEOUT_SEC || "100000"; // ~27.8h — matches Claude Code's own default MCP tool timeout (1e8 ms), so both directions are symmetric
+  const startup = process.env.GASLAMP_STARTUP_TIMEOUT_SEC || "30"; // headroom for npx cold-start
+  const cfgPath = join(process.env.CODEX_HOME || join(homedir(), ".codex"), "config.toml");
+
+  let text;
+  try { text = readFileSync(cfgPath, "utf8"); }
+  catch { console.warn(`  (could not read ${cfgPath}; skipped timeout patch)`); return; }
+
+  const lines = text.split("\n");
+  const header = lines.findIndex((l) => l.trim() === "[mcp_servers.gaslamp]");
+  if (header < 0) { console.warn("  (no [mcp_servers.gaslamp] block found; skipped timeout patch)"); return; }
+
+  // Block runs from the header to the next table header (line starting with `[`).
+  let end = lines.length;
+  for (let i = header + 1; i < lines.length; i++) { if (/^\s*\[/.test(lines[i])) { end = i; break; } }
+  const block = lines.slice(header, end);
+
+  const setKey = (key, val) => {
+    const i = block.findIndex((l) => new RegExp(`^\\s*${key}\\s*=`).test(l));
+    if (i >= 0) { block[i] = `${key} = ${val}`; return; }
+    let at = block.length;                       // insert before trailing blank lines
+    while (at > 1 && block[at - 1].trim() === "") at--;
+    block.splice(at, 0, `${key} = ${val}`);
+  };
+  setKey("tool_timeout_sec", tool);
+  setKey("startup_timeout_sec", startup);
+
+  writeFileSync(cfgPath, [...lines.slice(0, header), ...block, ...lines.slice(end)].join("\n"));
+  process.stdout.write(`  timeouts: tool_timeout_sec=${tool}s startup_timeout_sec=${startup}s in ${cfgPath}\n`);
+}
+
 // Quietly remove an existing registration (ignore "not found" noise).
 function remove(cli, name, scopeArgs = []) {
   spawnSync(cli, ["mcp", "remove", name, ...scopeArgs], { stdio: "ignore" });
@@ -62,12 +103,18 @@ export function runSetup(argv = []) {
     serveCmd = ["mcp", "add", "gaslamp", "--", "npx", "-y", "gaslamp", "serve"];
   }
   const okCodex = run("codex -> claude", "codex", serveCmd);
+  if (okCodex) patchCodexTimeouts(); // codex mcp add can't persist these; do it ourselves
 
   // --- Claude -> Codex: claude gets gaslamp's codex tools (user scope) --------
+  // `--env GASLAMP_NESTED=1` tags every Codex spawned as a Claude consult as
+  // nested, so gaslamp's server.mjs refuses if that consulted Codex tries to
+  // hand work back to Claude — a consult is one hop (GASLAMP_ALLOW_RECURSION=1
+  // opts back in). Placement is safe: the server name `gaslamp` precedes --env
+  // and `--` follows it, so the name is never misread as a KEY=VALUE pair.
   remove("claude", "gaslamp", ["-s", "user"]);
   remove("claude", "codex", ["-s", "user"]); // legacy name
   const okClaude = run("claude -> codex", "claude",
-    ["mcp", "add", "gaslamp", "-s", "user", "--", "codex", "mcp-server"]);
+    ["mcp", "add", "gaslamp", "-s", "user", "--env", "GASLAMP_NESTED=1", "--", "codex", "mcp-server"]);
 
   console.log();
   if (okCodex && okClaude) {