@indianaprado/claude-code-companion 0.1.0 → 0.1.3

package/README.md

@@ -99,6 +99,56 @@ The bundled MCP server exposes:
 - `cancel`
 
 `rescue` is write-capable by default. Pass `readOnly: true` for investigation-only delegation.
+The plugin does not set a default Claude permission mode; pass `permissionMode: "plan"` only when
+you explicitly want Claude's plan mode.
+
+Modes only control edit posture:
+
+- `normal`: no plugin-imposed permission mode.
+- `no_write`: no plan mode; appends a no-edit instruction and denies Claude edit tools.
+- `plan`: passes Claude `--permission-mode plan`.
+- `auto_accept`: passes Claude `--permission-mode acceptEdits`.
+
+The same capability flags are available in every mode:
+
+- `tools`
+- `allowedTools`
+- `disallowedTools`
+- `mcpConfig`
+- `strictMcpConfig`
+- `addDir`
+
+Use `mcpConfig` to give Claude access to local MCP servers for web/search, DBs, browser tools, or
+other local integrations. Avoid recursively giving Claude this `claude-code-companion` MCP unless you
+explicitly want nested Claude calls.
+
+Examples:
+
+```bash
+# Allow web search/fetch in no-write mode.
+node scripts/claude-companion.mjs rescue --mode no_write \
+  --allowed-tools WebSearch,WebFetch \
+  "Use web search to summarize today's NBA Finals news."
+
+# Allow local shell programs in no-write mode.
+node scripts/claude-companion.mjs rescue --mode no_write \
+  --allowed-tools Bash \
+  "Run redis-cli PING and report the output."
+
+# Give Claude local MCP servers.
+node scripts/claude-companion.mjs rescue --mode no_write \
+  --mcp-config /path/to/claude-mcp-config.json \
+  --allowed-tools mcp__server_name__tool_name \
+  "Use the MCP tool and summarize the result."
+```
+
+Important: `no_write` blocks Claude's built-in `Edit` and `Write` tools and tells Claude not to edit.
+If you also grant unrestricted `Bash`, a shell command can still mutate files or external systems.
+For hard no-write isolation with Bash/DB tools, run Claude against read-only credentials or an external
+sandbox.
+
+`maxBudgetUsd` is optional. Omit it for no cap. Very small caps are rejected by default because
+Claude Code can spend more than that loading context before producing a useful reply.
 
 `model` is optional. When omitted, the plugin does not pass `--model`, so Claude CLI chooses its
 current default/latest model. On this machine, that currently selected `claude-opus-4-5-20251101`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indianaprado/claude-code-companion",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "private": false,
   "description": "Claude Code Companion MCP server for Codex.",
   "type": "module",

package/scripts/claude-companion.mjs

@@ -62,13 +62,21 @@ async function executeClaudeJob(cwd, job, request) {
   });
   const result = await runClaude(request.prompt, {
     cwd,
+    mode: request.mode,
     readOnly: request.readOnly,
     resume: request.resume,
     sessionId: request.sessionId,
     model: request.model,
     effort: request.effort,
     maxBudgetUsd: request.maxBudgetUsd,
+    allowTinyBudget: request.allowTinyBudget,
     permissionMode: request.permissionMode,
+    tools: request.tools,
+    allowedTools: request.allowedTools,
+    disallowedTools: request.disallowedTools,
+    mcpConfig: request.mcpConfig,
+    strictMcpConfig: request.strictMcpConfig,
+    addDir: request.addDir,
     onStart: (pid) => {
       markJob(cwd, job.id, { pid, phase: "claude-running" });
       appendLog(job.logFile, `[${now()}] Claude process started pid=${pid}.\n`);
@@ -103,6 +111,7 @@ async function runJobRequest(cwd, request, options = {}) {
     kind: request.kind,
     title: request.title,
     summary: request.summary,
+    mode: request.mode,
     readOnly: request.readOnly,
     background: request.background
   });
@@ -125,11 +134,20 @@ export async function reviewCommand(input = {}) {
     title: input.adversarial ? "Claude Adversarial Review" : "Claude Review",
     summary: input.adversarial ? summarize(input.focus || "Adversarial review") : "Review current git state",
     prompt,
+    mode: input.mode ?? "no_write",
     readOnly: true,
     background: Boolean(input.background),
     model: input.model,
     effort: input.effort,
-    maxBudgetUsd: input.maxBudgetUsd
+    maxBudgetUsd: input.maxBudgetUsd,
+    allowTinyBudget: input.allowTinyBudget,
+    permissionMode: input.permissionMode,
+    tools: input.tools,
+    allowedTools: input.allowedTools,
+    disallowedTools: input.disallowedTools,
+    mcpConfig: input.mcpConfig,
+    strictMcpConfig: input.strictMcpConfig,
+    addDir: input.addDir
   });
 }
 
