@iamdevlinph/codex-kit 1.0.3 → 1.0.5

package/README.md

@@ -3,7 +3,7 @@
 Portable Codex setup for new devices and multiple projects. It provides:
 
 - four custom subagents: explorer, quick implementer, implementer, and reviewer
-- global subagent-routing guidance without a `commit-pusher`
+- automatic global role routing
 - a reusable, stack-neutral `AGENTS.md` template
 - safe commands for global setup, project synchronization, and reconciliation
 
@@ -20,12 +20,30 @@ codex-kit global install
 codex-kit global configure
 ```
 
+Start a new Codex task or restart the client after installation. Codex may ask
+you to review and trust the new command hooks once; approve them after confirming
+that they run the installed `${CODEX_HOME:-~/.codex}/codex-kit/routing-hook.js`.
+
 `npm install --global @iamdevlinph/codex-kit@latest` works as an alternative.
 For one-off use without a global installation, prefix a command with
 `pnpm dlx @iamdevlinph/codex-kit@latest`.
 
-`global install` copies reusable agents to `${CODEX_HOME:-~/.codex}` and
-maintains a marked routing section in the global `AGENTS.md`.
+`global install` copies reusable agents to `${CODEX_HOME:-~/.codex}`, maintains
+a marked routing section in the global `AGENTS.md`, and adds package-owned
+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.
 
 `global configure` sets these defaults while preserving unrelated settings:
 
@@ -55,8 +73,8 @@ pnpm dlx @iamdevlinph/codex-kit@latest global list
 ```
 
 The summary shows the Codex home, orchestrator, normal and Plan-mode reasoning
-effort, routing status, and installed custom agents without dumping unrelated
-configuration.
+effort, routing-file and routing-hook status, and installed custom agents without
+dumping unrelated configuration.
 
 Uninstall package-managed global files:
 
