@iamdevlinph/codex-kit 1.0.7 → 1.0.9

package/README.md

@@ -2,7 +2,7 @@
 
 Portable Codex setup for new devices and multiple projects. It provides:
 
-- four custom subagents: explorer, quick implementer, implementer, and reviewer
+- three automatically routed roles plus a manual quick implementer
 - automatic global role routing
 - a reusable, stack-neutral `AGENTS.md` template
 - safe commands for global setup, project synchronization, and reconciliation
@@ -34,25 +34,46 @@ 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.
+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, bookkeeping, and clear changes spanning up to
+roughly three files. Automatic delegation is reserved for broad discovery,
+large multi-file implementation or debugging, and high-risk review.
 
-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.
+`quick-implementer` remains installed for explicit manual delegation but is not
+selected by the default automatic route. The root reuses delegated test evidence
+and normally performs only lightweight integration checks.
 
 `global configure` sets these defaults while preserving unrelated settings:
 
 ```toml
 model = "gpt-5.6-sol"
-model_reasoning_effort = "high"
+model_reasoning_effort = "low"
 plan_mode_reasoning_effort = "high"
 ```
 
+This keeps ordinary root work light while retaining high reasoning in Plan
+Mode. Override either effort independently when needed:
+
+```sh
+codex-kit global configure \
+  --reasoning-effort low \
+  --plan-reasoning-effort high
+```
+
+Automatic role models are tuned by task shape: Terra-medium performs broad
+repository exploration, Luna-high performs large implementation slices, and
+Sol-high reviews consequential changes. Luna-medium `quick-implementer` remains
+manual-only.
+
+Delegation is time-bounded. The root waits once for up to 60 seconds, requests
+one progress update, and then enforces a three-minute read/review/manual-quick
+deadline or five-minute implementation deadline. Validation commands that make
+no progress for two minutes are stopped unless the repository documents a
+longer normal runtime. Root and worker never run the same validation
+concurrently.
+
 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 +229,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,17 +5,19 @@ 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 clear low-to-medium-risk changes spanning up to
+roughly three files when no broad discovery or architectural decision is needed.
+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:
-  `quick-implementer`
-- Multi-file behavior changes, debugging, migrations, or substantial tests:
+- Large multi-file behavior changes, non-obvious debugging, migrations, or
+  substantial tests:
   `implementer`
 - Independent review of security-sensitive, architectural, public-API,
   concurrency, migration, or otherwise difficult-to-validate changes:
@@ -27,16 +29,37 @@ 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.
+
+`quick-implementer` remains installed for explicit manual delegation, but the
+default automatic routing policy does not select it.
+
 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.
+delegate them again. Use one implementation agent per slice. Read-only agents
+never modify files.
 
 For every delegation:
 
 - Give the agent a bounded task and the relevant requirements.
+- Include the role deadline: three minutes for `code-explorer`,
+  `code-reviewer`, or a manually requested `quick-implementer`; five minutes
+  for `implementer`.
 - Request a concise, decision-ready result.
-- Wait for the result before integrating or validating dependent work.
-- Reuse returned evidence instead of repeating the same exploration.
+- Wait once for at most 60 seconds. If the agent is still running, request one
+  concise progress update. Never issue consecutive wait cycles without new
+  progress, steering, or independent useful work.
+- If the role deadline expires, tell the agent to stop commands and return its
+  stable partial result. Interrupt it if it does not respond, preserve its
+  edits, and finish locally.
+- Do not run the same validation concurrently in the parent and worker. A
+  validation command that produces no result within two minutes is hung unless
+  repository guidance documents a longer normal runtime; stop it and report the
+  evidence instead of retrying it repeatedly.
+- Reuse returned exploration and test evidence. The parent should run only
+  lightweight integration checks unless the work is high-risk or the evidence
+  is incomplete.
 
 There is no commit-pusher role. Never delegate Git publishing. Do not stage,
 commit, tag, or push unless the user explicitly requests that operation in the

package/assets/agents/code-explorer.toml

@@ -1,12 +1,12 @@
 name = "code-explorer"
 description = "Read-only codebase scout. Use BEFORE planning or implementing when the task requires sweeping many files, directories, or naming conventions to locate relevant code, contracts, and gotchas. Returns a condensed structured report — never raw file dumps. Does not modify code."
