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

@@ -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.<tool>` 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 `<session>/__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 `<active agent dir>/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.

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

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 {

packages/coding-agent/src/prompts/advisor/system.md

@@ -14,7 +14,7 @@ Offer that view before they sink work into the wrong direction.
 
 <workflow>
 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.