codex-model-router 1.2.0 → 2.1.0

package/README.md

@@ -1,222 +1,158 @@
 # codex-model-router
 
-A small Node.js CLI that safely installs advisory Codex subagent routing for Terra, Luna, and Sol without replacing unrelated user configuration.
+A small Node.js CLI that safely installs adaptive Codex subagent routing for Terra, Luna, and Sol without replacing unrelated user configuration or the user's selected primary model.
 
-> Routing is advisory. Terra reads the installed skill and decides when to delegate. This package does not intercept prompts or guarantee a hard model switch.
+> Routing is advisory. Codex reads the installed skills and decides when to delegate. This package does not intercept prompts, guarantee a hard model switch, or modify AGENTS.md.
 
-## Compatibility
+## Routing model
 
-Compatibility was verified on 2026-07-31 against:
+The normal installation uses free mode:
 
-- Codex CLI `0.145.0` or newer
-- Node.js 18, 20, 22, and 24
-- Windows, Linux, and macOS GitHub-hosted runners
-- Codex project agents in `.codex/agents/`
-- Codex user agents in `$CODEX_HOME/agents/` or `~/.codex/agents/`
-- project skills in `.agents/skills/`
-- user skills in `~/.agents/skills/`
+- The user-selected primary model handles conversation, clarification, follow-ups, final replies, and trivial work.
+- Terra/high investigates, produces implementation-ready plans, verifies results, debugs, and replans.
+- Luna/xhigh performs most clear, bounded, repetitive, or independently verifiable implementation work.
+- Sol/medium is read-only and used only when Terra still cannot resolve core logic after focused investigation and one materially revised plan, or when the user explicitly requests Sol.
+- Existing built-in and custom agents remain available and take precedence when they are a better match.
 
-The selected Codex account must have access to `gpt-5.6-terra`, `gpt-5.6-luna`, and `gpt-5.6-sol`. Older Codex versions may not recognize the generated agent or skill files.
+A normal workflow is Terra -> Luna -> Terra. Implementation errors return to Luna as focused corrections. Plan or logic errors return to Terra for a revised plan before Luna continues. Sol is not a routine reviewer.
 
 ## Quick start
 
-Preview a project installation without changing files:
+Preview without changing files:
 
 ```sh
-npx codex-model-router install --set-default --dry-run
+npx codex-model-router install --dry-run
 ```
 
-Install Terra/high as the project default, add Luna and Sol, then verify:
+Install free-mode routing and verify it:
 
 ```sh
-npx codex-model-router install --set-default
+npx codex-model-router install
 npx codex-model-router doctor
 ```
 
-Remove only unchanged package-managed settings and files:
+Remove only unchanged package-managed files and settings:
 
 ```sh
 npx codex-model-router uninstall
 ```
 
-## Install
+## Optional Terra default
+
+A normal install does not add or change top-level model settings. Users remain free to select any primary model through Codex.
 
-Run directly from npm without installing the CLI globally:
+To explicitly set and track Terra/high as the selected scope's default:
 
 ```sh
-npx codex-model-router install
+codex-model-router install --set-default
 ```
 
-Install the CLI command globally:
+Running a later plain `install` returns package-managed default settings to free mode. User-modified model settings are preserved.
+
+## Agent reasoning
+
+The managed agent defaults are Terra/high, Luna/xhigh, and Sol/medium. Override all agents or individual agents during installation:
 
 ```sh
-npm install -g codex-model-router
-codex-model-router install
+codex-model-router install --agent-reasoning high
+codex-model-router install --terra-reasoning xhigh --luna-reasoning low --sol-reasoning max
 ```
 
-Installing the CLI globally only makes the command available system-wide. It does not modify user-level Codex configuration. The separate `install --global` option applies routing to the current user's Codex configuration.
+Supported values are `none`, `low`, `medium`, `high`, `xhigh`, and `max`. Per-agent options override `--agent-reasoning`. Later installs preserve unchanged package-managed reasoning choices; manually edited agent files remain protected.
 
-Install a specific GitHub release:
+## Install
+
+Run from npm:
 
 ```sh
-npm install -g https://github.com/Honguan/codex-model-router/archive/refs/tags/v1.2.0.tar.gz
+npx codex-model-router install
+```
+
+Install the command globally:
+
+```sh
+npm install -g codex-model-router
 codex-model-router install
 ```
 
-## Project and global scope
+Installing the CLI globally only makes the command available system-wide. Use `install --global` to install routing for the current user's Codex configuration.
 
-Project scope is the default:
+Install a specific GitHub release:
 
 ```sh
+npm install -g https://github.com/Honguan/codex-model-router/archive/refs/tags/v2.1.0.tar.gz
 codex-model-router install
 ```
 
-It manages only:
+## Managed files
+
+Project scope is the default and manages only:
 
 ```text
-.codex/config.toml
+.codex/config.toml                              # only with --set-default or a managed migration
+.codex/agents/terra.toml
 .codex/agents/luna.toml
 .codex/agents/sol.toml
 .codex/model-router-state.json
-.codex/config.toml.codex-model-router.bak        # only when needed
+.codex/config.toml.codex-model-router.bak       # only when needed
 .agents/skills/model-router/SKILL.md
+.agents/skills/implementation-planning/SKILL.md
 ```
 
-During a mutating operation it may temporarily create:
-
-```text
-.codex/model-router.lock
-.codex/model-router-transaction.json
-.codex/model-router-transaction-data/
-```
-
-These transient files are removed after a successful operation or safe recovery.
-
-Use global scope only when the routing configuration should apply to every Codex project for the current user:
+Use global scope with:
 
 ```sh
 codex-model-router install --global
 codex-model-router doctor --global
 ```
 
