claude-org 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## Unreleased
+
+## 0.3.0 — 2026-10-10
+
+- `proxy`: each log line now names the model (`via <org> model=<model> -> <status>`), and the org and model of the last request are written to a JSON state file whose path is passed to `claude` as `CLAUDE_ORG_STATE_FILE`, for statusline and hooks (#12)
+- `probe` / `status`: `--model <id>` (or `CLAUDE_ORG_PROBE_MODEL`) checks that model instead of Haiku and appends `model_status=available|unavailable|unknown` (and `model_error=` when refused), so "5h allowed but this model is refused" is told apart. `auto` falls back to the default org when the preferred org refuses the model (#9)
+- `proxy`: `CLAUDE_ORG_STRATEGY=least-utilized` sends each request to the usable org with the lowest 5h utilization it has reported (orgs not yet measured are tried first). Unset keeps the priority order; the launch line and the log now show the strategy (#7)
+- Docs: proxy mode now explains that Agent-tool subagents go through the same proxy and what that implies (#16)
+
+## 0.2.2 — 2026-10-10
+
+- Development: `npm run release -- <patch|minor|major|X.Y.Z>` runs the whole release (checks, tests, CHANGELOG, version, commit, tag, push, npm publish, registry check)
+
+## 0.2.1 — 2026-10-10
+
+- `proxy`: a 429 is now classified before failing over (#8). Only a rejected 5h or 7d window takes the whole org out. Any other 429 (a used-up per-model allowance, a model that needs usage credits, a per-minute limit) takes the org out for that model only, for at most 10 minutes or the `retry-after` time, so other models keep using the org
+- `proxy`: the log now shows the reason of each 429 (`error.type: message`, decoded from a brotli/gzip/deflate body) and the rate-limit claim, and says to switch the model when every org refused the same model
+- Windows: launch `claude` without the Node DEP0190 deprecation warning (shell args passed as one quoted command string) (#10)
+
 ## 0.2.0 — 2026-10-03
 
 - Add `ccorg` as a short command alias for `claude-org` (same binary)

package/README.md

@@ -57,13 +57,22 @@ Repeat steps 1–2 **once per org**:
 | `claude-org proxy [claude args...]` | Launch via a local proxy: a **running** session fails over to another org the moment the 5h limit hits. Needs 2+ org tokens (incl. one for the default side). |
 | `claude-org auto [claude args...]` | Launch on the preferred org if usable, else on the default org. Decided once at launch. |
 | `claude-org <name> [claude args...]` | Launch with that org's token, e.g. `claude-org work --resume`. |
-| `claude-org probe [<name>]` | Print the org's 5h window state on one line (`status= 5h_util= 5h_reset= 5h_reset_local=`). Exit 0 when `allowed`. |
+| `claude-org probe [<name>] [--model <id>]` | Print the org's 5h window state on one line (`status= 5h_util= 5h_reset= 5h_reset_local=`). Exit 0 when `allowed`. With `--model`, probe with that model and append `model= model_status=` (see below). |
 | `claude-org watch` | Poll the preferred org until its window recovers, then notify (terminal + optional `CLAUDE_ORG_NOTIFY_CMD`). |
-| `claude-org status` | `claude auth status` for every saved token + the default login. |
+| `claude-org status [--model <id>]` | `claude auth status` and `probe` for every saved token + the default login. |
 | `claude-org list` | List saved org names. |
 
 `auto` and `<name>` only read env at launch — they cannot switch a running session. Settings, plugins, and session history live under `~/.claude/` and are shared across orgs, so `claude-org auto --resume` continues a session started under the other org.
 
+**Checking a model, not just the window**: `probe` and `status` use Haiku by default, but an org can show `status=allowed` and still refuse another model (for example one that needs usage credits). Pass the model your session uses:
+
+```sh
+claude-org probe work --model claude-fable-5-1
+# status=allowed 5h_util=0.34 ... model=claude-fable-5-1 model_status=unavailable model_error=rate_limit_error
+```
+
+`model_status` is `available` (2xx), `unavailable` (refused while the 5h/7d windows are not rejected; exit 1) or `unknown` (no response, bad token or permission, timeout, server error, or a rejected window; the exit code then follows `status` alone). Setting `CLAUDE_ORG_PROBE_MODEL` applies the same check to `probe`, `status` and `auto`; `auto` then launches on the default org when the preferred org refuses that model.
+
 The **preferred org** (used by `auto`, `watch`, and as `proxy`'s first candidate) resolves in this order: `CLAUDE_ORG_PREFER` -> first entry of `CLAUDE_ORG_ORDER` -> first `.token` file alphabetically.
 
 ## proxy mode
@@ -77,13 +86,29 @@ claude-org proxy --resume
 3. The proxy replaces the `Authorization` header with a real org token and forwards to `api.anthropic.com`. On a 429 or `anthropic-ratelimit-unified-5h-status: rejected` it marks that org limited until `5h-reset` and **resends the same request** with the next org's token.
 4. Claude Code only ever sees the successful response — the org switched mid-session. SSE streaming is piped through untouched.
 
-One log line per request (`via <org> -> <status>`) goes to a temp file printed at launch (`-> proxy 127.0.0.1:<port> (order: ..., log: ...)`).
+One log line per request (`via <org> model=<model> -> <status>`) goes to a temp file printed at launch (`-> proxy 127.0.0.1:<port> (order: ..., strategy: ..., log: ...)`). The prompt and the tokens are never logged.
+
+**Spreading load by utilization**: with `CLAUDE_ORG_STRATEGY=least-utilized`, the proxy remembers the `5h-utilization` each org last reported and sends each request to the usable org with the lowest value. An org that has not reported yet is tried first (in priority order) so it gets measured once; one that answers without a utilization goes after the measured ones. A value is forgotten when that org's 5h window resets. Rate-limited orgs are still skipped. Utilization is a share of each org's own plan, not an absolute amount, so a larger plan is picked more often; if you want one org's allowance used up first (e.g. your company's), keep the default and set `CLAUDE_ORG_ORDER` instead.
+
+**Which org is in use right now**: after each model request the proxy writes `{"org", "model", "status", "at"}` as JSON (`org` is `null` with `status` 503 when no org could serve) to `state.json` in the same temp directory as the log. Its path is exported to the `claude` process as `CLAUDE_ORG_STATE_FILE`, so a statusline command or hook can show it, e.g.:
+
+```sh
+[ -n "$CLAUDE_ORG_STATE_FILE" ] && [ -f "$CLAUDE_ORG_STATE_FILE" ] && node -p "require(process.env.CLAUDE_ORG_STATE_FILE).org"
+```
 
 **Limitations of proxy mode**
 
 - claude.ai connector MCPs (Gmail / Drive / Calendar / Notion / Slack …) and Remote Control are **unavailable**: `ANTHROPIC_AUTH_TOKEN` makes Claude Code treat the session as external-token auth, so `mcp__claude_ai_*` tools do not appear. Local/plugin MCPs work. Open connectors in a plain `claude --resume` session — history is shared.
 - Each proxy serves one session and dies when `claude` exits.
 
+**Subagents**
+
+- Subagents started with Claude Code's Agent tool run in the same process as the parent session and share its `ANTHROPIC_BASE_URL`, so they go through the same proxy with no setup and use the same orgs' limits. Their requests appear in the proxy log with their own `model=` (e.g. a Haiku subagent).
+- Not covered: a `claude` started as a separate process (it needs its own `claude-org proxy`), and agents that run in the cloud (e.g. `isolation: remote`).
+- The connector MCP limitation above applies to subagents too.
+- When an org's 5h or 7d window is rejected, the org is taken out for every model, so subagents also move to the next org until the window resets. A 429 for one model only (#8) moves that model only; other models, including those of subagents, stay on the org.
+- Work routed to a Team / Enterprise org (e.g. your company's) counts toward that org's usage, which its admins can see.
+
 ### Prompt cache & tool search
 
 A custom `ANTHROPIC_BASE_URL` + `ANTHROPIC_AUTH_TOKEN` makes Claude Code treat the session as API-key auth, which changes two defaults:
@@ -105,11 +130,14 @@ A custom `ANTHROPIC_BASE_URL` + `ANTHROPIC_AUTH_TOKEN` makes Claude Code treat t
 |---|---|---|
 | `CLAUDE_ORG_PREFER` | (unset) | Preferred org for `auto` / `watch` / `proxy` |
 | `CLAUDE_ORG_ORDER` | (unset) | Comma-separated org priority for `proxy`; unlisted orgs follow alphabetically |
+| `CLAUDE_ORG_STRATEGY` | (unset: priority order) | `least-utilized`: `proxy` sends each request to the usable org with the lowest 5h utilization (see proxy mode) |
+| `CLAUDE_ORG_PROBE_MODEL` | (unset: Haiku) | Model used by `probe` / `status` / `auto` to check the org; adds `model_status=` to the probe line |
 | `CLAUDE_ORG_TOKEN_DIR` | `~/.claude/org-tokens` | Where `<name>.token` files live |
 | `CLAUDE_ORG_NOTIFY_CMD` | (unset) | `watch` notification command, run as `<cmd> "<title>" "<message>"` via the OS shell |
 | `CLAUDE_ORG_WATCH_MAX_SLEEP` | `18000` | Max seconds between `watch` re-checks (values < 60 also lower the 60s minimum — for tests) |
 | `CLAUDE_ORG_UPSTREAM` | `https://api.anthropic.com` | API base URL for `probe` and `proxy` (stub upstream in tests) |
 | `CLAUDE_ORG_PROXY` | `1` when launched via `proxy` | Marker env passed to the claude process so user hooks can detect connector-less sessions |
+| `CLAUDE_ORG_STATE_FILE` | set when launched via `proxy` | Path of the JSON file holding the org and model of the last request (read it from a statusline or hook) |
 | `CLAUDE_ORG_FORCE_PROBE` | (unset) | Test seam: `allowed` / `rejected[:<epoch>]` / `rejected_until:<epoch>` fakes `probe` results without API calls |
 | `CLAUDE_ORG_REJECT_FILE` | (unset) | Test seam: orgs listed comma-separated in this file are treated as rate-limited by `proxy` |
 
@@ -130,6 +158,20 @@ npm test            # node:test suite, no real API calls
 npm pack --dry-run  # inspect the published file set
 ```
 
+### Releasing
+
+Write the changes under `## Unreleased` in `CHANGELOG.md`, then on an up-to-date `main`:
+
+```sh
+npm login                               # once per machine
+npm run release -- patch --dry-run      # checks + tests only, changes nothing
+npm run release -- patch                # or minor / major / X.Y.Z
+```
+
+The script refuses to run off `main`, with uncommitted tracked changes, out of sync with `origin/main`, with an existing tag or registry version, with files npm would publish that git does not track, or without npm login. It then runs the tests, renames `## Unreleased` to the new version heading, bumps `package.json`, commits `chore: release vX.Y.Z`, tags, pushes the commit and tag together (atomic), runs `npm publish` and waits until the registry serves the new version. `--no-publish` stops after the push.
+
+Users update with `npm install -g claude-org@latest`.
+
 ## License
 
 MIT

package/bin/claude-org.js

@@ -10,6 +10,23 @@ const { statusAll } = require('../lib/status');
 const { watch } = require('../lib/watch');
 const { proxyLaunch } = require('../lib/proxy');
 
+// `--model <id>` / `--model=<id>` for probe and status. Returns the model
+// ('' when absent) and the remaining args. A missing value is an error rather
+// than a silent fall back to the default model.
+function takeModel(args) {
+  const rest = [];
+  let model = '';
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--model' || args[i].startsWith('--model=')) {
+      model = args[i] === '--model' ? args[++i] : args[i].slice(8);
+      if (!model || model.startsWith('-')) throw new Error('--model needs a model id, e.g. --model claude-fable-5-1');
+    } else {
+      rest.push(args[i]);
+    }
+  }
+  return { model, rest };
+}
+
 async function main() {
   const [cmd, ...rest] = process.argv.slice(2);
   switch (cmd) {
@@ -23,11 +40,12 @@ async function main() {
       for (const o of listOrgs()) console.log(o);
       return 0;
     case 'status':
-      return statusAll();
+      return statusAll(takeModel(rest).model || undefined);
     case 'probe': {
-      const r = await probe(rest[0] || resolvePrefer());
+      const { model, rest: names } = takeModel(rest);
+      const r = await probe(names[0] || resolvePrefer(), model || undefined);
       if (r.line) console.log(r.line);
-      return r.allowed ? 0 : 1;
+      return r.usable ? 0 : 1;
     }
     case 'pick':
       console.log(await pick());

package/lib/claude-spawn.js

@@ -0,0 +1,16 @@
+'use strict';
+const { spawn } = require('child_process');
+
+// DEP0190: passing an args array with shell:true is deprecated (args are
+// concatenated unescaped). On Windows a shell is still needed to resolve
+// claude.cmd, so build a single quoted command string instead.
+const q = s => `"${String(s).replace(/(["\\$`])/g, '\\$1')}"`;
+
+function spawnClaude(args, opts = {}) {
+  if (process.platform === 'win32') {
+    return spawn(['claude', ...args.map(q)].join(' '), { ...opts, shell: true });
+  }
+  return spawn('claude', args, opts);
+}
+
+module.exports = { spawnClaude, q };

package/lib/launch.js

@@ -1,14 +1,13 @@
 'use strict';
-const { spawn } = require('child_process');
+const { spawnClaude } = require('./claude-spawn');
 const { readToken } = require('./config');
 
 // Spawn claude with inherited stdio and extra env. Resolves to the child's
 // exit code (128+n when killed by signal n, like a shell would report).
 function runClaude(args, envExtra = {}) {
   return new Promise(resolve => {
-    const child = spawn('claude', args, {
+    const child = spawnClaude(args, {
       stdio: 'inherit',
-      shell: process.platform === 'win32', // resolves claude.cmd on Windows
       env: { ...process.env, ...envExtra },
     });
     child.on('error', e => {

package/lib/pick.js

@@ -3,18 +3,23 @@ const { resolvePrefer } = require('./config');
 const { probe } = require('./probe');
 
 // pick(): which org `auto` should launch on. Returns 'default' when the
-// preferred org is over its 5h limit (or its token is missing). The decision
-// reason goes to stderr as a single `-> ...` line.
+// preferred org is over its 5h limit (or its token is missing), or refused the
+// model set in CLAUDE_ORG_PROBE_MODEL. The decision reason goes to stderr as a
+// single `-> ...` line.
 async function pick() {
   const prefer = resolvePrefer();
   const r = await probe(prefer);
-  if (r.allowed) {
+  if (r.usable) {
     let util = r.util;
     if (util !== '?') util = `${Math.trunc(Number(util) * 100)}%`;
     console.error(`-> ${prefer} (5h ${util} used)`);
     return prefer;
   }
-  console.error(`-> default (${prefer} is ${r.status}, resets ${r.resetLocal})`);
+  if (r.allowed) {
+    console.error(`-> default (${prefer} refused model ${r.model})`);
+  } else {
+    console.error(`-> default (${prefer} is ${r.status}, resets ${r.resetLocal})`);
+  }
   return 'default';
 }
 

package/lib/probe.js

@@ -2,18 +2,78 @@
 const { readToken } = require('./config');
 const { epochToHHMM } = require('./time');
 
-// probe(name): send a 1-token inference request and read the unified 5h
-// rate-limit headers. Returns { line, status, util, reset, resetLocal, allowed }.
-// `line` is the canonical one-line output:
+const DEFAULT_MODEL = 'claude-haiku-4-5-20251001';
+
+// Whether the org served the probed model. The 5h window is shared by every
+// model, but a model can still be refused while it reads "allowed" (it needs
+// usage credits, or its own weekly allowance is used up), so this is judged
+// from the HTTP status, not from the window headers.
+//   available    2xx
+//   unavailable  any other 4xx, while neither the 5h nor the 7d window is
+//                rejected
+//   unknown      no response, 401/403 (token or org permission), 408, 5xx, or
+//                a rejected window (which hides whether the model itself
+//                would be served)
+function judgeModel(res) {
+  if (!res) return 'unknown';
+  if (res.ok) return 'available';
+  const h = name => res.headers.get(`anthropic-ratelimit-unified-${name}`);
+  if (h('5h-status') === 'rejected' || h('7d-status') === 'rejected') return 'unknown';
+  if ([401, 403, 408].includes(res.status) || res.status >= 500 || res.status < 400) return 'unknown';
+  return 'unavailable';
+}
+
+// One 1-token request. Returns { res, errorType }: res is null when no response
+// came; errorType is error.type of a non-2xx JSON body ('' otherwise).
+async function send(tok, model) {
+  const base = (process.env.CLAUDE_ORG_UPSTREAM || 'https://api.anthropic.com').replace(/\/+$/, '');
+  try {
+    const res = await fetch(`${base}/v1/messages`, {
+      method: 'POST',
+      headers: {
+        authorization: `Bearer ${tok}`,
+        'anthropic-beta': 'oauth-2025-04-20',
+        'anthropic-version': '2023-06-01',
+        'content-type': 'application/json',
+      },
+      body: JSON.stringify({ model, max_tokens: 1, messages: [{ role: 'user', content: 'hi' }] }),
+      signal: AbortSignal.timeout(20000),
+    });
+    let errorType = '';
+    if (res.ok) {
+      res.body && res.body.cancel().catch(() => {});
+    } else {
+      try {
+        errorType = String(JSON.parse(await res.text()).error.type || '').replace(/[^\w.-]/g, '_').slice(0, 60);
+      } catch {
+        errorType = ''; // not a JSON error body: the HTTP status still decides model_status
+      }
+    }
+    return { res, errorType };
+  } catch {
+    return { res: null, errorType: '' };
+  }
+}
+
+// probe(name, model): send a 1-token inference request and read the unified
+// 5h rate-limit headers. Returns { line, status, util, reset, resetLocal,
+// allowed, model, modelStatus, usable }. `line` is the canonical one-line output:
 //   status=<allowed|rejected|unknown> 5h_util=<0.xx|?> 5h_reset=<epoch|?> 5h_reset_local=<HH:MM|?>
+// When a model is given (argument, else CLAUDE_ORG_PROBE_MODEL), the request
+// uses it and the line ends with ` model=<id> model_status=<see judgeModel>`,
+// plus ` model_error=<error.type>` when the model was refused.
+// Without one the request uses Haiku and the line is unchanged. `usable` is
+// "allowed and the model was not refused".
 //
 // Test seam: CLAUDE_ORG_FORCE_PROBE = allowed | rejected[:<epoch>] |
 // rejected_until:<epoch> (rejected_until flips to allowed once <epoch> passes).
 // When forced, the token file is not required and no request is sent.
 // CLAUDE_ORG_UPSTREAM overrides the API base URL (stub upstream in tests).
-async function probe(name) {
+async function probe(name, model = process.env.CLAUDE_ORG_PROBE_MODEL || '') {
   const forced = process.env.CLAUDE_ORG_FORCE_PROBE;
   let status, util, reset;
+  let modelStatus = 'unknown';
+  let modelError = '';
   if (forced) {
     const idx = forced.indexOf(':');
     status = idx === -1 ? forced : forced.slice(0, idx);
@@ -24,29 +84,26 @@ async function probe(name) {
     util = '?';
   } else {
     const tok = readToken(name);
-    if (tok === null) return { line: null, status: 'unknown', util: '?', reset: '?', resetLocal: '?', allowed: false };
-    const base = (process.env.CLAUDE_ORG_UPSTREAM || 'https://api.anthropic.com').replace(/\/+$/, '');
-    let headers = null;
-    try {
-      const res = await fetch(`${base}/v1/messages`, {
-        method: 'POST',
-        headers: {
-          authorization: `Bearer ${tok}`,
-          'anthropic-beta': 'oauth-2025-04-20',
-          'anthropic-version': '2023-06-01',
-          'content-type': 'application/json',
-        },
-        body: JSON.stringify({
-          model: 'claude-haiku-4-5-20251001',
-          max_tokens: 1,
-          messages: [{ role: 'user', content: 'hi' }],
-        }),
-        signal: AbortSignal.timeout(20000),
-      });
-      headers = res.headers;
-      res.body && res.body.cancel().catch(() => {});
-    } catch {
-      headers = null;
+    if (tok === null) {
+      return { line: null, status: 'unknown', util: '?', reset: '?', resetLocal: '?', allowed: false, model, modelStatus, usable: false };
+    }
+    const first = await send(tok, model || DEFAULT_MODEL);
+    let headers = first.res && first.res.headers;
+    modelStatus = judgeModel(first.res);
+    if (modelStatus === 'unavailable') modelError = first.errorType;
+    // A refusal for the model itself carried no window headers on 2026-10-10
+    // (Fable 5.1 on an org without usage credits), so the 5h state is read
+    // from a second request with the default model.
+    if (model && modelStatus === 'unavailable' && !headers.get('anthropic-ratelimit-unified-5h-status')) {
+      const second = await send(tok, DEFAULT_MODEL);
+      headers = second.res && second.res.headers;
+      // A rejected window there means the first 429 may have been the window,
+      // not the model, so the model cannot be judged.
+      const w = name => headers && headers.get(`anthropic-ratelimit-unified-${name}`);
+      if (w('5h-status') === 'rejected' || w('7d-status') === 'rejected') {
+        modelStatus = 'unknown';
+        modelError = '';
+      }
     }
     status = (headers && (headers.get('anthropic-ratelimit-unified-5h-status')
       || headers.get('anthropic-ratelimit-unified-status'))) || 'unknown';
@@ -54,8 +111,12 @@ async function probe(name) {
     reset = (headers && headers.get('anthropic-ratelimit-unified-5h-reset')) || '?';
   }
   const resetLocal = reset !== '?' ? epochToHHMM(reset) : '?';
-  const line = `status=${status} 5h_util=${util} 5h_reset=${reset} 5h_reset_local=${resetLocal}`;
-  return { line, status, util, reset, resetLocal, allowed: status === 'allowed' };
+  let line = `status=${status} 5h_util=${util} 5h_reset=${reset} 5h_reset_local=${resetLocal}`;
+  // The model is user input; keep the key=value line parseable.
+  if (model) line += ` model=${model.replace(/[^\w.:@/-]/g, '_')} model_status=${modelStatus}${modelError ? ` model_error=${modelError}` : ''}`;
+  const allowed = status === 'allowed';
+  const usable = allowed && !(model && modelStatus === 'unavailable');
+  return { line, status, util, reset, resetLocal, allowed, model, modelStatus, usable };
 }
 
 module.exports = { probe };

package/lib/proxy.js

@@ -6,6 +6,12 @@
 // with the next org's token. A running Claude Code session never sees the 429,
 // so the org switches without a restart.
 //
+// Not every 429 means the org is used up. A model can have its own limit (for
+// example a per-model weekly allowance, or usage credits that the org has not
+// enabled) while the 5h and 7d windows are still "allowed" and other models
+// work. Such a 429 only takes that org out for that model; the org keeps
+// serving other models.
+//
 // Why a proxy instead of apiKeyHelper: an OAuth long-lived token is accepted as
 // `Authorization: Bearer` alone, but if `x-api-key` is also present it is checked
 // first and returns 401. The proxy drops x-api-key and sends Bearer only.
@@ -15,14 +21,100 @@
 //                          "listening on" stderr line)
 //   CLAUDE_ORG_TOKEN_DIR   where <name>.token files live (~/.claude/org-tokens)
 //   CLAUDE_ORG_ORDER       org priority, comma-separated (default: alphabetical)
+//   CLAUDE_ORG_STRATEGY    "least-utilized": prefer the usable org with the
+//                          lowest 5h utilization seen so far (default: ORDER)
 //   CLAUDE_ORG_UPSTREAM    forward target (default https://api.anthropic.com)
 //   CLAUDE_ORG_REJECT_FILE test seam: orgs listed comma-separated in this file
 //                          are treated as rate-limited
+//   CLAUDE_ORG_STATE_FILE  where the org and model of the last /v1/messages
+//                          response are written as JSON (unset: not written)
 const http = require('http');
 const https = require('https');
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
+const zlib = require('zlib');
+
+// How long an org stays out when it is org-wide limited but sent no reset time,
+// and the longest a model-specific refusal keeps an (org, model) pair out.
+const ORG_REJECT_FALLBACK_MS = 10 * 60 * 1000;
+const MODEL_REJECT_MAX_MS = 10 * 60 * 1000;
+// A real 429 body is well under 1 KiB. These caps keep a misbehaving upstream
+// from exhausting memory: the raw body read, and the decompressed copy.
+const ERROR_BODY_MAX_BYTES = 1024 * 1024;
+const ERROR_DECODED_MAX_BYTES = 64 * 1024;
+
+// The "model" field of a /v1/messages request body, or '?' when the body is
+// not JSON (the proxy must still forward it). Used as is as the quarantine
+// key, so two different model names never share a key.
+function requestModel(body) {
+  try {
+    const m = JSON.parse(body.toString('utf8')).model;
+    return typeof m === 'string' && m ? m : '?';
+  } catch {
+    return '?';
+  }
+}
+
+// The model name for the log: client input, so limited to safe characters and
+// cut short.
+function logModel(model) {
+  return model.replace(/[^\w.:@/-]/g, '_').slice(0, 80);
+}
+
+// Milliseconds from a Retry-After header, which is either delay-seconds or an
+// HTTP-date. NaN when absent or unparsable.
+function retryAfterMs(value) {
+  if (value === undefined || value === '') return NaN;
+  const secs = Number(value);
+  if (Number.isFinite(secs)) return secs >= 0 ? secs * 1000 : NaN;
+  const at = Date.parse(value);
+  return Number.isFinite(at) ? Math.max(0, at - Date.now()) : NaN;
+}
+
+function readBody(res, maxBytes) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    let size = 0;
+    res.on('data', c => {
+      size += c.length;
+      if (size > maxBytes) {
+        res.destroy();
+        reject(new Error(`429 body larger than ${maxBytes} bytes`));
+        return;
+      }
+      chunks.push(c);
+    });
+    res.on('end', () => resolve(Buffer.concat(chunks)));
+    res.on('error', reject);
+  });
+}
+
+// The API compresses error bodies (brotli was observed on 2026-10-10) when the
+// client sent accept-encoding. Decode a copy for the log; the client still
+// gets the original bytes with the original content-encoding header.
+// maxOutputLength makes a decompression bomb throw instead of filling memory.
+function decodeBody(buf, encoding) {
+  const opts = { maxOutputLength: ERROR_DECODED_MAX_BYTES };
+  switch ((encoding || '').trim().toLowerCase()) {
+    case 'br': return zlib.brotliDecompressSync(buf, opts);
+    case 'gzip': case 'x-gzip': return zlib.gunzipSync(buf, opts);
+    case 'deflate': return zlib.inflateSync(buf, opts);
+    default: return buf;
+  }
+}
+
+// "error.type: error.message" from an API error body, for the log line. The
+// message is cut short; the full body still reaches the client.
+function describeError(buf, encoding) {
+  try {
+    const e = JSON.parse(decodeBody(buf, encoding).toString('utf8')).error || {};
+    const msg = String(e.message || '').replace(/\s+/g, ' ').slice(0, 160);
+    return msg ? `${e.type || 'unknown_error'}: ${msg}` : (e.type || 'unknown_error');
+  } catch {
+    return 'non-JSON 429 body';
+  }
+}
 
 function createProxy(opts = {}) {
   const TOKEN_DIR = opts.tokenDir || process.env.CLAUDE_ORG_TOKEN_DIR
@@ -31,12 +123,16 @@ function createProxy(opts = {}) {
     || (process.env.CLAUDE_ORG_ORDER || '').split(',').map(s => s.trim()).filter(Boolean);
   const UPSTREAM = new URL(opts.upstream || process.env.CLAUDE_ORG_UPSTREAM || 'https://api.anthropic.com');
   const REJECT_FILE = 'rejectFile' in opts ? opts.rejectFile : (process.env.CLAUDE_ORG_REJECT_FILE || '');
+  const STATE_FILE = 'stateFile' in opts ? opts.stateFile : (process.env.CLAUDE_ORG_STATE_FILE || '');
+  const STRATEGY = 'strategy' in opts ? opts.strategy : (process.env.CLAUDE_ORG_STRATEGY || '');
   const out = opts.log || process.stderr;
   const transport = UPSTREAM.protocol === 'http:' ? http : https;
 
   function log(...a) {
     out.write(`[claude-org-proxy ${new Date().toISOString().slice(11, 19)}] ${a.join(' ')}\n`);
   }
+  const leastUtilized = STRATEGY === 'least-utilized';
+  if (STRATEGY && !leastUtilized) log(`unknown CLAUDE_ORG_STRATEGY "${STRATEGY}" -> using the static order`);
 
   function listOrgs() {
     const files = fs.readdirSync(TOKEN_DIR).filter(f => f.endsWith('.token')).map(f => f.slice(0, -6)).sort();
@@ -59,6 +155,15 @@ function createProxy(opts = {}) {
       return false;
     }
   }
+  // Per-(org, model) memory for model-specific refusals: "org|model" -> epoch (ms).
+  const modelRejectedUntil = new Map();
+  function isModelRejected(name, model) {
+    const key = `${name}|${model}`;
+    const until = modelRejectedUntil.get(key);
+    if (until === undefined) return false;
+    if (Date.now() >= until) { modelRejectedUntil.delete(key); return false; }
+    return true;
+  }
   function isRejected(name) {
     if (fileRejected(name)) return true;
     const until = rejectedUntil.get(name);
@@ -66,11 +171,63 @@ function createProxy(opts = {}) {
     if (Date.now() >= until) { rejectedUntil.delete(name); return false; }
     return true;
   }
+  // Latest 5h utilization (0..1) each org reported, valid until that window's
+  // reset: name -> { util, until (epoch ms) }. An org that is not picked would
+  // otherwise keep its old high value after its window resets.
+  const utilization = new Map();
+  // Orgs that answered without a utilization header, so they are not put first
+  // again and again as "not measured yet".
+  const answeredUnmeasured = new Set();
+  function utilOf(name) {
+    const e = utilization.get(name);
+    if (e === undefined) return undefined;
+    if (Date.now() >= e.until) { utilization.delete(name); return undefined; }
+    return e.util;
+  }
+  function recordUtil(name, util, reset) {
+    const until = Number.isFinite(reset) ? reset * 1000 : Infinity;
+    utilization.set(name, { util, until });
+    answeredUnmeasured.delete(name);
+  }
   // Usable orgs first, in priority order; rate-limited orgs are moved to the
   // tail (kept as a last resort when everything is limited).
-  function pickOrder() {
+  // least-utilized: among the usable orgs, those that have not been measured
+  // come first (in priority order) so that each is measured once, then the
+  // rest by utilization, lowest first, then those that answered without a
+  // utilization. Utilization is a share of each org's own plan, not an
+  // absolute amount, so a larger plan is picked more often.
+  function pickOrder(model) {
     const orgs = listOrgs();
-    return orgs.filter(o => !isRejected(o)).concat(orgs.filter(o => isRejected(o)));
+    const blocked = o => isRejected(o) || isModelRejected(o, model);
+    let usable = orgs.filter(o => !blocked(o));
+    if (leastUtilized) {
+      const known = usable.filter(o => utilOf(o) !== undefined).sort((a, b) => utilOf(a) - utilOf(b));
+      const unknown = usable.filter(o => utilOf(o) === undefined);
+      usable = unknown.filter(o => !answeredUnmeasured.has(o))
+        .concat(known, unknown.filter(o => answeredUnmeasured.has(o)));
+    }
+    return usable.concat(orgs.filter(blocked));
+  }
+
+  // Claude Code does not show the x-claude-org response header, so the org in
+  // use is written to a file that a statusline or hook can read. Written via a
+  // rename so a reader never sees a half-written file. No prompt or token goes in.
+  // The model is stored in full (JSON escapes it), unlike the cut log copy, so
+  // two long model names stay distinguishable.
+  // On Windows the rename fails while a reader holds the file open; that write
+  // is skipped and only the first failure is logged, to keep the log readable.
+  let stateWriteFailed = false;
+  function writeState(org, model, status) {
+    if (!STATE_FILE) return;
+    const tmp = `${STATE_FILE}.${process.pid}.tmp`;
+    try {
+      fs.writeFileSync(tmp, JSON.stringify({ org, model, status, at: new Date().toISOString() }) + '\n');
+      fs.renameSync(tmp, STATE_FILE);
+    } catch (e) {
+      try { fs.unlinkSync(tmp); } catch { /* the tmp file was never created */ }
+      if (!stateWriteFailed) log(`cannot write state file ${STATE_FILE}: ${e.message} (further failures are not logged)`);
+      stateWriteFailed = true;
+    }
   }
 
   function forward(org, method, urlPath, headers, body) {
@@ -99,8 +256,10 @@ function createProxy(opts = {}) {
     clientReq.on('end', async () => {
       const body = Buffer.concat(chunks);
       const isModelReq = clientReq.url.startsWith('/v1/messages');
-      const order = pickOrder();
+      const model = isModelReq ? requestModel(body) : '';
+      const order = pickOrder(model);
       let attempt = 0;
+      let modelRefusals = 0;
       for (const org of order) {
         attempt++;
         let up;
@@ -110,29 +269,86 @@ function createProxy(opts = {}) {
           log(`upstream error via ${org}: ${e.message}`);
           continue;
         }
-        const status5h = up.headers['anthropic-ratelimit-unified-5h-status'];
-        const reset5h = Number(up.headers['anthropic-ratelimit-unified-5h-reset']);
-        const limited = up.statusCode === 429 || status5h === 'rejected';
-        if (limited && isModelReq && attempt < order.length) {
-          rejectedUntil.set(org, Number.isFinite(reset5h) ? reset5h * 1000 : Date.now() + 10 * 60 * 1000);
-          log(`${org} is rate-limited (HTTP ${up.statusCode}, 5h=${status5h ?? '?'}) -> retrying with next org`);
-          up.resume(); // discard the response body and try the next org
+        const hdr = name => up.headers[`anthropic-ratelimit-unified-${name}`];
+        const status5h = hdr('5h-status');
+        const status7d = hdr('7d-status');
+        const claim = hdr('representative-claim');
+        const util5h = Number(hdr('5h-utilization'));
+        if (isModelReq && hdr('5h-utilization') !== undefined && Number.isFinite(util5h)) {
+          recordUtil(org, util5h, Number(hdr('5h-reset')));
+        } else if (isModelReq) {
+          answeredUnmeasured.add(org);
+        }
+        // The 5h and 7d windows cover every model of the org, so only those make
+        // the org as a whole unusable. Other refusals are per model: a used-up
+        // per-model weekly allowance (claim=seven_day_overage_included) or a model
+        // that needs usage credits (429 with no window headers). The overall
+        // "unified-status" header is not used: it also reads "rejected" for those.
+        const orgWide = status5h === 'rejected' || status7d === 'rejected';
+        const limited = up.statusCode === 429 || orgWide;
+        const windows = `5h=${status5h ?? '?'}${claim ? `, claim=${claim}` : ''}`;
+        // A 429 body is a small JSON error; buffer it to log the reason and,
+        // if no org is left, to hand it to the client unchanged.
+        let errBody = null;
+        let reason = '';
+        if (isModelReq && up.statusCode === 429) {
+          try {
+            errBody = await readBody(up, ERROR_BODY_MAX_BYTES);
+          } catch (e) {
+            log(`upstream error via ${org} while reading 429 body: ${e.message}`);
+            continue;
+          }
+          reason = describeError(errBody, up.headers['content-encoding']);
+        }
+        const modelRefused = isModelReq && up.statusCode === 429 && !orgWide;
+        if (modelRefused) {
+          // retry-after is honoured when shorter (a transient per-minute limit
+          // must not keep the preferred org out for long); a long one (a weekly
+          // per-model allowance) is capped so the org is re-checked now and then.
+          const ra = retryAfterMs(up.headers['retry-after']);
+          const ms = Number.isFinite(ra) ? Math.min(ra, MODEL_REJECT_MAX_MS) : MODEL_REJECT_MAX_MS;
+          modelRejectedUntil.set(`${org}|${model}`, Date.now() + ms);
+        }
+        const isLast = attempt >= order.length;
+        if (limited && isModelReq && !isLast) {
+          if (orgWide) {
+            // When both windows are rejected the org is back only after the later reset.
+            const resets = [['5h', status5h], ['7d', status7d]]
+              .filter(([, s]) => s === 'rejected')
+              .map(([w]) => Number(hdr(`${w}-reset`)))
+              .filter(Number.isFinite);
+            rejectedUntil.set(org, resets.length ? Math.max(...resets) * 1000 : Date.now() + ORG_REJECT_FALLBACK_MS);
+            log(`${org} is rate-limited (HTTP ${up.statusCode}, ${windows}) -> retrying with next org${reason ? ` (${reason})` : ''}`);
+          } else {
+            modelRefusals++;
+            log(`${org} rejected model ${logModel(model)} (HTTP ${up.statusCode}, ${windows}, ${reason}) -> retrying with next org; ${org} stays in use for other models`);
+          }
+          if (!errBody) up.resume(); // discard the response body and try the next org
           continue;
         }
         if (isModelReq) {
-          const util = up.headers['anthropic-ratelimit-unified-5h-utilization'];
-          log(`${clientReq.method} ${clientReq.url} via ${org} -> ${up.statusCode} (5h ${status5h ?? '?'} ${util ?? '?'})`);
+          const util = hdr('5h-utilization');
+          log(`${clientReq.method} ${clientReq.url} via ${org} model=${logModel(model)} -> ${up.statusCode} (5h ${status5h ?? '?'} ${util ?? '?'})${reason ? ` ${reason}` : ''}`);
+          writeState(org, model, up.statusCode);
+          if (modelRefused && modelRefusals === attempt - 1) {
+            log(`all orgs rejected model ${logModel(model)} -> switch the model (e.g. /model) or wait for that model's limit to reset; the org tokens are not the cause`);
+          }
         }
         clientRes.writeHead(up.statusCode, { ...up.headers, 'x-claude-org': org });
-        up.pipe(clientRes); // SSE streaming is piped through untouched
+        if (errBody) {
+          clientRes.end(errBody);
+        } else {
+          up.pipe(clientRes); // SSE streaming is piped through untouched
+        }
         return;
       }
+      if (isModelReq) writeState(null, model, 503); // no org served it
       clientRes.writeHead(503, { 'content-type': 'application/json' });
       clientRes.end(JSON.stringify({ type: 'error', error: { type: 'claude_org_proxy', message: 'all orgs rate-limited or unreachable' } }));
     });
   });
 
-  return { server, listOrgs, log, upstream: UPSTREAM };
+  return { server, listOrgs, log, upstream: UPSTREAM, strategy: leastUtilized ? 'least-utilized' : 'order' };
 }
 
 // `claude-org proxy [claude args...]`: start an in-process proxy on a random
@@ -150,15 +366,17 @@ async function proxyLaunch(args) {
   }
 
   const order = process.env.CLAUDE_ORG_ORDER || resolvePrefer();
-  const logf = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'claude-org-proxy-')), 'proxy.log');
+  const runDir = fs.mkdtempSync(path.join(os.tmpdir(), 'claude-org-proxy-'));
+  const logf = path.join(runDir, 'proxy.log');
+  const stateFile = path.join(runDir, 'state.json');
   const logStream = fs.createWriteStream(logf);
-  const { server, log, upstream } = createProxy({ order: order.split(','), log: logStream });
+  const { server, log, upstream, strategy } = createProxy({ order: order.split(','), log: logStream, stateFile });
 
   try {
     await new Promise((resolve, reject) => {
       server.once('error', reject);
       server.listen(0, '127.0.0.1', () => {
-        log(`listening on http://127.0.0.1:${server.address().port} orgs=${listOrgs().join(',')} upstream=${upstream.host}`);
+        log(`listening on http://127.0.0.1:${server.address().port} orgs=${listOrgs().join(',')} upstream=${upstream.host} strategy=${strategy}`);
         resolve();
       });
     });
@@ -167,7 +385,7 @@ async function proxyLaunch(args) {
     return 1;
   }
   const port = server.address().port;
-  console.error(`-> proxy 127.0.0.1:${port} (order: ${order}, log: ${logf})`);
+  console.error(`-> proxy 127.0.0.1:${port} (order: ${order}, strategy: ${strategy}, log: ${logf})`);
 
   // A custom ANTHROPIC_BASE_URL + AUTH_TOKEN makes Claude Code treat the session
   // as API-key auth: prompt cache TTL drops to 5min and MCP tool search is
@@ -176,6 +394,7 @@ async function proxyLaunch(args) {
     ANTHROPIC_BASE_URL: `http://127.0.0.1:${port}`,
     ANTHROPIC_AUTH_TOKEN: 'claude-org-proxy', // dummy; the proxy replaces it
     CLAUDE_ORG_PROXY: '1',                    // marker: "connector MCPs unavailable" session
+    CLAUDE_ORG_STATE_FILE: stateFile,         // last org/model, for statusline and hooks
   };
   if (!process.env.CLAUDE_CODE_PROMPT_CACHE_TTL) envExtra.CLAUDE_CODE_PROMPT_CACHE_TTL = '1h';
   if (!process.env.ENABLE_TOOL_SEARCH) envExtra.ENABLE_TOOL_SEARCH = 'true';
@@ -190,9 +409,9 @@ async function proxyLaunch(args) {
 // `node claude-org-proxy.js`).
 if (require.main === module) {
   const PORT = Number(process.env.PORT || 0);
-  const { server, listOrgs, log, upstream } = createProxy();
+  const { server, listOrgs, log, upstream, strategy } = createProxy();
   server.listen(PORT, '127.0.0.1', () => {
-    log(`listening on http://127.0.0.1:${server.address().port} orgs=${listOrgs().join(',')} upstream=${upstream.host}`);
+    log(`listening on http://127.0.0.1:${server.address().port} orgs=${listOrgs().join(',')} upstream=${upstream.host} strategy=${strategy}`);
   });
 }
 

package/lib/status.js

@@ -1,5 +1,5 @@
 'use strict';
-const { spawn } = require('child_process');
+const { spawnClaude } = require('./claude-spawn');
 const { listOrgs, readToken } = require('./config');
 const { probe } = require('./probe');
 
@@ -10,8 +10,7 @@ const KEYS_RE_DEFAULT = /"(loggedIn|authMethod|orgName|subscriptionType)"/;
 // Run `claude auth status` and return combined stdout+stderr (like 2>&1).
 function authStatus(envExtra = {}) {
   return new Promise(resolve => {
-    const child = spawn('claude', ['auth', 'status'], {
-      shell: process.platform === 'win32',
+    const child = spawnClaude(['auth', 'status'], {
       env: { ...process.env, ...envExtra },
     });
     const chunks = [];
@@ -22,7 +21,8 @@ function authStatus(envExtra = {}) {
   });
 }
 
-async function statusAll() {
+// model: passed to probe (undefined -> CLAUDE_ORG_PROBE_MODEL or Haiku).
+async function statusAll(model) {
   for (const name of listOrgs()) {
     const tok = readToken(name);
     if (tok === null) continue;
@@ -30,7 +30,7 @@ async function statusAll() {
     const out = await authStatus({ CLAUDE_CODE_OAUTH_TOKEN: tok });
     const lines = out.split('\n').filter(l => KEYS_RE.test(l));
     console.log(lines.length ? lines.join('\n') : '  (auth status failed)');
-    const r = await probe(name);
+    const r = await probe(name, model);
     if (r.line) console.log(`  ${r.line}`);
   }
   console.log('== default (no env) ==');

package/lib/usage.js

@@ -24,11 +24,15 @@ token org alphabetically):
   claude-org auto [claude args...]    launch on <prefer> if usable, else default
                                     (decided once at launch)
   claude-org <name> [claude args...]  e.g. claude-org work --resume
-  claude-org probe [<name>]           print the org's 5h window state on one line
-                                    (exit 0 when allowed)
+  claude-org probe [<name>] [--model <id>]
+                                    print the org's 5h window state on one line
+                                    (exit 0 when allowed); with --model, probe with
+                                    that model and add model_status= (exit 1 when
+                                    the org refused it)
   claude-org watch                    wait until <prefer> recovers, then notify
                                     (terminal + optional CLAUDE_ORG_NOTIFY_CMD)
-  claude-org status                   show \`claude auth status\` for each org token
+  claude-org status [--model <id>]    show \`claude auth status\` and probe for each
+                                    org token
   claude-org list                     list saved org names
 
 auto / <name> only read env at launch, so they cannot switch mid-session. To keep

package/lib/watch.js

@@ -1,5 +1,6 @@
 'use strict';
 const { spawn } = require('child_process');
+const { q } = require('./claude-spawn');
 const { resolvePrefer } = require('./config');
 const { probe } = require('./probe');
 const { hhmmss } = require('./time');
@@ -16,7 +17,6 @@ function notify(title, message) {
   }
   // Quote args ourselves: spawn(shell:true) does not quote on Windows and the
   // title/message contain spaces.
-  const q = s => `"${String(s).replace(/(["\\$`])/g, '\\$1')}"`;
   return new Promise(resolve => {
     const child = spawn(`${cmd} ${q(title)} ${q(message)}`, { shell: true, stdio: 'ignore' });
     child.on('error', () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-org",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Switch Claude Code between multiple Anthropic organizations, with automatic failover on the 5-hour rate limit",
   "license": "MIT",
   "type": "commonjs",
@@ -19,7 +19,8 @@
     "CHANGELOG.md"
   ],
   "scripts": {
-    "test": "node --test"
+    "test": "node --test",
+    "release": "node scripts/release.js"
   },
   "keywords": [
     "claude-code",