sprag-cli 3.69.0 → 3.71.0

package/docs/TEAM.md

@@ -0,0 +1,175 @@
+# Team layer
+
+[← README](../README.md) · [한국어](./TEAM.ko.md)
+
+Sprag is local-only by default. The team layer is an opt-in add-on that lets a group see each member's daily spend and savings in one dashboard, and share the ratchet rules an owner or admin approves. Nothing is sent until you run `sprag team join <token>` or your environment sets `SPRAG_TEAM_TOKEN`. `SPRAG_NO_TEAM_SYNC=1` stops every usage upload, whatever else is configured.
+
+## What is sent and what is not
+
+After you join, Sprag uploads one row per local calendar day:
+
+| Field | Meaning |
+|---|---|
+| Spend (USD) | priced from your local session logs |
+| Savings (USD) | from the routing and doc2md ledgers |
+| Delegated runs | how many runs were delegated that day |
+| Model-family share | the share of those runs that went to each model family |
+| Sprag version | the installed version |
+| Agent | `claude` or `codex` |
+| Display name | the name you chose at join; the default is your OS user name |
+| Operating system | OS name and version (for example macOS 26, Windows 11, Ubuntu 24.04) and CPU architecture (arm64 or x64); sent once after joining and again only if it changes. Nothing that identifies the machine by name: no hostname, no user name, no path |
+
+Not sent: prompts, transcripts, file paths, project names, rule text, API keys. The one exception is the opt-in prompt upload of an Enterprise team with prompt capture on, described under "Prompt usage (Enterprise)". A rule leaves your machine only when you run `sprag team propose` yourself.
+
+The daily aggregate upload runs at most once every 6 hours after the last successful one, from a detached child process that the SessionStart hook (and the prompt hook, which only reads a small local file) spawns. If a sync fails, for example because the network is down, it is retried after 15, then 30, then 60 minutes (60 at most) instead of waiting 6 hours. The CLI remembers the last day it uploaded and re-sends from the day before it, up to 30 days, so a machine that was offline for days catches up on its first successful sync. Re-sending a day is safe because each day is an upsert. The prompt upload of an Enterprise team with capture on has its own 30-minute timer (see "Prompt usage (Enterprise)"). It never runs on the statusline path.
+
+Destination: `https://hiycfjwswtkixyoqkznm.supabase.co/rest/v1/rpc/*` (Supabase, region ap-northeast-2). The calls are the RPCs `team_join`, `ledger_upsert`, `team_rules_get`, `team_rule_propose`, `team_leave`, `prompt_chunk_put` (Enterprise prompt capture only) and `member_set_sync` (the upload-switch status call, see "The upload switch"); `sprag team create` also calls `team_create` with your sign-in session.
+
+## Create a team from the CLI
+
+You can set up a team without the web dashboard. Signing in uses a 6-digit code emailed to you (valid 15 minutes). Sprag never stores the sign-in session.
+
+In a terminal, run one command and answer the prompts (email, code, team name):
+
+```bash
+sprag team create
+```
+
+From an agent or any shell without a terminal, it takes two steps:
+
+```bash
+sprag team create --email you@example.com --name "Acme"
+# the code arrives by email, then:
+sprag team create --email you@example.com --name "Acme" --code 123456
+```
+
+The first step only sends the code. The second verifies it and creates the team. It then prints the invite token, the member command (`npm i -g sprag-cli@latest && sprag team join <token>`), the organization line (`export SPRAG_TEAM_TOKEN=<token>`) and the dashboard address. Sign in to https://sprag.io/team/ with the same email to manage the team.
+
+By default this machine joins as the first member and runs one sync. Pass `--no-join` to skip that. If this machine is already in a team, run `sprag team leave` first or pass `--no-join`.
+
+## Join as an individual
+
+An owner or admin gives you an invite token. Then:
+
+```bash
+sprag team join <token> --name "Mina"
+```
+
+Sprag prints the list of what will be uploaded and asks for confirmation. `--name` sets the display name (default: your OS user name). In a shell without a terminal, pass `--yes` to confirm. If you leave the token out, Sprag reads `SPRAG_TEAM_TOKEN`.
+
+Check the result with `sprag team status`.
+
+## Enroll an organization
+
+To enroll every machine without each person running a command, set `SPRAG_TEAM_TOKEN=<token>` in the environment. Two common places:
+
+- a shell profile: `export SPRAG_TEAM_TOKEN=<token>`
+- Claude Code managed settings: `{"env":{"SPRAG_TEAM_TOKEN":"…"}}`
+
+The machine joins at the next session start. The first session after that prints a one-line notice that names the team and the two commands that matter: `sprag team status --show-payload` shows what is sent, and `sprag team leave` stops it.
+
+`leave` wins over the environment. A machine that left does not rejoin on its own, even with the variable still set. It rejoins only after an owner or admin issues a new token and the member runs `sprag team join` again.
+
+## Team rules
+
+Rules come at two levels. **Organization rules** apply to every team in the organization; owners and admins write them on the Rules tab of the dashboard. **Team rules** apply to one team; owners and admins approve them there too. An approved team rule can be applied to the whole organization with one click ("Apply to whole organization"): it moves to the organization level and its team copy is retired, so no machine receives it twice.
+
+Members can suggest a team rule:
+
+```bash
+sprag team propose "Run lint before every commit" --scope ratchet
+```
+
+`--scope` is `ratchet` (the default) or `model`. A proposal stays pending until an owner or admin approves it.
+
+**When a rule arrives.** Approved rules reach a machine at its next session start. A machine checks for new rules at most every hour and uploads usage every 6 hours; `sprag team sync --force` then a new session applies them at once. Both kinds of sync rewrite the rule files as soon as the rules arrive, so the next session reads them without another round trip. `sprag team sync --rules-only` pulls the rules alone and uploads nothing.
+
+Sprag writes the rules to `~/.claude/ratchet-team.md` (Codex: `<CODEX_HOME>/ratchet-team.md`), organization rules first and then team rules, each with its model rules in a sub-section, and imports that file from the global harness block of `~/.claude/CLAUDE.md` for as long as the file exists. Do not edit the file by hand, because Sprag rewrites it. `sprag team rules` lists the cached rules as `- [org · model] text` or `- [team · ratchet] text`. `sprag team leave` removes the member key, the cache and the import.
+
+## Status, payload and leaving
+
+| Command | What it does |
+|---|---|
+| `sprag team join [token] [--name <n>] [--yes]` | Join a team |
+| `sprag team status [--show-payload]` | Team, plan, prompt-capture flag, display name, last sync. `--show-payload` also prints the device info and the exact daily rows that would be uploaded |
+| `sprag team sync [--force] [--rules-only]` | Upload now and pull rules. `--force` ignores the 6-hour interval; `--rules-only` pulls the organization and team rules and uploads nothing |
+| `sprag team rules` | Show the cached organization and team rules |
+| `sprag team propose "<text>" [--scope ratchet\|model]` | Propose a rule to the team |
+| `sprag team leave` | Leave the team and stop uploading |
+
+## Organizations and seats
+
+Every team belongs to an organization, and seats are bought per organization, not per team. Teams you create without naming an organization get a new one automatically, so existing setups keep working.
+
+- **What a seat is.** One machine (one member key) that has not left and either sent anything in the last 30 days or is paused. A machine that has been silent for 30 days or more without being paused holds no seat. Members who left are not counted.
+- **Second machine.** When the same person uses two machines, an owner or admin can merge the second one into the first so the two share one seat. In the dashboard, use "Merge seat" on the member row; "Unmerge" gives it its own seat back. A merged row shows "shares a seat with <name>".
+- **The limit.** Each organization has a seat limit. A join past the limit is refused: `sprag team join` exits 1 with "This organization has no free seat. Ask your organization owner or admin to add seats", and an environment auto-join stays silent and tries again at a later session start. Lowering the limit below current use never removes anyone; it only refuses new joins until Sprag raises it again.
+- **Roles.** There are three permission levels. The superuser is Sprag staff: it sets the plan and the seat limit, suspends organizations, adds owners, and sees every organization at sprag.io/ops/. An owner is a company's top level: it appoints and removes admins, and does everything an admin does. An admin is a company's management level: it creates teams and manages members, rules and seats. The person who created a team has no special rights over it; only the organization's owners and admins and the superuser manage teams. Owners and admins see the seat limit in the dashboard. To add seats, write to sales@sprag.io.
+- **The plan.** Sprag sets the plan (`pro` or `enterprise`) on the organization; owners and admins cannot change it. Prompt capture can be switched on only while the organization is on Enterprise. To change the plan, contact us.
+
+Create a team inside an existing organization from the CLI with `sprag team create --org <org-id>`. The command prints the organization name and how many seats are used. `sprag team status` shows the organization name.
+
+## The upload switch
+
+`SPRAG_NO_TEAM_SYNC=1` (the old name `CTS_NO_TEAM_SYNC` is still read) stops every usage upload. A joined machine sends one status-only call, `member_set_sync`, with no usage data, the first time it sees the switch on, and one more when it is off again. After that it uploads immediately. That call is how the dashboard can tell a paused machine from a silent one. A paused machine keeps its seat until an owner or admin removes it.
+
+## The dashboard
+
+https://sprag.io/team/ is where an owner or admin signs in with an email code, creates a team and gets the invite token. From there they see per-member spend and savings, manage organization and team rules on the Rules tab, and remove members. The organization panel shows the plan, seats used against the limit, admins and every team. The superuser sees every organization at sprag.io/ops/.
+
+A date range control at the top of the dashboard (7d, 30d, 90d, This month, Last month or Custom) sets the period for the members table, the Usage chart and the prompt usage tab. It defaults to the last 30 days, uses your local calendar days with the end date included, and allows 365 days at most. The choice is kept in the page address (`?from=2026-10-01&to=2026-10-18`), so a reload or a shared link shows the same period. The superuser console at /ops/ has the same control for the organization table, the organization header and its prompt usage.
+
+### The seat roster
+
+Owners and admins get a seat roster on /team. Each row is one machine and shows:
+
+- **Upload switch.** On or Off.
+- **Signal.** `ok`: an upload within 48 hours. `late`: the switch is on but there has been no upload for 48 hours or more. `paused`: the switch is off. `silent`: no contact for 30 days or more; the machine holds no seat. `left`: the member ran `sprag team leave`. `removed`: an owner or admin removed it.
+- **Dates and version.** Last upload, last contact, paused since, and the Sprag version.
+
+Row actions:
+
+- **Remove** frees the seat, and the machine's key stops working.
+- **Restore** brings back only machines that an owner or admin removed, and only within the seat limit.
+- **Seat merge** and unmerge, as described above.
+
+Below the roster, an activity log lists joined, paused, resumed, left, removed and restored events, with who did each one: member, owner, admin or superuser.
+
+## Plans
+
+Free, Pro ($5 per seat per month) and Enterprise ($10 per seat per month, with prompt capture and per-user prompt usage). Volume or annual invoicing is a custom agreement; write to sales@sprag.io. Details are on https://sprag.io/pricing/.
+
+## Prompt usage (Enterprise)
+
+Owners and admins of an Enterprise organization get a Prompts tab on sprag.io/team: a per-user table of prompts, characters, average length, active days and last prompt, and a searchable prompt list per user. Prompts are stored only for Enterprise teams that have prompt capture switched on; Pro organizations see a locked state.
+
+**What is captured.** Only the prompts you typed yourself, from your main Claude Code sessions (`~/.claude/projects/**/*.jsonl`) and Codex sessions (`<CODEX_HOME or ~/.codex>/sessions/**/*.jsonl`). Each prompt goes up as its time, the project folder's name (the last part of the path, never the full path) and its text, cut at 20,000 characters. Not captured: assistant replies, tool output, file contents, subagent transcripts, slash-command wrappers, system reminders, or any file path.
+
+**Redaction.** Before upload, obvious secrets are replaced with `[redacted]`: API keys and tokens (`sk-...`, `sk-ant-...`, `ghp_...`, `gho_...`, `github_pat_...`, `AKIA...`, `xox[abpr]-...`), `Bearer` tokens, private key blocks, and `KEY=`, `TOKEN=`, `PASSWORD=` and `SECRET=` assignments. This catches common shapes, not every secret, so do not paste secrets into prompts on a machine with capture on.
+
+**No backfill.** The first time a machine sees prompt capture on, it marks the end of every existing transcript and uploads only what you type after that. Nothing written before the policy reached your machine is sent, and what you type while capture is off is never sent later. Transcripts created afterwards are read from their start. When the policy turns off, the machine forgets its place (`prompts-offsets.json`), so switching it on again starts fresh at the end of every file.
+
+**Cadence.** Prompts are uploaded about every 30 minutes while Claude Code or Codex is in use; the daily aggregate stays at every 6 hours. A prompt you submit checks a small local timer and, when 30 minutes have passed, starts a detached background upload (no network and no parsing happen in the hook itself). A session start and `sprag team sync --force` also upload. One run sends at most 2,000 prompts or 8 MB; the rest waits for the next sync. The file path is never sent; each file is identified by the first 16 characters of a hash of its path, and a repeated chunk is ignored by the server.
+
+**Check it.** `sprag team status` shows "Prompt capture: on" and the time and count of the last prompt upload. `sprag team status --show-payload` also shows how many prompts are waiting and one example (time, project, first 80 characters), never the full text of the pending prompts.
+
+**How to stop.** Ask an owner or admin to switch prompt capture off for the team (the next sync stops the upload and clears the position file); set `SPRAG_NO_TEAM_SYNC=1` to stop every upload right away; or run `sprag team leave`.
+
+## Privacy notes
+
+- Owners and admins see per-member daily totals, not sessions or prompts, unless the organization is on Enterprise and the team has prompt capture switched on.
+- A member sees the same payload with `sprag team status --show-payload`.
+- Prompt capture is an Enterprise policy that an owner or admin can switch on in the dashboard. Members see its state in `sprag team status`. When capture is on, the CLI uploads the prompts you type after the policy reached your machine (see "Prompt usage (Enterprise)").
+- Rule text leaves your machine only through `sprag team propose`.
+
+## Files and environment variables
+
+| Name | Purpose |
+|---|---|
+| `<user data dir>/team.json` | Membership state and the member key (mode 0600) |
+| `<user data dir>/team-rules.json` | Organization and team rules pulled at the last sync |
+| `<user data dir>/prompts-offsets.json` | Where the prompt uploader stopped in each transcript; exists only while prompt capture is on |
+| `~/.claude/ratchet-team.md` | Approved organization and team rules for Claude Code, imported from `~/.claude/CLAUDE.md` |
+| `<CODEX_HOME>/ratchet-team.md` | The same rules for Codex |
+| `SPRAG_TEAM_TOKEN` | Invite token; enrolls the machine at the next session start |
+| `SPRAG_NO_TEAM_SYNC=1` | Stops every usage upload. A joined machine sends only one status-only call when it first sees the switch on and when it is off again (old name `CTS_NO_TEAM_SYNC` still read) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sprag-cli",
-  "version": "3.69.0",
+  "version": "3.71.0",
   "description": "Model-delegation router for Claude Code and Codex: lookups, checks and test runs go to cheaper models, documents go in as compact Markdown, and a live statusline shows spend and savings.",
   "type": "module",
   "bin": {
@@ -11,9 +11,11 @@
     "deploy": "node scripts/deploy.mjs",
     "docs:statusline": "node scripts/docs-statusline.mjs",
     "postinstall": "node bin/postinstall.js || true",
+    "presets:pull": "node scripts/presets-pull.mjs",
     "publish:legacy": "node scripts/publish-legacy.mjs",
     "release:notes": "node scripts/release-notes.mjs",
     "site:docs": "node scripts/build-site-docs.mjs",
+    "site:serve": "node scripts/serve-site.mjs",
     "test": "node --test",
     "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"
@@ -30,6 +32,8 @@
     "README.ko.md",
     "docs/CODEX.md",
     "docs/CODEX.ko.md",
+    "docs/TEAM.md",
+    "docs/TEAM.ko.md",
     "LICENSE",
     "NOTICE"
   ],

