codex-octopus 1.0.0

package/dist/lib.js

@@ -0,0 +1,148 @@
+/**
+ * Pure, testable logic extracted from index.ts.
+ */
+import { normalize, resolve, sep } from "node:path";
+// ── Env helpers ────────────────────────────────────────────────────
+export function envStr(key, env = process.env) {
+    return env[key] || undefined;
+}
+export function envList(key, env = process.env) {
+    const val = env[key];
+    if (!val)
+        return undefined;
+    if (val.startsWith("[")) {
+        try {
+            const parsed = JSON.parse(val);
+            if (Array.isArray(parsed))
+                return parsed.map(String).filter(Boolean);
+        }
+        catch {
+            // fall through to comma-split
+        }
+    }
+    return val
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+}
+export function envNum(key, env = process.env) {
+    const val = env[key];
+    if (!val)
+        return undefined;
+    const n = Number(val);
+    return Number.isNaN(n) ? undefined : n;
+}
+export function envBool(key, fallback, env = process.env) {
+    const val = env[key];
+    if (val === undefined)
+        return fallback;
+    return val === "true" || val === "1";
+}
+// ── Tool name sanitization ─────────────────────────────────────────
+export const MAX_TOOL_NAME_LEN = 64 - "_reply".length;
+export function sanitizeToolName(raw) {
+    const sanitized = raw
+        .replace(/[^a-zA-Z0-9_]/g, "_")
+        .slice(0, MAX_TOOL_NAME_LEN);
+    return sanitized || "codex";
+}
+// ── cwd security check ────────────────────────────────────────────
+export function isDescendantPath(requested, baseCwd) {
+    const normalBase = normalize(baseCwd);
+    const normalReq = normalize(resolve(normalBase, requested));
+    if (normalReq === normalBase)
+        return true;
+    const baseWithSep = normalBase.endsWith(sep)
+        ? normalBase
+        : normalBase + sep;
+    return normalReq.startsWith(baseWithSep);
+}
+// ── Sandbox mode validation ───────────────────────────────────────
+export const VALID_SANDBOX_MODES = new Set([
+    "read-only",
+    "workspace-write",
+    "danger-full-access",
+]);
+export function validateSandboxMode(mode) {
+    return VALID_SANDBOX_MODES.has(mode) ? mode : "read-only";
+}
+// Strictness order: most permissive → most restrictive
+const SANDBOX_STRICTNESS = {
+    "danger-full-access": 0,
+    "workspace-write": 1,
+    "read-only": 2,
+};
+/**
+ * Narrow sandbox mode: returns the stricter of base and override.
+ * Callers can tighten but never loosen.
+ */
+export function narrowSandboxMode(base, override) {
+    if (!VALID_SANDBOX_MODES.has(override))
+        return base;
+    const baseLevel = SANDBOX_STRICTNESS[base] ?? 2;
+    const overrideLevel = SANDBOX_STRICTNESS[override] ?? 2;
+    return overrideLevel >= baseLevel ? override : base;
+}
+// ── Approval policy validation ────────────────────────────────────
+export const VALID_APPROVAL_POLICIES = new Set([
+    "never",
+    "on-request",
+    "on-failure",
+    "untrusted",
+]);
+export function validateApprovalPolicy(policy) {
+    return VALID_APPROVAL_POLICIES.has(policy) ? policy : "on-failure";
+}
+const APPROVAL_STRICTNESS = {
+    never: 0,
+    "on-failure": 1,
+    "on-request": 2,
+    untrusted: 3,
+};
+/**
+ * Narrow approval policy: returns the stricter of base and override.
+ * Callers can tighten but never loosen.
+ */
+export function narrowApprovalPolicy(base, override) {
+    if (!VALID_APPROVAL_POLICIES.has(override))
+        return base;
+    const baseLevel = APPROVAL_STRICTNESS[base] ?? 1;
+    const overrideLevel = APPROVAL_STRICTNESS[override] ?? 1;
+    return overrideLevel >= baseLevel ? override : base;
+}
+// ── Effort validation ─────────────────────────────────────────────
+export const VALID_EFFORTS = new Set([
+    "minimal",
+    "low",
+    "medium",
+    "high",
+    "xhigh",
+]);
+export function validateEffort(effort) {
+    return VALID_EFFORTS.has(effort) ? effort : "medium";
+}
+// ── Factory name derivation ────────────────────────────────────────
+export function deriveServerName(description) {
+    const slug = description
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-|-$/g, "")
+        .slice(0, 30);
+    return slug || `agent-${Date.now()}`;
+}
+export function deriveToolName(name) {
+    const slug = name
+        .replace(/[^a-zA-Z0-9]+/g, "_")
+        .replace(/^_|_$/g, "")
+        .slice(0, MAX_TOOL_NAME_LEN);
+    return slug || "agent";
+}
+// ── Factory env serialization ──────────────────────────────────────
+export function serializeArrayEnv(val) {
+    const hasComma = val.some((v) => String(v).includes(","));
+    return hasComma ? JSON.stringify(val) : val.join(",");
+}
+// ── Formatters ─────────────────────────────────────────────────────
+export function formatErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/tools/factory.d.ts

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

