brindle 0.4.0__tar.gz → 0.4.2__tar.gz

{brindle-0.4.0 → brindle-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: brindle
-Version: 0.4.0
+Version: 0.4.2
 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
@@ -42,13 +42,20 @@ that exact commit and your checks pass. A goal is done only when its check comma
 exit 0.
 
 ```sh
-curl -fsSL pawdelta.com/brindle/install | sh
+curl -fsSL pawdelta.com/brindle/install | sh   # installs uv and tmux if missing, then brindle
+# or, if you already have uv and tmux:
+uv tool install brindle
+
 brindle demo        # watch it finish a practice repo in a few minutes
 ```
 
-![brindle demo: a supervisor splits a goal between two workers, each branch is reviewed and merged, and both milestones turn green once their checks pass](https://pawdelta.com/brindle/brindle-demo.gif?v=0.0.2)
+brindle is free to use, including at work, under the [brindle License 1.0](LICENSE): you
+may install and run it, but not modify or redistribute it or use it to build a competing
+service ([details](#license)).
 
-*`brindle demo`, recorded on brindle 0.0.2 (sped up 4×): two workers in parallel, each branch reviewed and merged, both milestones verified by their check commands.*
+![brindle demo: a supervisor splits a goal between two workers, each branch is reviewed and merged, and both milestones turn green once their checks pass](https://raw.githubusercontent.com/PawDelta/brindle/main/assets/brindle-demo.gif)
+
+*`brindle demo`, recorded on brindle 0.4.1 (sped up about 2.7×, 20 seconds): two workers in parallel, each branch reviewed and merged, both milestones verified by their check commands.*
 
 - **Done means a command passed.** A goal is split into milestones, each with a
   check command that brindle runs itself. A milestone is verified when its check exits
@@ -94,7 +101,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.4.0`). A session started before an upgrade keeps
+session shows it too (`brindle 0.4.2`). A session started before an upgrade keeps
 running the old code, and shows the old number, until you restart it.
 
 ## Quick start
@@ -115,7 +122,8 @@ as `brindle doctor`. Commit the config so your team gets it too.
 New to brindle? `brindle demo` runs it on a tiny practice repo (under `~/.brindle/demo/`)
 with two failing test files and a two-milestone goal: in a few minutes you watch two
 workers fix them in parallel, each branch get reviewed and merged, and both milestones
-turn green only once their test command passes. `brindle demo --local` keeps the workers
+turn green only once their test command passes (the demo repo's config sets
+`"delegation": "fast"`, so the supervisor always splits the work). `brindle demo --local` keeps the workers
 and reviewers on a local model (Ollama).
 
 `brindle doctor` checks that everything brindle needs is there (tmux, the agent CLIs,
@@ -347,6 +355,11 @@ or once its goal was replaced from the chat. From a linked worktree, it writes
 the `goals.md` it loaded (the main checkout's), never another session's. A
 write that fails never fails the check.
 
+A new session takes a hand-written `goals.md` over by moving it to its own
+`.brindle/goals/<session id>.md` (git-ignored). If `goals.md` was committed,
+its deletion is left for you to commit or restore; brindle doesn't count it as
+an uncommitted change, so it never blocks a merge or a milestone's check.
+
 `brindle autopilot` shows progress, `brindle autopilot check` runs the checks
 now, and `brindle autopilot off` (or `on`) hands the wheel back (or takes it
 again). `brindle --no-autopilot`, or `"autopilot": false` in the repo config,
@@ -399,6 +412,7 @@ your own status line prints, so what you see doesn't change.
 | `brindle login` | the same as `brindle account login`; when your org's policy has an `agent_setup` block it also signs you in to the Claude and Codex route the company chose (AWS SSO profile, `gcloud`, `az`, `claude auth login`, `codex login`), stores the Claude Code environment for brindle's panes in `~/.brindle/config.json`, and checks the pinned models. `brindle doctor --fix` does the same |
 | `brindle audit verify\|export\|pubkey\|ship\|prune` | the local tamper-evident audit log, and shipping it to your SIEM (brindle Enterprise; see "Audit log" below) |
 | `brindle watch [--all] [--once]` | the dashboard on its own (the same view as the sidebar): enter attaches, `p` peeks, `x` closes |
+| `brindle web [--port N] [--no-open]` | this session in your browser (see "Web UI") |
 | `brindle sidebar` | bring this session's sidebar into the tmux session you're in (also `Ctrl-b S` in a window without one); restarts it if it was closed |
 | `brindle attach / cd / open [WS]` | tmux session (at the agent waiting on you, else the busiest or newest) / path / editor |
 | `brindle status / diff [--stat] [WS]` | compared with the base branch (committed + uncommitted) |
@@ -421,6 +435,21 @@ your own status line prints, so what you see doesn't change.
 
 With no `WS` argument, commands act on the workspace you're in.
 
+### Web UI
+
+`brindle web` serves the current session to your browser: workspaces, agents
+and their status, and the goal's milestones with each one's last check. Run
+it from a terminal in the session's tmux session to show that session's
+goal; elsewhere it shows the newest autopilot session
+in the repo. The page refreshes itself every couple of seconds.
+
+It listens on `127.0.0.1` only, on a free port (or `--port N`), and prints a
+link with a random token, `http://127.0.0.1:PORT/?token=...`, which it also
+opens. The token is new each run and is needed on every request (the first
+one sets a cookie, so the page drops it from the address bar). Requests
+naming another host, or changing anything from another site's page, are
+refused. Ctrl-C stops it.
+
 ### Agent tools
 
 Agents launched by brindle get these MCP tools. You don't call them yourself, but
@@ -651,6 +680,7 @@ Autopilot, merge gates and cleanup:
 | `usage_limit` | `90` | autopilot stops pushing on at this % of your Claude usage limit |
 | `limit_cooldown_minutes` | `300` for Antigravity | how long a provider that hit its limit counts as unavailable |
 | `graphify` | if the graph is there | point agents at the repo's [graphify](https://github.com/safishamsi/graphify) code map (`false` turns it off) |
+| `graphify_auto_refresh` | `true` | automatically rebuild untracked code maps; `false` disables rebuilds while keeping queries available |
 | `stale_after` | `30` | minutes before a worker that reported and sat idle is closed, or `brindle prune` closes a stale paused/exited agent whose workspace is merged or gone (`0`: never) |
 | `pipeline` | `true` | brindle reviews and merges reported branches itself; the supervisor gets one message per branch |
 | `review_rounds` | `2` | fix-and-re-review rounds the pipeline runs before handing findings to the supervisor |
@@ -658,7 +688,7 @@ Autopilot, merge gates and cleanup:
 | `merge_into` | none | branch that worker branches are cut from and merge into, whatever branch the supervisor is on |
 | `auto_merge_default_branch` | `false` | let the pipeline merge into the repo's default branch (origin HEAD, else `main`/`master`) on its own; by default it sends a "needs you" message instead, and you run `merge_workspace` yourself (manual merges are never gated) |
 | `permission_policy` | `"off"` | `"on"`: brindle answers Claude Code workers' permission prompts from its rules (see "Permission policy" below); off, the prompts behave as they always did |
-| `agy_approvals` | `"prompt"` | `"brindle"`: with the policy on, Antigravity workers run without approval prompts and brindle's hook allows or denies every call (see "Antigravity" under "Permission policy") |
+| `agy_approvals` | unset | `"brindle"`: Antigravity agents run without approval prompts and brindle's hook allows or denies every call, applying the profile's `allowed_tools` (see "Antigravity" under "Permission policy"); `"prompt"`: agy asks as usual. Unset, workers get `"brindle"` and interactive agy sessions `"prompt"` |
 | `rules` | `[]` | standing rules for the supervisor, e.g. `["Fix review findings without asking", "Validate options before offering them"]`; added to every supervisor's brief. Rules in `~/.brindle/config.json`, the repo's config and `config.local.json` are all kept, so a team's rules and your own add up |
 | `plan_first` | `false` | workers propose a plan (`submit_plan`) and wait for `approve_plan` before editing |
 | `overlap` | unset | a task whose `files` overlap a running task's: `"block"` refuses it, `"warn"` starts it with a warning, `"queue"` queues it until that task merges. Unset, it is refused within a session and queued behind another session's task (both sessions' supervisors are told; the other session's work is never cancelled), and the queued task starts from that task's merge commit |
@@ -931,7 +961,8 @@ 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,
+and it has no "no opinion" answer. So, where agy prompts (an interactive agy
+session, or any agy agent under `"agy_approvals": "prompt"`), the hook denies what the policy denies,
 answers "allow" for a file inside the workspace (which agy reads and writes
 without asking anyway) and "ask" for everything else, and brindle copies the
 rules agy can express exactly into your `~/.gemini/antigravity-cli/settings.json`
@@ -946,8 +977,10 @@ does it by hand. To undo, turn `permission_policy` off and run `sync-agy`: brind
 removes exactly its own entries. brindle doesn't learn from agy approvals (its
 hook runs for every tool call, so a tool running doesn't mean you approved it).
 
-With `"agy_approvals": "brindle"` (and the policy on), brindle's hook is the
-only gate instead: agy workers start with `--dangerously-skip-permissions`,
+For workers (any agy agent but an interactive one) when `agy_approvals` is
+unset, and for every agy agent under `"agy_approvals": "brindle"`, whether or
+not the policy is on, brindle's hook is the
+only gate instead: they start with `--dangerously-skip-permissions`,
 under which agy still honors a hook's deny, and the hook runs on every tool,
 subagents' calls included. It allows what a rule allows (a repo's checks
 included), the shell commands in the profile's `allowed_tools` (what a Claude
@@ -955,11 +988,20 @@ Code worker on it runs without asking), files inside the workspace given as one
 absolute path (writes under `.agents/`, `.git/` and
 `.brindle/` only by a rule, since those hold the hook, git's hooks and the
 repo's checks), brindle's own tools and agy's tools that act only on the
-conversation, and denies everything else, telling the agent to
-ask its supervisor; you allow it with `brindle permissions allow`. Any failure
+conversation, and denies everything else. A call no rule covers (not one a
+rule denies) is what a Claude Code worker would wait on you for: brindle
+records it as the worker's pending request and tells its supervisor, once per
+request in a turn, with the `brindle permissions allow ...` commands that allow
+it (one per part of a compound command that no rule covers yet); once you run
+them, the worker's retry goes through. A command no rule can allow as written
+(`$(...)`, a redirection that writes, a heredoc) comes with that instead, so
+the worker can split it into simple commands. A `dontAsk` profile (a
+reviewer) and an agent with no supervisor are only told to ask. Any failure
 in the hook is a deny, and a tool brindle doesn't know is denied. Nobody can
-approve a prompt in the agent's pane in this mode. The default, `"prompt"`,
-leaves agy asking as described above.
+approve a prompt in the agent's pane in this mode, so a worker never waits at
+one nobody is watching. `"prompt"` leaves agy asking as described above (and
+`assign`/`handoff` name the profile's `allowed_tools` agy's own settings don't
+already allow).
 
 ## brindle Pro and Team
 
@@ -1003,7 +1045,7 @@ brindle account login      # opens your browser to sign in (--device: enter a co
 brindle account status     # your plan, features, hosted learning on or off, when the entitlement expires
 brindle account savings    # what hosted learning's picks gained in this repo, this month and last: estimates, from this machine's records only
 brindle account upgrade    # opens the checkout for brindle Pro (and prints its URL)
-brindle account upgrade --enterprise [--trial] --seats N --org ORG   # brindle Enterprise for a team org; --trial: free trial, at most 10 seats
+brindle account upgrade --enterprise      # brindle Enterprise is set up by contact (prints support@pawdelta.com); not a checkout
 brindle account portal     # opens the billing portal (invoices, payment method, cancellation); --org ORG for a team org
 brindle account seats N    # set a Team or Enterprise org's seat count (billing admin); --org ORG; Stripe prorates the change
 brindle account org list   # the orgs you belong to; `org use <id>` switches, `org policy` shows the current one
@@ -1454,7 +1496,11 @@ knowledge graph (`graphify-out/graph.json`, built with `/graphify`) and `graphif
 installed, brindle tells the supervisor and every worker to find code with
 `graphify query` before grepping or reading whole files. Those commands are
 pre-approved, and brindle refreshes the graph's code (`graphify update`, no LLM) in
-the background after each merge.
+the background after each merge. Automatic rebuilds skip checkouts with any
+git-tracked files under `graphify-out/`, preserving richer semantic graphs and
+their generated reports. Update tracked graphs explicitly with graphify.
+Set `"graphify_auto_refresh": false` in `.brindle/config.json` to also disable
+automatic rebuilds and session seeding for untracked graphs while keeping queries.
 
 When `pool_size` is greater than `0`, a claimed worktree keeps the path and
 port block it was built with -- it's never moved, and its port block is fixed
@@ -1536,6 +1582,7 @@ change files under a directory without prompts.
 | `claude` (Claude Code) | yes (the default) | yes |
 | `codex` | yes | yes |
 | `antigravity` (`agy`) | yes | yes |
+| `opencode` (OpenCode) | yes | yes (`developer-opencode`, `reviewer-opencode`) |
 | `native` (local models) | no: its loop has only the worker tools (report, message, diff), not `assign` or `handoff` | yes |
 | `subagent` | no: it runs inside a supervisor's own Agent tool | yes, through `assign`/`handoff` |
 | `shell` | only as a stand-in, for testing brindle itself | a plain shell, for dev servers and testing brindle |
@@ -1561,6 +1608,7 @@ it's signed in without a plan that includes it, is reported to its supervisor.
 | `claude` | yes: `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, `CLAUDE_CODE_OAUTH_TOKEN`, or Bedrock/Vertex/Foundry (`CLAUDE_CODE_USE_BEDROCK`, `CLAUDE_CODE_USE_VERTEX`, `CLAUDE_CODE_USE_FOUNDRY`) |
 | `codex` | yes: `OPENAI_API_KEY`, `CODEX_API_KEY`. With Codex signed in with ChatGPT (checked on Codex CLI 0.162.0): interactive `codex`, which brindle runs in agent panes, ignores both keys and uses the ChatGPT plan, and only `codex login --with-api-key` switches it to a key; headless `codex exec` (Brindle-CI) bills `CODEX_API_KEY` over the login and ignores `OPENAI_API_KEY`. `brindle doctor` and `brindle keys set` say so, and `auth: api_key` on an interactive Codex profile is refused under a ChatGPT login (run `codex login --with-api-key`, or use `auth: subscription`) |
 | `antigravity` | `GEMINI_API_KEY`, only with `"modelProvider": "gemini"` in `agy`'s `settings.json` (see [Google Antigravity](#google-antigravity)); otherwise `agy`'s own browser sign-in |
+| `opencode` | whatever the model's provider takes (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, ...), or `opencode auth login`; its free `opencode/...` models need neither |
 
 Workers that run unattended should use key login where the CLI supports it.
 A personal login is one interactive session with one quota shared by every
@@ -1595,7 +1643,39 @@ When running long, unattended autopilot sessions with API keys:
   - **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**: For Claude keys rotated outside brindle, set Claude Code's `apiKeyHelper` in `~/.claude/settings.json` or the project's `.claude/settings.json`. Claude Code re-runs the helper every 5 minutes (configurable with `CLAUDE_CODE_API_KEY_HELPER_TTL_MS`) and after a 401, so running workers pick up the new key. Don't also export `ANTHROPIC_API_KEY` or set a Claude key with `brindle keys set`, since an environment key takes precedence over the helper. Codex and Antigravity keys still need workers stopped, then `brindle keys set`, then `brindle continue`. 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`).
+- **Antigravity permissions prerequisite**: Antigravity (`agy`) does not support approving shell commands solely via external hooks. brindle therefore runs agy workers with `--dangerously-skip-permissions` and its own hook as the gate, applying their profile's `allowed_tools` and denying the rest (see Permissions). Under an explicit `agy_approvals: "prompt"` they instead stall on approval prompts for anything `settings.json` doesn't allow, their profile's `allowed_tools` included.
+
+#### OpenCode
+
+[OpenCode](https://opencode.ai) (`npm install -g opencode-ai`) runs in an agent
+pane like the other CLIs; `brindle doctor` says whether it's installed. Run a
+supervisor on it with `brindle -s opencode`, or workers with the built-in
+`developer-opencode` and `reviewer-opencode` profiles (or any profile with
+`provider: opencode`). Checked with OpenCode 1.19.3.
+
+brindle writes nothing into the worktree. It hands OpenCode its MCP server, a
+small plugin and the profile's prompt through `OPENCODE_CONFIG_CONTENT`, which
+OpenCode merges over your own config, so your providers, models and other MCP
+servers still apply. The plugin reports each turn's start, its end (and any
+error, such as a rate limit), and permission prompts from OpenCode's own
+events, so a worker's status never depends on reading its screen.
+
+| Profile field | OpenCode |
+|---|---|
+| `model` | `--model`. Use OpenCode's `provider/model` form (`anthropic/claude-sonnet-4-5`, `opencode/big-pickle`); a bare `claude-…`, `gpt-…` or `gemini-…` name gets its provider added. With no model, OpenCode's own default. |
+| `allowed_tools` | Each `Bash(cmd:*)` becomes an allowed `bash` pattern; any other command asks. |
+| `permission_mode` | `bypassPermissions`: everything runs. `dontAsk`: only `allowed_tools` commands run, edits and web fetches are refused. `acceptEdits`/`auto`: edits run. `plan`: OpenCode's `plan` agent. Unset: edits ask too. |
+| `add_dirs`, `worker_extra_read_dirs` | Allowed as external directories. |
+
+A `dontAsk` OpenCode worker (the built-in reviewer, for one) can't read outside
+its worktree or its `add_dirs`: with nobody to ask, anything else is refused.
+
+`effort` isn't passed (OpenCode's terminal UI has no flag for it). With
+`permission_policy` on, brindle's plugin also asks brindle before every tool
+call and stops the ones the policy denies (as for Claude Code and Codex
+workers); calls the policy allows or asks about are left to the profile's
+permissions above, so the policy can narrow what an OpenCode worker does but
+never widens it.
 
 ### Cheap workers
 
@@ -1886,6 +1966,17 @@ No hooks, no screen scraping, and messages sent to the worker arrive between
 its model calls. It works with any OpenAI-compatible chat-completions endpoint
 or Anthropic Messages endpoint.
 
+The native worker automatically starts language servers found on `PATH` when it
+first reads or changes a supported file (Python: `pyright-langserver` or `pylsp`;
+JS/TS: `typescript-language-server`; Go: `gopls`; Rust: `rust-analyzer`; C/C++:
+`clangd`; Ruby: `ruby-lsp`; Lua: `lua-language-server`). Servers use the worktree
+as their root and stop with the worker. `Diagnostics`, `Definition`, and
+`References` provide code information; diagnostics also follow successful Edit
+and Write calls. Navigation takes 1-based lines and character columns. Explicit
+LSP tools report missing servers; ordinary file tools stay silent when no server
+can run. Profiles with a narrowed read scope skip language
+servers because workspace indexing cannot enforce that boundary.
+
 ```markdown
 ---
 name: developer-local
@@ -1947,6 +2038,14 @@ Other endpoints, same fields:
 | DeepSeek | anthropic | `https://api.deepseek.com/anthropic` | paid; `api_key_env: DEEPSEEK_API_KEY` |
 | Anthropic | anthropic | `https://api.anthropic.com` | `api_key_env: ANTHROPIC_API_KEY` |
 
+Or name any [Models.dev](https://models.dev) model as `model: <provider>/<model>`
+(say `nano-gpt/deepseek/deepseek-v3`) and leave out `base_url`: brindle fills in
+`base_url`, `api`, `api_key_env` and `context_tokens` from the catalog, and
+anything you set in the profile wins. The catalog is cached in
+`~/.brindle/models-catalog.json` for a day. It is never fetched in air-gap mode
+or offline; brindle uses the cached copy, and says so if there isn't one. A profile
+with its own `base_url` is left alone, so OpenRouter-style ids still work.
+
 What to expect: a 30B-class local model does well on small, well-specified
 tasks (the kind brindle hands out: one change, the test named up front) and on
 reviews of modest diffs, and less well on long multi-step work. The native
@@ -2098,10 +2197,25 @@ you already have them, and won't change one that's committed. Each agent's first
 message is a short warm-up with its instructions, because `agy` connects MCP servers
 only once a conversation has started.
 
-**Permissions.** `agy` doesn't let hooks approve shell commands, so an Antigravity
-agent asks before running anything your own `agy` settings don't already allow, and
-the sidebar shows it as needing you. To let agents run tests and commit without asking,
-add rules to `~/.gemini/antigravity-cli/settings.json`, for example:
+**Permissions.** `agy` doesn't let hooks approve shell commands, so by default
+brindle runs Antigravity workers with `--dangerously-skip-permissions` and its
+own hook as the only gate (see "Antigravity" under "Permission policy"): a
+profile's `allowed_tools` shell entries and brindle's rules apply as they do
+for a Claude Code worker, and a call nothing allows is denied, with its
+supervisor told how you can allow it (a `brindle permissions allow` you run),
+never left at a prompt nobody is watching. A profile's `permission_mode` maps to agy's modes
+(`auto` to agy's Auto mode, `acceptEdits` to accept-edits, `plan` to plan;
+`dontAsk` runs brindle's hook as the only gate even in an interactive session).
+
+An interactive agy session, or any agy agent under `"agy_approvals": "prompt"`,
+asks before running anything your own `agy` settings don't already allow, and
+the sidebar shows it as needing you. There a profile's `allowed_tools` don't
+apply by themselves: agy reads no hook's "allow", and its only allow list,
+`~/.gemini/antigravity-cli/settings.json`, is shared by every agy session, so brindle
+doesn't add one worker's rules there (another worker, or you, would get them too).
+`assign` and `handoff` name the `allowed_tools` that settings file doesn't already
+allow. To let such agents run tests and commit without asking,
+add rules to that file yourself, for example:
 
 ```json
 { "permissions": { "allow": ["command(uv run pytest)", "command(git status)",
@@ -2117,14 +2231,20 @@ add rules to `~/.gemini/antigravity-cli/settings.json`, for example:
   and every agent's MCP server share it. Worktrees live in
   `~/.brindle/worktrees/<repo>/<branch>`, and the base branch is recorded in git
   config as `branch.<b>.brindle-base`.
-- **Messages arrive through Claude Code's own inbox.** Every Claude Code session
-  listens on a socket for messages from other sessions, and tells its hooks where
-  it is; brindle's SessionStart hook records it, and from then on messages go there
-  instead of being typed into the pane. An idle agent starts a new turn with the
-  message; a busy one gets it between tool calls. Typing into the pane is the
-  fallback when there's no socket (Codex, Antigravity, older Claude Code). A
-  `crossSessionInbound` of `hold` or `refuse` in your Claude settings would hold or
-  drop them.
+- **Messages wake a supervisor through brindle's own hook.** Your interactive
+  Claude Code chat runs a small background waiter (an `asyncRewake` hook started
+  at `SessionStart` and at every `Stop`). When a worker reports, or brindle has a
+  "new messages" notice or an autopilot nudge, the waiter hands it over and Claude
+  Code wakes the model with it: an idle chat starts a new turn, a busy one gets it
+  between steps, and the chat shows one "Stop hook feedback" line. Each message
+  is wrapped as `<brindle-msg nonce="..." from="developer agent w1">...</brindle-msg>`
+  with a fresh random nonce every hand-over, and `from` comes from who really sent
+  it, never from its text: a worker can't make its words read as brindle's or yours.
+  A session paused on an expired cloud login gets its mail once the login is back.
+  Workers and older sessions get messages through Claude Code's own inbox
+  (another-session messages; a `crossSessionInbound` of `hold` or `refuse` in your
+  Claude settings would hold or drop them). Typing into the pane is the fallback
+  when neither is there (Codex, Antigravity, older Claude Code).
 - **Agent status comes from hooks, not screen-scraping.** Guessing an agent's
   state by pattern-matching terminal output breaks whenever a CLI redesigns its
   interface. brindle launches Claude Code with `--settings` hooks