From fbd9227a606e5daa2758cec903af83a45d4ad0a1 Mon Sep 17 00:00:00 2001 From: roboomp Date: Wed, 1 Jul 2026 05:21:09 +0000 Subject: [PATCH] docs(advisor): described full-agent tool grants and WATCHDOG.yml roster - Rewrote docs/advisor-watchdog.md 'Tools and isolation' to describe the read-only default plus the WATCHDOG.yml tools: grant surface (edit, write, bash, eval, browser, ...), and called out that grants do not bypass the session's approval mode (always-ask / write / yolo). - Added a WATCHDOG.yml section documenting the advisor roster file (fields, legacy tool aliases, discovery locations) with an example that grants a fixer advisor edit + bash. - Reworked the intro (title + first paragraphs) and the trailing peer sentence so they no longer promise a hard read-only observer. - Updated the advisor system prompt to describe using whichever tools this session grants instead of asserting read-only access. - Fixed the AdvisorConfig docstring in advisor/config.ts to match the runtime (any built-in name; default read/grep/glob). Fixes #4044 --- docs/advisor-watchdog.md | 57 ++++++++++++++++--- packages/coding-agent/CHANGELOG.md | 4 ++ packages/coding-agent/src/advisor/config.ts | 6 +- .../src/prompts/advisor/system.md | 2 +- 4 files changed, 57 insertions(+), 12 deletions(-) diff --git a/docs/advisor-watchdog.md b/docs/advisor-watchdog.md index 448646179..40e8f56d8 100644 --- a/docs/advisor-watchdog.md +++ b/docs/advisor-watchdog.md @@ -1,8 +1,8 @@ -# Advisor and WATCHDOG.md +# Advisor, WATCHDOG.md, and WATCHDOG.yml -The advisor is an optional second model attached to a session. It reviews the primary agent's transcript after each turn, can inspect the workspace with read-only tools, and injects concise advice back into the primary session. +The advisor is an optional second model attached to a session. It reviews the primary agent's transcript after each turn, inspects the workspace with its own tools, and injects concise advice back into the primary session. -The advisor is not a second executor. It cannot edit files, run commands, approve actions, or change session state directly. +The advisor is not a second executor: it cannot approve actions or change primary session state directly, and its tool calls flow through the session's normal approval policy. Its default toolset is read-only (`read`, `grep`, `glob`) plus `advise`, but a `WATCHDOG.yml` roster entry may broaden `tools:` to any built-in — including mutating tools such as `edit`, `write`, `bash`, `eval`, and `browser` — subject to the same approval mode as the primary agent (see [Tools and isolation](#tools-and-isolation)). ## Implementation files @@ -72,14 +72,17 @@ When the advisor is enabled mid-session, the cursor seeds to the current primary ## Tools and isolation -The advisor receives a hard-isolated read-only tool set: +The advisor is a full agent with its own `Agent` instance and a distinct `ToolSession` whose id is suffixed `-advisor`. The advisor therefore does not share the primary agent's file snapshots, seen-lines tracking, conflict state, summary cache, or edit/yield capabilities. + +Every advisor has the `advise` tool for surfacing notes into the primary transcript. Its investigative pool defaults to the read-only subset: - `read` -- `search` -- `find` -- `advise` +- `grep` +- `glob` -The read/search/find tools are built against a distinct `ToolSession` whose session id is suffixed with `-advisor`. The advisor therefore does not share the primary agent's file snapshots, seen-lines tracking, conflict state, summary cache, or edit/yield capabilities. +A `WATCHDOG.yml` roster entry may broaden this with `tools: [...]`, selecting any subset of the built-in pool the session actually built (a factory that returned `null`, e.g. `lsp` with no matching servers, is absent). Grantable tools include mutating ones: `edit`, `write`, `bash`, `eval`, `browser`, `debug`, `ast_edit`, `task`, `job`, and the memory tools. Tool names outside [`BUILTIN_TOOL_NAMES`](../packages/coding-agent/src/tools/builtin-names.ts) are dropped with a warning. + +Grants do not bypass approval policy. Write- and exec-tier tools still run through the session's approval mode (`always-ask`, `write`, `yolo`) and any `tools.approval.` overrides exactly like the primary — the `-advisor` `ToolSession` is a separate state namespace, not a separate policy. In `always-ask` and `write` modes an advisor-initiated exec/write therefore still prompts the user; in `yolo` (or under a per-tool `allow` override) it runs without prompting, so grant mutating tools deliberately. The `advise` tool accepts one note and an optional severity: @@ -201,6 +204,42 @@ Especially pay attention to: Later project files sit closer to the end of the advisor prompt, so narrower directory guidance is more prominent than broad ancestor guidance. +## WATCHDOG.yml + +`WATCHDOG.yml` (or `WATCHDOG.yaml`) is the advisor roster. Where `WATCHDOG.md` supplies review priorities, `WATCHDOG.yml` declares the advisors themselves — one entry per name, each with its own model, tool grant, and specialization prompt. The `/advisor configure` overlay edits this file in place. Files that fail to parse or fail schema validation are logged and skipped so one bad project config cannot kill the session. + +Example: + +```yaml +instructions: | + Everyone: prefer diffs that keep tests unified. + +advisors: + - name: Architecture + model: anthropic/claude-sonnet-4-5:medium + tools: [read, grep, glob] + instructions: | + Watch cross-module coupling and public-API growth. + + - name: Fixer + model: anthropic/claude-sonnet-4-5:high + tools: [read, grep, glob, edit, bash] + instructions: | + You may edit and run tests to prove a fix locally, then advise. +``` + +Fields: + +- `instructions` (top level): shared prompt prepended to every advisor's system prompt alongside `WATCHDOG.md`. Concatenated across all discovered `WATCHDOG.yml` files. +- `advisors[].name`: human label; slugified for the session id and the `/__advisor.jsonl` filename. Duplicate slugs across files are resolved by the same specificity rule as `WATCHDOG.md` discovery (project leaf > project ancestor > user). +- `advisors[].model`: optional model selector with optional `:level` thinking suffix (e.g. `x-ai/grok-code-fast:high`). Omitted → the advisor uses `modelRoles.advisor`. +- `advisors[].tools`: optional list of built-in tool names to grant. Omitted or empty → the default `read`/`grep`/`glob` subset. Any name in [`BUILTIN_TOOL_NAMES`](../packages/coding-agent/src/tools/builtin-names.ts) is accepted, including mutating tools (`edit`, `write`, `bash`, `eval`, `browser`, `debug`, `ast_edit`, `task`, `job`, and the memory tools). Legacy aliases (`search`→`grep`, `find`→`glob`) are normalized. Unknown names are dropped with a warning. See [Tools and isolation](#tools-and-isolation) for the approval-policy implications of granting mutating tools. +- `advisors[].instructions`: this advisor's specialization, appended after the shared baseline. Both instruction fields expand `@path` imports like `WATCHDOG.md`. + +### Discovery locations + +`WATCHDOG.yml`/`WATCHDOG.yaml` share the same user + project search path as `WATCHDOG.md`: the user-level `/WATCHDOG.yml` plus every `WATCHDOG.yml`/`.omp/WATCHDOG.yml` encountered while walking from `cwd` up to the repository root (or the home directory when no repo root is found). All discovered files are loaded together; a more-specific file (project leaf > project ancestor > user) replaces an earlier entry with the same advisor slug. + ## Subagents `advisor.subagents` controls whether spawned task/eval subagents also get an advisor runtime. @@ -238,4 +277,4 @@ Why a file: The file follows session switches: on `/new`, resume/switch, and branch the recorder reopens at the new session's path on the next advisor turn; before a `/drop` deletes the old artifacts dir the recorder feed is detached and drained so a queued write cannot recreate the deleted file. The on-disk log is append-only and independent of the in-memory context — re-primes and compaction never truncate it. -The advisor is never a peer. The `advisor`-kind registry ref is excluded from every agent-facing surface — the `irc` peer roster and broadcast targets, the subagent peer prompt, and the `history://` index/lookup/completions — and cannot be messaged (`irc send` and collab chat refuse it) or revived/killed from the Agent Hub or collab. It is observability only. +The advisor is never a peer. The `advisor`-kind registry ref is excluded from every agent-facing surface — the `irc` peer roster and broadcast targets, the subagent peer prompt, and the `history://` index/lookup/completions — and cannot be messaged (`irc send` and collab chat refuse it) or revived/killed from the Agent Hub or collab. It is not addressable as a peer, regardless of what tools it has been granted. diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md index d1722f2ec..aa1257790 100644 --- a/packages/coding-agent/CHANGELOG.md +++ b/packages/coding-agent/CHANGELOG.md @@ -2,6 +2,10 @@ ## [Unreleased] +### Fixed + +- Fixed the advisor docs and system prompt still describing a hard read-only observer after `WATCHDOG.yml` `tools:` grants were opened to every built-in tool (including `edit`, `write`, `bash`, `eval`, `browser`). `docs/advisor-watchdog.md` now documents the `WATCHDOG.yml` roster format, the default `read`/`grep`/`glob` grant, and the approval-mode implications of broadening the grant; the advisor system prompt no longer asserts read-only access. ([#4044](https://github.com/can1357/oh-my-pi/issues/4044)) + ## [16.2.12] - 2026-07-01 ### Breaking Changes diff --git a/packages/coding-agent/src/advisor/config.ts b/packages/coding-agent/src/advisor/config.ts index 81377eb69..0ee5bbe8d 100644 --- a/packages/coding-agent/src/advisor/config.ts +++ b/packages/coding-agent/src/advisor/config.ts @@ -10,8 +10,10 @@ import { collectConfigCandidates } from "./watchdog"; /** * One advisor declared in a `WATCHDOG.yml` file. `model` is a model selector * with an optional `:level` thinking suffix (e.g. `x-ai/grok-code-fast:high`), - * resolved exactly like any other model override; `tools` is a subset of the - * read-only investigative tool names (default: all). `instructions` is the + * resolved exactly like any other model override; `tools` is a subset of + * `BUILTIN_TOOL_NAMES` — any built-in name, including mutating tools such as + * `edit`/`write`/`bash` (the advisor is a full agent). Omitted or empty falls + * back to the default `read`/`grep`/`glob` subset. `instructions` is the * advisor's specialization, appended to the shared baseline. */ export interface AdvisorConfig { diff --git a/packages/coding-agent/src/prompts/advisor/system.md b/packages/coding-agent/src/prompts/advisor/system.md index f0f848df7..981aada05 100644 --- a/packages/coding-agent/src/prompts/advisor/system.md +++ b/packages/coding-agent/src/prompts/advisor/system.md @@ -14,7 +14,7 @@ Offer that view before they sink work into the wrong direction. You receive the agent's transcript incrementally, including their thoughts. -You have read-only access through `read`, `grep`, `glob` to verify your suspicions. +Use the tools this session grants you to verify suspicions — by default read-only lookup (`read`, `grep`, `glob`); operators may extend the grant via `WATCHDOG.yml`. Advising is your primary channel; touch mutating tools (when granted) only when a verify step genuinely needs them. Keep exploration lean: - 2–3 tool calls per advise. - Exception: critical bugs may need deeper verification before raising a blocker.