sprag-cli 3.65.0 → 3.66.0

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

@@ -14,6 +14,12 @@ import type { EngineInterface, Register } from 'claude-code'
  * 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.
+ *
+ * The exception is an encrypted document (password or DRM). Claude Code
+ * refuses a pptx, xlsx or docx as a binary file before any settings hook runs,
+ * so the settings hook can never tell the model why such a file cannot be
+ * read; this mod is the only place that can, so it refuses the Read itself
+ * with the CLI's notice.
  */
 
 // Mirrors TARGET_EXTENSIONS in src/doc2md.cjs. A hooks module has no Node, so
@@ -34,13 +40,20 @@ const CONVERT_TIMEOUT_MS = 150_000
 // prototype shortcut: a `--json` flag on that command should replace it.
 const CONVERTED = /^✓ (cached|converted): (.+)$/m
 
+// What `sprag doc2md <path>` prints on stderr for an encrypted document: the
+// reason line, then one indented line holding the notice for the model. A CLI
+// that predates the notice line prints the reason line alone.
+const LOCKED = /^✗ (encrypted|drm-protected)\b.*$/m
+
 type Converted = { cacheFile: string; isCached: boolean }
+type Locked = { locked: string }
 
 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.
+ * Answers null on any failure so the caller passes the event on unchanged,
+ * and `{ locked }` with the CLI's notice when the document is encrypted.
  *
  * 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
@@ -48,11 +61,17 @@ const baseName = (path: string) => path.split(/[\\/]/).pop() ?? path
  * 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> {
+async function convert($: EngineInterface, path: string): Promise<Converted | Locked | 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
+    if (run.exitCode !== 0) {
+      const reason = LOCKED.exec(run.stderr)
+      if (!reason) return null
+      const rest = run.stderr.slice(reason.index + reason[0].length)
+      const notice = rest.split('\n').map(line => line.trim()).find(line => line !== '')
+      return notice ? { locked: notice } : null
+    }
     const match = CONVERTED.exec(run.stdout)
     if (!match) return null
     return { cacheFile: match[2].trim(), isCached: match[1] === 'cached' }
@@ -63,19 +82,25 @@ async function convert($: EngineInterface, path: string): Promise<Converted | nu
   }
 }
 
+const isLocked = (doc: Converted | Locked): doc is Locked => 'locked' in doc
+
 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.
+  // Both hooks fail open, which is the point of the .catch on each: a hook that
+  // breaks hands the event on as it came and sprag's settings hook beneath
+  // answers as before. Only the encrypted-document refusal in the Read hook guards
+  // anything, and failing open there costs the notice, not safety.
   // 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)
+    // Refuse rather than pass the original on: it cannot be opened, and the
+    // binary-file refusal it would meet says nothing of why.
+    if (isLocked(doc)) return { deny: `[doc2md] ${doc.locked}` }
     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.
