sprag-cli 3.66.0 → 3.68.0

package/bin/cli.js

@@ -32,6 +32,7 @@ import { dirname, isAbsolute, join } from 'node:path';
 
 import {
   readStdinJson,
+  readStdinRaw,
   extractCaps,
   extractContextUsage,
   extractEffort,
@@ -87,12 +88,78 @@ function tableColor() {
 }
 
 // Subcommands this build knows how to run. Used only by the guard below.
+/**
+ * `--segments a,b,c` as a list, or null for the default order. One parser for
+ * the demo, the populated line and the no-session line, so `--segments harness`
+ * means the same chip set on each of them.
+ */
+function segmentsFromArgs() {
+  const raw = getArg('--segments');
+  return raw ? raw.split(',').map((s) => s.trim()).filter(Boolean) : null;
+}
+
 const KNOWN_SUBCOMMANDS = new Set([
   'last', 'brief', 'history', 'handoff', 'install', 'uninstall', 'mode', 'korean', 'cohesion',
   'doc2md', 'delegate', 'harness', 'route-scan', 'compact-window', 'update-check', 'upgrade',
-  'seed', 'litellm-budget', 'profile-map', 'feedback', 'saved',
+  'seed', 'litellm-budget', 'profile-map', 'feedback', 'saved', 'cowork',
 ]);
 
+// Flags each entry path reads, collected from the hasFlag/getArg/numArg calls in
+// this file, src/statusline-mode.js, src/hook.cjs and the install/uninstall
+// commands. `value` flags take an argument (`--days 3` or `--days=3`); `bool`
+// flags do not. --agent is not listed: selectAgent() removes it before `args`
+// exists. Only the default path (report, statusline, hook management) and
+// install/uninstall are checked; every other subcommand parses its own arguments.
+// Keep these in step with the code that reads the flag: a flag read but not
+// listed is rejected, and a flag listed but never read is silently ignored again.
+const FLAG_SPECS = {
+  report: {
+    value: ['--format', '-f', '--project', '-p', '--days', '-d', '--hours', '--demo',
+      '--demo-cycle-sec', '--segments', '--exclude-session', '--threshold'],
+    bool: ['--statusline', '--verbose', '--no-verbose', '--compact', '--no-color', '--icon',
+      '--no-icon', '--text', '--narrow', '--no-timer', '--single-line', '--demo-label',
+      '--version', '-v', '--help', '-h', '--hook', '--hook-run', '--install-hook', '--uninstall-hook'],
+  },
+  install: { value: [], bool: ['--force', '--manual', '--yes', '--no-input', '--help', '-h'] },
+  // --yes and --no-input are the explicit spelling of "do not ask", and
+  // uninstall never asks, so they are accepted as no-ops.
+  uninstall: { value: [], bool: ['--purge', '--yes', '--no-input', '--help', '-h'] },
+};
+
+/** Which spec applies to this invocation, or null for a subcommand that parses its own arguments. */
+function flagSpecFor(first) {
+  if (!first || first.startsWith('-')) return FLAG_SPECS.report;
+  return FLAG_SPECS[first] || null;
+}
+
+/**
+ * The flags in `argv` that `spec` does not list. A value flag swallows the next
+ * token the way getArg() does, so `--exclude-session --x` reads `--x` as a path,
+ * not as a flag, and both `--days 3` and `--days=3` are understood. A bool flag
+ * written `--no-color=1` is reported too: hasFlag() compares whole tokens, so
+ * that form was never honoured. Everything after a bare `--` is not a flag.
+ *
+ * @returns {string[]} the offending tokens as typed
+ */
+function findUnknownFlags(argv, spec) {
+  const value = new Set(spec.value);
+  const bool = new Set(spec.bool);
+  const unknown = [];
+  for (let i = 0; i < argv.length; i++) {
+    const tok = argv[i];
+    if (tok === '--') break;
+    if (tok.length < 2 || !tok.startsWith('-')) continue;
+    const eq = tok.indexOf('=');
+    const name = eq === -1 ? tok : tok.slice(0, eq);
+    if (value.has(name)) {
+      if (eq === -1) i++;
+    } else if (!bool.has(name) || eq !== -1) {
+      unknown.push(tok);
+    }
+  }
+  return unknown;
+}
+
 const USAGE = `sprag — Claude Code and Codex agent harness
 
 Usage:
@@ -116,6 +183,7 @@ Usage:
   sprag uninstall --agent codex   remove the global Codex integration
       --agent claude|codex (default: claude; accepted before or after subcommands)
   sprag route-scan         detect recurring easy work → delegation candidates
+  sprag delegate agents [on|off]   tool-restricted delegation agents (no MCP tools)
   sprag profile-map        show/refresh the gateway model map (LiteLLM /model/info)
   sprag install            set up everything (presets, and Codex when present) without asking
   sprag install --manual   confirm each optional step
@@ -127,6 +195,7 @@ Usage:
   sprag handoff            write a session handoff file
   sprag mode [keywords]    statusline preferences (icon/text, en/ko, window, ttl)
   sprag seed               register the bundled starter rules, one answer at a time
+  sprag cowork [sync|on|off|exclude <dir>|include <dir>]   copy the ratchet rules into Cowork tab folders
   sprag korean on|off|status     Korean writing guidance + write-time check
   sprag cohesion on|off|status   English sentence-connection guidance
   sprag doc2md on|off|<file>     convert documents to Markdown before the model reads them
@@ -169,6 +238,34 @@ async function main() {
     return;
   }
 
+  // Refuse what this build cannot honour, before anything is scanned or written.
+  // An unknown first word used to fall into the 30-day report, and an unknown
+  // flag was dropped without a word: `sprag install --dry-run` ran the real
+  // install and rewrote settings.json. Exit 2 is the usage-error code.
+  if (args[0] && !args[0].startsWith('-') && !KNOWN_SUBCOMMANDS.has(args[0])) {
+    console.error(`Unknown command: ${args[0]}`);
+    console.error('Run `sprag --help` for the list of commands.');
+    process.exitCode = 2;
+    return;
+  }
+  const flagSpec = flagSpecFor(args[0]);
+  const unknownFlags = flagSpec ? findUnknownFlags(args, flagSpec) : [];
+  if (unknownFlags.length > 0) {
+    // The statusline and the PostToolUse hook run from a fixed command in
+    // settings.json, and a typo or a flag from a newer release there must not
+    // blank the line or fail the hook. Warn and carry on; every other caller is
+    // a person at a prompt who is better told.
+    const lenient = hasFlag('--statusline') || getArg('--format') === 'statusline' || hasFlag('--hook-run');
+    if (lenient) {
+      for (const f of unknownFlags) console.error(`Warning: Unknown option: ${f} (ignored)`);
+    } else {
+      for (const f of unknownFlags) console.error(`Unknown option: ${f}`);
+      console.error('Run `sprag --help` for usage.');
+      process.exitCode = 2;
+      return;
+    }
+  }
+
   // Subcommand: last — print the most recent warning + how to handle it.
   // Designed for the auto-trigger skill so the user immediately sees
   // "what just fired and how to fix it" without having to read the whole
@@ -290,6 +387,11 @@ async function main() {
     return (await import('../src/commands/seed.js')).run({ args, hasFlag });
   }
 
+  // Subcommand: cowork — ratchet copies for the Claude app's Cowork tab.
+  if (args[0] === 'cowork') {
+    return (await import('../src/commands/cowork.js')).run({ args, hasFlag });
+  }
+
   // Subcommand: saved — stopwatch reset for the lifetime "saved" counters.
   //   sprag saved | saved reset [routing|doc2md|all] | saved undo
   if (args[0] === 'saved') {
@@ -339,56 +441,9 @@ async function main() {
   }
 
   // Subcommand: litellm-budget · LiteLLM 게이트웨이 키의 max_budget/spend 조회.
-  //   sprag litellm-budget            # 캐시된 예산을 게이지·금액으로 출력
-  //   sprag litellm-budget --json     # 캐시 원본 JSON 출력
-  //   sprag litellm-budget --refresh  # 지금 프록시에 물어봄 (detached 자식이 사용)
+  //   sprag litellm-budget [--json | --refresh]
   if (args[0] === 'litellm-budget') {
-    const { gatewayBase, readBudgetState, refreshBudgetState, formatBudgetReport, resolveKey } =
-      await import('../src/litellm-budget.js');
-    const quiet = hasFlag('--quiet');
-    if (hasFlag('--refresh')) {
-      try {
-        // apiKeyHelper 가 토큰 수명(TTL)을 소유합니다. 헬퍼를 한 번만 불러 그
-        // 키를 예산 갱신과 게이트웨이 모델맵 갱신 양쪽에 재사용합니다. 갱신
-        // 경로마다 resolveKey() 를 다시 부르면 사본을 만드는 셈이 되고, 헬퍼
-        // 호출 횟수도 그만큼 늘어납니다.
-        const key = resolveKey();
-        let next = null;
-        if (key) {
-          next = await refreshBudgetState(process.env, fetch, key);
-          const { maybeRefreshGatewayModelMap } = await import('../src/litellm-models.js');
-          await maybeRefreshGatewayModelMap({ base: gatewayBase(), key });
-        }
-        if (!quiet) console.log(JSON.stringify(next, null, 2));
-      } catch (e) {
-        debug('litellm-budget:refresh', e);
-        if (!quiet) console.error(`litellm-budget refresh failed: ${e.message}`);
-        process.exitCode = 1;
-      }
-      return;
-    }
-    // 읽기 경로는 캐시만 보므로 키를 요구하지 않습니다 (apiKeyHelper 환경 배려).
-    const base = gatewayBase();
-    if (!base) {
-      console.log('게이트웨이가 감지되지 않았습니다 (ANTHROPIC_BASE_URL 필요).');
-      return;
-    }
-    const state = readBudgetState();
-    if (hasFlag('--json')) {
-      console.log(JSON.stringify(state, null, 2));
-      return;
-    }
-    if (state.base !== base || state.maxBudget === undefined) {
-      console.log('예산 캐시가 비어 있습니다. `sprag litellm-budget --refresh` 로 먼저 조회하십시오.');
-      return;
-    }
-    // Same resolver the statusline uses: this report draws a gauge too, and a
-    // glyph the terminal's font lacks garbles here exactly as it does there.
-    const { resolveLabelMode } = await import('../src/statusline-mode.js');
-    const { statuslineDefaults } = await import('../src/config.js');
-    const { mode: labelMode } = resolveLabelMode({ hasFlag, cfg: statuslineDefaults() });
-    for (const line of formatBudgetReport(state, new Date(), labelMode)) console.log(line);
-    return;
+    return (await import('../src/commands/litellm-budget.js')).run({ hasFlag });
   }
 
   // Subcommand: profile-map · LiteLLM 게이트웨이의 프로파일 ID → 모델 별칭
@@ -477,10 +532,7 @@ async function main() {
       : (hasFlag('--no-verbose') || hasFlag('--compact') ? false : cfg.verbose);
     const showTimer = hasFlag('--no-timer') ? false : cfg.timer;
     const colorOk = !hasFlag('--no-color') && !process.env.NO_COLOR && cfg.color;
-    const segmentsArg = getArg('--segments');
-    const segments = segmentsArg
-      ? segmentsArg.split(',').map((s) => s.trim()).filter(Boolean)
-      : null;
+    const segments = segmentsFromArgs();
     const out = formatReport(data, {
       color: colorOk,
       verbose: isVerbose,
@@ -584,8 +636,8 @@ async function main() {
       const { withBaseStatusline } = await import('../src/statusline-base.js');
       console.log(withBaseStatusline(formatNoSession(
         { caps, model, effort, windowLabel, version: PKG_VERSION, update: readUpdateChip(PKG_VERSION) },
-        { color: colorOk, mode: labelMode },
-      )));
+        { color: colorOk, mode: labelMode, segments: segmentsFromArgs() },
+      ), { input: readStdinRaw() }));
       return;
     }
     // JSON mode stays JSON. A caller that asked for machine-readable output
@@ -761,12 +813,13 @@ async function main() {
   // 이미 파싱한 세션을 재사용하고, 사용자가 창을 줄여 둔 경우(mode 1d 등)에만
   // 월초까지 다시 파싱한다. 파싱 결과는 세션 캐시가 받아 주므로 싸다.
   let monthSpendInfo = null;
+  let monthSessions = null;
   if (isStatusline) {
     try {
       const { monthSpend, monthStartMs } = await import('../src/month-spend.js');
       const since = monthStartMs();
       const daysNeeded = (Date.now() - since) / 86400000;
-      const monthSessions = days >= daysNeeded
+      monthSessions = days >= daysNeeded
         ? sessions
         : await parseAllSessions({ days: Math.max(1, Math.ceil(daysNeeded)), projectFilter, sinceMs: since });
       // 월 경계에 걸친 세션은 월초 이후 요청만 남긴다. 그러지 않으면 1일 자정을
@@ -777,6 +830,22 @@ async function main() {
     }
   }
 
+  // 모델별 사용 비중: `sprag saved` 와 같은 기간(라우팅 초기화 기록, 없으면 월초)의
+  // 비용 기준 분포. 이미 파싱한 월간 세션을 재사용한다. 실패하면 칩만 빠진다.
+  let modelShare = null;
+  if (isStatusline) {
+    try {
+      const { statuslineDefaults } = await import('../src/config.js');
+      if (statuslineDefaults().modelShare) {
+        const { loadModelShare } = await import('../src/model-share.js');
+        const { userDataDir } = await import('../src/paths.js');
+        modelShare = await loadModelShare({ dir: userDataDir(), env: process.env, projectFilter, monthSessions: monthSessions || undefined });
+      }
+    } catch (e) {
+      debug('model-share', e);
+    }
+  }
+
   // Rolling week/month/lifetime totals from the delegation ledger — the
   // statusline's headline line. Falls back to null (chip hidden) on any error.
   // A lookup, never a scan: the statusline re-renders every few seconds and a
@@ -873,6 +942,7 @@ async function main() {
     update: format === 'statusline' ? readUpdateChip(PKG_VERSION) : null,
     lastActivity,
     monthSpend: monthSpendInfo,
+    modelShare,
     spikeReport,
     contextWindow,
     ctxLive,
@@ -915,10 +985,7 @@ async function main() {
     const colorOk =
       !hasFlag('--no-color') && !process.env.NO_COLOR && cfg.color;
 
-    const segmentsArg = getArg('--segments');
-    const segments = segmentsArg
-      ? segmentsArg.split(',').map((s) => s.trim()).filter(Boolean)
-      : null;
+    const segments = segmentsFromArgs();
     output = formatReport(data, {
       color: colorOk,
       verbose: isVerbose,
@@ -937,7 +1004,8 @@ async function main() {
 
   if (format === 'statusline') {
     const { withBaseStatusline } = await import('../src/statusline-base.js');
-    output = withBaseStatusline(output);
+    // The payload was read above; the base gets the same text, not a second read.
+    output = withBaseStatusline(output, { input: readStdinRaw() });
   }
   console.log(output);
 }

package/docs/CODEX.ko.md

@@ -38,6 +38,38 @@ macOS zsh 환경에서는 설치가 tmux 설치 여부를 먼저 확인합니다
 `sprag panel auto off --agent codex`로 끈 설정은 재설치해도 유지합니다.
 패널 실행 여부는 `sprag panel doctor --agent codex`로 확인하십시오.
 
+## 명령 한눈에 보기
+
+명령의 기본 대상은 Claude Code입니다. `--agent codex`를 붙이면 Codex를 고릅니다.
+
+```sh
+npm i -g sprag-cli --ignore-scripts  # Claude Code를 건드리지 않는 Codex 전용 설치
+sprag install --agent codex
+sprag --agent codex --days 7
+sprag panel --agent codex  # 별도 터미널에서 실시간 패널 실행
+sprag --statusline --agent codex --text
+sprag doctor --agent codex  # 문제가 생겼을 때만
+sprag route-scan --agent codex
+sprag seed --agent codex
+```
+
+설치 후 Codex의 `/hooks`에서 새 훅을 검토하고 신뢰해야 실행됩니다. Codex가 요구하는
+절차입니다. Codex 기본 상태줄은 셸 명령을 실행하지 않으므로, Sprag는 터미널 상태줄과 패널을
+따로 제공합니다. 기능별 지원 여부는 `sprag capabilities --agent codex`로 확인하십시오.
+
+## Claude Code와 Codex 비교
+
+| 기능 | Claude Code | Codex |
+|---|---|---|
+| 세션 지침 | `CLAUDE.md`와 훅 | `AGENTS.md`와 기본 훅 |
+| 실시간 상태 | 기본 상태줄에 명령 등록 | 별도 패널 또는 tmux 구성 |
+| 규칙 후보 | Claude 기록과 모델 등급 프리셋 | Codex 기록과 호환 래칫 프리셋 |
+| 모델 위임 | Haiku·Sonnet 등급 규칙 | 공급자 모델 ID와 범위별 규칙 |
+| 위임 원장 | Claude 실행별 예상 차액 | LiteLLM 단가와 하위 실행별 예상 차액 |
+
+두 연동을 함께 설치할 수 있습니다. `--agent codex`를 붙이지 않으면 기존 Claude 동작을 유지합니다.
+README의 금액 수치는 Claude Code 세션 기록에서 나온 값이며 Codex 벤치마크가 아닙니다.
+
 ## 지원 기능
 
 | 기능 | Codex 동작 |

package/docs/CODEX.md

@@ -72,6 +72,40 @@ fails, the preference stays unchanged. Review new or changed definitions in
 `/hooks`; registration does not grant trust. Turning a feature off keeps the
 shared hooks needed by other features.
 
+## Command Quick Reference
+
+Commands default to Claude Code. Add `--agent codex` to select Codex.
+
+```sh
+npm i -g sprag-cli --ignore-scripts  # Codex-only install, leaves Claude Code alone
+sprag install --agent codex
+sprag --agent codex --days 7
+sprag panel --agent codex  # live companion in a separate terminal
+sprag --statusline --agent codex --text
+sprag doctor --agent codex  # troubleshooting only
+sprag route-scan --agent codex
+sprag seed --agent codex
+```
+
+Review and trust the new hooks in Codex's `/hooks` menu; Codex requires that
+step. The native Codex footer does not accept shell commands, so Sprag provides
+a terminal statusline and a panel instead. Run `sprag capabilities --agent codex`
+for the support matrix.
+
+## Claude Code And Codex Compared
+
+| Workflow | Claude Code | Codex |
+|---|---|---|
+| Session instructions | `CLAUDE.md` and hooks | `AGENTS.md` and native hooks |
+| Live telemetry | Native statusline command | Companion panel or tmux layout |
+| Rule candidates | Claude transcripts and tier presets | Codex rollouts and compatible ratchet presets |
+| Model routing | Haiku/Sonnet tier rules | Explicit provider model IDs and scoped rules |
+| Routing ledger | Claude run estimates | Attributed child estimates with LiteLLM prices |
+
+Both integrations coexist. Commands without `--agent codex` retain Claude behavior.
+The dollar figures in the README come from Claude Code sessions, not from a Codex
+benchmark.
+
 ## Supported Workflows
 
 | Feature | Codex behavior |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sprag-cli",
-  "version": "3.66.0",
-  "description": "Lower your Claude Code bill without changing how you work: simple tasks go to cheaper models, documents go in as compact Markdown, and the statusline shows spend and savings live. Works with Codex too.",
+  "version": "3.68.0",
+  "description": "Cut Claude Code and Codex token costs: cheaper-model routing, compact Markdown for documents, and a live statusline of spend and savings.",
   "type": "module",
   "bin": {
     "sprag": "bin/cli.js",
@@ -34,7 +34,7 @@
     "NOTICE"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "keywords": [
     "claude-code",
@@ -52,7 +52,14 @@
     "subagent",
     "prompt-caching",
     "haiku",
-    "cli"
+    "cli",
+    "token",
+    "tokens",
+    "cost",
+    "llm-cost",
+    "cost-optimization",
+    "openai-codex",
+    "pptx-to-markdown"
   ],
   "license": "Apache-2.0",
   "repository": {

package/presets/ratchet-rules.json

@@ -40,6 +40,13 @@
     {
       "ko": "지침이나 룰이 지켜지지 않아 같은 품질 문제가 재발하면 문구를 다시 쓰지 말 것 → 그 조항이 기계로 판정 가능한지부터 따지고(문자열 비교나 정규식으로 결정되면 판정 가능), 가능하면 쓰기 시점 훅이나 테스트 같은 차단 지점을 추가한다. 판단이 필요한 잔여 부분만 지침에 남기고 그 경계를 지침에 적는다. 실제 코퍼스에 돌려 오탐 건수를 센 뒤 좁히고, 회귀 테스트를 같은 커밋에 넣는다",
       "en": "When a guideline keeps being violated and the same quality defect recurs, do NOT reword the instruction → first ask whether the clause is machine-decidable (a string comparison or regex settles it), and if so add an enforcement point such as a write-time hook or a test. Leave only the judgement remainder in the prose and state that boundary there. Measure the false-positive count on a real corpus, narrow until it is acceptable, and land a regression test in the same commit"
+    },
+    {
+      "ko": "여러 파일에 걸친 구현을 맡으면 → 설계와 스펙 확정은 메인 모델이 하고 코드 작성은 서브에이전트에 위임한다(Claude는 `model: sonnet`, Codex는 명시적 매핑을 우선해 해석한 T1을 쓰며 haiku나 T2에는 구현을 맡기지 않는다). 위임 프롬프트에는 설계, 수정할 파일, 제약, 완료 기준, 테스트 명령, 예산, 권장 모델과 그 이유를 적어 다른 문맥 없이 실행할 수 있게 한다. 이미 읽은 파일의 약 50줄 이하 변경이나 의존 단계가 하나뿐인 짧은 구현, 그리고 위임 도구나 하위 모델을 쓸 수 없는 경우는 메인 모델이 직접 처리한다. 위임한 구현은 끝날 때까지 기다리고 같은 구현을 중복 실행하지 않으며, 돌아온 diff와 테스트 결과를 메인 모델이 직접 검증한 뒤에 완료로 보고한다",
+      "en": "When an implementation spans several files → the main model settles the design and specification, then delegates the code writing to a subagent (Claude: `model: sonnet`; Codex: its resolved T1, explicit mapping first; never haiku or T2 for implementation). Write the delegation prompt so it runs without other context: design, files to change, constraints, completion criteria, test commands, budget, and the recommended model with a one-line reason. Keep changes of roughly 50 lines or less in files already read, a single short dependency chain, or cases where the subagent tools or the lower model are unavailable on the main model. Wait for the delegated work instead of duplicating it, and verify the returned diff and the actual test results before reporting completion",
+      "agents": [
+        "claude"
+      ]
     }
   ]
 }

package/src/agents.js

@@ -8,6 +8,12 @@
  * part that actually saves tokens and it is universal, so `model: haiku` is the
  * default phrasing — the agent name is only added when the file is really
  * there, which keeps the tool-restricted preset in play for users who have it.
+ *
+ * A rule that names a tier alone (`sonnet`, `haiku`) resolves to that tier's
+ * delegation-only agent (`sonnet-worker`, `haiku-explore`, installed by
+ * delegation-agents.js) when its file exists. A phrase that names an agent
+ * always carries a general-purpose fallback, because Cowork reads no agents
+ * directory and a copied rule would otherwise name an agent that is not there.
  */
 
 import { existsSync } from 'node:fs';
@@ -20,9 +26,9 @@ const AGENT_MODEL = {
   'haiku-runner': 'haiku',
   'haiku-translate': 'haiku',
   'sonnet-worker': 'sonnet',
-  // A T1 rule names its target by tier alone (`agent: 'sonnet'`), with no
-  // preset agent behind it. Without these the phrase fell through to the
-  // haiku default, and a sonnet rule told the session to delegate to haiku.
+  // A T1 rule names its target by tier alone (`agent: 'sonnet'`). Without these
+  // the phrase fell through to the haiku default, and a sonnet rule told the
+  // session to delegate to haiku. resolveAgentName maps them to an agent file.
   sonnet: 'sonnet',
   haiku: 'haiku',
 };
@@ -43,9 +49,23 @@ export function agentExists(name, root = process.cwd()) {
     existsSync(join(claudeUserDir(), 'agents', `${name}.md`));
 }
 
+/** Agent a bare tier name stands for when that agent's file exists. */
+const TIER_AGENT = { sonnet: 'sonnet-worker', haiku: 'haiku-explore' };
+
+/**
+ * The agent a rule target really names on this machine, or null when none is
+ * installed. A name wins when its own file exists; a bare tier name falls back
+ * to its delegation-only agent.
+ */
+export function resolveAgentName(name, root = process.cwd()) {
+  if (agentExists(name, root)) return name;
+  const alt = TIER_AGENT[name];
+  return alt && agentExists(alt, root) ? alt : null;
+}
+
 /**
  * Korean phrase for a delegation target, e.g.
- *   agent present → `haiku-explore(model 인자 생략)`
+ *   agent present → `haiku-explore(model 인자 생략. …general-purpose에 model: haiku)`
  *   agent absent  → `model: haiku`
  *
  * A named agent carries its model in its own definition, and the Agent tool's
@@ -56,18 +76,20 @@ export function agentExists(name, root = process.cwd()) {
  * now says to leave the argument out.
  */
 export function agentPhrase(name, { model, root } = {}) {
-  const tier = model || AGENT_MODEL[name] || 'haiku';
-  return agentExists(name, root) ? `${name}(model 인자 생략)` : `model: ${tier}`;
+  const resolved = resolveAgentName(name, root);
+  if (!resolved) return `model: ${model || AGENT_MODEL[name] || 'haiku'}`;
+  const tier = AGENT_MODEL[resolved] || model || 'haiku';
+  return `${resolved}(model 인자 생략. 이 에이전트가 없거나 MCP 도구가 필요하면 general-purpose에 model: ${tier})`;
 }
 
 /**
  * English phrase, including the article, e.g.
- *   agent present → `the haiku-explore subagent (omit the model argument)`
+ *   agent present → `the haiku-explore subagent (omit the model argument; …)`
  *   agent absent  → `a model: haiku subagent`
  */
 export function agentPhraseEn(name, { model, root } = {}) {
-  const tier = model || AGENT_MODEL[name] || 'haiku';
-  return agentExists(name, root)
-    ? `the ${name} subagent (omit the model argument)`
-    : `a model: ${tier} subagent`;
+  const resolved = resolveAgentName(name, root);
+  if (!resolved) return `a model: ${model || AGENT_MODEL[name] || 'haiku'} subagent`;
+  const tier = AGENT_MODEL[resolved] || model || 'haiku';
+  return `the ${resolved} subagent (omit the model argument; if it is unavailable or MCP tools are needed, use general-purpose with model: ${tier})`;
 }

package/src/{codex-brief.js → codex/brief.js}

@@ -1,13 +1,13 @@
 import { createHash } from 'node:crypto';
 import { readFileSync, mkdirSync, readdirSync } from 'node:fs';
 import { join, resolve } from 'node:path';
-import { codexUserDir } from './agent.js';
-import { userDataDir } from './paths.js';
-import { writeViaTmp } from './state-file.js';
-import { readCodexSnapshot } from './codex-parser.js';
-import { loadCodexModelRules } from './codex-delegation.js';
-import { loadCodexLedger } from './codex-ledger.js';
-import { codexRulesInReview, codexSharedRuleHealth } from './codex-rule-health.js';
+import { codexUserDir } from '../agent.js';
+import { userDataDir } from '../paths.js';
+import { writeViaTmp } from '../state-file.js';
+import { readCodexSnapshot } from './parser.js';
+import { loadCodexModelRules } from './delegation.js';
+import { loadCodexLedger } from './ledger.js';
+import { codexRulesInReview, codexSharedRuleHealth } from './rule-health.js';
 
 const RESET_TOLERANCE_S = 300;
 const hash = (value) => createHash('sha256').update(value).digest('hex');

package/src/{codex-budget.js → codex/budget.js}

@@ -3,8 +3,8 @@ import { join } from 'node:path';
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { parse } from 'smol-toml';
-import { codexUserDir } from './agent.js';
-import { pickBudgetSource } from './litellm-budget.js';
+import { codexUserDir } from '../agent.js';
+import { pickBudgetSource } from '../litellm-budget.js';
 
 const run = promisify(execFile);
 

package/src/{codex-cache-policy.js → codex/cache-policy.js}

@@ -2,15 +2,15 @@ import { readFileSync, mkdirSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { createHash, randomUUID } from 'node:crypto';
 import { parse } from 'smol-toml';
-import { codexUserDir } from './agent.js';
-import { userDataDir } from './paths.js';
-import { writeViaTmp } from './state-file.js';
-import { codexBudgetProvider, codexProviderKey } from './codex-budget.js';
-import { codexCachePolicy } from './codex-cache.js';
-import { PRICE_MAX_AGE_MS, gatewayPrices } from './gateway-prices.js';
-import { OPENAI_LIST_PRICES, OPENAI_PRICES_CHECKED_AT } from './openai-prices.js';
-
-export { PRICE_MAX_AGE_MS, rate, deploymentPrice, gatewayPrices, codexRunCost } from './gateway-prices.js';
+import { codexUserDir } from '../agent.js';
+import { userDataDir } from '../paths.js';
+import { writeViaTmp } from '../state-file.js';
+import { codexBudgetProvider, codexProviderKey } from './budget.js';
+import { codexCachePolicy } from './cache.js';
+import { PRICE_MAX_AGE_MS, gatewayPrices } from '../gateway-prices.js';
+import { OPENAI_LIST_PRICES, OPENAI_PRICES_CHECKED_AT } from '../openai-prices.js';
+
+export { PRICE_MAX_AGE_MS, rate, deploymentPrice, gatewayPrices, codexRunCost } from '../gateway-prices.js';
 
 export const CACHE_POLICY_MAX_AGE_MS = 300000;
 const OPENAI_POLICY = 'https://developers.openai.com/api/docs/guides/prompt-caching#cache-lifetime';

package/src/{codex-delegation-diagnostics.js → codex/delegation-diagnostics.js}

@@ -2,8 +2,8 @@ import { execFileSync } from 'node:child_process';
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { parse } from 'smol-toml';
-import { codexUserDir, codexModelName } from './agent.js';
-import { codexDelegationStatus } from './codex-ledger.js';
+import { codexUserDir, codexModelName } from '../agent.js';
+import { codexDelegationStatus } from './ledger.js';
 
 /** Local introspection only. A CLI feature flag cannot prove a model received a tool. */
 export function codexDelegationDiagnostics({ home = codexUserDir(), model = codexModelName({ home }), sessionId, dir,

package/src/{codex-delegation.js → codex/delegation.js}

@@ -2,17 +2,17 @@ import { readFileSync, readdirSync, mkdirSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { parse } from 'smol-toml';
-import { userDataDir } from './paths.js';
-import { writeViaTmp } from './state-file.js';
-import { codexUserDir, codexProviderName } from './agent.js';
-import { categorize, ESCALATE_RE, EDIT_RE } from './route-scan.js';
-import { looksPasted } from './route-inject.js';
-import { newRouteId, recordCodexDelegation } from './codex-ledger.js';
-import { readCodexTailLines } from './codex-parser.js';
-import { loadConfig } from './config.js';
-import { loadSharedModelRules, sharedModelRulesForProject, sharedRuleBounds, SHARED_RULE_TIERS } from './shared-model-rules.js';
-import { codexPriceBook, readCodexPrices } from './codex-cache-policy.js';
-import { codexRunCost } from './gateway-prices.js';
+import { userDataDir } from '../paths.js';
+import { writeViaTmp } from '../state-file.js';
+import { codexUserDir, codexProviderName } from '../agent.js';
+import { categorize, ESCALATE_RE, EDIT_RE } from '../route-scan.js';
+import { looksPasted } from '../route-inject.js';
+import { newRouteId, recordCodexDelegation } from './ledger.js';
+import { readCodexTailLines } from './parser.js';
+import { loadConfig } from '../config.js';
+import { loadSharedModelRules, sharedModelRulesForProject, sharedRuleBounds, SHARED_RULE_TIERS } from '../shared-model-rules.js';
+import { codexPriceBook, readCodexPrices } from './cache-policy.js';
+import { codexRunCost } from '../gateway-prices.js';
 
 export const CODEX_ROUTE_CATEGORIES = ['paste', 'translate', 'explore', 'read', 'check', 'run'];
 const MARKER = '<!-- sprag:codex:delegation -->';

package/src/{codex-doc2md-ledger.js → codex/doc2md-ledger.js}

@@ -1,11 +1,11 @@
 import { createHash, randomUUID } from 'node:crypto';
 import { mkdirSync, readdirSync, readFileSync, realpathSync, statSync } from 'node:fs';
 import { extname, join, resolve } from 'node:path';
-import { codexUserDir } from './agent.js';
-import { userDataDir } from './paths.js';
-import { writeViaTmp } from './state-file.js';
-import { readResetMarks, isBeforeReset } from './saved-reset.cjs';
-import { codexPriceBook, readCodexPrices } from './codex-cache-policy.js';
+import { codexUserDir } from '../agent.js';
+import { userDataDir } from '../paths.js';
+import { writeViaTmp } from '../state-file.js';
+import { readResetMarks, isBeforeReset } from '../saved-reset.cjs';
+import { codexPriceBook, readCodexPrices } from './cache-policy.js';
 
 const hash = (value) => createHash('sha256').update(value).digest('hex');
 const ledgerDir = ({ home = codexUserDir(), dir = userDataDir() } = {}) => join(dir, 'codex-doc2md', hash(resolve(home)));

package/src/{codex-doc2md.js → codex/doc2md.js}

@@ -2,12 +2,12 @@ import { createRequire } from 'node:module';
 import { realpathSync, readFileSync, writeFileSync, renameSync, rmSync, openSync, readSync, closeSync } from 'node:fs';
 import { basename, dirname, resolve } from 'node:path';
 import { randomUUID } from 'node:crypto';
-import { recordCodexDocument } from './codex-doc2md-ledger.js';
-import { readCodexSnapshot } from './codex-parser.js';
+import { recordCodexDocument } from './doc2md-ledger.js';
+import { readCodexSnapshot } from './parser.js';
 
 const require = createRequire(import.meta.url);
-const doc2md = require('./doc2md.cjs');
-const lint = require('./korean-lint.cjs');
+const doc2md = require('../doc2md.cjs');
+const lint = require('../korean-lint.cjs');
 const shellTools = new Set(['Bash', 'exec_command', 'shell_command', 'shell']);
 
 /** Hook identity, never the user's default model or another project's session. */