@iamdevlinph/codex-kit 1.0.6 → 1.0.8

package/README.md

@@ -34,25 +34,29 @@ handlers to the global `hooks.json` without replacing existing hooks.
 
 The Sol root plans, routes, coordinates, and validates. On every prompt, the
 routing hook supplies the current `SUBAGENT_ROUTING.md`; the root classifies the
-task and delegates to the exact matching role. The role's agent TOML—not the
-routing policy—selects its model and reasoning effort. Planning, conversation,
-status, and small read-only checks may stay on the root.
-
-The hook rejects direct root writes through Codex edit tools and obvious
-write-shaped shell commands. `SubagentStart` opens a 15-minute write allowance
-for that worker's `session_id + turn_id`; `SubagentStop` closes it. This identifies
-the delegated lane without hard-coding a model. Codex hooks do not intercept
-every possible indirect shell-write path, so this is a workflow guardrail rather
-than a security boundary.
+task and delegates substantive work to the exact matching role. The role's agent
+TOML—not the routing policy—selects its model and reasoning effort. To avoid
+subagent startup overhead, the root may directly handle planning, conversation,
+read-only checks, documentation, configuration bookkeeping, template
+reconciliation, and explicit low-risk one-file edits.
 
 `global configure` sets these defaults while preserving unrelated settings:
 
 ```toml
 model = "gpt-5.6-sol"
-model_reasoning_effort = "high"
+model_reasoning_effort = "medium"
 plan_mode_reasoning_effort = "high"
 ```
 
+This keeps ordinary root work lighter while retaining high reasoning in Plan
+Mode. Override either effort independently when needed:
+
+```sh
+codex-kit global configure \
+  --reasoning-effort medium \
+  --plan-reasoning-effort high
+```
+
 Before changing these keys, codex-kit creates a timestamped `config.toml`
 backup and records their previous values. `global uninstall` restores those
 values without replacing unrelated configuration changed afterward.
