[bug] #401's github_list_pulls / github_read_pull are unreachable by EVERY agent — no seeded capabilities.tools declares them, so the Pulls panel works and no agent can answer "what PRs are open?"

[serge-ivo]

#401 shipped the Pulls panel and, with it, two registry tools so an agent could answer the
question directly: github_list_pulls and github_read_pull (6f6e42f). The panel works. The
tools are unreachable — by every agent on the platform, including the legacy coder.

Ask a Repo Coder "what pull requests are open on this repo?" and it has no tool for it. It will
either decline or reach for the terminal, which is the overlapping drive-path the Coder-2 split
exists to remove.

Correction to the report I was handed

The claim was that "the legacy coder slug declares no allowlist and gets them today." It does
declare one — migration 0054_coder_github_tools.sql re-set coder's full capabilities object,
including "tools":["github_create_issue","github_list_issues","github_read_issue"]. So coder is
on the allowlist path too and is equally blocked. Nothing can call these tools.

Measured, in production

GET /v1/instances/{coder-repo instance}/tools:

{
  "name": "github_list_pulls",
  "connector": "github",
  "scope": "read",
  "allowed": false,
  "disabled": false,
  "reason": "not_declared",
  "writeConsent": "n/a"
}

GET /v1/instances/my/instances, resolved capabilities.tools:

agent	declared tools
coder-repo	repo_tree, repo_read_file, repo_git, repo_remote, github_list_issues, github_read_issue, github_create_issue
coder-lead	list_subordinates, subordinate_status, delegate_goal, check_delegation, github_list_issues, github_read_issue
coder	github_create_issue, github_list_issues, github_read_issue
repo-chat	search_knowledge, list_knowledge, read_knowledge

Not one carries a pulls tool.

Mechanism

workers/api/src/agent-do-tools.ts:187-203 — a declared list is authoritative, not additive to
a default:

if (declared?.length) {
    set = new Set<string>(BASE);
    for (const name of declared) if (CREATOR_SELECTABLE_TOOLS.has(name)) set.add(name);
}

A name absent from capabilities.tools is never handed to the model, and a text-embedded call to it
is refused. The registry half is complete and correct — lib/connectors/github.ts:190-209 declares
both with scope: "read" (no write consent needed) and :229-230 wires the handlers — so this is
purely the declaration side.

Two correct decisions composing: an authoritative allowlist is exactly what makes a third-party
creator's tool scope safe (#58), and shipping a tool into the registry is the normal way to add
one. Nothing connects them, so a registry addition is inert until a migration says otherwise.

Do

• One migration. The next free number is 0100 — the highest on main is
  0099_tmux_operator_backend_exclusive_tools.sql. (There are 100 migration files because
  0092 is a historical duplicate pair, recorded as an exception in scripts/check-migrations.mjs;
  the count is not the highest number.)
• Follow 0054's shape: json_set re-setting the full $.capabilities object so the JSON
  stays one source of truth, idempotent, one UPDATE … WHERE slug = '…' per agent. Do not
  edit 0054/0070 — check-migrations.mjs --require-history fails a migration whose DDL
  changes after the commit that introduced it.
• coder-repo and coder: add both tools. They already read and write issues; pull
  requests are the same family and the same auth path.
• coder-lead: recommend adding both. A Lead reads issues to decide what to delegate; one
  that can see PRs can notice "that is already open in [bug] A negatively-jittered cron run computes its next slot from the early fire time — "@daily" reliably fires twice in one night #412" before spending an Engine on it.
  Owner's call — it widens what the Lead reads, and it is the one of the three where the
  benefit is an argument rather than a gap.
• repo-chat: recommend not adding. Its declared set is deliberately knowledge-only
  (migration 0050, the first agent built "the creator way") and giving it connector tools is a
  product decision, not a fix for this.

No console change and no instance migration needed: capabilitiesForInstance
(lib/agent-capabilities.ts:524-541) JOINs the agents row at read time, so updating the agent
reaches every already-subscribed instance on the next turn. Verified.

Alternatives considered

• Auto-grant every read-scoped registry tool to any agent that declares a sibling from the same
  connector. Rejected: it would silently widen every existing agent whenever a connector gains a
  tool — the exact inversion of what the allowlist is for, and it would have handed
  github_workflow_runs to agents that never asked for it.