package/dist/tools/factory.js

@@ -0,0 +1,110 @@
+import { z } from "zod/v4";
+import { OPTION_CATALOG } from "../constants.js";
+import { sanitizeToolName, deriveServerName, deriveToolName, serializeArrayEnv, } from "../lib.js";
+function buildEnvFromParams(params) {
+    const env = {};
+    for (const opt of OPTION_CATALOG) {
+        const val = params[opt.key];
+        if (val === undefined || val === null)
+            continue;
+        if (Array.isArray(val)) {
+            if (val.length > 0)
+                env[opt.envVar] = serializeArrayEnv(val);
+        }
+        else if (typeof val === "object") {
+            env[opt.envVar] = JSON.stringify(val);
+        }
+        else if (typeof val === "boolean") {
+            env[opt.envVar] = String(val);
+        }
+        else if (val !== "") {
+            env[opt.envVar] = String(val);
+        }
+    }
+    return env;
+}
+export function registerFactoryTool(server) {
+    server.registerTool("create_codex_mcp", {
+        description: [
+            "Generate a .mcp.json config entry for a new Codex Octopus MCP server instance.",
+            "WHEN TO USE: user says 'codex octopus agent', 'codex octopus mcp',",
+            "'new codex octopus', 'add codex octopus', 'create codex octopus',",
+            "'codex octopus instance', 'codex octopus config', 'codex octopus server',",
+            "or any phrase combining 'codex 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.",
+        ].join(" "),
+        inputSchema: z.object({
+            description: z.string().describe("What this agent should do, in plain language. Example: 'a code reviewer with read-only sandbox'"),
+            name: z.string().optional().describe("Server name / alias (derived from description if omitted)"),
+            toolName: z.string().optional().describe("Custom tool name prefix"),
+            model: z.string().optional(),
+            instructions: z.string().optional(),
+            appendInstructions: z.string().optional(),
+            sandboxMode: z.enum(["read-only", "workspace-write", "danger-full-access"]).optional(),
+            approvalPolicy: z.enum(["never", "on-request", "on-failure", "untrusted"]).optional(),
+            cwd: z.string().optional(),
+            additionalDirs: z.array(z.string()).optional(),
+            effort: z.enum(["minimal", "low", "medium", "high", "xhigh"]).optional(),
+            networkAccess: z.boolean().optional(),
+            webSearchMode: z.enum(["disabled", "cached", "live"]).optional(),
+            persistSession: z.boolean().optional(),
+            apiKey: z.string().optional().describe("OpenAI API key for this agent (leave unset to inherit)"),
+        }),
+    }, async (params) => {
+        const { description, name: nameParam, toolName: toolNameParam } = params;
+        const name = nameParam || deriveServerName(description);
+        const derivedToolName = toolNameParam
+            ? sanitizeToolName(toolNameParam)
+            : deriveToolName(name);
+        const env = {
+            CODEX_TOOL_NAME: derivedToolName,
+            CODEX_SERVER_NAME: name,
+            CODEX_DESCRIPTION: description,
+        };
+        const optionEnv = buildEnvFromParams(params);
+        Object.assign(env, optionEnv);
+        const configured = Object.keys(optionEnv);
+        const notConfigured = OPTION_CATALOG.filter((o) => !configured.includes(o.envVar));
+        const SENSITIVE_KEYS = new Set(["CODEX_API_KEY"]);
+        const displayEnv = {};
+        for (const [k, v] of Object.entries(env)) {
+            displayEnv[k] = SENSITIVE_KEYS.has(k) ? "<REDACTED>" : v;
+        }
+        const mcpEntry = {
+            [name]: {
+                command: "npx",
+                args: ["codex-octopus"],
+                env: displayEnv,
+            },
+        };
+        const sections = [];
+        sections.push("## Generated config", "", "Add to `mcpServers` in your `.mcp.json`:", "", "```json", JSON.stringify(mcpEntry, null, 2), "```");
+        sections.push("", "## What's configured");
+        sections.push("", `| Setting | Value |`, `|---|---|`);
+        sections.push(`| Name | \`${name}\` |`);
+        sections.push(`| Tool names | \`${derivedToolName}\`, \`${derivedToolName}_reply\` |`);
+        for (const key of configured) {
+            const opt = OPTION_CATALOG.find((o) => o.envVar === key);
+            if (opt) {
+                const val = SENSITIVE_KEYS.has(key) ? "<REDACTED>" : env[key];
+                sections.push(`| ${opt.label} | \`${val}\` |`);
+            }
+        }
+        if (configured.length === 0) {
+            sections.push(`| _(all defaults)_ | — |`);
+        }
+        if (notConfigured.length > 0) {
+            sections.push("", "## Available customizations", "", "These options are not yet set. Ask the user if they'd like to configure any:", "");
+            for (const opt of notConfigured) {
+                sections.push(`- **${opt.label}** — ${opt.hint}`);
+                sections.push(`  Example: ${opt.example}`);
+            }
+            sections.push("", "_Call this tool again with additional parameters to refine the config._");
+        }
+        return {
+            content: [{ type: "text", text: sections.join("\n") }],
+        };
+    });
+}

