agent-shim 11.84.1 → 11.86.0

package/README.md

@@ -33,7 +33,7 @@ agent-shim was called `claude-use` until it was renamed. Everything written for
 
 - The `claude-use` command is installed beside `agent-shim` by every channel and runs the same program.
 - `CLAUDE_USE_*` environment variables are read wherever `AGENT_SHIM_*` is; the current name wins when both are set.
-- An existing `~/.claude-use` is used in place when there is no `~/.agent-shim`. Do not move it: macOS Claude Code keys each identity's Keychain login on the exact path of its configuration directory (`<root>/identities/<name>`), so relocating the root signs every identity out. A fresh installation uses `~/.agent-shim`.
+- An existing `~/.claude-use` is used in place when there is no `~/.agent-shim`. Do not move it: macOS Claude Code keys each identity's Keychain login on the exact path of its configuration directory (`<root>/identities/<id>`), so relocating the root signs every identity out. A fresh installation uses `~/.agent-shim`.
 - A committed `.claude-use.json` or `.claude-use.local.json` is read when the directory has no `.agent-shim.json` or `.agent-shim.local.json`; `configure` keeps writing into the legacy local file while it is the only one.
 - A farm manifest written under the old name is read, and replaced by the current one on the next resync.
 - A session launched by a release under the old name keeps working against a newer front door: its internal `x-claude-use-*` request headers are accepted as their `x-agent-shim-*` equivalents and never forwarded upstream.
@@ -54,7 +54,7 @@ That's it — with no further configuration, everything in `~/.claude` that isn'
 
 `agent-shim` separates two things most ad hoc multi-account setups conflate:
 
-- **An identity** is a login: the thing that owns credentials and daemon state, selected with `agent-shim run @<name>` or, once `agent-shim shim enable` has run, `claude @<name>`.
+- **An identity** is a login: the thing that owns credentials and daemon state, selected with `agent-shim run @<name>` or, once `agent-shim shim enable` has run, `claude @<name>`. Its name is the `name` in its `identity.json`; its directory is named by an id fixed when it is created, so `identity rename` changes the name and every reference to it without moving the directory, the login or the usage, while sessions keep running on it. See [docs/configuration-model.md](docs/configuration-model.md#identities).
 - **A configuration profile** is a reusable, named bundle of sharing rules, independent of any identity, resolved per working directory via directory rules or a committed `.agent-shim.json`.
 
 A third, optional thing sits on top of identities: **a pool** is a named list of them. Select `pool:<name>` where an identity name goes (`claude @pool:subs`) and agent-shim picks the member whose unused quota is closest to expiring, skipping any that are refused right now, using the usage it already records. A pool can instead declare `--preference listed`, which tries the members in the order the pool lists them, skipping only one that is refused right now. A member entry may itself name another pool (`pool:<name>`), which is ranked with its own policy and contributes its pick at that position, so "this identity first, then the fleet" nests the fleet rather than copying its member list; cycles are refused. Members that hold the same login (the same account in the same organisation) share one quota window, so a pool ranks them as one candidate and never fails over from one to the other; `pool add`, `pool set` and `doctor` warn when a pool lists two of them. See [docs/configuration-model.md](docs/configuration-model.md#pools-picking-an-account-at-launch). On a terminal, `agent-shim run` asks which identity to run as when none resolves, when a pool pick would change account, or when the identity is refused right now (`--pick` forces the question, `--no-pick` never asks); see [docs/configuration-model.md](docs/configuration-model.md#choosing-the-identity-at-launch-the-picker).
@@ -81,7 +81,7 @@ The full mechanics, including the credential block, the merge algorithm, conditi
 
 Every command is `agent-shim <noun> <verb> [name] [options]`, over the nouns `identity`, `profile`, `pool`, `provider`, `model`, `rule` and `job`, plus the top-level `run`, `configure`, `check`, `doctor`, `usage`, `update` and the others; `claude @<identity>` is the same as `agent-shim run @<identity>` once `agent-shim shim enable` has run. The full list of commands with every flag is in [docs/cli-reference.md](docs/cli-reference.md#full-command-list), and `agent-shim --help` and `agent-shim <noun> --help` print it from the installed version.
 
-Every `list`, `show`, `check`, `doctor` and `headroom status` prints text by default and JSON with `--json`, and so do the mutating commands (`add`, `set`, `remove` and `use` on identities, profiles, providers, pools and rules), which print one object naming the `action`, the `kind`, the `name` and, for a creation or update, the stored `value`. `identity rename` prints its report of what it moved and rewrote as the `value`, with the `action` `planned` under `--dry-run`. Prompts appear only when standard input is a terminal; without one, a command that needs input fails with the option that supplies it (a `remove` needs `--yes`). Failures print as `agent-shim: <message>` and exit 1, usage errors exit 2, a selected provider or identity whose credential block yields no token exits 64, and `AGENT_SHIM_DEBUG=1` adds stack traces to unexpected errors. `agent-shim completion <bash|zsh|fish>` prints a shell completion script.
+Every `list`, `show`, `check`, `doctor` and `headroom status` prints text by default and JSON with `--json`, and so do the mutating commands (`add`, `set`, `remove` and `use` on identities, profiles, providers, pools and rules), which print one object naming the `action`, the `kind`, the `name` and, for a creation or update, the stored `value`. `identity rename` prints its report of what it rewrote (and with `--move` moved) as the `value`, with the `action` `planned` under `--dry-run`. Prompts appear only when standard input is a terminal; without one, a command that needs input fails with the option that supplies it (a `remove` needs `--yes`). Failures print as `agent-shim: <message>` and exit 1, usage errors exit 2, a selected provider or identity whose credential block yields no token exits 64, and `AGENT_SHIM_DEBUG=1` adds stack traces to unexpected errors. `agent-shim completion <bash|zsh|fish>` prints a shell completion script.
 
 `agent-shim check [path]` resolves the full cascade for a directory without touching the farm, and is the primary way to answer "why is X shared or hidden here". `agent-shim doctor` audits the whole `~/.agent-shim` config graph at once: every identity, profile, `extends` chain, provider (naming the exact replacement for a file still in the format before the credential block) and directory rule, plus whether the right `agent-shim` is the one actually on `PATH`.