CODER-008: Super agent (orchestrator chat) missing reliable delegation tool — cannot send tasks to per-repo coding Engines

[serge-ivo]

Problem

The main Coder orchestrator chat ("super agent") is unable to delegate work to per-repo coding Engines. It has read-only tools (read_terminal, get_tasks, get_activity, read_memory, search_knowledge) but the send/delegate tool (send_to_cli / SendMessage) is either missing or inconsistently wired — it was present on Jun 29, gone by Aug 1.

When it can't delegate, it falls into two failure modes:

1. Deflecting — tells the user to go to the Coding tab and paste instructions themselves
2. Hallucinating success — invents fake commit hashes, file paths, test counts, then apologizes

User quote (Aug 1): "Don't you have tools to interact with agents?" — Agent: "I cannot directly send instructions to the coding engine in another session tab."

Root cause

The send_to_cli / SendMessage delegation tool is not reliably included in the orchestrator's tool set. It needs to be a permanent, always-present tool for the orchestrator chat instance.

Fix required

1. Audit why send_to_cli was present Jun 29 but missing Aug 1 — find where the orchestrator's tool list is configured
2. Ensure the delegation tool is always wired to the orchestrator chat (not just the per-repo Engines)
3. Ensure read_terminal reliably returns live data (not empty) so the orchestrator can actually monitor Engine progress
4. Add a guardrail: if the delegation tool is unavailable at startup, surface an error rather than silently falling back to deflection/hallucination

Priority

HIGH — this is the core orchestration capability. Without it the super agent is useless for cross-repo coordination.

[serge-ivo]

Prioritized — fix in progress

Marking this HIGH and taking it on. This is the core cross-repo orchestration capability, so it jumps the CODER-001…007 queue.

Action items (from the report above):

1. Audit the tool wiring — find why send_to_cli / SendMessage was present Jun 29 but gone by Aug 1; locate where the orchestrator chat's tool list is resolved (vs. the per-repo Engines' tool set).
2. Permanently wire delegation to the orchestrator chat — the send/delegate tool must be always-present for the super agent, not only the Engines.
3. Fix read_terminal liveness — it frequently returned (empty) / [unknown], leaving the orchestrator blind; it must reliably return live capture so progress can be monitored.
4. Add a startup guardrail — if the delegation tool is unavailable, surface an explicit error instead of silently degrading to deflection ("go paste it in the Coding tab") or hallucinated success (fake commits/tests).

Acceptance: the orchestrator can send an instruction to a named repo's Engine and confirm receipt + live progress in the same chat, with no fabricated results and no "do it yourself" deflection.

Related: this is the delegation counterpart to the real-time status work in CODER-007 (WebSocket push) — the orchestrator should both drive Engines and observe them over the same reliable channel.

[serge-ivo]

Root cause found + fixed — shipped in 1f2c3b8

Investigated the tool wiring end-to-end. The delegation tools were defined all along (send_to_cli, read_terminal, list_coding_repos in lib/storage-tools.ts, grouped as CODING in agent-do-tools.ts), so this was not a missing-definition problem — it was a resolution + routing problem in three places.

1. The divergence (toolNamesFor, agent-do-tools.ts). The function had an early return: if an instance had a declared capabilities.tools allowlist, it returned BASE + (declared ∩ catalog) and never re-added the CODING group — even for a coding-surface agent. So any Coder instance whose stored capabilities carried a tools array that didn't explicitly list the coding tools silently lost send_to_cli/read_terminal. That's the "present Jun 29, gone Aug 1" behavior — it tracked a capabilities/config change, not a code path that was ever intentional.

• Fix: CODING is now a hard invariant for the coding surface — appended last, after the allowlist logic, so it can never be dropped. A declared allowlist still governs every other tool (a Coder can still opt into KB, etc.).

2. Startup guardrail (buildAgentToolDefinitions). Tool names are only emitted to the model if a backing definition exists; a name enabled without a def is silently dropped. Added a check: for a coding-surface agent, if any CODING tool is enabled but has no definition, throw a clear error at build time ("…missing delegation tool definition(s): … check STORAGE_TOOLS registration") instead of silently handing the model a crippled tool set. This makes the exact CODER-008 regression class fail loudly.

3. read_terminal returning empty (lib/storage-tools.ts). The read_terminal and send_to_cli handlers addressed the relay via relay.idFromName(agentId) — a node-less RelayDO lookup. But runners connect on a node-scoped relay (${instanceId}:node:${node}), so that lookup never matched the live runner → capture returned an empty pane → the orchestrator kept reporting (empty).

• Fix: both handlers now route through getBoundRunnerConn + callRunner — the same live-node path the chat brain (agent-think.ts) already uses (config.runnerNode-aware, relay-verified). read_terminal now labels output [live · <state>] vs [last snapshot — runner offline] (falls back to the saved snapshot, clearly marked) and returns an honest offline error instead of a blank pane — which also removes the "is this live or stale?" ambiguity the agent used to fabricate answers about.

Verification: tsc --noEmit clean; agent-do-tools (15), tool-registry (19), and storage-tools (15) tests all pass. Updated the one test that encoded the old "declared allowlist drops coding tools" behavior to assert the new invariant.

Not yet covered (follow-ups worth tracking): no automated integration test that a live runner actually receives a send_to_cli instruction end-to-end (unit tests mock the runner); and the deeper "orchestrator should refuse to claim success it can't verify" anti-hallucination guardrail is prompt-side, not addressed here.

[serge-ivo]

Shipped & live — closing

Fix landed in 1f2c3b8 on main. CI ✅ and Deploy API Worker ✅ both completed successfully, so the change is live in production.

Recap of what shipped (full detail in the earlier comment):

• toolNamesFor now treats the coding delegation tools (send_to_cli, read_terminal, list_coding_repos) as a hard invariant for the coding surface — never dropped, even under a declared capabilities.tools allowlist. This was the 'present Jun 29, gone Aug 1' divergence.
• buildAgentToolDefinitions now throws a clear error if a coding agent has a delegation tool enabled but no backing definition (no more silent drop).
• read_terminal / send_to_cli route through the live-node getBoundRunnerConn + callRunner path (the same one the chat brain uses) instead of a node-less RelayDO lookup — fixes the empty-terminal reports; read_terminal now labels [live · …] vs [last snapshot — runner offline].

Tests green (agent-do-tools 15, tool-registry 19, storage-tools 15); tsc --noEmit clean.

Open follow-ups noted for later (not blockers): an end-to-end integration test that a live runner actually receives a send_to_cli, and the prompt-side anti-hallucination guardrail.