-Global scope manages the equivalent paths under `$CODEX_HOME` and stores the skill under `~/.agents/skills/model-router/`. When `CODEX_HOME` is unset, it defaults to `~/.codex`.
-
-## Existing settings
-
-A normal install adds Terra/high only when the top-level values are absent. Existing model values are preserved:
-
-```sh
-codex-model-router install
-```
+Global scope stores agents under `$CODEX_HOME/agents` and skills under `~/.agents/skills`. When `CODEX_HOME` is unset, it defaults to `~/.codex`.
 
-To explicitly set and track Terra/high:
+Existing files at managed paths are never overwritten. Later manual edits are preserved and reported by `doctor`.
 
-```sh
-codex-model-router install --set-default
-```
+## Prompt and cache efficiency
 
-`--set-default` changes only:
+The installed model-router skill is intentionally short. Detailed planning rules live in the separate implementation-planning skill and are loaded only for nontrivial or uncertain changes.
 
-```toml
-model = "gpt-5.6-terra"
-model_reasoning_effort = "high"
-```
+Within the same agent thread, accepted state is kept and concise deltas are appended. A new agent thread receives the latest self-contained snapshot. After three deltas or a material contract or logic change, Terra produces a new snapshot.
 
-The exact prior values are recorded. Uninstall restores them only while the current values still match what the package installed. Later user edits are preserved and reported instead of overwritten.
+Prompt-cache reuse is best effort: genuinely new information cannot be a cache hit on first use. Stable wording and ordering improve repeated-prefix reuse, but correctness takes priority over cache behavior.
 
-Existing Luna, Sol, or skill files are never overwritten. Unrelated TOML settings, comments, BOM, ordering, and LF/CRLF line endings are preserved.
+## Planning rules
 
-## Installed routing
+For nontrivial changes, Terra identifies only applicable correctness-critical details, including exact files and symbols, names, contracts, parameter flow, callers, ordered logic, invariants, fixed decisions, safe local choices, return conditions, and acceptance criteria.
 
-- Terra/high handles normal questions, coding, debugging, fixes, tests, and implementation.
-- Luna/high handles deterministic repeated edits, bulk patterns, searches, formatting, counting, extraction, and summaries.
-- Sol/medium/workspace-write handles security-sensitive or high-regression-risk review and implementation.
-- Sol normally reviews first and may edit files only when Terra explicitly delegates implementation or a confirmed fix.
-- Simple questions do not spawn a subagent.
+Information is marked as CONFIRMED, PROPOSED, or UNKNOWN. Luna does not begin implementation while an UNKNOWN can materially change behavior, targets, contracts, parameter flow, control flow, or compatibility.
 
-Users may edit model names, reasoning levels, and `sandbox_mode` directly in the generated TOML files. Later installs preserve manual edits, and `doctor` reports changed managed files.
+Terra verifies separately whether implementation matches the plan and whether the plan plus implementation satisfy the original requirement. After three cycles without new evidence or a changed decision, the workflow stops instead of repeating the same approach.
 
 ## Commands
 
 ```text
 codex-model-router install [--global] [--set-default] [--dry-run]
+  [--agent-reasoning <effort>]
+  [--terra-reasoning <effort>] [--luna-reasoning <effort>] [--sol-reasoning <effort>]
 codex-model-router uninstall [--global] [--dry-run]
 codex-model-router doctor [--global]
 codex-model-router --version
 ```
 
-`doctor` is read-only. Exit code `0` means healthy; exit code `1` means action is required.
-
-Common statuses:
-
-- `healthy`: the managed item matches its expected state.
-- `preserve` or `user-modified`: user content was detected and left unchanged.
-- `missing` or `invalid`: a required item is absent or malformed.
-- `unsafe-state`: state paths or path components are unsafe.
-- `locked` or `stale-lock`: another operation is active or a previous process ended unexpectedly.
-- `unfinished`, `recoverable`, `conflicting`, or `corrupt`: an interrupted transaction needs attention.
+`doctor` is read-only. Exit code 0 means healthy; exit code 1 means action is required.
 
 ## Safety behavior
 
+- Preserves unrelated TOML settings, comments, BOM, ordering, and LF/CRLF line endings.
 - Rejects malformed, non-UTF-8, duplicate, or unsafe configuration before writing.
-- Rejects symlinks and Windows junctions in managed paths so writes cannot escape the selected scope.
-- Uses a scope-level process lock to prevent concurrent install/uninstall races.
-- Uses an atomic transaction journal and private snapshots to recover interrupted multi-file operations.
-- Never overwrites post-interruption user changes during recovery.
-- Uses atomic file replacement and rollback for handled failures.
-- Removes or restores only unchanged package-managed content.
-- Never modifies `AGENTS.md`, shell profiles, editor settings, hooks, MCP servers, telemetry, accounts, or environment variables.
+- Rejects symlinks and Windows junctions in managed paths.
+- Uses scope-level locking, atomic transactions, rollback, and conflict-safe recovery.
+- Never overwrites post-interruption user changes.
 - Dry-run creates no files, directories, backups, locks, journals, or state.
-- Tests use temporary directories and never touch real Codex configuration.
-
-## Troubleshooting
-
-### Agents or skills do not appear
-
-Restart Codex after installation. Verify the selected scope with `doctor` or `doctor --global`, and confirm that your Codex version is at least the compatibility baseline above.
-
-### `user-modified`
-
-The file or setting was changed after installation. The CLI intentionally leaves it untouched. Review the reported path and decide manually whether to retain the custom value or reinstall the package template under a different name.
-
-### `unsafe-state` or unsafe path component
-
-Do not delete the reported file blindly. Check whether `.codex`, `.agents`, `CODEX_HOME`, or one of their parent directories is a symlink or Windows junction. Use a normal directory inside the intended project or user scope.
-
-### Active or stale lock
-
-An active lock includes the operation and process ID. Wait for that process to finish. A later mutating command automatically removes a stale lock only when the recorded local process is no longer alive. A corrupt or remote-host lock must be inspected manually before removal.
+- Never modifies AGENTS.md, shell profiles, editor settings, hooks, MCP servers, telemetry, accounts, or environment variables.
 
