claude-octopus 1.0.1 → 1.0.2

package/README.md

@@ -1,3 +1,7 @@
+<p align="center">
+  <img src="assets/claude-octopus-icon.svg" alt="Claude Octopus" width="200" />
+</p>
+
 # Claude Octopus
 
 One brain, many arms.
@@ -120,23 +124,27 @@ In factory-only mode, no query tools are registered — just the wizard. This ke
 
 Each non-factory instance exposes:
 
-| Tool | Purpose |
-|------|---------|
-| `<name>` | Send a task to the agent, get a response + `session_id` |
-| `<name>_reply` | Continue a previous conversation by `session_id` |
+| Tool           | Purpose                                                 |
+| -------------- | ------------------------------------------------------- |
+| `<name>`       | Send a task to the agent, get a response + `session_id` |
+| `<name>_reply` | Continue a previous conversation by `session_id`        |
 
 Per-invocation parameters (override server defaults):
 
-| Parameter | Description |
-|-----------|-------------|
-| `prompt` | The task or question (required) |
-| `cwd` | Working directory override |
-| `model` | Model override |
-| `allowedTools` | Tool whitelist (intersects with server default) |
-| `disallowedTools` | Tool blacklist (unions with server default) |
-| `maxTurns` | Max conversation turns |
-| `maxBudgetUsd` | Max spend in USD |
-| `systemPrompt` | Additional prompt (appended to server default) |
+| Parameter         | Description                                     |
+| ----------------- | ----------------------------------------------- |
+| `prompt`          | The task or question (required)                 |
+| `cwd`             | Working directory override                      |
+| `model`           | Model override                                  |
+| `tools`           | Restrict available tools (intersects with server restriction) |
+| `disallowedTools` | Block additional tools (unions with server blacklist) |
+| `additionalDirs`  | Extra directories the agent can access           |
+| `plugins`         | Additional plugin paths to load                  |
+| `effort`          | Thinking effort (`low`, `medium`, `high`, `max`) |
+| `permissionMode`  | Permission mode (can only tighten, never loosen) |
+| `maxTurns`        | Max conversation turns                          |
+| `maxBudgetUsd`    | Max spend in USD                                |
+| `systemPrompt`    | Additional prompt (appended to server default)  |
 
 ## Configuration
 
@@ -144,50 +152,50 @@ All configuration is via environment variables in `.mcp.json`. Every env var is
 
 ### Identity
 
-| Env Var | Description | Default |
-|---------|-------------|---------|
-| `CLAUDE_TOOL_NAME` | Tool name prefix (`<name>` and `<name>_reply`) | `claude_code` |
-| `CLAUDE_DESCRIPTION` | Tool description shown to the host AI | generic |
-| `CLAUDE_SERVER_NAME` | MCP server name in protocol handshake | `claude-octopus` |
-| `CLAUDE_FACTORY_ONLY` | Only expose the factory wizard tool | `false` |
+| Env Var               | Description                                    | Default          |
+| --------------------- | ---------------------------------------------- | ---------------- |
+| `CLAUDE_TOOL_NAME`    | Tool name prefix (`<name>` and `<name>_reply`) | `claude_code`    |
+| `CLAUDE_DESCRIPTION`  | Tool description shown to the host AI          | generic          |
+| `CLAUDE_SERVER_NAME`  | MCP server name in protocol handshake          | `claude-octopus` |
+| `CLAUDE_FACTORY_ONLY` | Only expose the factory wizard tool            | `false`          |
 
 ### Agent
 
-| Env Var | Description | Default |
-|---------|-------------|---------|
-| `CLAUDE_MODEL` | Model (`sonnet`, `opus`, `haiku`, or full ID) | SDK default |
-| `CLAUDE_CWD` | Working directory | `process.cwd()` |
-| `CLAUDE_PERMISSION_MODE` | `default`, `acceptEdits`, `bypassPermissions`, `plan` | `default` |
-| `CLAUDE_ALLOWED_TOOLS` | Comma-separated tool whitelist | all |
-| `CLAUDE_DISALLOWED_TOOLS` | Comma-separated tool blacklist | none |
-| `CLAUDE_MAX_TURNS` | Max conversation turns | unlimited |
-| `CLAUDE_MAX_BUDGET_USD` | Max spend per invocation | unlimited |
-| `CLAUDE_EFFORT` | `low`, `medium`, `high`, `max` | SDK default |
+| Env Var                   | Description                                           | Default         |
+| ------------------------- | ----------------------------------------------------- | --------------- |
+| `CLAUDE_MODEL`            | Model (`sonnet`, `opus`, `haiku`, or full ID)         | SDK default     |
+| `CLAUDE_CWD`              | Working directory                                     | `process.cwd()` |
+| `CLAUDE_PERMISSION_MODE`  | `default`, `acceptEdits`, `bypassPermissions`, `plan` | `default`       |
+| `CLAUDE_ALLOWED_TOOLS`    | Comma-separated tool restriction (available tools)    | all             |
+| `CLAUDE_DISALLOWED_TOOLS` | Comma-separated tool blacklist                        | none            |
+| `CLAUDE_MAX_TURNS`        | Max conversation turns                                | unlimited       |
+| `CLAUDE_MAX_BUDGET_USD`   | Max spend per invocation                              | unlimited       |
+| `CLAUDE_EFFORT`           | `low`, `medium`, `high`, `max`                        | SDK default     |
 
 ### Prompts
 
-| Env Var | Description |
-|---------|-------------|
-| `CLAUDE_SYSTEM_PROMPT` | Replaces the default Claude Code system prompt |
+| Env Var                | Description                                            |
+| ---------------------- | ------------------------------------------------------ |
+| `CLAUDE_SYSTEM_PROMPT` | Replaces the default Claude Code system prompt         |
 | `CLAUDE_APPEND_PROMPT` | Appended to the default prompt (usually what you want) |
 
 ### Advanced
 
