sprag-cli 3.63.0 → 3.64.0

package/bin/cli.js

@@ -57,7 +57,7 @@ import { sessionCostAcross } from '../src/claude-price.js';
 import { chipForIssues } from '../src/advice.js';
 import { debug } from '../src/debug.js';
 import { createArgs } from '../src/cli-args.js';
-import { updateStatus, maybeSpawnUpdateCheck, readUpdateState, updateCheckDisabled } from '../src/update-check.js';
+import { readUpdateChip } from '../src/update-notice.js';
 import { selectAgent } from '../src/agent.js';
 
 const selection = (() => {
@@ -77,28 +77,6 @@ const PKG_VERSION = (() => {
 
 const { getArg, hasFlag, numArg } = createArgs(args);
 
-/**
- * Version/update state for the statusline chip. Reads a cache file and, when
- * that cache has aged past the check interval, kicks a detached child to
- * refresh it for a later render. Never awaits the network, never throws into
- * the render: a registry outage must not cost the statusline its other chips.
- */
-function readUpdateChip() {
-  try {
-    maybeSpawnUpdateCheck(PKG_VERSION);
-    const status = updateStatus(PKG_VERSION);
-    // When the registry was last asked, for the verbose "✓6h" on an up-to-date
-    // version. updateStatus() does not carry it, and a second read of the
-    // 200-byte state file is cheaper than a second status computation. With
-    // checks switched off the file is a leftover, so it says nothing.
-    const checkedAt = updateCheckDisabled() ? null : (Number(readUpdateState().checkedAt) || null);
-    return { ...status, checkedAt };
-  } catch (e) {
-    debug('update-check:chip', e);
-    return null;
-  }
-}
-
 /**
  * Whether the table report may use ANSI codes. The formatter looked at NO_COLOR
  * alone, so `--no-color` did nothing there and a piped report (`sprag | less`,
@@ -605,7 +583,7 @@ async function main() {
       }
       const { withBaseStatusline } = await import('../src/statusline-base.js');
       console.log(withBaseStatusline(formatNoSession(
-        { caps, model, effort, windowLabel, version: PKG_VERSION, update: readUpdateChip() },
+        { caps, model, effort, windowLabel, version: PKG_VERSION, update: readUpdateChip(PKG_VERSION) },
         { color: colorOk, mode: labelMode },
       )));
       return;
@@ -892,7 +870,7 @@ async function main() {
     cost,
     options: { days, windowHours, windowLabel, version: PKG_VERSION },
     // Cached-only; the background refresh it may trigger lands on a later render.
-    update: format === 'statusline' ? readUpdateChip() : null,
+    update: format === 'statusline' ? readUpdateChip(PKG_VERSION) : null,
     lastActivity,
     monthSpend: monthSpendInfo,
     spikeReport,

package/docs/CODEX.ko.md

@@ -49,6 +49,7 @@ macOS zsh 환경에서는 설치가 tmux 설치 여부를 먼저 확인합니다
 | seed | 호환되는 래칫 프리셋을 제안하고 응답을 별도 저장합니다 |
 | 문서 변환 | PDF·Office·Figma 문서를 Markdown으로 변환하고 캐시 덮어쓰기를 막습니다 |
 | 한국어 검사 | 파일 쓰기 후 문체 위반을 검사하며 block·warn·off를 지원합니다 |
+| 답변 언어 검사 | Stop 훅이 현재 한국어 질문과 최종 답변을 대조합니다. 영어 답변 요청, Stop 재개, `korean reply off`는 제외합니다 |
 | 상태 표시 | 별도 패널, tmux 패널, 일회성 상태줄을 제공합니다 |
 | 브리핑·이력 | 최신 컨텍스트와 사용량 경고를 알리고 세션별로 저장합니다 |
 | 위임 원장 | Sprag가 위임한 하위 실행의 토큰에 호출 경로의 단가를 적용해 예상 차액을 계산합니다. 직접 호출은 OpenAI 정가를, LiteLLM 공급자는 그 게이트웨이의 단가를 씁니다 |
@@ -240,6 +241,8 @@ sprag harness prune --global --older-than 6 --dry-run --agent codex
 ```sh
 sprag doc2md install-converter --agent codex
 sprag doc2md report.pdf --agent codex
+sprag doc2md deck.pptx --agent codex --session SESSION_ID
+sprag doc2md savings --agent codex --format json
 sprag korean on --agent codex
 sprag korean lint warn --agent codex
 sprag cohesion on --agent codex
@@ -250,6 +253,25 @@ sprag cohesion on --agent codex
 지원하는 라이브러리로 복사본을 편집한 뒤 다시 변환하십시오. 텍스트 추출만으로 차트·이미지·배치를
 검증했다고 말할 수 없습니다. 실패와 잘린 결과는 그대로 보고해야 합니다.
 
+`Doc2md saved`는 PPTX·DOCX·XLSX의 원본 XML과 준비된 Markdown을 비교한 추정치입니다.
+각각 UTF-8 바이트 수를 4로 나눠 토큰 수를 추정하고, 그 차이에 해당 Codex 모델의 입력 단가를
+적용합니다. 네이티브 첨부 비용이나 실제 청구액을 측정한 값은 아닙니다. 변환본이 더 크면
+음수를 그대로 표시합니다. Claude 단가를 가져오지 않으며 모델, 프로바이더와 단가 출처를 기록합니다.
+
+같은 문서를 다시 사용해도 절감액을 더하거나 단가를 바꾸지 않습니다. 원본이 바뀌면 해당 문서의
+기존 기록을 교체합니다. PDF·Figma·구형 XLS, 잘린 변환본, 단가나 모델 정보가 없는 기록은
+미산정으로 남깁니다. 과거 기록에 현재 기본 모델의 단가를 임의로 적용하지 않습니다.
+수동 변환은 `--session` 또는 `CODEX_THREAD_ID`로 세션을 식별하며, 정보가 없으면 변환만 수행합니다.
+
+패널은 `Doc2md saved`와 `Routing saved`를 설정 항목 앞에 함께 표시합니다. 위임 안내만
+생성되고 자식이 실행되지 않으면 절감액은 `n/a`이며, 세션별 pending·bound·completed·unclaimed
+건수로 진행 상태를 구분합니다. 한 요청의 T1/T2 선택지는 안내 한 건으로 계산합니다.
+
+`sprag delegate doctor --agent codex --session SESSION_ID`는 모델 호출 없이 로컬 버전,
+기능 플래그, 모델 카탈로그와 연결 기록을 확인합니다. v2 카탈로그와 기능 플래그가 다르면
+진단 단서로만 알리고 설정은 바꾸지 않습니다. 실제 세션에 `spawn_agent`와 `wait_agent`가
+있는지는 별도로 확인해야 하며, 도구가 없으면 메인 모델이 처리합니다.
+
 훅은 지원되는 파일 읽기와 단순한 `cat`·`head`·`tail`, 인식 가능한 쓰기 대상을 처리합니다.
 임의의 추출 스크립트나 복합 셸 명령을 모두 가로채지는 않습니다. `doc2md off`는 Codex의 자동
 변환과 문서 쓰기 보호를 끕니다. 문체 설정은 공유하지만 기능을 켤 때는 Codex 훅을 먼저 등록합니다.
@@ -286,16 +308,48 @@ sprag capabilities --agent codex
 
 ## 제거와 업그레이드
 
+패널은 새 버전이 있으면 사용량 앞에 알림을 표시하고, 백그라운드에서 버전 캐시를 갱신합니다.
+일회성 상태줄은 캐시만 읽습니다. 대화형 SessionStart는 변경 내용을 알리고 설치 동의를 구합니다.
+`sprag update-check --dismiss --agent codex`로 해당 버전의 알림을 끌 수 있습니다.
+`CTS_NO_UPDATE_CHECK=1` 또는 `NO_UPDATE_NOTIFIER`는 확인 자체를 끕니다.
+compaction, 하위 세션 시작, `codex exec`에는 업그레이드 질문을 넣지 않습니다.
+
 ```sh
 sprag uninstall --agent codex
 npm i -g sprag-cli --ignore-scripts
 sprag install --agent codex
 ```
 
-제거는 Codex 훅과 전역 하네스 블록만 대상으로 합니다. 프로젝트 하네스, 래칫 규칙, 백업과
+제거는 Codex 훅, 전역 하네스 블록, 관리 중인 zsh 함수를 대상으로 합니다. 새 셸을 열어야
+이미 로드된 함수도 사라집니다. 프로젝트 하네스, 래칫 규칙, 백업과
 공유 상태는 남습니다. 일반 npm 설치는 Claude postinstall을 실행하므로 Codex만 사용한다면
 업그레이드에도 `--ignore-scripts`를 유지하십시오.
 
+## 구현 분업
+
+설계, 원인 진단, 스펙 확정과 최종 검증은 메인 모델이 맡습니다. 여러 파일을 고치는 구현은
+설계를 확정한 뒤 T1 모델에 위임합니다. Claude는 기존처럼 `model: sonnet`을 쓰고,
+Codex는 현재 부모 모델과 프로바이더의 명시적 T1 매핑을 우선합니다. 매핑이 없으면
+자동 해석한 T1을 씁니다. 이는 역할 구분이며 두 모델의 성능이 같다는 뜻은 아닙니다.
+
+```sh
+sprag delegate implementation --agent codex --from PARENT_MODEL --provider PROVIDER --session PARENT_SESSION_ID
+```
+
+기본 설정 대신 실제 부모 세션의 정보를 넘깁니다. 자식에게 설계, 수정할 파일, 제약,
+테스트 명령, 완료 기준과 모델 선택 이유를 전달하고, 반환된 route 줄을 메시지 끝에 붙입니다.
+`fork_turns "none"`으로 생성하며 출력 상한은 8,000토큰입니다. 메인은 `wait_agent`로
+완료를 기다린 뒤 diff와 실제 테스트 결과를 검증합니다. 상한은 지침이며 강제 제한은 아닙니다.
+
+T1이 없거나 위임이 꺼져 있으면 메인이 처리합니다. haiku나 T2로 대체하지 않습니다.
+이미 읽은 파일의 약 50줄 이하 수정도 메인에서 처리합니다. 위임 도구가 없으면 위 명령을
+실행하지 않고 제약을 알립니다. 별도 Codex CLI로 우회하지 않습니다. 원장에는 부모, 모델,
+프로바이더가 맞는 자식 실행만 집계하며, 실행되지 않은 안내는 절감으로 계산하지 않습니다.
+
+공유 정책의 Codex 실패율도 규칙 목록, 패널, 브리핑에 표시합니다. 정책, 등급, 범위,
+프로바이더와 부모·자식 모델별로 집계하며 Claude 통계에는 합치지 않습니다. 매핑을 검토할
+동안 `sprag delegate shared off --agent codex`로 공유 위임을 끌 수 있습니다.
+
 공식 인터페이스는 [Codex 훅](https://developers.openai.com/codex/hooks/)과
 [AGENTS.md 안내](https://developers.openai.com/codex/guides/agents-md/),
 [설정 참조](https://developers.openai.com/codex/config-reference/)에서 확인할 수 있습니다.

package/docs/CODEX.md

@@ -80,6 +80,7 @@ shared hooks needed by other features.
 | Ratchet rules | Separate Codex files; global and project rules injected at SessionStart, including resume and compaction |
 | Korean guidance / English cohesion | SessionStart injection using shared Sprag preferences |
 | Korean write-time lint | PostToolUse feedback for `apply_patch` and recognized shell write targets; block, warn, and off modes |
+| Reply language | Stop checks the current Korean prompt and final answer; `korean reply off` disables it, and explicit English requests and Stop continuations are excluded |
 | Documents | Shared converter, prompt paths, supported file reads, and recognized document/cache write guards; `sprag doc2md <file> --agent codex` also works manually |
 | Token report | Table, JSON, or CSV from local Codex rollout logs, with time and project filters |
 | Statusline | `--statusline` or `--format statusline` renders the compact panel once, with wrapping and label/color preferences |
@@ -94,6 +95,7 @@ shared hooks needed by other features.
 | Routing saved | Sprag-attributed child tokens priced by the path the call took (OpenAI list prices for direct calls, the gateway's `/model/info` prices for a LiteLLM provider); signed, so a pricier child is a loss; an estimate, not billed savings |
 | Diagnostics | `doctor` checks user config, hook registration, harness, logs, panel activity, and preferences |
 | Capability matrix | `capabilities` lists supported, partial, native, and unsupported areas without invoking a model |
+| Updates | Live panels refresh the shared version cache in the background; one-shot statuslines read it offline; interactive SessionStart offers a consent-based Codex-only upgrade |
 
 The document converter is shared with Claude Code and requires its optional
 converter dependencies. Disable automatic Codex conversion and write guards with
@@ -120,11 +122,34 @@ history is not imported. Counts are sorted by frequency, then extension, with no
 Claude pricing involved. Codex reads a neutral Markdown view without the shared
 cache's Claude-based savings banner; the shared cache remains unchanged.
 
+`Doc2md saved` is a separate Codex estimate for `.pptx`, `.docx`, and `.xlsx`:
+Office body XML bytes divided by four, minus the prepared Markdown bytes divided
+by four, multiplied by the recorded model's input-token price. This compares
+XML extraction with Markdown, not native attachment billing or measured tokens.
+Negative differences remain negative. The price comes from the active Codex
+provider, never Claude's price table, and its source is recorded with the result.
+Repeated use of the same source does not add another saving or reprice a saved
+estimate. Changed sources replace their previous entry, just like document counts.
+Clipped conversions, PDF/Figma/legacy XLS, missing prices, and old records without
+model identity remain unpriced. Nothing is backfilled from default config.
+
+```sh
+sprag doc2md deck.pptx --agent codex --session SESSION_ID
+sprag doc2md savings --agent codex --format json
+sprag saved --agent codex
+```
+
+Hooks use the current payload/rollout model and provider. Manual conversion can
+use `--session` or the CLI's `CODEX_THREAD_ID`; without session identity, the
+document is converted but the monetary estimate stays unavailable. No network
+request is needed for conversion accounting; it uses a cached provider price.
+
 ## Diagnostics And Continuity
 
 ```sh
 sprag doctor --agent codex
 sprag doctor --agent codex --format json
+sprag delegate doctor --agent codex --session SESSION_ID
 sprag capabilities --agent codex
 sprag brief --agent codex
 sprag brief on --agent codex
@@ -142,6 +167,15 @@ proof of trust. Its config report excludes provider credentials and is not an
 effective-config resolver: active profiles, project config, managed policy,
 and invocation overrides can differ. Check Codex `/hooks` for approval.
 
+`delegate doctor` reads local Codex version, feature flags, bundled model catalog
+and Sprag offer/binding records without calling a model. A v2 catalog/feature
+mismatch is reported only as a compatibility clue, not a diagnosis. Enabled
+settings and registered hooks cannot prove the running model has `spawn_agent`
+and `wait_agent`. Confirm those tools in the active session. The panel reports
+pending, bound, completed and unclaimed offers separately, scoped to its session;
+T1/T2 alternatives from one prompt count as one offer. Unclaimed offers are not
+charged or credited as savings. Missing tools leave work on the main agent.
+
 Briefing is enabled by default after installing and trusting the prompt hook.
 It reads at most the latest 256 KiB of the current transcript and warns when
 recorded input reaches 80% or 95% of the recorded context window, or a reported
@@ -304,6 +338,35 @@ booked as a loss and the entry is marked `aborted`.
 
 ## Harness Commands
 
+### Implementation Split
+
+The main agent retains design, diagnosis, specification and final verification.
+After design is complete, multi-file implementation can use the resolved T1:
+
+```sh
+sprag delegate implementation --agent codex --from PARENT_MODEL --provider PROVIDER --session PARENT_SESSION_ID
+```
+
+Use the active parent's identity, not the defaults in config. The installed
+harness treats this policy as the user's delegation request. The resolver uses
+an explicit T1 mapping first, otherwise automatic T1 resolution; Claude's
+corresponding policy still uses `model: sonnet`. These are roles, not a claim of
+equal model capability. It never falls back to T2. Disabled delegation or an
+unresolved T1 leaves the work on the main agent. Small edits of roughly 50 lines
+in already-read files also stay on the main agent.
+
+The child receives a self-contained specification, owned files, constraints,
+tests, completion criteria, the model-selection reason and an 8,000-output-token
+cap. Use `fork_turns "none"` and end the child message with the returned route
+line. Wait with `wait_agent` (at least 120 seconds per wait), then inspect its
+diff and actual test results. Without native subagent tools, skip the resolver
+and report the limitation; do not launch a second Codex CLI as a substitute.
+The cap is guidance, not runtime enforcement. Accounting requires a child of
+the recorded parent on the selected model/provider; an unused hint earns no
+savings. Implementation requests are not automatically classified as cheap work.
+
+### Ratchet Management
+
 ```sh
 sprag harness init --agent codex                 # current project
 sprag harness check --agent codex                # project, or global fallback
@@ -463,6 +526,12 @@ each other:
 rate and signed saving. A rule is flagged for review when the 95% lower bound
 of its failure rate exceeds 20% over at least five runs, as on the Claude side.
 
+Shared policies also report their Codex outcomes in the rule list, panel and
+prompt briefing. Outcomes are grouped by policy, tier, scope, provider and
+parent/child model pair; they are never imported into Claude's rule statistics.
+Use `sprag delegate shared off --agent codex` to pause shared routing while
+reviewing the mapping. Removing a common policy affects both agents.
+
 Providers are kept separate. Negative values are losses: the child ran on a
 pricier model than the parent, and the loss reduces the totals. Missing rates or usage produce unpriced entries, never invented zeroes. A priced
 entry keeps its rate snapshot across later outages. Pending route records are
@@ -470,7 +539,8 @@ matched for seven days; saved ledger entries remain afterward. Run `--refresh`
 after delegation to update the ledger without waiting for the next route scan.
 
 Claude's ledger is never imported. Document conversion shows distinct document
-counts rather than a Codex dollar saving or billing measurement.
+counts and the explicitly labelled Office XML-versus-Markdown estimate above,
+not a billing measurement.
 
 ### Live Companion Panel
 
@@ -574,7 +644,9 @@ The inline compact panel reuses Claude's icon/narrow/text preferences and
 segmented gauges. Chips wrap as units instead of losing their trailing values;
 the pane grows with the content while keeping at least ten rows for Codex.
 If the terminal is too small, a remaining-row count marks hidden content.
-Cache reuse is shown in tokens, not an inferred dollar saving. Document counts
+Cache reuse is shown in tokens, not an inferred dollar saving. `Doc2md saved` and
+`Routing saved` stay together before preferences, even when unavailable; missing
+prices or execution evidence are labelled instead of being reported as $0. Document counts
 and format breakdowns come from Codex's own document records and are labelled
 `Codex total`; Claude-based dollar estimates are not attributed to Codex.
 Unavailable cost and limit placeholders are hidden in compact mode. Cache timer
@@ -615,6 +687,7 @@ are skipped, and incomplete/copied/reset logs can only give best-effort totals.
 Reports show **cost and exact cache TTL as unavailable** (`null` in JSON). They do not
 apply Anthropic prices, infer subscription charges, or claim Claude's cache TTL.
 Document counts are not a measurement of Codex billing or avoided tokens.
+The separate Doc2md estimate is a bytes-based comparison, not tokenizer output.
 
 ## Limits And Removal
 
@@ -634,7 +707,9 @@ Rate-limit gauges use Codex's recorded values only. Run
 sprag uninstall --agent codex
 ```
 
-Removal takes out Sprag's Codex hooks and global harness block. It keeps project
+Removal takes out Sprag's Codex hooks, global harness block and managed zsh
+wrapper. Open a fresh shell afterward; an already-loaded shell function remains
+in the old shell. It keeps project
 harnesses, ratchet rules, backups, other hooks, and shared Sprag state.
 `--purge` is intentionally unsupported for Codex. Remove a project block with
 `sprag harness uninit --agent codex --project` in that project.
@@ -643,6 +718,13 @@ Normal npm upgrades still run the package's Claude postinstall. Codex-only users
 should keep using `npm i -g sprag-cli --ignore-scripts` followed by
 `sprag install --agent codex` when upgrading.
 
+The panel places an available update before usage metrics. Dismissing a version
+with `sprag update-check --dismiss --agent codex` hides its chip and session
+offer until a newer version appears. `CTS_NO_UPDATE_CHECK=1` or
+`NO_UPDATE_NOTIFIER` disables checks. Compaction, subagent starts and `codex exec`
+do not ask to upgrade. SessionStart checks at most every three hours; the live
+panel uses the shared 24-hour interval and never waits for a network response.
+
 ## Official References
 
 - [Codex hooks, event schemas, and trust](https://developers.openai.com/codex/hooks/)

package/mod/sprag-delegation-meter/hooks/hooks.json

@@ -0,0 +1,3 @@
+{
+  "modules": ["./register.ts"]
+}

package/mod/sprag-delegation-meter/hooks/register.ts

@@ -0,0 +1,197 @@
+import type { EngineInterface, Register, TurnUsage } from 'claude-code'
+
+/**
+ * sprag-delegation-meter: what each delegated subagent actually spent.
+ *
+ * sprag's delegation ledger prices a run after the fact, from the transcript
+ * it left. This mod reads the same numbers while the run happens, from the
+ * API's own usage: agent.spawn says which model the subagent got and what its
+ * parent runs on, every turn.step of the subagent's loop reports one
+ * request's tokens, and turn.complete closes a turn of that loop.
+ *
+ * Each run is kept in $.store under a key of its own, `run:<session>:<agent>`,
+ * so two sessions never overwrite each other's runs. The mod only observes: no
+ * spawn, request or turn is changed, and sprag's transcript-based ledger keeps
+ * running beside it.
+ */
+
+type Usage = { input: number; output: number; cacheRead: number; cacheWrite: number }
+
+type Run = {
+  sessionId: string
+  agentId: string
+  description: string
+  subagentType: string
+  /** The Agent tool's `model` parameter as given; null when the call named none. */
+  requestedModel: string | null
+  /** What the spawn resolved; null when this module never saw the spawn. */
+  model: string | null
+  parentModel: string | null
+  /** The model the API last reported answering, by its own id. */
+  answeredBy: string | null
+  startedAt: number
+  endedAt: number | null
+  durationMs: number
+  steps: number
+  turns: number
+  usage: Usage
+  lastReason: string | null
+}
+
+// Families as sprag's modelFamily() names them: versions are noise in a log line.
+const FAMILIES = ['fable', 'mythos', 'opus', 'sonnet', 'haiku']
+
+const family = (model: string) => FAMILIES.find(f => model.toLowerCase().includes(f)) ?? model
+
+const zero = (): Usage => ({ input: 0, output: 0, cacheRead: 0, cacheWrite: 0 })
+
+const fromApi = (u: TurnUsage): Usage => ({
+  input: u.input_tokens,
+  output: u.output_tokens,
+  cacheRead: u.cache_read_input_tokens,
+  cacheWrite: u.cache_creation_input_tokens,
+})
+
+const add = (into: Usage, more: Usage) => {
+  into.input += more.input
+  into.output += more.output
+  into.cacheRead += more.cacheRead
+  into.cacheWrite += more.cacheWrite
+}
+
+const tokens = (n: number) =>
+  n >= 1_000_000 ? `${(n / 1_000_000).toFixed(1)}M` : n >= 1_000 ? `${(n / 1_000).toFixed(1)}k` : String(n)
+
+const OUTCOME: Record<string, string> = { answer: '완료', aborted: '중단', refusal: '거절', error: '실패' }
+
+// Runs in flight by agent id, and per run the requests of the turn still open.
+// A run leaves the map once its turn is saved, so the map holds only what is
+// running and does not grow with the session. $.store has the run from then
+// on: a subagent resumed later (SendMessage starts another turn of the same
+// loop) or met again after a module reload continues from its saved totals.
+const runs = new Map<string, Run>()
+const openTurn = new Map<string, { usage: Usage; steps: number }>()
+
+const storeKey = (sessionId: string, agentId: string) => `run:${sessionId}:${agentId}`
+
+const isRun = (value: unknown, agentId: string): value is Run =>
+  typeof value === 'object' && value !== null
+  && (value as Run).agentId === agentId
+  && typeof (value as Run).usage === 'object' && (value as Run).usage !== null
+
+/**
+ * The run for an agent id: the one in flight, else the saved one, else a new
+ * one. A subagent's first request can arrive before the spawn hook resumes
+ * after `await next(e)`, so a step may be what creates the run.
+ *
+ * The session id is read per run and never cached in the module: the module
+ * outlives /clear, /resume and /branch, each of which moves the conversation
+ * to another session id without loading the module again.
+ */
+async function runFor($: EngineInterface, agentId: string): Promise<Run> {
+  const held = runs.get(agentId)
+  if (held) return held
+  const sessionId = await $.session.id()
+  let saved: unknown
+  try {
+    saved = await $.store.get(storeKey(sessionId, agentId))
+  } catch {
+    // An unreadable store costs this run only its earlier turns.
+  }
+  // A copy, since the totals are added to in place.
+  const run: Run = isRun(saved, agentId) ? JSON.parse(JSON.stringify(saved)) : {
+    sessionId,
+    agentId,
+    description: '',
+    subagentType: '',
+    requestedModel: null,
+    model: null,
+    parentModel: null,
+    answeredBy: null,
+    startedAt: await $.clock.now(),
+    endedAt: null,
+    durationMs: 0,
+    steps: 0,
+    turns: 0,
+    usage: zero(),
+    lastReason: null,
+  }
+  runs.set(agentId, run)
+  return run
+}
+
+export const register: Register = on => {
+  // A meter must never stop what it measures, so every hook here fails open:
+  // a hook that breaks before its next() is skipped and the event goes on, and
+  // one that breaks after it keeps the result next() settled to. That is the
+  // engine's default already; each .catch states it, and answers the same way
+  // when the hook is reached from beneath its own $ call (a re-entry).
+  on('agent.spawn', async ($, e, next) => {
+    const spawned = await next(e)
+    if (spawned.deny !== undefined || !spawned.agentId) return spawned
+    const run = await runFor($, spawned.agentId)
+    run.description = e.description
+    run.subagentType = e.subagentType
+    run.requestedModel = e.model ?? null
+    run.model = spawned.model
+    run.parentModel = e.parentModel || null
+    // A workflow can start dozens of agents; one line each would bury the transcript.
+    if (!e.workflow) {
+      const parent = run.parentModel ? ` (메인 ${family(run.parentModel)})` : ''
+      $.ui.log(`🔀 [sprag] "${e.description}" → ${family(spawned.model)} 위임${parent}`)
+    }
+    return spawned
+  }).catch(($, e, next) => next(e))
+
+  on('turn.step', async function* ($, e, next) {
+    const result = yield* next(e)
+    if (e.agentId && result.usage) {
+      const run = await runFor($, e.agentId)
+      const turn = openTurn.get(e.agentId) ?? { usage: zero(), steps: 0 }
+      add(turn.usage, fromApi(result.usage))
+      turn.steps += 1
+      openTurn.set(e.agentId, turn)
+      run.answeredBy = result.usage.model
+    }
+    return result
+  }).catch(async function* ($, e, next) {
+    return yield* next(e)
+  })
+
+  on('turn.complete', async ($, e, next) => {
+    if (!e.agentId) return next(e)
+    const run = await runFor($, e.agentId)
+    const turn = openTurn.get(e.agentId)
+    openTurn.delete(e.agentId)
+    // The steps' own counts are the measurement. The turn's sum stands in only
+    // when no step was seen, e.g. the module reloaded during the turn.
+    if (turn && turn.steps > 0) {
+      add(run.usage, turn.usage)
+      run.steps += turn.steps
+    } else if (e.usage) {
+      add(run.usage, fromApi(e.usage))
+      run.answeredBy = e.usage.model
+    }
+    run.turns += 1
+    run.durationMs += e.durationMs
+    run.endedAt = await $.clock.now()
+    run.lastReason = e.reason
+
+    try {
+      await $.store.set(storeKey(run.sessionId, run.agentId), run)
+      runs.delete(e.agentId)
+    } catch {
+      // A store that refuses the write leaves only this run unrecorded. It
+      // stays in the map, so its next turn still adds to these totals.
+    }
+
+    const model = family(run.model ?? run.answeredBy ?? 'unknown')
+    const u = run.usage
+    $.ui.log(
+      `🔀 [sprag] ${model} 위임 ${OUTCOME[e.reason] ?? e.reason} · ${(run.durationMs / 1000).toFixed(1)}초`
+        + ` · 요청 ${run.steps}회 · 입력 ${tokens(u.input)} · 캐시 읽기 ${tokens(u.cacheRead)}`
+        + ` · 캐시 쓰기 ${tokens(u.cacheWrite)} · 출력 ${tokens(u.output)}`,
+    )
+    return next(e)
+  }).catch(($, e, next) => next(e))
+}

package/mod/sprag-doc2md/hooks/hooks.json

@@ -0,0 +1,3 @@
+{
+  "modules": ["./register.ts"]
+}

package/mod/sprag-doc2md/hooks/register.ts

@@ -0,0 +1,97 @@
+import type { EngineInterface, Register } from 'claude-code'
+
+/**
+ * sprag-doc2md: the mod form of sprag's PreToolUse(Read) hook.
+ *
+ * The settings hook can only refuse the Read and tell Claude where the
+ * converted Markdown is, which costs one more tool call per document. A mod
+ * sits in front of the call, so it hands the same call on with the path
+ * swapped: Claude asked for deck.pptx and reads deck.md, and the permission
+ * check still runs on the path that is actually read.
+ *
+ * Whenever this mod does not redirect (not a document, conversion refused or
+ * failed, sprag not on PATH) the call goes on untouched, and sprag's settings
+ * hook beneath it explains the refusal exactly as it does today. After a
+ * redirect that hook sees a .md path and stays silent, so the two never
+ * answer the same Read twice.
+ */
+
+// Mirrors TARGET_EXTENSIONS in src/doc2md.cjs. A hooks module has no Node, so
+// it cannot load that file; test/mod-install.test.js holds the two in step.
+const TARGET = /\.(pptx|xlsx|xls|pdf|docx|fig)$/i
+
+// The CLI's name, as CLI_NAME in src/cli-name.js spells it. The mod cannot
+// import that file either; test/mod-install.test.js holds the two in step.
+const CLI = 'sprag'
+
+// The converter gives up at 120 s on its own; the margin covers CLI start-up.
+// Time spent in $.process.run does not count against the hook's 10 s budget,
+// so the Read waits as long as the conversion does, as it does under the
+// settings hook today. The status line says so while it lasts.
+const CONVERT_TIMEOUT_MS = 150_000
+
+// What `sprag doc2md <path>` prints on success. Parsing human output is a
+// prototype shortcut: a `--json` flag on that command should replace it.
+const CONVERTED = /^✓ (cached|converted): (.+)$/m
+
+type Converted = { cacheFile: string; isCached: boolean }
+
+const baseName = (path: string) => path.split(/[\\/]/).pop() ?? path
+
+/**
+ * Runs the conversion the settings hook would run, ledger entry included.
+ * Answers null on any failure so the caller passes the event on unchanged.
+ *
+ * A first conversion can take a minute, and nothing else on screen says the
+ * Read is waiting on it, so the status line under the prompt names the file
+ * until the CLI returns. A status line rather than a transcript line: whether
+ * the file is cached is unknown until the CLI answers, and a log line on every
+ * Read would double the lines for the cached ones too.
+ */
+async function convert($: EngineInterface, path: string): Promise<Converted | null> {
+  $.ui.status(`doc2md: ${baseName(path)} 변환 중…`)
+  try {
+    const run = await $.process.run([CLI, 'doc2md', path], { timeoutMs: CONVERT_TIMEOUT_MS })
+    if (run.exitCode !== 0) return null
+    const match = CONVERTED.exec(run.stdout)
+    if (!match) return null
+    return { cacheFile: match[2].trim(), isCached: match[1] === 'cached' }
+  } catch {
+    return null
+  } finally {
+    $.ui.status(undefined)
+  }
+}
+
+function logRedirect($: EngineInterface, from: string, doc: Converted) {
+  $.ui.log(`doc2md: ${baseName(from)} 대신 변환본을 읽습니다${doc.isCached ? ' (캐시)' : ''}`)
+}
+
+export const register: Register = on => {
+  // Both hooks fail open, which is the point of the .catch on each: this mod
+  // saves a round trip and guards nothing, so a hook that breaks hands the
+  // event on as it came and sprag's settings hook beneath answers as before.
+  // Where the hook had already called next, next(e) replays that call.
+  on('tool.call', { tool: 'Read' }, async ($, e, next) => {
+    if (!TARGET.test(e.file_path)) return next(e)
+    const doc = await convert($, e.file_path)
+    if (!doc) return next(e)
+    logRedirect($, e.file_path, doc)
+    // Line and page ranges addressed the binary and mean nothing in the
+    // Markdown (`pages` applies to PDFs only), so the whole file is read.
+    const { offset: _offset, limit: _limit, pages: _pages, ...call } = e
+    return next({ ...call, file_path: doc.cacheFile })
+  }).catch(($, e, next) => next(e))
+
+  // An @-mentioned document is attached whole, before any tool call, so the
+  // Read hook above never sees it. Redirect the attachment the same way.
+  on('prompt.mention', { path: TARGET }, async ($, e, next) => {
+    const doc = await convert($, e.path)
+    if (!doc) return next(e)
+    logRedirect($, e.path, doc)
+    // A mention carries no `pages` (PromptMentionInput has mention, path,
+    // offset, limit and agentId), so only the line range is dropped here.
+    const { offset: _offset, limit: _limit, ...mention } = e
+    return next({ ...mention, path: doc.cacheFile })
+  }).catch(($, e, next) => next(e))
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sprag-cli",
-  "version": "3.63.0",
+  "version": "3.64.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.",
   "type": "module",
   "bin": {
@@ -22,7 +22,7 @@
     "bin/",
     "src/",
     "mod/*/.claude-plugin/plugin.json",
-    "mod/*/hooks/",
+    "mod/*/hooks/**",
     "presets/",
     "examples/",
     "README.md",

package/src/codex-brief.js

@@ -7,7 +7,7 @@ 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 } from './codex-rule-health.js';
+import { codexRulesInReview, codexSharedRuleHealth } from './codex-rule-health.js';
 
 const RESET_TOLERANCE_S = 300;
 const hash = (value) => createHash('sha256').update(value).digest('hex');
@@ -88,6 +88,15 @@ export function runCodexBrief({ sessionId, transcriptPath, cwd, root: projectRoo
       }
     }
   } catch { /* An unreadable rule file or ledger only skips this line. */ }
+  try {
+    for (const { rule, health, from, model, provider } of codexSharedRuleHealth({ root: cwd || projectRoot || snapshot.projectDir, dir })) {
+      if (health.status !== 'review') continue;
+      issues.push({ key: 'rule-health', tier: 1,
+        signature: `shared-rule-health:${JSON.stringify([rule.sharedSignature, rule.scope, rule.targetRoot, provider, from, model])}`,
+        level: 'warning', message: `Codex shared policy ${rule.tier} ${rule.category} (${provider}: ${from} -> ${model}) failed ${health.errs} of ${health.runs} measured runs.`,
+        advice: 'Review: sprag delegate rules --agent codex. Pause shared routing: sprag delegate shared off --agent codex. Common policy removal affects both agents.' });
+    }
+  } catch { /* Shared health is independent of Codex-only rule parsing. */ }
   const next = issues.filter((issue) => !active.includes(issue.signature) &&
     !(issue.key === 'context' && issue.tier === 1 && active.includes('context:2')));
   // Missing or stale measurements do not resolve an earlier warning. A fresh