@@ -138,13 +156,15 @@ export async function rescueCommand(input = {}) {
   if (!input.prompt || !String(input.prompt).trim()) {
     throw new Error("Provide a task prompt for Claude.");
   }
-  const readOnly = Boolean(input.readOnly);
-  const prompt = buildRescuePrompt(input.prompt, { readOnly });
+  const mode = input.mode ?? (input.readOnly ? "no_write" : null);
+  const readOnly = mode === "no_write";
+  const prompt = buildRescuePrompt(input.prompt, { mode, readOnly });
   return runJobRequest(cwd, {
     kind: "task",
     title: input.resume ? "Claude Resume" : "Claude Task",
     summary: summarize(input.prompt),
     prompt,
+    mode,
     readOnly,
     background: Boolean(input.background),
     resume: Boolean(input.resume),
@@ -153,7 +173,14 @@ export async function rescueCommand(input = {}) {
     model: input.model,
     effort: input.effort,
     maxBudgetUsd: input.maxBudgetUsd,
-    permissionMode: input.permissionMode
+    allowTinyBudget: input.allowTinyBudget,
+    permissionMode: input.permissionMode,
+    tools: input.tools,
+    allowedTools: input.allowedTools,
+    disallowedTools: input.disallowedTools,
+    mcpConfig: input.mcpConfig,
+    strictMcpConfig: input.strictMcpConfig,
+    addDir: input.addDir
   });
 }
 
@@ -188,8 +215,24 @@ async function handleWorker(argv) {
 async function main() {
   const [command, ...argv] = process.argv.slice(2);
   const common = {
-    valueOptions: ["cwd", "job-id", "base", "scope", "model", "effort", "max-budget-usd", "session-id", "permission-mode"],
-    booleanOptions: ["json", "background", "read-only", "write", "resume", "fresh", "all", "adversarial", "fork-session"]
+    valueOptions: [
+      "cwd",
+      "job-id",
+      "base",
+      "scope",
+      "model",
+      "effort",
+      "max-budget-usd",
+      "session-id",
+      "permission-mode",
+      "mode",
+      "tools",
+      "allowed-tools",
+      "disallowed-tools",
+      "mcp-config",
+      "add-dir"
+    ],
+    booleanOptions: ["json", "background", "read-only", "write", "resume", "fresh", "all", "adversarial", "fork-session", "allow-tiny-budget", "strict-mcp-config"]
   };
   const { options, positionals } = parseArgs(argv, common);
   const cwd = cwdFrom(options);
@@ -212,9 +255,18 @@ async function main() {
       focus: positionals.join(" "),
       adversarial: command === "adversarial-review" || options.adversarial,
       background: options.background,
+      mode: options.mode,
       model: options.model,
       effort: options.effort,
-      maxBudgetUsd: options["max-budget-usd"]
+      maxBudgetUsd: options["max-budget-usd"],
+      allowTinyBudget: Boolean(options["allow-tiny-budget"]),
+      permissionMode: options["permission-mode"],
+      tools: options.tools,
+      allowedTools: options["allowed-tools"],
+      disallowedTools: options["disallowed-tools"],
+      mcpConfig: options["mcp-config"],
+      strictMcpConfig: Boolean(options["strict-mcp-config"]),
+      addDir: options["add-dir"]
     });
     output(asJson ? response : response.rendered, asJson);
     return;
@@ -223,6 +275,7 @@ async function main() {
     const response = await rescueCommand({
       cwd,
       prompt: positionals.join(" "),
+      mode: options.mode,
       readOnly: Boolean(options["read-only"]) && !options.write,
       background: options.background,
       resume: Boolean(options.resume),
@@ -231,7 +284,14 @@ async function main() {
       model: options.model,
       effort: options.effort,
       maxBudgetUsd: options["max-budget-usd"],
-      permissionMode: options["permission-mode"]
+      allowTinyBudget: Boolean(options["allow-tiny-budget"]),
+      permissionMode: options["permission-mode"],
+      tools: options.tools,
+      allowedTools: options["allowed-tools"],
+      disallowedTools: options["disallowed-tools"],
+      mcpConfig: options["mcp-config"],
+      strictMcpConfig: Boolean(options["strict-mcp-config"]),
+      addDir: options["add-dir"]
     });
     output(asJson ? response : response.rendered, asJson);
     return;

package/scripts/claude-mcp-server.mjs

@@ -12,6 +12,31 @@ import { renderSetup, renderStatus, renderStoredResult } from "./lib/render.mjs"
 
 const PROTOCOL_VERSION = "2024-11-05";
 
+const modeSchema = {
+  type: "string",
+  enum: ["normal", "no_write", "plan", "auto_accept"],
+  description: "Optional high-level Claude mode. normal adds no permission defaults; no_write blocks edit tools without plan mode; plan uses Claude plan mode; auto_accept uses acceptEdits."
+};
+
+const stringOrArraySchema = (description) => ({
+  oneOf: [
+    { type: "string" },
+    { type: "array", items: { type: "string" } }
+  ],
+  description
+});
+
+const capabilityProperties = {
+  mode: modeSchema,
+  tools: { type: "string", description: "Optional pass-through for Claude --tools, for example 'default' or 'Bash,Read,Edit'." },
+  allowedTools: stringOrArraySchema("Optional pass-through for Claude --allowedTools."),
+  disallowedTools: stringOrArraySchema("Optional pass-through for Claude --disallowedTools."),
+  mcpConfig: stringOrArraySchema("Optional path(s) or JSON string(s) passed to Claude --mcp-config."),
+  strictMcpConfig: { type: "boolean", default: false, description: "Pass --strict-mcp-config so Claude uses only the supplied MCP config." },
+  addDir: stringOrArraySchema("Optional additional directory path(s) passed to Claude --add-dir."),
+  permissionMode: { type: "string", description: "Optional raw Claude --permission-mode. Prefer mode unless you need a CLI-specific value." }
+};
+
 const tools = [
   {
     name: "setup",
@@ -35,7 +60,9 @@ const tools = [
         background: { type: "boolean", default: false },
         model: { type: "string", description: "Optional Claude model alias or full model name. Omit to let Claude CLI choose its current default/latest model." },
         effort: { type: "string", enum: ["low", "medium", "high", "xhigh", "max"] },
-        maxBudgetUsd: { type: "number" }
+        maxBudgetUsd: { type: "number", description: "Optional. Omit for no budget cap. Values below 0.25 are rejected unless allowTinyBudget is true." },
+        allowTinyBudget: { type: "boolean", default: false },
+        ...capabilityProperties
       }
     }
   },
@@ -52,7 +79,9 @@ const tools = [
         background: { type: "boolean", default: false },
         model: { type: "string", description: "Optional Claude model alias or full model name. Omit to let Claude CLI choose its current default/latest model." },
         effort: { type: "string", enum: ["low", "medium", "high", "xhigh", "max"] },
-        maxBudgetUsd: { type: "number" }
+        maxBudgetUsd: { type: "number", description: "Optional. Omit for no budget cap. Values below 0.25 are rejected unless allowTinyBudget is true." },
+        allowTinyBudget: { type: "boolean", default: false },
+        ...capabilityProperties
       },
       required: ["focus"]
     }
@@ -72,8 +101,9 @@ const tools = [
         forkSession: { type: "boolean", default: false, description: "Pass through Claude CLI --fork-session when resuming. Behavior depends on the installed Claude CLI." },
         model: { type: "string", description: "Optional Claude model alias or full model name. Omit to let Claude CLI choose its current default/latest model." },
         effort: { type: "string", enum: ["low", "medium", "high", "xhigh", "max"] },
-        maxBudgetUsd: { type: "number" },
-        permissionMode: { type: "string", enum: ["acceptEdits", "auto", "bypassPermissions", "default", "dontAsk", "plan"] }
+        maxBudgetUsd: { type: "number", description: "Optional. Omit for no budget cap. Values below 0.25 are rejected unless allowTinyBudget is true." },
+        allowTinyBudget: { type: "boolean", default: false },
+        ...capabilityProperties
       },
       required: ["prompt"]
     }
@@ -227,7 +257,7 @@ async function handle(message) {
         result: {
           protocolVersion: PROTOCOL_VERSION,
           capabilities: { tools: {} },
-          serverInfo: { name: "claude-code-companion", version: "0.1.0" }
+          serverInfo: { name: "claude-code-companion", version: "0.1.3" }
         }
       });
       return;

package/scripts/lib/claude.mjs

@@ -1,7 +1,8 @@
 import { binaryStatus, spawnCapture } from "./process.mjs";
 
-const READ_ONLY_TOOLS = "Read,Glob,Grep,Bash(git *)";
-const EDIT_TOOLS = "Edit,MultiEdit,Write,NotebookEdit";
+const MIN_BUDGET_USD = 0.25;
+const NO_WRITE_DISALLOWED_TOOLS = "Edit,Write";
+const VALID_MODES = new Set(["normal", "no_write", "plan", "auto_accept"]);
 
 export function getClaudeVersion(cwd) {
   return binaryStatus("claude", ["--version"], { cwd });
@@ -38,6 +39,28 @@ function normalizeEffort(effort) {
   return value;
 }
 
+function normalizeMode(mode) {
+  if (mode == null || mode === "") {
+    return null;
+  }
+  const value = String(mode).trim();
+  if (!VALID_MODES.has(value)) {
+    throw new Error(`Unsupported Claude mode "${mode}". Use normal, no_write, plan, or auto_accept.`);
+  }
+  return value;
+}
+
+function appendStringList(args, flag, value) {
+  if (value == null || value === false) {
+    return;
+  }
+  const values = Array.isArray(value) ? value : [value];
+  const normalized = values.map((entry) => String(entry).trim()).filter(Boolean);
+  if (normalized.length > 0) {
+    args.push(flag, ...normalized);
+  }
+}
+
 function parseClaudeJson(stdout) {
   const text = String(stdout ?? "").trim();
   if (!text) {
@@ -59,6 +82,10 @@ function parseClaudeJson(stdout) {
 
 export async function runClaude(prompt, options = {}) {
   const args = ["-p", prompt, "--output-format", "json"];
+  if (options.mode && options.permissionMode) {
+    throw new Error("Use either mode or permissionMode, not both.");
+  }
+  const mode = normalizeMode(options.mode ?? (options.readOnly ? "no_write" : null));
   if (options.resume) {
     if (options.sessionId) {
       args.push("--resume", options.sessionId);
@@ -78,15 +105,40 @@ export async function runClaude(prompt, options = {}) {
   if (effort) {
     args.push("--effort", effort);
   }
-  if (options.maxBudgetUsd) {
-    args.push("--max-budget-usd", String(options.maxBudgetUsd));
+  appendStringList(args, "--add-dir", options.addDir);
+  appendStringList(args, "--mcp-config", options.mcpConfig);
+  if (options.strictMcpConfig) {
+    args.push("--strict-mcp-config");
+  }
+  if (options.tools) {
+    args.push("--tools", String(options.tools));
+  }
+  if (options.maxBudgetUsd != null) {
+    const budget = Number(options.maxBudgetUsd);
+    if (!Number.isFinite(budget) || budget <= 0) {
+      throw new Error("maxBudgetUsd must be a positive number when provided.");
+    }
+    if (budget < MIN_BUDGET_USD && !options.allowTinyBudget) {
+      throw new Error(
+        `maxBudgetUsd ${budget} is too low for Claude Code's startup/context cost. Omit maxBudgetUsd for no cap, use at least ${MIN_BUDGET_USD}, or set allowTinyBudget: true.`
+      );
+    }
+    args.push("--max-budget-usd", String(budget));
   }
-  if (options.readOnly) {
+  appendStringList(args, "--allowedTools", options.allowedTools);
+  appendStringList(
+    args,
+    "--disallowedTools",
+    mode === "no_write"
+      ? [NO_WRITE_DISALLOWED_TOOLS, ...(Array.isArray(options.disallowedTools) ? options.disallowedTools : [options.disallowedTools]).filter(Boolean)]
+      : options.disallowedTools
+  );
+  if (mode === "plan") {
     args.push("--permission-mode", "plan");
-    args.push("--allowedTools", READ_ONLY_TOOLS);
-    args.push("--disallowedTools", EDIT_TOOLS);
-  } else {
-    args.push("--permission-mode", options.permissionMode || "acceptEdits");
+  } else if (mode === "auto_accept") {
+    args.push("--permission-mode", "acceptEdits");
+  } else if (options.permissionMode) {
+    args.push("--permission-mode", options.permissionMode);
   }
 
   const result = await spawnCapture("claude", args, {

package/scripts/lib/jobs.mjs

@@ -14,6 +14,7 @@ export function createJob(cwd, values) {
     phase: "queued",
     pid: null,
     logFile,
+    mode: values.mode ?? null,
     readOnly: Boolean(values.readOnly),
     background: Boolean(values.background),
     createdAt: now()

package/scripts/lib/prompts.mjs

@@ -16,9 +16,14 @@ export function buildReviewPrompt(cwd, options = {}) {
 }
 
 export function buildRescuePrompt(prompt, options = {}) {
-  const mode = options.readOnly
-    ? "Read-only mode: investigate, reason, and report. Do not edit files."
-    : "Write-capable mode: you may edit files in this checkout when needed to satisfy the task.";
+  const mode =
+    options.mode === "no_write" || options.readOnly
+      ? "No-write mode: investigate, reason, and report. Do not edit files."
+      : options.mode === "plan"
+        ? "Plan mode requested: analyze and propose a plan without editing files."
+        : options.mode === "auto_accept"
+          ? "Auto-accept mode requested: you may edit files in this checkout when needed to satisfy the task."
+          : "";
   return [mode, "You are Claude Code being called by Codex as a companion agent.", "Task:", prompt]
     .filter(Boolean)
     .join("\n\n");

package/scripts/lib/render.mjs

@@ -37,7 +37,7 @@ export function renderTaskResult(job, result) {
     "",
     `Job: ${job.id}`,
     `Status: ${result.status === 0 ? "completed" : "failed"}`,
-    `Mode: ${job.readOnly ? "read-only" : "write-capable"}`,
+    `Mode: ${job.mode ?? (job.readOnly ? "no_write" : "normal")}`,
     result.sessionId ? `Claude session: ${result.sessionId}` : "",
     result.costUsd != null ? `Cost: $${result.costUsd}` : "",
     "",
@@ -60,7 +60,7 @@ export function renderStatus(jobs) {
   const rows = ["| Job | Kind | Status | Phase | Mode | Elapsed | Summary |", "| --- | --- | --- | --- | --- | --- | --- |"];
   for (const job of jobs) {
     rows.push(
-      `| ${job.id} | ${job.kind ?? ""} | ${job.status ?? ""} | ${job.phase ?? ""} | ${job.readOnly ? "read-only" : "write"} | ${elapsed(job)} | ${(job.summary ?? "").replaceAll("|", "\\|")} |`
+      `| ${job.id} | ${job.kind ?? ""} | ${job.status ?? ""} | ${job.phase ?? ""} | ${job.mode ?? (job.readOnly ? "no_write" : "normal")} | ${elapsed(job)} | ${(job.summary ?? "").replaceAll("|", "\\|")} |`
     );
   }
   return `${rows.join("\n")}\n`;

package/skills/claude-code-runtime/SKILL.md

@@ -24,5 +24,9 @@ Use the `claude-code-companion` MCP tools as a thin runtime bridge to the instal
 - Use read-only review tools when the user asks for critique, planning, diagnosis, or a second opinion without edits.
 - Use write-capable `rescue` when the user explicitly wants Claude to implement or fix something.
 - Omit `model` when the user wants Claude CLI's current default/latest model. Pass `model` only when the user asks for a specific alias or full model name.
+- Omit `maxBudgetUsd` unless the user explicitly asks for a budget cap.
+- Omit `permissionMode` unless the user explicitly asks for a Claude permission mode such as `plan`.
+- Use `mode: "no_write"` when Claude should be able to investigate normally but must not edit files. This is not plan mode.
+- Capability fields (`tools`, `allowedTools`, `disallowedTools`, `mcpConfig`, `strictMcpConfig`, `addDir`) are available in every mode. Pass them only when the user wants Claude to use extra local tools, MCP servers, DB access, browser/search tools, or extra directories.
 - Claude runs in the same checkout. Do not assume worktree isolation.
 - Preserve the user's task text. Add only minimal context needed to make the delegation clear.