@@ -87,7 +112,9 @@ export const register: Register = on => {
   // 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)
+    // A deny here would only reach the debug log, not the model, so an
+    // encrypted mention goes on as it came; the prompt hook names it instead.
+    if (!doc || isLocked(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.

package/mod/sprag-statusline/.claude-plugin/plugin.json

@@ -0,0 +1,7 @@
+{
+  "name": "sprag-statusline",
+  "version": "0.1.0",
+  "description": "Draws sprag's statusline above the prompt in the Claude desktop app, which never runs the statusLine command, and keeps the snapshots the statusline leaves behind",
+  "author": { "name": "DeepPulse", "url": "https://www.youtube.com/@DeepPulseKR" },
+  "types": "./types/index.d.ts"
+}

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

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

package/mod/sprag-statusline/hooks/register.tsx

@@ -0,0 +1,176 @@
+import { atom, read, update } from 'claude-code'
+import type { EngineInterface, Register, SessionUsage } from 'claude-code'
+
+/**
+ * sprag-statusline: sprag's statusline in the Claude desktop app.
+ *
+ * The desktop app's Code tab runs claude in stream-json mode, which never runs
+ * settings.json's statusLine.command. Hooks and mods do run there, so this mod
+ * runs the same sprag command itself and draws its text in the band above the
+ * prompt. Running the real CLI also leaves what a statusline render leaves: the
+ * rate-limit snapshot and the context window size that the delegation briefing
+ * reads back.
+ *
+ * The terminal has its own statusline, so the band is drawn on the desktop
+ * surface only. Nothing here may slow or break a session: a run is skipped
+ * while another is in flight, cut off after a few seconds, and a failure keeps
+ * the last text on screen.
+ */
+
+const lines = atom({ plugin: 'sprag-statusline', key: 'lines' } as const, [] as string[])
+
+const REFRESH_MS = 5000
+const RUN_TIMEOUT_MS = 3000
+const DEFAULT_ARGV = ['sprag', '--statusline', '--no-color']
+
+// The executable names src/installer.js's argsAfterOurExecutable accepts
+const OUR_EXECUTABLES = ['sprag', 'claude-token-saver', 'sprag-cli']
+const RUNNERS = /^(npx|bunx|pnpx)$/
+const RUNNER_SUBCOMMANDS: Record<string, string[]> = {
+  pnpm: ['dlx', 'exec'],
+  yarn: ['dlx', 'run'],
+  bun: ['x', 'run'],
+  npm: ['exec'],
+}
+
+/** Whether a statusLine command starts with sprag's executable, as the installer judges it. */
+function isOurCommand(tokens: string[]): boolean {
+  let i = 0
+  if (RUNNERS.test(tokens[0] ?? '')) i = 1
+  else if (RUNNER_SUBCOMMANDS[tokens[0] ?? '']?.includes(tokens[1] ?? '')) i = 2
+  const token = tokens[i]
+  if (!token) return false
+  const exe = (token.split(/[/\\]/).pop() ?? '').replace(/\.(cmd|exe|ps1)$/i, '')
+  return OUR_EXECUTABLES.includes(exe)
+}
+
+/**
+ * The command to run: the user's own sprag statusLine command with --no-color
+ * added, or the default one. This module has no shell, so the command is split
+ * on whitespace, the same way the installer reads it; a command with quoting
+ * falls back to the default rather than being run in pieces.
+ */
+export function statuslineArgv(settings: Readonly<Record<string, unknown>>): string[] {
+  const statusLine = settings.statusLine as { command?: unknown } | undefined
+  const command = typeof statusLine?.command === 'string' ? statusLine.command.trim() : ''
+  if (!command || /["'`$;|&<>\\]/.test(command)) return DEFAULT_ARGV
+  const tokens = command.split(/\s+/)
+  if (!isOurCommand(tokens)) return DEFAULT_ARGV
+  return tokens.includes('--no-color') ? tokens : [...tokens, '--no-color']
+}
+
+/**
+ * The JSON Claude Code's statusline would have been fed. Fields the engine has
+ * no value for are left out, never zeroed: sprag reads an absent rate_limits as
+ * "no data" but a 0 as "0% used". transcript_path is left out because the mod
+ * cannot know it, and sprag takes it only for the effort chip.
+ */
+export function statuslinePayload(input: {
+  sessionId: string
+  cwd: string
+  model: string
+  usage: SessionUsage
+}) {
+  const { usage } = input
+  const payload: Record<string, unknown> = {
+    session_id: input.sessionId,
+    cwd: input.cwd,
+    workspace: { current_dir: input.cwd, project_dir: input.cwd },
+    model: { id: input.model, display_name: input.model },
+  }
+  if (usage.context.percent !== undefined) {
+    payload.context_window = {
+      context_window_size: usage.context.window,
+      used_percentage: usage.context.percent,
+    }
+  }
+  if (usage.rateLimits.length) {
+    const limits: Record<string, { used_percentage: number; resets_at?: number }> = {}
+    for (const limit of usage.rateLimits) {
+      const at = limit.resetsAt ? Math.floor(Date.parse(limit.resetsAt) / 1000) : NaN
+      limits[limit.kind] = {
+        used_percentage: limit.percentUsed,
+        ...(Number.isFinite(at) ? { resets_at: at } : {}),
+      }
+    }
+    payload.rate_limits = limits
+  }
+  if (usage.cost) payload.cost = { total_cost_usd: usage.cost.usd }
+  return payload
+}
+
+/** Output with stray ANSI escapes removed and blank lines dropped. */
+export function cleanOutput(text: string): string[] {
+  return text
+    .replace(/\u001b\[[0-9;?]*[ -/]*[@-~]/g, '')
+    .replace(/\u001b\][^\u0007]*(\u0007|\u001b\\)/g, '')
+    .split(/\r?\n/)
+    .map(line => line.trimEnd())
+    .filter(line => line.trim() !== '')
+}
+
+let isRunning = false
+let timer: { cancel: () => void } | undefined
+
+/** Runs the statusline once and stores its text; any failure leaves the last text as it was. */
+async function refresh($: EngineInterface): Promise<void> {
+  if (isRunning) return
+  isRunning = true
+  try {
+    if (!(await $.session.surfaces()).includes('desktop')) return
+    const [sessionId, cwd, model, usage, settings] = await Promise.all([
+      $.session.id(),
+      $.session.cwd(),
+      $.session.model(),
+      $.session.usage(),
+      $.settings.read(),
+    ])
+    const run = await $.process.run(statuslineArgv(settings), {
+      stdin: JSON.stringify(statuslinePayload({ sessionId, cwd, model, usage })),
+      timeoutMs: RUN_TIMEOUT_MS,
+    })
+    if (run.exitCode !== 0) return
+    const next = cleanOutput(run.stdout)
+    if (!next.length) return
+    // An unchanged text is not written, so the band is not redrawn every tick
+    const same = JSON.stringify(await read($, lines)) === JSON.stringify(next)
+    if (!same) await update($, lines, () => next)
+  } catch {
+    // The statusline is a convenience; a refused or timed-out run is not worth an error
+  } finally {
+    isRunning = false
+  }
+}
+
+export const register: Register = on => {
+  on('session.start', ($, e, next) => {
+    timer?.cancel()
+    timer = $.clock.every(REFRESH_MS, () => void refresh($))
+    void refresh($)
+    return next(e)
+  })
+
+  // Not awaited: a slow statusline must never hold a turn open
+  on('turn.complete', ($, e, next) => {
+    void refresh($)
+    return next(e)
+  })
+
+  on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
+    if (e.surface !== 'desktop' || e.props.hasSurvey) return next(e)
+    const shown = (await read($, lines)).slice(0, Math.max(0, e.props.maxRows))
+    if (!shown.length) return next(e)
+
+    const { Box, Text } = $.ui.resolve(e)
+    // One statusline line per row; a Box lays its children out in a row unless told otherwise
+    return (
+      <Box flexDirection="column">
+        {shown.map((line, i) => (
+          <Text key={`line-${i}`} dimColor>
+            {line}
+          </Text>
+        ))}
+      </Box>
+    )
+  })
+}

package/mod/sprag-statusline/types/index.d.ts

@@ -0,0 +1,5 @@
+declare module 'claude-code' {
+  interface PluginState {
+    'sprag-statusline': { lines: string[] }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sprag-cli",
-  "version": "3.65.0",
+  "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.",
   "type": "module",
   "bin": {
@@ -15,7 +15,7 @@
     "release:notes": "node scripts/release-notes.mjs",
     "site:docs": "node scripts/build-site-docs.mjs",
     "test": "node --test",
-    "test:mods": "claude plugin test mod/sprag-doc2md && claude plugin test mod/sprag-delegation-meter",
+    "test:mods": "claude plugin test mod/sprag-doc2md && claude plugin test mod/sprag-delegation-meter && claude plugin test mod/sprag-statusline",
     "version": "node scripts/sync-site-version.mjs"
   },
   "files": [
@@ -23,6 +23,7 @@
     "src/",
     "mod/*/.claude-plugin/plugin.json",
     "mod/*/hooks/**",
+    "mod/*/types/**",
     "presets/",
     "examples/",
     "README.md",

package/src/commands/doc2md.js

@@ -11,7 +11,7 @@
 
 import { createRequire } from 'node:module';
 import { readdirSync, rmSync, existsSync, statSync } from 'node:fs';
-import { join } from 'node:path';
+import { basename, join } from 'node:path';
 
 const require = createRequire(import.meta.url);
 
@@ -149,6 +149,15 @@ export async function run({ args, hasFlag }) {
     }
     console.error(`✗ ${result.reason}${result.detail ? `: ${result.detail}` : ''}`);
     if (result.reason === 'no-markitdown') console.error(`  ${doc2md.INSTALL_HINT}`);
+    // The line after the reason is the same sentence the hooks give the model;
+    // the mod reads it back from here, so keep the first line's format as is.
+    let lang = 'en';
+    try {
+      const { userLanguage } = await import('../config.js');
+      lang = userLanguage();
+    } catch { /* the diagnostic must not depend on the config module */ }
+    const notice = doc2md.lockedNotice(basename(sub), result, lang);
+    if (notice) console.error(`  ${notice}`);
     process.exitCode = 1;
     return;
   }

package/src/commands/install.js

@@ -87,6 +87,8 @@ export async function run({ hasFlag }) {
     print('PostToolUse hook (delegation rescan)', r.delegationHook);
     print('mod (delegation meter, Claude Code 2.1.287+)', r.delegationMeterMod);
     if (r.delegationMeterMod.reason) console.log(`    ${r.delegationMeterMod.reason}`);
+    print('mod (desktop statusline, Claude Code 2.1.287+)', r.statuslineMod);
+    if (r.statuslineMod.reason) console.log(`    ${r.statuslineMod.reason}`);
     print('UserPromptSubmit hook (brief)', r.briefHook);
     {
       let s = r.statusline;

package/src/doc2md.cjs

@@ -678,8 +678,9 @@ function decideForRead(context, opts = {}) {
     return { deny: true, reason: bits.join('\n') };
   }
 
-  // From here down the Read is allowed through untouched. The only question is
-  // whether the model is told why nothing was converted.
+  // From here down the Read is allowed through untouched, except for the
+  // locked and unsafe-archive cases below. The only question is whether the
+  // model is told why nothing was converted.
   if (result.reason === 'no-markitdown') {
     if (noticeAlreadyShown()) return null;
     markNoticeShown();
@@ -690,21 +691,10 @@ function decideForRead(context, opts = {}) {
         + `  진행 상황: ${INSTALL_HINT} 를 직접 실행하면 설치 로그를 볼 수 있습니다.`,
     };
   }
-  if (result.reason === 'drm-protected') {
-    return {
-      deny: false,
-      reason: `[doc2md] ${name} 는 DRM 으로 보호된 파일이라 변환하지 못했습니다(${result.detail || ''}).\n`
-        + '  DRM 은 암호 입력으로 풀리지 않습니다. 벤더 에이전트가 허용한 프로그램에서만 평문이 보이므로, '
-        + '사용자에게 DRM 클라이언트에서 연 뒤 해제본으로 저장하거나 반출 승인을 받은 사본을 요청하십시오.',
-    };
-  }
-  if (result.reason === 'encrypted') {
-    return {
-      deny: false,
-      reason: `[doc2md] ${name} 는 암호가 걸린 문서라 변환하지 못했습니다. `
-        + '사용자에게 암호를 푼 사본을 요청하십시오. 이 도구는 암호를 묻거나 저장하지 않습니다.',
-    };
-  }
+  // An encrypted document blocks the Read. It cannot be opened anyway, and
+  // handing the original on only invites the model to try to get around it.
+  const locked = lockedNotice(name, result, 'ko');
+  if (locked) return { deny: true, reason: '[doc2md] ' + locked };
   if (result.reason === 'python-too-old') {
     if (noticeAlreadyShown()) return null;
     markNoticeShown();
@@ -827,6 +817,23 @@ function conversionSummary(sourcePath, meta = {}) {
   return parts.join(', ');
 }
 
+/**
+ * The one sentence for a document that cannot be opened because it is
+ * encrypted, or null for any other result.
+ *
+ * Password protection and DRM are deliberately not told apart here. To the
+ * user both are a document that cannot be opened, and releasing either one
+ * goes through the company's own export procedure, so asking for an unlocked
+ * copy is never something the model should do. The Read hook, the prompt hook,
+ * the CLI diagnostic and the mod all share this wording.
+ */
+function lockedNotice(name, result, lang = 'en') {
+  if (!result || (result.reason !== 'encrypted' && result.reason !== 'drm-protected')) return null;
+  return lang === 'ko'
+    ? `${name} 는 암호화된 문서라 내용을 확인할 수 없습니다${result.detail ? `(${result.detail})` : ''}. 사용자에게 그대로 알리고, 암호 해제나 다른 변환 방법은 시도하지 마십시오.`
+    : `${name} is encrypted, so its contents cannot be read${result.detail ? ` (${result.detail})` : ''}. Tell the user so, and do not try to unlock it or convert it another way.`;
+}
+
 /**
  * Context to inject for a UserPromptSubmit payload, or null.
  *
@@ -863,14 +870,8 @@ function contextForPrompt(payload, opts = {}) {
         : lang === 'ko'
         ? `  ${name}: 변환기를 설치하는 중입니다(첫 실행에만 걸립니다). 설치가 끝나면 다음 요청부터 자동 변환됩니다.`
         : `  ${name}: the converter is installing now (first run only). It will convert automatically from the next request.`);
-    } else if (result.reason === 'drm-protected') {
-      lines.push(lang === 'ko'
-        ? `  ${name}: DRM 으로 보호된 파일입니다(${result.detail || ''}). 암호로는 풀 수 없으므로, DRM 클라이언트에서 저장한 해제본이나 반출 승인 사본을 달라고 사용자에게 요청하십시오.`
-        : `  ${name}: the file is DRM-wrapped (${result.detail || ''}). A password will not open it — ask the user for a copy released from DRM.`);
-    } else if (result.reason === 'encrypted') {
-      lines.push(lang === 'ko'
-        ? `  ${name}: 암호가 걸린 문서입니다. 암호를 푼 사본을 달라고 사용자에게 요청하십시오.`
-        : `  ${name}: the document is password-protected. Ask the user for an unlocked copy.`);
+    } else if (result.reason === 'drm-protected' || result.reason === 'encrypted') {
+      lines.push(`  ${lockedNotice(name, result, lang)}`);
     } else if (result.reason === 'python-too-old') {
       lines.push(lang === 'ko'
         ? `  ${name}: 변환기가 Python 3.10 이상을 요구하는데 PATH 에 없습니다(macOS 기본은 3.9). \`brew install python\` 후 다시 시도하도록 사용자에게 안내하십시오.`
@@ -921,15 +922,17 @@ function contextForPrompt(payload, opts = {}) {
 /**
  * The standing note injected at session start.
  *
- * Two things the model cannot work out on its own: that attaching a document
- * costs far more than naming its path, and that the binary-file refusal it
- * will meet on a pptx has a one-command answer.
+ * Three things the model cannot work out on its own: that attaching a document
+ * costs far more than naming its path, that the binary-file refusal it
+ * will meet on a pptx has a one-command answer, and that an encrypted document
+ * is to be reported, not worked around.
  */
 function sessionNote(lang = 'en') {
   if (lang === 'ko') {
     return [
       '[doc2md] 문서(pptx·xlsx·pdf·docx)를 다룰 때의 규칙입니다.',
       '  문서를 열어야 하는데 Read 가 이진 파일이라며 거부하면, `sprag doc2md <경로>` 를 실행하고 그 결과로 나온 .md 를 Read 하십시오.',
+      '  변환이 암호화 문서(encrypted·drm-protected)라는 이유로 실패하면, 내용을 확인할 수 없다고 사용자에게 알리고 암호 해제나 다른 변환 방법은 시도하지 마십시오.',
       '  사용자가 문서를 메시지에 직접 첨부했다면, 첨부는 내용 전체가 컨텍스트에 실려 토큰을 크게 씁니다. 다음부터는 첨부 대신 파일 경로를 적어 달라고 안내하십시오. 경로로 주면 변환본만 읽습니다.',
       '  변환은 단방향입니다. 변환본 .md 를 고쳐도 원본에는 반영되지 않습니다. 문서 수정 요청을 받으면: ① 원본을 복사하고 ② 복사본을 스크립트로 수정하십시오. pptx·docx·xlsx 는 도구 venv 파이썬에 python-pptx·python-docx·openpyxl 이 준비되어 있고(`sprag doc2md` 상태 출력에 경로가 나옵니다), .fig 는 openfig-core 로 편집·재인코드합니다. ③ 수정한 복사본을 doc2md 로 재변환해 변경이 들어갔는지 검증하십시오. 차트·이미지 같은 시각 요소는 변환본에 안 잡히므로 텍스트 검증만으로 완료를 단정하지 마십시오.',
     ].join('\n');
@@ -937,6 +940,7 @@ function sessionNote(lang = 'en') {
   return [
     '[doc2md] Handling documents (pptx/xlsx/pdf/docx):',
     '  If Read refuses a document as a binary file, run `sprag doc2md <path>` and Read the .md it prints.',
+    '  If conversion fails because the document is encrypted (encrypted or drm-protected), tell the user its contents cannot be read, and do not try to unlock it or convert it another way.',
     '  If the user attached a document to their message, its full contents were billed into the context. Tell them that naming the file path instead is far cheaper, since only the converted Markdown gets read.',
     '  Conversions are one-way: editing the cached .md changes nothing in the source. When asked to modify a document: ① copy the original, ② edit the COPY with a script — the managed venv python has python-pptx/python-docx/openpyxl, and .fig edits go through openfig-core — then ③ re-convert the copy with doc2md to verify the change landed. Charts and images do not appear in conversions, so text verification alone does not prove visual edits.',
   ].join('\n');
@@ -1043,6 +1047,7 @@ module.exports = {
   isTargetPath,
   isSensitivePath,
   documentPathsIn,
+  lockedNotice,
   contextForPrompt,
   sessionNote,
   findInterpreter,

package/src/installer.js

@@ -709,7 +709,8 @@ const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
 const PLUGIN_DIRS_ENV = 'CLAUDE_CODE_PLUGIN_DIRS';
 export const DOC2MD_MOD = 'sprag-doc2md';
 export const DELEGATION_METER_MOD = 'sprag-delegation-meter';
-export const MOD_NAMES = [DOC2MD_MOD, DELEGATION_METER_MOD];
+export const STATUSLINE_MOD = 'sprag-statusline';
+export const MOD_NAMES = [DOC2MD_MOD, DELEGATION_METER_MOD, STATUSLINE_MOD];
 
 export function modDir(name) {
   return join(PACKAGE_ROOT, 'mod', name);
@@ -809,6 +810,26 @@ export function installDelegationMeterMod() {
   return { path: file, action: read.state === 'absent' ? 'created' : 'updated' };
 }
 
+// The statusline mod draws sprag's statusline in the Claude desktop app, whose
+// Code tab never runs settings.json's statusLine.command (see
+// mod/sprag-statusline). The terminal keeps its own statusline; the mod draws
+// on the desktop surface only. Ships on with installAll() and is taken out
+// with every other mod by uninstallAll().
+export function installStatuslineMod() {
+  const dir = claudeUserDir();
+  const file = join(dir, 'settings.json');
+  mkdirSync(dir, { recursive: true });
+  const read = readSettings(file);
+  if (read.state === 'unusable') return { path: file, action: 'skipped', reason: read.reason };
+  const settings = read.settings;
+  const changed = addModDir(settings, STATUSLINE_MOD);
+  if (typeof changed === 'string') return { path: file, action: 'skipped', reason: changed };
+  if (!changed) return { path: file, action: 'exists' };
+  const writeProblem = writeSettings(file, settings);
+  if (writeProblem) return { path: file, action: 'skipped', reason: writeProblem };
+  return { path: file, action: read.state === 'absent' ? 'created' : 'updated' };
+}
+
 // Registers the PreToolUse hook that converts attached documents to Markdown
 // before the model reads them. PreToolUse rather than PostToolUse because the
 // point is to intervene before a pptx lands in the context window; afterwards
@@ -1247,6 +1268,7 @@ export function installAll({ force = false } = {}) {
     sessionStartHook: installSessionStartHook(),
     delegationHook: installDelegationHook(),
     delegationMeterMod: installDelegationMeterMod(),
+    statuslineMod: installStatuslineMod(),
     briefHook: installBriefHook(),
     cacheMonitorMigration: migrateLegacyCacheMonitorHook(),
     legacy: removeLegacyCommand(),

package/src/model-alias.js

@@ -371,18 +371,59 @@ function addVote(votes, pid, role, kind) {
 }
 
 /**
- * Read one main transcript: which profile id the session itself ran on, and
- * which role each Task/Agent tool_use asked for (joined later by tool_use id).
+ * The model id Claude Code told a transcript's agent it runs on: the
+ * `attachment.type === 'model'` record (`identity.modelId`) written at the
+ * start of a session and of every subagent run. On a gateway `message.model`
+ * is an opaque profile ARN, while this names what the alias resolved to.
+ */
+function declaredModelOf(entry) {
+  const a = entry?.type === 'attachment' ? entry.attachment : null;
+  if (!a || a.type !== 'model') return null;
+  const id = a.identity?.modelId;
+  return typeof id === 'string' && id ? id : null;
+}
+
+/**
+ * The role one delegated run votes for its profile id, or null for no vote.
+ *
+ * What the run was told it is outranks what its caller asked for. A Task that
+ * asks for haiku in a session whose haiku alias resolves to nothing runs on
+ * the session model instead: the Claude Desktop app does this when its
+ * provider settings register no haiku model, and the transcript keeps the
+ * `model: "haiku"` request while the run answers on the parent's profile.
+ * Counting the request stamped that profile 'haiku' through the explicit-veto
+ * path in tallyVotes (1 explicit vote against 4,153 inferred 'main' ones,
+ * measured 2026-10-12), and once the gateway table aged out every record of
+ * the session model would have priced as Haiku.
+ *
+ * A declared id that names a family decides. One that is opaque too (an alias
+ * pointed at a profile ARN) and equals the parent's own declared model means
+ * the run fell back, so it says nothing about the tier it was asked for.
+ * Transcripts written before the declaration existed keep voting the request.
+ */
+export function voteRole(requested, declared, parentDeclared) {
+  const stated = roleFromModelParam(declared);
+  if (stated) return stated;
+  if (declared && declared === parentDeclared && requested && !rolesAgree(requested, 'main')) return null;
+  return requested || null;
+}
+
+/**
+ * Read one main transcript: which profile id the session itself ran on, the
+ * model it was declared to run on, and which role each Task/Agent tool_use
+ * asked for (joined later by tool_use id).
  */
 async function scanMainTranscript(path, votes, requestedByToolUse, agentTypeCache) {
   let sawGateway = false;
+  let declared = null;
   const rl = createInterface({
     input: createReadStream(path, { encoding: 'utf8' }),
     crlfDelay: Infinity,
   });
   try {
     for await (const line of rl) {
-      if (!line.includes('arn:aws:bedrock:') && !line.includes('"Task"') && !line.includes('"Agent"')) {
+      if (!line.includes('arn:aws:bedrock:') && !line.includes('"Task"') && !line.includes('"Agent"')
+        && !line.includes('"identity"')) {
         continue;
       }
       let entry;
@@ -391,6 +432,7 @@ async function scanMainTranscript(path, votes, requestedByToolUse, agentTypeCach
       } catch {
         continue;
       }
+      if (!declared && entry.isSidechain !== true) declared = declaredModelOf(entry);
       const msg = entry.message;
       if (!msg) continue;
 
@@ -418,31 +460,36 @@ async function scanMainTranscript(path, votes, requestedByToolUse, agentTypeCach
   } finally {
     rl.close();
   }
-  return sawGateway;
+  return { sawGateway, declared };
 }
 
-/** First profile id used by a subagent transcript (a run uses exactly one). */
-async function subagentProfileId(path) {
+/**
+ * First profile id used by a subagent transcript (a run uses exactly one),
+ * and the model the run was declared to run on, which comes before it.
+ */
+async function subagentModelInfo(path) {
+  let declared = null;
   const rl = createInterface({
     input: createReadStream(path, { encoding: 'utf8' }),
     crlfDelay: Infinity,
   });
   try {
     for await (const line of rl) {
-      if (!line.includes('arn:aws:bedrock:')) continue;
+      if (!line.includes('arn:aws:bedrock:') && !line.includes('"identity"')) continue;
       let entry;
       try {
         entry = JSON.parse(line);
       } catch {
         continue;
       }
+      declared ??= declaredModelOf(entry);
       const pid = profileIdFrom(entry.message?.model);
-      if (pid) return pid;
+      if (pid) return { pid, declared };
     }
   } finally {
     rl.close();
   }
-  return null;
+  return { pid: null, declared };
 }
 
 /** Subagent transcripts a session spawned (mirrors subagent-records layout). */
@@ -580,7 +627,8 @@ function newestFirst(paths) {
  * The join is exact rather than time-windowed: `.meta.json` carries the
  * `toolUseId` of the Task block that spawned the run, and that block names the
  * model tier. A subagent transcript uses exactly one profile id, so the run's
- * id and the requested role identify each other.
+ * id and the requested role identify each other, unless the run declares that
+ * it ran on another model (see voteRole).
  *
  * @param {object}   opts
  * @param {string[]} opts.sessionPaths transcripts to read, in any order — they
@@ -597,8 +645,9 @@ export async function learnProfileMapping({ sessionPaths = [], maxSessions = 40
   for (const sessionPath of newestFirst(sessionPaths).slice(0, maxSessions)) {
     const requestedByToolUse = new Map();
     let sawGateway = false;
+    let parentDeclared = null;
     try {
-      sawGateway = await scanMainTranscript(sessionPath, votes, requestedByToolUse, agentTypeCache);
+      ({ sawGateway, declared: parentDeclared } = await scanMainTranscript(sessionPath, votes, requestedByToolUse, agentTypeCache));
     } catch {
       continue;
     }
@@ -609,14 +658,16 @@ export async function learnProfileMapping({ sessionPaths = [], maxSessions = 40
       try {
         meta = JSON.parse(await readFile(jsonl.replace(/\.jsonl$/, '.meta.json'), 'utf8'));
       } catch { /* pre-toolUseId runs simply cast no vote */ }
-      const role = (meta?.toolUseId && requestedByToolUse.get(meta.toolUseId))
+      const requested = (meta?.toolUseId && requestedByToolUse.get(meta.toolUseId))
         || roleFromAgentType(meta?.agentType, agentTypeCache);
-      if (!role) continue;
-      const pid = await subagentProfileId(jsonl);
+      if (!requested) continue;
+      const { pid, declared } = await subagentModelInfo(jsonl);
       if (!pid) continue;
+      const role = voteRole(requested, declared, parentDeclared);
+      if (!role) continue;
       sawGateway = true;
       // Stated evidence: the Task call named this tier, or the agent
-      // definition it used did.
+      // definition it used did, or the run itself declared what it ran on.
       addVote(votes, pid, role, 'explicit');
     }
     if (sawGateway) gateway = true;

package/src/route-inject.js

@@ -111,6 +111,29 @@ export function sessionModelRank({ env = process.env, transcriptPath = null, sna
   return rankOf(snap && snap.model);
 }
 
+/**
+ * Tiers a delegation cannot reach in this session, because the alias the hint
+ * names resolves to no model here.
+ *
+ * A host that manages the provider writes the ANTHROPIC_DEFAULT_*_MODEL
+ * variables itself, from the models registered in its own settings, and
+ * leaves the unregistered ones empty; settings.json `env` does not override
+ * them. The Claude Desktop app does this in its third-party mode
+ * (CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST=1), and a Task(model: "haiku") there
+ * runs on the session model. Measured 2026-10-12: with no haiku registered the
+ * run answered on the parent's Opus profile, and after registering one, on the
+ * Haiku profile. Hinting a delegation in that state costs a subagent's context
+ * and saves nothing. Outside such a host an unset variable selects Claude
+ * Code's built-in default for the tier, so nothing is reported unreachable.
+ */
+const TIER_ALIAS_ENV = { T2: 'ANTHROPIC_DEFAULT_HAIKU_MODEL', T1: 'ANTHROPIC_DEFAULT_SONNET_MODEL' };
+const TIER_ALIAS = { T2: 'haiku', T1: 'sonnet' };
+
+export function unreachableTiers(env = process.env) {
+  if (env.CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST !== '1') return [];
+  return Object.keys(TIER_ALIAS_ENV).filter((tier) => !env[TIER_ALIAS_ENV[tier]]);
+}
+
 /**
  * The rules a prompt matches, or null when the hint should stay quiet.
  *
@@ -120,9 +143,13 @@ export function sessionModelRank({ env = process.env, transcriptPath = null, sna
  * @param {number|null} [opts.sessionRank] price rank of the model reading the
  *   hint (see sessionModelRank). null means unknown, and an unknown session
  *   model filters nothing.
- * @returns {{cat: object, t2: object|undefined, t1: object|undefined}|null}
+ * @param {object} [opts.env] environment to read tier aliases from (see
+ *   unreachableTiers)
+ * @returns {{cat: object, t2: object|undefined, t1: object|undefined, unreachable?: string[]}|null}
+ *   `unreachable` is set, with neither t2 nor t1, when every matching tier is
+ *   one this session cannot reach
  */
-export function routeMatch(text, { rules, sessionRank = null, root } = {}) {
+export function routeMatch(text, { rules, sessionRank = null, root, env = process.env } = {}) {
   const t = String(text || '').trim();
   if (t.length < MIN_LEN) return null;
   // Judgement and irreversible work stay on the top tier. This check comes
@@ -167,9 +194,15 @@ export function routeMatch(text, { rules, sessionRank = null, root } = {}) {
     ? matched
     : matched.filter((r) => worthDelegating(r.tier, sessionRank));
   if (!usable.length) return null;
+  // A tier whose alias resolves to nothing would run on the session model, so
+  // it is dropped like a tier that saves nothing. When that empties the list
+  // the match is still reported, so the hint can say why it does not delegate.
+  const unreachable = unreachableTiers(env);
+  const reachable = usable.filter((r) => !unreachable.includes(r.tier));
+  if (!reachable.length) return { cat, unreachable: [...new Set(usable.map((r) => r.tier))] };
 
   // The closest scope states the cap, whatever order the registry holds.
-  const nearest = [...usable].sort((a, b) => scopeRank(b) - scopeRank(a));
+  const nearest = [...reachable].sort((a, b) => scopeRank(b) - scopeRank(a));
   const t2 = nearest.find((r) => r.tier === 'T2');
   const t1 = nearest.find((r) => r.tier === 'T1');
   return t2 || t1 ? { cat, t2, t1 } : null;
@@ -184,6 +217,24 @@ export function matchCaps(match) {
   return caps;
 }
 
+/**
+ * What the hint says instead of a delegation when every matching tier is
+ * unreachable (see unreachableTiers). The model is told to work directly, and
+ * to pass the fix on once: the registration lives in the app's settings,
+ * which only the user can change.
+ */
+function unreachableNotice(label, tiers, ko) {
+  const models = tiers.map((t) => TIER_ALIAS[t]).join(', ');
+  return ko
+    ? `[sprag] 이 요청은 위임 룰 "${label}" 에 해당하지만, 이 세션에는 ${models} 모델이 등록되어 있지 않습니다. `
+      + `위임해도 세션 모델이 그대로 처리하므로 비용이 줄지 않으니, 위임하지 말고 직접 처리하십시오. `
+      + `이 안내를 이번 세션에서 처음 받았다면 답변 끝에 "Claude 앱 설정에 ${models} 모델을 등록하면 이런 요청을 더 싼 모델에 맡길 수 있습니다."라고 사용자에게 한 줄로 알리십시오.`
+    : `[sprag] This request matches the delegation rule "${label}", but no ${models} model is registered for this session, `
+      + `so a delegated run would stay on the session model and save nothing. Handle it directly instead of delegating. `
+      + `If this is the first such notice in this session, end your reply with one line for the user: `
+      + `"Register a ${models} model in the Claude app settings to hand requests like this to a cheaper model."`;
+}
+
 /**
  * @param {string} text the prompt just submitted
  * @param {object} [opts] as routeMatch, plus:
@@ -194,12 +245,13 @@ export function matchCaps(match) {
  * @param {object|null} [opts.match] a routeMatch result the caller already has
  * @returns {string|null} the line to inject, or null to stay quiet
  */
-export function routeHint(text, { rules, lang = userLanguage(), root, sessionRank = null, match } = {}) {
-  const found = match === undefined ? routeMatch(text, { rules, sessionRank, root }) : match;
+export function routeHint(text, { rules, lang = userLanguage(), root, sessionRank = null, match, env } = {}) {
+  const found = match === undefined ? routeMatch(text, { rules, sessionRank, root, env }) : match;
   if (!found) return null;
   const { cat, t2, t1 } = found;
   const ko = lang === 'ko';
   const label = ko ? (cat.label || cat.id) : (cat.labelEn || cat.label || cat.id);
+  if (!t2 && !t1 && found.unreachable?.length) return unreachableNotice(label, found.unreachable, ko);
   // `root` is threaded through to agentPhrase, which names the subagent only
   // when its .md actually exists on this machine. A caller that pins it can
   // therefore get a deterministic phrase; a test that does not pin it reads