package/dist/tools/query.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ThreadConfig } from "../types.js";
+export declare function registerQueryTools(server: McpServer, baseConfig: ThreadConfig, toolName: string, toolDescription: string, apiKey?: string): void;

package/dist/tools/query.js

@@ -0,0 +1,167 @@
+import { z } from "zod/v4";
+import { resolve } from "node:path";
+import { Codex } from "@openai/codex-sdk";
+import { narrowSandboxMode, narrowApprovalPolicy, formatErrorMessage, } from "../lib.js";
+async function runQuery(prompt, overrides, baseConfig, apiKey) {
+    const codex = new Codex({
+        ...(apiKey ? { apiKey } : {}),
+    });
+    const threadOptions = {};
+    // Model
+    const model = overrides.model || baseConfig.model;
+    if (model)
+        threadOptions.model = model;
+    // Working directory — accept any path, preserve agent's base access
+    let cwd = baseConfig.cwd || process.cwd();
+    if (overrides.cwd) {
+        const resolvedCwd = resolve(cwd, overrides.cwd);
+        if (resolvedCwd !== cwd) {
+            const dirs = new Set(baseConfig.additionalDirectories || []);
+            dirs.add(cwd);
+            threadOptions.additionalDirectories = [...dirs];
+            cwd = resolvedCwd;
+        }
+    }
+    threadOptions.workingDirectory = cwd;
+    // Per-invocation additionalDirs — unions with server-level + auto-added dirs
+    if (overrides.additionalDirs?.length) {
+        const existing = threadOptions.additionalDirectories || baseConfig.additionalDirectories || [];
+        const dirs = new Set(existing);
+        for (const dir of overrides.additionalDirs) {
+            dirs.add(dir);
+        }
+        threadOptions.additionalDirectories = [...dirs];
+    }
+    else if (baseConfig.additionalDirectories && !threadOptions.additionalDirectories) {
+        threadOptions.additionalDirectories = baseConfig.additionalDirectories;
+    }
+    // Sandbox mode — can only tighten
+    const baseSandbox = baseConfig.sandboxMode || "read-only";
+    if (overrides.sandboxMode) {
+        threadOptions.sandboxMode = narrowSandboxMode(baseSandbox, overrides.sandboxMode);
+    }
+    else {
+        threadOptions.sandboxMode = baseSandbox;
+    }
+    // Approval policy — can only tighten
+    const baseApproval = baseConfig.approvalPolicy || "on-failure";
+    if (overrides.approvalPolicy) {
+        threadOptions.approvalPolicy = narrowApprovalPolicy(baseApproval, overrides.approvalPolicy);
+    }
+    else {
+        threadOptions.approvalPolicy = baseApproval;
+    }
+    // Effort
+    const effort = overrides.effort || baseConfig.effort;
+    if (effort)
+        threadOptions.modelReasoningEffort = effort;
+    // Network access
+    if (overrides.networkAccess !== undefined) {
+        threadOptions.networkAccessEnabled = overrides.networkAccess;
+    }
+    else if (baseConfig.networkAccess !== undefined) {
+        threadOptions.networkAccessEnabled = baseConfig.networkAccess;
+    }
+    // Web search
+    const webSearch = overrides.webSearchMode || baseConfig.webSearchMode;
+    if (webSearch)
+        threadOptions.webSearchMode = webSearch;
+    // Start or resume thread
+    const thread = overrides.resumeThreadId
+        ? codex.resumeThread(overrides.resumeThreadId, threadOptions)
+        : codex.startThread(threadOptions);
+    // Build prompt with instructions
+    let fullPrompt = prompt;
+    if (!overrides.resumeThreadId) {
+        const instructions = overrides.instructions || baseConfig.instructions;
+        const appendInstructions = baseConfig.appendInstructions;
+        if (instructions) {
+            fullPrompt = `${instructions}\n\n${prompt}`;
+        }
+        else if (appendInstructions) {
+            fullPrompt = `${appendInstructions}\n\n${prompt}`;
+        }
+    }
+    const turn = await thread.run(fullPrompt);
+    return {
+        threadId: thread.id || "",
+        response: turn.finalResponse || "",
+        usage: turn.usage || { input_tokens: 0, cached_input_tokens: 0, output_tokens: 0 },
+        isError: false,
+    };
+}
+function formatResult(result) {
+    const payload = {
+        thread_id: result.threadId,
+        result: result.response,
+        usage: result.usage,
+        is_error: result.isError,
+    };
+    return {
+        content: [
+            { type: "text", text: JSON.stringify(payload, null, 2) },
+        ],
+        isError: result.isError,
+    };
+}
+function formatError(error) {
+    return {
+        content: [
+            { type: "text", text: `Error: ${formatErrorMessage(error)}` },
+        ],
+        isError: true,
+    };
+}
+export function registerQueryTools(server, baseConfig, toolName, toolDescription, apiKey) {
+    const replyToolName = `${toolName}_reply`;
+    server.registerTool(toolName, {
+        description: toolDescription,
+        inputSchema: z.object({
+            prompt: z.string().describe("Task or question for Codex"),
+            cwd: z.string().optional().describe("Working directory (overrides CODEX_CWD)"),
+            model: z.string().optional().describe('Model override (e.g. "gpt-5-codex", "o3", "codex-1")'),
+            additionalDirs: z.array(z.string()).optional().describe("Extra directories the agent can access for this invocation"),
+            effort: z.enum(["minimal", "low", "medium", "high", "xhigh"]).optional().describe("Reasoning effort override"),
+            sandboxMode: z.enum(["read-only", "workspace-write"]).optional().describe("Sandbox mode override (can only tighten, never loosen)"),
+            approvalPolicy: z.enum(["on-failure", "on-request", "untrusted"]).optional().describe("Approval policy override (can only tighten, never loosen)"),
+            networkAccess: z.boolean().optional().describe("Enable network access from sandbox"),
+            webSearchMode: z.enum(["disabled", "cached", "live"]).optional().describe("Web search mode"),
+            instructions: z.string().optional().describe("Additional instructions (prepended to prompt)"),
+        }),
+    }, async ({ prompt, cwd, model, additionalDirs, effort, sandboxMode, approvalPolicy, networkAccess, webSearchMode, instructions }) => {
+        try {
+            const result = await runQuery(prompt, {
+                cwd, model, additionalDirs, effort, sandboxMode, approvalPolicy, networkAccess, webSearchMode, instructions,
+            }, baseConfig, apiKey);
+            return formatResult(result);
+        }
+        catch (error) {
+            return formatError(error);
+        }
+    });
+    if (baseConfig.persistSession !== false) {
+        server.registerTool(replyToolName, {
+            description: [
+                `Continue a previous ${toolName} conversation by thread ID.`,
+                "Use this for follow-up questions, iterative refinement,",
+                "or multi-step workflows that build on prior context.",
+            ].join(" "),
+            inputSchema: z.object({
+                thread_id: z.string().describe(`Thread ID from a prior ${toolName} response`),
+                prompt: z.string().describe("Follow-up instruction or question"),
+                cwd: z.string().optional().describe("Working directory override"),
+                model: z.string().optional().describe("Model override"),
+            }),
+        }, async ({ thread_id, prompt, cwd, model }) => {
+            try {
+                const result = await runQuery(prompt, {
+                    cwd, model, resumeThreadId: thread_id,
+                }, baseConfig, apiKey);
+                return formatResult(result);
+            }
+            catch (error) {
+                return formatError(error);
+            }
+        });
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,32 @@
+export interface ThreadConfig {
+    cwd?: string;
+    model?: string;
+    sandboxMode?: "read-only" | "workspace-write" | "danger-full-access";
+    approvalPolicy?: "never" | "on-request" | "on-failure" | "untrusted";
+    effort?: "minimal" | "low" | "medium" | "high" | "xhigh";
+    additionalDirectories?: string[];
+    networkAccess?: boolean;
+    webSearchMode?: "disabled" | "cached" | "live";
+    persistSession?: boolean;
+    instructions?: string;
+    appendInstructions?: string;
+}
+export interface InvocationOverrides {
+    cwd?: string;
+    model?: string;
+    sandboxMode?: string;
+    approvalPolicy?: string;
+    effort?: string;
+    additionalDirs?: string[];
+    networkAccess?: boolean;
+    webSearchMode?: string;
+    instructions?: string;
+    resumeThreadId?: string;
+}
+export interface OptionCatalogEntry {
+    key: string;
+    envVar: string;
+    label: string;
+    hint: string;
+    example: string;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "codex-octopus",
+  "version": "1.0.0",
+  "description": "One brain, many arms — spawn multiple specialized Codex agents as MCP servers",
+  "type": "module",
+  "bin": {
+    "codex-octopus": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "dependencies": {
+    "@openai/codex-sdk": "^0.118.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@vitest/coverage-v8": "^4.1.2",
+    "typescript": "^5.8.0",
+    "vitest": "^4.1.2"
+  },
+  "license": "ISC",
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/config.ts

@@ -0,0 +1,67 @@
+import type { ThreadConfig } from "./types.js";
+import {
+  envStr,
+  envList,
+  envBool,
+  validateSandboxMode,
+  validateApprovalPolicy,
+  validateEffort,
+} from "./lib.js";
+
+export function buildBaseConfig(): ThreadConfig {
+  const config: ThreadConfig = {
+    cwd: envStr("CODEX_CWD") || process.cwd(),
+    persistSession: envBool("CODEX_PERSIST_SESSION", true),
+  };
+
+  const model = envStr("CODEX_MODEL");
+  if (model) config.model = model;
+
+  const rawSandbox = envStr("CODEX_SANDBOX_MODE") || "read-only";
+  const sandbox = validateSandboxMode(rawSandbox);
+  if (rawSandbox !== sandbox) {
+    console.error(
+      `codex-octopus: invalid CODEX_SANDBOX_MODE "${rawSandbox}", using "read-only"`
+    );
+  }
+  config.sandboxMode = sandbox as ThreadConfig["sandboxMode"];
+
+  const rawApproval = envStr("CODEX_APPROVAL_POLICY") || "on-failure";
+  const approval = validateApprovalPolicy(rawApproval);
+  if (rawApproval !== approval) {
+    console.error(
+      `codex-octopus: invalid CODEX_APPROVAL_POLICY "${rawApproval}", using "on-failure"`
+    );
+  }
+  config.approvalPolicy = approval as ThreadConfig["approvalPolicy"];
+
+  const effort = envStr("CODEX_EFFORT");
+  if (effort) {
+    const validated = validateEffort(effort);
+    if (effort !== validated) {
+      console.error(
+        `codex-octopus: invalid CODEX_EFFORT "${effort}", using "medium"`
+      );
+    }
+    config.effort = validated as ThreadConfig["effort"];
+  }
+
+  const dirs = envList("CODEX_ADDITIONAL_DIRS");
+  if (dirs) config.additionalDirectories = dirs;
+
+  const networkAccess = envStr("CODEX_NETWORK_ACCESS");
+  if (networkAccess !== undefined) {
+    config.networkAccess = networkAccess === "true" || networkAccess === "1";
+  }
+
+  const webSearch = envStr("CODEX_WEB_SEARCH");
+  if (webSearch) config.webSearchMode = webSearch as ThreadConfig["webSearchMode"];
+
+  const instructions = envStr("CODEX_INSTRUCTIONS");
+  if (instructions) config.instructions = instructions;
+
+  const appendInstructions = envStr("CODEX_APPEND_INSTRUCTIONS");
+  if (appendInstructions) config.appendInstructions = appendInstructions;
+
+  return config;
+}

package/src/constants.ts

@@ -0,0 +1,88 @@
+import type { OptionCatalogEntry } from "./types.js";
+
+export const OPTION_CATALOG: OptionCatalogEntry[] = [
+  {
+    key: "model",
+    envVar: "CODEX_MODEL",
+    label: "Model",
+    hint: "Which model to use",
+    example: '"gpt-5-codex", "o3", "codex-1"',
+  },
+  {
+    key: "appendInstructions",
+    envVar: "CODEX_APPEND_INSTRUCTIONS",
+    label: "Behavior instructions",
+    hint: "Instructions appended to the default system prompt",
+    example: '"Always explain your reasoning step by step."',
+  },
+  {
+    key: "instructions",
+    envVar: "CODEX_INSTRUCTIONS",
+    label: "Full instructions",
+    hint: "Completely replaces the default instructions",
+    example: '"You are a security auditor..."',
+  },
+  {
+    key: "sandboxMode",
+    envVar: "CODEX_SANDBOX_MODE",
+    label: "Sandbox mode",
+    hint: "How file system access is restricted",
+    example: '"read-only", "workspace-write", "danger-full-access"',
+  },
+  {
+    key: "approvalPolicy",
+    envVar: "CODEX_APPROVAL_POLICY",
+    label: "Approval policy",
+    hint: "When to prompt for command approval",
+    example: '"never" (auto-approve), "on-failure", "on-request", "untrusted"',
+  },
+  {
+    key: "cwd",
+    envVar: "CODEX_CWD",
+    label: "Working directory",
+    hint: "Default directory the agent operates in",
+    example: '"/home/user/project"',
+  },
+  {
+    key: "additionalDirs",
+    envVar: "CODEX_ADDITIONAL_DIRS",
+    label: "Additional directories",
+    hint: "Extra directories the agent can access (comma-separated)",
+    example: '"/shared/libs,/data"',
+  },
+  {
+    key: "effort",
+    envVar: "CODEX_EFFORT",
+    label: "Reasoning effort",
+    hint: "How hard the agent thinks",
+    example: '"minimal" (fastest), "low", "medium", "high", "xhigh" (deepest)',
+  },
+  {
+    key: "networkAccess",
+    envVar: "CODEX_NETWORK_ACCESS",
+    label: "Network access",
+    hint: "Allow network access from sandbox",
+    example: '"true" or "false" (default)',
+  },
+  {
+    key: "webSearchMode",
+    envVar: "CODEX_WEB_SEARCH",
+    label: "Web search",
+    hint: "Web search mode",
+    example: '"disabled" (default), "cached", "live"',
+  },
+  {
+    key: "persistSession",
+    envVar: "CODEX_PERSIST_SESSION",
+    label: "Persist sessions",
+    hint: "Save sessions for later resume via _reply tool",
+    example: '"true" (default) or "false"',
+  },
+  {
+    key: "apiKey",
+    envVar: "CODEX_API_KEY",
+    label: "API key",
+    hint: "OpenAI API key for this agent (overrides inherited auth)",
+    example: '"sk-..." — leave unset to inherit from parent',
+  },
+];