@@ -64,8 +82,8 @@ Uninstall package-managed global files:
 pnpm dlx @iamdevlinph/codex-kit@latest global uninstall
 ```
 
-Modified managed files are preserved unless `--force` is supplied. An existing
-unmanaged `commit-pusher.toml` is reported but never silently deleted.
+Uninstall removes only codex-kit's handlers from `hooks.json` and preserves other
+hooks. Modified managed files are preserved unless `--force` is supplied.
 
 ## Commands
 
@@ -175,7 +193,7 @@ commands do not add network latency or depend on registry availability.
 ## Requirements
 
 - Node.js 20 or newer
-- Codex with custom subagent support
+- Codex with custom subagent and lifecycle-hook support
 
 The published package has no runtime dependencies and uses only Node.js
 standard-library modules.
@@ -189,3 +207,6 @@ 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

@@ -1,36 +1,43 @@
 # Subagent Routing
 
-Keep focused, tightly coupled work in the parent task. Delegate only bounded,
-independent work when it materially reduces parent-context growth, latency, or
-cost. The user does not need to request subagents explicitly.
+The root parent is the planner and orchestrator. Before acting on a substantive
+task, classify the work using this file. Route by role and task shape, never by a
+model name; each agent definition owns its model and reasoning effort.
 
-The parent owns requirements, architecture, integration, and final validation.
-Never delegate the overall objective. Avoid parallel write-heavy work and never
-assign overlapping files to multiple agents.
-
-Do not delegate trivial conversation, known-target edits limited to one or two
-files, or straightforward commands. A slow command alone is not a reason to
-delegate.
-
-When delegation is worthwhile:
-
-- Prefer one subagent. Add more only for independent, non-overlapping work.
-- Give each agent a bounded task and request a concise, decision-ready report.
-- For parallel implementation, assign explicit file or module ownership.
-- Wait for relevant agents and synthesize their results in the parent task.
-- Reuse prior exploration and evidence instead of repeating it.
+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.
 
 Select custom agents by exact name:
 
-- Broad repository discovery or contract tracing: `code-explorer`
-- Mechanical, well-specified one- or two-file change: `quick-implementer`
-- Multi-file behavior change, debugging, or substantial tests: `implementer`
-- Independent review of high-risk or difficult-to-validate changes: `code-reviewer`
-
-Use either `quick-implementer` or `implementer` for a change, not both. Use the
-lowest reasoning effort that reliably fits the work. Do not substitute a generic
-agent when a matching custom role is available.
+- 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:
+  `implementer`
+- Independent review of security-sensitive, architectural, public-API,
+  concurrency, migration, or otherwise difficult-to-validate changes:
+  `code-reviewer`
+
+For tasks with multiple phases, sequence only the roles that add value. For
+example, use `code-explorer` before implementation only when broad discovery is
+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.
+
+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.
+
+For every delegation:
+
+- Give the agent a bounded task and the relevant requirements.
+- 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.
 
 There is no commit-pusher role. Never delegate Git publishing. Do not stage,
-commit, or push unless the user explicitly requests that operation in the current
-task; if requested, the parent handles it after review.
+commit, tag, or push unless the user explicitly requests that operation in the
+current task; if requested, the parent handles it after review.

package/bin/codex-kit.js

@@ -10,6 +10,7 @@ const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const ASSETS = join(ROOT, "assets");
 const AGENTS_DIR = join(ASSETS, "agents");
 const ROUTING_FILE = join(ASSETS, "SUBAGENT_ROUTING.md");
+const ROUTING_HOOK_FILE = join(ROOT, "bin", "routing-hook.js");
 const TEMPLATE_FILE = join(ASSETS, "TEMPLATE_AGENTS.md");
 const PACKAGE = JSON.parse(readFileSync(join(ROOT, "package.json"), "utf8"));
 const GLOBAL_BEGIN = "<!-- BEGIN codex-kit:subagent-routing -->";
@@ -44,6 +45,116 @@ function write(file, data) {
     writeFileSync(temporary, data);
     renameSync(temporary, file);
 }
+function readJsonObject(file) {
+    if (!existsSync(file))
+        return {};
+    try {
+        const value = JSON.parse(readText(file));
+        if (isRecord(value))
+            return value;
+    }
+    catch {
+        // Use the actionable error below for invalid JSON and non-object roots.
+    }
+    throw new Error(`${file} must contain a JSON object; fix or move it before installing.`);
+}
+function shellQuote(value) {
+    return `'${value.replaceAll("'", `'"'"'`)}'`;
+}
+function hookCommands(file) {
+    return {
+        command: `/usr/bin/env node ${shellQuote(file)}`,
+        commandWindows: `node ${JSON.stringify(file)}`,
+    };
+}
+function removeHookHandlers(root, state) {
+    const hooks = root.hooks;
+    if (!isRecord(hooks))
+        return;
+    for (const [event, groupsValue] of Object.entries(hooks)) {
+        if (!Array.isArray(groupsValue))
+            continue;
+        const groups = groupsValue.flatMap((groupValue) => {
+            if (!isRecord(groupValue) || !Array.isArray(groupValue.hooks))
+                return [groupValue];
+            const handlers = groupValue.hooks.filter((handler) => {
+                if (!isRecord(handler))
+                    return true;
+                return handler.command !== state.command && handler.commandWindows !== state.commandWindows;
+            });
+            return handlers.length ? [{ ...groupValue, hooks: handlers }] : [];
+        });
+        if (groups.length)
+            hooks[event] = groups;
+        else
+            delete hooks[event];
+    }
+}
+function installRoutingHooks(home, previous) {
+    const target = join(home, "hooks.json");
+    const hookFile = join(home, "codex-kit", "routing-hook.js");
+    const commands = hookCommands(hookFile);
+    const created = previous?.created ?? !existsSync(target);
+    const root = readJsonObject(target);
+    if (previous)
+        removeHookHandlers(root, previous);
+    const hooks = isRecord(root.hooks) ? root.hooks : {};
+    root.hooks = hooks;
+    const handler = {
+        type: "command",
+        command: commands.command,
+        commandWindows: commands.commandWindows,
+        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" }] },
+    ];
+    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" }],
+        },
+    ];
+    const updated = `${JSON.stringify(root, null, 2)}\n`;
+    const original = existsSync(target) ? readText(target) : "";
+    if (updated !== original) {
+        backup(target);
+        write(target, updated);
+        console.log(`updated: ${target}`);
+    }
+    return { target, ...commands, created };
+}
+function uninstallRoutingHooks(state) {
+    if (!existsSync(state.target)) {
+        console.warn(`preserved missing hooks file: ${state.target}`);
+        return;
+    }
+    const root = readJsonObject(state.target);
+    removeHookHandlers(root, state);
+    const hooks = root.hooks;
+    if (isRecord(hooks) && !Object.keys(hooks).length)
+        delete root.hooks;
+    backup(state.target);
+    if (state.created && !Object.keys(root).length)
+        rmSync(state.target);
+    else
+        write(state.target, `${JSON.stringify(root, null, 2)}\n`);
+    console.log(`removed managed routing hooks from: ${state.target}`);
+}
 function loadState(home) {
     const file = join(home, STATE_FILE);
     if (!existsSync(file))
@@ -234,6 +345,7 @@ function installGlobal(options) {
         version: PACKAGE.version,
         files: {},
         globalAgents: null,
+        hooks: null,
         config: prior.config ?? null,
     };
     for (const name of readdirSync(AGENTS_DIR).filter((name) => name.endsWith(".toml")).sort()) {
@@ -245,6 +357,9 @@ function installGlobal(options) {
     const routingRecord = installFile(ROUTING_FILE, join(home, "SUBAGENT_ROUTING.md"), "routing", prior, options.force);
     if (routingRecord)
         next.files.routing = routingRecord;
+    const hookRecord = installFile(ROUTING_HOOK_FILE, join(home, "codex-kit", "routing-hook.js"), "routing-hook", prior, options.force);
+    if (hookRecord)
+        next.files["routing-hook"] = hookRecord;
     for (const [key, record] of Object.entries(prior.files)) {
         if (key in next.files)
             continue;
@@ -272,6 +387,7 @@ function installGlobal(options) {
         console.log(`updated: ${globalAgents}`);
     }
     next.globalAgents = { target: globalAgents };
+    next.hooks = installRoutingHooks(home, prior.hooks);
     saveState(home, next);
     const commitPusher = join(home, "agents", "commit-pusher.toml");
     if (existsSync(commitPusher)) {
@@ -360,6 +476,11 @@ function listGlobal(options) {
     const hasRoutingBlock = existsSync(globalAgents) && readText(globalAgents).includes(GLOBAL_BEGIN);
     console.log(`Global routing: ${hasRoutingBlock ? "installed" : "not installed"}`);
     console.log(`Routing file: ${existsSync(routingFile) ? routingFile : "missing"}`);
+    const routingHook = state.hooks;
+    const hooksInstalled = Boolean(routingHook &&
+        existsSync(routingHook.target) &&
+        readText(routingHook.target).includes(routingHook.command));
+    console.log(`Routing hook: ${hooksInstalled ? "installed" : "not installed"}`);
     console.log("Custom agents:");
     const agents = existsSync(agentsDir)
         ? readdirSync(agentsDir).filter((name) => name.endsWith(".toml")).sort()
@@ -441,6 +562,14 @@ function uninstallGlobal(options) {
             }
         }
     }
+    if (state.hooks)
+        uninstallRoutingHooks(state.hooks);
+    const allowancesDir = join(home, "codex-kit", "allowances");
+    if (existsSync(allowancesDir))
+        rmSync(allowancesDir, { recursive: true, force: true });
+    const kitDir = join(home, "codex-kit");
+    if (existsSync(kitDir) && !readdirSync(kitDir).length)
+        rmSync(kitDir, { recursive: true });
     rmSync(statePath);
     console.log(`Codex kit uninstalled from ${home}`);
 }
@@ -647,22 +776,30 @@ function help() {
     console.log(`codex-kit ${PACKAGE.version}
 
 Usage:
-  codex-kit global install [--codex-home PATH] [--force]
-  codex-kit global configure [--orchestrator MODEL] [--reasoning-effort LEVEL]
-  codex-kit global list [--codex-home PATH]
-  codex-kit global uninstall [--codex-home PATH]
-  codex-kit project init [--cwd PATH]
-  codex-kit project sync [--cwd PATH]
-  codex-kit project status [--cwd PATH]
-  codex-kit project mark-applied [--cwd PATH]
-  codex-kit version check
-  codex-kit --help
-  codex-kit --version
+  codex-kit <command> [options]
+
+Commands:
+  global install       Install or update package-owned agents and routing guidance.
+  global configure     Set the orchestrator and normal/Plan reasoning defaults.
+  global list          Show model settings, routing status, and custom agents.
+  global uninstall     Restore managed config values and remove package-owned files.
+  project init         Initialize AGENTS.md, TEMPLATE_AGENTS.md, and project state.
+  project sync         Refresh TEMPLATE_AGENTS.md without editing AGENTS.md.
+  project status       Show whether template changes still need reconciliation.
+  project mark-applied Record the current template as reconciled with AGENTS.md.
+  version check        Compare the installed version with the latest npm release.
+  --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).
 
-Global configure defaults to gpt-5.6-sol with high normal and Plan-mode reasoning
-and edits only those top-level model settings in CODEX_HOME/config.toml.
-Global install manages custom agents and a marked routing block under CODEX_HOME.
-Project sync refreshes TEMPLATE_AGENTS.md and never merges it into AGENTS.md.`);
+Run a command with only its applicable options.`);
 }
 export function main(argv = process.argv.slice(2)) {
     const options = parse(argv);

package/bin/routing-hook.js

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } 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: {
+            hookEventName: event,
+            additionalContext: context,
+        },
+    });
+}
+if (input.hook_event_name === "UserPromptSubmit" && existsSync(routingFile)) {
+    const routing = readFileSync(routingFile, "utf8").trim();
+    process.stdout.write(`Codex-kit routing policy for this turn:\n\n${routing}\n\n` +
+        "Classify the task using this policy before acting. When it requires delegation, " +
+        "spawn the exact named role before doing that role's work. Agent definitions, not " +
+        "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.3",
+  "version": "1.0.5",
   "description": "Portable Codex subagents and project AGENTS.md defaults.",
   "type": "module",
   "bin": {