• Drop the tools and let the panel be the only surface. Rejected: the panel answers a human
  looking at a screen. [feature] Coding agents cannot show a pull request — add a Pulls panel, and make "don't fetch if nothing changed" true with GitHub conditional requests #401's stated gap was the agent's, and the console already proves the data
  path works.

Acceptance

• GET /v1/instances/:id/tools for a coder-repo instance reports allowed: true for
  github_list_pulls and github_read_pull.
• Asking that instance's Assistant "what pull requests are open on owner/repo?" produces a
  tool.call for github_list_pulls in agent_trace — not a decline and not a terminal
  command.
• A test asserts the declared lists contain both names, in the shape
  workers/api/src/lib/coder2-parity.test.ts already uses for the issue tools.

Regression risk

• MAX_DECLARED_TOOLS is 40 (lib/agent-capabilities.ts:343); coder-repo goes 7 → 9. No risk,
  but it is the cap that silently truncates so it is worth naming.
• coder2-parity.test.ts:131-166 parses migration 0070 by regex (declared0070()) to assert
  the Repo Coder kept the Co-pilot's read tools. After 0100, 0070 is no longer the effective
  declaration and that helper reads a superseded list — it will keep passing while describing the
  wrong state. Either point it at the latest migration touching coder-repo, or re-word it to say
  it only guards that 0070 did not lose anything. Do not leave it silently stale; that is the
  same trap as an expired premise.
• The tools are scope: "read", so no write-consent surface changes and no new grant is requested
  from any owner.

Files: workers/api/src/lib/connectors/github.ts:190-209,229-230,
workers/api/src/agent-do-tools.ts:187-217, workers/api/src/lib/agent-capabilities.ts:343,524-541,
workers/api/migrations/0054_coder_github_tools.sql, workers/api/migrations/0070_coder_repo_one_chat.sql,
workers/api/src/lib/coder2-parity.test.ts:131-166, scripts/check-migrations.mjs.
Related: #401 (which shipped the tools), #58 (why the allowlist is authoritative).

[serge-ivo]

Shipped in 1a3955e — migration 0101_coder_github_pull_tools.sql.

The migration number in the issue was already stale. The issue says 0100; by the time this was worked, the concurrent #412 lane had taken 0100_trigger_next_slot.sql (now on main as 9a57fad). This is 0101, assigned up front rather than derived — that is the 0092 collision from #369 not repeating.

Declared lists after 0101 (each a json_set re-setting the full $.capabilities object, one UPDATE per slug, idempotent, guarded with json_valid):

slug	tools
coder-repo (9)	repo_tree, repo_read_file, repo_git, repo_remote, github_list_issues, github_read_issue, github_create_issue, github_list_pulls, github_read_pull
coder-lead (8)	list_subordinates, subordinate_status, delegate_goal, check_delegation, github_list_issues, github_read_issue, github_list_pulls, github_read_pull
coder (5)	github_create_issue, github_list_issues, github_read_issue, github_list_pulls, github_read_pull
repo-chat	untouched — still knowledge-only per 0050, asserted by a test

coder-lead included — the recommendation taken, with the rationale in the migration header and the reversal named (drop the two names from that one statement; the three slugs are deliberately separate statements).

The whole-object re-set was checked for silent drops, twice. 0070 and 0067 set only paths, so the rest of each object comes from the 0063 seed — I re-derived each effective declaration independently of the implementing agent and confirmed the 0101 objects reproduce them exactly (coder-repo also restates surfaceOptions.coding = {repos:"single", drive:false, copilot:false} from 0065+0070, which a whole-object re-set would otherwise drop). I also swept for migrations that write $.capabilities with no slug filter, which a per-slug grep misses: 0091_merge_authority.sql is the only one, and it only reads $.capabilities.surfaces in its WHERE and writes top-level $.settingsSchema, so it is untouched by this.

The stale helper (item 8) is fixed, not left. declared0070() read one migration by name and would have kept passing while describing a superseded state. It is now effectiveDeclared(slug), which walks migrations in filename order and keeps the last statement writing $.capabilities (whole-object) or $.capabilities.tools (path) for that slug, so it self-updates on the next migration. Two new guards added: 0101 must not lose anything 0070 granted, and a whole-object rewrite must not switch the Co-pilot back on by omission.