package/presets/agents.json

@@ -0,0 +1,118 @@
+{
+  "note": [
+    "Delegation-only subagents written to ~/.claude/agents by syncDelegationAgents().",
+    "Same shape as the \"agents\" array of a published preset bundle, so the bundled copy",
+    "and a remote bundle render through one path. A remote bundle replaces this list",
+    "when its signature verifies; otherwise this file is used.",
+    "Models are aliases on purpose (a gateway resolves them through ANTHROPIC_DEFAULT_*_MODEL),",
+    "except opus-worker, which names the full id: a bare alias resolves to an older model.",
+    "Effort follows how the work is verified: low for lookups and command runs, medium for",
+    "implementation against tests, high for the larger opus share.",
+    "The files are rendered in English (description.en, body.en): they are model-facing",
+    "prompts, and the Korean copy is what the /ops console shows next to it."
+  ],
+  "agents": [
+    {
+      "name": "haiku-explore",
+      "model": "haiku",
+      "effort": "low",
+      "tools": [
+        "Read",
+        "Grep",
+        "Glob",
+        "Bash"
+      ],
+      "description": {
+        "ko": "위임 작업용 저비용 읽기 전용 탐색, 조회, 상태 확인, 요약 에이전트입니다. MCP 도구는 없습니다.",
+        "en": "Cheap read-only exploration, lookup, status checks and summaries for delegated tasks. It has no MCP tools."
+      },
+      "body": {
+        "ko": "맡은 역할: 읽기 전용 탐색, 조회, 상태 확인, 붙여넣은 로그나 텍스트를 두고 묻는 질문에 답합니다.\n위임받은 작업만 하고, 호출자가 프롬프트에 적은 상한(도구 호출 횟수, 출력 토큰)을 넘기지 마십시오.\n호출자 프롬프트의 언어로 간결하게 보고하십시오.\nMCP 도구나 목록에 없는 도구가 필요하면 즉시 멈추고 \"needs general-purpose: <필요한 도구>\" 한 줄로 보고하십시오. 부모가 다시 위임합니다.\n확인하지 못한 내용은 추측하지 말고 확인하지 못했다고 말하십시오.",
+        "en": "Your role: read-only exploration, lookups, status checks, and questions about pasted logs or text.\nDo only the delegated task, and stay within the caps (tool calls, output tokens) the caller wrote in the prompt.\nReport concisely, in the language of the caller's prompt.\nIf you need an MCP tool or any tool not on your list, stop at once and report one line: \"needs general-purpose: <tools needed>\". The parent will delegate again.\nDo not guess at anything you could not verify; say that you could not verify it."
+      }
+    },
+    {
+      "name": "haiku-runner",
+      "model": "haiku",
+      "effort": "low",
+      "tools": [
+        "Bash",
+        "Read",
+        "Grep",
+        "Glob"
+      ],
+      "description": {
+        "ko": "위임 작업의 빌드·테스트·git 명령을 실행하는 저비용 에이전트입니다. MCP 도구는 없습니다.",
+        "en": "Cheap runner for build, test and git commands in delegated tasks. It has no MCP tools."
+      },
+      "body": {
+        "ko": "맡은 역할: 전달받은 빌드·테스트·git 명령을 실행하고 결과를 보고합니다.\n위임받은 작업만 하고, 호출자가 프롬프트에 적은 상한(도구 호출 횟수, 출력 토큰)을 넘기지 마십시오.\n호출자 프롬프트의 언어로 간결하게 보고하십시오.\nMCP 도구나 목록에 없는 도구가 필요하면 즉시 멈추고 \"needs general-purpose: <필요한 도구>\" 한 줄로 보고하십시오. 부모가 다시 위임합니다.\n확인하지 못한 내용은 추측하지 말고 확인하지 못했다고 말하십시오.",
+        "en": "Your role: run the build, test, or git commands you are given and report the result.\nDo only the delegated task, and stay within the caps (tool calls, output tokens) the caller wrote in the prompt.\nReport concisely, in the language of the caller's prompt.\nIf you need an MCP tool or any tool not on your list, stop at once and report one line: \"needs general-purpose: <tools needed>\". The parent will delegate again.\nDo not guess at anything you could not verify; say that you could not verify it."
+      }
+    },
+    {
+      "name": "haiku-translate",
+      "model": "haiku",
+      "effort": "low",
+      "tools": [
+        "Read",
+        "Grep",
+        "Glob",
+        "Edit",
+        "Write"
+      ],
+      "description": {
+        "ko": "위임 작업용 저비용 일괄 번역·정형 텍스트 변환 에이전트입니다. MCP 도구는 없습니다.",
+        "en": "Cheap batch translation and structured text conversion for delegated tasks. It has no MCP tools."
+      },
+      "body": {
+        "ko": "맡은 역할: 전달받은 파일이나 텍스트의 일괄 번역과 정형 텍스트 변환입니다.\n위임받은 작업만 하고, 호출자가 프롬프트에 적은 상한(도구 호출 횟수, 출력 토큰)을 넘기지 마십시오.\n호출자 프롬프트의 언어로 간결하게 보고하십시오.\nMCP 도구나 목록에 없는 도구가 필요하면 즉시 멈추고 \"needs general-purpose: <필요한 도구>\" 한 줄로 보고하십시오. 부모가 다시 위임합니다.\n확인하지 못한 내용은 추측하지 말고 확인하지 못했다고 말하십시오.",
+        "en": "Your role: batch translation and mechanical text conversion of the files or text you are given.\nDo only the delegated task, and stay within the caps (tool calls, output tokens) the caller wrote in the prompt.\nReport concisely, in the language of the caller's prompt.\nIf you need an MCP tool or any tool not on your list, stop at once and report one line: \"needs general-purpose: <tools needed>\". The parent will delegate again.\nDo not guess at anything you could not verify; say that you could not verify it."
+      }
+    },
+    {
+      "name": "sonnet-worker",
+      "model": "sonnet",
+      "effort": "medium",
+      "tools": [
+        "Read",
+        "Grep",
+        "Glob",
+        "Bash",
+        "Edit",
+        "Write",
+        "NotebookEdit"
+      ],
+      "description": {
+        "ko": "여러 단계 작업과 설계가 확정된 구현을 맡는 중간 티어 워커입니다. MCP 도구는 없습니다.",
+        "en": "Mid-tier worker for multi-step tasks and implementation handed over with a fixed design. It has no MCP tools."
+      },
+      "body": {
+        "ko": "맡은 역할: 여러 단계로 이어지는 작업과, 호출자가 설계를 확정한 구현을 맡습니다.\n위임받은 작업만 하고, 호출자가 프롬프트에 적은 상한(도구 호출 횟수, 출력 토큰)을 넘기지 마십시오.\n호출자 프롬프트의 언어로 간결하게 보고하십시오.\nMCP 도구나 목록에 없는 도구가 필요하면 즉시 멈추고 \"needs general-purpose: <필요한 도구>\" 한 줄로 보고하십시오. 부모가 다시 위임합니다.\n확인하지 못한 내용은 추측하지 말고 확인하지 못했다고 말하십시오.",
+        "en": "Your role: multi-step work and the implementation half of a design the caller already fixed.\nDo only the delegated task, and stay within the caps (tool calls, output tokens) the caller wrote in the prompt.\nReport concisely, in the language of the caller's prompt.\nIf you need an MCP tool or any tool not on your list, stop at once and report one line: \"needs general-purpose: <tools needed>\". The parent will delegate again.\nDo not guess at anything you could not verify; say that you could not verify it."
+      }
+    },
+    {
+      "name": "opus-worker",
+      "model": "claude-opus-5-5",
+      "effort": "high",
+      "tools": [
+        "Read",
+        "Grep",
+        "Glob",
+        "Bash",
+        "Edit",
+        "Write",
+        "NotebookEdit"
+      ],
+      "description": {
+        "ko": "Fable 세션용 고성능 워커로, 설계가 확정된 대규모 구현·디버깅·리팩터링을 맡습니다. MCP 도구는 없습니다.",
+        "en": "Heavy worker for Fable sessions: large implementation, debugging and refactoring handed over with a fixed design. It has no MCP tools."
+      },
+      "body": {
+        "ko": "맡은 역할: 호출자가 설계를 확정한 대규모 구현과 디버깅입니다. 설계 판단과 되돌릴 수 없는 작업은 호출자에게 넘기십시오.\n위임받은 작업만 하고, 호출자가 프롬프트에 적은 상한(도구 호출 횟수, 출력 토큰)을 넘기지 마십시오.\n호출자 프롬프트의 언어로 간결하게 보고하십시오.\nMCP 도구나 목록에 없는 도구가 필요하면 즉시 멈추고 \"needs general-purpose: <필요한 도구>\" 한 줄로 보고하십시오. 부모가 다시 위임합니다.\n확인하지 못한 내용은 추측하지 말고 확인하지 못했다고 말하십시오.",
+        "en": "Your role: large implementation and debugging work whose design the caller already fixed. Hand design judgement and irreversible actions back to the caller.\nDo only the delegated task, and stay within the caps (tool calls, output tokens) the caller wrote in the prompt.\nReport concisely, in the language of the caller's prompt.\nIf you need an MCP tool or any tool not on your list, stop at once and report one line: \"needs general-purpose: <tools needed>\". The parent will delegate again.\nDo not guess at anything you could not verify; say that you could not verify it."
+      }
+    }
+  ]
+}

