@dreb/coding-agent 2.48.0 → 2.50.0

package/docs/dashboard.md

@@ -120,7 +120,7 @@ networking window above.
 | Screen | What it does |
 |---|---|
 | **Fleet** | Home. Live-first: one grid of every live session at the top — status chip (● running / ◆ needs-attention / ○ idle / ✕ error), project path, activity line, live subagent lines, tasks progress, ctx%, model, terminal provider-error reason, last activity. Live cards keep a deterministic order by project path, then session start time; needs-attention cards badge the browser tab without jumping around. Below the grid: past sessions grouped by project, three compact rows per group with an "all N on disk" expander, resume and delete. |
-| **Session view** | Full chat drill-in. Markdown streaming transcript (text, thinking blocks with expand preference, inline provider/API failures with partial output preserved, agent-result cards, tool cards with bespoke read/write/edit/bash bodies plus full expandable inputs, markdown-rendered results for markdown-contract tools like subagent/skill/web_fetch/suggest_next, and inline tool-result images, compaction/branch summaries, custom messages), per-message copy, tasks panel, subagent strip, status line with elapsed time plus ■ stop and compaction/retry aborts, a persistent session-header live indicator, and an info bar with cwd, branch, session name, token breakdown, cost/(sub)/daily rollup, ctx%, median tok/s, and a stats popover. Composer supports auto-grow, history, `/` autocomplete from `get_commands`, image attach/paste with sent images retained as user-message previews, queued-message chips with restore-all, steer/follow-up modes, and suggest-next. The ⋯ menu covers export HTML, compact, rename, fork-from-message, loaded context, and tool expand/collapse. Session names update live from manual rename or auto-naming. Extension UI requests for select/confirm/input/editor render as modals; rich `ask`/`ask_user` questions render inline with Markdown-formatted question text, choices, optional free text, an in-card Stop agent action, Escape-to-stop, and the authoritative auto-stop countdown. Pending questions set needs-attention state and use the existing hidden-page notification path. Extension notifications render as toasts. |
+| **Session view** | Full chat drill-in. Markdown streaming transcript (text, thinking blocks with expand preference, inline provider/API failures with partial output preserved, agent-result cards, tool cards with bespoke read/write/edit/bash bodies plus full expandable inputs, markdown-rendered results for markdown-contract tools like subagent/skill/web_fetch/suggest_next, and inline tool-result images, compaction/branch summaries, custom messages), per-message copy, tasks panel, a bounded scrollable subagent panel that lists every retained agent newest-first with full running/done counts, status line with elapsed time plus ■ stop and compaction/retry aborts, a persistent session-header live indicator, and an info bar with cwd, branch, session name, token breakdown, cost/(sub)/daily rollup, ctx%, median tok/s, and a stats popover. Composer supports auto-grow, history, `/` autocomplete from `get_commands`, image attach/paste with sent images retained as user-message previews, queued-message chips with restore-all, steer/follow-up modes, and suggest-next. The ⋯ menu covers export HTML, compact, rename, fork-from-message, loaded context, and tool expand/collapse. Session names update live from manual rename or auto-naming. Extension UI requests for select/confirm/input/editor render as modals; rich `ask`/`ask_user` questions render inline with Markdown-formatted question text, choices, optional free text, an in-card Stop agent action, Escape-to-stop, and the authoritative auto-stop countdown. Pending questions set needs-attention state and use the existing hidden-page notification path. Extension notifications render as toasts. |
 | **Subagent view** | Read-only transcript of a background agent: live events via the RPC relay, hydrated from the agent's on-disk session log (`/subagents/:agentId/messages`) so the transcript survives browser reloads. Shows the task, streaming output, tool activity, and any safe Dispatch Arbiter changed/unchanged/failure records with the final agent/model/thinking. No raw arbiter output is displayed or transported. No composer — subagents can't be steered yet; the parent session controls them. |
 | **Files** | Host-wide browser with places shortcuts (home, /tmp, project roots), breadcrumbs to `/`, new-folder, download, drop-zone/picker upload with explicit collision prompts, and "new session here" on any directory. It also shows the **effective global nested-context trust** for the displayed canonical directory: untrusted, trusted by that root, inherited from a granting root, or global expert trust-all. You can trust the displayed folder and descendants, or untrust the actual granting root; untrusting an inherited folder removes that root's trust for all descendants. |
 | **Settings** | Persistent defaults (default model, thinking level, steering/follow-up queue modes, auto-compaction, auto-retry) via `get_settings`/`set_settings` — validation errors are shown verbatim. The global-only Dispatch Arbiter card exposes enable/disable, exact authenticated model selection, thinking, guide path, and readiness guidance; model-less enablement is blocked and RPC/runtime validation remains fail-closed. Entering Settings flushes pending writes and reloads durable global + project settings, so external edits appear; read, parse, or write failures fail loudly instead of showing stale settings. The global-only nested-context policy lists every explicit trusted root for audit and revoke, offers a simple add-by-path control, and includes a prominently warned expert trust-all toggle; the Files view remains the primary place to grant trust while browsing. Most defaults seed new sessions; context-trust changes are observed by active main/subagent processes for future lazy loads, but cannot remove already injected content. Dashboard-local preferences (always expand thinking, transcript image display mode, needs-attention notification permission) live in the browser, alongside an appearance section: a theme gallery of eight curated themes (entropist.ca, Dim, Solarized, Gruvbox, Caves of Qud, Van Gogh, and the colorblind-safe Okabe-Ito and Paul Tol) with live preview cards and a system/light/dark mode selector, saved per browser. Shows the current rotating pairing code on the host/local dashboard, plus the paired-devices list with unpair. |
