claude-dev-env 2.10.0 → 2.12.0

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.

package/skills/usage-pause/SKILL.md

@@ -44,7 +44,7 @@ On exit 2 the script prints `{"error": ...}`. Ask the user for a manual reset ti
 In short: the resolver picks a bearer token, probes the OAuth usage endpoint the interactive `/usage` panel uses, and returns the session and weekly buckets with utilization and reset times. Token sources depend on the host:
 
 - **Desktop host** (the `CLAUDE_CODE_ENTRYPOINT` variable is `claude-desktop`): the resolver does not read the CLI credential file, which belongs to a different authentication session than the one the desktop app counts usage against. It uses the session ingress token when one is set, and otherwise takes the manual-override path.
-- **Every other host**: the resolver reads the Claude Code CLI's stored OAuth access token first (honored only while unexpired), then the session ingress bearer token file named by `CLAUDE_SESSION_INGRESS_TOKEN_FILE` (cloud sessions) when the credential token is unavailable.
+- **Every other host**: the resolver reads the Claude Code CLI's stored OAuth access token first (honored only while unexpired), then the session ingress bearer token file named by `CLAUDE_SESSION_INGRESS_TOKEN_FILE` (cloud sessions) when the credential token is unavailable. The credential file lives under the directory `CLAUDE_CONFIG_DIR` names when that variable is set — a profile-isolated session's own account — else the home-directory default; the home file on a multi-profile machine can belong to a different account, whose meter is the wrong one to read.
 
 Fallbacks, in order: both token sources unavailable (expired/unreadable credential and no ingress file), a failed request, or a response with no readable session-window reset time all end in exit 2 — the manual-override ask above. The manual path works with no probe at all, so the skill functions even when both token sources are unavailable.
 

package/skills/usage-pause/scripts/resolve_usage_window.py

@@ -9,8 +9,10 @@
 
 With no ``--override``, the script resolves a bearer token. On the desktop
 host it uses only the session ingress token. On every other host it reads the
-Claude Code OAuth access token from the CLI credential file, then the session
-ingress token file when that credential is unavailable. It asks the OAuth
+Claude Code OAuth access token from the CLI credential file — under the
+directory ``CLAUDE_CONFIG_DIR`` names when set, else the home-directory
+default — then the session ingress token file when that credential is
+unavailable. It asks the OAuth
 usage endpoint for the ``five_hour`` and ``seven_day`` windows. Exit code 2
 means the probe cannot resolve; the caller then asks the user for a manual
 reset time.
