claude-dev-env 2.10.0 → 2.11.0

package/docs/references/advisor-tool.md

@@ -1,14 +1,14 @@
 # Advisor Tool
 
-Canonical consult timing and weight for any stronger-reviewer path: the native `advisor()` tool, `/team-advisor`, and the shared warm advisor.
+Canonical consult timing and weight for the repository advisor path: `/team-advisor` and the shared warm advisor. Anthropic's advisor documentation supplies the source guidance for packet shape and review timing.
 
 Source bones: [Anthropic Advisor tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool) (Suggested system prompt for coding tasks). API shape, model pairs, cost, and caching live there. This file carries only the call rules a session needs every time.
 
 ## What it is
 
-`advisor()` is a no-parameter review call. The platform forwards the full conversation (task, tool calls, results) to a stronger model. The executor continues with that guidance.
+`/team-advisor` is the repository's advisor implementation. It carries the full first packet explicitly, sends later deltas, and owns the warm Agent/SendMessage or read-only Sol CLI lifecycle.
 
-When `advisor()` is absent, use `/team-advisor` (see `team-advisor-skill.md`).
+See `team-advisor-skill.md` for the bind and lifecycle map.
 
 ## When to call
 
@@ -18,11 +18,11 @@ If the task needs orientation first (find files, fetch a source, see what exists
 
 Also call:
 
-- **When you believe the task is complete.** Before this call, make the deliverable durable: write the file, save the result, commit the change. The call takes time; if the session ends during it, a durable result survives and an unwritten one does not.
+- **When you believe the task is complete.** Before this call, make the deliverable durable: write the file, save the result, commit the change. The call takes time; if the session ends during it, a durable result survives and an unwritten one does not. Ask the advisor to hunt for missing requirements, untested behavior, wrong assumptions, unhandled edge cases, evidence gaps, and early completion claims.
 - **When stuck** — errors recur, approach does not converge, results do not fit.
 - **When considering a change of approach.**
 
-On tasks longer than a few steps, call at least once before committing to an approach and once before declaring done. On short reactive tasks where the next action is dictated by tool output you just read, you do not need repeated calls — most value is on the first call, before the approach hardens.
+On tasks longer than a few steps, aim for an early approach consult and a completion review. Reserve a third consult for recovery or reconciliation, and add consults when material new evidence or forks arise. This cadence guides planning and leaves the task free to follow its evidence. Short reactive tasks may use the single consult that best fits the live decision.
 
 Call for design, architecture, and risk questions where you will not touch a file. If the response would be analysis or a recommendation with no other tool calls, call first. That judgment is where a second opinion is highest value. Simple factual lookups and arithmetic do not need a call.
 
@@ -34,7 +34,22 @@ Your first write, edit, or state-changing shell call on a task must be preceded
 
 Give the advice serious weight. If a step fails empirically, or primary-source evidence contradicts a claim (the file says X, the paper states Y), adapt. A passing self-test is not evidence the advice is wrong — it is evidence the test does not check what the advice is checking.
 
-If your data points one way and the advisor points another: do not silently switch. Surface the conflict in one more call — "I found X, you suggest Y, which constraint breaks the tie?" The advisor saw the evidence but may have underweighted it; a reconcile call is cheaper than the wrong branch.
+If your data points one way and the advisor points another: do not silently switch. Surface the conflict in one more call — "I found X, you suggest Y, which constraint breaks the tie?" A reconcile call is cheaper than the wrong branch.
+
+Work a disagreement in this order: keep the observed evidence in the record, name the conflict plainly, ask the advisor which constraint breaks the tie, then act on the reconciled plan.
+
+## Escalation shapes
+
+Four shapes cover how a harder task gets more strength behind it. Route to the one that matches the work, not by default to the advisor.
+
+| Shape | Fits when |
+|---|---|
+| Advisor | The task needs intermittent strategy and review, and one executor keeps the task from start to finish. |
+| Subagent | A piece of the task is a bounded subtask that benefits from its own context and its own loop. |
+| Stronger-model planning phase | The plan needs the strong model's judgment; the fast model can carry it out once written. |
+| Full model switch | Every step of the task needs the stronger tier, not just the hard decisions. |
+
+Spawn a subagent when the work is a delegable bounded subtask. Switch the whole task to the stronger model when every turn needs that tier.
 
 ## Brevity cue
 
@@ -42,10 +57,13 @@ When the consult path supports a free-text brief, append:
 
 `(Advisor: please keep your guidance under 80 words — I need a focused starting point, not a comprehensive plan.)`
 
+Size the ask at roughly 80 percent of the true ceiling; direct address to the advisor lands more reliably than a third-person description.
+
 ## Related
 
 | Doc | Holds |
 |---|---|
 | [Anthropic Advisor tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool) | API shape, model pairs, cost, caching, full best practices |
-| `team-advisor-skill.md` | Standing warm advisor when `advisor()` is missing |
-| `~/.claude/_shared/advisor/advisor-protocol.md` | Host bind, floor walk, lifecycle, executor paste blocks |
+| `team-advisor-skill.md` | Standing warm advisor for this repository |
+| `~/.claude/_shared/advisor/advisor-protocol.md` | Host bind, floor walk, lifecycle — a read map routes each bind or consult moment to its `reference/` detail file |
+| `weak-executor-advisor.md` | Consult deltas for an executor spawned below the advisor's own tier |

package/docs/references/team-advisor-skill.md

@@ -1,6 +1,6 @@
 # Team-Advisor Skill
 
-`/team-advisor` binds one standing warm advisor for this session at the strongest reachable tier. Use it when `advisor()` is absent, or when you want a standing four-signal reviewer across many decision points.
+`/team-advisor` binds one standing warm advisor for this session at the strongest reachable tier. This skill is the selected custom reproduction path for advisor behavior: it forwards explicit packets to a warm Agent/SendMessage advisor or the read-only `codex_sol_advisor.py` path across many decision points.
 
 ## Refs
 
@@ -15,6 +15,6 @@
 
 Follow the call rules in `advisor-tool.md` (orientation first, then consult before substantive work; durable deliverable before the completion consult; stuck or reapproach; long tasks twice).
 
-## Relation to `advisor()`
+## Selected path
 
-`/team-advisor` works with no `advisor()` tool. When both exist: `advisor()` for a fast history-forwarded check; `/team-advisor` for a standing named reviewer consulted at the same cadence.
+`/team-advisor` is the repository's advisor implementation. It provides explicit first-consult packets, delta consults, a standing warm reviewer, and a read-only Sol CLI option.

package/docs/references/weak-executor-advisor.md

@@ -0,0 +1,91 @@
+# Weak-Executor Advisor Profile
+
+Consult profile for an executor spawned below the advisor's own tier — a
+Sonnet or Haiku model carrying an advisor bind. `advisor-tool.md` sets the
+canonical cadence for every consumer; this file adds the deltas a below-tier
+executor needs on top of it.
+
+Source: [Anthropic Advisor tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool)
+(Suggested system prompt for coding tasks). The distilled facts behind each
+section live in
+`skills/team-advisor/reference/advisor-docs-review.md`.
+
+## Scope
+
+Applies to any executor running below the advisor's tier. A same-tier or
+stronger executor follows `advisor-tool.md` alone. The paste-ready form of
+this profile is the **Weak-executor add-on** block in
+`~/.claude/_shared/advisor/reference/advisor-block.md`.
+
+## Steering lives in the spawn prompt
+
+The advisor rules sit at the top of the spawn prompt, ahead of every other
+sentence that mentions the advisor — the spawn prompt is the one steering
+surface with measured effect on Sonnet.
+
+## Context packaging
+
+Everything the advisor learns arrives inside the consult. Each consult
+carries its own packet:
+
+- **First consult** — use the complete packet in
+  `~/.claude/_shared/advisor/reference/consult-format.md`: assignment,
+  desired outcome, constraints and exclusions, actions taken in order, real
+  output and current state, decision or blocker, validation evidence,
+  unresolved risks, and load-bearing paths or excerpts.
+- **Later consults** — the delta since the last consult.
+- **Ordering** — stable role and charter text first, volatile detail last.
+
+## Two-timing rule
+
+Two consult moments carry the measured gain:
+
+1. **Early** — after a few exploratory reads land in the transcript, before
+   the first write. This is the hard rule `advisor-tool.md` §Hard rule
+   states for every consumer.
+2. **Final** — after file writes and test output exist to forward. Make the
+   deliverable durable first (write the file, save the result, commit the
+   change), then consult.
+
+## Planner funnel
+
+Consult the advisor before any task-list or planner tool. The advisor's plan
+becomes the task list.
+
+## Consult budget
+
+Aim for two consults per task: early orientation and completion review. Reserve a third for advisory recovery or reconciliation guidance, and add a consult when a material fork produces new evidence. This is a planning target that leaves the task free to follow its evidence.
+
+## Advice weight
+
+Advice is binding absent empirical contradiction. A conflict between the
+executor's own evidence and the advisor's guidance goes back to the advisor
+as a reconcile consult. See `advisor-tool.md` §How to treat advice for the
+full weighing rule.
+
+## Long-run reminder
+
+On a run past roughly 20 advisor-free turns, the executor re-reads its
+advisor rules before the next substantive step — the re-read keeps the
+advisor visible across a long horizon.
+
+## Failure branches
+
+- **Transient advisor failure** — retry once, then carry on with the
+  evidence in hand and record the gap in the result.
+- **Advisor unreachable** — report upward and hold the decision for the
+  owning session; re-binding belongs to that session alone.
+
+## Pairing invariant
+
+The advisor binds at or above the strongest consumer's tier. The floor
+holds at that tier whichever executor joins the pairing.
+
+## Related
+
+| Doc | Holds |
+|---|---|
+| `advisor-tool.md` | Canonical consult cadence, hard rule, brevity cue |
+| `~/.claude/_shared/advisor/advisor-protocol.md` | Host bind, model floor, and the Advisor-block assembly rule |
+| `~/.claude/_shared/advisor/reference/advisor-block.md` | The paste parts — transport preambles, shared core, weak-executor add-on |
+| `skills/team-advisor/reference/advisor-docs-review.md` | Distilled source facts behind each section above |

package/hooks/blocking/test_fable_spawn_gate.py

@@ -11,8 +11,9 @@ field, pass whether or not the marker is present. One test reads
 spawn tool names.
 
 Token pins read the warm-up section and each consuming skill. Two doc-gate
-agreement tests assemble a spawn prompt out of the advisor-protocol wording a
-warm-up bind and a drift re-spawn follow, and run each through the gate, so
+agreement tests assemble a spawn prompt out of the advisor reference wording a
+warm-up bind (``reference/warm-up.md``) and a drift re-spawn
+(``reference/lifecycle.md``) follow, and run each through the gate, so
 wording that stops naming the marker fails here. Two deny-path tests read the
 preview the gate hands the block logger and hold it bounded and scoped to the
 model field.
@@ -64,6 +65,13 @@ _FULL_SONNET_MODEL_ID = "claude-sonnet-4-5"
 _PACKAGE_ROOT = _HOOKS_TREE.parent
 _ADVISOR_PROTOCOL_PATH = _PACKAGE_ROOT / "_shared" / "advisor" / "advisor-protocol.md"
 _ADVISOR_PROTOCOL_TEXT = _ADVISOR_PROTOCOL_PATH.read_text(encoding="utf-8")
+_ADVISOR_REFERENCE_DIR = _PACKAGE_ROOT / "_shared" / "advisor" / "reference"
+_ADVISOR_LIFECYCLE_TEXT = (_ADVISOR_REFERENCE_DIR / "lifecycle.md").read_text(
+    encoding="utf-8"
+)
+_ADVISOR_WARM_UP_TEXT = (_ADVISOR_REFERENCE_DIR / "warm-up.md").read_text(
+    encoding="utf-8"
+)
 _ALL_CONSUMING_SKILL_NAMES = ("team-advisor", "orchestrator", "orchestrator-refresh")
 _ALL_CONSUMING_SKILL_PATHS = tuple(
     _PACKAGE_ROOT / "skills" / each_skill_name / "SKILL.md"
@@ -321,19 +329,18 @@ def test_consuming_skill_names_the_marker_token(skill_path: pathlib.Path) -> Non
     assert FABLE_SPAWN_AUTHORIZATION_MARKER in skill_path.read_text(encoding="utf-8")
 
 
-def _paragraph_starting_at(paragraph_marker: str) -> str:
-    """Return the advisor-protocol paragraph that opens with a marker.
+def _paragraph_starting_at(source_text: str, paragraph_marker: str) -> str:
+    """Return the advisor-doc paragraph that opens with a marker.
 
     Args:
+        source_text: The advisor document text holding the paragraph.
         paragraph_marker: The literal text opening the paragraph.
 
     Returns:
         The paragraph text, running from that marker to the blank line that
         closes it.
     """
-    paragraph_body = _ADVISOR_PROTOCOL_TEXT[
-        _ADVISOR_PROTOCOL_TEXT.index(paragraph_marker) :
-    ]
+    paragraph_body = source_text[source_text.index(paragraph_marker) :]
     paragraph_end = paragraph_body.find(_PARAGRAPH_SEPARATOR)
     if paragraph_end < 0:
         return paragraph_body
@@ -341,7 +348,7 @@ def _paragraph_starting_at(paragraph_marker: str) -> str:
 
 
 def _respawn_spawn_prompt() -> str:
-    """Assemble the spawn prompt a drift re-spawn writes from the protocol.
+    """Assemble the spawn prompt a drift re-spawn writes from the lifecycle doc.
 
     The prompt comes from the re-spawn paragraph alone, so the gate reads
     what that one paragraph tells a session to send.
@@ -349,7 +356,7 @@ def _respawn_spawn_prompt() -> str:
     Returns:
         The spawn prompt text a session following that paragraph sends.
     """
-    return _paragraph_starting_at(_RESPAWN_PARAGRAPH_MARKER)
+    return _paragraph_starting_at(_ADVISOR_LIFECYCLE_TEXT, _RESPAWN_PARAGRAPH_MARKER)
 
 
 def test_respawn_paragraph_prompt_passes_the_gate_at_the_fable_tier() -> None:
@@ -358,7 +365,7 @@ def test_respawn_paragraph_prompt_passes_the_gate_at_the_fable_tier() -> None:
 
 
 def _warm_up_spawn_prompt() -> str:
-    """Assemble the spawn prompt a warm-up bind writes from the protocol.
+    """Assemble the spawn prompt a warm-up bind writes from the warm-up doc.
 
     The prompt comes from the spawn-field prompt bullet alone, so the gate
     reads what that one bullet tells a session to send.
@@ -366,7 +373,7 @@ def _warm_up_spawn_prompt() -> str:
     Returns:
         The spawn prompt text a session following that bullet sends.
     """
-    return _paragraph_starting_at(_WARM_UP_PROMPT_BULLET_MARKER)
+    return _paragraph_starting_at(_ADVISOR_WARM_UP_TEXT, _WARM_UP_PROMPT_BULLET_MARKER)
 
 
 def test_warm_up_prompt_bullet_passes_the_gate_at_the_fable_tier() -> None:

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "2.10.0",
+    "version": "2.11.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {

package/skills/_shared/advisor/CLAUDE.md

@@ -6,4 +6,4 @@
 
 @~/.claude/_shared/advisor/advisor-protocol.md
 
-Scripts: `~/.claude/_shared/advisor/scripts/` (`model_tier_run_validator.py`, `tier_model_ids.py`, constants under `scripts/config/`).
+Scripts: `~/.claude/_shared/advisor/scripts/` (`model_tier_run_validator.py`, `codex_sol_advisor.py`, `tier_model_ids.py`, constants under `scripts/config/`).

package/skills/_shared/advisor/scripts/README.md

@@ -4,6 +4,8 @@
 
 @~/.claude/_shared/advisor/scripts/model_tier_run_validator.py
 
+@~/.claude/_shared/advisor/scripts/codex_sol_advisor.py
+
 @~/.claude/_shared/advisor/scripts/tier_model_ids.py
 
 Full tree: `~/.claude/_shared/advisor/scripts/`.

package/skills/grokify/SKILL.md

@@ -43,7 +43,7 @@ The user types `/grokify`, alone or with guidance.
 
 - **Bind once, first:** charter + findings + constraints + plan piped from a temp file into `claude -p --model fable --effort high --output-format json`; parse and save `session_id` from the JSON reply.
 - **Consult:** brief piped into `claude -p --resume <session_id> --model fable --effort high --output-format json`.
-- **ConsultB** If fable is unavailable, use opus with max effort: `claude -p --resume <session_id> --model opus --effort max --output-format json`.
+- **ConsultB** If fable is unavailable, use opus with xhigh effort: `claude -p --resume <session_id> --model opus --effort xhigh --output-format json`.
 - **Signals:** every advisor reply opens with exactly one of ENDORSE, CORRECTION, PLAN, or STOP. CORRECTION and PLAN are actions to take, with a report-back in the next consult on that topic. STOP halts that line of work and surfaces it to the user. When the CLI is unreachable, Grok stops and says so — it never self-endorses in the advisor's place.
 - **Cadence, mandatory:** after planning and before any edit; per phase before implementation (TDD red + approach) and after (diff, tests, acceptance evidence); before every `git commit` and `git push`; on every user-facing fork before asking; on any twice-repeated failure or stall.
 

package/skills/grokify/templates/handoff-template.md

@@ -43,7 +43,7 @@ CONFIRM THESE WITH THE USER FIRST, VIA ASKUSERQUESTION, BEFORE EMBEDDING]
    append the full Established findings, Hard constraints, and Plan sections of this
    document to the same file.
 2. Bind: `claude -p --model fable --effort high --output-format json < <charter-file>`
-2a. If 2 fails, replace fable with opus, effort high to max.
+2a. If 2 fails, replace fable with opus, effort high to xhigh.
 3. The JSON output is an array of events, not one object. Take `session_id` from any
    event; the reply text is the `type == "result"` event's `.result` field. Persist
    `session_id`, the repo root, and the cwd to a state file at once.
@@ -56,7 +56,7 @@ CONFIRM THESE WITH THE USER FIRST, VIA ASKUSERQUESTION, BEFORE EMBEDDING]
    session, not a model failure.
 
 **Consult (every time):** write the brief to a temp file, then
-`claude -p --resume <session_id> --model fable (or opus) --effort high (max for opus) --output-format json < <brief-file>`.
+`claude -p --resume <session_id> --model fable (or opus) --effort high (xhigh for opus) --output-format json < <brief-file>`.
 Act on the reply's opening signal: ENDORSE — proceed. CORRECTION — apply it first;
 your next consult on that topic opens with what happened. PLAN — adopt it; same
 report-back rule. STOP — halt that line of work and surface it to the user. Never

package/skills/orchestrator/SKILL.md

@@ -193,7 +193,7 @@ Touch only: <files or globs>
 Done when: <one mechanical check — a command, a test, a diff scope>
 Return: status, artifact paths, blockers — nothing else.
 
-<host-matched Advisor block from advisor-protocol.md, advisor name filled in>
+<Advisor block assembled per _shared/advisor/reference/advisor-block.md — advisor name filled in>
 ```
 
 - **Size the task by its done-check.** The right task is the largest
@@ -218,9 +218,10 @@ Return: status, artifact paths, blockers — nothing else.
   table picks the definition, and `clean-coder` already holds the code
   discipline. The ticket adds the task, the pointers, and the Advisor
   block only.
-- **The Advisor block is the one pasted paragraph.** It is host-matched
-  at bind time and written to be self-contained (the protocol's Advisor
-  block section) — paste it; do not point at it.
+- **The Advisor block is pasted, assembled text.** Assemble it at bind
+  time from the parts in
+  [`_shared/advisor/reference/advisor-block.md`](../../_shared/advisor/reference/advisor-block.md)
+  and paste the assembled text itself into the ticket.
 
 ## Workflow Agent Routing
 

package/skills/team-advisor/SKILL.md

@@ -16,25 +16,28 @@ One warm advisor at the strongest tier this session can reach. This session is t
 | Doc | Holds |
 |---|---|
 | [`docs/references/advisor-tool.md`](../../docs/references/advisor-tool.md) | **Consult cadence and weight** — when to call, hard rule before first write, how to treat advice. Read this for every consult. |
-| [`~/.claude/_shared/advisor/advisor-protocol.md`](../../_shared/advisor/advisor-protocol.md) | **Bind and lifecycle** — host detect, model floor, warm-up or CLI bind, charter, drift re-bind, CLI fallback, executor paste blocks. |
+| [`~/.claude/_shared/advisor/advisor-protocol.md`](../../_shared/advisor/advisor-protocol.md) | **Bind and lifecycle** — 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. |
+| [`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. Detect the host profile first (protocol **Host profiles**), then walk the model floor.
-2. Floor: this session's own tier on Claude; Opus floor with Fable first on a third-party host.
+2. Floor: the stronger of Opus and this session's own tier on Claude; Opus floor with Fable first on a third-party host.
 3. Name: `team-advisor-agent` on Claude (Agent spawn of `session-advisor`); one CLI `session_id` on a third-party host via the protocol Claude-chain.
 4. A Fable-tier spawn or re-spawn carries the exact token `FABLE-SPAWN-AUTHORIZED` in its prompt (protocol warm-up; `fable_spawn_gate` requires it).
 5. Skip the multi-consumer "who you are" opener — sole consumer.
 6. When the bind or reply path fails, fail closed and report to the user. On a third-party host, only the bound Claude advisor issues ENDORSE / CORRECTION / PLAN / STOP.
 
-Full walk, charter, consult message shape, and drift re-bind live in the protocol.
+Full walk, charter, consult packet, Sol routing, and drift re-bind live in the protocol read map and its authoritative `reference/` leaves.
 
 ## Consult
 
 Follow **When to call**, **Hard rule**, and **How to treat advice** in `advisor-tool.md`.
 
-Each brief: delta since last consult, live decision or blocker, paths or excerpts needed. Protocol owns the full consult format.
+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.
+
+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
 

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

@@ -0,0 +1,207 @@
+# Advisor-Tool Documentation Review
+
+Distilled facts from the Anthropic advisor-tool documentation, for the
+Sonnet-executor advisor path and the hand-rolled `/team-advisor` bind. Every
+source claim below cites its page; section H is repository practice and says
+so.
+
+Consult timing, the hard rule before a first write, and how to weigh the
+advice live in [`docs/references/advisor-tool.md`](../../../docs/references/advisor-tool.md).
+The consult cadence lives in [`SKILL.md`](../SKILL.md). This file carries the
+source facts those two omit: measured effects, Sonnet steering, cost levers,
+failure modes, and what transfers to a hand-rolled bind.
+
+## Sources
+
+| # | Page |
+|---|---|
+| 1 | [Advisor tool — platform docs](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool) |
+| 2 | [Escalate hard decisions with the advisor tool — Claude Code](https://code.claude.com/docs/en/advisor) |
+| 3 | [The advisor strategy — blog](https://claude.com/blog/the-advisor-strategy) |
+| 4 | [Best practices for computer and browser use — blog](https://claude.com/blog/best-practices-for-computer-and-browser-use-with-claude) |
+| 5 | [Claude models explained — blog](https://claude.com/blog/claude-models-explained-choosing-the-best-model-for-your-use-case) |
+| 6 | [Messages API — beta](https://platform.claude.com/docs/en/api/beta/messages) |
+| 7 | [Claude Code changelog](https://code.claude.com/docs/en/changelog) |
+
+## A. Consult timing the canonical rules omit
+
+Planner funnel, page 1:
+
+```text
+If your agent exposes other planner-like tools (for example, a todo list
+tool), prompt the model to call the advisor before those tools so the
+advisor's plan funnels into them.
+```
+
+Consult moments for long agent runs, page 4: "choosing which tab to open,
+recovering from an unexpected modal, deciding whether to abandon a strategy".
+
+Frequency control stays prompt-only, page 2:
+
+```text
+There is no setting to cap or force advisor calls; if you want Claude to
+consult more or less often during a task, say so in your instructions.
+```
+
+## B. Measured effect of the hard rule
+
+The rule itself — an advisor call before the first write, edit, or
+state-changing shell call — lives under **Hard rule** in
+[`advisor-tool.md`](../../../docs/references/advisor-tool.md). Page 1 states
+it inside the Haiku and Opus system-prompt blocks and reports its effect:
+the Haiku coding block raises pass rates by roughly 7.5 points on an
+internal coding benchmark. On Opus the same checkpoint raises
+under-calling tasks 7–10 points and holds roughly flat on a mixed workload
+where plan-free tasks over-call.
+
+## C. Sonnet-executor facts
+
+Page 1 marks the startup nudge as dead weight on Sonnet:
+
+```text
+On Sonnet executors, the plain-text nudge had no measurable effect in
+Anthropic's testing.
+```
+
+Steering for a Sonnet executor belongs in the system prompt, prepended
+"before any other sentences that mention the advisor" (page 1).
+
+Page 4 names a long-session gap: the executor does not always remember the
+advisor exists on long-horizon tasks; the tested pattern is a one-line
+reminder after roughly 20 advisor-free turns.
+
+Named pairing, page 1:
+
+```text
+You currently use Sonnet on complex tasks: Add a higher-tier advisor. Opus
+keeps total cost similar or lower; Claude Fable 5 maximizes the quality lift.
+```
+
+Effort pairing, page 1:
+
+```text
+For coding tasks, pairing a Sonnet executor at medium effort with an Opus
+advisor achieves intelligence comparable to Sonnet at default effort, at
+lower cost. For maximum intelligence, keep the executor at default effort.
+```
+
+Page 3 footnotes the benchmark condition: the Sonnet-plus-advisor SWE-bench
+Multilingual run uses the suggested system prompt "with thinking turned
+off" — a consult substitutes for extended thinking in that run.
+
+## D. Benchmarks
+
+Page 3 and page 5 report these results:
+
+- Sonnet 4.6 with an Opus 4.6 advisor: +2.7 points on SWE-bench Multilingual
+  over Sonnet solo, cost per agentic task down 11.9%.
+- Haiku 4.5 with an Opus advisor on BrowseComp: 41.2% versus 19.7% solo;
+  trails Sonnet solo by 29% in score at 85% lower cost per task.
+- Sonnet 5 with a Fable 5 advisor (page 5): within 10% of Fable 5's own score
+  at 63% of the price of running Fable 5 for the whole task, on SWE-bench
+  Pro.
+
+Advisor reply shape, page 3:
+
+```text
+Opus accesses the shared context and returns a plan, a correction, or a stop
+signal, and the executor resumes. The advisor never calls tools or produces
+user-facing output.
+```
+
+## E. Cost levers
+
+Output size is the advisor's largest cost driver; the top-level `max_tokens`
+parameter does not bound it (pages 1, 4, 6). A tool-definition
+`max_tokens: 2048` cuts mean advisor output roughly 7x with near-zero
+truncation; `1024` cuts roughly 10x and truncates about 10% of calls. The
+server passes the advisor its remaining budget, so the advisor self-shapes
+its reply length.
+
+The brevity line belongs in the user message and addresses the advisor
+directly; the wording lives under **Brevity cue** in
+[`advisor-tool.md`](../../../docs/references/advisor-tool.md).
+
+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
+lowering total cost.
+
+Typical advisor output runs 400–700 text tokens, or 1,400–1,800 with
+thinking included.
+
+Advisor-side caching breaks even at roughly three consults per conversation;
+set it once and leave it. A `clear_thinking` setting with `keep` other than
+`"all"` shifts the advisor's quoted transcript and causes advisor-side cache
+misses.
+
+`max_uses` caps consults per request; Anthropic's launch example sets
+`max_uses: 3`. Conversation-level caps count client-side; dropping the tool
+requires stripping every `advisor_tool_result` block from history, or the API
+returns 400.
+
+## F. Failure modes and API mechanics
+
+Error codes the advisor call surfaces (pages 1, 6): `max_uses_exceeded`,
+`too_many_requests`, `overloaded`, `prompt_too_long`,
+`execution_time_exceeded`, `unavailable`, `model_not_found`.
+
+```text
+The executor sees the error and continues without further advice. The
+request itself does not fail.
+```
+
+The advisor runs without tools and without context management; thinking
+blocks are dropped, and only advice text returns. On the server side,
+nothing the executor puts in `input` reaches the advisor — the server
+forwards the full transcript itself.
+
+Fable, Opus 5, and Mythos advisors return `advisor_redacted_result`
+(encrypted, round-trips verbatim). Opus 4.8 and below return plaintext
+`advisor_result`. A native Fable-class advisor's encrypted block carries no
+guidance the client can read; when logging or auditing the guidance matters,
+pick a plaintext-returning advisor — the hand-rolled CLI and warm-agent
+paths always yield a readable transcript.
+
+Pairing invariant: "The advisor must be at least as capable as the
+executor." Claude Code enforces the same check per subagent — subagents
+inherit the configured advisor and apply the same pairing check against
+their own model.
+
+The native advisor is a server tool with no name a permission rule or hook
+matcher can reference, so it bypasses hooks. The bind this skill uses lives
+in [`SKILL.md`](../SKILL.md) **Bind**.
+
+Consults run slow enough to look like stalls: changelog 2.1.214 (page 7)
+fixes a spurious "check your network" warning that appeared while the
+advisor was thinking.
+
+Usage accounting: each consult is an `advisor_message` entry in
+`usage.iterations[]` with its own model and token counts, billed at advisor
+rates.
+
+## G. What transfers to the hand-rolled advisor path
+
+The claude-dev-env advisor is a warm agent or CLI session. Three inversions
+apply against the native server tool:
+
+1. **Context forwarding is manual.** The native tool auto-forwards the full
+   transcript. Everything a hand-rolled advisor sees arrives in the consult.
+   Build the first packet with
+   [`_shared/advisor/reference/consult-format.md`](../../../_shared/advisor/reference/consult-format.md);
+   later consults carry only the delta.
+2. **Caching becomes prefix stability.** The charter and role text stay
+   byte-stable at the top of the consult stream; volatile detail goes last.
+3. **Hooks apply.** Consult payloads travel through ordinary tools, so each
+   payload stays hook-safe and the bind log is mechanically validated.
+
+## H. Measuring the advisor's lift
+
+Repository practice, sourced to no page: benchmark three routes on one
+representative workload — the executor alone, the executor plus advisor, and
+the strongest model throughout. Route future work by measured cost per
+successful task.
+
+Track, per route: completion rate, regression rate, tool calls, tokens by
+tier, and latency.