sprag-cli 3.65.0 → 3.67.0

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/harness.js

@@ -70,7 +70,7 @@ function ratchetMdPath(root) {
   return join(root, '.claude', 'ratchet.md');
 }
 
-function globalRatchetMdPath() {
+export function globalRatchetMdPath() {
   return join(homedir(), '.claude', 'ratchet.md');
 }
 

package/src/implementation-delegation.js

@@ -1,11 +1,14 @@
+import { agentPhrase, agentPhraseEn, resolveAgentName } from './agents.js';
+
 /** Shared policy, rendered with each client's native model selector. */
 export function implementationDelegationRule(agent = 'claude', lang = 'en') {
   const target = agent === 'codex'
     ? 'the resolved T1 model for the current parent model and provider (explicit mapping first, automatic resolution otherwise)'
-    : 'a model: sonnet subagent';
+    : (resolveAgentName('sonnet', null) ? agentPhraseEn('sonnet', { root: null }) : 'a model: sonnet subagent');
+  const targetKo = resolveAgentName('sonnet', null) ? agentPhrase('sonnet', { root: null }) : 'model: sonnet 서브에이전트';
   if (lang === 'ko') return [
     '- **구현 분업**: 여러 파일을 고칠 때 설계와 스펙 확정은 메인 모델이 맡습니다.',
-    `  구현은 ${agent === 'codex' ? '현재 부모 모델과 프로바이더의 T1 모델' : 'model: sonnet 서브에이전트'}에 위임합니다.`,
+    `  구현은 ${agent === 'codex' ? '현재 부모 모델과 프로바이더의 T1 모델' : targetKo}에 위임합니다.`,
     '  Claude는 sonnet을 쓰고, Codex는 명시적 T1 매핑을 우선하며 없으면 자동 해석한 T1을 씁니다.',
     '  두 모델의 성능이 같다고 가정하지 않으며 haiku나 T2에 구현을 맡기지 않습니다.',
     '  위임 프롬프트에는 설계, 수정할 파일, 제약, 완료 기준, 테스트 명령, 예산과',

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/model-rules.js

@@ -33,7 +33,7 @@ import { join, dirname } from 'node:path';
 import { homedir } from 'node:os';
 import { userDataDir } from './paths.js';
 import { userLanguage } from './config.js';
-import { agentPhrase, agentPhraseEn } from './agents.js';
+import { agentPhrase, agentPhraseEn, resolveAgentName } from './agents.js';
 import { writeStateFile } from './state-file.js';
 import { signedUsd } from './money.js';
 import { implementationDelegationRule } from './implementation-delegation.js';
@@ -132,16 +132,23 @@ function shortExample(text) {
   return one.length <= EXAMPLE_MAX ? one : `${one.slice(0, EXAMPLE_MAX - 1)}…`;
 }
 
+// T1 is named through its delegation agent only when that file exists; without
+// it the literal `model: sonnet` stays so output on such machines is unchanged.
+function t1Target(root, ko) {
+  if (resolveAgentName('sonnet', root) === null) return null;
+  return (ko ? agentPhrase : agentPhraseEn)('sonnet', { root });
+}
+
 export function modelRuleBaseText(g, lang = userLanguage(), { root } = {}) {
   if (lang === 'ko') {
     return g.tier === 'T2'
       ? `"${g.label}" 단순 요청(예: "${shortExample(g.example)}")은 ${agentPhrase(g.agent, { root })}에 위임`
-      : `"${g.label}" 중간 난도 요청(예: "${shortExample(g.example)}")은 model: sonnet에 위임`;
+      : `"${g.label}" 중간 난도 요청(예: "${shortExample(g.example)}")은 ${t1Target(root, true) ?? 'model: sonnet'}에 위임`;
   }
   const example = g.exampleEn || g.example;
   return g.tier === 'T2'
     ? `Simple "${g.labelEn}" requests (e.g. "${shortExample(example)}") go to ${agentPhraseEn(g.agent, { root })}`
-    : `Moderate "${g.labelEn}" requests (e.g. "${shortExample(example)}") go to a model: sonnet subagent`;
+    : `Moderate "${g.labelEn}" requests (e.g. "${shortExample(example)}") go to ${t1Target(root, false) ?? 'a model: sonnet subagent'}`;
 }
 
 // See the note in route-scan.js — paths.js is the only place that resolves
@@ -401,10 +408,10 @@ export function renderModelRatchet(rules, lang = userLanguage(), { root } = {})
       // match at a glance.
       const rule = ko
         ? `"${t2.label}": 기본 ${agentPhrase(t2.agent, { root })}(예: "${ex(t2)}"), ` +
-          `여러 단계·여러 파일이 얽히면 model: sonnet(예: "${ex(t1)}"). ` +
+          `여러 단계·여러 파일이 얽히면 ${t1Target(root, true) ?? 'model: sonnet'}(예: "${ex(t1)}"). ` +
           mergedBudget(t2, t1)
         : `"${t2.labelEn || t2.label}": ${agentPhraseEn(t2.agent, { root })} by default (e.g. "${ex(t2)}"), ` +
-          `model: sonnet when it spans multiple steps or file edits (e.g. "${ex(t1)}"). ` +
+          `${t1Target(root, false) ?? 'model: sonnet'} when it spans multiple steps or file edits (e.g. "${ex(t1)}"). ` +
           mergedBudget(t2, t1);
       lines.push(`- ${rule}${healthOf(t2)}${healthOf(t1)}${extraHealth} <!-- T2 ${statsOf(t2)} / T1 ${statsOf(t1)}${extraStats} -->`);
     } else if (t2 || t1) {

package/src/route-inject.js

@@ -34,7 +34,7 @@
 import { categorizeScored, ESCALATE_RE, EDIT_RE, worthDelegating } from './route-scan.js';
 import { loadModelRules, budgetCapPhrase, ruleBudget } from './model-rules.js';
 import { sharedProjectRoots, realProjectRoot, scopeRank } from './shared-model-rules.js';
-import { agentPhrase, agentPhraseEn } from './agents.js';
+import { agentPhrase, agentPhraseEn, resolveAgentName } from './agents.js';
 import { userLanguage } from './config.js';
 import { aliasForRole, resolveModelAlias } from './model-alias.js';
 import { isRecognizedModelId, modelRank } from './cost.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
@@ -207,11 +259,16 @@ export function routeHint(text, { rules, lang = userLanguage(), root, sessionRan
   const raw = ko ? agentPhrase : agentPhraseEn;
   const phrase = (name) => raw(name, root === undefined ? undefined : { root });
 
+  // T1 is named through its delegation agent only when that file exists here;
+  // otherwise the literal tier string stays, so output without agents is unchanged.
+  const t1Root = root === undefined ? undefined : root;
+  const t1Named = resolveAgentName('sonnet', t1Root) !== null;
+  const t1Phrase = t1Named ? phrase('sonnet') : 'model: sonnet';
   let target;
   if (t2 && t1) {
     target = ko
-      ? `기본 ${phrase(t2.agent)}, 여러 단계·여러 파일이 얽히면 model: sonnet`
-      : `${phrase(t2.agent)} by default, model: sonnet when it spans multiple steps or file edits`;
+      ? `기본 ${phrase(t2.agent)}, 여러 단계·여러 파일이 얽히면 ${t1Phrase}`
+      : `${phrase(t2.agent)} by default, ${t1Phrase} when it spans multiple steps or file edits`;
   } else {
     const only = t2 || t1;
     target = ko ? phrase(only.agent) : phrase(only.agent);