-| Env Var | Description |
-|---------|-------------|
-| `CLAUDE_ADDITIONAL_DIRS` | Extra directories to grant access (comma-separated) |
-| `CLAUDE_PLUGINS` | Local plugin paths (comma-separated) |
-| `CLAUDE_MCP_SERVERS` | MCP servers for the inner agent (JSON) |
+| Env Var                  | Description                                              |
+| ------------------------ | -------------------------------------------------------- |
+| `CLAUDE_ADDITIONAL_DIRS` | Extra directories to grant access (comma-separated)      |
+| `CLAUDE_PLUGINS`         | Local plugin paths (comma-separated)                     |
+| `CLAUDE_MCP_SERVERS`     | MCP servers for the inner agent (JSON)                   |
 | `CLAUDE_PERSIST_SESSION` | `true`/`false` — enable session resume (default: `true`) |
-| `CLAUDE_SETTING_SOURCES` | Settings to load: `user`, `project`, `local` |
-| `CLAUDE_SETTINGS` | Path to settings JSON or inline JSON |
-| `CLAUDE_BETAS` | Beta features (comma-separated) |
+| `CLAUDE_SETTING_SOURCES` | Settings to load: `user`, `project`, `local`             |
+| `CLAUDE_SETTINGS`        | Path to settings JSON or inline JSON                     |
+| `CLAUDE_BETAS`           | Beta features (comma-separated)                          |
 
 ### Authentication
 
-| Env Var | Description | Default |
-|---------|-------------|---------|
-| `ANTHROPIC_API_KEY` | Anthropic API key for this agent | inherited from parent |
+| Env Var                   | Description                            | Default               |
+| ------------------------- | -------------------------------------- | --------------------- |
+| `ANTHROPIC_API_KEY`       | Anthropic API key for this agent       | inherited from parent |
 | `CLAUDE_CODE_OAUTH_TOKEN` | Claude Code OAuth token for this agent | inherited from parent |
 
 Leave both unset to inherit auth from the parent process. Set one per agent to use a different account or billing source.