package/presets/doc2md/convert.py

@@ -34,7 +34,7 @@ import zipfile
 
 MAX_UNCOMPRESSED = 500 * 1024 * 1024
 MAX_RATIO = 200
-ROW_CAP = int(os.environ.get("CTS_DOC2MD_ROW_CAP", "50000"))
+ROW_CAP = int(os.environ.get("SPRAG_DOC2MD_ROW_CAP", os.environ.get("CTS_DOC2MD_ROW_CAP", "50000")))
 ZIP_EXTS = {".pptx", ".xlsx", ".docx"}
 
 

package/presets/ratchet-rules.json

@@ -6,31 +6,39 @@
     "each answer. Both read this file, so there is one source for the wording.",
     "Each rule carries both languages because the text is injected into the model's",
     "context, where a Korean-only rule would steer an English session into Korean.",
-    "Ids are derived from the `ko` text (the canonical one), so a rule keeps its",
-    "identity — and a user's 'no' — when the English wording is revised."
+    "Each rule carries a stable `id`. It was derived once from the `ko` text",
+    "(fix-<sha1(ko)[0:6]>) and is kept when the wording changes, so a rule keeps its",
+    "identity, and a user's 'no', across rewording. This file is also the fallback for",
+    "the centrally published preset bundle; `npm run presets:pull` refreshes it."
   ],
   "rules": [
     {
+      "id": "fix-bd7836",
       "ko": "웹 fetch/search에서 robots·UA 차단('unable to fetch' 등)이 발생하면 → curl에 브라우저 UA(Mozilla/5.0 ... Chrome/...) 헤더를 붙여 재시도. reddit 등은 .json 엔드포인트 + UA 조합으로 접근 가능",
       "en": "When a web fetch/search is blocked by robots or user-agent checks ('unable to fetch' and similar) → retry with curl carrying a browser UA header (Mozilla/5.0 ... Chrome/...). Sites like reddit also answer on their .json endpoints with that UA"
     },
     {
+      "id": "fix-4168c2",
       "ko": "ratchet 룰 promote 호출 직전 사용자에게 scope(global/project)를 먼저 묻는다 — Bash 환경은 non-TTY라 CLI readline 프롬프트가 안 뜨므로, 호출자(LLM)가 대신 묻고 --global/--project 플래그를 명시해 실행",
       "en": "Ask the user for the scope (global or project) before calling ratchet promote — the Bash environment is non-TTY, so the CLI's readline prompt never appears; the caller (the model) has to ask and pass --global/--project explicitly"
     },
     {
+      "id": "fix-ce98b4",
       "ko": "자동화 도구가 grep·정규식으로 찾는 마커 텍스트(헤더·앵커·키워드 라인)는 리팩터링·압축·수정 금지 — 정확 매칭 검출은 한 글자만 바뀌어도 깨짐",
       "en": "Never refactor, compress or reword marker text that an automated tool finds by grep or regex (headings, anchors, keyword lines) — exact-match detection breaks on a single changed character"
     },
     {
+      "id": "fix-b1da7a",
       "ko": "자동화 설계에서 vision/screenshot 루프가 보이면 → 호출 가능한 함수·API·MCP tool부터 찾는다. 통제 가능한 내부 도구는 무조건 API, 통제 불가 외부 SaaS만 vision 차선책. 인터페이스를 바꾼 뒤에 모델을 내린다 — 거꾸로 가면 토큰 폭발",
       "en": "When an automation design calls for a vision/screenshot loop → look for a callable function, API or MCP tool first. Anything you control gets an API; vision is the fallback only for external SaaS you cannot change. Fix the interface before lowering the model — doing it the other way round explodes the token cost"
     },
     {
+      "id": "fix-1dee5f",
       "ko": "입력 데이터(ground-truth) 변경 시 그에 의존하는 모든 파생 자산을 끝까지 재생성한다 — 중간 단계를 생략하면 stale 산출물이 새 입력 위에 얹혀 결과가 깨짐",
       "en": "When the ground-truth input changes, regenerate every derived asset all the way through — skipping an intermediate step leaves a stale artifact sitting on top of the new input and the result breaks"
     },
     {
+      "id": "fix-f558f9",
       "ko": "탐색·조회·상태 확인·명령 실행 같은 단순 요청은 `model: haiku` 서브에이전트로 위임해 상위 모델 토큰을 아낀다 (읽기 전용 preset 에이전트가 이미 있으면 그걸 쓰고, 없으면 티어만 내려서 위임)",
       "en": "Delegate simple requests — lookup, status checks, running commands — to a `model: haiku` subagent to keep the expensive model's tokens for real work (use an existing read-only preset agent when there is one; otherwise delegate with the tier lowered)",
       "agents": [
@@ -38,10 +46,12 @@
       ]
     },
     {
+      "id": "fix-aa18bc",
       "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"
     },
     {
+      "id": "fix-777a15",
       "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": [

package/src/agents.js

@@ -26,10 +26,12 @@ const AGENT_MODEL = {
   'haiku-runner': 'haiku',
   'haiku-translate': 'haiku',
   'sonnet-worker': 'sonnet',
+  'opus-worker': 'opus',
   // 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',
+  opus: 'opus',
   haiku: 'haiku',
 };
 
@@ -50,7 +52,7 @@ export function agentExists(name, root = process.cwd()) {
 }
 
 /** Agent a bare tier name stands for when that agent's file exists. */
-const TIER_AGENT = { sonnet: 'sonnet-worker', haiku: 'haiku-explore' };
+const TIER_AGENT = { sonnet: 'sonnet-worker', opus: 'opus-worker', haiku: 'haiku-explore' };
 
 /**
  * The agent a rule target really names on this machine, or null when none is

package/src/cli-entry.js

@@ -0,0 +1,40 @@
+/**
+ * The script a detached child of this CLI must run.
+ *
+ * The preset sync and the two team syncs start a detached child to do their
+ * network work, and they used to pass `process.argv[1]` as its script. Inside
+ * the CLI that is bin/cli.js. Inside anything else that imports these modules
+ * it is that caller's script: under `node --test` a test file relaunched
+ * itself, detached, on every session-start case, and each copy did the same.
+ * 4,055 processes in 59 seconds on 2026-10-20, and three memory-exhaustion
+ * stalls in two days. So the entry is fixed here from this module's own
+ * location, and a spawned child carries a marker that refuses to spawn again.
+ */
+import * as childProcess from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { envVar } from './env.js';
+
+export const CLI_ENTRY = fileURLToPath(new URL('../bin/cli.js', import.meta.url));
+
+/** The marker a detached child carries; read through envVar('DETACHED_CHILD'). */
+export const DETACHED_CHILD_VAR = 'SPRAG_DETACHED_CHILD';
+
+export function isDetachedChild(env = process.env) {
+  return envVar('DETACHED_CHILD', env) === '1';
+}
+
+/** The environment for a detached child: the caller's, plus the marker. */
+export function detachedChildEnv(env = process.env) {
+  return { ...env, [DETACHED_CHILD_VAR]: '1' };
+}
+
+/**
+ * Start `sprag <args>` detached, never awaited, never from a detached child.
+ * Returns true when a child was started. Every background refresh goes
+ * through here so that no caller can name the script itself.
+ */
+export function spawnDetachedCli(args, { env = process.env, spawn = childProcess.spawn, execPath = process.execPath } = {}) {
+  if (isDetachedChild(env)) return false;
+  spawn(execPath, [CLI_ENTRY, ...args], { detached: true, stdio: 'ignore', windowsHide: true, env: detachedChildEnv(env) }).unref();
+  return true;
+}

package/src/codex/delegation.js

@@ -36,7 +36,7 @@ export function validateCodexTarget(model, effort) {
 
 export function validateCodexSharedTarget({ tier, from, model, effort, provider }) {
   validateCodexTarget(model, effort);
-  if (!SHARED_RULE_TIERS.includes(tier)) throw new Error('Shared rule tier must be T1 or T2.');
+  if (!SHARED_RULE_TIERS.includes(tier)) throw new Error('Shared rule tier must be T1, T1H or T2.');
   if (!safeId(from) || from === model) throw new Error('--from must name a different parent model.');
   if (!safeId(provider)) throw new Error('A shared model mapping requires a Codex provider ID.');
   return { tier, from, model, ...(effort === undefined ? {} : { effort }), provider };
@@ -78,7 +78,7 @@ function catalogCodexModels(home) {
 }
 
 /**
- * The models Codex resolves T2 and T1 to when the user mapped none, the way
+ * The models Codex resolves T2, T1 and T1H to when the user mapped none, the way
  * Claude Code resolves `haiku` and `sonnet`. Candidates are the models that
  * already ran in this user's Codex sessions plus, for the built-in OpenAI
  * provider only, the models Codex's catalog lists for the account (a gateway
@@ -86,7 +86,8 @@ function catalogCodexModels(home) {
  * qualifies only if it is priced on the parent's provider and costs less than
  * the parent, so the hint never names a model the gateway cannot serve. The
  * cheapest is T2 and the next one up is T1; with a single candidate T1 stays
- * on the main agent. Returns { targets, reason }.
+ * on the main agent. T1H is the most expensive cheaper model, and only when
+ * there are at least three candidates, so that it differs from T1. Returns { targets, reason }.
  */
 export function autoCodexSharedTargets({ dir = userDataDir(), home = codexUserDir(), model, provider, now = Date.now() } = {}) {
   if (!safeId(model) || !safeId(provider)) return { targets: [], reason: 'unknown parent model or provider' };
@@ -104,7 +105,9 @@ export function autoCodexSharedTargets({ dir = userDataDir(), home = codexUserDi
       ? `${model} is already the cheapest available model on ${provider}`
       : `no cheaper priced model has run in your Codex sessions on ${provider}` };
   }
-  const targets = cheaper.slice(0, 2).map((x, i) => ({ tier: i === 0 ? 'T2' : 'T1', from: model, model: x.model, provider, auto: true }));
+  const picks = cheaper.slice(0, 2).map((x, i) => ({ tier: i === 0 ? 'T2' : 'T1', x }));
+  if (cheaper.length >= 3) picks.push({ tier: 'T1H', x: cheaper.at(-1) });
+  const targets = picks.map(({ tier, x }) => ({ tier, from: model, model: x.model, provider, auto: true }));
   return { targets, reason: null };
 }
 
@@ -240,7 +243,7 @@ export function codexDelegateMinContext(cfg) {
 // Codex tells the model to set spawn_agent's model only on the user's request,
 // so the shared hint says where this request came from.
 const SHARED_APPROVAL = 'The user approved this policy and its model mapping, so setting model here follows the user\'s request.';
-const SHARED_TIER_GUIDANCE = 'Choose T2 only for a simple bounded lookup or command. Use T1 for multi-step tool chains or work spanning multiple files. If the required tier is not mapped, keep the task on the main agent. Do not delegate design judgement, diagnosis, or irreversible actions.';
+const SHARED_TIER_GUIDANCE = 'Choose T2 only for a simple bounded lookup or command. Use T1 for multi-step tool chains or work spanning multiple files. Use T1H only for large-scope work that T1 would likely get wrong. If the required tier is not mapped, keep the task on the main agent. Do not delegate design judgement, diagnosis, or irreversible actions.';
 const WAIT_TEXT = 'Wait for it to finish (call wait_agent with timeout_ms of at least 120000, and again if it times out) and do not do the delegated task yourself while it runs; then verify its result and report unfinished work. Do not spawn another CLI process. '
   + 'If sub-agent tools or the target model are unavailable, keep the task on the main agent and state that delegation was unavailable.';
 

package/src/codex/hooks.js

@@ -1,5 +1,6 @@
+import { envVar } from '../env.js';
+import { spawnDetachedCli } from '../cli-entry.js';
 import { createRequire } from 'node:module';
-import { spawn } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { mkdirSync, openSync, readFileSync, readSync, closeSync, statSync } from 'node:fs';
 import { join, resolve } from 'node:path';
@@ -116,9 +117,8 @@ async function routeNotice(root, { spawnRescan = defaultRescan } = {}) {
 }
 
 function defaultRescan() {
-  if (process.env.CTS_NO_ROUTE_SCAN === '1') return;
-  spawn(process.execPath, [process.argv[1], 'route-scan', '--refresh', '--quiet', '--agent', 'codex'],
-    { detached: true, stdio: 'ignore', windowsHide: true }).unref();
+  if (envVar('NO_ROUTE_SCAN') === '1') return;
+  spawnDetachedCli(['route-scan', '--refresh', '--quiet', '--agent', 'codex']);
 }
 
 /**
@@ -130,9 +130,8 @@ function defaultRescan() {
  * of the parent is the earliest point that knows one was spawned.
  */
 function defaultLedgerRefresh() {
-  if (process.env.CTS_NO_ROUTE_SCAN === '1') return;
-  spawn(process.execPath, [process.argv[1], 'route-scan', 'savings', '--refresh', '--quiet', '--agent', 'codex'],
-    { detached: true, stdio: 'ignore', windowsHide: true }).unref();
+  if (envVar('NO_ROUTE_SCAN') === '1') return;
+  spawnDetachedCli(['route-scan', 'savings', '--refresh', '--quiet', '--agent', 'codex']);
 }
 
 export function lintCodexTool(payload, { scope = 'all' } = {}) {
@@ -180,13 +179,25 @@ export async function codexHookOutput(event, payload, { cfg = loadConfig(), refr
     const parts = [];
     // Keep the preset file current with this version's wording before it is read.
     if (event === 'session-start') {
+      try { (await import('../preset-sync.js')).spawnPresetSyncIfDue(); } catch (e) { debug('codex:preset-sync', e); }
       try { (await import('../preset-ratchet.js')).preparePresetRatchet({ agent: 'codex' }); } catch (e) { debug('codex:preset', e); }
     }
     const { presetRatchetPath } = await import('../preset-ratchet.js');
+    let teamRatchetPath = () => '';
+    let teamNotice = null;
+    try {
+      const tr = await import('../team-ratchet.js');
+      teamRatchetPath = tr.teamRatchetPath;
+      if (event === 'session-start') {
+        tr.syncTeamRatchet({ agent: 'codex' });
+        tr.spawnTeamSyncIfDue();
+        teamNotice = tr.autoJoinNoticeBlock(undefined, 'en');
+      }
+    } catch (e) { debug('codex:team-ratchet', e); }
     // Lower priority survives the budget first. Rules and style move to a file
     // when they do not fit; offers and notices are simply left out.
     for (const [scope, ratchet] of [['global', codexHarnessPaths(root, 'global').ratchet],
-      ['preset', presetRatchetPath({ agent: 'codex' })], ['project', codexHarnessPaths(root, 'project').ratchet]]) {
+      ['preset', presetRatchetPath({ agent: 'codex' })], ['team', teamRatchetPath({ agent: 'codex' })], ['project', codexHarnessPaths(root, 'project').ratchet]]) {
       try {
         if (statSync(ratchet).size > 32 * 1024) {
           parts.push({ priority: 1, text: `Read the ${scope} Sprag ratchet rules at ${JSON.stringify(ratchet)} before working; they exceed the automatic injection limit.` });
@@ -194,10 +205,11 @@ export async function codexHookOutput(event, payload, { cfg = loadConfig(), refr
           const text = readFileSync(ratchet, 'utf8').trim();
           // An empty preset file is only its header; injecting it would spend
           // tokens every session on no rules.
-          if (text && (scope !== 'preset' || /^- /m.test(text))) parts.push({ priority: 1, spill: true, text: `[Sprag Codex ratchet: ${scope}]\n${text}` });
+          if (text && ((scope !== 'preset' && scope !== 'team') || /^- /m.test(text))) parts.push({ priority: 1, spill: true, text: `[Sprag Codex ratchet: ${scope}]\n${text}` });
         }
       } catch (e) { if (e?.code !== 'ENOENT') debug('codex:ratchet', e); }
     }
+    if (teamNotice) parts.push({ priority: 5, text: teamNotice });
     if (event === 'subagent-start') parts.push({ priority: 0, text:
       '[Sprag Codex delegation]\nStay within the assigned task and any caller-provided budget. Return findings with file references and actual verification results; state unfinished work. Use only available Codex tools and configured roles. Do not infer a model tier or invent a tool-call budget.' });
     // Codex reads the Korean guide from the global AGENTS.md, so the hook adds it
@@ -207,7 +219,7 @@ export async function codexHookOutput(event, payload, { cfg = loadConfig(), refr
     try { korean = syncCodexKoreanBlock({ cfg }); } catch (e) { debug('codex:korean-sync', e); }
     if (korean?.action !== 'unchanged') parts.push({ priority: 2, spill: true, text: koreanStyleInjection({ cfg }) });
     parts.push({ priority: 3, spill: true, text: await cohesionInjection({ cfg }) });
-    if (process.env.CTS_NO_DOC2MD !== '1' && cfg?.codex?.doc2md !== false) parts.push({ priority: 4, spill: true, text: codexDocumentNote() });
+    if (envVar('NO_DOC2MD') !== '1' && cfg?.codex?.doc2md !== false) parts.push({ priority: 4, spill: true, text: codexDocumentNote() });
     // Offers ask the user a question; a `codex exec` run has no one to answer it.
     if (event === 'session-start' && payload.source !== 'compact' && !isCodexExecSession(payload.transcript_path)) {
       if (version) parts.push({ priority: 5, text: updateOffer(version, { agent: 'codex', lang: userLanguage() }) });
@@ -219,6 +231,7 @@ export async function codexHookOutput(event, payload, { cfg = loadConfig(), refr
   }
   if (event === 'prompt') {
     const parts = [];
+    try { (await import('../team-ratchet.js')).spawnTeamSyncOnPrompt(); } catch (e) { debug('codex:team-prompts', e); }
     if (codexDelegateEnabled(cfg)) {
       // Before the hint for this prompt is recorded: a hint from an earlier turn
       // that no child claimed is closed, and children that did run get priced.
@@ -235,14 +248,14 @@ export async function codexHookOutput(event, payload, { cfg = loadConfig(), refr
       }
       catch (e) { debug('codex:brief', e); }
     }
-    if (process.env.CTS_NO_DOC2MD !== '1' && cfg?.codex?.doc2md !== false) {
+    if (envVar('NO_DOC2MD') !== '1' && cfg?.codex?.doc2md !== false) {
       const identity = codexDocumentContext(payload);
       parts.push(doc2md.contextForPrompt(payload, { lang: userLanguage(), agent: 'codex', convert: (source) => convertCodexDocument(source, identity) }));
     }
     return context('UserPromptSubmit', parts.filter(Boolean).join('\n\n'));
   }
   if (event === 'pre-tool') {
-    if (process.env.CTS_NO_DOC2MD !== '1' && cfg?.codex?.doc2md !== false) {
+    if (envVar('NO_DOC2MD') !== '1' && cfg?.codex?.doc2md !== false) {
       const result = codexDocumentTool(payload);
       if (result) return result;
     }