sprag-cli 3.65.0 → 3.67.0

package/bin/cli.js

@@ -90,7 +90,7 @@ function tableColor() {
 const KNOWN_SUBCOMMANDS = new Set([
   'last', 'brief', 'history', 'handoff', 'install', 'uninstall', 'mode', 'korean', 'cohesion',
   'doc2md', 'delegate', 'harness', 'route-scan', 'compact-window', 'update-check', 'upgrade',
-  'seed', 'litellm-budget', 'profile-map', 'feedback', 'saved',
+  'seed', 'litellm-budget', 'profile-map', 'feedback', 'saved', 'cowork',
 ]);
 
 const USAGE = `sprag — Claude Code and Codex agent harness
@@ -116,6 +116,7 @@ Usage:
   sprag uninstall --agent codex   remove the global Codex integration
       --agent claude|codex (default: claude; accepted before or after subcommands)
   sprag route-scan         detect recurring easy work → delegation candidates
+  sprag delegate agents [on|off]   tool-restricted delegation agents (no MCP tools)
   sprag profile-map        show/refresh the gateway model map (LiteLLM /model/info)
   sprag install            set up everything (presets, and Codex when present) without asking
   sprag install --manual   confirm each optional step
@@ -127,6 +128,7 @@ Usage:
   sprag handoff            write a session handoff file
   sprag mode [keywords]    statusline preferences (icon/text, en/ko, window, ttl)
   sprag seed               register the bundled starter rules, one answer at a time
+  sprag cowork [sync|on|off|exclude <dir>|include <dir>]   copy the ratchet rules into Cowork tab folders
   sprag korean on|off|status     Korean writing guidance + write-time check
   sprag cohesion on|off|status   English sentence-connection guidance
   sprag doc2md on|off|<file>     convert documents to Markdown before the model reads them
@@ -290,6 +292,11 @@ async function main() {
     return (await import('../src/commands/seed.js')).run({ args, hasFlag });
   }
 
+  // Subcommand: cowork — ratchet copies for the Claude app's Cowork tab.
+  if (args[0] === 'cowork') {
+    return (await import('../src/commands/cowork.js')).run({ args, hasFlag });
+  }
+
   // Subcommand: saved — stopwatch reset for the lifetime "saved" counters.
   //   sprag saved | saved reset [routing|doc2md|all] | saved undo
   if (args[0] === 'saved') {

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.67.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/presets/ratchet-rules.json

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

package/src/agents.js

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

package/src/commands/cowork.js

@@ -0,0 +1,107 @@
+/**
+ * Subcommand: cowork : keep the Claude app's Cowork tab on the same ratchet rules.
+ *
+ *   sprag cowork                  status
+ *   sprag cowork sync             discover connected folders and write the copies now
+ *   sprag cowork on | off         turn the sync on (and sync) or off (and remove the copies)
+ *   sprag cowork exclude <dir>    never write into <dir> (removes its copy)
+ *   sprag cowork include <dir>    undo exclude (and sync)
+ */
+
+import { resolve } from 'node:path';
+import { realpathSync } from 'node:fs';
+
+const REASONS = {
+  ko: {
+    'not-absolute': '절대 경로가 아님', missing: '폴더가 없음', 'not-a-directory': '디렉터리가 아님',
+    'home-or-ancestor': '홈 디렉터리 또는 그 상위 경로', 'inside-claude-dir': '~/.claude 안',
+    'inside-library': '~/Library 안', 'inside-sprag-data': 'sprag 데이터 폴더 안', excluded: '제외 목록에 있음',
+    'not-owned': '같은 이름의 사용자 파일이 있어 덮어쓰지 않음', 'no-source': '복사할 원본 래칫 파일이 없음',
+  },
+  en: {
+    'not-absolute': 'not an absolute path', missing: 'folder does not exist', 'not-a-directory': 'not a directory',
+    'home-or-ancestor': 'the home directory or one of its parents', 'inside-claude-dir': 'inside ~/.claude',
+    'inside-library': 'inside ~/Library', 'inside-sprag-data': 'inside the sprag data folder', excluded: 'on the exclude list',
+    'not-owned': 'a user file of the same name exists, not overwritten', 'no-source': 'no source ratchet file to copy',
+  },
+};
+
+const norm = (p) => {
+  const abs = resolve(p);
+  try { return realpathSync(abs); } catch { return abs; }
+};
+
+export async function run({ args }) {
+  const cw = await import('../cowork-sync.js');
+  const { userLanguage } = await import('../config.js');
+  const ko = userLanguage() === 'ko';
+  const why = (r) => (REASONS[ko ? 'ko' : 'en'][r] || r);
+  const sub = args[1];
+
+  const summarize = (r) => {
+    console.log(ko
+      ? `Cowork 래칫 동기화: 새로 씀 ${r.written.length}, 변경 없음 ${r.unchanged.length}, 건너뜀 ${r.skipped.length}, 제거 ${r.removed.length}`
+      : `Cowork ratchet sync: written ${r.written.length}, unchanged ${r.unchanged.length}, skipped ${r.skipped.length}, removed ${r.removed.length}`);
+    for (const d of r.written) console.log(`  + ${d}`);
+    for (const d of r.removed) console.log(`  - ${d}`);
+    for (const s of r.skipped) console.log(`  ! ${s.dir} (${why(s.reason)})`);
+  };
+
+  if (sub === 'sync') return summarize(cw.syncCoworkRatchets({ discover: true }));
+
+  if (sub === 'off') {
+    cw.saveCoworkConfig({ sync: false });
+    console.log(ko ? 'Cowork 래칫 동기화를 껐습니다. 만들어 둔 사본을 지웁니다.' : 'Cowork ratchet sync is off. Removing the copies it made.');
+    return summarize(cw.removeCoworkRatchets());
+  }
+
+  if (sub === 'on') {
+    cw.saveCoworkConfig({ sync: true });
+    console.log(ko ? 'Cowork 래칫 동기화를 켰습니다.' : 'Cowork ratchet sync is on.');
+    return summarize(cw.syncCoworkRatchets({ discover: true }));
+  }
+
+  if (sub === 'exclude' || sub === 'include') {
+    const target = args.slice(2).find((a) => !a.startsWith('-'));
+    if (!target) {
+      console.error(ko ? '폴더 경로를 지정하십시오.' : 'Pass a folder path.');
+      process.exitCode = 1;
+      return;
+    }
+    const dir = norm(target);
+    const list = cw.coworkConfig().exclude;
+    if (sub === 'exclude') {
+      if (!list.includes(dir)) cw.saveCoworkConfig({ exclude: [...list, dir] });
+      const removed = cw.removeCoworkRatchetIn(dir);
+      console.log(ko
+        ? `제외 목록에 추가했습니다: ${dir}${removed ? ' (사본을 지웠습니다)' : ''}`
+        : `Added to the exclude list: ${dir}${removed ? ' (copy removed)' : ''}`);
+      return;
+    }
+    cw.saveCoworkConfig({ exclude: list.filter((x) => x !== dir && norm(x) !== dir) });
+    console.log(ko ? `제외 목록에서 뺐습니다: ${dir}` : `Removed from the exclude list: ${dir}`);
+    return summarize(cw.syncCoworkRatchets({ discover: true }));
+  }
+
+  if (sub !== undefined) {
+    console.error(ko ? `알 수 없는 하위 명령입니다: ${sub}` : `Unknown subcommand: ${sub}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const st = cw.coworkStatus();
+  console.log(ko ? `Cowork 래칫 동기화: ${st.enabled ? '켜짐' : '꺼짐'}` : `Cowork ratchet sync: ${st.enabled ? 'on' : 'off'}`);
+  console.log(ko ? `마지막 동기화: ${st.lastSync || '없음'}` : `Last sync: ${st.lastSync || 'never'}`);
+  if (st.folders.length === 0) {
+    console.log(ko ? '발견한 Cowork 연결 폴더가 없습니다.' : 'No Cowork folders discovered.');
+    return;
+  }
+  console.log(ko ? '연결 폴더:' : 'Connected folders:');
+  for (const f of st.folders) {
+    const state = f.hasCopy ? (ko ? '사본 있음' : 'copy present')
+      : f.foreign ? why('not-owned')
+      : f.eligible ? (ko ? '사본 없음' : 'no copy yet')
+      : (ko ? `제외: ${why(f.reason)}` : `skipped: ${why(f.reason)}`);
+    console.log(`  ${f.dir}  [${state}]`);
+  }
+}