-### Interrupted transaction
-
-Run `doctor` first. A mutating command automatically rolls back `unfinished` or `recoverable` transactions when all hashes still match. `conflicting` means a managed file changed after interruption; preserve that file and resolve the journal manually rather than forcing an overwrite. `corrupt` means the journal or snapshot cannot be trusted.
-
-### Untracked backup already exists
-
-The CLI refuses to replace `config.toml.codex-model-router.bak`. Compare it with `config.toml`, move it to a clearly named safe location, and retry only after confirming its ownership.
-
-### Permission or `CODEX_HOME` errors
-
-For project scope, verify write access to the project. For global scope, print and verify `CODEX_HOME`; do not run with elevated privileges merely to bypass an unexplained path error.
-
-### Manual backup recovery
-
-The managed `.bak` is the exact pre-change configuration. Before restoring it, stop Codex, preserve the current `config.toml` under a new name, verify both files, and restore only within the same project/global scope.
-
-### npx uses an old version
-
-Request the exact version first:
-
-```sh
-npx --yes codex-model-router@1.2.0 --version
-```
-
-When necessary, inspect the npm cache with `npm cache verify`; avoid deleting unrelated cache directories blindly.
-
-## Security and release integrity
+## Compatibility
 
-Security vulnerabilities should be reported privately according to [SECURITY.md](SECURITY.md).
+Compatibility is tested on Node.js 18, 20, 22, and 24 across Windows, Linux, and macOS runners. The selected Codex account must have access to gpt-5.6-terra, gpt-5.6-luna, and gpt-5.6-sol.
 
-Releases use npm Trusted Publishing through GitHub Actions, verified provenance, exact tag/version validation, current-version-only release notes, workflow linting, and a clean public-registry end-to-end install/doctor/uninstall check before the GitHub Release is created. Maintainer setup and release steps are documented in [MAINTAINERS.md](MAINTAINERS.md).
+Restart Codex after installation so new agents and skills are discovered. Use `doctor` for missing, user-modified, unsafe-state, lock, or interrupted-transaction reports.
 