@@ -38,10 +40,12 @@ from usage_pause_constants.resolve_usage_window_constants import (
     BARE_MINUTES_PATTERN,
     CLOCK_HOUR_MAXIMUM,
     CLOCK_PATTERN,
+    CONFIG_DIR_ENV_VAR,
     CONTENT_TYPE_HEADER_NAME,
     CONTENT_TYPE_JSON,
     CREDENTIALS_ACCESS_TOKEN_KEY,
     CREDENTIALS_EXPIRES_AT_KEY,
+    CREDENTIALS_FILE_NAME,
     CREDENTIALS_OAUTH_SECTION_KEY,
     DESKTOP_ENTRYPOINT_VALUE,
     DURATION_PATTERN,
@@ -203,6 +207,27 @@ def plan_wakeup_stages(seconds_until_reset: int) -> list[int]:
     return stages
 
 
+def default_credentials_path() -> Path:
+    """Locate the CLI credential file for the account this session runs as.
+
+    ::
+
+        CLAUDE_CONFIG_DIR=C:/profiles/mel  ->  C:/profiles/mel/.credentials.json
+        (variable unset or empty)          ->  ~/.claude/.credentials.json
+
+    A profile-isolated session keeps its credential under the config-dir
+    directory. On such a machine the home file belongs to a different
+    account. Reading the home file reports that other account's meter.
+
+    Returns:
+        The credential file for the session's own account.
+    """
+    config_directory = os.environ.get(CONFIG_DIR_ENV_VAR)
+    if config_directory:
+        return Path(config_directory) / CREDENTIALS_FILE_NAME
+    return Path.home().joinpath(*ALL_CREDENTIALS_RELATIVE_PATH_PARTS)
+
+
 def read_oauth_access_token(credentials_path: Path, now: datetime) -> str | None:
     """Read the CLI's OAuth access token when it is still valid.
 
@@ -523,7 +548,10 @@ def _parse_arguments() -> argparse.Namespace:
     parser.add_argument(
         "--credentials-path",
         default=None,
-        help="Path to the CLI credential file; defaults to the home-directory location.",
+        help=(
+            "Path to the CLI credential file; defaults to the CLAUDE_CONFIG_DIR "
+            "location when that variable is set, else the home-directory location."
+        ),
     )
     return parser.parse_args()
 
@@ -558,7 +586,7 @@ def main() -> int:
     credentials_path = (
         Path(arguments.credentials_path)
         if arguments.credentials_path
-        else Path.home().joinpath(*ALL_CREDENTIALS_RELATIVE_PATH_PARTS)
+        else default_credentials_path()
     )
     access_token = resolve_access_token(credentials_path, now)
     if access_token is None:

package/skills/usage-pause/scripts/test_resolve_usage_window.py

@@ -19,6 +19,7 @@ if str(SCRIPTS_DIRECTORY) not in sys.path:
     sys.path.insert(0, str(SCRIPTS_DIRECTORY))
 
 from usage_pause_constants.resolve_usage_window_constants import (  # noqa: E402
+    CONFIG_DIR_ENV_VAR,
     DESKTOP_ENTRYPOINT_VALUE,
     ENTRYPOINT_ENV_VAR,
     SESSION_INGRESS_TOKEN_FILE_ENV_VAR as INGRESS_TOKEN_FILE_ENV_VAR,
@@ -195,6 +196,31 @@ class TestReadOauthAccessToken:
         assert any("unreadable" in each_message for each_message in caplog.messages)
 
 
+class TestDefaultCredentialsPath:
+    def should_use_the_config_dir_credential_file_when_the_variable_is_set(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        resolver = load_resolver_module()
+        monkeypatch.setenv(CONFIG_DIR_ENV_VAR, str(tmp_path))
+        assert resolver.default_credentials_path() == tmp_path / ".credentials.json"
+
+    def should_fall_back_to_the_home_credential_file_when_the_variable_is_unset(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        resolver = load_resolver_module()
+        monkeypatch.delenv(CONFIG_DIR_ENV_VAR, raising=False)
+        expected = Path.home() / ".claude" / ".credentials.json"
+        assert resolver.default_credentials_path() == expected
+
+    def should_fall_back_to_the_home_credential_file_when_the_variable_is_empty(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        resolver = load_resolver_module()
+        monkeypatch.setenv(CONFIG_DIR_ENV_VAR, "")
+        expected = Path.home() / ".claude" / ".credentials.json"
+        assert resolver.default_credentials_path() == expected
+
+
 class TestReadSessionIngressToken:
     def should_return_stripped_token_from_the_named_file(
         self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch

package/skills/usage-pause/scripts/usage_pause_constants/resolve_usage_window_constants.py

@@ -19,6 +19,8 @@ CONTENT_TYPE_JSON = "application/json"
 PROBE_TIMEOUT_SECONDS = 10
 
 ALL_CREDENTIALS_RELATIVE_PATH_PARTS = (".claude", ".credentials.json")
+CONFIG_DIR_ENV_VAR = "CLAUDE_CONFIG_DIR"
+CREDENTIALS_FILE_NAME = ".credentials.json"
 CREDENTIALS_OAUTH_SECTION_KEY = "claudeAiOauth"
 CREDENTIALS_ACCESS_TOKEN_KEY = "accessToken"
 CREDENTIALS_EXPIRES_AT_KEY = "expiresAt"
@@ -67,4 +69,4 @@ SOURCE_OVERRIDE = "override"
 EXIT_CODE_RESOLVED = 0
 EXIT_CODE_PROBE_UNAVAILABLE = 2
 
-LOGGING_FORMAT = "%(levelname)s %(name)s: %(message)s"
+LOGGING_FORMAT = "%(levelname)s %(name)s: %(message)s"