code-coordinator 0.5.507__tar.gz → 0.5.508__tar.gz

{code_coordinator-0.5.507 → code_coordinator-0.5.508}/CLAUDE.md

@@ -2,20 +2,21 @@
 
 CLI tool + per-machine agent server that coordinates Claude Code workers across multiple machines and repos over Tailscale.
 
-> **Scope of this file (#2195).** This is the **worker- and reviewer-facing** rulebook: it is
-> loaded into every worker leg, every review leg, and every coordinator session — and re-read on
-> every turn of each — so it holds only what someone *editing this repo* must act on. Operator
-> runbooks live in [`docs/`](docs/), indexed by
-> [`docs/OPERATOR_GUIDES.md`](docs/OPERATOR_GUIDES.md). Settled design rationale lives in
-> [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md#design-decisions--the-settled-rationale).
-> Keep it that way: **if a new rule does not change what a worker does, it belongs in `docs/`.**
-> Operator sessions — the "dispatch, don't do" rule now lives in
-> [`docs/COST_DISCIPLINE.md`](docs/COST_DISCIPLINE.md); read it before hand-editing any tracked
-> repo. If you're a worker or reviewer leg, that one isn't for you.
-
-## Current Goal — read first
-
-**[`GOAL.md`](GOAL.md) holds the current north-star objective** — the living, cross-repo / cross-machine goal that should bias all planning, triage, and dispatch. It is meta-level (above any single issue, repo, or session) and changes as priorities evolve: read it first, plan against it, and keep it current. `coordinator.yml` is the source of truth for *topology*; `GOAL.md` is the source of truth for *intent*.
+> **Scope of this file (#2195, #2817).** This is the **worker- and reviewer-facing**
+> rulebook: it is loaded into every worker leg, every review leg and every coordinator
+> session — and re-read on **every turn** of each, so every byte here is a recurring
+> fleet-wide cost. It holds only what someone *editing this repo* must act on.
+> **If a new rule does not change what a worker does, it belongs in [`docs/`](docs/).**
+> `tests/test_claude_md_budget.py` enforces that with a byte cap — move a section out
+> rather than raise it.
+>
+> Not here: operator runbooks ([`docs/OPERATOR_GUIDES.md`](docs/OPERATOR_GUIDES.md)) ·
+> settled design rationale
+> ([`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md#design-decisions--the-settled-rationale)) ·
+> the `coord` command reference (`coord <cmd> --help`) · operator cost rules and
+> "dispatch, don't do" ([`docs/COST_DISCIPLINE.md`](docs/COST_DISCIPLINE.md)) ·
+> the current north-star objective ([`GOAL.md`](GOAL.md) — read it in a coordinator
+> session when planning or triaging; a worker or reviewer leg does not need it).
 
 ## Codebase navigation — query the graph first
 
@@ -64,22 +65,11 @@ Query the **graphify graph** (`graphify-out/`) for the full module map + relatio
 
 ## Commands
 
-`coord <cmd> --help` documents every command + flags. The core loop:
-
-```bash
-coord plan                 # Brain proposes assignments for idle machines
-coord approve 1,3          # Dispatch approved proposals (comma-separated IDs)
-coord assign <machine> <repo> <issue> [--briefing TEXT | --briefing-file F] [--dry-run]  # Direct dispatch
-coord status [--freshness] # Machines, assignments, connectivity (+ repo freshness vs GitHub HEADs)
-coord log <id> [-f] [--machine NAME]            # claude -p output (remote logs need --machine)
-coord notify               # Poll agents, post completion/failure comments to GitHub
-coord test --passed|--fail|--skipped <id>       # Record the Test-gate verdict (bare `coord test <id>` builds+tests locally)
-coord merge [--dry-run] [--repo NAME] [--method rebase|squash|merge] [--order IDs] [--force-merge]
-coord reconcile-merges     # Backfill missing branches + record out-of-band merges (#609/#611)
-coord retry|stop|resume <id>                    # Recovery; `coord done` ends the session
-```
-
-Setup / diagnostics (discoverable via `--help`): `coord init`, `coord config`, `coord agent`, `coord serve`, `coord web`, `coord diagnose`, `coord sessions [--remote]`, `coord split`, `coord notifier`, `coord repo add` / `coord repo doctor`.
+`coord <cmd> --help` documents every command and flag — that is the reference, not this
+file. The operator-facing core loop (`plan`/`approve`/`assign`/`status`/`merge`/...) is in
+[`docs/OPERATOR_GUIDES.md`](docs/OPERATOR_GUIDES.md#the-core-loop). The one `coord` command
+a **worker** runs is `coord acceptance run --issue N`, in an oracle-loop round (see Testing
+below).
 
 ## Development
 
@@ -133,34 +123,22 @@ computes the routing without actually building or testing anything.
 
 ## Key Design Decisions
 
-One line each — the reasoning behind them is in
-[`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md#design-decisions--the-settled-rationale).
-
-- **No API key needed.** Everything uses `claude -p`, which runs on a Max/Pro subscription via OAuth.
-- **Agent servers are dumb dispatchers.** They spawn `claude -p` and track the subprocess; all intelligence is in the coordinator brain.
-- **GitHub issue comments are the message bus.** Briefings, completion notices and failure reports are comments, carrying `<!-- coord:... -->` markers for machine parsing.
-- **`coordinator.yml` is the single source of truth** for repo topology, machine capabilities, dependencies, concurrency limits, review settings, smoke-test rules, and the pipeline gate order (`pipeline.default_gates`). It lives in `~/.coord/`, **not** the repo checkout.
-- **User approves everything.** `coord plan` proposes, the user reviews, `coord approve` dispatches. No autonomous dispatch.
-- **Claim detection prevents duplicate work.** Before dispatching, the coordinator checks the board for active assignments and the remote for `issue-{N}-*` branches.
-- **Conflict rules are inferred, not configured.** There is no `file_groups`/`exclusive_files` config and never will be. `coord drive-queue add` compares an issue's own `## Files` declaration against the **real diffs** of in-flight branches in that repo (`coord/overlap_predict.py`, #2247) and, on an overlap, chains the newcomer `--after` the incumbent. **It ORDERS, never refuses** — a false positive costs latency, a refusal costs work. Accuracy is measured, not assumed: `coord drive-queue overlap-report`.
-- **Adversarial reviews are rule-enforcing, not rubber-stamping.** On worker completion a fresh `claude -p` session on a *different* machine reviews the PR diff against this file and the review checklist, with zero shared context with the worker — that's the whole point.
-- **The pipeline order is `Work → Test → Review → Merge`.** Test precedes Review; the headless auto-loop holds review dispatch until there is a `passed`/`skipped` test verdict.
-- **Merge is gated on CI checks (#240).** `coord merge` refuses when a check failed or is still running — and a PR with *zero* reported checks is not automatically clear either (#1904).
-- **Mechanical merge conflicts auto-rebase (#241).** A `type="conflict-fix"` worker rebases and resolves additive merges; semantic conflicts are left for a human.
-- **Smoke tests validate on capable hardware.** `smoke_tests.capability_rules` map changed files to required machine capabilities (e.g. GTK changes → a machine with GTK).
-- **Progress streaming from workers.** Workers emit `STATUS:` and `STUCK:` lines; the coordinator parses these for real-time progress in `coord status` and the dashboard.
-- **The notifier tells you when NOBODY IS COMING — and nothing else (#1632).** Advisory, isolated, off by default; it is not an error channel and not a progress feed.
-
-## Review Prompt Assembly
-
-The reviewer gets a prompt built from:
-1. **Repo's CLAUDE.md** — the project rules (source of truth, not duplicated)
-2. **Generic checklist** — "did you add tests?", "did you stay in file scope?", "any security issues?"
-3. **Repo overrides** — project-specific patterns from `coordinator.yml` `reviews.repo_overrides`
-4. **The diff** — `gh pr diff` of the worker's branch vs base
-5. **The issue** — title and body for intent verification
-
-The reviewer reads the rules and enforces them against the diff. It does not have the worker's session context — genuinely independent.
+These are the ones a **diff** can violate. The full set, with the reasoning behind each, is
+in [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md#design-decisions--the-settled-rationale).
+
+- **`coordinator.yml` is the single source of truth** for repo topology, machine
+  capabilities, dependencies, concurrency limits, review settings, smoke-test rules and the
+  pipeline gate order (`pipeline.default_gates`). It lives in `~/.coord/`, **not** the repo
+  checkout.
+- **Conflict rules are inferred, not configured.** There is no `file_groups` /
+  `exclusive_files` config and never will be — `coord drive-queue add` compares an issue's
+  own `## Files` declaration against the **real diffs** of in-flight branches
+  (`coord/overlap_predict.py`, #2247). **It ORDERS, never refuses.** Do not add such config.
+- **The pipeline order is `Work → Test → Review → Merge`.** Test precedes Review; the
+  headless auto-loop holds review dispatch until there is a `passed`/`skipped` verdict.
+- **Adversarial reviews are rule-enforcing, not rubber-stamping.** A fresh `claude -p`
+  session on a *different* machine reviews your diff against this file, with **zero shared
+  context with you** — so your diff and final message must stand on their own.
 
 ## Rules for workers
 
@@ -212,7 +190,5 @@ versus keep in the coordinator session, and the coordinator session's own
 
 ## Operating the fleet — operator-facing
 
-**Not needed to work on this repo.** A worker or reviewer can stop reading here. Every operator
-runbook — the pre-flight gotchas, agent installs and releases, the drive queue, the customer
-portal, and the two deploy facts that bite most often — is indexed in
+**Not needed to work on this repo.** Every operator runbook is indexed in
 [`docs/OPERATOR_GUIDES.md`](docs/OPERATOR_GUIDES.md).

{code_coordinator-0.5.507 → code_coordinator-0.5.508}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-coordinator
-Version: 0.5.507
+Version: 0.5.508
 Summary: Coordinate Claude Code workers across multiple machines and repos.
 Author-email: John Donaghy <johnfdonaghy@gmail.com>
 License-Expression: LicenseRef-FSL-1.1-MIT

{code_coordinator-0.5.507 → code_coordinator-0.5.508}/code_coordinator.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-coordinator
-Version: 0.5.507
+Version: 0.5.508
 Summary: Coordinate Claude Code workers across multiple machines and repos.
 Author-email: John Donaghy <johnfdonaghy@gmail.com>
 License-Expression: LicenseRef-FSL-1.1-MIT

{code_coordinator-0.5.507 → code_coordinator-0.5.508}/code_coordinator.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
-  "tag": "0.5.507",
+  "tag": "0.5.508",
   "distance": 0,
-  "node": "g77eaf6af7d9e29387584dbfe661ea201eb62e524",
+  "node": "g8afe10d6337d6c249497f95932b1a6acd5596222",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-09-20"

{code_coordinator-0.5.507 → code_coordinator-0.5.508}/coord/agent.py

@@ -5062,6 +5062,136 @@ def _claude_md_system_prompt_suffix(repo_path: str) -> str:
     return "\n\n## Project rules (from CLAUDE.md)\n\n" + claude_md.strip() + "\n"
 
 
+# #3420: every `claude -p` leg loads the full JSON schema for all built-in
+# tools regardless of `--allowedTools`, which is a *permission* filter, not a
+# tool-surface one — a leg with `Read,Bash` in `--allowedTools` still pays
+# the prompt-token cost of the `Workflow`/`Skill`/etc. schemas it can never
+# call. Measured with controlled `claude -p` probes on this repo's own
+# `default_worker_command` flags (Claude Code 2.1.278, `type="work"`): the
+# schemas for these tools cost 12,134 tokens/turn (44% of the static
+# prefix), re-read at cache-read rates on every turn of every leg. None of
+# them has a legitimate use from a headless coord leg:
+#   - `Workflow`: requires explicit user opt-in; a headless leg has no user.
+#   - `Skill`: all `coord` skills are operator-only runbooks.
+#   - `ScheduleWakeup`: every leg is one-shot (WORKER_SYSTEM_PROMPT's
+#     ONE-SHOT section, #1394) — there is no future turn to wake up into.
+#   - `Task`: CLAUDE.md mandates `graphify query` + grep for navigation
+#     instead of spawning a subagent.
+#   - `ReportFindings`, `ListAgents`: unreferenced by any coord system
+#     prompt; no fleet-messaging or review-findings-reporting surface is
+#     exposed to a leg.
+#   - The remainder (`Cron*`, `DesignSync`, `EnterWorktree`/`ExitWorktree`,
+#     `NotebookEdit`, `PushNotification`, `RemoteTrigger`, `SendMessage`):
+#     operator/coordinator-session tools with no worker-leg counterpart —
+#     already deferred behind `ToolSearch` so each costs only ~6-9 tokens,
+#     but included for a consistent, minimal tool surface.
+#
+# Deliberately EXCLUDED, despite being equally unusable:
+#   - `Monitor`: 0 marginal token cost, and WORKER_SYSTEM_PROMPT's ONE-SHOT
+#     polling guidance depends on it (it's the sanctioned way to await a
+#     backgrounded command in bounded steps).
+#   - `ToolSearch`: cheap on its own, and removing it is untested — it's the
+#     mechanism that resolves every deferred tool name at all.
+#   - `TaskOutput`/`TaskStop`: look like `Task`'s output/cancel pair at
+#     first glance, but WORKER_SYSTEM_PROMPT's ONE-SHOT section and
+#     coord/smoke.py's SMOKE_SYSTEM_PROMPT both explicitly teach
+#     `TaskOutput` as the bounded-poll alternative to `Monitor` for a
+#     backgrounded Bash command (`run_in_background`) — disallowing it
+#     would make that documented guidance a dead end. `TaskStop` is kept
+#     alongside it since it's the same background-job-management pair.
+#   - `WebFetch`/`WebSearch`: ~6 tokens each either way (negligible), and a
+#     worker may legitimately need to look up library docs or an error
+#     message mid-task — kept allowed rather than trading real capability
+#     for a rounding error in prompt size.
+UNUSABLE_TOOL_SCHEMAS: list[str] = [
+    "Workflow",
+    "Skill",
+    "ScheduleWakeup",
+    "Task",
+    "ReportFindings",
+    "ListAgents",
+    "CronCreate",
+    "CronDelete",
+    "CronList",
+    "DesignSync",
+    "EnterWorktree",
+    "ExitWorktree",
+    "NotebookEdit",
+    "PushNotification",
+    "RemoteTrigger",
+    "SendMessage",
+]
+
+
+def worker_disallowed_tools(spec: AssignmentSpec, allowed_tools: str) -> list[str]:
+    """Return the ordered ``--disallowedTools`` entries for *spec*.
+
+    **Single source of truth.** Both argv builders that emit
+    ``--disallowedTools`` — :func:`default_worker_command` and
+    :meth:`coord.providers.claude.ClaudeProvider.build_command` — call
+    this, rather than each reimplementing the same four-layer stack. The
+    two previously transcribed the logic independently, which is exactly
+    how #3420's ``UNUSABLE_TOOL_SCHEMAS`` layer landed in one and not the
+    other; the parity suite in ``tests/test_providers.py`` caught it, but
+    a shared function makes the divergence unrepresentable instead of
+    merely detectable.
+
+    Layers, in argv order (each skips entries an earlier layer already
+    added, so the result is de-duplicated but order-stable):
+
+    1. #3420 ``UNUSABLE_TOOL_SCHEMAS`` — unconditional, every spec type.
+    2. #1315 sealed-oracle write guard, from ``spec.files_forbidden``.
+    3. #1642 base-checkout write guard — only when *allowed_tools*
+       actually grants ``Edit``; for the Read/Bash-only chat types the
+       guard would be a no-op cluttering the argv.
+    4. #2461 ``REVIEW_DENY_COMMANDS`` — only for ``spec.type ==
+       "review"``, wiring the mutating-command deny list into the
+       CLI-enforced flag and not just the soft prompt reminder.
+
+    Args:
+        spec: The assignment being dispatched.
+        allowed_tools: The ``--allowedTools`` value computed for this
+            spec — inspected for ``Edit`` to decide layer 3. Passing the
+            caller's own computed value (rather than re-deriving it here)
+            keeps the two flags consistent even when a caller overrides
+            ``--allowedTools`` explicitly, as ``build_command`` allows.
+
+    Returns:
+        A fresh list; callers may mutate it. Empty only in the
+        impossible case where every layer contributes nothing — since
+        #3420, layer 1 is unconditional, so in practice this is always
+        non-empty and ``--disallowedTools`` is always emitted.
+    """
+    # #3420: strip the unusable-tool schemas from every spec type, including
+    # the Read/Bash-only chat legs (plan, refinement, test-chat,
+    # new-issue-chat, smoke, review) — they carry the same
+    # Workflow/Skill/Task/etc. schemas as a work leg and benefit identically.
+    # This is FIRST so the guards below, which each append to this same
+    # list, keep working unchanged.
+    disallowed_tools = list(UNUSABLE_TOOL_SCHEMAS)
+    # #1315: structural sealing enforcement — see _sealed_write_guard_tools.
+    for pattern in _sealed_write_guard_tools(spec.files_forbidden):
+        if pattern not in disallowed_tools:
+            disallowed_tools.append(pattern)
+    # #1642: block Edit/Write on the shared base checkout for any spec.type
+    # that actually gets Edit/Write in --allowedTools — the Read/Bash-only
+    # chat types can't touch files regardless, and adding the guard there
+    # would be a no-op cluttering their argv for nothing.
+    if "Edit" in allowed_tools:
+        for pattern in _base_checkout_write_guard_tools(spec.repo_path):
+            if pattern not in disallowed_tools:
+                disallowed_tools.append(pattern)
+    # #2461: review gets its mutating-command deny list wired into
+    # --disallowedTools too, not just the soft system-prompt reminder from
+    # build_deny_prompt — the CLI enforces this one even if the model
+    # decides to ignore its own prompt.
+    if spec.type == "review":
+        for pattern in REVIEW_DENY_COMMANDS:
+            if pattern not in disallowed_tools:
+                disallowed_tools.append(pattern)
+    return disallowed_tools
+
+
 def default_worker_command(spec: AssignmentSpec, *, binary: str = DEFAULT_WORKER_BINARY) -> list[str]:
     """Build the argv for invoking the worker on this assignment.
 
@@ -5347,24 +5477,10 @@ def default_worker_command(spec: AssignmentSpec, *, binary: str = DEFAULT_WORKER
     ]
     if spec.model:
         argv.extend(["--model", spec.model])
-    # #1315: structural sealing enforcement — see _sealed_write_guard_tools.
-    disallowed_tools = _sealed_write_guard_tools(spec.files_forbidden)
-    # #1642: block Edit/Write on the shared base checkout for any spec.type
-    # that actually gets Edit/Write in --allowedTools — the Read/Bash-only
-    # chat types above can't touch files regardless, and adding the guard
-    # there would be a no-op cluttering their argv for nothing.
-    if "Edit" in allowed_tools:
-        for pattern in _base_checkout_write_guard_tools(spec.repo_path):
-            if pattern not in disallowed_tools:
-                disallowed_tools.append(pattern)
-    # #2461: review gets its mutating-command deny list wired into
-    # --disallowedTools too, not just the soft system-prompt reminder from
-    # build_deny_prompt above — the CLI enforces this one even if the model
-    # decides to ignore its own prompt.
-    if spec.type == "review":
-        for pattern in REVIEW_DENY_COMMANDS:
-            if pattern not in disallowed_tools:
-                disallowed_tools.append(pattern)
+    # #3420 / #1315 / #1642 / #2461: all four --disallowedTools layers live
+    # in worker_disallowed_tools, shared with ClaudeProvider.build_command so
+    # the two argv builders cannot drift apart (see that function's docstring).
+    disallowed_tools = worker_disallowed_tools(spec, allowed_tools)
     if disallowed_tools:
         argv.extend(["--disallowedTools", ",".join(disallowed_tools)])
     # #315: when resuming a prior chat session, load the prior conversation so

{code_coordinator-0.5.507 → code_coordinator-0.5.508}/coord/providers/claude.py

@@ -2,10 +2,13 @@
 
 Parity requirement: ``ClaudeProvider().build_command(spec)`` produces the
 **same argv** as ``coord.agent.default_worker_command(spec)`` for the same
-inputs.  The logic is a direct transcription of that function's body with
-the ``resolved_model`` / ``system_prompt`` / ``allowed_tools`` /
-``permission_mode`` kwargs spliced in; the parity tests in
-``tests/test_providers.py`` enforce this mechanically.
+inputs.  The ``spec.type`` → prompt/allowed-tools branches are a direct
+transcription of that function's body with the ``resolved_model`` /
+``system_prompt`` / ``allowed_tools`` / ``permission_mode`` kwargs spliced
+in; the parity tests in ``tests/test_providers.py`` enforce this
+mechanically.  The ``--disallowedTools`` stack is **not** transcribed —
+both builders call the shared ``coord.agent.worker_disallowed_tools``, so
+a new deny layer lands in both without a sync step (#3420).
 
 Imports from ``coord.agent`` are **deferred** (inside method bodies) to keep
 the import cycle latent until the wiring issue lands.  At that point
@@ -119,10 +122,9 @@ class ClaudeProvider(Provider):
             TEST_CHAT_SYSTEM_PROMPT,
             WORKER_PLAN_PROMPT,
             WORKER_SYSTEM_PROMPT,
-            _base_checkout_write_guard_tools,
             _claude_md_system_prompt_suffix,
-            _sealed_write_guard_tools,
             build_deny_prompt,
+            worker_disallowed_tools,
         )
         from coord.review import REVIEWER_SYSTEM_PROMPT  # noqa: PLC0415
         from coord.smoke import SMOKE_SYSTEM_PROMPT  # noqa: PLC0415
@@ -285,20 +287,16 @@ class ClaudeProvider(Provider):
         ]
         if effective_model:
             argv.extend(["--model", effective_model])
-        # #1315 / #1642: same structural write guards as
-        # default_worker_command — sealed-oracle prefix plus (for any type
-        # with Edit in --allowedTools) the shared base checkout.
-        disallowed_tools = _sealed_write_guard_tools(spec.files_forbidden)
-        if "Edit" in allowed_tools:
-            for pattern in _base_checkout_write_guard_tools(spec.repo_path):
-                if pattern not in disallowed_tools:
-                    disallowed_tools.append(pattern)
-        # #2461: same CLI-enforced hard block as default_worker_command —
-        # see REVIEW_DENY_COMMANDS.
-        if spec.type == "review":
-            for pattern in REVIEW_DENY_COMMANDS:
-                if pattern not in disallowed_tools:
-                    disallowed_tools.append(pattern)
+        # #3420 / #1315 / #1642 / #2461: NOT transcribed from
+        # default_worker_command like the branches above — both builders call
+        # the one shared `worker_disallowed_tools`, so a new deny layer lands
+        # in both by construction. It previously WAS transcribed here, and
+        # #3420's unusable-tool-schema layer went into default_worker_command
+        # only; the parity suite caught the drift, but the shared call means
+        # there is nothing left to keep in sync. Pass this method's own
+        # `allowed_tools` (possibly a caller override) so the two flags stay
+        # consistent.
+        disallowed_tools = worker_disallowed_tools(spec, allowed_tools)
         if disallowed_tools:
             argv.extend(["--disallowedTools", ",".join(disallowed_tools)])
         if spec.resume_session_id:

{code_coordinator-0.5.507 → code_coordinator-0.5.508}/docs/ARCHITECTURE.md

@@ -250,6 +250,21 @@ which is why it lives here rather than in the file every worker leg loads. The o
 statements of these rules remain in `CLAUDE.md`'s "Key Design Decisions"; the reasoning is
 here.
 
+### How the review prompt is assembled
+
+The reviewer gets a prompt built from:
+1. **Repo's CLAUDE.md** — the project rules (source of truth, not duplicated)
+2. **Generic checklist** — "did you add tests?", "did you stay in file scope?", "any security issues?"
+3. **Repo overrides** — project-specific patterns from `coordinator.yml` `reviews.repo_overrides`
+4. **The diff** — `gh pr diff` of the worker's branch vs base
+5. **The issue** — title and body for intent verification
+
+The reviewer reads the rules and enforces them against the diff. It does not have the worker's session context — genuinely independent.
+
+Moved here from [`CLAUDE.md`](../CLAUDE.md) (#3422). The reviewer does not need a description
+of how its own prompt was built, and neither does a worker — this is for someone editing
+`coord/review.py`.
+
 ### Agent servers are dumb dispatchers
 
 They spawn `claude -p` and track the subprocess. All intelligence is in the coordinator

{code_coordinator-0.5.507 → code_coordinator-0.5.508}/docs/OPERATOR_GUIDES.md

@@ -19,6 +19,29 @@ in `docs/`.*
   still manual. Epic #3117.
 - [`DRIVE_QUEUE.md`](DRIVE_QUEUE.md) — the durable, board-backed driver (`coord drive-queue`, #1750). **Read the top section before queuing more than ~2 issues on one repo.**
 
+## The core loop
+
+Moved here from [`CLAUDE.md`](../CLAUDE.md) (#3422): a worker cannot run any of these —
+the coordinator owns dispatch and GitHub — so it was pure operator surface being re-read
+on every turn of every leg. `coord <cmd> --help` remains the authoritative reference.
+
+`coord <cmd> --help` documents every command + flags. The core loop:
+
+```bash
+coord plan                 # Brain proposes assignments for idle machines
+coord approve 1,3          # Dispatch approved proposals (comma-separated IDs)
+coord assign <machine> <repo> <issue> [--briefing TEXT | --briefing-file F] [--dry-run]  # Direct dispatch
+coord status [--freshness] # Machines, assignments, connectivity (+ repo freshness vs GitHub HEADs)
+coord log <id> [-f] [--machine NAME]            # claude -p output (remote logs need --machine)
+coord notify               # Poll agents, post completion/failure comments to GitHub
+coord test --passed|--fail|--skipped <id>       # Record the Test-gate verdict (bare `coord test <id>` builds+tests locally)
+coord merge [--dry-run] [--repo NAME] [--method rebase|squash|merge] [--order IDs] [--force-merge]
+coord reconcile-merges     # Backfill missing branches + record out-of-band merges (#609/#611)
+coord retry|stop|resume <id>                    # Recovery; `coord done` ends the session
+```
+
+Setup / diagnostics (discoverable via `--help`): `coord init`, `coord config`, `coord agent`, `coord serve`, `coord web`, `coord diagnose`, `coord sessions [--remote]`, `coord split`, `coord notifier`, `coord repo add` / `coord repo doctor`.
+
 ## Reference
 
 - [`ARCHITECTURE.md`](ARCHITECTURE.md) — how it all fits together, plus the settled design rationale. Two diagnostic entry points: [why a merge/review isn't happening](ARCHITECTURE.md#when-a-merge-isnt-happening) (**check here first when "Go does nothing"**) and [why an issue is in the Pipeline you never dispatched](ARCHITECTURE.md#when-an-issue-is-sitting-in-the-pipeline-you-never-dispatched).

{code_coordinator-0.5.507 → code_coordinator-0.5.508}/tests/test_agent.py

@@ -26,6 +26,7 @@ from coord.agent import (
     REVIEW_DENY_COMMANDS,
     RUNNING,
     RUNTIME_CEILING_EXIT,
+    UNUSABLE_TOOL_SCHEMAS,
     MOCK_AUTHOR_SYSTEM_PROMPT,
     WORKER_SYSTEM_PROMPT,
     AgentAssignment,
@@ -1862,8 +1863,10 @@ def test_default_worker_command_blocks_base_checkout_writes() -> None:
     disallowed = argv[idx + 1]
     assert "Edit(//tmp/repo/**)" in disallowed
     assert "Write(//tmp/repo/**)" in disallowed
-    # Read-only spec types (no Edit in --allowedTools) get no guard at all —
-    # they can't write anywhere so the flag would be a no-op.
+    # Read-only spec types (no Edit in --allowedTools) get no base-checkout
+    # guard entries — they can't write anywhere so those patterns would be a
+    # no-op. --disallowedTools itself is still present, though (#3420: the
+    # unusable-tool-schema list applies unconditionally to every spec type).
     plan_spec = AssignmentSpec(
         repo_name="api",
         repo_path="/tmp/repo",
@@ -1872,7 +1875,11 @@ def test_default_worker_command_blocks_base_checkout_writes() -> None:
         briefing="b",
         type="plan",
     )
-    assert "--disallowedTools" not in default_worker_command(plan_spec)
+    plan_argv = default_worker_command(plan_spec)
+    assert "--disallowedTools" in plan_argv
+    plan_disallowed = plan_argv[plan_argv.index("--disallowedTools") + 1]
+    assert "Edit(" not in plan_disallowed
+    assert "Write(" not in plan_disallowed
 
 
 def test_default_worker_command_blocks_sealed_oracle_writes() -> None:
@@ -1927,6 +1934,119 @@ def test_default_worker_command_mock_author_not_sealed() -> None:
     assert "Write(//tmp/repo/**)" in disallowed
 
 
+# ── #3420: strip unusable tool schemas from every leg ────────────────────────
+
+
+@pytest.mark.parametrize(
+    "spec_type",
+    [
+        "plan",
+        "refinement",
+        "test-chat",
+        "new-issue-chat",
+        "milestone-chat",
+        "decomposition-chat",
+        "mock-author",
+        "smoke",
+        "review",
+        "work",
+    ],
+)
+def test_default_worker_command_disallows_unusable_tool_schemas_for_every_spec_type(
+    spec_type: str,
+) -> None:
+    """Every tool schema Claude Code still loads even though a worker/chat
+    leg can never legitimately call it (Workflow needs a user, Skill is
+    operator-only, etc. — see UNUSABLE_TOOL_SCHEMAS' docstring comment) must
+    land in --disallowedTools for EVERY spec type, not just work legs — the
+    Read/Bash-only chat types pay the exact same schema cost and benefit
+    identically (#3420)."""
+    spec = AssignmentSpec(
+        repo_name="api",
+        repo_path="/tmp/repo",
+        issue_number=1,
+        issue_title="t",
+        briefing="b",
+        type=spec_type,
+    )
+    argv = default_worker_command(spec)
+    assert "--disallowedTools" in argv
+    disallowed = argv[argv.index("--disallowedTools") + 1].split(",")
+    for tool in UNUSABLE_TOOL_SCHEMAS:
+        assert tool in disallowed, f"{tool} missing from --disallowedTools for type={spec_type}"
+
+
+def test_unusable_tool_schemas_keeps_the_one_shot_polling_tools() -> None:
+    """Monitor and TaskOutput/TaskStop must NOT be disallowed: both
+    WORKER_SYSTEM_PROMPT's ONE-SHOT section and coord.smoke.SMOKE_SYSTEM_PROMPT
+    explicitly teach `Monitor` / `TaskOutput` as the sanctioned bounded-poll
+    pattern for a backgrounded Bash command. Disallowing either would turn
+    documented guidance into a dead end. ToolSearch (resolves every deferred
+    tool name) and WebFetch/WebSearch (kept for real capability — see the
+    comment above UNUSABLE_TOOL_SCHEMAS) must not be disallowed either."""
+    for tool in ("Monitor", "ToolSearch", "TaskOutput", "TaskStop", "WebFetch", "WebSearch"):
+        assert tool not in UNUSABLE_TOOL_SCHEMAS
+
+
+def test_default_worker_command_unusable_tool_schemas_coexist_with_sealed_write_guard() -> None:
+    """Regression for #3420: disallowed_tools must be BUILT UP (append), not
+    overwritten, by the new unusable-tool-schema seed — a bare `disallowed_tools
+    = list(UNUSABLE_TOOL_SCHEMAS)` placed after the #1315 sealed-write guard
+    populated it would silently discard that guard. Confirms both the new
+    entries and the existing sealed-oracle guard appear together in the same
+    --disallowedTools value for a sealed work spec."""
+    spec = AssignmentSpec(
+        repo_name="api",
+        repo_path="/tmp/repo",
+        issue_number=1120,
+        issue_title="t",
+        briefing="please fix tests/acceptance/ms-38/contract.md",
+        files_forbidden=["tests/acceptance/"],
+    )
+    argv = default_worker_command(spec)
+    disallowed = argv[argv.index("--disallowedTools") + 1]
+    assert "Edit(tests/acceptance/**)" in disallowed
+    assert "Write(tests/acceptance/**)" in disallowed
+    for tool in UNUSABLE_TOOL_SCHEMAS:
+        assert tool in disallowed.split(",")
+
+
+@pytest.mark.posix_only
+@_posix_repo_path_skip
+def test_default_worker_command_unusable_tool_schemas_coexist_with_base_checkout_guard() -> None:
+    """Regression for #3420: confirms the #1642 base-checkout guard (which
+    appends to disallowed_tools AFTER the new seed) still lands alongside the
+    unusable-tool-schema entries for an Edit-capable spec — the seed must not
+    have clobbered what the base-checkout guard adds next."""
+    spec = AssignmentSpec(
+        repo_name="api",
+        repo_path="/tmp/repo",
+        issue_number=1,
+        issue_title="t",
+        briefing="b",
+        files_forbidden=[],
+    )
+    argv = default_worker_command(spec)
+    disallowed = argv[argv.index("--disallowedTools") + 1]
+    assert "Edit(//tmp/repo/**)" in disallowed
+    assert "Write(//tmp/repo/**)" in disallowed
+    for tool in UNUSABLE_TOOL_SCHEMAS:
+        assert tool in disallowed.split(",")
+
+
+def test_default_worker_command_unusable_tool_schemas_coexist_with_review_deny_commands() -> None:
+    """Regression for #3420: confirms #2461's REVIEW_DENY_COMMANDS (appended
+    to disallowed_tools last, for spec.type == "review") still lands
+    alongside the unusable-tool-schema entries — a bare overwrite anywhere in
+    the chain would silently disable the review mutating-command guard."""
+    argv = default_worker_command(_review_spec())
+    disallowed = argv[argv.index("--disallowedTools") + 1].split(",")
+    for pattern in REVIEW_DENY_COMMANDS:
+        assert pattern in disallowed
+    for tool in UNUSABLE_TOOL_SCHEMAS:
+        assert tool in disallowed
+
+
 # ── #1445: worktree-writability preflight ───────────────────────────────────
 
 

{code_coordinator-0.5.507 → code_coordinator-0.5.508}/tests/test_claude_md_budget.py

@@ -2,9 +2,13 @@
 
 CLAUDE.md is loaded into every worker leg, every review leg, and every
 coordinator session -- and re-read on every turn of each, at cache-read
-rates. It has already been cut twice for size (#2195: 41,506 -> 24,219
+rates. It had already been cut twice for size (#2195: 41,506 -> 24,219
 bytes; #2787: ~29,732 -> 19,622 bytes) because nothing watched its size in
 between, and it drifted back up at roughly 500 bytes/day both times.
+#3422 cut it a third time (18,605 -> 15,001) by moving the `## Commands`
+reference, the explanatory Key-Design bullets and the review-prompt-assembly
+note out to docs/ -- the first cut made with this guard already in place, so
+the cap came down with the file rather than leaving room to drift back into.
 
 This test is that watch. It is deliberately dumb: a byte count, nothing
 more -- no parsing, no section analysis, no escape hatch. See #2817 for the
@@ -15,14 +19,14 @@ from __future__ import annotations
 
 from pathlib import Path
 
-# ~4% headroom over the 19,622-byte size CLAUDE.md was at immediately after
-# the #2787 re-split. Raising this constant is a deliberate, reviewable act
+# ~6% headroom over the 15,001-byte size CLAUDE.md was at immediately after
+# the #3422 operator-split. Raising this constant is a deliberate, reviewable act
 # -- not something to do reflexively to make this test pass. If CLAUDE.md
 # has grown past the cap, the fix is almost always to MOVE a section to
 # docs/ (leaving a one-line pointer behind), not to raise this number. Per
 # the file's own scope note: "if a new rule does not change what a worker
 # does, it belongs in docs/."
-CLAUDE_MD_MAX_BYTES = 20480  # 20 KiB
+CLAUDE_MD_MAX_BYTES = 15872  # 15.5 KiB
 
 CLAUDE_MD_PATH = Path(__file__).resolve().parent.parent / "CLAUDE.md"
 
@@ -37,7 +41,7 @@ def test_claude_md_stays_within_byte_budget() -> None:
         "Its size is a direct, per-turn, fleet-wide cost, not a one-time "
         "reading-time cost.\n\n"
         "This file has already been cut twice for exactly this reason "
-        "(#2195, #2787) and drifted back up both times because nothing "
+        "(#2195, #2787, #3422) and drifted back up each time because nothing "
         "enforced a cap -- that is what this test is for.\n\n"
         "The fix is almost always to MOVE a section out to docs/ (leaving "
         "a short pointer line in CLAUDE.md), per the file's own scope "