brindle 0.3.2__tar.gz → 0.3.4__tar.gz

{brindle-0.3.2 → brindle-0.3.4}/.gitignore

@@ -10,3 +10,5 @@ graphify-out/
 docs/
 .brindle/config.local.json
 .brindle/bench.json
+.DS_Store
+commit_msg.txt

{brindle-0.3.2 → brindle-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: brindle
-Version: 0.3.2
+Version: 0.3.4
 Summary: Run coding agents in parallel, each on its own git branch, with a supervisor that delegates, reviews, and merges
 Project-URL: Homepage, https://pawdelta.com/brindle/
 Project-URL: Documentation, https://pawdelta.com/brindle/docs/recommended-use
@@ -89,7 +89,7 @@ uv tool install --editable ~/Projects/brindle   # or from a local checkout
 brindle drives Claude Code, so you need that too (`npm install -g @anthropic-ai/claude-code`).
 
 `brindle --version` prints the installed version; the tmux status bar of every brindle
-session shows it too (`brindle 0.3.2`). A session started before an upgrade keeps
+session shows it too (`brindle 0.3.4`). A session started before an upgrade keeps
 running the old code, and shows the old number, until you restart it.
 
 ## Quick start
@@ -118,11 +118,11 @@ a writable home) and, in a repo, what's set up for it, and says what to do about
 anything missing. Bare `brindle` runs the essential ones (tmux, the chat's CLI)
 before it launches anything.
 
-That's it. `brindle` opens a supervisor chat (Claude Code) in your repo, with a
-narrow sidebar on the left showing every agent: who's working, who's idle, and
-who's waiting for your approval. Tell the supervisor what you want. It splits the
-work between workers, each on its own branch, then reviews and merges their
-branches. It starts in under a second.
+That's it. Bare `brindle` opens a fresh interactive developer chat (Claude Code)
+in your repo (with autopilot off), with a narrow sidebar on the left showing every
+agent: who's working, who's idle, and who's waiting for your approval. To launch an
+autopilot supervisor that splits work between parallel workers, reviews, and merges
+their branches toward verified milestones, run `brindle supervisor`. It starts in under a second.
 
 **The sidebar follows you.** There's one sidebar pane per session root, not
 one per window: switch to any other brindle window or session (⏎ in the
@@ -242,7 +242,7 @@ for mechanical edits and a Codex reviewer for a second model's opinion.
 
 ## Autopilot
 
-`brindle` starts the supervisor with autopilot on. Tell it what we're building,
+`brindle supervisor` starts the supervisor with autopilot on (or `brindle start -a supervisor`). Tell it what we're building,
 or put the goal in `.brindle/goals.md`, and it works like a project manager:
 
 1. **Goal and milestones.** The goal is split into milestones, and each one has
@@ -337,7 +337,8 @@ your own status line prints, so what you see doesn't change.
 
 | | |
 |---|---|
-| `brindle` | a fresh supervisor chat here, dashboard alongside |
+| `brindle` | a fresh developer chat here (autopilot off), dashboard alongside |
+| `brindle supervisor` | start an explicit autopilot supervisor chat to coordinate parallel workers and milestones |
 | `brindle init` | detect setup and test commands, write `.brindle/config.json`, check tools |
 | `brindle demo [--local]` | watch brindle finish a tiny practice repo: parallel workers, reviews, gated merges |
 | `brindle new BRANCH [-b BASE] [-a PROFILE] [-p PROMPT]` | worktree + branch + agent |
@@ -346,6 +347,7 @@ your own status line prints, so what you see doesn't change.
 | `brindle start [-a PROFILE] [-p PROMPT] [--no-watch] [--no-autopilot] [-b BRANCH] [-w PATH]` | the same, with options; `-b`/`-w` run it in that branch's worktree (created if needed, or the one you already made), which gets the repo's `.brindle` config |
 | `brindle handover --to BRANCH\|PATH [-n NOTE]` | hand the session to a new supervisor there: goal and milestones, workers, queued tasks and your note move across; the old one is paused |
 | `brindle autopilot [on\|off\|check]` | the goal's progress; turn autopilot on or off; run the checks now |
+| `brindle audit-decision FINDING [-r RATIONALE]` | record acceptance of an audit finding with rationale so subsequent audits respect it |
 | `brindle delegation [conservative\|balanced\|fast]` | how readily the supervisor delegates: fewest tokens, the default, or quickest |
 | `brindle transfer [REPO] [--from SESSION] [-b BRANCH]` | move a scratch session's work into a real repo |
 | `brindle ls [--all]` | workspaces and agents |
@@ -407,6 +409,7 @@ knowing them helps when you tell the supervisor how to work.
 | `approve_plan` | supervisor | approve a worker's plan, or send it back with feedback (`approved=false`) |
 | `complete_subagent` | supervisor | record the result of a `subagent`-profile task |
 | `set_goal` / `get_progress` / `check_milestone` | supervisor | autopilot's goal, its progress, and running the checks |
+| `record_audit_decision` | supervisor | record acceptance of an audit finding with rationale so subsequent audits respect it |
 | `need_user` | supervisor | stop autopilot and ask you a question |
 | `transfer_to_repo` | supervisor | move a scratch session's work into a repository |
 | `handover` | supervisor | hand the session to a new supervisor on another branch or worktree, with a note |
@@ -603,6 +606,21 @@ keep theirs):
 No tier prefers another provider for its own sake: all-Claude or all-Codex may
 be what works best for you, and that's for the learner to find out.
 
+Routing merges per tier in this order: built-in defaults, `~/.brindle/config.json`
+(every repo), the repo's `.brindle/config.json` (shared with the team), then
+`.brindle/config.local.json` (your override for that repo). Each tier you set
+replaces that tier's list; tiers you leave out keep the list from the layer below.
+For example, put this in `~/.brindle/config.json` to use Codex for light tasks
+in every repo, or in a repo's `.brindle/config.local.json` to do so only there:
+
+```json
+{"routing": {"light": ["developer-codex", "developer"]}}
+```
+
+Run `brindle doctor` in the repo to see the effective list and source file for
+each tier. Unknown profile names are skipped; doctor and the routing reply
+report the missing name and the file that supplied it.
+
 `developer-light` runs on Claude Haiku at low effort; `developer` on your Claude
 Code default model; `developer-codex` on Codex; `developer-heavy` on Claude Fable
 at high effort.
@@ -613,6 +631,53 @@ wins. When every candidate is out, the repo's `default_agent` runs. The reply sa
 what was picked and why, e.g. `weight medium -> developer (Codex at 93%, skipped developer-codex)`.
 An `agent_profile` you pass, or a milestone's `profile`, always wins over weight.
 
+Provisioning and routing also check explicit models against supported read-only
+catalogs, with the managed model, stored keys and the worker's filtered pane
+environment. A model absent from a complete authoritative catalog is rejected
+before creating a worker worktree or process. Partial catalogs, aliases,
+discovery errors and Codex's bundled catalogs remain unverified; being listed
+does not prove generation access, billing or quota. Catalog discovery is bounded
+to five seconds for standalone checks; foreground routing/provisioning limits
+discovery to one second, leaving room in the three-second launch budget for
+provisioning and bounded helper cleanup. A timeout remains unverified and
+launch proceeds with the real-task health follow-up. Catalogs are cached
+briefly by environment and local account/config
+revision where available. Routing and provisioning reuse equivalent catalog
+context across worktrees, excluding launch bookkeeping while retaining project
+settings, credentials and account selectors. CLI catalogs remain advisory;
+unobservable external/keychain login changes may remain cached for 30 seconds.
+Custom CLI binaries retain separate cache entries per working directory.
+Claude, Bedrock, Vertex and Foundry have no catalog
+probe here; no Claude CLI or synthetic generation request is used for these checks.
+
+The real first worker task is sent once. A detached helper inspects its current
+pane five seconds after delivery, so readiness delays do not use up that window.
+Fresh interactive Antigravity chats without a task still receive their profile,
+tool instructions and any autopilot context once after readiness; worker
+instructions accompany the actual task in the same delivery.
+For argv tasks, the timer starts at prompt submission or observed CLI readiness,
+after trust/startup handling; readiness timeout does not establish delivery or
+release queued work. Paused workers, replaced launches and reassigned panes are
+excluded from the observation.
+Explicit fresh authentication, access, model and capacity errors, or an early
+exit, produce a safe supervisor message with a next step. A live process with
+no clear result is recorded as pending for diagnostics, not verified model
+access; it does not send a supervisor notification. Refusals use
+the existing one-hour cooldown, scoped to the effective model/environment and
+local login revision. Changing the account, model or credentials invalidates
+that refusal; CLI/keychain account changes without an observable local revision
+may require waiting for the cooldown or clearing `model_refusals.json`.
+This is a single observation, not an entitlement test: unfamiliar error layouts,
+later failures and slow requests can remain pending. It does not scan
+historical transcripts, and excludes task text, previous pane lines and older
+marked replies, fenced examples and ordinary assistant/tool explanations. A
+Codex follow-up retains the complete submitted argv prompt (including profile
+instructions) and distinguishes assistant/tool responses from the idle composer.
+Quoted prompts and error-looking markers inside assistant/tool output remain
+ambiguous and pending; markers from another provider do not establish failure.
+A separate detached check covers headless and argv startup exits before task
+delivery. Existing readiness and watch/cull handling continues afterward.
+
 **Hosted learning (brindle Pro).** With a plan that includes it, brindle learns
 which of your `learning_candidates` profiles suits which kind of task, and picks
 one when `assign` gets no profile and no milestone names one (the reply says
@@ -711,6 +776,38 @@ Codex patches are checked file by file: allowed only if every file is. Codex
 doesn't say which tool run followed which prompt, so brindle doesn't learn from
 Codex approvals. To undo, delete that entry (or untrust it in Codex's `/hooks`).
 
+Codex also uses the profile's `allowed_tools` shell entries: `Bash(just lint)`
+allows that exact command, and `Bash(task test:*)` allows it with arguments.
+The same simple-command restriction applies, and default, user, repo and
+profile denies still win. Other `allowed_tools` entries aren't translated.
+An unrecognized patch header prevents automatic approval without discarding
+denies for files brindle can identify. Session/status bookkeeping failures
+don't discard the hook's decision; failures to evaluate the policy leave
+Codex's normal approval flow in place.
+
+Scope and platform limits: this is an **approval-request hook**, not a gate
+on every tool call. Codex commands already permitted by its sandbox or own
+rules never reach it, so brindle cannot enforce denies on those calls. It
+doesn't change Codex's sandbox or approval mode, and cannot make a `never`
+approval mode interactive. Disabled hooks, managed-only hook policies, older
+Codex versions without `PermissionRequest`, and nonlocal execution can prevent
+the hook from running. Keep Codex's own restrictions for tools that must always
+be blocked. See the [OpenAI hook protocol](https://learn.chatgpt.com/docs/hooks).
+
+The integration targets local macOS/Linux Codex CLI processes (POSIX shell
+quoting); native Windows hook commands aren't supported. The local app-server
+protocol was checked on macOS with Codex CLI **0.162.1**: newline-delimited
+`initialize`, `initialized`, and `hooks/list` returned the session-flags key
+above, `eventName: "permissionRequest"`, `source: "sessionFlags"`,
+`currentHash`, `enabled: true`, and `trustStatus: "trusted"` for the installed
+brindle hook. This read-only probe made no model calls or trust edits; hook
+dispatch/allow/deny behavior is covered by the permission tests. Linux runtime
+and native Windows behavior were not exercised by that probe.
+`codex features list` also reported `hooks stable true` without a user
+`features.hooks` setting, both on 0.162.1 and the bundled 0.158.0-alpha.2.1.
+A session override of `features.hooks=false` reported false. No feature-enable
+flag is needed on these versions, and brindle leaves explicit disablement alone.
+
 **Antigravity.** agy's hook can deny but its "allow" is ignored (an agy bug),
 and it has no "no opinion" answer. So the hook denies what the policy denies,
 answers "allow" for a file inside the workspace (which agy reads and writes
@@ -1343,6 +1440,22 @@ A profile chooses between the two with `auth`:
 
 Your org's `deny_personal_keys` (Enterprise) still applies on top of `auth`.
 
+#### Running unattended on API keys
+
+When running long, unattended autopilot sessions with API keys:
+
+- **Quota, token and cost measurements per provider**:
+  - Autopilot's automatic usage pause (`usage_limit: 90`) relies on the percentage numbers emitted by Claude Code's status line under subscription plans. Under API-key billing (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`), the CLIs report no subscription percentage, so subscription usage pause thresholds do not trigger; manage spend via provider account budget limits or brindle budget policies.
+  - Token and cost tracking: Token counts and cost estimates are captured from Claude and Codex transcripts. Antigravity (`agy`) currently has **no token/cost measurements**, so budget policies and cost tracking cannot monitor Antigravity spend; enforce usage caps directly in Google AI Studio or your Google Cloud project billing settings.
+- **Runtime auth failure handling and provider differences**:
+  - **Claude and Antigravity**: Runtime authentication failures (such as 401/403, revoked API keys, or credit/billing errors) are intercepted via StopFailure and exit hooks. Brindle marks the worker as failed, alerts the supervisor, invalidates cached sign-in checks, and pauses autopilot with a `Credentials need attention` notice rather than cycling idle nudges.
+  - **Codex (unsupported runtime auth detection)**: Codex CLI turn completion (`agent-turn-complete`) does not classify auth errors at runtime. If an OpenAI API key expires or is rejected, Codex workers will not automatically transition to `failed` or trigger an autopilot credential pause. When running Codex workers unattended, monitor their progress via `brindle watch` or check tmux panes; if an auth failure occurs, manually restart or rotate keys.
+- **Supervisor credential refresh and key rotation**:
+  - **Recovering failed/blocked workers**: When an agent fails on an expired key or autopilot pauses with a credential error, export the fresh key (or update `brindle keys set`), then run `brindle continue`. This unpauses the session and relaunches paused/failed agents with the new credentials. The replacement credentials are automatically synced to the session credential store, dynamically refreshed by the supervisor's launcher on all subsequent worker delegations (`assign`/`handoff`).
+  - **Proactive rotation in live sessions**: Exporting a new key while an active session is healthy does not restart running workers or the supervisor (running `brindle continue` on an active healthy session simply reattaches to tmux without restarting workers). To proactively rotate credentials for the entire session and all running workers: run `brindle stop` -> update credentials in your environment or via `brindle keys set` -> run `brindle continue`.
+  - **Precedence**: Newly stored keys (`brindle keys set`) or session credentials updated during recovery take effect dynamically for all new panes, overriding stale launcher environments. For profile-level overrides, an explicit profile key (`env.NAME`) takes precedence over default provider credentials.
+- **Antigravity permissions prerequisite**: Antigravity (`agy`) does not support approving shell commands solely via external hooks. With `GEMINI_API_KEY`, unattended agy workers will still stall on approval prompts unless permissions are pre-populated in `settings.json` (see Permissions) or run with `agy_approvals: "brindle"` under `permission_policy: "on"` (`--dangerously-skip-permissions`).
+
 ### Cheap workers
 
 By default a Claude Code worker loads everything your own `claude` does: your

{brindle-0.3.2 → brindle-0.3.4}/README.md

@@ -59,7 +59,7 @@ uv tool install --editable ~/Projects/brindle   # or from a local checkout
 brindle drives Claude Code, so you need that too (`npm install -g @anthropic-ai/claude-code`).
 
 `brindle --version` prints the installed version; the tmux status bar of every brindle
-session shows it too (`brindle 0.3.2`). A session started before an upgrade keeps
+session shows it too (`brindle 0.3.4`). A session started before an upgrade keeps
 running the old code, and shows the old number, until you restart it.
 
 ## Quick start
@@ -88,11 +88,11 @@ a writable home) and, in a repo, what's set up for it, and says what to do about
 anything missing. Bare `brindle` runs the essential ones (tmux, the chat's CLI)
 before it launches anything.
 
-That's it. `brindle` opens a supervisor chat (Claude Code) in your repo, with a
-narrow sidebar on the left showing every agent: who's working, who's idle, and
-who's waiting for your approval. Tell the supervisor what you want. It splits the
-work between workers, each on its own branch, then reviews and merges their
-branches. It starts in under a second.
+That's it. Bare `brindle` opens a fresh interactive developer chat (Claude Code)
+in your repo (with autopilot off), with a narrow sidebar on the left showing every
+agent: who's working, who's idle, and who's waiting for your approval. To launch an
+autopilot supervisor that splits work between parallel workers, reviews, and merges
+their branches toward verified milestones, run `brindle supervisor`. It starts in under a second.
 
 **The sidebar follows you.** There's one sidebar pane per session root, not
 one per window: switch to any other brindle window or session (⏎ in the
@@ -212,7 +212,7 @@ for mechanical edits and a Codex reviewer for a second model's opinion.
 
 ## Autopilot
 
-`brindle` starts the supervisor with autopilot on. Tell it what we're building,
+`brindle supervisor` starts the supervisor with autopilot on (or `brindle start -a supervisor`). Tell it what we're building,
 or put the goal in `.brindle/goals.md`, and it works like a project manager:
 
 1. **Goal and milestones.** The goal is split into milestones, and each one has
@@ -307,7 +307,8 @@ your own status line prints, so what you see doesn't change.
 
 | | |
 |---|---|
-| `brindle` | a fresh supervisor chat here, dashboard alongside |
+| `brindle` | a fresh developer chat here (autopilot off), dashboard alongside |
+| `brindle supervisor` | start an explicit autopilot supervisor chat to coordinate parallel workers and milestones |
 | `brindle init` | detect setup and test commands, write `.brindle/config.json`, check tools |
 | `brindle demo [--local]` | watch brindle finish a tiny practice repo: parallel workers, reviews, gated merges |
 | `brindle new BRANCH [-b BASE] [-a PROFILE] [-p PROMPT]` | worktree + branch + agent |
@@ -316,6 +317,7 @@ your own status line prints, so what you see doesn't change.
 | `brindle start [-a PROFILE] [-p PROMPT] [--no-watch] [--no-autopilot] [-b BRANCH] [-w PATH]` | the same, with options; `-b`/`-w` run it in that branch's worktree (created if needed, or the one you already made), which gets the repo's `.brindle` config |
 | `brindle handover --to BRANCH\|PATH [-n NOTE]` | hand the session to a new supervisor there: goal and milestones, workers, queued tasks and your note move across; the old one is paused |
 | `brindle autopilot [on\|off\|check]` | the goal's progress; turn autopilot on or off; run the checks now |
+| `brindle audit-decision FINDING [-r RATIONALE]` | record acceptance of an audit finding with rationale so subsequent audits respect it |
 | `brindle delegation [conservative\|balanced\|fast]` | how readily the supervisor delegates: fewest tokens, the default, or quickest |
 | `brindle transfer [REPO] [--from SESSION] [-b BRANCH]` | move a scratch session's work into a real repo |
 | `brindle ls [--all]` | workspaces and agents |
@@ -377,6 +379,7 @@ knowing them helps when you tell the supervisor how to work.
 | `approve_plan` | supervisor | approve a worker's plan, or send it back with feedback (`approved=false`) |
 | `complete_subagent` | supervisor | record the result of a `subagent`-profile task |
 | `set_goal` / `get_progress` / `check_milestone` | supervisor | autopilot's goal, its progress, and running the checks |
+| `record_audit_decision` | supervisor | record acceptance of an audit finding with rationale so subsequent audits respect it |
 | `need_user` | supervisor | stop autopilot and ask you a question |
 | `transfer_to_repo` | supervisor | move a scratch session's work into a repository |
 | `handover` | supervisor | hand the session to a new supervisor on another branch or worktree, with a note |
@@ -573,6 +576,21 @@ keep theirs):
 No tier prefers another provider for its own sake: all-Claude or all-Codex may
 be what works best for you, and that's for the learner to find out.
 
+Routing merges per tier in this order: built-in defaults, `~/.brindle/config.json`
+(every repo), the repo's `.brindle/config.json` (shared with the team), then
+`.brindle/config.local.json` (your override for that repo). Each tier you set
+replaces that tier's list; tiers you leave out keep the list from the layer below.
+For example, put this in `~/.brindle/config.json` to use Codex for light tasks
+in every repo, or in a repo's `.brindle/config.local.json` to do so only there:
+
+```json
+{"routing": {"light": ["developer-codex", "developer"]}}
+```
+
+Run `brindle doctor` in the repo to see the effective list and source file for
+each tier. Unknown profile names are skipped; doctor and the routing reply
+report the missing name and the file that supplied it.
+
 `developer-light` runs on Claude Haiku at low effort; `developer` on your Claude
 Code default model; `developer-codex` on Codex; `developer-heavy` on Claude Fable
 at high effort.
@@ -583,6 +601,53 @@ wins. When every candidate is out, the repo's `default_agent` runs. The reply sa
 what was picked and why, e.g. `weight medium -> developer (Codex at 93%, skipped developer-codex)`.
 An `agent_profile` you pass, or a milestone's `profile`, always wins over weight.
 
+Provisioning and routing also check explicit models against supported read-only
+catalogs, with the managed model, stored keys and the worker's filtered pane
+environment. A model absent from a complete authoritative catalog is rejected
+before creating a worker worktree or process. Partial catalogs, aliases,
+discovery errors and Codex's bundled catalogs remain unverified; being listed
+does not prove generation access, billing or quota. Catalog discovery is bounded
+to five seconds for standalone checks; foreground routing/provisioning limits
+discovery to one second, leaving room in the three-second launch budget for
+provisioning and bounded helper cleanup. A timeout remains unverified and
+launch proceeds with the real-task health follow-up. Catalogs are cached
+briefly by environment and local account/config
+revision where available. Routing and provisioning reuse equivalent catalog
+context across worktrees, excluding launch bookkeeping while retaining project
+settings, credentials and account selectors. CLI catalogs remain advisory;
+unobservable external/keychain login changes may remain cached for 30 seconds.
+Custom CLI binaries retain separate cache entries per working directory.
+Claude, Bedrock, Vertex and Foundry have no catalog
+probe here; no Claude CLI or synthetic generation request is used for these checks.
+
+The real first worker task is sent once. A detached helper inspects its current
+pane five seconds after delivery, so readiness delays do not use up that window.
+Fresh interactive Antigravity chats without a task still receive their profile,
+tool instructions and any autopilot context once after readiness; worker
+instructions accompany the actual task in the same delivery.
+For argv tasks, the timer starts at prompt submission or observed CLI readiness,
+after trust/startup handling; readiness timeout does not establish delivery or
+release queued work. Paused workers, replaced launches and reassigned panes are
+excluded from the observation.
+Explicit fresh authentication, access, model and capacity errors, or an early
+exit, produce a safe supervisor message with a next step. A live process with
+no clear result is recorded as pending for diagnostics, not verified model
+access; it does not send a supervisor notification. Refusals use
+the existing one-hour cooldown, scoped to the effective model/environment and
+local login revision. Changing the account, model or credentials invalidates
+that refusal; CLI/keychain account changes without an observable local revision
+may require waiting for the cooldown or clearing `model_refusals.json`.
+This is a single observation, not an entitlement test: unfamiliar error layouts,
+later failures and slow requests can remain pending. It does not scan
+historical transcripts, and excludes task text, previous pane lines and older
+marked replies, fenced examples and ordinary assistant/tool explanations. A
+Codex follow-up retains the complete submitted argv prompt (including profile
+instructions) and distinguishes assistant/tool responses from the idle composer.
+Quoted prompts and error-looking markers inside assistant/tool output remain
+ambiguous and pending; markers from another provider do not establish failure.
+A separate detached check covers headless and argv startup exits before task
+delivery. Existing readiness and watch/cull handling continues afterward.
+
 **Hosted learning (brindle Pro).** With a plan that includes it, brindle learns
 which of your `learning_candidates` profiles suits which kind of task, and picks
 one when `assign` gets no profile and no milestone names one (the reply says
@@ -681,6 +746,38 @@ Codex patches are checked file by file: allowed only if every file is. Codex
 doesn't say which tool run followed which prompt, so brindle doesn't learn from
 Codex approvals. To undo, delete that entry (or untrust it in Codex's `/hooks`).
 
+Codex also uses the profile's `allowed_tools` shell entries: `Bash(just lint)`
+allows that exact command, and `Bash(task test:*)` allows it with arguments.
+The same simple-command restriction applies, and default, user, repo and
+profile denies still win. Other `allowed_tools` entries aren't translated.
+An unrecognized patch header prevents automatic approval without discarding
+denies for files brindle can identify. Session/status bookkeeping failures
+don't discard the hook's decision; failures to evaluate the policy leave
+Codex's normal approval flow in place.
+
+Scope and platform limits: this is an **approval-request hook**, not a gate
+on every tool call. Codex commands already permitted by its sandbox or own
+rules never reach it, so brindle cannot enforce denies on those calls. It
+doesn't change Codex's sandbox or approval mode, and cannot make a `never`
+approval mode interactive. Disabled hooks, managed-only hook policies, older
+Codex versions without `PermissionRequest`, and nonlocal execution can prevent
+the hook from running. Keep Codex's own restrictions for tools that must always
+be blocked. See the [OpenAI hook protocol](https://learn.chatgpt.com/docs/hooks).
+
+The integration targets local macOS/Linux Codex CLI processes (POSIX shell
+quoting); native Windows hook commands aren't supported. The local app-server
+protocol was checked on macOS with Codex CLI **0.162.1**: newline-delimited
+`initialize`, `initialized`, and `hooks/list` returned the session-flags key
+above, `eventName: "permissionRequest"`, `source: "sessionFlags"`,
+`currentHash`, `enabled: true`, and `trustStatus: "trusted"` for the installed
+brindle hook. This read-only probe made no model calls or trust edits; hook
+dispatch/allow/deny behavior is covered by the permission tests. Linux runtime
+and native Windows behavior were not exercised by that probe.
+`codex features list` also reported `hooks stable true` without a user
+`features.hooks` setting, both on 0.162.1 and the bundled 0.158.0-alpha.2.1.
+A session override of `features.hooks=false` reported false. No feature-enable
+flag is needed on these versions, and brindle leaves explicit disablement alone.
+
 **Antigravity.** agy's hook can deny but its "allow" is ignored (an agy bug),
 and it has no "no opinion" answer. So the hook denies what the policy denies,
 answers "allow" for a file inside the workspace (which agy reads and writes
@@ -1313,6 +1410,22 @@ A profile chooses between the two with `auth`:
 
 Your org's `deny_personal_keys` (Enterprise) still applies on top of `auth`.
 
+#### Running unattended on API keys
+
+When running long, unattended autopilot sessions with API keys:
+
+- **Quota, token and cost measurements per provider**:
+  - Autopilot's automatic usage pause (`usage_limit: 90`) relies on the percentage numbers emitted by Claude Code's status line under subscription plans. Under API-key billing (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`), the CLIs report no subscription percentage, so subscription usage pause thresholds do not trigger; manage spend via provider account budget limits or brindle budget policies.
+  - Token and cost tracking: Token counts and cost estimates are captured from Claude and Codex transcripts. Antigravity (`agy`) currently has **no token/cost measurements**, so budget policies and cost tracking cannot monitor Antigravity spend; enforce usage caps directly in Google AI Studio or your Google Cloud project billing settings.
+- **Runtime auth failure handling and provider differences**:
+  - **Claude and Antigravity**: Runtime authentication failures (such as 401/403, revoked API keys, or credit/billing errors) are intercepted via StopFailure and exit hooks. Brindle marks the worker as failed, alerts the supervisor, invalidates cached sign-in checks, and pauses autopilot with a `Credentials need attention` notice rather than cycling idle nudges.
+  - **Codex (unsupported runtime auth detection)**: Codex CLI turn completion (`agent-turn-complete`) does not classify auth errors at runtime. If an OpenAI API key expires or is rejected, Codex workers will not automatically transition to `failed` or trigger an autopilot credential pause. When running Codex workers unattended, monitor their progress via `brindle watch` or check tmux panes; if an auth failure occurs, manually restart or rotate keys.
+- **Supervisor credential refresh and key rotation**:
+  - **Recovering failed/blocked workers**: When an agent fails on an expired key or autopilot pauses with a credential error, export the fresh key (or update `brindle keys set`), then run `brindle continue`. This unpauses the session and relaunches paused/failed agents with the new credentials. The replacement credentials are automatically synced to the session credential store, dynamically refreshed by the supervisor's launcher on all subsequent worker delegations (`assign`/`handoff`).
+  - **Proactive rotation in live sessions**: Exporting a new key while an active session is healthy does not restart running workers or the supervisor (running `brindle continue` on an active healthy session simply reattaches to tmux without restarting workers). To proactively rotate credentials for the entire session and all running workers: run `brindle stop` -> update credentials in your environment or via `brindle keys set` -> run `brindle continue`.
+  - **Precedence**: Newly stored keys (`brindle keys set`) or session credentials updated during recovery take effect dynamically for all new panes, overriding stale launcher environments. For profile-level overrides, an explicit profile key (`env.NAME`) takes precedence over default provider credentials.
+- **Antigravity permissions prerequisite**: Antigravity (`agy`) does not support approving shell commands solely via external hooks. With `GEMINI_API_KEY`, unattended agy workers will still stall on approval prompts unless permissions are pre-populated in `settings.json` (see Permissions) or run with `agy_approvals: "brindle"` under `permission_policy: "on"` (`--dangerously-skip-permissions`).
+
 ### Cheap workers
 
 By default a Claude Code worker loads everything your own `claude` does: your

{brindle-0.3.2 → brindle-0.3.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "brindle"
-version = "0.3.2"
+version = "0.3.4"
 description = "Run coding agents in parallel, each on its own git branch, with a supervisor that delegates, reviews, and merges"
 readme = "README.md"
 requires-python = ">=3.11"