brindle 0.3.16__tar.gz → 0.3.18__tar.gz

{brindle-0.3.16 → brindle-0.3.18}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: brindle
-Version: 0.3.16
+Version: 0.3.18
 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
@@ -94,7 +94,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.16`). A session started before an upgrade keeps
+session shows it too (`brindle 0.3.18`). A session started before an upgrade keeps
 running the old code, and shows the old number, until you restart it.
 
 ## Quick start
@@ -415,7 +415,7 @@ knowing them helps when you tell the supervisor how to work.
 | `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 |
+| `need_user` | supervisor | ask you a question (a decision, a denied action, a stalled external job such as a CI run no runner picks up); only the steps that depend on it wait, the rest keeps going; `answered=true` once you've replied |
 | `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 |
 
@@ -641,6 +641,8 @@ 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.
 
+The supervisor runs on your Claude Code model. If your organisation's Claude Code managed settings pin the model (e.g. to Sonnet), that applies to the brindle supervisor too. Supervising goes best on Opus (or Fable where available), so if your org allows it, switch in the supervisor's own session with `/model`. Worker profiles set their own model and aren't affected.
+
 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
@@ -1419,7 +1421,7 @@ change files under a directory without prompts.
 
 ### Which provider can do what
 
-| Provider | Supervisor (`brindle --provider …`) | Worker / reviewer |
+| Provider | Supervisor (`brindle --supervisor …`) | Worker / reviewer |
 |---|---|---|
 | `claude` (Claude Code) | yes (the default) | yes |
 | `codex` | yes | yes |
@@ -1481,7 +1483,7 @@ When running long, unattended autopilot sessions with API keys:
   - **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`.
+  - **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`).
 
@@ -1966,7 +1968,8 @@ you to sign in. `agy` takes no other key or token from the environment; its
 Google Cloud, Workforce Identity and Application Default Credentials sign-ins are
 chosen on its sign-in screen.
 
-Then run the whole session on it with `brindle --provider antigravity`, or mix models:
+Then run the supervisor on it with `brindle --supervisor antigravity`.
+Workers keep their own profiles' providers. To mix models,
 give a profile `provider: antigravity` (for example a `gemini-reviewer` for a second
 model's review) and the supervisor can hand it tasks.
 

{brindle-0.3.16 → brindle-0.3.18}/README.md

@@ -63,7 +63,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.16`). A session started before an upgrade keeps
+session shows it too (`brindle 0.3.18`). A session started before an upgrade keeps
 running the old code, and shows the old number, until you restart it.
 
 ## Quick start
@@ -384,7 +384,7 @@ knowing them helps when you tell the supervisor how to work.
 | `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 |
+| `need_user` | supervisor | ask you a question (a decision, a denied action, a stalled external job such as a CI run no runner picks up); only the steps that depend on it wait, the rest keeps going; `answered=true` once you've replied |
 | `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 |
 
@@ -610,6 +610,8 @@ 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.
 
+The supervisor runs on your Claude Code model. If your organisation's Claude Code managed settings pin the model (e.g. to Sonnet), that applies to the brindle supervisor too. Supervising goes best on Opus (or Fable where available), so if your org allows it, switch in the supervisor's own session with `/model`. Worker profiles set their own model and aren't affected.
+
 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
@@ -1388,7 +1390,7 @@ change files under a directory without prompts.
 
 ### Which provider can do what
 
-| Provider | Supervisor (`brindle --provider …`) | Worker / reviewer |
+| Provider | Supervisor (`brindle --supervisor …`) | Worker / reviewer |
 |---|---|---|
 | `claude` (Claude Code) | yes (the default) | yes |
 | `codex` | yes | yes |
@@ -1450,7 +1452,7 @@ When running long, unattended autopilot sessions with API keys:
   - **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`.
+  - **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`).
 
@@ -1935,7 +1937,8 @@ you to sign in. `agy` takes no other key or token from the environment; its
 Google Cloud, Workforce Identity and Application Default Credentials sign-ins are
 chosen on its sign-in screen.
 
