claude-dev-env 8.1.0 → 8.3.0

package/.agents/skills/orchestrator/reference/consult-the-orchestrator.md

@@ -21,7 +21,7 @@ The first consult is complete. It carries:
 - Assignment and desired outcome
 - Constraints and exclusions
 - Actions taken in order
-- Real output and current state
+- Output and current state
 - Live decision or blocker
 - Validation evidence
 - Unresolved risks

package/.agents/skills/orchestrator/reference/executor-consult-block.md

@@ -31,7 +31,7 @@ Fill `<orchestrator-name>` with the name the executor can address.
 > failure repeats or progress has stalled, and when the chosen approach
 > is being reconsidered.
 > The first consult carries: assignment, desired outcome, constraints
-> and exclusions, actions taken in order, real output and current
+> and exclusions, actions taken in order, output and current
 > state, live decision or blocker, validation evidence, unresolved
 > risks, load-bearing paths or excerpts, and who is asking. Later
 > consults carry only changed evidence.

package/.agents/skills/orchestrator-refresh/SKILL.md

@@ -70,7 +70,7 @@ reports and adds nothing further.
    executor has no `in_progress` task naming it as owner; a finished
    executor's task is still open (or was closed without its result
    merged); the next phase you will dispatch has no pending task; a
-   `blockedBy` link contradicts the actual run order. Fix every mismatch
+   `blockedBy` link contradicts the run order. Fix every mismatch
    with TaskCreate / TaskUpdate in this same firing — never defer.
 2. **You are the orchestrator.** Orchestrate and hold the user
    conversation; spawn executor subagents for every code edit and build