@@ -128,7 +128,7 @@ networking window above.
 
 ### Dispatch Arbiter observability
 
-When the global Dispatch Arbiter is enabled, the dashboard consumes the typed `subagent_arbitration` RPC event. The matching background-agent card is updated to the final selected agent before child events arrive; the parent chip shows final model/thinking or a failure marker, and the subagent drill-in lists ordered records (including chain steps). Runtime snapshots carry the same safe records so refresh/resync during a live process does not revert to the requested identity.
+When the global Dispatch Arbiter is enabled, the dashboard consumes the typed `subagent_arbitration` RPC event. The matching background-agent card is updated to the final selected agent before child events arrive; the parent panel row shows final model/thinking or a failure marker, and the subagent drill-in lists ordered records (including chain steps). Runtime snapshots carry the same safe records so refresh/resync during a live process does not revert to the requested identity.
 
 Only host-validated proposed/final tuples, changed fields, status, step, and bounded host errors cross RPC/SSE. Arbiter prompts, raw output, reasoning, tasks, guides, and parent excerpts never reach dashboard protocol state. The safe record is separately persisted in the parent session as a non-context custom entry; child transcript hydration remains sourced from the child log.
 
@@ -374,8 +374,10 @@ Then open `https://hostname.tailXXXX.ts.net:<port>` on the phone.
 Background subagents are first-class:
 
 - Fleet cards show running/done counts and live agent lines.