-Then run the whole session on it with `brindle --provider antigravity`, or mix models:
+Then run the supervisor on it with `brindle --supervisor antigravity`.
+Workers keep their own profiles' providers. To mix models,
 give a profile `provider: antigravity` (for example a `gemini-reviewer` for a second
 model's review) and the supervisor can hand it tasks.
 

{brindle-0.3.16 → brindle-0.3.18}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "brindle"
-version = "0.3.16"
+version = "0.3.18"
 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"

{brindle-0.3.16 → brindle-0.3.18}/src/brindle/agents.py

@@ -300,9 +300,11 @@ def decorate_worker_prompt(task: str, agent_id: str, ws: Workspace, done_when: s
         prompt += PLAN_FIRST_NOTE
     prompt += WORKER_FOOTER.format(agent_id=agent_id, branch=ws.branch,
                                    guidance=worker_guidance(ws))
-    if done_when and provider.name == "claude" and not headless:
-        # /goal is an interactive command; headless workers get the finish
-        # line above and the Stop hook's reminder to report.
+    if (done_when and provider.name == "claude" and not headless
+            and not provider.hooks_disabled(ws.path)):
+        # /goal is an interactive command that Claude Code refuses when hooks
+        # are disabled (#133), and headless workers get the finish line above
+        # and the Stop hook's reminder to report either way.
         prompt = pilot.worker_goal(prompt, done_when, ws.branch) or prompt
     return prompt
 
@@ -322,10 +324,12 @@ def spawn(
     autopilot: bool = False,
     plan_first: bool = False,
     review_sha: str | None = None,
+    claim_goals: bool = True,
 ) -> Agent:
     """Start an agent in ``ws``. Workers (handoff/assign) given a ``done_when``
     finish line run it as a Claude Code ``/goal``. With ``autopilot``, the
-    agent is a session root that drives toward a goal (see brindle.autopilot)."""
+    agent is a session root that drives toward a goal (see brindle.autopilot);
+    with ``claim_goals`` it claims a hand-written ``.brindle/goals.md``."""
     from brindle import autopilot as pilot
     from brindle import identity_lock
 
@@ -377,9 +381,9 @@ def spawn(
         db.update_agent(agent_id, plan_first=1)
         agent.plan_first = 1
     if autopilot:
-        plan = pilot.enable(db, agent_id, ws)
+        plan = pilot.enable(db, agent_id, ws, claim=claim_goals)
         if plan and not prompt:
-            prompt = agent.task = pilot.kickoff(plan)
+            prompt = agent.task = pilot.kickoff(plan, agent_id)
             db.update_agent(agent_id, task=prompt)
     if mode == "interactive":
         from brindle import codemap
@@ -1177,6 +1181,10 @@ def resume(db: DB, root_id: str, *, watch_pane: bool = True,
                   if a.status in ("paused", "failed") and (only is None or a.id in only)]
     for a in candidates:   # all or nothing: a session never half-resumes under another identity
         identity_lock.ensure(a)
+    if any(a.id == root_id for a in candidates):
+        from brindle import autopilot as pilot
+
+        pilot.reload_goals_file(db, root_id)   # edits the person made to this session's goal file
     resumed = []
     for a in candidates:
         if a.status == "failed":
@@ -1506,14 +1514,22 @@ def screen_status(db: DB, agent: Agent, samples: int = 2, gap: float = 0.7) -> s
     single cheap read, as the dashboard does, leaves it alone. Moving an
     agent to idle also delivers anything queued for it, but only when
     ``samples`` >= 2: a single-sample read must never pop a message into a
-    terminal as a side effect of just rendering the dashboard."""
+    terminal as a side effect of just rendering the dashboard.
+
+    An agent whose CLI runs none of brindle's hooks (``hooks_off``: the
+    person's settings turn them off, at launch or later through /hooks, or
+    none reported within HOOKS_GRACE of its input box appearing) has only the
+    screen to go by: it may leave 'starting', a single read may move it from
+    'idle' to busy, and a ``samples`` >= 2 idle read delivers what's queued
+    even when the status was already idle, since no Stop hook ever will."""
     provider = get_provider(agent.provider)
     if (agent.headless or not provider.uses_hooks
             or agent.status not in ("starting", "idle", "processing", "waiting")):
         return None  # a headless pane shows output, not a TUI to read
-    if agent.status == "idle" and samples < 2:
+    _sync_hooks_off(db, agent, provider.hooks_disabled(*_settings_scope(db, agent)))
+    if agent.status == "idle" and samples < 2 and not agent.hooks_off:
         return None
-    seen = set()
+    seen, ready = set(), True
     for i in range(samples):
         if i:
             time.sleep(gap)
@@ -1525,25 +1541,71 @@ def screen_status(db: DB, agent: Agent, samples: int = 2, gap: float = 0.7) -> s
         if agent.status == "idle" and state == "busy" and not provider.busy_in_footer(screen):
             state = None
         seen.add(state)
+        ready = ready and provider.input_ready(screen)
+    if (agent.status == "starting" and not agent.hooks_off and ready and provider.announces_start
+            and time.time() - (agent.status_since or agent.created_at) >= HOOKS_GRACE):
+        # Its input box is up, and SessionStart, which runs before it, never reported.
+        # (A CLI without one is marked ready by after_launch instead: see ready.)
+        _sync_hooks_off(db, agent, f"{NO_HOOK_EVENTS} from {provider.name}")
     if len(seen) != 1:
         return None
     state = seen.pop()
     new = {"idle": "idle", "busy": "processing", "waiting": "waiting"}.get(state or "")
-    if agent.status == "starting" and new != "waiting":
+    if agent.status == "starting" and new != "waiting" and not agent.hooks_off:
         # Its hooks say when it's ready; the screen only adds that it's
         # stuck on a dialog before they could (e.g. folder trust).
         return None
-    if new and new != agent.status:
+    changed = bool(new) and new != agent.status
+    if changed:
         db.set_status(agent.id, new, only_if=agent.status)
         agent.status = new
-        if new == "idle" and samples >= 2 and db.pending_count(agent.id):
-            try:
-                flush(db, agent.id)
-            except tmux.TmuxError:
-                pass  # stays queued; its Stop hook hands it over
+    if (new == "idle" and samples >= 2 and (changed or agent.hooks_off)
+            and db.pending_count(agent.id)):
+        try:
+            flush(db, agent.id)
+        except tmux.TmuxError:
+            pass  # stays queued; its Stop hook hands it over
     return new
 
 
+# How long a hooks CLI may show its input box while still 'starting' before
+# brindle takes it that none of its hooks run (see screen_status).
+HOOKS_GRACE = 60.0
+# How hooks_off reads when no settings explain it, only the missing events.
+NO_HOOK_EVENTS = "no hook events"
+
+
+_settings_scopes: dict[tuple[str, float], tuple[str | None, list[str] | None]] = {}
+
+
+def _settings_scope(db: DB, agent: Agent) -> tuple[str | None, list[str] | None]:
+    """Where ``agent``'s CLI reads its settings: its workspace, and the
+    profile's setting_sources (None: all of them). Kept per agent, as the
+    sidebar asks on every refresh and a running CLI keeps its launch flags."""
+    key = (agent.id, agent.created_at)
+    if key in _settings_scopes:
+        return _settings_scopes[key]
+    from brindle.profiles import ProfileError
+
+    ws = db.get_workspace(agent.workspace_id)
+    try:
+        sources = load_profile(agent.profile, ws.repo_root if ws else None).setting_sources
+    except (KeyError, ProfileError):
+        sources = None
+    scope = _settings_scopes[key] = (ws.path if ws else None), sources
+    return scope
+
+
+def _sync_hooks_off(db: DB, agent: Agent, why: str | None) -> None:
+    """Record ``why`` its hooks are off; None clears a reason the settings
+    gave (turned back on), but not missing events, which only a hook clears."""
+    if why is None and agent.hooks_off and agent.hooks_off.startswith(NO_HOOK_EVENTS):
+        return
+    if why != agent.hooks_off:
+        db.update_agent(agent.id, hooks_off=why)
+        agent.hooks_off = why
+
+
 def _deliver_to_inbox(db: DB, agent: Agent, message_id: int, text: str,
                       sender_id: str | None) -> bool:
     """Send a queued message through Claude Code's own inbox (see
@@ -2661,6 +2723,8 @@ def handle_hook(db: DB, agent_id: str, event: str, payload: dict) -> dict | None
     agent = db.get_agent(agent_id)
     if agent is None:
         return None
+    if agent.hooks_off:
+        db.update_agent(agent_id, hooks_off=None)  # its hooks run after all: turned back on
     # A hook runs only once the session is going, so its launch is past any
     # startup prompt: a menu on its pane from now on is the agent's own (a
     # question for the user), which no sweep may answer.
@@ -2750,6 +2814,11 @@ def handle_hook(db: DB, agent_id: str, event: str, payload: dict) -> dict | None
         db.set_status(agent_id, "processing", only_if="waiting")
         db.set_status(agent_id, "processing", only_if="idle")  # see "pre-tool"
         note_permission_outcome(db, agent, payload)
+        from brindle import launch_health
+        try:
+            launch_health.check_mcp(db, agent)
+        except Exception:  # noqa: BLE001
+            log.exception("brindle: couldn't check the brindle MCP server's start")
     elif event == "stop":
         from brindle import inbox, tasks
 
@@ -3052,6 +3121,47 @@ def reopen_reviewer(db: DB, agent: Agent, ws: Workspace,
     return True
 
 
+def review_moot(db: DB, agent: Agent) -> bool:
+    """A reviewer whose branch already merged at its current commit: there is
+    nothing left for it to review or report. A reviewer of commits made after
+    the merge is not moot."""
+    if agent.mode != "review":
+        return False
+    ws = db.get_workspace(agent.workspace_id)
+    if ws is None:
+        return False
+    from brindle import pipeline
+
+    return (pipeline._settled(db, ws) or "").startswith(pipeline.ALREADY_MERGED)
+
+
+def liveness(db: DB, a: Agent, ws: Workspace | None, panes: dict[str, bool] | None = None) -> str:
+    """What brindle can see of an agent for free, as one line for its
+    supervisor: whether it's running, when it last did anything, and what
+    its branch holds, so deciding what to do about it takes no digging.
+    Never raises: a fact it can't read is left out."""
+    parts = []
+    try:
+        parts.append("running" if is_alive(a, panes) else "not running")
+        path = transcript_file(a)
+        last = (os.stat(path).st_mtime if path else
+                tmux.window_activity(a.tmux_window, server=server_of(a)) if a.tmux_window else None)
+        if last:
+            parts[-1] += f", last active {int((time.time() - last) // 60)} min ago"
+        if ws is not None and os.path.isdir(ws.path):
+            base = git.base_ref(ws.path, ws.base_branch or git.default_branch(ws.repo_root))
+            ahead = git.ahead_behind(ws.path, base)[1]
+            stat = git.out(["diff", "--stat", git.merge_base(ws.path, base)], ws.path).splitlines()
+            files = ", ".join(ln.split("|")[0].strip() for ln in stat[:-1][:5])
+            more = f" and {len(stat) - 6} more" if len(stat) > 6 else ""
+            parts.append(f"{ahead} commit(s) ahead of {base}"
+                         + (f" ({files}{more}: {stat[-1].strip()})" if stat else ""))
+            parts.append(f"{len(git.dirty_files(ws.path))} uncommitted file(s)")
+    except Exception:  # noqa: BLE001
+        pass
+    return "; ".join(parts)
+
+
 def tell_parent_unreported(db: DB, agent: Agent) -> bool:
     """A worker stopped again after being reminded to report, still without a
     result. It won't be reminded again on its own, and its supervisor has
@@ -3064,6 +3174,9 @@ def tell_parent_unreported(db: DB, agent: Agent) -> bool:
         _note_reviewer_end(db, agent)
         return False
     ws = db.get_workspace(agent.workspace_id)
+    if review_moot(db, agent):
+        close_later(agent.id)
+        return False
     if agent.mode == "review" and ws is not None and os.path.isdir(ws.path):
         from brindle import gates
 
@@ -3092,9 +3205,10 @@ def tell_parent_unreported(db: DB, agent: Agent) -> bool:
             if agent.pipeline == "fixing" and agent.result is not None
             else f"stopped without calling {tool}")
     body = (
-        f"{who} {agent.id}{where} {what}, and won't be reminded "
-        f"again on its own. Check on it: workspace_diff to see what it did, send_message to "
-        f"ask it to finish or report, or remove_workspace if the work is abandoned."
+        f"{who} {agent.id}{where} {what}, and won't be reminded again on its own. "
+        f"What brindle sees: {liveness(db, agent, ws)}. Decide from that: send_message to "
+        f"ask it to finish or report, workspace_diff for the full change, or remove_workspace "
+        f"if the work is abandoned."
     )
     try:
         send_message(db, agent.parent_id, body)