@@ -196,10 +204,10 @@ Lists accept JSON arrays when values contain commas: `["path,with,comma", "/norm
 
 ## Security
 
-- **Permission mode defaults to `default`** — tool executions prompt for approval unless you explicitly set `bypassPermissions`.
-- **`cwd` overrides are confined** — per-invocation `cwd` must be a descendant of the server-level base directory. Traversal attempts are silently ignored.
-- **Tool restrictions narrow, never widen** — per-invocation `allowedTools` intersects with the server whitelist (can only remove tools, not add). `disallowedTools` unions (can only block more).
-- **`_reply` tool respects persistence** — not registered when `CLAUDE_PERSIST_SESSION=false`.
+- **Permission mode defaults to ****`default`** — tool executions prompt for approval unless you explicitly set `bypassPermissions`.
+- **`cwd` overrides preserve agent knowledge** — when the host overrides `cwd`, the agent's configured base directory is automatically added to `additionalDirectories` so it retains access to its own context.
+- **Tool restrictions narrow, never widen** — per-invocation `tools` intersects with the server restriction (can only remove tools, not add). `disallowedTools` unions (can only block more).
+- **`_reply`**** tool respects persistence** — not registered when `CLAUDE_PERSIST_SESSION=false`.
 
 ## Architecture
 
@@ -232,14 +240,14 @@ Lists accept JSON arrays when values contain commas: `["path,with,comma", "/norm
 
 ## How It Compares
 
-| Feature | [`claude mcp serve`](https://code.claude.com/docs/en/mcp) | [claude-code-mcp](https://github.com/steipete/claude-code-mcp) | **Claude Octopus** |
-|---------|--------------------|--------------------------|--------------------|
-| Approach | Built-in | CLI wrapping | Agent SDK |
-| Exposes | 16 raw tools | 1 prompt tool | 1 prompt + reply |
-| Multi-instance | No | No | Yes |
-| Per-instance config | No | No | Yes (18 env vars) |
-| Factory wizard | No | No | Yes |
-| Session continuity | No | No | Yes |
+| Feature             | ``         | [claude-code-mcp](https://github.com/steipete/claude-code-mcp) | **Claude Octopus** |
+| ------------------- | ------------ | -------------------------------------------------------------- | ------------------ |
+| Approach            | Built-in     | CLI wrapping                                                   | Agent SDK          |
+| Exposes             | 16 raw tools | 1 prompt tool                                                  | 1 prompt + reply   |
+| Multi-instance      | No           | No                                                             | Yes                |
+| Per-instance config | No           | No                                                             | Yes (18 env vars)  |
+| Factory wizard      | No           | No                                                             | Yes                |
+| Session continuity  | No           | No                                                             | Yes                |
 
 ## Development
 
@@ -247,7 +255,7 @@ Lists accept JSON arrays when values contain commas: `["path,with,comma", "/norm
 pnpm install
 pnpm build       # compile TypeScript
 pnpm test        # run tests (vitest)
-pnpm test:coverage  # 100% coverage
+pnpm test:coverage  # coverage report
 ```
 
 ## License

package/assets/claude-octopus-icon.svg

@@ -0,0 +1,50 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 32 32" shape-rendering="crispEdges">
+<rect x="7" y="6" width="18" height="1" fill="#C56F52"/>
+<rect x="7" y="7" width="18" height="1" fill="#C56F52"/>
+<rect x="7" y="8" width="18" height="1" fill="#C56F52"/>
+<rect x="7" y="9" width="18" height="1" fill="#C56F52"/>
+<rect x="7" y="10" width="4" height="1" fill="#C56F52"/>
+<rect x="13" y="10" width="6" height="1" fill="#C56F52"/>
+<rect x="21" y="10" width="4" height="1" fill="#C56F52"/>
+<rect x="7" y="11" width="4" height="1" fill="#C56F52"/>
+<rect x="13" y="11" width="6" height="1" fill="#C56F52"/>
+<rect x="21" y="11" width="4" height="1" fill="#C56F52"/>
+<rect x="5" y="12" width="22" height="1" fill="#C56F52"/>
+<rect x="5" y="13" width="22" height="1" fill="#C56F52"/>
+<rect x="3" y="14" width="26" height="1" fill="#C56F52"/>
+<rect x="3" y="15" width="26" height="1" fill="#C56F52"/>
+<rect x="3" y="16" width="26" height="1" fill="#C56F52"/>
+<rect x="3" y="17" width="26" height="1" fill="#C56F52"/>
+<rect x="3" y="18" width="2" height="1" fill="#C56F52"/>
+<rect x="7" y="18" width="18" height="1" fill="#C56F52"/>
+<rect x="27" y="18" width="2" height="1" fill="#C56F52"/>
+<rect x="3" y="19" width="2" height="1" fill="#C56F52"/>
+<rect x="7" y="19" width="18" height="1" fill="#C56F52"/>
+<rect x="27" y="19" width="2" height="1" fill="#C56F52"/>
+<rect x="3" y="20" width="2" height="1" fill="#C56F52"/>
+<rect x="7" y="20" width="18" height="1" fill="#C56F52"/>
+<rect x="27" y="20" width="2" height="1" fill="#C56F52"/>
+<rect x="3" y="21" width="2" height="1" fill="#C56F52"/>
+<rect x="7" y="21" width="18" height="1" fill="#C56F52"/>
+<rect x="27" y="21" width="2" height="1" fill="#C56F52"/>
+<rect x="7" y="22" width="2" height="1" fill="#C56F52"/>
+<rect x="11" y="22" width="2" height="1" fill="#C56F52"/>
+<rect x="15" y="22" width="2" height="1" fill="#C56F52"/>
+<rect x="19" y="22" width="2" height="1" fill="#C56F52"/>
+<rect x="23" y="22" width="2" height="1" fill="#C56F52"/>
+<rect x="7" y="23" width="2" height="1" fill="#C56F52"/>
+<rect x="11" y="23" width="2" height="1" fill="#C56F52"/>
+<rect x="15" y="23" width="2" height="1" fill="#C56F52"/>
+<rect x="19" y="23" width="2" height="1" fill="#C56F52"/>
+<rect x="23" y="23" width="2" height="1" fill="#C56F52"/>
+<rect x="7" y="24" width="2" height="1" fill="#C56F52"/>
+<rect x="11" y="24" width="2" height="1" fill="#C56F52"/>
+<rect x="15" y="24" width="2" height="1" fill="#C56F52"/>
+<rect x="19" y="24" width="2" height="1" fill="#C56F52"/>
+<rect x="23" y="24" width="2" height="1" fill="#C56F52"/>
+<rect x="7" y="25" width="2" height="1" fill="#C56F52"/>
+<rect x="11" y="25" width="2" height="1" fill="#C56F52"/>
+<rect x="15" y="25" width="2" height="1" fill="#C56F52"/>
+<rect x="19" y="25" width="2" height="1" fill="#C56F52"/>
+<rect x="23" y="25" width="2" height="1" fill="#C56F52"/>
+</svg>

package/dist/config.js

@@ -16,9 +16,9 @@ export function buildBaseOptions() {
     const model = envStr("CLAUDE_MODEL");
     if (model)
         opts.model = model;
-    const allowed = envList("CLAUDE_ALLOWED_TOOLS");
-    if (allowed)
-        opts.allowedTools = allowed;
+    const tools = envList("CLAUDE_ALLOWED_TOOLS");
+    if (tools)
+        opts.tools = tools;
     const disallowed = envList("CLAUDE_DISALLOWED_TOOLS");
     if (disallowed)
         opts.disallowedTools = disallowed;
@@ -62,16 +62,17 @@ export function buildBaseOptions() {
     }
     const settings = envStr("CLAUDE_SETTINGS");
     if (settings) {
-        if (settings.startsWith("{")) {
+        const trimmed = settings.trim();
+        if (trimmed.startsWith("{")) {
             try {
-                opts.settings = JSON.parse(settings);
+                opts.settings = JSON.parse(trimmed);
             }
-            catch {
-                opts.settings = settings;
+            catch (e) {
+                console.error(`claude-octopus: invalid CLAUDE_SETTINGS JSON: ${e instanceof Error ? e.message : e}`);
             }
         }
         else {
-            opts.settings = settings;
+            opts.settings = trimmed;
         }
     }
     const betas = envList("CLAUDE_BETAS");

package/dist/constants.js

@@ -23,8 +23,8 @@ export const OPTION_CATALOG = [
     {
         key: "allowedTools",
         envVar: "CLAUDE_ALLOWED_TOOLS",
-        label: "Allowed tools",
-        hint: "Only these tools are available (comma-separated)",
+        label: "Available tools",
+        hint: "Restrict agent to only these tools (comma-separated)",
         example: '"Read,Grep,Glob" for read-only; "Bash,Read,Write,Edit,Grep,Glob" for full access',
     },
     {

package/dist/index.js

@@ -10,15 +10,13 @@
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { fileURLToPath } from "node:url";
-import { dirname, resolve } from "node:path";
+import { createRequire } from "node:module";
 import { envStr, envBool, sanitizeToolName } from "./lib.js";
 import { buildBaseOptions } from "./config.js";
 import { registerQueryTools } from "./tools/query.js";
 import { registerFactoryTool } from "./tools/factory.js";
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-const SERVER_ENTRY = resolve(__dirname, "index.js");
+const require = createRequire(import.meta.url);
+const { version: PKG_VERSION } = require("../package.json");
 // ── Configuration ──────────────────────────────────────────────────
 const BASE_OPTIONS = buildBaseOptions();
 const TOOL_NAME = sanitizeToolName(envStr("CLAUDE_TOOL_NAME") || "claude_code");
@@ -33,12 +31,12 @@ const DEFAULT_DESCRIPTION = [
 ].join(" ");
 const TOOL_DESCRIPTION = envStr("CLAUDE_DESCRIPTION") || DEFAULT_DESCRIPTION;
 // ── Server ─────────────────────────────────────────────────────────
-const server = new McpServer({ name: SERVER_NAME, version: "1.0.0" });
+const server = new McpServer({ name: SERVER_NAME, version: PKG_VERSION });
 if (!FACTORY_ONLY) {
     registerQueryTools(server, BASE_OPTIONS, TOOL_NAME, TOOL_DESCRIPTION);
 }
 if (FACTORY_ONLY) {
-    registerFactoryTool(server, SERVER_ENTRY);
+    registerFactoryTool(server);
 }
 // ── Start ──────────────────────────────────────────────────────────
 async function main() {

package/dist/lib.d.ts

@@ -9,10 +9,16 @@ export declare function envJson<T>(key: string, env?: Record<string, string | un
 export declare const MAX_TOOL_NAME_LEN: number;
 export declare function sanitizeToolName(raw: string): string;
 export declare function isDescendantPath(requested: string, baseCwd: string): boolean;
-export declare function mergeAllowedTools(serverList: string[] | undefined, callList: string[]): string[];
+export declare function mergeTools(serverList: string[] | undefined, callList: string[]): string[];
 export declare function mergeDisallowedTools(serverList: string[] | undefined, callList: string[]): string[];
 export declare const VALID_PERM_MODES: Set<string>;
 export declare function validatePermissionMode(mode: string): string;
+/**
+ * Narrow permission mode: returns the stricter of base and override.
+ * Callers can tighten permissions but never loosen them.
+ * Returns base unchanged if override is invalid or less strict.
+ */
+export declare function narrowPermissionMode(base: string, override: string): string;
 export declare function deriveServerName(description: string): string;
 export declare function deriveToolName(name: string): string;
 export declare function serializeArrayEnv(val: unknown[]): string;

package/dist/lib.js

@@ -69,7 +69,7 @@ export function isDescendantPath(requested, baseCwd) {
     return normalReq.startsWith(baseWithSep);
 }
 // ── Tool restriction merging ───────────────────────────────────────
-export function mergeAllowedTools(serverList, callList) {
+export function mergeTools(serverList, callList) {
     if (serverList?.length) {
         const serverSet = new Set(serverList);
         return callList.filter((t) => serverSet.has(t));
@@ -87,11 +87,30 @@ export const VALID_PERM_MODES = new Set([
     "bypassPermissions",
     "plan",
     "dontAsk",
-    "auto",
 ]);
 export function validatePermissionMode(mode) {
     return VALID_PERM_MODES.has(mode) ? mode : "default";
 }
+// Strictness order: most permissive → most restrictive
+const PERM_STRICTNESS = {
+    bypassPermissions: 0,
+    acceptEdits: 1,
+    default: 2,
+    plan: 3,
+    dontAsk: 4,
+};
+/**
+ * Narrow permission mode: returns the stricter of base and override.
+ * Callers can tighten permissions but never loosen them.
+ * Returns base unchanged if override is invalid or less strict.
+ */
+export function narrowPermissionMode(base, override) {
+    if (!VALID_PERM_MODES.has(override))
+        return base;
+    const baseLevel = PERM_STRICTNESS[base] ?? 2;
+    const overrideLevel = PERM_STRICTNESS[override] ?? 2;
+    return overrideLevel >= baseLevel ? override : base;
+}
 // ── Factory name derivation ────────────────────────────────────────
 export function deriveServerName(description) {
     const slug = description

package/dist/tools/factory.d.ts

@@ -1,2 +1,2 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-export declare function registerFactoryTool(server: McpServer, serverEntry: string): void;
+export declare function registerFactoryTool(server: McpServer): void;

package/dist/tools/factory.js

@@ -23,14 +23,14 @@ function buildEnvFromParams(params) {
     }
     return env;
 }
-export function registerFactoryTool(server, serverEntry) {
+export function registerFactoryTool(server) {
     server.registerTool("create_claude_code_mcp", {
         description: [
-            "Create a new specialized Claude Code agent as an MCP server.",
-            "WHEN TO USE: user says 'create agent', 'new agent', 'set up agent',",
-            "'configure agent', 'add a reviewer', 'add a test writer',",
-            "'make me a code reviewer', 'I need a specialized agent', etc.",
-            "DO NOT USE when user just wants to run a task — use the main tool for that.",
+            "Generate a .mcp.json config entry for a new Claude Octopus MCP server instance.",
+            "WHEN TO USE: user says 'octopus agent', 'octopus mcp',",
+            "'new octopus', 'add octopus', 'create octopus',",
+            "'octopus instance', 'octopus config', 'octopus server',",
+            "or any phrase combining 'octopus' with agent/mcp/new/add/create/config/server/setup.",
             "This is a wizard: only a description is required.",
             "Returns a ready-to-use .mcp.json config and lists all customization options.",
             "Call again with more parameters to refine.",
@@ -73,11 +73,17 @@ export function registerFactoryTool(server, serverEntry) {
         Object.assign(env, optionEnv);
         const configured = Object.keys(optionEnv);
         const notConfigured = OPTION_CATALOG.filter((o) => !configured.includes(o.envVar));
+        const SENSITIVE_KEYS = new Set(["ANTHROPIC_API_KEY", "CLAUDE_CODE_OAUTH_TOKEN"]);
+        // Redact secrets in rendered output, keep real values in config
+        const displayEnv = {};
+        for (const [k, v] of Object.entries(env)) {
+            displayEnv[k] = SENSITIVE_KEYS.has(k) ? "<REDACTED>" : v;
+        }
         const mcpEntry = {
             [name]: {
-                command: "node",
-                args: [serverEntry],
-                env,
+                command: "npx",
+                args: ["claude-octopus"],
+                env: displayEnv,
             },
         };
         const sections = [];
@@ -89,7 +95,8 @@ export function registerFactoryTool(server, serverEntry) {
         for (const key of configured) {
             const opt = OPTION_CATALOG.find((o) => o.envVar === key);
             if (opt) {
-                sections.push(`| ${opt.label} | \`${env[key]}\` |`);
+                const val = SENSITIVE_KEYS.has(key) ? "<REDACTED>" : env[key];
+                sections.push(`| ${opt.label} | \`${val}\` |`);
             }
         }
         if (configured.length === 0) {

package/dist/tools/query.js

@@ -1,17 +1,53 @@
 import { z } from "zod/v4";
 import { resolve } from "node:path";
 import { query, } from "@anthropic-ai/claude-agent-sdk";
-import { isDescendantPath, mergeAllowedTools, mergeDisallowedTools, buildResultPayload, formatErrorMessage, } from "../lib.js";
+import { mergeTools, mergeDisallowedTools, narrowPermissionMode, buildResultPayload, formatErrorMessage, } from "../lib.js";
 async function runQuery(prompt, overrides, baseOptions) {
     const options = { ...baseOptions };
+    // Handle cwd override — accept any path, preserve agent's base access
     if (overrides.cwd) {
         const baseCwd = baseOptions.cwd || process.cwd();
-        if (isDescendantPath(overrides.cwd, baseCwd)) {
-            options.cwd = resolve(baseCwd, overrides.cwd);
+        const resolvedCwd = resolve(baseCwd, overrides.cwd);
+        if (resolvedCwd !== baseCwd) {
+            options.cwd = resolvedCwd;
+            // Agent's base dir becomes an additional dir so it keeps its knowledge
+            const dirs = new Set(options.additionalDirectories || []);
+            dirs.add(baseCwd);
+            options.additionalDirectories = [...dirs];
         }
     }
+    // Per-invocation additionalDirs — unions with server-level + auto-added dirs
+    if (overrides.additionalDirs?.length) {
+        const dirs = new Set(options.additionalDirectories || []);
+        for (const dir of overrides.additionalDirs) {
+            dirs.add(dir);
+        }
+        options.additionalDirectories = [...dirs];
+    }
+    // Per-invocation plugins — unions with server-level plugins
+    if (overrides.plugins?.length) {
+        const base = baseOptions.plugins || [];
+        const overridePaths = new Set(base.map((p) => p.path));
+        const merged = [...base];
+        for (const path of overrides.plugins) {
+            if (!overridePaths.has(path)) {
+                merged.push({ type: "local", path });
+                overridePaths.add(path);
+            }
+        }
+        options.plugins = merged;
+    }
     if (overrides.model)
         options.model = overrides.model;
+    if (overrides.effort)
+        options.effort = overrides.effort;
+    // Permission mode can only tighten, never loosen
+    if (overrides.permissionMode) {
+        const base = baseOptions.permissionMode || "default";
+        const narrowed = narrowPermissionMode(base, overrides.permissionMode);
+        options.permissionMode = narrowed;
+        options.allowDangerouslySkipPermissions = narrowed === "bypassPermissions";
+    }
     if (overrides.maxTurns !== undefined && overrides.maxTurns > 0) {
         options.maxTurns = overrides.maxTurns;
     }
@@ -19,8 +55,9 @@ async function runQuery(prompt, overrides, baseOptions) {
         options.maxBudgetUsd = overrides.maxBudgetUsd;
     if (overrides.resumeSessionId)
         options.resume = overrides.resumeSessionId;
-    if (overrides.allowedTools?.length) {
-        options.allowedTools = mergeAllowedTools(baseOptions.allowedTools, overrides.allowedTools);
+    if (overrides.tools?.length) {
+        const baseTools = Array.isArray(baseOptions.tools) ? baseOptions.tools : undefined;
+        options.tools = mergeTools(baseTools, overrides.tools);
     }
     if (overrides.disallowedTools?.length) {
         options.disallowedTools = mergeDisallowedTools(baseOptions.disallowedTools, overrides.disallowedTools);
@@ -87,16 +124,20 @@ export function registerQueryTools(server, baseOptions, toolName, toolDescriptio
             prompt: z.string().describe("Task or question for Claude Code"),
             cwd: z.string().optional().describe("Working directory (overrides CLAUDE_CWD)"),
             model: z.string().optional().describe('Model override (e.g. "sonnet", "opus", "haiku")'),
-            allowedTools: z.array(z.string()).optional().describe("Tool whitelist override"),
-            disallowedTools: z.array(z.string()).optional().describe("Tool blacklist override"),
+            tools: z.array(z.string()).optional().describe("Restrict available tools to this list (intersects with server-level restriction)"),
+            disallowedTools: z.array(z.string()).optional().describe("Additional tools to block (unions with server-level blacklist)"),
+            additionalDirs: z.array(z.string()).optional().describe("Extra directories the agent can access for this invocation"),
+            plugins: z.array(z.string()).optional().describe("Additional plugin paths to load for this invocation (unions with server-level plugins)"),
+            effort: z.enum(["low", "medium", "high", "max"]).optional().describe("Thinking effort override"),
+            permissionMode: z.enum(["default", "acceptEdits", "plan"]).optional().describe("Permission mode override (can only tighten, never loosen)"),
             maxTurns: z.number().int().positive().optional().describe("Max conversation turns"),
-            maxBudgetUsd: z.number().optional().describe("Max spend in USD"),
+            maxBudgetUsd: z.number().positive().optional().describe("Max spend in USD"),
             systemPrompt: z.string().optional().describe("Additional system prompt (appended to server default)"),
         }),
-    }, async ({ prompt, cwd, model, allowedTools, disallowedTools, maxTurns, maxBudgetUsd, systemPrompt }) => {
+    }, async ({ prompt, cwd, model, tools, disallowedTools, additionalDirs, plugins, effort, permissionMode, maxTurns, maxBudgetUsd, systemPrompt }) => {
         try {
             const result = await runQuery(prompt, {
-                cwd, model, allowedTools, disallowedTools, maxTurns, maxBudgetUsd, systemPrompt,
+                cwd, model, tools, disallowedTools, additionalDirs, plugins, effort, permissionMode, maxTurns, maxBudgetUsd, systemPrompt,
             }, baseOptions);
             return formatResult(result);
         }
@@ -117,7 +158,7 @@ export function registerQueryTools(server, baseOptions, toolName, toolDescriptio
                 cwd: z.string().optional().describe("Working directory override"),
                 model: z.string().optional().describe("Model override"),
                 maxTurns: z.number().int().positive().optional().describe("Max conversation turns"),
-                maxBudgetUsd: z.number().optional().describe("Max spend in USD"),
+                maxBudgetUsd: z.number().positive().optional().describe("Max spend in USD"),
             }),
         }, async ({ session_id, prompt, cwd, model, maxTurns, maxBudgetUsd }) => {
             try {

package/dist/types.d.ts

@@ -2,8 +2,12 @@ import type { Options } from "@anthropic-ai/claude-agent-sdk";
 export interface InvocationOverrides {
     cwd?: string;
     model?: string;
-    allowedTools?: string[];
+    tools?: string[];
     disallowedTools?: string[];
+    additionalDirs?: string[];
+    plugins?: string[];
+    effort?: string;
+    permissionMode?: string;
     maxTurns?: number;
     maxBudgetUsd?: number;
     systemPrompt?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-octopus",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "One brain, many arms — spawn multiple specialized Claude Code agents as MCP servers",
   "type": "module",
   "bin": {

package/src/config.ts

@@ -29,8 +29,8 @@ export function buildBaseOptions(): Options {
   const model = envStr("CLAUDE_MODEL");
   if (model) opts.model = model;
 
-  const allowed = envList("CLAUDE_ALLOWED_TOOLS");
-  if (allowed) opts.allowedTools = allowed;
+  const tools = envList("CLAUDE_ALLOWED_TOOLS");
+  if (tools) opts.tools = tools;
   const disallowed = envList("CLAUDE_DISALLOWED_TOOLS");
   if (disallowed) opts.disallowedTools = disallowed;
 
@@ -78,14 +78,15 @@ export function buildBaseOptions(): Options {
 
   const settings = envStr("CLAUDE_SETTINGS");
   if (settings) {
-    if (settings.startsWith("{")) {
+    const trimmed = settings.trim();
+    if (trimmed.startsWith("{")) {
       try {
-        opts.settings = JSON.parse(settings);
-      } catch {
-        opts.settings = settings;
+        opts.settings = JSON.parse(trimmed);
+      } catch (e) {
+        console.error(`claude-octopus: invalid CLAUDE_SETTINGS JSON: ${e instanceof Error ? e.message : e}`);
       }
     } else {
-      opts.settings = settings;
+      opts.settings = trimmed;
     }
   }
 

package/src/constants.ts

@@ -25,8 +25,8 @@ export const OPTION_CATALOG: OptionCatalogEntry[] = [
   {
     key: "allowedTools",
     envVar: "CLAUDE_ALLOWED_TOOLS",
-    label: "Allowed tools",
-    hint: "Only these tools are available (comma-separated)",
+    label: "Available tools",
+    hint: "Restrict agent to only these tools (comma-separated)",
     example: '"Read,Grep,Glob" for read-only; "Bash,Read,Write,Edit,Grep,Glob" for full access',
   },
   {

package/src/index.ts

@@ -12,16 +12,14 @@
 
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { fileURLToPath } from "node:url";
-import { dirname, resolve } from "node:path";
+import { createRequire } from "node:module";
 import { envStr, envBool, sanitizeToolName } from "./lib.js";
 import { buildBaseOptions } from "./config.js";
 import { registerQueryTools } from "./tools/query.js";
 import { registerFactoryTool } from "./tools/factory.js";
 
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-const SERVER_ENTRY = resolve(__dirname, "index.js");
+const require = createRequire(import.meta.url);
+const { version: PKG_VERSION } = require("../package.json");
 
 // ── Configuration ──────────────────────────────────────────────────
 
@@ -43,14 +41,14 @@ const TOOL_DESCRIPTION = envStr("CLAUDE_DESCRIPTION") || DEFAULT_DESCRIPTION;
 
 // ── Server ─────────────────────────────────────────────────────────
 
-const server = new McpServer({ name: SERVER_NAME, version: "1.0.0" });
+const server = new McpServer({ name: SERVER_NAME, version: PKG_VERSION });
 
 if (!FACTORY_ONLY) {
   registerQueryTools(server, BASE_OPTIONS, TOOL_NAME, TOOL_DESCRIPTION);
 }
 
 if (FACTORY_ONLY) {
-  registerFactoryTool(server, SERVER_ENTRY);
+  registerFactoryTool(server);
 }
 
 // ── Start ──────────────────────────────────────────────────────────

package/src/lib.test.ts

@@ -8,9 +8,10 @@ import {
   sanitizeToolName,
   MAX_TOOL_NAME_LEN,
   isDescendantPath,
-  mergeAllowedTools,
+  mergeTools,
   mergeDisallowedTools,
   validatePermissionMode,
+  narrowPermissionMode,
   VALID_PERM_MODES,
   deriveServerName,
   deriveToolName,
@@ -202,24 +203,24 @@ describe("isDescendantPath", () => {
   });
 });
 
-// ── mergeAllowedTools ──────────────────────────────────────────────
+// ── mergeTools ───────────────────────────────────────────────────
 
-describe("mergeAllowedTools", () => {
+describe("mergeTools", () => {
   it("intersects when server has a list", () => {
     expect(
-      mergeAllowedTools(["Read", "Grep", "Glob"], ["Read", "Write", "Glob"])
+      mergeTools(["Read", "Grep", "Glob"], ["Read", "Write", "Glob"])
     ).toEqual(["Read", "Glob"]);
   });
 
   it("passes through when server has no list", () => {
     expect(
-      mergeAllowedTools(undefined, ["Read", "Write"])
+      mergeTools(undefined, ["Read", "Write"])
     ).toEqual(["Read", "Write"]);
   });
 
   it("returns empty when no overlap", () => {
     expect(
-      mergeAllowedTools(["Read"], ["Write"])
+      mergeTools(["Read"], ["Write"])
     ).toEqual([]);
   });
 });
@@ -257,6 +258,52 @@ describe("validatePermissionMode", () => {
     expect(validatePermissionMode("allowEdits")).toBe("default");
     expect(validatePermissionMode("garbage")).toBe("default");
     expect(validatePermissionMode("")).toBe("default");
+    expect(validatePermissionMode("auto")).toBe("default");
+  });
+});
+
+// ── narrowPermissionMode ──────────────────────────────────────────
+
+describe("narrowPermissionMode", () => {
+  it("allows tightening from bypassPermissions to stricter modes", () => {
+    expect(narrowPermissionMode("bypassPermissions", "acceptEdits")).toBe("acceptEdits");
+    expect(narrowPermissionMode("bypassPermissions", "default")).toBe("default");
+    expect(narrowPermissionMode("bypassPermissions", "plan")).toBe("plan");
+    expect(narrowPermissionMode("bypassPermissions", "dontAsk")).toBe("dontAsk");
+  });
+
+  it("allows tightening from acceptEdits to stricter modes", () => {
+    expect(narrowPermissionMode("acceptEdits", "default")).toBe("default");
+    expect(narrowPermissionMode("acceptEdits", "plan")).toBe("plan");
+    expect(narrowPermissionMode("acceptEdits", "dontAsk")).toBe("dontAsk");
+  });
+
+  it("dontAsk is the strictest — rejects all loosening", () => {
+    expect(narrowPermissionMode("dontAsk", "bypassPermissions")).toBe("dontAsk");
+    expect(narrowPermissionMode("dontAsk", "acceptEdits")).toBe("dontAsk");
+    expect(narrowPermissionMode("dontAsk", "default")).toBe("dontAsk");
+    expect(narrowPermissionMode("dontAsk", "plan")).toBe("dontAsk");
+    expect(narrowPermissionMode("dontAsk", "dontAsk")).toBe("dontAsk");
+  });
+
+  it("rejects loosening — returns base unchanged", () => {
+    expect(narrowPermissionMode("default", "bypassPermissions")).toBe("default");
+    expect(narrowPermissionMode("default", "acceptEdits")).toBe("default");
+    expect(narrowPermissionMode("plan", "bypassPermissions")).toBe("plan");
+    expect(narrowPermissionMode("plan", "acceptEdits")).toBe("plan");
+    expect(narrowPermissionMode("plan", "default")).toBe("plan");
+  });
+
+  it("same mode returns same mode", () => {
+    expect(narrowPermissionMode("default", "default")).toBe("default");
+    expect(narrowPermissionMode("plan", "plan")).toBe("plan");
+    expect(narrowPermissionMode("bypassPermissions", "bypassPermissions")).toBe("bypassPermissions");
+  });
+
+  it("invalid override returns base unchanged", () => {
+    expect(narrowPermissionMode("default", "garbage")).toBe("default");
+    expect(narrowPermissionMode("bypassPermissions", "")).toBe("bypassPermissions");
+    expect(narrowPermissionMode("default", "auto")).toBe("default");
   });
 });
 

package/src/lib.ts

@@ -94,7 +94,7 @@ export function isDescendantPath(
 
 // ── Tool restriction merging ───────────────────────────────────────
 
-export function mergeAllowedTools(
+export function mergeTools(
   serverList: string[] | undefined,
   callList: string[]
 ): string[] {
@@ -121,13 +121,33 @@ export const VALID_PERM_MODES = new Set([
   "bypassPermissions",
   "plan",
   "dontAsk",
-  "auto",
 ]);
 
 export function validatePermissionMode(mode: string): string {
   return VALID_PERM_MODES.has(mode) ? mode : "default";
 }
 
+// Strictness order: most permissive → most restrictive
+const PERM_STRICTNESS: Record<string, number> = {
+  bypassPermissions: 0,
+  acceptEdits: 1,
+  default: 2,
+  plan: 3,
+  dontAsk: 4,
+};
+
+/**
+ * Narrow permission mode: returns the stricter of base and override.
+ * Callers can tighten permissions but never loosen them.
+ * Returns base unchanged if override is invalid or less strict.
+ */
+export function narrowPermissionMode(base: string, override: string): string {
+  if (!VALID_PERM_MODES.has(override)) return base;
+  const baseLevel = PERM_STRICTNESS[base] ?? 2;
+  const overrideLevel = PERM_STRICTNESS[override] ?? 2;
+  return overrideLevel >= baseLevel ? override : base;
+}
+
 // ── Factory name derivation ────────────────────────────────────────
 
 export function deriveServerName(description: string): string {

package/src/tools/factory.ts

@@ -33,15 +33,14 @@ function buildEnvFromParams(
 
 export function registerFactoryTool(
   server: McpServer,
-  serverEntry: string
 ) {
   server.registerTool("create_claude_code_mcp", {
     description: [
-      "Create a new specialized Claude Code agent as an MCP server.",
-      "WHEN TO USE: user says 'create agent', 'new agent', 'set up agent',",
-      "'configure agent', 'add a reviewer', 'add a test writer',",
-      "'make me a code reviewer', 'I need a specialized agent', etc.",
-      "DO NOT USE when user just wants to run a task — use the main tool for that.",
+      "Generate a .mcp.json config entry for a new Claude Octopus MCP server instance.",
+      "WHEN TO USE: user says 'octopus agent', 'octopus mcp',",
+      "'new octopus', 'add octopus', 'create octopus',",
+      "'octopus instance', 'octopus config', 'octopus server',",
+      "or any phrase combining 'octopus' with agent/mcp/new/add/create/config/server/setup.",
       "This is a wizard: only a description is required.",
       "Returns a ready-to-use .mcp.json config and lists all customization options.",
       "Call again with more parameters to refine.",
@@ -93,11 +92,19 @@ export function registerFactoryTool(
       (o) => !configured.includes(o.envVar)
     );
 
+    const SENSITIVE_KEYS = new Set(["ANTHROPIC_API_KEY", "CLAUDE_CODE_OAUTH_TOKEN"]);
+
+    // Redact secrets in rendered output, keep real values in config
+    const displayEnv: Record<string, string> = {};
+    for (const [k, v] of Object.entries(env)) {
+      displayEnv[k] = SENSITIVE_KEYS.has(k) ? "<REDACTED>" : v;
+    }
+
     const mcpEntry = {
       [name]: {
-        command: "node",
-        args: [serverEntry],
-        env,
+        command: "npx",
+        args: ["claude-octopus"],
+        env: displayEnv,
       },
     };
 
@@ -120,7 +127,8 @@ export function registerFactoryTool(
     for (const key of configured) {
       const opt = OPTION_CATALOG.find((o) => o.envVar === key);
       if (opt) {
-        sections.push(`| ${opt.label} | \`${env[key]}\` |`);
+        const val = SENSITIVE_KEYS.has(key) ? "<REDACTED>" : env[key];
+        sections.push(`| ${opt.label} | \`${val}\` |`);
       }
     }
     if (configured.length === 0) {

package/src/tools/query.ts

@@ -7,9 +7,9 @@ import {
 } from "@anthropic-ai/claude-agent-sdk";
 import type { Options, InvocationOverrides } from "../types.js";
 import {
-  isDescendantPath,
-  mergeAllowedTools,
+  mergeTools,
   mergeDisallowedTools,
+  narrowPermissionMode,
   buildResultPayload,
   formatErrorMessage,
 } from "../lib.js";
@@ -21,13 +21,53 @@ async function runQuery(
 ): Promise<SDKResultMessage> {
   const options: Options = { ...baseOptions };
 
+  // Handle cwd override — accept any path, preserve agent's base access
   if (overrides.cwd) {
     const baseCwd = baseOptions.cwd || process.cwd();
-    if (isDescendantPath(overrides.cwd, baseCwd)) {
-      options.cwd = resolve(baseCwd, overrides.cwd);
+    const resolvedCwd = resolve(baseCwd, overrides.cwd);
+    if (resolvedCwd !== baseCwd) {
+      options.cwd = resolvedCwd;
+      // Agent's base dir becomes an additional dir so it keeps its knowledge
+      const dirs = new Set(options.additionalDirectories || []);
+      dirs.add(baseCwd);
+      options.additionalDirectories = [...dirs];
     }
   }
+
+  // Per-invocation additionalDirs — unions with server-level + auto-added dirs
+  if (overrides.additionalDirs?.length) {
+    const dirs = new Set(options.additionalDirectories || []);
+    for (const dir of overrides.additionalDirs) {
+      dirs.add(dir);
+    }
+    options.additionalDirectories = [...dirs];
+  }
+
+  // Per-invocation plugins — unions with server-level plugins
+  if (overrides.plugins?.length) {
+    const base = baseOptions.plugins || [];
+    const overridePaths = new Set(base.map((p) => p.path));
+    const merged = [...base];
+    for (const path of overrides.plugins) {
+      if (!overridePaths.has(path)) {
+        merged.push({ type: "local" as const, path });
+        overridePaths.add(path);
+      }
+    }
+    options.plugins = merged;
+  }
+
   if (overrides.model) options.model = overrides.model;
+  if (overrides.effort) options.effort = overrides.effort as Options["effort"];
+
+  // Permission mode can only tighten, never loosen
+  if (overrides.permissionMode) {
+    const base = (baseOptions.permissionMode as string) || "default";
+    const narrowed = narrowPermissionMode(base, overrides.permissionMode);
+    options.permissionMode = narrowed as Options["permissionMode"];
+    options.allowDangerouslySkipPermissions = narrowed === "bypassPermissions";
+  }
+
   if (overrides.maxTurns !== undefined && overrides.maxTurns > 0) {
     options.maxTurns = overrides.maxTurns;
   }
@@ -35,11 +75,9 @@ async function runQuery(
     options.maxBudgetUsd = overrides.maxBudgetUsd;
   if (overrides.resumeSessionId) options.resume = overrides.resumeSessionId;
 
-  if (overrides.allowedTools?.length) {
-    options.allowedTools = mergeAllowedTools(
-      baseOptions.allowedTools,
-      overrides.allowedTools
-    );
+  if (overrides.tools?.length) {
+    const baseTools = Array.isArray(baseOptions.tools) ? baseOptions.tools : undefined;
+    options.tools = mergeTools(baseTools, overrides.tools);
   }
   if (overrides.disallowedTools?.length) {
     options.disallowedTools = mergeDisallowedTools(
@@ -125,16 +163,20 @@ export function registerQueryTools(
       prompt: z.string().describe("Task or question for Claude Code"),
       cwd: z.string().optional().describe("Working directory (overrides CLAUDE_CWD)"),
       model: z.string().optional().describe('Model override (e.g. "sonnet", "opus", "haiku")'),
-      allowedTools: z.array(z.string()).optional().describe("Tool whitelist override"),
-      disallowedTools: z.array(z.string()).optional().describe("Tool blacklist override"),
+      tools: z.array(z.string()).optional().describe("Restrict available tools to this list (intersects with server-level restriction)"),
+      disallowedTools: z.array(z.string()).optional().describe("Additional tools to block (unions with server-level blacklist)"),
+      additionalDirs: z.array(z.string()).optional().describe("Extra directories the agent can access for this invocation"),
+      plugins: z.array(z.string()).optional().describe("Additional plugin paths to load for this invocation (unions with server-level plugins)"),
+      effort: z.enum(["low", "medium", "high", "max"]).optional().describe("Thinking effort override"),
+      permissionMode: z.enum(["default", "acceptEdits", "plan"]).optional().describe("Permission mode override (can only tighten, never loosen)"),
       maxTurns: z.number().int().positive().optional().describe("Max conversation turns"),
-      maxBudgetUsd: z.number().optional().describe("Max spend in USD"),
+      maxBudgetUsd: z.number().positive().optional().describe("Max spend in USD"),
       systemPrompt: z.string().optional().describe("Additional system prompt (appended to server default)"),
     }),
-  }, async ({ prompt, cwd, model, allowedTools, disallowedTools, maxTurns, maxBudgetUsd, systemPrompt }) => {
+  }, async ({ prompt, cwd, model, tools, disallowedTools, additionalDirs, plugins, effort, permissionMode, maxTurns, maxBudgetUsd, systemPrompt }) => {
     try {
       const result = await runQuery(prompt, {
-        cwd, model, allowedTools, disallowedTools, maxTurns, maxBudgetUsd, systemPrompt,
+        cwd, model, tools, disallowedTools, additionalDirs, plugins, effort, permissionMode, maxTurns, maxBudgetUsd, systemPrompt,
       }, baseOptions);
       return formatResult(result);
     } catch (error) {
@@ -155,7 +197,7 @@ export function registerQueryTools(
         cwd: z.string().optional().describe("Working directory override"),
         model: z.string().optional().describe("Model override"),
         maxTurns: z.number().int().positive().optional().describe("Max conversation turns"),
-        maxBudgetUsd: z.number().optional().describe("Max spend in USD"),
+        maxBudgetUsd: z.number().positive().optional().describe("Max spend in USD"),
       }),
     }, async ({ session_id, prompt, cwd, model, maxTurns, maxBudgetUsd }) => {
       try {

package/src/types.ts

@@ -3,8 +3,12 @@ import type { Options } from "@anthropic-ai/claude-agent-sdk";
 export interface InvocationOverrides {
   cwd?: string;
   model?: string;
-  allowedTools?: string[];
+  tools?: string[];
   disallowedTools?: string[];
+  additionalDirs?: string[];
+  plugins?: string[];
+  effort?: string;
+  permissionMode?: string;
   maxTurns?: number;
   maxBudgetUsd?: number;
   systemPrompt?: string;