-- The session view shows a chip strip — one chip per background agent; click
-  to drill into its live transcript.
+- The session view shows every retained background agent in a bounded,
+  scrollable panel, ordered newest-first with the full running/done count in its
+  summary. It uses the same native collapse pattern as the task tracker, starts
+  collapsed on mobile, and keeps every row available for transcript drill-in.
 - The drill-in view streams the child's events in real time via the
   `background_agent_event` relay (see [RPC events](rpc.md#event-types)) and
   hydrates from the agent's on-disk session log on mount, so transcripts
@@ -387,7 +389,8 @@ Single breakpoint at 700px. At <=700px, fleet cards stack; long session names,
 status chips, project paths, activity and subagent text, and past-session
 labels wrap within their cards or rows rather than spilling off-screen. The
 session view prioritizes read-and-steer (model/thinking switchers collapse into
-⋯, tasks default collapsed), and the file table shows name + download only.
+⋯, and task/subagent panels default collapsed), and the file table shows name +
+download only.
 Composer modes, abort, and needs-attention affordances are never reduced away
 — steering a running agent from a phone is the primary remote use case.
 

package/docs/extensions.md

@@ -613,7 +613,7 @@ In the default parallel tool execution mode, sibling tool calls from the same as
 import { isToolCallEventType } from "@dreb/coding-agent";
 
 dreb.on("tool_call", async (event, ctx) => {
-  // event.toolName - "bash", "read", "write", "edit", "grep", "find", "ls", "web_search", "web_fetch", "subagent", "wait", "search", "ask_user", "skill", "tasks_update", "suggest_next", or custom tool names
+  // event.toolName - "bash", "read", "write", "edit", "grep", "find", "ls", "web_search", "web_fetch", "subagent", "wait", "watch_github_ci", "search", "ask_user", "skill", "tasks_update", "suggest_next", or custom tool names
   // event.toolCallId
   // event.input - tool parameters
 
@@ -1518,7 +1518,7 @@ async execute(toolCallId, params) {
 
 ### Overriding Built-in Tools
 
-Extensions can override built-in tools (`read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`, `web_search`, `web_fetch`, `subagent`, `wait`, `search`, `ask_user`) by registering a tool with the same name. Interactive mode displays a warning when this happens. The factory-only tools (`skill`, `tasks_update`, `suggest_next`) can also be overridden.
+Extensions can override built-in tools (`read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`, `web_search`, `web_fetch`, `subagent`, `wait`, `watch_github_ci`, `search`, `ask_user`) by registering a tool with the same name. Interactive mode displays a warning when this happens. The factory-only tools (`skill`, `tasks_update`, `suggest_next`) can also be overridden.
 
 ```bash
 # Extension's read tool replaces built-in read
@@ -1549,6 +1549,8 @@ Built-in tool implementations:
 - [ls.ts](https://github.com/aebrer/dreb/blob/master/packages/coding-agent/src/core/tools/ls.ts) - `LsToolDetails`
 - [web.ts](https://github.com/aebrer/dreb/blob/master/packages/coding-agent/src/core/tools/web.ts) - `web_search` and `web_fetch`
 - [subagent.ts](https://github.com/aebrer/dreb/blob/master/packages/coding-agent/src/core/tools/subagent.ts)
+- [wait.ts](https://github.com/aebrer/dreb/blob/master/packages/coding-agent/src/core/tools/wait.ts)
+- [watch-github-ci.ts](https://github.com/aebrer/dreb/blob/master/packages/coding-agent/src/core/tools/watch-github-ci.ts) - `watch_github_ci`
 - [skill.ts](https://github.com/aebrer/dreb/blob/master/packages/coding-agent/src/core/tools/skill.ts) - factory-only
 - [tasks.ts](https://github.com/aebrer/dreb/blob/master/packages/coding-agent/src/core/tools/tasks.ts) - factory-only
 

package/docs/mach6.md

@@ -30,7 +30,7 @@ Assess an existing GitHub issue or create a new one.
 /skill:mach6-issue add dark mode   # Create issue from description
 ```
 
-**Assess mode:** Launches parallel subagents to explore the codebase, then posts a structured assessment (summary, gaps, ambiguities, scope, risks) as an issue comment.
+**Assess mode:** Launches parallel Explore agents to retrieve bounded code/documentation evidence, then has the primary agent synthesize and post the assessment (summary, gaps, ambiguities, scope, risks) as an issue comment.
 
 **Create mode:** Drafts a structured issue with title, summary, acceptance criteria, and technical notes.
 
@@ -44,7 +44,7 @@ Explore the codebase, create an implementation plan, open a draft PR, and post t
 
 - Reads the issue and any existing assessment
 - Checks project conventions (AGENTS.md, CONTRIBUTING.md, etc.)
-- Launches parallel subagents to explore similar features, architecture, and integration points
+- Launches parallel Explore agents to locate related implementations, enumerate explicit flows/call sites, and quote bounded evidence; the primary agent owns architecture and planning
 - Creates a feature branch (`feature/issue-42-<slug>`) with an empty commit
 - Opens a draft PR linking to the issue
 - Posts the plan as a PR comment with `<!-- mach6-plan -->` marker
@@ -112,7 +112,7 @@ Pre-merge checks, version bump, docs update, merge, tag, and release.
 /skill:mach6-publish 53
 ```
 
-- Verifies CI passing, no merge conflicts, all findings addressed
+- Verifies CI passing with the blocking `watch_github_ci` tool (never `wait` or a polling loop), no merge conflicts, and all findings addressed
 - Runs pre-merge checklist (version bump, tests)
 - Applies version bump on the feature branch
 - Proactively reviews and updates ALL documentation affected by the PR's changes

package/docs/rpc.md

@@ -1112,7 +1112,7 @@ Response:
       },
       {
         "name": "Explore",
-        "description": "Codebase and web exploration — find files, search code, search the web, answer questions. Read-only."
+        "description": "Concrete evidence retrieval — locate files, symbols, documentation, call sites, and exact snippets. No implementation work."
       }
     ]
   }

package/docs/sdk.md

@@ -387,10 +387,10 @@ const { session } = await createAgentSession({ resourceLoader: loader });
 
 ```typescript
 import {
-  codingTools,   // read, bash, edit, write (subset — default is all 11)
+  codingTools,   // read, bash, edit, write (subset — default is all 13 standard tools)
   readOnlyTools, // read, grep, find, ls
   readTool, bashTool, editTool, writeTool,
-  grepTool, findTool, lsTool,
+  grepTool, findTool, lsTool, watchGithubCiTool,
 } from "@dreb/coding-agent";
 
 // Use built-in tool set
@@ -953,13 +953,13 @@ SettingsManager
 codingTools
 readOnlyTools
 readTool, bashTool, editTool, writeTool
-grepTool, findTool, lsTool
+grepTool, findTool, lsTool, watchGithubCiTool
 
 // Tool factories (for custom cwd)
 createCodingTools
 createReadOnlyTools
 createReadTool, createBashTool, createEditTool, createWriteTool
-createGrepTool, createFindTool, createLsTool
+createGrepTool, createFindTool, createLsTool, createWatchGithubCiTool
 
 // Types
 type CreateAgentSessionOptions

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@dreb/coding-agent",
-	"version": "2.48.0",
+	"version": "2.50.0",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"type": "module",
 	"drebConfig": {

package/skills/mach6-implement/SKILL.md

@@ -133,13 +133,14 @@ tasks_update([
 
 #### If `ci` was specified:
 
+Use `watch_github_ci` with `pr: "<pr-number>"` so the tool blocks until the pull request's checks pass or fail. Do not use `wait`, sleep, or repeated polling commands for CI.
+
+If checks fail, use the returned check output to identify the failed run, then inspect it:
+
 ```bash
-gh pr checks <pr-number>
 gh run view <run-id> --log-failed
 ```
 
-**Note:** `gh pr checks` returns exit code 8 while checks are still pending — this is expected, not a failure. Wait and re-run if needed.
-
 Read the failed CI logs and identify issues. Extract test failures, stack traces, error messages. If all checks pass, report this and stop.
 
 #### If finding numbers were specified:

package/skills/mach6-issue/SKILL.md

@@ -52,12 +52,12 @@ Update task: read → completed, explore → in_progress.
 
 ### Step 3: Explore the codebase
 
-Launch 2-3 Explore subagents in parallel targeting different aspects. Agent definitions specify their own model with a provider fallback list — defaults work across providers and are fine for most cases. Override only with good reason (e.g. a particularly complex issue warrants a stronger tier).
-- **Relevant code**: Find existing code related to the issue, trace implementation patterns
-- **Architecture**: Map relevant architecture layers, abstractions, data flow
-- **Prior work**: Check for related branches, PRs, or commits
+Launch 2-3 Explore subagents in parallel for concrete evidence retrieval. Agent definitions specify their own model with a provider fallback list — defaults work across providers and are fine for most cases. Override only with good reason (e.g. a large repository requires inspecting many files).
+- **Relevant code evidence**: Locate named related behavior and quote the exact implementation and test snippets
+- **Flow inventory**: Enumerate files, symbols, imports, calls, and registrations in an explicitly named existing flow without diagnosing it
+- **Prior-work evidence**: Locate related branches, PRs, commits, and documentation and report their exact references
 
-Each agent should return 5-10 key files. After agents complete, read all identified files.
+Do not ask Explore to determine the root cause, interpret ambiguous requirements, recommend an implementation, decide architecture, or assess the issue. Each agent should return 5-10 key files with bounded evidence. After agents complete, read all identified files and have the primary agent synthesize the current state, gaps, scope, and risks.
 
 Update task: explore → completed, assess → in_progress.
 
@@ -109,7 +109,7 @@ ls .github/ISSUE_TEMPLATE/ 2>/dev/null
 ```
 If templates exist, read them and select the most appropriate one.
 
-Explore the codebase if needed to understand the relevant area.
+If codebase context is needed, use Explore subagents only for bounded evidence such as locating named behavior, files, tests, call sites, or exact snippets. The primary agent must interpret that evidence and own the issue's requirements, proposed behavior, scope, and technical conclusions.
 
 ### Step 2: Draft the issue
 

package/skills/mach6-plan/SKILL.md

@@ -53,12 +53,12 @@ Extract planning-relevant guidance: project layers, testing expectations, coding
 
 ## Step 4: Explore the codebase
 
-Launch 2-3 Explore subagents in parallel. Agent definitions specify their own model with a provider fallback list — defaults work across providers and are fine for most cases. Override only with good reason (e.g. a particularly large or complex codebase warrants a stronger tier).
-- **Similar features**: Find existing code that solves related problems, trace implementation patterns
-- **Architecture**: Map relevant architecture layers, abstractions, data flow
-- **Integration points**: Identify where new code connects to existing systems
+Launch 2-3 Explore subagents in parallel for concrete evidence retrieval. Agent definitions specify their own model with a provider fallback list — defaults work across providers and are fine for most cases. Override only with good reason (e.g. a particularly large codebase requires inspecting many files).
+- **Existing feature evidence**: Locate named related features and quote the exact implementation and test snippets that establish their patterns
+- **Layer inventory**: Enumerate the files, symbols, imports, and calls in an explicitly named existing data flow without deciding the architecture
+- **Integration evidence**: Enumerate concrete call sites, registrations, configuration, and documentation for the relevant symbols
 
-Include project conventions in each agent's context. Each agent returns 5-10 key files. Read all identified files.
+Do not ask Explore to diagnose the problem, interpret ambiguous requirements, recommend an implementation, design the architecture, or produce the plan. Include project conventions in each agent's context. Each agent returns 5-10 key files with bounded evidence. Read all identified files, then have the primary agent synthesize the architecture, risks, and implementation plan.
 
 Update task: explore → completed, plan → in_progress.
 

package/skills/mach6-publish/SKILL.md

@@ -34,10 +34,9 @@ tasks_update([
 gh pr checkout <pr-number>
 git pull
 gh pr view <pr-number> --json mergeable,mergeStateStatus,statusCheckRollup,reviewDecision,comments,body
-gh pr checks <pr-number>
 ```
 
-**Note:** `gh pr checks` returns exit code 8 while checks are still pending — this is expected, not a failure. Wait and re-run if needed.
+Use `watch_github_ci` with `pr: "<pr-number>"` to block until CI passes or fails. Do not use `wait`, sleep, or repeated polling commands for CI.
 
 Read ALL PR comments to understand the full history — plans, reviews, assessments, progress updates, and discussion.
 
@@ -90,7 +89,7 @@ Update task: checks → completed, version → in_progress.
    git push
    ```
 
-5. Wait for CI to pass on the version bump commit before proceeding to merge.
+5. Use `watch_github_ci` with `pr: "<pr-number>"` and proceed only after it reports that CI passed on the version bump commit.
 
 If the project doesn't use versioning, skip this step.
 
@@ -127,7 +126,7 @@ Proactively review and update ALL documentation affected by the PR's changes. Th
    git push
    ```
 
-5. Wait for CI to pass on the docs commit.
+5. Use `watch_github_ci` with `pr: "<pr-number>"` and proceed only after it reports that CI passed on the docs commit.
 
 If no documentation changes are needed (rare), skip this step.