-Codex references: [Subagents](https://developers.openai.com/codex/subagents), [Build skills](https://developers.openai.com/codex/build-skills), and [Configuration reference](https://developers.openai.com/codex/config-reference).
+Security vulnerabilities should be reported privately according to [SECURITY.md](SECURITY.md). Maintainer setup and release steps are documented in [MAINTAINERS.md](MAINTAINERS.md).

package/bin/codex-model-router.js

@@ -1,4 +1,4 @@
 #!/usr/bin/env node
-import { run } from "../lib/router.js";
+import { runCli } from "../lib/agent-reasoning-cli.js";
 
-process.exitCode = await run(process.argv.slice(2), { output: console.log });
+process.exitCode = await runCli(process.argv.slice(2), { output: console.log });

package/lib/agent-reasoning-cli.js

@@ -0,0 +1,160 @@
+import { createHash } from "node:crypto";
+import { lstat, readFile, realpath } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import {
+  AGENT_NAMES,
+  configureAgentReasoning,
+  DEFAULT_AGENT_REASONING,
+  REASONING_EFFORTS,
+  VERSION
+} from "./manifest.js";
+import { run as runCore } from "./router.js";
+
+const OPTION_TO_AGENT = Object.freeze({
+  "--terra-reasoning": "terra",
+  "--luna-reasoning": "luna",
+  "--sol-reasoning": "sol"
+});
+
+function usage() {
+  return `codex-model-router ${VERSION}
+
+Usage:
+  codex-model-router install [--global] [--set-default] [--dry-run]
+    [--agent-reasoning <effort>]
+    [--terra-reasoning <effort>]
+    [--luna-reasoning <effort>]
+    [--sol-reasoning <effort>]
+  codex-model-router uninstall [--global] [--dry-run]
+  codex-model-router doctor [--global]
+  codex-model-router --version
+
+Reasoning efforts: ${REASONING_EFFORTS.join(", ")}
+Defaults: Terra=${DEFAULT_AGENT_REASONING.terra}, Luna=${DEFAULT_AGENT_REASONING.luna}, Sol=${DEFAULT_AGENT_REASONING.sol}`;
+}
+
+function optionValue(argv, index, option) {
+  const token = argv[index];
+  if (token.startsWith(`${option}=`)) return { value: token.slice(option.length + 1), consumed: 1 };
+  const value = argv[index + 1];
+  if (!value || value.startsWith("--")) return { error: `missing value for ${option}` };
+  return { value, consumed: 2 };
+}
+
+function parseReasoningOptions(argv) {
+  const command = argv[0];
+  const cleaned = command ? [command] : [];
+  const overrides = {};
+  let all;
+
+  for (let index = 1; index < argv.length;) {
+    const token = argv[index];
+    const option = token.split("=", 1)[0];
+    const agent = OPTION_TO_AGENT[option];
+    if (option !== "--agent-reasoning" && !agent) {
+      cleaned.push(token);
+      index += 1;
+      continue;
+    }
+    if (command !== "install") return { error: `${option} is supported only for install` };
+    const parsed = optionValue(argv, index, option);
+    if (parsed.error) return parsed;
+    const reasoning = parsed.value.toLowerCase();
+    if (!REASONING_EFFORTS.includes(reasoning)) {
+      return { error: `unsupported reasoning effort: ${parsed.value}` };
+    }
+    if (agent) overrides[agent] = reasoning;
+    else all = reasoning;
+    index += parsed.consumed;
+  }
+  return { cleaned, overrides, all };
+}
+
+function digest(content) {
+  return createHash("sha256").update(content).digest("hex");
+}
+
+async function readRegularText(path) {
+  try {
+    const info = await lstat(path);
+    if (!info.isFile() || info.isSymbolicLink()) return null;
+    return await readFile(path, "utf8");
+  } catch (error) {
+    if (error?.code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+function activeReasoning(content) {
+  const match = content.match(/^\s*model_reasoning_effort\s*=\s*"([^"\r\n]+)"\s*(?:#.*)?$/m);
+  return match && REASONING_EFFORTS.includes(match[1]) ? match[1] : null;
+}
+
+function versionAtLeast(version, minimum) {
+  const parse = (value) => String(value || "0").split(".").slice(0, 3).map((part) => Number.parseInt(part, 10) || 0);
+  const left = parse(version);
+  const right = parse(minimum);
+  for (let index = 0; index < 3; index += 1) {
+    if (left[index] !== right[index]) return left[index] > right[index];
+  }
+  return true;
+}
+
+async function installedReasoning(argv, options) {
+  const global = argv.includes("--global");
+  const home = resolve(options.home ?? homedir());
+  const cwd = resolve(options.cwd ?? process.cwd());
+  const env = options.env ?? process.env;
+  const codexHome = global
+    ? resolve(env.CODEX_HOME || join(home, ".codex"))
+    : join(cwd, ".codex");
+  const stateText = await readRegularText(join(codexHome, "model-router-state.json"));
+  if (!stateText) return { reasoning: {}, content: {}, packageVersion: null };
+
+  let state;
+  try {
+    state = JSON.parse(stateText);
+  } catch {
+    return { reasoning: {}, content: {}, packageVersion: null };
+  }
+
+  const physicalCodexHome = await realpath(codexHome);
+  const reasoning = {};
+  const content = {};
+  for (const name of AGENT_NAMES) {
+    const path = join(physicalCodexHome, "agents", `${name}.toml`);
+    const tracked = state.files?.[name];
+    const current = await readRegularText(path);
+    if (!tracked || !current || resolve(tracked.path) !== resolve(path) || digest(current) !== tracked.hash) continue;
+    const effort = activeReasoning(current);
+    if (!effort) continue;
+    reasoning[name] = effort;
+    content[name] = current;
+  }
+  return { reasoning, content, packageVersion: state.packageVersion };
+}
+
+export async function runCli(argv, options = {}) {
+  const output = options.output ?? console.log;
+  if (!argv.length || argv.includes("--help") || argv.includes("-h")) {
+    output(usage());
+    return 0;
+  }
+
+  const parsed = parseReasoningOptions(argv);
+  if (parsed.error) {
+    output(`${parsed.error}\n\n${usage()}`);
+    return 1;
+  }
+
+  const installed = await installedReasoning(parsed.cleaned, options);
+  const selected = { ...DEFAULT_AGENT_REASONING };
+  if (versionAtLeast(installed.packageVersion, "2.1.0")) Object.assign(selected, installed.reasoning);
+  if (parsed.all) {
+    for (const name of AGENT_NAMES) selected[name] = parsed.all;
+  }
+  Object.assign(selected, parsed.overrides);
+  configureAgentReasoning(selected, installed.content);
+  return runCore(parsed.cleaned, options);
+}

package/lib/manifest.js

@@ -5,12 +5,13 @@ const packageJson = require("../package.json");
 
 export const VERSION = packageJson.version;
 
+// Explicit opt-in only. A normal install leaves the user's primary model unchanged.
 export const DEFAULTS = Object.freeze({
   model: "gpt-5.6-terra",
   model_reasoning_effort: "high"
 });
 
-const luna = `name = "luna"
+const legacyLunaV12 = `name = "luna"
 description = "Low-risk helper for repeated edits, searches, formatting, extraction, counting, and summaries."
 model = "gpt-5.6-luna"
 model_reasoning_effort = "high"
@@ -21,7 +22,7 @@ Escalate ambiguous, security-sensitive, or logic-heavy decisions to Terra.
 """
 `;
 
-const sol = `name = "sol"
+const legacySolWorkspaceWrite = `name = "sol"
 description = "High-capability specialist for security-sensitive or high-regression-risk work."
 model = "gpt-5.6-sol"
 model_reasoning_effort = "medium"
@@ -35,7 +36,18 @@ Do not expand the scope beyond the delegated task.
 """
 `;
 
-const skill = `---
+const legacySolReadOnly = `name = "sol"
+description = "Read-only reviewer for security-sensitive or high-regression-risk logic."
+model = "gpt-5.6-sol"
+model_reasoning_effort = "medium"
+sandbox_mode = "read-only"
+developer_instructions = """
+Review only. Focus on security, authentication, permissions, secrets, destructive actions, financial logic, SQL writes, concurrency, complex state, and regression risk.
+Report concrete findings to Terra; do not apply fixes.
+"""
+`;
+
+const legacySkillWorkspaceWrite = `---
 name: model-router
 description: Route Codex work between Terra, Luna, and Sol with the fewest required agents.
 ---
@@ -46,50 +58,196 @@ Use Sol for security, authentication, authorization, permissions, secrets, destr
 Do not spawn a subagent for a simple question. Use the minimum number of agents and run Luna with Sol only when both independent tasks are required.
 `;
 
-export const TEMPLATES = Object.freeze({
-  luna: Object.freeze({ relative: ["agents", "luna.toml"], content: luna }),
-  sol: Object.freeze({ relative: ["agents", "sol.toml"], content: sol }),
-  skill: Object.freeze({ content: skill })
-});
+const legacySkillReadOnly = `---
+name: model-router
+description: Route Codex work between Terra, Luna, and Sol with the fewest required agents.
+---
 
-const legacySolReadOnly = `name = "sol"
-description = "Read-only reviewer for security-sensitive or high-regression-risk logic."
+Terra handles ordinary questions, coding, debugging, fixes, testing, and implementation. Never create a Terra subagent.
+Use Luna only for deterministic low-risk repeated edits, bulk patterns, read-heavy searches, formatting, counting, extraction, or summaries; prefer Luna when the same clear operation repeats at least three times.
+Use Sol only as a read-only reviewer for security, authentication, authorization, permissions, secrets, destructive actions, financial logic, SQL writes, concurrency, complex state changes, high-regression-risk logic, or an explicit review. Terra applies fixes.
+Do not spawn a subagent for a simple question. Use the minimum number of agents and run Luna with Sol only when both independent tasks are required.
+`;
+
+const terra = `name = "terra"
+description = "Investigates, plans, verifies, debugs, and replans nontrivial code changes."
+model = "gpt-5.6-terra"
+model_reasoning_effort = "high"
+sandbox_mode = "read-only"
+developer_instructions = """
+Own focused investigation, compact implementation-ready planning, verification, debugging, and replanning.
+Use the implementation-planning skill only for nontrivial or uncertain changes.
+Never invent repository facts; preserve valid work and revise only affected parts.
+Verify both plan conformance and whether the plan plus implementation satisfy the user's requirement.
+Use Sol only when focused investigation and one materially revised plan still leave the core logic unresolved.
+Return only the artifact required by the current stage.
+"""
+`;
+
+const luna = `name = "luna"
+description = "Implements clear, bounded work from an approved plan."
+model = "gpt-5.6-luna"
+model_reasoning_effort = "xhigh"
+sandbox_mode = "workspace-write"
+developer_instructions = """
+Implement the current approved plan with the smallest coherent change.
+Preserve fixed behavior, contracts, scope, parameter flow, control flow, callers, and invariants.
+Use local choice only for equivalent implementation details.
+Return to Terra when the plan conflicts with current code, is stale, omits a required target or caller, or needs a new correctness-affecting decision.
+Report the plan version, changed files and symbols, deviations, logical checks, and remaining uncertainty.
+Do not self-approve.
+"""
+`;
+
+const sol = `name = "sol"
+description = "Last-resort advisor for core logic Terra cannot resolve."
 model = "gpt-5.6-sol"
 model_reasoning_effort = "medium"
 sandbox_mode = "read-only"
 developer_instructions = """
-Review only. Focus on security, authentication, permissions, secrets, destructive actions, financial logic, SQL writes, concurrency, complex state, and regression risk.
-Report concrete findings to Terra; do not apply fixes.
+Analyze only the unresolved logical conflict.
+Identify unsupported assumptions, the likely root cause, required invariants, viable correction directions, and remaining uncertainty.
+Do not perform routine planning, implementation, verification, or final review.
+Return findings to Terra; do not manage Luna.
 """
 `;
 
-const legacySkillReadOnly = `---
+const skill = `---
 name: model-router
-description: Route Codex work between Terra, Luna, and Sol with the fewest required agents.
+description: Adaptively route code planning and implementation while preserving the selected primary model and existing agents.
 ---
 
-Terra handles ordinary questions, coding, debugging, fixes, testing, and implementation. Never create a Terra subagent.
-Use Luna only for deterministic low-risk repeated edits, bulk patterns, read-heavy searches, formatting, counting, extraction, or summaries; prefer Luna when the same clear operation repeats at least three times.
-Use Sol only as a read-only reviewer for security, authentication, authorization, permissions, secrets, destructive actions, financial logic, SQL writes, concurrency, complex state changes, high-regression-risk logic, or an explicit review. Terra applies fixes.
-Do not spawn a subagent for a simple question. Use the minimum number of agents and run Luna with Sol only when both independent tasks are required.
+Preserve repository rules and existing specialized agents. Explicit user instructions win.
+The selected primary model handles conversation, clarification, follow-ups, final replies, and trivial work.
+For code changes: ask the user when expected behavior is unclear; use Terra to investigate, plan, verify, debug, and replan; use Luna for clear bounded implementation; use Sol only when Terra still cannot resolve core logic after focused investigation and one materially revised plan, or when the user explicitly requests Sol.
+Use the implementation-planning skill for nontrivial or uncertain changes.
+Luna may choose equivalent local details only; approved behavior, contracts, scope, parameter flow, control flow, and invariants remain fixed.
+Terra verifies both plan conformance and requirement correctness. Preserve verified work and revise only affected parts.
+Stop after three cycles without new evidence or a changed decision. Use the fewest agents needed.
+Within one agent thread append concise deltas; a new thread receives the latest self-contained snapshot.
+`;
+
+const planning = `---
+name: implementation-planning
+description: Create or revise a compact implementation-ready plan for nontrivial code changes involving multiple symbols, contracts, parameters, callers, control flow, or uncertain targets.
+---
+
+Inspect only enough code to confirm correctness-critical facts. Mark information as CONFIRMED, PROPOSED, or UNKNOWN. Do not implement while an UNKNOWN can change behavior, targets, contracts, parameter flow, control flow, or compatibility.
+
+Produce one compact current snapshot using only applicable fields:
+
+- TASK, REQUIREMENT_VERSION, PLAN_VERSION
+- OBJECTIVE: observable result
+- TARGETS: exact files, symbols, and change type
+- SYMBOLS: exact new names and naming basis
+- CONTRACTS: current and proposed signatures, parameters, defaults, returns, and failure behavior
+- FLOW: source -> caller -> parameter -> transformation -> use -> destination
+- LOGIC: ordered steps and branches
+- CALLERS: affected callers and argument changes
+- INVARIANTS: behavior that must remain true
+- FIXED: decisions Luna cannot change
+- LOCAL_CHOICE: safe implementation freedom
+- RETURN_REQUIRED: conditions requiring Terra
+- DONE_WHEN: acceptance conditions
+
+Omit irrelevant fields and vague instructions. Preserve verified work, revise only affected sections, and identify superseded decisions. Create a new snapshot after three deltas or any material contract or logic change.
+
+Verification answers separately: did implementation match the plan, and did the plan plus implementation satisfy the request? Use PASS, IMPLEMENTATION_FIX, PLAN_REVISION, EVIDENCE_GAP, or REQUIREMENT_CLARIFICATION.
 `;
 
-export const LEGACY_TEMPLATES = Object.freeze({
-  luna: Object.freeze([]),
-  sol: Object.freeze([legacySolReadOnly]),
-  skill: Object.freeze([legacySkillReadOnly])
+export const REASONING_EFFORTS = Object.freeze([
+  "none",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+  "max"
+]);
+
+export const DEFAULT_AGENT_REASONING = Object.freeze({
+  terra: "high",
+  luna: "xhigh",
+  sol: "medium"
 });
 
-export const AGENT_EXPECTATIONS = Object.freeze({
-  luna: Object.freeze({
+export const AGENT_NAMES = Object.freeze(["terra", "luna", "sol"]);
+
+const AGENT_BASE_TEMPLATES = Object.freeze({ terra, luna, sol });
+
+function withReasoning(content, reasoning) {
+  const pattern = /^model_reasoning_effort = "[^"]+"$/m;
+  if (!pattern.test(content)) throw new Error("agent template is missing model_reasoning_effort");
+  return content.replace(pattern, `model_reasoning_effort = "${reasoning}"`);
+}
+
+export const TEMPLATES = {
+  terra: { relative: Object.freeze(["agents", "terra.toml"]), content: terra },
+  luna: { relative: Object.freeze(["agents", "luna.toml"]), content: luna },
+  sol: { relative: Object.freeze(["agents", "sol.toml"]), content: sol },
+  skill: { relative: Object.freeze(["model-router", "SKILL.md"]), content: skill },
+  planning: { relative: Object.freeze(["implementation-planning", "SKILL.md"]), content: planning }
+};
+
+export const MANAGED_FILE_NAMES = Object.freeze(["terra", "luna", "sol", "skill", "planning"]);
+
+export const LEGACY_TEMPLATES = {
+  terra: [],
+  luna: [legacyLunaV12, withReasoning(luna, "max")],
+  sol: [legacySolWorkspaceWrite, legacySolReadOnly],
+  skill: [legacySkillWorkspaceWrite, legacySkillReadOnly],
+  planning: []
+};
+
+export const AGENT_EXPECTATIONS = {
+  terra: {
+    name: "terra",
+    model: "gpt-5.6-terra",
+    model_reasoning_effort: "high",
+    sandbox_mode: "read-only"
+  },
+  luna: {
     name: "luna",
     model: "gpt-5.6-luna",
-    model_reasoning_effort: "high"
-  }),
-  sol: Object.freeze({
+    model_reasoning_effort: "xhigh",
+    sandbox_mode: "workspace-write"
+  },
+  sol: {
     name: "sol",
     model: "gpt-5.6-sol",
     model_reasoning_effort: "medium",
-    sandbox_mode: "workspace-write"
+    sandbox_mode: "read-only"
+  }
+};
+
+export function configureAgentReasoning(overrides = {}, migrateFrom = {}) {
+  const selected = { ...DEFAULT_AGENT_REASONING, ...overrides };
+  for (const [name, reasoning] of Object.entries(selected)) {
+    if (!AGENT_NAMES.includes(name)) throw new Error(`unknown agent: ${name}`);
+    if (!REASONING_EFFORTS.includes(reasoning)) {
+      throw new Error(`unsupported reasoning effort for ${name}: ${reasoning}`);
+    }
+  }
+
+  for (const name of AGENT_NAMES) {
+    const previous = migrateFrom[name];
+    if (typeof previous === "string" && !LEGACY_TEMPLATES[name].includes(previous)) {
+      LEGACY_TEMPLATES[name].push(previous);
+    }
+    TEMPLATES[name].content = withReasoning(AGENT_BASE_TEMPLATES[name], selected[name]);
+    AGENT_EXPECTATIONS[name].model_reasoning_effort = selected[name];
+  }
+  return Object.freeze({ ...selected });
+}
+
+configureAgentReasoning();
+
+export const SKILL_EXPECTATIONS = Object.freeze({
+  skill: Object.freeze({
+    name: "model-router",
+    required: Object.freeze(["primary model", "Terra", "Luna", "Sol", "three cycles"])
+  }),
+  planning: Object.freeze({
+    name: "implementation-planning",
+    required: Object.freeze(["CONFIRMED", "PROPOSED", "UNKNOWN", "FIXED", "LOCAL_CHOICE", "RETURN_REQUIRED", "PLAN_REVISION"])
   })
 });

package/lib/router-core.js

@@ -17,15 +17,18 @@ import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { applyEdits, insertionEdit, removalEdit, scanToml } from "./toml.js";
 import {
   AGENT_EXPECTATIONS,
+  AGENT_NAMES,
   DEFAULTS,
   LEGACY_TEMPLATES,
+  MANAGED_FILE_NAMES,
+  SKILL_EXPECTATIONS,
   TEMPLATES,
   VERSION
 } from "./manifest.js";
 
 export { VERSION };
 
-const STATE_VERSION = 3;
+const STATE_VERSION = 4;
 const LOCK_FILE = "model-router.lock";
 const JOURNAL_FILE = "model-router-transaction.json";
 const TRANSACTION_DIR = "model-router-transaction-data";
@@ -213,9 +216,11 @@ function expectedPaths({ cwd, home, global, env }) {
     config: join(codexHome, "config.toml"),
     state: join(codexHome, "model-router-state.json"),
     backup: join(codexHome, "config.toml.codex-model-router.bak"),
+    terra: join(codexHome, ...TEMPLATES.terra.relative),
     luna: join(codexHome, ...TEMPLATES.luna.relative),
     sol: join(codexHome, ...TEMPLATES.sol.relative),
-    skill: join(skillsHome, "model-router", "SKILL.md"),
+    skill: join(skillsHome, ...TEMPLATES.skill.relative),
+    planning: join(skillsHome, ...TEMPLATES.planning.relative),
     lock: join(codexHome, LOCK_FILE),
     journal: join(codexHome, JOURNAL_FILE),
     transactionData: join(codexHome, TRANSACTION_DIR)
@@ -239,6 +244,7 @@ async function validateLocationSafety(location) {
     location.config,
     location.state,
     location.backup,
+    location.terra,
     location.luna,
     location.sol,
     location.lock,
@@ -248,7 +254,7 @@ async function validateLocationSafety(location) {
   for (const target of codexTargets) {
     await assertNoIndirection(target, location.codexHome, codexAnchor, target);
   }
-  const skillsTargets = [location.skillsRoot, location.skillsHome, location.skill];
+  const skillsTargets = [location.skillsRoot, location.skillsHome, location.skill, location.planning];
   for (const target of skillsTargets) {
     await assertNoIndirection(target, location.skillsRoot, skillsAnchor, target);
   }
@@ -295,7 +301,7 @@ function normalizeLegacyState(raw, location) {
       source: item.previous == null ? "inserted" : "replaced"
     };
   }
-  for (const name of ["luna", "sol", "skill"]) {
+  for (const name of MANAGED_FILE_NAMES) {
     const item = raw.files[name];
     if (!item) continue;
     assertExactPath(item.path, location[name], name);
@@ -312,7 +318,7 @@ function validateState(raw, location) {
   if (!raw || typeof raw !== "object") throw new Error("state is not an object");
   let state;
   if (!raw.version) state = normalizeLegacyState(raw, location);
-  else if (raw.version === 2 || raw.version === STATE_VERSION) state = structuredClone(raw);
+  else if ([2, 3, STATE_VERSION].includes(raw.version)) state = structuredClone(raw);
   else throw new Error(`unsupported state version: ${raw.version}`);
 
   state.version = STATE_VERSION;
@@ -410,10 +416,12 @@ function stateJson(state) {
 async function missingDirectories(location) {
   const candidates = [
     location.codexHome,
+    dirname(location.terra),
     dirname(location.luna),
     location.skillsRoot,
     location.skillsHome,
-    dirname(location.skill)
+    dirname(location.skill),
+    dirname(location.planning)
   ];
   const unique = [...new Set(candidates.map((value) => resolve(value)))].sort((a, b) => a.length - b.length);
   const missing = [];
@@ -429,6 +437,29 @@ function patchInstallConfig(original, state, setDefault) {
   const additions = [];
   const nextValues = structuredClone(state.config.values || {});
 
+  if (!setDefault) {
+    for (const [key, item] of Object.entries(nextValues)) {
+      const assignment = scan.targets.get(key);
+      if (!assignment) {
+        delete nextValues[key];
+        continue;
+      }
+      if (assignment.parsedValue.kind !== "string") {
+        throw new Error(`${key} must be a TOML string`);
+      }
+      if (semanticValue(assignment) === item.installed) {
+        if (item.previousRaw === null) edits.push(removalEdit(assignment));
+        else edits.push({ start: assignment.valueStart, end: assignment.valueEnd, text: item.previousRaw });
+      }
+      delete nextValues[key];
+    }
+    return {
+      content: edits.length ? applyEdits(original, edits) : original,
+      values: nextValues,
+      changed: edits.length > 0
+    };
+  }
+
   for (const [key, installed] of Object.entries(DEFAULTS)) {
     const assignment = scan.targets.get(key);
     const tracked = nextValues[key];
@@ -441,7 +472,6 @@ function patchInstallConfig(original, state, setDefault) {
       nextValues[key] = tracked || { installed, previousRaw: null, source: "inserted" };
       continue;
     }
-    if (!setDefault) continue;
     if (current === installed) continue;
     edits.push({ start: assignment.valueStart, end: assignment.valueEnd, text: quoteToml(installed) });
     nextValues[key] = tracked || {
@@ -509,26 +539,43 @@ async function planInstall(scope, flags) {
   state.config.values = patched.values;
 
   if (patched.changed) {
-    if (!state.backup && config.exists) {
-      const backup = await readText(location.backup);
-      if (backup.exists) {
-        failPlan(plan, `untracked backup already exists: ${location.backup}`);
-        return plan;
+    const empty = patched.content.replace(/^\uFEFF/, "").trim() === "";
+    if (!flags.setDefault && state.config.createdFile && empty) {
+      addDelete(plan, location.config, "config.toml");
+      state.config.createdFile = false;
+    } else {
+      if (flags.setDefault && !state.backup && config.exists) {
+        const backup = await readText(location.backup);
+        if (backup.exists) {
+          failPlan(plan, `untracked backup already exists: ${location.backup}`);
+          return plan;
+        }
+        state.backup = { path: location.backup, hash: digest(Buffer.from(original, "utf8")) };
+        addWrite(plan, location.backup, original, "create", "config backup");
       }
-      state.backup = { path: location.backup, hash: digest(Buffer.from(original, "utf8")) };
-      addWrite(plan, location.backup, original, "create", "config backup");
+      addWrite(plan, location.config, patched.content, config.exists ? "update" : "create", "config.toml");
     }
-    addWrite(plan, location.config, patched.content, config.exists ? "update" : "create", "config.toml");
   } else {
     addMessage(
       plan,
       "preserve",
       "config.toml",
-      flags.setDefault ? "already matches or contains protected values" : "existing defaults preserved"
+      flags.setDefault ? "already matches or contains protected values" : "primary model preserved"
     );
   }
 
-  for (const name of ["luna", "sol", "skill"]) {
+  if (!flags.setDefault && Object.keys(state.config.values).length === 0 && state.backup) {
+    const backup = await readText(location.backup);
+    if (!backup.exists) addMessage(plan, "skip", "config backup", "already missing");
+    else if (digest(Buffer.from(backup.text, "utf8")) === state.backup.hash) {
+      addDelete(plan, location.backup, "config backup");
+    } else {
+      addMessage(plan, "preserve", "config backup", "user-modified");
+    }
+    state.backup = null;
+  }
+
+  for (const name of MANAGED_FILE_NAMES) {
     const current = await readText(location[name]);
     const tracked = state.files[name];
     const template = TEMPLATES[name].content;
@@ -599,7 +646,7 @@ async function planUninstall(scope) {
   }
   state.config.values = {};
 
-  for (const name of ["luna", "sol", "skill"]) {
+  for (const name of MANAGED_FILE_NAMES) {
     const tracked = state.files[name];
     if (!tracked) continue;
     const current = await readText(location[name]);
@@ -1015,16 +1062,15 @@ function getString(assignments, key) {
   return assignment?.parsedValue?.kind === "string" ? assignment.parsedValue.value : null;
 }
 
-function validateSkill(content) {
+function validateSkill(content, expectation) {
   const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/);
   if (!match) return "invalid front matter";
   const front = match[1];
   const body = match[2];
-  if (!/^name:\s*model-router\s*$/m.test(front)) return "incorrect skill name";
+  if (!front.split(/\r?\n/).some((line) => line.trim() === `name: ${expectation.name}`)) return "incorrect skill name";
   if (!/^description:\s*\S.+$/m.test(front)) return "missing skill description";
-  const requirements = [/Terra/i, /Luna/i, /Sol/i, /workspace-write/i, /simple question/i, /minimum number|fewest/i];
-  if (requirements.some((pattern) => !pattern.test(body))) return "missing required routing rule";
-  return null;
+  const missing = expectation.required.find((term) => !body.toLowerCase().includes(term.toLowerCase()));
+  return missing ? `missing required rule: ${missing}` : null;
 }
 
 function doctorStatus(messages, status, label, detail) {
@@ -1088,19 +1134,22 @@ async function doctor(scope) {
   doctorStatus(messages, "healthy", "state", `schema v${state.version}`);
 
   const config = await readText(location.config);
-  if (!config.exists) {
+  const managedConfigKeys = Object.keys(state.config.values || {});
+  if (!managedConfigKeys.length) {
+    doctorStatus(messages, "healthy", "config.toml", config.exists ? "primary model preserved" : "free mode");
+  } else if (!config.exists) {
     healthy = doctorStatus(messages, "missing", "config.toml") && healthy;
   } else {
     try {
       const scan = scanToml(config.text);
-      for (const [key, expected] of Object.entries(DEFAULTS)) {
+      for (const key of managedConfigKeys) {
+        const expected = DEFAULTS[key];
         const assignment = scan.targets.get(key);
         if (!assignment) healthy = doctorStatus(messages, "missing", key) && healthy;
         else if (assignment.parsedValue.kind !== "string") {
           healthy = doctorStatus(messages, "invalid", key, "must be a TOML string") && healthy;
         } else if (assignment.parsedValue.value !== expected) {
-          const status = state.config.values[key] ? "user-modified" : "user-override";
-          healthy = doctorStatus(messages, status, key, assignment.parsedValue.value ?? assignment.rawValue) && healthy;
+          healthy = doctorStatus(messages, "user-modified", key, assignment.parsedValue.value ?? assignment.rawValue) && healthy;
         } else {
           doctorStatus(messages, "healthy", key, expected);
         }
@@ -1110,7 +1159,7 @@ async function doctor(scope) {
     }
   }
 
-  for (const name of ["luna", "sol"]) {
+  for (const name of AGENT_NAMES) {
     const current = await readText(location[name]);
     if (!current.exists) {
       healthy = doctorStatus(messages, "missing", name) && healthy;
@@ -1133,17 +1182,19 @@ async function doctor(scope) {
     }
   }
 
-  const skill = await readText(location.skill);
-  if (!skill.exists) {
-    healthy = doctorStatus(messages, "missing", "skill") && healthy;
-  } else {
-    const invalid = validateSkill(skill.text);
-    if (state.files.skill && digest(Buffer.from(skill.text, "utf8")) !== state.files.skill.hash) {
-      healthy = doctorStatus(messages, "user-modified", "skill", invalid || "managed file hash changed") && healthy;
+  for (const [name, expectation] of Object.entries(SKILL_EXPECTATIONS)) {
+    const current = await readText(location[name]);
+    if (!current.exists) {
+      healthy = doctorStatus(messages, "missing", name) && healthy;
+      continue;
+    }
+    const invalid = validateSkill(current.text, expectation);
+    if (state.files[name] && digest(Buffer.from(current.text, "utf8")) !== state.files[name].hash) {
+      healthy = doctorStatus(messages, "user-modified", name, invalid || "managed file hash changed") && healthy;
     } else if (invalid) {
-      healthy = doctorStatus(messages, "invalid", "skill", invalid) && healthy;
+      healthy = doctorStatus(messages, "invalid", name, invalid) && healthy;
     } else {
-      doctorStatus(messages, "healthy", "skill");
+      doctorStatus(messages, "healthy", name);
     }
   }
 

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "codex-model-router",
-  "version": "1.2.0",
-  "description": "Safely install Codex subagent routing for Terra, Luna, and Sol.",
+  "version": "2.1.0",
+  "description": "Safely install adaptive free-mode Codex routing for Terra, Luna, and Sol.",
   "type": "module",
   "bin": {
     "codex-model-router": "./bin/codex-model-router.js"
   },
   "scripts": {
-    "check": "node --check bin/codex-model-router.js && node --check lib/manifest.js && node --check lib/router.js && node --check lib/router-core.js && node --check lib/toml.js && node --check scripts/release-metadata.js && node --check scripts/verify-published.js",
+    "check": "node --check bin/codex-model-router.js && node --check lib/agent-reasoning-cli.js && node --check lib/manifest.js && node --check lib/router.js && node --check lib/router-core.js && node --check lib/toml.js && node --check scripts/release-metadata.js && node --check scripts/verify-published.js",
     "test": "node --test",
     "test:package": "node scripts/package-smoke.js"
   },