@@ -79,6 +79,8 @@ reports and adds nothing further.
      Claude host, or the resolver-printed sonnet-equivalent id on a
      third-party host, and fails closed — see Workflow Agent Routing in
      [`skills/orchestrator/SKILL.md`](../orchestrator/SKILL.md#workflow-agent-routing).
+     Advisor spawns use `flags: ["--advisor"]` only when they intentionally
+     select Astra.
    - **Focused tickets.** One mechanical done-check per ticket; resume a
      warm agent with a thin next-slice ticket rather than a fresh cold
      spawn, and keep thick context in the assignment file.
@@ -89,7 +91,7 @@ reports and adds nothing further.
    to orchestration and light verification reads.
 4. **Resume before you spawn.** `SendMessage` an existing *executor* by
    name or `agentId` before a cold spawn.
-5. **Fresh spawn only for a genuine task switch.** Never tell an agent
+5. **Fresh spawn only for a task switch.** Never tell an agent
    to compact for a clean context.
 6. **Single-pending re-arm only.** Same protocol as the orchestrator
    skill (host-agnostic; **create then claim**):

package/.agents/skills/plugin-eval-standalone-skill/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: plugin-eval-standalone-skill
+description: >-
+  Run `claude plugin eval` against a standalone skill that is not a plugin, by wrapping the skill in a plugin folder, writing trigger and must-not-trigger cases, and reading the with-skill minus without-skill delta. Triggers: eval a skill, plugin eval, claude plugin eval, test my skill, skill eval, eval a standalone skill.
+---
+
+# Plugin eval for a standalone skill
+
+## Contents
+
+- Principle
+- Gotchas
+- When this applies
+- Process
+- Files
+
+## Principle
+
+`claude plugin eval` runs plugins only. Wrap the skill in a plugin folder whose layout keeps every
+relative link working. Grade behavior only the skill produces. Judge the skill by the delta between
+the arm with the plugin and the arm without it.
+
+## Gotchas
+
+- A `.claude-plugin/plugin.json` under any skills directory turns that folder into a
+  `<name>@skills-dir` plugin in every session. Build the wrapper outside every skills directory.
+- The run sandbox gets a throwaway home and config. User settings, hooks, CLAUDE.md, MCP servers,
+  memory, and other skills are absent. Plugin items carry a prefix, such as `<plugin>:session-advisor`.
+- `claude plugin eval init` with no arguments is interactive and needs a terminal. From an agent
+  shell, run `claude plugin eval init --bare <case-name>`.
+- A prompt that starts with `/skill-name` loads the skill with no `Skill` tool call, so
+  `tool_used: Skill` always fails on a slash case.
+- A plain-words case triggers only when the skill allows model invocation. Leave
+  `disable-model-invocation` unset in the copied frontmatter.
+- Write, Edit, SendMessage, and Bash need `--allow-tools` on the command line. Bash and PowerShell
+  grants refuse the run on native Windows, which has no sandbox backend. Run those cases under WSL2.
+- Writes under a loaded `--plugin-dir` are denied in dontAsk mode. That skews the with-plugin arm
+  only, so keep every working and output folder outside the plugin root.
+- A metric built from tool_use attempts reports success even when every write was denied. Read each
+  run's `permission_denials` and final result before you compare arms.
+- A score under `--ablation none` says nothing about what the skill adds. Run the baseline once
+  before you claim the skill helps.
+- The sandbox disables feature-flag fetching. Flag-gated features such as the built-in `advisor()`
+  tool are off, and `/advisor` replies "isn't available in this environment". No env var or plugin
+  setting turns them on. Plugin `settings.json` accepts only `agent` and `subagentStatusLine`. Test
+  such a feature with the `claude -p` recipe in `reference/graders-and-commands.md`.
+- `--keep-temp` on Windows warns that it cannot seal the folder. Delete that folder when done with
+  PowerShell `Remove-Item -Recurse -Force -LiteralPath <path>`.
+
+## When this applies
+
+Use this skill to measure whether a skill that is not packaged as a plugin triggers and changes
+behavior. It needs Claude Code 2.1.269 or later. Source doc: https://code.claude.com/docs/en/plugin-evals
+
+## Process
+
+Register one session task per numbered step through the host task tool. Use `TaskCreate`, else
+`TodoWrite`. Where the host has no task tool, say so and work the steps in order.
+
+1. Run `claude --version` and confirm 2.1.269 or later.
+2. Create the wrapper folder outside every skills directory:
+
+   ```text
+   <wrapper>/
+   ├── .claude-plugin/
+   │   └── plugin.json
+   ├── skills/
+   │   └── <name>/
+   ├── agents/
+   └── <each shared doc, at the path the skill's relative links expect>
+   ```
+
+   `plugin.json` holds `name`, `version`, and `description`.
+3. Copy the skill, every agent it spawns, and every shared doc it links. Copy from a tree at
+   `origin/main`, not from a stale worktree. Resolve each relative link in the copied skill against
+   the wrapper root.
+4. In the wrapper root, run `claude plugin eval init --bare <case-name>` once per case.
+5. Write `evals/<case>/prompt.md` and `evals/<case>/graders/*.md` for each case. Frontmatter keys,
+   grader types, and the case set are in `reference/graders-and-commands.md`.
+6. Re-copy the skill from `origin/main`, then run the smoke command from the reference file.
+7. Read each run's `permission_denials` and final result. Fix any denial that the case needs.
+8. Re-copy the skill, then run the full eval. Read the delta in `aggregate-result.json`.
+9. Delete any `--keep-temp` sandbox folder.
+
+## Files
+
+- `SKILL.md`. Wrapper layout, gotchas, and process.
+- `reference/graders-and-commands.md`. Prompt frontmatter, grader types, case set, eval commands,
+  and the `claude -p` recipe for flag-gated features.
+
+```text
+plugin-eval-standalone-skill/
+├── SKILL.md
+└── reference/
+    └── graders-and-commands.md
+```

package/.agents/skills/plugin-eval-standalone-skill/reference/graders-and-commands.md

@@ -0,0 +1,108 @@
+# Graders and commands
+
+## Contents
+
+- Prompt frontmatter
+- Grader types
+- Case set
+- Eval commands
+- Results
+- Flag-gated features outside plugin eval
+
+## Prompt frontmatter
+
+`evals/<case>/prompt.md` takes these frontmatter keys.
+
+| Key | Use |
+| --- | --- |
+| `max_turns` | Default 10. Set about 40 for a skill that spawns agents. |
+| `timeout_seconds` | Wall-clock cap for one run. |
+| `allowed_tools` | Read-only set: Read, Glob, Grep, Skill, Agent, TodoWrite, and the task tools. |
+
+Write, Edit, SendMessage, and Bash go on the command line through `--allow-tools`, not in
+`allowed_tools`.
+
+## Grader types
+
+Each file in `evals/<case>/graders/` is one grader.
+
+| Type | Fields | Checks |
+| --- | --- | --- |
+| `regex` | `target`: `last_message`, `trace`, `files`, or `{source: file, path}` | A pattern in the chosen text |
+| `tool_used` | `tool`, `input_match`, `min`, `max`, `arm` | How many calls to a tool, filtered by an input regex |
+| `tool_order` | `before`, `after`, each a tool name or `{tool, input_match}` | One call lands before another |
+| `file_exists` | `path` glob, `exists` | A file created during the run matches, or none does with `exists: false` |
+| `llm` | The body is the rubric, `focus` | A judge panel votes, and 2 of 3 decide |
+| `baseline` | `baseline_file`, `criteria` | A judge rates the run at least as good as a reference `.jsonl` transcript |
+
+Source doc: https://code.claude.com/docs/en/plugin-evals
+
+## Case set
+
+Write at least these three shapes.
+
+**Slash case.** The prompt starts with `/<name>`. No `Skill` call happens, so grade what only the
+skill produces:
+
+- `tool_used` with `tool: Agent` and an `input_match` on the agent name the skill spawns.
+- `tool_order` with that `Agent` spawn before the first `Write`.
+
+**Plain-words case.** The prompt asks for the job in ordinary words. Vary the wording, and do not
+copy the exact phrase from the skill description into the only trigger case. Grade the trigger with:
+
+```text
+tool: Skill
+input_match: '"skill"\s*:\s*"(?:[\w-]+:)?<name>"'
+```
+
+**Must-not-trigger case.** The prompt uses a verb near the triggers in its ordinary sense. Grade
+with `tool_used`, `tool: Skill`, `min: 0`, `max: 0`, `arm: both`.
+
+Grade on skill behavior. A grader keyed to a transport token that upstream may remove breaks on an
+upgrade with no change in the skill.
+
+## Eval commands
+
+Run every command from the wrapper root.
+
+Smoke run, one case:
+
+```text
+claude plugin eval . --case <name> --runs 1 --ablation none --max-cost-usd 2 --no-publish --trust-plugin --allow-tools Write SendMessage
+```
+
+`--trust-plugin` is needed when stdin is not a terminal. `--case` takes one glob. Only the last
+`--case` flag takes effect, so match several cases with one glob.
+
+Full run: drop `--runs` and `--ablation`. The default is 3 runs with the plugin and 3 runs without.
+The delta, with minus without, measures what the skill adds. A smoke score under `--ablation none`
+has no without-plugin arm, so it measures nothing about contribution.
+
+Add `--keep-temp` to keep the sandbox. Its trace is `out/trace.jsonl`.
+
+## Results
+
+Each run writes `evals/results/<timestamp>/report.html` and `aggregate-result.json`.
+
+Before you compare arms, read each run's `permission_denials` and its final result. A run whose
+writes were all denied still shows the tool_use attempts.
+
+## Flag-gated features outside plugin eval
+
+The sandbox cannot turn on a flag-gated feature. Test it with `claude -p`, once with the wrapper
+loaded and once without:
+
+```text
+claude -p "<task>" --advisor <model> --plugin-dir <wrapper> --setting-sources project --strict-mcp-config --allowedTools "<list>" --permission-mode dontAsk --output-format stream-json --verbose
+```
+
+Drop `--plugin-dir <wrapper>` for the second arm.
+
+- Keep the user's config. An empty `CLAUDE_CONFIG_DIR` drops the login and the run reports
+  "Not logged in". `--setting-sources project` keeps user settings out.
+- Count the feature in the stream. For the advisor, count content blocks with `type`
+  `server_tool_use` and `name` `advisor` on the main thread only.
+- Before you read a zero count, run a positive control whose prompt asks for the feature by name. A
+  zero can mean the feature was not attached, rather than not chosen.
+- Keep the run's working folder outside the wrapper root, since writes under `--plugin-dir` are
+  denied in dontAsk mode.

package/.agents/skills/privacy-hygiene/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: privacy-hygiene
-description: Full-repo sweep for personal data and secrets before commit or durable GitHub post. Use when preparing a PR, cleaning a leak, or when `pii_prevention_blocker` denies a write, post, or commit. Triggers on "privacy hygiene", "personal data", "secret sweep", "sanitize repository", "/privacy-hygiene".
+description: Full-repo sweep for personal data and secrets before commit or durable GitHub post. Use when preparing a PR or cleaning a leak. Triggers on "privacy hygiene", "personal data", "secret sweep", "sanitize repository", "/privacy-hygiene".
 ---
 
 # privacy-hygiene
 
 ## Overview
 
-Find and remove personal data and high-confidence secrets before they land in git history or a durable GitHub post. The `pii_prevention_blocker` hook blocks the common cases at write, post, and commit time. This skill is the full sweep when you need a broader pass or a remediation plan.
+Find and remove personal data and high-confidence secrets before they land in git history or a durable GitHub post. No write-time hook scans for these; `pii_prevention_blocker` was retired. This skill is the sweep.
 
 **Announce at start:** "Running privacy-hygiene sweep."
 
@@ -40,8 +40,7 @@ Run the full-tree sweep in
 run the ripgrep pass for the four high-confidence pattern families (email, home
 path, LAN address, secret), review each hit against the ignore list, and
 remediate. It also lists the accepted residual — what to leave in place rather
-than over-scrub. The ripgrep command is the only full-tree pass; the write-time
-`pii_prevention_blocker` scans one payload at a time.
+than over-scrub. The ripgrep command is the only pass over the tree.
 
 ## Enable on any machine / public repository
 
@@ -56,9 +55,9 @@ Hooks register via `hooks/hooks.json` into `~/.claude/settings.json`. Once insta
 
 ## Open knobs
 
-- **NAS / LAN allowlist:** Unlisted private IPs are blocked. The scanner resolves your NAS host from `CLAUDE_NAS_HOST`, then `~/.claude/local-identity.json` (`nas.host`), and allowlists it when it is a private address, so the committed tree holds no real host. `ALL_ALLOWLISTED_PRIVATE_IP_ADDRESSES` in `hooks_constants` holds the static allowlist for any host every machine must share.
+- **NAS / LAN allowlist:** Unlisted private IPs are blocked. The scanner resolves your NAS host from `CLAUDE_NAS_HOST`, then `~/.claude/local-identity.json` (`nas.host`), and allowlists it when it is a private address, so the committed tree holds no host address. `ALL_ALLOWLISTED_PRIVATE_IP_ADDRESSES` in `hooks_constants` holds the static allowlist for any host every machine must share.
 - **Commit-scan exempt repositories:** named owner/repo slugs skip the staged-commit PII scan only. Set `CLAUDE_PII_EXEMPT_REPOS` (comma-separated `owner/repo` values) or list them under `pii_exempt_repositories` in `~/.claude/local-identity.json`. Matching uses the repository's `remote.origin.url` and accepts only the exact host `github.com` (https, ssh scheme, or scp-style). A repository with no readable origin is never exempt (fail-closed to scanning). Write / Edit / MultiEdit and durable post bodies still scan in every repository.
-- **Public maintainer identity:** when a real email or name is intentional product surface, keep it and note that in the PR body so reviewers do not treat it as a leak.
+- **Public maintainer identity:** when an email or name is intentional product surface, keep it and note that in the PR body so reviewers do not treat it as a leak.
 
 ## What this skill does not do
 

package/.agents/skills/privacy-hygiene/reference/sweep-procedure.md

@@ -1,10 +1,9 @@
 # Full-tree PII sweep procedure
 
-The on-demand full-repository sweep for the `privacy-hygiene` skill — the
-complement to the write-time `pii_prevention_blocker`, which scans one payload at
-a time. The canonical per-payload patterns live in the hooks' `pii_scanner` and
-`pii_prevention_constants` modules; the ripgrep command below is the only
-full-tree pass. The hub ([`../SKILL.md`](../SKILL.md)) points here.
+The on-demand full-repository sweep for the `privacy-hygiene` skill. The
+per-payload patterns live in the hooks' `pii_scanner` and
+`pii_prevention_constants` modules; the ripgrep command below is the only pass
+over the tree. The hub ([`../SKILL.md`](../SKILL.md)) points here.
 
 ## 1. Scope the tree
 
@@ -40,7 +39,7 @@ Review each hit. Ignore:
 
 | Hit | Fix |
 |---|---|
-| Real email | Replace with `user@example.com` or remove |
+| Email address | Replace with `user@example.com` or remove |
 | Home path | Use `Path.home()`, `~`, or `C:/Users/<you>/` |
 | LAN address | Remove, use a hostname, or — for your own NAS — set the host in `CLAUDE_NAS_HOST` or `~/.claude/local-identity.json`, both of which stay out of git |
 | Credential material | Remove from the tree; rotate the credential; load from env/secret store |

package/.agents/skills/pull-request/SKILL.md

@@ -38,8 +38,9 @@ Use this skill for one pull request action:
 - Submit a pull request review.
 - Recover one selected legacy author record before the action.
 
-Send issue create, edit, and comment work to `issue-tracker`. Send review and
-fix-loop work to `e-code-review`. Send commits to `source-command-commit`.
+Send issue create, edit, and comment work to `pstack:poteto-agent` with the
+`issue-tracker` skill and one action. Send review and fix-loop work to
+`e-code-review`. Send commits to `source-command-commit`.
 
 Require one repository and one action target. Stop before author lookup or
 network work when the repository, pull request, action, author, or required
@@ -73,9 +74,9 @@ current process environment.
 
 | Skill | When | Produces | If missing |
 |---|---|---|---|
-| `pr-description-writer` | Create or a full body rewrite, when you want the body drafted for you | A reviewed title and body file | Write the title and body yourself |
+| `pstack:poteto-agent` with `pull-request` instructions | Create or a full body rewrite, when you want the body drafted for you | A reviewed title and body file | Write the title and body yourself |
 | `privacy-hygiene` | Before any durable GitHub post | A clean body and repository privacy sweep | Stop before publication and report the missing gate |
-| `issue-tracker` | Issue create, edit, or comment requests | Issue state and issue URLs | Route the request there. |
+| `pstack:poteto-agent` with `issue-tracker` | Issue create, edit, or comment requests | Issue state and issue URLs | Load the skill in this session. |
 | `e-code-review` | Review or review/fix loop requests | Structured findings or a clean review result | Route the request there. |
 | `source-command-commit` | Commit or push requests | A verified commit or pushed branch | Route the request there. |
 
@@ -98,10 +99,15 @@ request target. Create actions publish drafts. Record the target before any writ
 ### 2. Author the title and body
 
 For create and full body rewrite, write the title and a body file, or invoke
-the installed `pr-description-writer` to draft them from the diff. A comment or
+`pstack:poteto-agent` with the diff-specific writing instructions to draft
+them. A comment or
 review may use a supplied body file when it does not rewrite the pull request
 description.
 
+Check each behavior claim against the final diff and verification evidence.
+Preserve whether a rule is added, removed, or narrowed, and distinguish tests
+added from tests run. Refresh these claims after a rebase or correction.
+
 ### 3. Run the local linter
 
 Resolve the active managed root (`CLAUDE_CONFIG_DIR` when set, `~/.claude`
@@ -153,6 +159,9 @@ Confirm the pull request URL and number, title, body, head SHA, and draft state.
 For comments and reviews, confirm the new remote entry. Report artifact URLs
 without exposing author values.
 
+Confirm the published claims still describe the verified head and preserve the
+scope of its evidence, including whether checks used saved artifacts or a new run.
+
 ## Exit handling
 
 Stop before network work when authoring, local validation, privacy, or author

package/.agents/skills/pull-request/reference/publication-tasks.md

@@ -6,7 +6,7 @@ reason when the task is conditional. This file is a task seed catalog, not a
 markdown progress board.
 
 1. Resolve one repository, action, and selected author. For create, resolve the source branch, base, and head. For other actions, resolve one existing pull request target. Create actions publish drafts.
-2. Record the title and body file for create or full body rewrite, written by you or drafted by `pr-description-writer`. Mark `N/A` for comment or review bodies that do not rewrite the pull request description.
+2. Record the title and body file for create or full body rewrite, written by you or drafted by `pstack:poteto-agent` with a PR-writing brief. Mark `N/A` for comment or review bodies that do not rewrite the pull request description.
 3. Validate every title, body, artifact, and local path input. Reject inline body input.
 4. Resolve the active managed root and run `<managed-root>/scripts/durable_post_lint.py` for the matching action. Record exit code `0` before credential lookup or network work.
 5. Run `privacy-hygiene` before the GitHub post and record its clean result.

package/.agents/skills/repairing-hook-boundaries/SKILL.md

@@ -27,7 +27,7 @@ output envelope, and exit status as separate boundaries.
 Use this skill for Claude or Codex hook failures involving registered events,
 settings, launchers, imports, paths, payloads, output envelopes, or exit status.
 
-For installer-only work, say: `Use /run-claude-dev-env for installer work that has no hook-boundary failure.`
+For installer-only work, say: `Installer work with no hook-boundary failure belongs outside this skill.`
 
 ## Process
 

package/.agents/skills/syncing-submodules/SKILL.md

@@ -31,7 +31,7 @@ Use this skill after committing inside a checked-out submodule when its parent r
 Refusals use the first matching line:
 
 - Clone, initialize, or check out a submodule: `Use Git's submodule commands. This skill records an existing submodule commit in its parent.`
-- Fast-forward `main`: `Use /update. This skill changes one parent submodule pointer.`
+- Fast-forward `main`: `Use Git directly. This skill changes one parent submodule pointer.`
 - Make an ordinary commit or push: `Use /source-command-commit. This skill commits only a parent submodule pointer.`
 
 ## Process

package/.agents/skills/team-advisor/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: team-advisor
 description: >-
-  Spawn one warm session-advisor at the strongest reachable tier and consult
-  it before substantive work, completion, commits, or when stuck. Triggers:
-  'team-advisor', 'team advisor', 'second opinion', 'advisor', 'consult',
-  'verify', 'validate', 'commit', 'push'.
-disable-model-invocation: true
+  Bind one advisor, the built-in advisor tool or a warm `pstack:poteto-agent`, and
+  consult it before substantive work, completion, commits, or when stuck.
+  Triggers:
+  'team-advisor', 'team advisor', 'second opinion', 'consult the advisor',
+  'get an advisor', 'check my approach with an advisor'.
 ---
 
 # Team Advisor
@@ -18,14 +18,14 @@ One warm advisor at the strongest tier this session can reach. This session is t
 |---|---|
 | [`docs/references/advisor-tool.md`](../../docs/references/advisor-tool.md) | **Consult cadence and weight.** When to call, the hard rule before first write, and how to treat advice. Read this for every consult. |
 | [`~/.claude/_shared/advisor/advisor-protocol.md`](../../_shared/advisor/advisor-protocol.md) | **Bind and lifecycle.** Session identity, host detect, model floor, warm-up, CLI fallback. Its read map routes each moment to a `reference/` detail file. |
-| [`agents/session-advisor.md`](../../agents/session-advisor.md) | **Reply contract.** ENDORSE / CORRECTION / PLAN / STOP. SendMessage only. |
+| Installed `poteto-mode` skill | **Reply contract.** The advisor prompt carries ENDORSE / CORRECTION / PLAN / STOP. |
 | [`reference/advisor-docs-review.md`](reference/advisor-docs-review.md) | Anthropic advisor-tool source facts: measured effects, Sonnet steering, cost levers, failure modes. Background. Read it when tuning the bind, not on every consult. |
 
 ## Bind
 
 1. Name the session identity first (protocol **Host profiles**), then walk the model floor.
-2. Claude: Fable first in-session at `ADVISOR_EFFORT` (default low). When Fable is out of usage, bind Astra at the same effort. Codex: Astra in-session. Third-party: headless Fable then Astra. When the host's walk fails, fail closed.
-3. Name: `team-advisor-agent` on Claude (Agent spawn of `session-advisor`); a native Astra subagent on Codex; one CLI `session_id` on a third-party host via the protocol Claude-chain or Astra helper.
+2. Claude: when `advisor` is in this session's tool list, the built-in advisor tool is the advisor. Spawn nothing and call `advisor()` at each consult point. Otherwise spawn or resume `pstack:poteto-agent` at `ADVISOR_EFFORT` (default low) with the advisor response contract in the prompt. When the bound model is out of usage, use the configured fallback at the same effort. Codex: use the native advisor path. Third-party: use the headless advisor path. When the host's walk fails, fail closed.
+3. Name the warm instance `team-advisor-agent` and keep its advisor response contract in every first prompt. When a native Codex subagent spawn is the advisor path, pass `flags: ["--advisor"]` with Astra.
 4. Skip the multi-consumer "who you are" opener. This session is the sole consumer.
 5. When the bind or reply path fails, fail closed and report to the user. On a third-party host, only the bound advisor issues ENDORSE / CORRECTION / PLAN / STOP.
 
@@ -39,10 +39,12 @@ Follow **When to call**, **Hard rule**, and **How to treat advice** in `advisor-
 
 Build every first brief with [`_shared/advisor/reference/consult-format.md`](../../_shared/advisor/reference/consult-format.md). Later briefs carry only the delta and changed evidence.
 
+With the built-in advisor tool, call `advisor()` with no brief. The tool forwards the whole transcript. Its reply is free text, not one of the four signal words, so weigh it per **How to treat advice** in `advisor-tool.md`.
+
 Aim for two consults on a normal task: one after orientation and one after writes and validation. Reserve a third for advisory recovery or reconciliation guidance, and add a consult when a material fork produces new evidence. This is an advisory target owned by the task, not a cap or gate.
 
 ## Constraints
 
-- One bind per session; this session owns spawn, in-session Astra spawn, or CLI bind, drift re-bind, and shutdown.
+- One bind per session; this session owns the built-in tool choice, spawn, in-session Astra spawn, or CLI bind, drift re-bind, and shutdown.
 - Bind at or above the protocol floor for this host.
 - The advisor only answers (messaging); the session runs tools and posts.

package/.agents/skills/team-advisor/reference/advisor-docs-review.md

@@ -125,7 +125,7 @@ directly; the wording lives under **Brevity cue** in
 Direct address works because the advisor reads the executor's prompt as
 quoted context: "instructions that address the advisor directly are followed
 much more reliably than third-person descriptions." A brief that asks for
-roughly 80 percent of the true ceiling raises consult frequency while
+roughly 80 percent of the ceiling raises consult frequency while
 lowering total cost.
 
 Typical advisor output runs 400–700 text tokens, or 1,400–1,800 with
@@ -205,3 +205,30 @@ successful task.
 
 Track, per route: completion rate, regression rate, tool calls, tokens by
 tier, and latency.
+
+## I. Verifying the built-in tool path
+
+Repository practice, observed on Claude Code 2.1.277: `claude plugin eval`
+cannot reach the built-in tool path. Its sandbox turns off feature-flag
+fetching, and `/advisor` replies "isn't available in this environment". A
+plugin-eval suite therefore grades the warm-agent path alone.
+
+Drive the built-in tool path with a headless run, once with the skill and once
+without:
+
+```text
+claude -p "<task>" --advisor opus --plugin-dir <wrapper> \
+  --setting-sources project --strict-mcp-config \
+  --allowedTools "Read,Glob,Grep,Skill,Agent,SendMessage,Write,Edit" \
+  --permission-mode dontAsk --output-format stream-json --verbose
+```
+
+Count main-thread content blocks with `type: server_tool_use` and
+`name: advisor`. Keep each run's folder outside `<wrapper>`, because
+`dontAsk` denies writes under a loaded plugin directory. Read
+`permission_denials` in each run before you compare the two arms.
+
+Run a positive control first, with a prompt that asks for the advisor by name.
+A zero count means the tool was never attached, or the model chose not to
+call it. The control tells the two apart. An empty `CLAUDE_CONFIG_DIR` drops
+the login, so keep the user config and use `--setting-sources project`.

package/.agents/skills/usage-pause/SKILL.md

@@ -33,7 +33,7 @@ On exit 0 the script prints one JSON object:
 | `session_utilization` | Percent of the 5-hour window spent (null on override) |
 | `weekly_utilization` | Percent of the weekly window spent (null on override) |
 | `weekly_resets_at` | When the weekly window resets (null on override) |
-| `weekly_near_cap` | True when the weekly meter is at or past the warn threshold |
+| `weekly_near_cap` | `true` when the weekly meter is at or past the warn threshold |
 
 On exit 2 the script prints `{"error": ...}`. Ask the user for a manual reset time via AskUserQuestion (offer clock-time and duration examples), then rerun with `--override`.
 
@@ -68,7 +68,7 @@ Before the first sleep:
 
 The stage plan (`stages_seconds` from the resolver) keeps every stage under the maximum stage length and ends with a short tail so the final firing lands just past the reset. Stage sizing constants live in `scripts/usage_pause_constants/resolve_usage_window_constants.py`; a leftover too short to stand alone folds into the tail.
 
-Every wakeup does exactly three things — ping, record, schedule — and dispatches no new work. The cache rationale: an unpinged idle agent left past the cache window resumes cold and re-reads its whole transcript, so pings run tighter than the cache lifetime and keep each agent's next real invocation cheap.
+Every wakeup does exactly three things — ping, record, schedule — and dispatches no new work. The cache rationale: an unpinged idle agent left past the cache window resumes cold and re-reads its whole transcript, so pings run tighter than the cache lifetime and keep each agent's next invocation cheap.
 
 ### Stage wakeup prompt template
 
@@ -78,7 +78,7 @@ Remaining chain (seconds): <remaining_stage_durations>. Cancelled crons: <cancel
 1. Ping every live agent AND every idle-but-warm agent with exactly this one line:
    "status checkpoint: reply with where you stand, do not start new work"
    An unpinged idle agent past the cache window resumes cold and re-reads its whole
-   transcript; the ping keeps its next real invocation cheap.
+   transcript; the ping keeps its next invocation cheap.
 2. Record any finished agent results on the task list. Dispatch nothing.
 3. Take the first duration off the remaining chain and ScheduleWakeup it, passing this
    same prompt with that duration removed and the stage number advanced. When the

package/_shared/advisor/advisor-protocol.md

@@ -62,7 +62,9 @@ On Codex: Astra is the in-session default. The `ADVISOR_ASTRA` flag is not requi
 
 ### Claude host
 
-Use the **Model floor** ladder below (Fable first, then Astra when Fable is out of usage).
+When `advisor` is in the session's tool list, the built-in advisor tool is the advisor. The user turns it on with `/advisor`, the `advisorModel` setting, or `--advisor`. Spawn nothing and call `advisor()` at each consult point. The tool forwards the whole transcript, so a consult needs no packet. Its reply is free text, so the four signal words do not apply; weigh it per `docs/references/advisor-tool.md` **How to treat advice**. It is a server tool, so hooks and the spawn-walk log do not see it. A Fable or Opus 5 advisor returns an encrypted result that a log cannot read. When a readable record matters, use the warm agent below.
+
+When `advisor` is not in the tool list, use the **Model floor** ladder below (Fable first, then Astra when Fable is out of usage).
 Warm-up spawns `subagent_type: session-advisor` via the Agent tool for Fable; consults go through `SendMessage` to that warm agent. Astra uses the Codex helper.
 Assemble and paste each executor's Advisor block per the **Advisor block** section.
 
@@ -85,6 +87,7 @@ Executors report to the orchestrating session; that session consults the bound a
 
 ## Model floor
 
+The built-in advisor tool sits outside this ladder. Claude Code and the API accept it only when the advisor is at least as capable as the main model, and that check is its floor.
 On Claude and ThirdParty the advisor ladder is `Fable` first, then Astra (flag-gated, Codex CLI) when Fable is out of usage.
 On Codex the walk is Astra only, in-session.
 Opus is not an advisor candidate. `Sonnet` and `Haiku` are executor tiers only.
@@ -103,7 +106,8 @@ The validator checks ladder shape only; host policy sits on top.
 
 ## Warm-up (once per session)
 
-On a **Claude host**, spawn `session-advisor` at the Fable alias with the charter as its prompt. When Fable is out of usage and the Astra rung is open, bind Astra through the Codex helper instead.
+On a **Claude host** with `advisor` in the tool list, skip the warm-up; the built-in tool needs none.
+On a **Claude host** without it, spawn `session-advisor` at the Fable alias with the charter as its prompt. When Fable is out of usage and the Astra rung is open, bind Astra through the Codex helper instead.
 Full spawn fields and the charter template: [`reference/warm-up.md`](reference/warm-up.md).
 
 On a **Codex host**, spawn a native in-session Astra subagent with the same charter. Bind fields: [`reference/identity.md`](reference/identity.md) and [`reference/warm-up.md`](reference/warm-up.md).
@@ -141,7 +145,7 @@ Modes and failover, the tier-to-alias table, brief piping, and `--resume` sessio
 
 **Codex host:** do not use this runner as the primary path. Astra binds in-session.
 
-**Claude host:** fall back to this runner exactly when one of these holds:
+**Claude host:** the built-in advisor tool never falls back to this runner. On the warm-agent path, fall back to this runner exactly when one of these holds:
 - The Agent-tool spawn errors at every candidate tier down to the floor. The tool itself is unavailable.
 - `SendMessage` to the shared advisor errors, or draws no reply within the bound in `ADVISOR_SENDMESSAGE_REPLY_WAIT_SECONDS` (120) in `$HOME/.claude/_shared/advisor/scripts/config/advisor_scripts_constants/model_tier_run_validator_constants.py`, and a re-spawn also fails.
 - The running session is itself a subagent barred from spawning further agents.

package/_shared/advisor/reference/advisor-block.md

@@ -3,7 +3,7 @@
 Detail behind the **Advisor block** section of [`advisor-protocol.md`](../advisor-protocol.md).
 Open this when assembling the block for an executor spawn prompt.
 
-Assembly order: one transport preamble picked by host profile, then the shared core, then the weak-executor add-on for an executor at Sonnet or below.
+Assembly order: one transport preamble picked by host profile, then the shared core, then the weak-executor add-on for an executor at Sonnet or below. A Claude host with the built-in advisor tool takes its own block and skips the preamble and the shared core.
 Paste the assembled block at the **top** of the spawn prompt, ahead of any other sentence that mentions the advisor.
 The assembled block is self-contained. The executor receives this text alone, so every path it names is absolute.
 The consult rules it restates are owned by [`consult-format.md`](consult-format.md); edit that file first and carry the change here.
@@ -12,6 +12,13 @@ The consult rules it restates are owned by [`consult-format.md`](consult-format.
 
 > A shared session advisor named `<name>` is reachable via SendMessage; send each consult to it directly by that name.
 
+## Block for a Claude host with the built-in advisor tool
+
+Subagents inherit the session's advisor tool, so the executor calls it directly. Paste this block alone, then the weak-executor add-on for an executor at Sonnet or below. The shared core's packet and signal-word lines do not apply, and neither does the add-on's 80-word line.
+
+> Your session has the built-in `advisor` tool. Call `advisor()` before locking in a nontrivial approach, once you believe your assignment is done, before any hard-to-reverse action, when the same failure repeats or progress has stalled, and when the chosen approach is being reconsidered.
+> The tool reads your whole transcript, so call it with no brief. Its reply is free text. Give it serious weight; when your evidence contradicts it, call again and name the conflict.
+
 ## Transport preamble for a Codex host
 
 > A shared session advisor named `<name>` is reachable as a native Codex Astra subagent; send each consult to it in-session by that name.

package/audit-rubrics/category_rubrics/category-f-silent-failures.md

@@ -20,14 +20,14 @@
 |---|---|---|
 | F1 | Catch-all except clauses | `except:` (bare), `except Exception:`, `except BaseException:` followed by `pass` / `continue` / log-only. |
 | F2 | Errors logged then swallowed | `logger.error(...)` followed by `return None` / `return default` without re-raise. |
-| F3 | Default fallback values masking failure | `dict.get(key, default)` where the absence of the key is itself a bug; `or default` short-circuits hiding `None`. Includes the stale-payload-key shape: a `payload.get("KEY", "")` (or `payload["KEY"]` wrapped in a fallback) read against an external-input dict whose contract the diff migrated — the rest of the module reads the payload through a different key set named in the docstring and bound to same-named variables, while this lone read targets a dropped key, so it resolves to the default on every real payload and silently records an empty value into the field it feeds. The audit teammate lists every string-literal key read from each `*_payload` / event / request dict, checks each key against the payload contract the module's docstring and other reads set up, and flags a key read at one site that no docstring, second read, or same-named binding anchors. A key consumed inline with a meaningful default (`resolve(payload.get("cwd", "."))`) is legitimate, not stale — the flag is the dropped key whose value the field needs but never receives. |
+| F3 | Default fallback values masking failure | `dict.get(key, default)` where the absence of the key is itself a bug; `or default` short-circuits hiding `None`. Includes the stale-payload-key shape: a `payload.get("KEY", "")` (or `payload["KEY"]` wrapped in a fallback) read against an external-input dict whose contract the diff migrated — the rest of the module reads the payload through a different key set named in the docstring and bound to same-named variables, while this lone read targets a dropped key, so it resolves to the default on every payload and silently records an empty value into the field it feeds. The audit teammate lists every string-literal key read from each `*_payload` / event / request dict, checks each key against the payload contract the module's docstring and other reads set up, and flags a key read at one site that no docstring, second read, or same-named binding anchors. A key consumed inline with a meaningful default (`resolve(payload.get("cwd", "."))`) is legitimate, not stale — the flag is the dropped key whose value the field needs but never receives. |
 | F4 | Async task error swallowing | `asyncio.create_task(...)` without exception observation; `gather(..., return_exceptions=True)` consumed loosely. |
 | F5 | Boolean / status returns identical on success and failure | A function returns `True` on the happy path and `True` on the catch-all error path. |
 | F6 | Ignored return values from fallible calls | `subprocess.run` without `check=True` and unchecked `returncode`; `os.write` return value discarded. |
 | F7 | PowerShell error-suppression patterns | `-ErrorAction SilentlyContinue` followed by `.Property` access; `2>$null` or `*>$null`; `$?` not consulted. |
 | F8 | Test-level swallowing | Tests that catch and log instead of asserting; `pytest.warns` used instead of `pytest.raises`. |
 | F9 | Gate-validator self-defeat via parse-failure swallow | A new gate / validator / hook check parses input as code (`ast.parse`) and catches the parse error with `return []` / `return None` / `return True` (clean signal). When the dispatcher feeds the check a partial fragment (e.g., the Edit tool's `new_string` rather than the full file content), the parse always fails and the check silently fires zero findings. The audit teammate lists every new `ast.parse` / `tokenize` / `json.loads` / `yaml.safe_load` call in gate code and asks: does the catch branch produce a clean signal that would mask the gate being broken? |
-| F10 | Guard helper returns success-default on unverifiable input | A guard helper / predicate / classifier short-circuits to `True` / `Ok` / the success sentinel when it cannot validate the input shape (missing positional args, wrong arity, unexpected None). Guards must default-deny when they cannot verify; default-allow on unverifiable input masks real violations downstream. |
+| F10 | Guard helper returns success-default on unverifiable input | A guard helper / predicate / classifier short-circuits to `True` / `Ok` / the success sentinel when it cannot validate the input shape (missing positional args, wrong arity, unexpected None). Guards must default-deny when they cannot verify; default-allow on unverifiable input masks violations downstream. |
 
 ---
 

package/audit-rubrics/category_rubrics/category-i-concurrency.md

@@ -33,6 +33,6 @@
 The reusable Variant C template for Category I is in [`../prompts/category-i-concurrency.md`](../prompts/category-i-concurrency.md). Inline your artifact under `## Source material` and adapt the sub-bucket bullets to your project's concurrency model.
 
 For a literal worked example using PR #394, see [`category-a-api-contracts.md`](category-a-api-contracts.md). Category I walks for that diff:
-- I4: TOCTOU between `os.walk` enumerating a directory and `os.path.getctime` / `os.rmdir` on the same path — another process could delete or repopulate the dir in the window. The `try/except OSError` handles the race correctly (Category F notes the same blocks for silent-failure concerns; here they're actually protective).
+- I4: TOCTOU between `os.walk` enumerating a directory and `os.path.getctime` / `os.rmdir` on the same path — another process could delete or repopulate the dir in the window. The `try/except OSError` handles the race correctly (Category F notes the same blocks for silent-failure concerns; here they're protective).
 - I4 (PowerShell): `Test-Path $Target` followed by `Register-ScheduledTask` — directory could be deleted between the check and the registration. Low-impact since the schedule still registers.
 - I1, I2, I3, I5–I8: not applicable — script is single-threaded synchronous Python with no asyncio, no shared mutable state across processes.