tiergear 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jang2162
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,294 @@
+# tiergear
+
+A plugin and CLI that lets a decision model (the judge) pick the model and reasoning effort for Claude Code sessions and Orca workers.
+
+- **First turn**: the first prompt goes to the judge, which returns a tier (trivial, quick, standard, deep, max). Tables A and B turn that into a model and effort. The first turn has no cache to lose, so the model changes too.
+- **Later turns**: by default the model stays and only effort changes. Raising is easy (confidence 0.5); lowering is hard (confidence 0.85 for 2 turns in a row), unless the optional instant switch is on and the judge is sure enough.
+- **Floor**: the tier never drops below one step under the first decision. Sessions started with `tiergear launch`/`orca-spawn` use the launch tier itself as their floor, so a `--min-tier` holds for the whole session.
+- **Ceiling**: a session launched with `--max-tier` never rises above it, whether the judge asks for a harder tier or the session looks stuck.
+- **Pick a tier, or off, from the band**: the band above the prompt has a button per tier and one for **off** (see [Status band](#status-band)). A picked tier is a starting point; the judge keeps moving it as usual. **off** withdraws what tiergear applies until you pick a tier again.
+- **Manual changes pause routing**: changing the model or effort yourself with `/model` or `/effort` mid-session pauses the session, just like picking **off**, and writes `[tiergear] manual model/effort change — routing paused for this session` to the hook log once. Pick a tier to hand it back to tiergear. It compares the session values the engine reports between turns, so tiergear's own changes don't trigger it. If the engine switches to a fallback model from the first request of a turn, that can also look like a manual change.
+
+If the judge is slow or fails, that turn proceeds untouched.
+
+### Which prompts are judged
+
+Only prompts the user typed are judged: terminal input (`composer`), Remote Control (`bridge`), and the SDK or `claude -p` (`sdk`). Background task notifications, scheduled tasks and `/loop`, messages from other sessions or SendMessage, observers, auto-continue, plugin-sent prompts, and unknown origins (`unclassified`) pass through unjudged, and the tier and applied values stay as they are. Prompts that enter a running turn (including ones typed and queued while a turn runs) are not judged. Slash commands starting with `/` are not judged.
+
+## Install
+
+Requires Claude Code 2.1.289 or later. At the prompt of a Claude Code session:
+
+```
+/plugin marketplace add jang2162/tiergear
+/plugin install tiergear@tiergear
+```
+
+Pick a scope when asked (user is first). The hooks run in that session at once and in every new session under that scope. `/plugin` lists it as `tiergear@tiergear`. The default judge, jev, needs a TypeSafe API key in `TYPESAFE_API_KEY` (your shell or user settings) or in the `judgeApiKey` option; without one it answers nothing and the [ Recent ] pane shows `judge no API key for jev`. Or pick a local judge (laya, kev) in the plugin options.
+
+To update: `claude plugin update tiergear@tiergear`, then `/reload-plugins`.
+
+### CLI (optional)
+
+`tiergear launch`, `tiergear orca-spawn`, `tiergear stats` and `tiergear status` are a separate command-line tool; the hooks don't need it. Requires Node 20 or later.
+
+```bash
+npm install -g tiergear
+```
+
+`which tiergear` should print the CLI path.
+
+### From a clone (development)
+
+To run the hooks and the CLI from a working copy instead, so `/reload-plugins` picks up edits without an update:
+
+```bash
+git clone https://github.com/jang2162/tiergear.git
+cd tiergear
+npm install && npm run build && npm link
+mkdir -p ~/.claude/skills
+ln -s "$PWD" ~/.claude/skills/tiergear
+claude plugin list | grep -A3 tiergear
+```
+
+You should see `tiergear@skills-dir` and `Status: ✔ loaded`. If `tiergear@tiergear` is also installed, it takes precedence and the clone is not loaded (`claude plugin list` says so); uninstall it with `claude plugin uninstall tiergear@tiergear` to run from the clone.
+
+## Judges
+
+All three judges use TypeSafe's `<baseUrl>/v1/systemone` contract. The default is `jev`.
+
+| Preset | Address | Model | Key env var | Timeout (first turn / later) |
+| --- | --- | --- | --- | --- |
+| jev | `https://api.typesafe.ai` | `jev-latest` | `TYPESAFE_API_KEY` (required) | 2000ms / 1200ms |
+| laya | `http://localhost:11435` | `laya` | `OLLAYA_API_KEY` (optional) | 3000ms / 2500ms |
+| kev | `http://localhost:8009` | `kev-latest` | `KEV_API_KEY` (optional) | 3000ms / 2000ms |
+
+- jev needs a key and sends data to TypeSafe's servers.
+- laya runs locally with `ollaya run laya`.
+- kev points at a server you run locally or on Modal (change the address with `judgeBaseUrl`).
+- A judge address must be `https`, or `http` to this machine (`localhost`, `127.0.0.1`, `[::1]`), since prompts travel in the request. Any other address is refused and the turn goes on untouched.
+- A preset's key goes only to that preset's own address. Point `judgeBaseUrl` (or the CLI's `--judge-url`) elsewhere and set the key for it explicitly with `judgeApiKey` (CLI: `TIERGEAR_JUDGE_API_KEY`); `TYPESAFE_API_KEY` and the like are not sent there.
+- A key that a repository's `.claude/settings.json` supplies (in `env`) is ignored, so a cloned repo can't route your prompts to its own account. Keys in your user settings, `.claude/settings.local.json` or your shell are used.
+- After 3 judge failures in a row, the session skips the judge for 5 minutes and keeps its current state instead of falling back to the tables.
+
+## Tables A and B
+
+**Table A: the model each tier starts on**
+
+| Tier | Claude | Codex |
+| --- | --- | --- |
+| trivial | sonnet | gpt-5.6-luna |
+| quick | sonnet | gpt-5.6-terra |
+| standard | sonnet | gpt-5.6-terra |
+| deep | opus | gpt-5.6-terra |
+| max | fable | gpt-5.6-terra |
+
+Claude's trivial tier uses sonnet, not haiku: Claude Code's auto mode doesn't run on haiku, so a haiku session stops to ask for approval on commands. If you run with permission checks off, see [Haiku for trivial](#haiku-for-trivial-bypass-permissions-users).
+
+**Table B: effort per model** (`-` means no effort is sent; the haiku row applies only if you put haiku in Table A)
+
+| Model | trivial | quick | standard | deep | max |
+| --- | --- | --- | --- | --- | --- |
+| haiku | - | - | - | - | - |
+| sonnet | low | low | medium | high | max |
+| opus | low | low | medium | xhigh | max |
+| fable | low | low | medium | high | xhigh |
+| gpt-5.6-luna (Codex) | low | low | medium | high | high |
+| gpt-5.6-terra (Codex) | low | low | medium | xhigh | max |
+
+On Codex, deep and max both use `gpt-5.6-terra`; only the effort differs (xhigh vs max).
+
+A session on a model without effort (haiku, if you set it) can't be raised through effort alone, so raising the tier switches to that tier's model even when `switchModelMidSession=false` (the cache breaks once).
+
+### Customizing the tables
+
+Put only the cells you want to change in `~/.config/tiergear/tables.json`; they are merged over the defaults.
+
+```json
+{ "claude": { "effort": { "opus": { "deep": "max" } } } }
+```
+
+Model cells go under `models`, as in `{"claude":{"models":{"deep":"opus"}}}`. A model must be a plain id (letters, digits, `.`, `_`, `-`, `:`, `/` and brackets as in `opus[1m]`), since it ends up in a launch command a shell reads. Effort values are low, medium, high, xhigh, max, or `null`. If any value or the JSON itself is invalid, **the whole file is ignored** and the default tables are used (this is noted in the hook log). Hooks read the file once, the first time it's needed after session start, so open a new session after editing it.
+
+### Haiku for trivial (bypass-permissions users)
+
+If you run Claude Code with permission checks off ("yolo" mode), auto mode doesn't matter and haiku is the cheaper choice for trivial work. Put it back with one cell:
+
+```json
+{ "claude": { "models": { "trivial": "haiku" } } }
+```
+
+Permission checks can be turned off in two ways:
+
+- One session: `claude --dangerously-skip-permissions`.
+- Every session, including the workers `orca-spawn` starts: in `~/.claude/settings.json`,
+
+  ```json
+  { "permissions": { "defaultMode": "bypassPermissions" } }
+  ```
+
+Use the settings file if you start workers with tiergear. `tiergear launch` prints a command with only `--model` and `--effort`, `orca-spawn` starts the agent with that command, and inside a Run Orca's `worker-start` builds the command itself, so none of them adds the flag. With only the flag, a haiku worker asks for approval again.
+
+**Bypass mode runs every tool call without asking.** Use it only where you accept that, such as a sandbox or a throwaway worktree.
+
+## Plugin options
+
+Change these in `/config` (plugin options).
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `judge` | `jev` | Judge preset: one of jev, laya, kev (shown as a list in `/config`). An unknown value falls back to jev and is noted once in the hook log |
+| `judgeBaseUrl` | preset | Leave empty for the preset's address. Must be https, or http to localhost |
+| `judgeModel` | preset | Leave empty for the preset's model |
+| `judgeApiKey` | preset env var | Leave empty to use TYPESAFE_API_KEY, OLLAYA_API_KEY, or KEV_API_KEY, which only go to the preset's own address (sensitive) |
+| `switchModelMidSession` | `false` | Also change the model after the first turn. Off: only effort changes. Either change breaks the messages prompt cache; a model change also breaks the tools and system caches |
+| `instantSwitchConfidence` | off | Confidence · instant switch: a lower tier the judge is at least this sure of applies at once, straight to that tier (never under the floor), skipping `downgradeStreak`. Leave unset or 0 to keep it off |
+| `minDowngradeConfidence` | `0.85` | Confidence · lower: minimum confidence for a turn to count toward lowering |
+| `minUpgradeConfidence` | `0.5` | Confidence · raise: minimum confidence to raise the tier |
+| `stuckConfidence` | `0.6` | Confidence · stuck: raise one step when the judge's stuck probability is at or above this |
+| `downgradeStreak` | `2` | Consecutive turns needed to lower one step |
+| `stuckFailures` | `3` | Raise one step after this many identical tool failures in a row |
+| `firstTurnTimeoutMs` | preset | First-turn latency budget. At most 8000ms (the whole hook budget is 10s, so larger values are cut to 8000) |
+| `turnTimeoutMs` | preset | Later-turn latency budget. At most 8000ms |
+| `showRecentButton` | `true` | Show the **[ Recent ]** button above the prompt. Off: `/tiergear` still opens the pane |
+| `showPrefix` | `true` | Start the band with `tiergear` |
+| `showStatusText` | `true` | Show the line's parts below (all four at once). Turn it off when a status line tool shows them (see [Status line tools](#status-line-tools-ccstatusline)) |
+| `showTier` | `true` | The tier, `deep` |
+| `showConfidence` | `true` | The judge's confidence, `0.91` (`n/d` without one) |
+| `showModelEffort` | `true` | The model and effort in effect, `opus/xhigh` (`→ opus/xhigh` when tiergear just applied them) |
+| `showReason` | `true` | Why nothing changed, `unchanged (same tier)` |
+| `showTierButtons` | `true` | Show the off and tier buttons above the prompt |
+| `showFloor` | `true` | Show the floor picker above the prompt |
+
+## Status band
+
+tiergear shows its state in one row just above the prompt: a line, the **Tier** picker (off and a button per tier), the **Floor** picker, and **[ Recent ]**. The choice in effect is bracketed; the others are dim.
+
+```
+tiergear · deep 0.91 → opus/xhigh  | Tier: off  ~~trivial~~  quick  standard  [deep]  max | Floor: quick |  [ Recent ]
+```
+
+It doesn't use the status line below the prompt. Before anything is decided the line reads just `tiergear` and no button is bracketed.
+
+The line starts with `tiergear ·` and shows the model and effort the session is running on as `model/effort`; a model without effort shows `-`.
+
+- Applied: `tiergear · deep 0.91 → opus/xhigh`.
+- Unchanged: `tiergear · standard 0.62 · sonnet/medium · unchanged (<reason>)`. When tiergear isn't overriding anything (low confidence, off), this is the session's own model and effort.
+- The line is set when a prompt is judged, then refreshed with the values the engine reports when the turn starts. Before the session's first turn the values may not be known yet: an unchanged line then leaves them out, and an applied line shows only the effort if tiergear isn't setting the model.
+- `unset` appears when no tier has been decided yet, and `n/d` takes the place of the confidence when the judge gave no answer (as after a pick from the band).
+
+Reasons for no change: `no answer` (no judge response), `low confidence`, `same tier`, `paused` (off is chosen), `manual tier` (the first prompt runs on a tier picked before it), `floor set` (the floor was changed by hand), `at floor` (can't go lower), `at ceiling` (can't go higher than the launch's `--max-tier`), `easier step N/M` (Nth lowering candidate, M needed), `stuck at max`.
+
+### Tier buttons and floor
+
+- **Floor** picks the lowest tier the session may go to. A tier above the current one raises the session to it at once. A tier under the floor is struck through and can't be clicked; lower the floor first. A floor above a launch's `--max-tier` stops at it. Set before the first prompt, the first decided tier starts no lower than it. The floor picker is a select: click or focus it, then use the arrow keys and Enter.
+
+- One click picks. A tier applies from the next request, even in the middle of a running turn. Mid-session only the effort changes (from the session model's column in table B), unless `switchModelMidSession` is on. The judge goes on from the picked tier by the usual rules. A pick below the floor lowers the floor to it. A pick may go above a launch's `--max-tier`, but the judge still won't raise past it.
+- Picked before the first prompt, a tier works like a launch tier: the first turn runs on its table A model and effort without asking the judge, and the judge takes over from the second prompt.
+- **off** withdraws the model and effort tiergear applies, so the session runs on its own (startup flags, `/model`, `/effort`), and stops asking the judge. `[off]` stays bracketed until you pick a tier.
+- Picking a tier while off turns tiergear back on at that tier, on the session's own model with the effort from the tier, and the judge is asked again from the next prompt. That prompt becomes the task the judge reads.
+
+### Recent decisions
+
+Press **[ Recent ]** to open a pane listing this session's decisions, newest first, and press it again to close it. `/tiergear` opens the pane too. To hide the button, turn off `showRecentButton` in the plugin options. Each part of the band has its own option (`showPrefix`, `showStatusText` and the line's parts, `showTierButtons`, `showFloor`, `showRecentButton`); with all of them off the band draws nothing.
+
+```
+12:11  judge quick 0.44 → hold deep (low confidence) · opus/xhigh
+11:16  judge deep 0.52 → up deep (harder step) · opus/xhigh
+```
+
+Each line is: time, what the judge proposed and its confidence, what tiergear did and the resulting tier (with the reason), and the model/effort tiergear applied (`session` when it applied nothing). `judge skipped` means the judge wasn't asked (a launch floor, a picked tier, off, a paused judge); a failure shows its reason, like `judge timed out after 2000ms`. A pick from the band (a tier or off) reads `manual` instead, as in `manual → set quick (manual tier) · opus/low`. The pane reads the decision log, so it still works after a plugin reload; the line comes back with the next judged prompt.
+
+### Status line tools (ccstatusline)
+
+Claude Code's status JSON reports the session's own model and effort, not what tiergear applies per request, so a status line built from it misses tiergear's changes. The hook writes what the band shows to `~/.local/state/tiergear/status/<session>.json`, and `tiergear status` prints it:
+
+```bash
+tiergear status [tier|state|model|effort] [--session <id>] [--json] [--format <template>]
+```
+
+- The session is `--session`, else the `session_id` of the status JSON piped on stdin (what a status line command receives), else the session updated last.
+- Before tiergear has a value for the session (a new session, the first turn), the model and effort come from the status JSON on stdin, the session's own; the tier stays empty. A value tiergear doesn't know yet is filled the same way.
+- Default output: `deep · opus/xhigh`, `paused · sonnet/medium` when paused; nothing (exit 0) when neither tiergear nor the status JSON on stdin has a value, so a widget hides. The stdin fallback applies only without `--session`.
+- A field prints that value alone, for a widget of its own: `tiergear status model` prints `opus`, `tiergear status effort` prints `xhigh`, `tiergear status tier` prints `deep`, `tiergear status state` prints `auto` or `paused`. An unknown value prints nothing. A field wins over `--json` and `--format`.
+- `--format` fills `{tier}`, `{model}`, `{modelName}` (as Claude Code names it, `Opus 5.5`), `{effort}`, `{state}` (`auto` or `paused`) and `{line}` (the band's text); an unknown value is `-` (`unset` for the tier), and a template with no known value in it prints nothing. `--json` prints the whole record, or `null`.
+
+With the line shown there, turn off `showStatusText` to keep the band to its buttons.
+
+In [ccstatusline](https://github.com/sirmalloc/ccstatusline), add a **Custom Command** widget with the command `tiergear status`, or one widget per value (`tiergear status model`, `tiergear status effort`, ...) to color them apart (the CLI must be installed, see [CLI](#cli-optional)). It runs in about 50ms, well within the widget's default 1000ms timeout. The value follows a pick or a judged prompt at the next status line refresh.
+
+## CLI
+
+```bash
+tiergear launch "<brief>" [--agent claude|codex] [--worktree <path>] [--min-tier <tier>] [--max-tier <tier>] [--judge jev|laya|kev] [--judge-url <url>] [--judge-model <name>]
+tiergear orca-spawn "<brief>" --name <task> [--agent claude|codex] [--repo <dir>] [--base-branch <ref>] [--min-tier <tier>] [--max-tier <tier>] [--judge ...]
+tiergear stats [days]
+tiergear status [tier|state|model|effort] [--session <id>] [--json] [--format <template>]
+```
+
+- `launch`: judges the brief and prints the command to run (e.g. `claude --model opus --effort xhigh`). With Claude, `--worktree` writes a floor for that path. The path is stored as an absolute real path (symlinks resolved), so a relative path still works for a session opened in that folder. With `--agent codex`, floors are Claude-only, so none is written and a one-line note is printed instead.
+- `orca-spawn`: needs Orca, the multi-agent IDE, with its `orca` CLI on your PATH (or named by `ORCA_CLI_COMMAND`). It creates an Orca worktree, writes the floor, and starts the agent there with the judged model and effort. Prints the result as JSON. `--base-branch` picks the ref the worktree starts from; without it Orca uses the repo's default base, which may be a remote branch behind your local one. A brief that starts with `!` or `/` (which the agent's prompt would run as a shell or slash command) or holds control characters other than line breaks and tabs is refused before the judge is asked.
+  - **Inside an orchestration Run** (run from the coordinator terminal after `orca orchestration run-create`): starts the agent with `orca orchestration worker-start`, so the worker gets Orca's lifecycle preamble and reports `worker_done` to the Run. The JSON includes `dispatch` (`runId`, `taskId`, `dispatchId`, `handle`). A failed `worker-start` exits non-zero with Orca's error; don't rerun it blindly, since Orca may have left resources behind.
+  - **Without a Run**: creates a terminal, waits for the agent, then types the brief as is (no preamble, `dispatch` is `null`). If Claude asks whether to trust the folder, **`orca-spawn` does not approve it for you.** Approve it yourself in Orca within 120 seconds. If the agent isn't ready, the brief is **not sent** (exit code 1) and a fallback shell may be left in the worktree.
+  - The floor is written before the agent's first prompt in both cases. Without it, the first turn would be judged on Orca's preamble, which usually gives low confidence.
+- `stats`: number of recorded decisions, counts by change type, and response rate and average latency per judge (default 7 days).
+- `status`: what a session runs on now, for status line tools; see [Status line tools](#status-line-tools-ccstatusline).
+- `--min-tier <tier>` and `--max-tier <tier>` (either or both; trivial, quick, standard, deep or max) bound the launch. The judge's tier is clamped into the range, and tables A and B pick the model and effort from the clamped tier. The floor written for the session holds the clamped tier as its floor and `--max-tier` as its ceiling, so later turns stay in the range too. An unknown tier or a minimum above the maximum exits 2 before the judge is asked or a worktree is created. With `--agent codex` the range sets the starting tier only (floors are Claude-only), and a one-line note says so.
+- Both commands report the judge's tier beside the one applied. `launch` prints `tiergear: judged <tier>, applied <tier>` on stderr (`judged none` when the judge decided nothing); stdout stays the command alone. `orca-spawn`'s JSON has `tier`, the tier applied after the range, and `judgedTier`, the judge's tier before it (`null` when the judge failed, gave no tier, or had confidence under 0.5).
+- Without a range, a floor is written only when the judge actually decided. If the judge failed, didn't answer, or had low confidence and standard was used instead, no floor is written and a warning is printed. With `--min-tier` or `--max-tier`, standard is clamped into the range and the floor is written anyway, since the range is yours, not the judge's. So with only `--max-tier` and a failed judge, the session's floor is standard (or `--max-tier`, if lower).
+- The CLI's judge timeout is 5000ms.
+
+The CLI can't read plugin options, so it looks up settings from flags, then environment variables, then the preset.
+
+| Variable | Meaning |
+| --- | --- |
+| `TIERGEAR_JUDGE` | Judge name (default jev) |
+| `TIERGEAR_JUDGE_URL` | Judge address |
+| `TIERGEAR_JUDGE_MODEL` | Judge model |
+| `TIERGEAR_JUDGE_API_KEY` | Key (falls back to the preset's key env var, only for the preset's own address) |
+| `ORCA_CLI_COMMAND` | The `orca` executable `orca-spawn` runs (default `orca` on your PATH) |
+
+## Where things are stored
+
+| What | Location |
+| --- | --- |
+| Tables | `~/.config/tiergear/tables.json` |
+| Floors (valid 24 hours) | `~/.local/state/tiergear/floors/<fnv1a(worktree)>.json` |
+| Decision log (1000 lines per file; one file per session, not removed) | `~/.local/state/tiergear/decisions/<name>.jsonl` |
+| Status for status line tools (one small file per session, not removed) | `~/.local/state/tiergear/status/<session>.json` |
+| Session records (kept 7 days, newest 200) | Plugin `$.store` under `session:<id>` (the first prompt is truncated to 2000 characters, and dropped while a session is paused) |
+
+Raw prompt text is never written to the logs.
+
+## Cost
+
+- Changing the model and changing effort mid-session both invalidate the messages prompt cache (per Anthropic's docs). The first turn has no cache, so it costs nothing.
+- That's why the default mid-session change is effort only, and lowering only happens after repeated high-confidence turns, to keep changes rare.
+- Raising from a model without effort, like haiku if you set it, switches the model and breaks the cache once.
+- The judge call itself adds cost and latency to every judged prompt (within the timeouts above).
+
+## Data sent to the judge
+
+- First turn: the first prompt (only the start and end if long).
+- Later turns: the next prompt, the last 3 exchanges, the first prompt (up to 500 characters), the number of files edited, the repeated failure count, and the current tier and effort.
+  - An exchange is one prompt, the assistant's last words before the next prompt, and the names of the tools it used. Tool calls and their results are folded into it, so a busy turn doesn't push the conversation out of view.
+  - Recent text gets more room: the reply the next prompt answers is sent up to 1500 characters, keeping mostly its end, where a question usually sits. Prompts and older replies get 400 characters each. Longer text keeps its start and end.
+- jev sends data externally (TypeSafe). laya and kev stay on your local server (if you run kev on Modal, data goes there).
+- Prompts that aren't judged (see "Which prompts are judged" above) never go to the judge as the prompt being judged, but one can still appear among the recent exchanges: a task notification or a message from another session is a prompt in the conversation too. Nothing is masked, so with jev that text leaves your machine.
+
+## Limitations
+
+- Codex gets its model and effort only at launch (`launch`/`orca-spawn`). Mid-session adjustment works only in Claude Code.
+- Hooks are an early-access feature, so the contract can change with Claude Code updates.
+- The confidence thresholds (0.5, 0.85, 0.6) are tuned for Jev. For other judges, check response rate and latency with `tiergear stats` and adjust the options.
+- Subagent requests are left alone; only main-loop requests are changed.
+
+## Development
+
+`npm test`, `npm run typecheck` and `npm run validate:plugin` check a working copy. `types/claude-code.d.ts` is the hook API declaration Claude Code 2.1.289 generated; after a Claude Code update, replace it with the `.claude-plugin/types/claude-code/index.d.ts` the engine writes next to a loaded plugin.
+
+To release, set the same version in `package.json` and `.claude-plugin/plugin.json`, push, then publish a GitHub release tagged `v<version>` (`gh release create v<version> --generate-notes`). `.github/workflows/publish.yml` tests it and publishes it to npm through npm trusted publishing, with no token stored.
+
+## License
+
+MIT

package/dist/cli/bin.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { main } from './main.js';
+try {
+    process.exitCode = await main(process.argv.slice(2));
+}
+catch (error) {
+    console.error(`tiergear: ${error instanceof Error ? error.message : String(error)}`);
+    process.exitCode = 1;
+}

package/dist/cli/files.js

@@ -0,0 +1,43 @@
+import { mkdir, readFile, readdir, realpath, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { floorPath, normalizePath, serializeFloor } from '../core/floor.js';
+import { appendLogLine, decisionLogPath, decisionsDir, parseLogLines } from '../core/log.js';
+import { DEFAULT_TABLES, parseTablesFile, tablesPath } from '../core/tables.js';
+// The hook matches the session's cwd, which Claude Code reports as an absolute physical path.
+export async function realWorktree(worktree) {
+    const absolute = resolve(worktree);
+    return realpath(absolute).catch(() => absolute);
+}
+export async function writeFloorFile(home, worktree, floor, now) {
+    const real = normalizePath(await realWorktree(worktree));
+    const path = floorPath(home, real);
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, serializeFloor({ worktree: real, tier: floor.tier, createdAt: now, ceiling: floor.ceiling }));
+    return path;
+}
+export async function appendDecision(home, name, entry) {
+    const path = decisionLogPath(home, name);
+    await mkdir(dirname(path), { recursive: true });
+    const existing = await readFile(path, 'utf8').catch(() => '');
+    await writeFile(path, appendLogLine(existing, JSON.stringify(entry)));
+}
+export async function readDecisions(home) {
+    const dir = decisionsDir(home);
+    const names = await readdir(dir).catch(() => []);
+    const entries = [];
+    for (const name of names) {
+        if (!name.endsWith('.jsonl'))
+            continue;
+        entries.push(...parseLogLines(await readFile(join(dir, name), 'utf8')));
+    }
+    return entries;
+}
+export async function readTables(home) {
+    const text = await readFile(tablesPath(home), 'utf8').catch(() => null);
+    if (text === null)
+        return DEFAULT_TABLES;
+    const parsed = parseTablesFile(text);
+    if (!parsed)
+        console.error('tiergear: tables.json ignored: invalid JSON or values; using the default tables');
+    return parsed ?? DEFAULT_TABLES;
+}

package/dist/cli/judge.js

@@ -0,0 +1,19 @@
+import { JUDGE_PRESETS, isAllowedJudgeUrl, isJudgeName, presetKeyApplies } from '../core/judges/presets.js';
+// The CLI cannot read the plugin's options, so it takes flags first, then TIERGEAR_* variables, then the preset.
+export function cliJudgeOptions(flags, env) {
+    const name = flags.judge ?? env['TIERGEAR_JUDGE'] ?? 'jev';
+    if (!isJudgeName(name))
+        throw new Error(`unknown judge ${name} (use jev, laya or kev)`);
+    const preset = JUDGE_PRESETS[name];
+    const baseUrl = flags.url ?? env['TIERGEAR_JUDGE_URL'] ?? preset.baseUrl;
+    if (!isAllowedJudgeUrl(baseUrl))
+        throw new Error(`judge URL ${baseUrl} must be https, or http to localhost`);
+    const presetKey = presetKeyApplies(preset, baseUrl) ? env[preset.keyEnv] : undefined;
+    return {
+        name,
+        baseUrl,
+        model: flags.model ?? env['TIERGEAR_JUDGE_MODEL'] ?? preset.model,
+        apiKey: env['TIERGEAR_JUDGE_API_KEY'] || presetKey || undefined,
+        keyRequired: preset.keyRequired,
+    };
+}

package/dist/cli/launch.js

@@ -0,0 +1,50 @@
+import { firstTurnState } from '../core/state.js';
+import { firstTarget } from '../core/tables.js';
+import { TIER_ORDER, clampTier, isTier, launchCommand, tierRank } from '../core/tiers.js';
+export const CLI_TIMEOUT_MS = 5000;
+const MIN_CONFIDENCE = 0.5;
+export function parseTierRange(min, max) {
+    for (const [flag, value] of [['--min-tier', min], ['--max-tier', max]]) {
+        if (value !== undefined && !isTier(value))
+            return { ok: false, error: `${flag} must be one of ${TIER_ORDER.join('|')}, not "${value}"` };
+    }
+    const range = {};
+    if (isTier(min))
+        range.min = min;
+    if (isTier(max))
+        range.max = max;
+    if (range.min && range.max && tierRank(range.min) > tierRank(range.max))
+        return { ok: false, error: `--min-tier ${range.min} is above --max-tier ${range.max}` };
+    return { ok: true, range };
+}
+export async function planLaunch(params) {
+    const range = params.range ?? {};
+    const fallback = clampTier('standard', range);
+    const started = params.now();
+    const result = await params.judge.ask({ state: firstTurnState(params.brief), withStuck: false, timeoutMs: CLI_TIMEOUT_MS });
+    const ms = params.now() - started;
+    let judgedTier = null;
+    let confidence = null;
+    let warning = null;
+    let outcome = 'ok';
+    if (!result.ok) {
+        outcome = result.reason;
+        warning = `${params.judge.name} unavailable (${result.reason}); using ${fallback}`;
+    }
+    else if (!result.verdict.tier) {
+        warning = `${params.judge.name} gave no tier; using ${fallback}`;
+    }
+    else if (result.verdict.tier.confidence < MIN_CONFIDENCE) {
+        confidence = result.verdict.tier.confidence;
+        warning = `low confidence ${confidence.toFixed(2)} for ${result.verdict.tier.tier}; using ${fallback}`;
+    }
+    else {
+        judgedTier = result.verdict.tier.tier;
+        confidence = result.verdict.tier.confidence;
+    }
+    const tier = judgedTier === null ? fallback : clampTier(judgedTier, range);
+    // A range a person gave is not the judge's call, so it is floored even when the judge decided nothing.
+    const floor = warning === null || range.min || range.max ? { tier, ceiling: range.max } : null;
+    const target = firstTarget(params.tables, params.harness, tier);
+    return { tier, judgedTier, confidence, target, command: launchCommand(params.harness, target), warning, outcome, ms, floor };
+}

package/dist/cli/main.js

@@ -0,0 +1,145 @@
+import { parseArgs } from 'node:util';
+import { createSystemOneJudge } from '../core/judges/systemone.js';
+import { appendDecision, readDecisions, readTables, writeFloorFile } from './files.js';
+import { cliJudgeOptions } from './judge.js';
+import { parseTierRange, planLaunch } from './launch.js';
+import { createOrcaExec } from './orca.js';
+import { homeDir, nodeSleep, nodeTransport, readStdin } from './node.js';
+import { briefProblem, spawnWorker } from './spawn.js';
+import { summarize } from './stats.js';
+import { statusCommand } from './status.js';
+import { isStatusField } from '../core/status.js';
+export const USAGE = `usage:
+  tiergear launch "<brief>" [--agent claude|codex] [--worktree <path>] [--min-tier <tier>] [--max-tier <tier>] [--judge jev|laya|kev] [--judge-url <url>] [--judge-model <name>]
+  tiergear orca-spawn "<brief>" --name <task> [--agent claude|codex] [--repo <dir>] [--base-branch <ref>] [--min-tier <tier>] [--max-tier <tier>] [--judge ...]
+  tiergear stats [days]
+  tiergear status [tier|state|model|effort] [--session <id>] [--json] [--format <template>]
+  <tier> is one of trivial|quick|standard|deep|max`;
+async function plan(command, brief, harness, home, flags, range) {
+    const options = cliJudgeOptions(flags, process.env);
+    const judge = createSystemOneJudge({ ...options, transport: nodeTransport, sleep: nodeSleep });
+    const result = await planLaunch({ brief, harness, judge, tables: await readTables(home), now: Date.now, range });
+    if (result.warning)
+        console.error(`tiergear: ${result.warning}`);
+    try {
+        await appendDecision(home, `cli-${new Date().toISOString().slice(0, 10)}`, {
+            at: Date.now(),
+            source: 'cli',
+            session: command,
+            phase: 'launch',
+            judge: options.name,
+            tier: result.tier,
+            change: 'set',
+            confidence: result.confidence,
+            stuck: null,
+            outcome: result.outcome,
+            ms: result.ms,
+            applied: { model: result.target.model, effort: result.target.effort },
+            reason: command,
+        });
+    }
+    catch (error) {
+        console.error(`tiergear: decision log not written: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return result;
+}
+export async function main(argv) {
+    const [command, ...rest] = argv;
+    const { values, positionals } = parseArgs({
+        args: rest,
+        allowPositionals: true,
+        options: {
+            agent: { type: 'string', default: 'claude' },
+            worktree: { type: 'string' },
+            name: { type: 'string' },
+            repo: { type: 'string' },
+            'base-branch': { type: 'string' },
+            judge: { type: 'string' },
+            'judge-url': { type: 'string' },
+            'judge-model': { type: 'string' },
+            'min-tier': { type: 'string' },
+            'max-tier': { type: 'string' },
+            session: { type: 'string' },
+            json: { type: 'boolean', default: false },
+            format: { type: 'string' },
+        },
+    });
+    const home = homeDir();
+    if (command === 'status') {
+        const field = positionals[0];
+        if (positionals.length > 1 || (field !== undefined && !isStatusField(field))) {
+            console.error(USAGE);
+            return 2;
+        }
+        const out = await statusCommand({ home, session: values.session, stdin: () => readStdin(500), json: values.json, format: values.format, field });
+        if (out)
+            console.log(out);
+        return 0;
+    }
+    if (command === 'stats') {
+        const days = Number(positionals[0] ?? 7);
+        console.log(summarize(await readDecisions(home), Date.now() - days * 86_400_000));
+        return 0;
+    }
+    const brief = positionals.join(' ').trim();
+    const harness = values.agent;
+    if ((command !== 'launch' && command !== 'orca-spawn') || !brief || (harness !== 'claude' && harness !== 'codex')) {
+        console.error(USAGE);
+        return 2;
+    }
+    const flags = { judge: values.judge, url: values['judge-url'], model: values['judge-model'] };
+    const parsedRange = parseTierRange(values['min-tier'], values['max-tier']);
+    if (!parsedRange.ok) {
+        console.error(`tiergear: ${parsedRange.error}`);
+        return 2;
+    }
+    const { range } = parsedRange;
+    const ranged = range.min !== undefined || range.max !== undefined;
+    if (command === 'launch') {
+        const launch = await plan(command, brief, harness, home, flags, range);
+        // stdout carries only the command, so the tiers go to stderr.
+        console.error(`tiergear: judged ${launch.judgedTier ?? 'none'}, applied ${launch.tier}`);
+        if (harness === 'codex' && values.worktree)
+            console.error('tiergear: --worktree ignored: floors are Claude-only');
+        else if (harness === 'codex' && ranged)
+            console.error('tiergear: the tier range sets the start only: floors are Claude-only');
+        if (values.worktree && harness === 'claude') {
+            if (launch.floor)
+                await writeFloorFile(home, values.worktree, launch.floor, Date.now());
+            else
+                console.error('tiergear: no floor written (judge fallback)');
+        }
+        console.log(launch.command);
+        return 0;
+    }
+    if (!values.name) {
+        console.error(USAGE);
+        return 2;
+    }
+    const problem = briefProblem(brief);
+    if (problem) {
+        console.error(`tiergear: ${problem}`);
+        return 2;
+    }
+    const spawnPlan = await plan(command, brief, harness, home, flags, range);
+    if (harness === 'codex' && ranged)
+        console.error('tiergear: the tier range sets the start only: floors are Claude-only');
+    const result = await spawnWorker({
+        brief,
+        name: values.name,
+        harness,
+        repoDir: values.repo ?? process.cwd(),
+        baseBranch: values['base-branch'],
+        plan: spawnPlan,
+        orca: createOrcaExec(),
+        writeFloor: async (path, floor) => {
+            await writeFloorFile(home, path, floor, Date.now());
+        },
+        log: (line) => console.error(`tiergear: ${line}`),
+    });
+    if (result.status === 'not-started') {
+        console.error('tiergear: the agent did not become ready; the brief was not sent. A fallback shell may remain in the worktree.');
+    }
+    console.log(JSON.stringify({ ...result, tier: spawnPlan.tier, judgedTier: spawnPlan.judgedTier, command: spawnPlan.command }));
+    return result.status === 'sent' ? 0 : 1;
+}

package/dist/cli/node.js

@@ -0,0 +1,53 @@
+import { homedir } from 'node:os';
+import { MAX_RESPONSE_CHARS } from '../core/judges/systemone.js';
+import { CLI_TIMEOUT_MS } from './launch.js';
+// The judge's deadline only stops waiting; aborting the request is what lets the process exit, and the
+// byte limit keeps a runaway body from being read whole.
+export function createNodeTransport(deadlineMs, maxBytes = MAX_RESPONSE_CHARS) {
+    return async (url, init) => {
+        const response = await fetch(url, { ...init, signal: AbortSignal.timeout(deadlineMs) });
+        const reader = response.body?.getReader();
+        const chunks = [];
+        let size = 0;
+        for (;;) {
+            if (!reader)
+                break;
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            size += value.byteLength;
+            if (size > maxBytes) {
+                await reader.cancel();
+                throw new Error('judge response too large');
+            }
+            chunks.push(value);
+        }
+        return { status: response.status, ok: response.ok, text: Buffer.concat(chunks).toString('utf8') };
+    };
+}
+export const nodeTransport = createNodeTransport(CLI_TIMEOUT_MS + 1000);
+// unref so a pending deadline does not keep the CLI alive after the judge answered.
+export const nodeSleep = (ms) => new Promise((resolve) => {
+    setTimeout(resolve, ms).unref();
+});
+export function homeDir() {
+    return process.env['HOME'] ?? homedir();
+}
+// Reads what is piped in, giving up after timeoutMs so a stdin left open never hangs the command.
+export function readStdin(timeoutMs) {
+    if (process.stdin.isTTY)
+        return Promise.resolve(null);
+    return new Promise((resolve) => {
+        let text = '';
+        const done = (value) => {
+            clearTimeout(timer);
+            process.stdin.destroy();
+            resolve(value);
+        };
+        const timer = setTimeout(() => done(text || null), timeoutMs);
+        process.stdin.setEncoding('utf8');
+        process.stdin.on('data', (chunk) => (text += chunk));
+        process.stdin.on('end', () => done(text));
+        process.stdin.on('error', () => done(null));
+    });
+}