@@ -208,5 +212,3 @@ redistribute the package beyond applicable law and npm's service terms.
 - [Codex custom subagents](https://learn.chatgpt.com/docs/agent-configuration/subagents)
 - [Codex `AGENTS.md` discovery](https://learn.chatgpt.com/docs/agent-configuration/agents-md)
 - [Codex hooks](https://learn.chatgpt.com/docs/hooks)
-- [Delegate Mode](https://github.com/Raylinkh/delegate-mode), whose short-lived
-  subagent allowance pattern informed codex-kit's write guard

package/assets/SUBAGENT_ROUTING.md

@@ -5,15 +5,18 @@ task, classify the work using this file. Route by role and task shape, never by
 model name; each agent definition owns its model and reasoning effort.
 
 The parent owns requirements, architecture, sequencing, integration, and final
-validation. It may handle planning, conversation, status reporting, and small
-read-only checks directly. When a route below matches, spawn that exact role
-before performing the role's work. The user does not need to request delegation.
+validation. It may directly handle planning, conversation, status, read-only
+checks, documentation and instruction updates, configuration bookkeeping,
+template reconciliation, and explicit low-risk edits isolated to one file.
+When a substantive route below matches, spawn that exact role before performing
+the role's work. The user does not need to request delegation.
 
 Select custom agents by exact name:
 
 - Broad repository discovery, contract tracing, or search across many files:
   `code-explorer`
-- Mechanical, well-specified implementation localized to one or two files:
+- Well-specified implementation that benefits from isolated editing or focused
+  tests, usually localized to a few files:
   `quick-implementer`
 - Multi-file behavior changes, debugging, migrations, or substantial tests:
   `implementer`
@@ -27,6 +30,10 @@ actually needed, and use `code-reviewer` after implementation only when the
 change meets its risk threshold. Avoid parallel write-heavy work and never assign
 overlapping files to multiple agents.
 
+Prefer the parent fast path when delegation would cost more than the work. Do not
+spawn a subagent solely because a tool will write a file. Delegate based on task
+complexity, context isolation, testing needs, and review risk.
+
 An assigned implementation agent performs its edits directly and must not
 delegate them again. Use either `quick-implementer` or `implementer` for one
 implementation slice, not both. Read-only agents never modify files.

package/bin/codex-kit.js

@@ -21,7 +21,8 @@ const STATE_FILE = ".codex-kit-state.json";
 const PROJECT_STATE_FILE = ".codex-kit-state.json";
 const REGISTRY = PACKAGE.publishConfig?.registry ?? "https://registry.npmjs.org";
 const DEFAULT_ORCHESTRATOR = "gpt-5.6-sol";
-const DEFAULT_REASONING_EFFORT = "high";
+const DEFAULT_REASONING_EFFORT = "medium";
+const DEFAULT_PLAN_REASONING_EFFORT = "high";
 const sha256 = (data) => createHash("sha256").update(data).digest("hex");
 const read = (file) => readFileSync(file);
 const readText = (file) => readFileSync(file, "utf8");
@@ -107,7 +108,6 @@ function installRoutingHooks(home, previous) {
         timeout: 5,
     };
     const promptGroups = Array.isArray(hooks.UserPromptSubmit) ? hooks.UserPromptSubmit : [];
-    const toolGroups = Array.isArray(hooks.PreToolUse) ? hooks.PreToolUse : [];
     hooks.UserPromptSubmit = [
         ...promptGroups,
         { hooks: [{ ...handler, statusMessage: "Loading subagent routing" }] },
@@ -115,19 +115,7 @@ function installRoutingHooks(home, previous) {
     const startGroups = Array.isArray(hooks.SubagentStart) ? hooks.SubagentStart : [];
     hooks.SubagentStart = [
         ...startGroups,
-        { hooks: [{ ...handler, statusMessage: "Opening delegated write lane" }] },
-    ];
-    const stopGroups = Array.isArray(hooks.SubagentStop) ? hooks.SubagentStop : [];
-    hooks.SubagentStop = [
-        ...stopGroups,
-        { hooks: [{ ...handler, statusMessage: "Closing delegated write lane" }] },
-    ];
-    hooks.PreToolUse = [
-        ...toolGroups,
-        {
-            matcher: "Bash|Edit|Write|MultiEdit|NotebookEdit|apply_patch|ApplyPatch|functions.apply_patch",
-            hooks: [{ ...handler, statusMessage: "Checking orchestrator routing" }],
-        },
+        { hooks: [{ ...handler, statusMessage: "Briefing delegated worker" }] },
     ];
     const updated = `${JSON.stringify(root, null, 2)}\n`;
     const original = existsSync(target) ? readText(target) : "";
@@ -402,7 +390,7 @@ function configureGlobal(options) {
     const desired = {
         model: options.orchestrator,
         model_reasoning_effort: options.reasoningEffort,
-        plan_mode_reasoning_effort: options.reasoningEffort,
+        plan_mode_reasoning_effort: options.planReasoningEffort,
     };
     const priorState = loadState(home);
     const original = existsSync(configFile) ? readText(configFile) : "";
@@ -737,6 +725,7 @@ function parse(argv) {
         codexHome: resolve(process.env.CODEX_HOME || join(homedir(), ".codex")),
         orchestrator: DEFAULT_ORCHESTRATOR,
         reasoningEffort: DEFAULT_REASONING_EFFORT,
+        planReasoningEffort: DEFAULT_PLAN_REASONING_EFFORT,
         force: false,
         positionals: [],
     };
@@ -767,6 +756,12 @@ function parse(argv) {
                 throw new Error(`${arg} requires a value.`);
             options.reasoningEffort = value;
         }
+        else if (arg === "--plan-reasoning-effort") {
+            const value = argv[++index];
+            if (!value)
+                throw new Error(`${arg} requires a value.`);
+            options.planReasoningEffort = value;
+        }
         else
             options.positionals.push(arg);
     }
@@ -791,15 +786,34 @@ Commands:
   --help               Show this help.
   --version            Print the installed version.
 
-Options:
-  --codex-home PATH         Use a Codex home other than CODEX_HOME or ~/.codex.
-  --cwd PATH                Use a project directory other than the current directory.
-  --force                   Replace modified files or config managed by codex-kit.
-  --orchestrator MODEL      Set the root/orchestrator model (default: gpt-5.6-sol).
-  --model MODEL             Alias for --orchestrator.
-  --reasoning-effort LEVEL  Set normal and Plan-mode effort (default: high).
+Options by command:
+  global install
+    --codex-home PATH  Use a Codex home other than CODEX_HOME or ~/.codex.
+    --force            Replace modified files managed by codex-kit.
+
+  global configure
+    --codex-home PATH         Use a Codex home other than CODEX_HOME or ~/.codex.
+    --force                   Replace modified config managed by codex-kit.
+    --orchestrator MODEL      Set the root/orchestrator model (default: gpt-5.6-sol).
+    --model MODEL             Alias for --orchestrator.
+    --reasoning-effort LEVEL       Set normal reasoning effort (default: medium).
+    --plan-reasoning-effort LEVEL  Set Plan-mode reasoning effort (default: high).
+
+  global list, global uninstall
+    --codex-home PATH  Use a Codex home other than CODEX_HOME or ~/.codex.
+
+  project init, project sync
+    --cwd PATH  Use a project directory other than the current directory.
+    --force     Replace modified files managed by codex-kit.
+
+  project status, project mark-applied
+    --cwd PATH  Use a project directory other than the current directory.
 
-Run a command with only its applicable options.`);
+Examples:
+  codex-kit global install --force
+  codex-kit global configure --reasoning-effort medium --plan-reasoning-effort high
+  codex-kit project sync --cwd /path/to/project --force
+  codex-kit project status --cwd /path/to/project`);
 }
 export function main(argv = process.argv.slice(2)) {
     const options = parse(argv);

package/bin/routing-hook.js

@@ -1,132 +1,10 @@
 #!/usr/bin/env node
-import { createHash } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 const home = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const routingFile = join(home, "SUBAGENT_ROUTING.md");
-const allowancesDir = join(home, "codex-kit", "allowances");
-const allowanceTtlMs = 15 * 60 * 1000;
-const writeTools = new Set([
-    "Edit",
-    "Write",
-    "MultiEdit",
-    "NotebookEdit",
-    "apply_patch",
-    "ApplyPatch",
-    "functions.apply_patch",
-]);
-const writeCommands = new Set([
-    "chmod",
-    "chown",
-    "cp",
-    "dd",
-    "install",
-    "ln",
-    "mkdir",
-    "mv",
-    "rm",
-    "rmdir",
-    "rsync",
-    "tee",
-    "touch",
-    "truncate",
-]);
-const gitWriteCommands = new Set([
-    "add",
-    "am",
-    "apply",
-    "checkout",
-    "cherry-pick",
-    "clean",
-    "commit",
-    "merge",
-    "mv",
-    "rebase",
-    "reset",
-    "restore",
-    "revert",
-    "rm",
-    "stash",
-    "switch",
-]);
 const input = JSON.parse(readFileSync(0, "utf8"));
-function allowanceFile(payload) {
-    if (!payload.session_id || !payload.turn_id)
-        return null;
-    const key = createHash("sha256")
-        .update(`${payload.session_id}\0${payload.turn_id}`)
-        .digest("hex");
-    return join(allowancesDir, `${key}.json`);
-}
-function writeAllowance(payload) {
-    const file = allowanceFile(payload);
-    if (!file)
-        return false;
-    mkdirSync(allowancesDir, { recursive: true });
-    const temporary = `${file}.${process.pid}.tmp`;
-    writeFileSync(temporary, JSON.stringify({
-        agentId: payload.agent_id,
-        agentType: payload.agent_type,
-        expiresAt: Date.now() + allowanceTtlMs,
-    }));
-    renameSync(temporary, file);
-    return true;
-}
-function removeAllowance(payload) {
-    const file = allowanceFile(payload);
-    if (file)
-        rmSync(file, { force: true });
-}
-function hasAllowance(payload) {
-    const file = allowanceFile(payload);
-    if (!file || !existsSync(file))
-        return false;
-    try {
-        const value = JSON.parse(readFileSync(file, "utf8"));
-        if (typeof value.expiresAt === "number" && value.expiresAt > Date.now())
-            return true;
-    }
-    catch {
-        // Invalid allowance files fail closed.
-    }
-    rmSync(file, { force: true });
-    return false;
-}
-function pruneAllowances() {
-    if (!existsSync(allowancesDir))
-        return;
-    for (const name of readdirSync(allowancesDir)) {
-        if (!name.endsWith(".json"))
-            continue;
-        const file = join(allowancesDir, name);
-        try {
-            const value = JSON.parse(readFileSync(file, "utf8"));
-            if (typeof value.expiresAt === "number" && value.expiresAt > Date.now())
-                continue;
-        }
-        catch {
-            // Invalid allowance files are stale.
-        }
-        rmSync(file, { force: true });
-    }
-}
-function isWriteShapedBash(command) {
-    if (/(^|[^<])(?:>>?|&>>?|\d>>?)\s*[^&]/.test(command))
-        return true;
-    const commands = command.split(/(?:&&|\|\||;|\|)/).map((part) => part.trim()).filter(Boolean);
-    return commands.some((segment) => {
-        const tokens = segment.match(/(?:[^\s"']+|"[^"]*"|'[^']*')+/g) ?? [];
-        const executable = tokens[0]?.split("/").at(-1);
-        if (!executable)
-            return false;
-        if (writeCommands.has(executable))
-            return true;
-        if ((executable === "sed" || executable === "perl") && tokens.slice(1, 5).some((token) => /^-[^-]*i/.test(token)))
-            return true;
-        return executable === "git" && Boolean(tokens[1] && gitWriteCommands.has(tokens[1]));
-    });
-}
 function hookContext(event, context) {
     return JSON.stringify({
         hookSpecificOutput: {
@@ -143,24 +21,6 @@ if (input.hook_event_name === "UserPromptSubmit" && existsSync(routingFile)) {
         "this policy, determine each role's model and reasoning effort.");
 }
 if (input.hook_event_name === "SubagentStart") {
-    pruneAllowances();
-    const recorded = writeAllowance(input);
     process.stdout.write(hookContext("SubagentStart", `You are the delegated ${input.agent_type ?? "worker"}. ` +
-        `${recorded ? "A temporary write lane is active." : "No write lane could be recorded."} ` +
         "Follow the assigned scope, perform the role's work directly without further delegation, validate it, and return concise evidence."));
 }
-if (input.hook_event_name === "SubagentStop")
-    removeAllowance(input);
-if (input.hook_event_name === "PreToolUse") {
-    const writeAttempt = writeTools.has(input.tool_name ?? "") ||
-        (input.tool_name === "Bash" && isWriteShapedBash(input.tool_input?.command ?? ""));
-    if (writeAttempt && !input.agent_id && !hasAllowance(input)) {
-        process.stdout.write(JSON.stringify({
-            hookSpecificOutput: {
-                hookEventName: "PreToolUse",
-                permissionDecision: "deny",
-                permissionDecisionReason: "The root orchestrator may not write directly. Consult SUBAGENT_ROUTING.md and delegate to the exact role selected there.",
-            },
-        }));
-    }
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iamdevlinph/codex-kit",
-  "version": "1.0.6",
+  "version": "1.0.8",
   "description": "Portable Codex subagents and project AGENTS.md defaults.",
   "type": "module",
   "bin": {