package/src/commands/delegate.js

@@ -59,6 +59,13 @@ export async function run({ args, hasFlag }) {
   const { userLanguage } = await import('../config.js');
   const lang = userLanguage();
 
+  // `delegate agents` manages the tool-restricted subagent files. It is split
+  // off by the second word so it never mixes with the on/off PreToolUse guard.
+  if (sub === 'agents') {
+    await agentsCommand(args[2], lang);
+    return;
+  }
+
   if (sub === 'on') {
     // Install first, and only record the feature as on once that worked.
     // Saving the flag first left `delegate: on, hook not registered` behind
@@ -131,3 +138,39 @@ export async function run({ args, hasFlag }) {
     console.log('Enable with: sprag delegate on');
   }
 }
+
+async function agentsCommand(action, lang) {
+  const ko = lang === 'ko';
+  const da = await import('../delegation-agents.js');
+  const report = (r) => {
+    for (const n of r.written) console.log(ko ? `✓ ${n} 에이전트를 설치했습니다.` : `✓ installed agent ${n}`);
+    for (const n of r.unchanged) console.log(ko ? `  ${n} 에이전트는 이미 최신입니다.` : `  agent ${n} is already current`);
+    for (const k of r.skipped) {
+      console.log(ko
+        ? `✗ ${k.name} 에이전트는 건너뛰었습니다 (${k.reason === 'not-owned' ? '직접 만든 같은 이름의 파일이 있습니다' : k.reason}).`
+        : `✗ skipped agent ${k.name} (${k.reason})`);
+    }
+    for (const n of r.removed) console.log(ko ? `✓ ${n} 에이전트를 제거했습니다.` : `✓ removed agent ${n}`);
+  };
+  const rerender = async () => {
+    try { (await import('../model-rules.js')).syncAllFiles(); } catch { /* the next session start re-renders */ }
+  };
+
+  if (action === 'on' || action === 'off') {
+    const { loadConfig, saveConfig } = await import('../config.js');
+    saveConfig({ ...loadConfig(), delegationAgents: action === 'on' });
+    const r = action === 'on' ? da.syncDelegationAgents() : da.removeDelegationAgents();
+    await rerender();
+    report(r);
+    console.log(action === 'on'
+      ? (ko ? '위임 전용 에이전트를 켰습니다. 래칫 문구가 에이전트 이름으로 다시 만들어졌습니다.' : 'Delegation agents are on. The ratchet wording was re-rendered with the agent names.')
+      : (ko ? '위임 전용 에이전트를 껐습니다. 래칫 문구가 model 지정 방식으로 다시 만들어졌습니다.' : 'Delegation agents are off. The ratchet wording was re-rendered with plain model tiers.'));
+    return;
+  }
+
+  const st = da.delegationAgentStatus();
+  console.log(ko ? `delegate agents: ${st.enabled ? 'on' : 'off'}` : `delegate agents: ${st.enabled ? 'on' : 'off'}`);
+  const label = { 'installed-by-sprag': ko ? 'sprag 가 설치함' : 'installed by sprag', 'user-file': ko ? '직접 만든 파일' : 'user file', absent: ko ? '없음' : 'absent' };
+  for (const a of st.agents) console.log(`  ${a.name}: ${a.state} (${label[a.state]})`);
+  console.log(ko ? '켜기 또는 끄기: sprag delegate agents on|off' : 'Toggle with: sprag delegate agents on|off');
+}

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;
   }