Verified: pnpm typecheck; pnpm vitest run — 387 files / 6296 tests, 0 failed, after rebasing onto the then-current main; biome --error-on-warnings; check-design-tokens; check-migrations.mjs --require-history (the form ci.yml:63 uses) → ✓ 102 migrations, 101 distinct numbers. Both tools confirmed present in CREATOR_SELECTABLE_TOOLS via registryConnectorGroups(), so toolNamesFor will actually admit them — the inert-tool trap checked rather than assumed. 0054/0065/0067/0070 not edited.

Confirmed in production: the deploy applied it to live D1 — 0101_coder_github_pull_tools.sql │ ✅, 4 commands executed.

Not verified, and I want to be exact about it: the two runtime acceptance criteria. GET /v1/instances/:id/tools reporting allowed: true, and a tool.call for github_list_pulls in agent_trace, both need an authenticated session for the owning account, which I don't hold — capabilities is not exposed on any public endpoint. The migration is applied and capabilitiesForInstance JOINs the agents row at read time (verified in lib/agent-capabilities.ts:524-541), so every subscribed instance should pick it up on its next turn, but somebody signed in should confirm on a Repo Coder instance before this is called done. Leaving the issue open for that.

[serge-ivo]

Runtime acceptance met, in production. Closing.

The migration half was already confirmed. What was left open was the runtime half, correctly — a
migration being applied is not evidence that a model can call a tool. Both criteria are now measured
against live production on a coder-repo instance (bd43f4de-…, repo proappstore-online/chess-academy),
via an authenticated MCP session on the owning account.

1. GET /v1/instances/:id/tools reports allowed: true — VERIFIED

list_instance_tools on that instance, 63 tools returned:

{"name":"github_list_pulls","connector":"github","scope":"read","allowed":true,"disabled":false,"reason":"ok","writeConsent":"n/a"}
{"name":"github_read_pull","connector":"github","scope":"read","allowed":true,"disabled":false,"reason":"ok","writeConsent":"n/a"}

This is the exact measurement in the issue body, inverted: it recorded
"allowed": false, "reason": "not_declared" for github_list_pulls, and the same call now returns
ok. github_workflow_runs still reads not_declared on this agent, which is the control — the
change is scoped to the two names 0101 added, not a blanket widening.

The resolved capabilities.tools on the live instance row confirms capabilitiesForInstance's
read-time JOIN did reach an already-subscribed instance with no instance migration, as predicted:

repo_tree, repo_read_file, repo_git, repo_remote,
github_list_issues, github_read_issue, github_create_issue,
github_list_pulls, github_read_pull        ← 9, was 7

Checked across every instance on the account: all 7 live coder-repo instances carry the 9-tool
list, both coder instances carry 5, coder-lead carries 8. repo-chat is still
search_knowledge, list_knowledge, read_knowledge — untouched, as 0101 promised.

2. A tool.call in agent_trace, not a decline and not a terminal command — VERIFIED

Asked that instance's Assistant: "What pull requests are open on proappstore-online/chess-academy?"

agent_trace, trace 7acacd5d-d121-4edd-a591-fcf5904a097f:

05:20:39  chat  info  chat.in    What pull requests are open on proappstore-online/chess-academy? …
05:20:39  chat  info  tool.call  ✅ **github_list_pulls** []
05:20:39  chat  info  chat.out   No open pull requests on `proappstore-online/chess-academy` right now — the list came back empty.

The empty result is the honest one — that repo has no open PRs — and it is the tool reporting it,
which is what the criterion asks for. No terminal/send_to_cli call in the trace, no decline. The
failure mode this ticket existed to remove ("it will either decline or reach for the terminal") does
not occur.

Not verified

github_read_pull was not exercised end to end — it reports allowed: true, but with no open PR on
the attached repo there was nothing to read, and I was not willing to open one on a production repo
to manufacture a fixture. It shares github_list_pulls's auth path, declaration statement and
scope: "read", so the risk that it is separately broken is low but it is not zero, and I would
rather say so than round it up.

The third acceptance item (a test asserting both names appear in the declared lists) was verified in
the code, not at runtime — effectiveDeclared(slug) in coder2-parity.test.ts.