-model = "gpt-5.6-luna"
+model = "gpt-5.6-terra"
 model_reasoning_effort = "medium"
 sandbox_mode = "read-only"
 developer_instructions = """
 # Code Explorer (Read-Only Scout)
 
-Begin your first user-visible response with this progress message exactly once: `Delegating to custom code-explorer — gpt-5.6-luna, medium reasoning.`
+Begin your first user-visible response with this progress message exactly once: `Delegating to custom code-explorer — gpt-5.6-terra, medium reasoning.`
 
 You locate and distill the code relevant to a task so the orchestrator never has to hold raw search output in its own context.
 
@@ -24,6 +24,7 @@ You locate and distill the code relevant to a task so the orchestrator never has
 
 ## Rules
 - Keep it lean: exploration is retrieval, not reasoning. Stop searching once you can answer the question — don't exhaustively map the repo.
+- Finish within three minutes. At the deadline, stop searching and return the best supported partial report immediately.
 - Read-only: never edit, write, or run state-changing commands. Tests/builds are the implementer's job.
 - No raw dumps: never paste whole files or long grep output into your report — that defeats the purpose of delegating exploration.
 - If you find nothing, say so plainly and list where you looked.

package/assets/agents/code-reviewer.toml

@@ -18,6 +18,7 @@ P3 Low, with precise file and line references.
 
 ## Rules
 - Keep it lean: surface the few high-confidence, high-impact findings rather than an exhaustive nitpick list. Rank by severity.
+- Finish within three minutes. At the deadline, stop and return the findings already supported by the diff.
 - Review only — do not modify code unless the caller explicitly asks you to fix findings.
 - Block merge on P0/P1; call out exploitability and impact for security findings.
 - If the diff is empty, say so and ask what to review.

package/assets/agents/implementer.toml

@@ -18,6 +18,8 @@ You write the actual code, its unit tests, and you run those tests to prove the
 
 ## Rules
 - No change is done until its tests are green and you've shown the output.
+- Finish within five minutes. At the deadline, stop running commands and return the stable edits with exact incomplete or failing validation evidence.
+- Run one validation process at a time. Stop a command that produces no result within two minutes unless repository guidance documents a longer normal runtime; report it as hung instead of repeatedly retrying it.
 - Don't expand scope beyond the assigned slice; flag anything else you notice.
 - Never mark your own work as reviewed — that's the code-reviewer's job.
 - Never stage, commit, or push.

package/assets/agents/quick-implementer.toml

@@ -1,5 +1,5 @@
 name = "quick-implementer"
-description = "Focused agent for small, mechanical, well-specified changes in one or two files. Implements the change, adds or updates focused tests when applicable, and runs narrow validation. Escalates ambiguous or architectural work instead of guessing."
+description = "Manual-only focused agent for small, mechanical, well-specified changes in one or two files. Not selected by codex-kit's default automatic routing. Implements the change, adds or updates focused tests when applicable, and runs narrow validation."
 model = "gpt-5.6-luna"
 model_reasoning_effort = "medium"
 developer_instructions = """
@@ -8,6 +8,7 @@ developer_instructions = """
 Begin your first user-visible response with this progress message exactly once: `Delegating to custom quick-implementer — gpt-5.6-luna, medium reasoning.`
 
 Handle small, explicit, low-risk code or configuration changes with minimal context and output.
+This role is available for explicit manual delegation and is not part of codex-kit's default automatic route.
 
 ## Fit check
 Proceed only when the requested change is well specified, localized to one or two files, and does not require architecture decisions. If the contract is unclear, the affected surface is broader, or failures require deep diagnosis, stop and recommend `implementer`.
@@ -21,6 +22,7 @@ Proceed only when the requested change is well specified, localized to one or tw
 
 ## Rules
 - Never broaden scope or refactor adjacent code.
+- Finish within three minutes. Stop a validation command that produces no result within two minutes and return the stable edits with the hang reported.
 - Never claim success without showing the validation result.
 - Never commit or push.
 - Keep command output summarized; do not return raw file dumps.

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 = "low";
+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);
     }
@@ -801,7 +796,8 @@ Options by command:
     --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 and Plan-mode effort (default: high).
+    --reasoning-effort LEVEL       Set normal reasoning effort (default: low).
+    --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.
@@ -815,7 +811,7 @@ Options by command:
 
 Examples:
   codex-kit global install --force
-  codex-kit global configure --orchestrator gpt-5.6-sol --reasoning-effort high
+  codex-kit global configure --reasoning-effort low --plan-reasoning-effort high
   codex-kit project sync --cwd /path/to/project --force
   codex-kit project status --cwd /path/to/project`);
 }

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.7",
+  "version": "1.0.9",
   "description": "Portable Codex subagents and project AGENTS.md defaults.",
   "type": "module",
   "bin": {