claude-dev-env 2.7.1 → 2.9.0

package/docs/references/advisor-tool.md

@@ -1,13 +1,51 @@
 # Advisor Tool
 
-`advisor()` is a review tool backed by a stronger reviewer model. It takes no parameters — calling it forwards the entire conversation history automatically, so the reviewer sees the task, every tool call made, and every result seen so far.
+Canonical consult timing and weight for any stronger-reviewer path: the native `advisor()` tool, `/team-advisor`, and the shared warm advisor.
 
-## When to call it
+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.
 
-Call `advisor()` before substantive work: before writing, before committing to an interpretation, before building on an assumption. Orientation work — finding files, fetching a source, seeing what exists — comes first; call `advisor()` once that orientation is done and before the substantive step begins.
+## What it is
 
-Treat the advisor as more experienced than the calling agent. Consult it whenever a path forward is uncertain.
+`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.
 
-## Availability
+When `advisor()` is absent, use `/team-advisor` (see `team-advisor-skill.md`).
 
-`advisor()` is present only in environments where it has been configured as a tool. Check the available tools before relying on it; when it is absent, fall back to `/team-advisor` (see `team-advisor-skill.md` in this directory).
+## When to call
+
+Call **before substantive work** — before writing, before locking an interpretation, before building on an assumption.
+
+If the task needs orientation first (find files, fetch a source, see what exists), do that, then call. Orientation is not substantive work. Writing, editing, and declaring an answer are.
+
+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 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.
+
+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.
+
+## Hard rule
+
+Your first write, edit, or state-changing shell call on a task must be preceded by an advisor call in the same or an earlier turn. Read-only orientation (`ls`, `cat`, `grep`, `find`, and harness equivalents) is not state-changing. This is a checkpoint, not a difficulty judgment. It applies to one-line edits too.
+
+## How to treat advice
+
+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?" A reconcile call is cheaper than the wrong branch.
+
+## Brevity cue
+
+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.)`
+
+## 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 |

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

@@ -1,14 +1,20 @@
-# Team-Advisor Skill Invocation
+# Team-Advisor Skill
 
-`/team-advisor` spawns a standing review agent for the session at the strongest reachable model tier, run at the highest reasoning effort. Use it to get a second opinion from a distinct model line than the one driving the session. For example:
+`/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.
 
-- Claude session -> consult Fable xhigh
-- Codex session -> consult Sol xhigh
+## Refs
 
-## When to use it
+| Doc | Holds |
+|---|---|
+| `skills/team-advisor/SKILL.md` | Sole-consumer bind wiring and constraints |
+| `advisor-tool.md` | Consult timing, hard rule, how to treat advice |
+| `~/.claude/_shared/advisor/advisor-protocol.md` | Host bind, floor, lifecycle |
+| `agents/session-advisor.md` | ENDORSE / CORRECTION / PLAN / STOP |
 
-Consult the spawned advisor before big decisions, before declaring work complete, before any commit, when a failure repeats, or when reconsidering a chosen approach.
+## When to use
 
-## Relationship to the advisor tool
+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).
 
-`/team-advisor` works standalone; it needs no `advisor()` tool present. When both are available (see `advisor-tool.md` in this directory), use `advisor()` for a fast, history-forwarding check before substantive work, and `/team-advisor` for a standing reviewer consulted at decision points.
+## Relation to `advisor()`
+
+`/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.

package/hooks/blocking/CLAUDE.md

@@ -85,6 +85,7 @@ The check modules it calls are the `code_rules_<concern>.py` files below.
 | `eli11_reply_enforcer.py` | Stop | Final replies breaking the `eli11-replies` shape — more than 120 reader-visible words, more than 6 bullet lines, more than 2 lines carrying over 20 words each, or instruction lines telling the user to act with no numbered step among the lead lines. Code fences, inline code, blockquotes, table rows, and link targets come off before the reply is judged, replies under 60 words always pass, and a reply opening with `Long form:` opts out entirely |
 | `env_var_table_code_drift_blocker.py` | PreToolUse (Write/Edit/MultiEdit) | A markdown env-var summary table row attributing an environment variable to a code file whose source never references that variable name |
 | `es_exe_path_rewriter.py` | PreToolUse | Rewrites paths referencing `.exe` under the Everything search path |
+| `fable_spawn_gate.py` | PreToolUse (Agent/Task) | An `Agent` or `Task` spawn whose prompt carries no `FABLE-SPAWN-AUTHORIZED` token and whose model field reads `fable` in any letter case — the bare alias, or a delimiter segment of a full model id, so `claude-fable-5` is denied too |
 | `gh_body_arg_blocker.py` | PreToolUse (Bash) | `gh` commands passing `--body`/`-b` directly (requires `--body-file` instead) |
 | `gh_pr_author_enforcer.py` | PreToolUse | Enforces PR author identity rules |
 | `gh_pr_author_restore.py` | PostToolUse | Restores PR author after a tool call |
@@ -98,6 +99,7 @@ The check modules it calls are the `code_rules_<concern>.py` files below.
 | `pii_payload_scan.py` | library | Write/Edit and durable post-body PII evaluation reused by `pii_prevention_blocker.py` |
 | `pii_prevention_blocker.py` | PreToolUse (Write/Edit/MultiEdit/Bash/PowerShell/MCP GitHub) | Entry hook — content that carries high-confidence personal data or secrets (real emails, home-dir paths, private IPs, credential material) on write, durable GitHub posts, or staged commit paths; resolves the staged-commit repository from the command it gates (via `pii_prevention_blocker_parts`), not the session working directory |
 | `pii_scanner.py` | library | Pure text scanners shared by `pii_prevention_blocker.py` |
+| `piped_pytest_blocker.py` | PreToolUse (Bash) | A pytest run whose output feeds a pipe, where the pipeline reports the exit code of the command on the right |
 | `plain_language_blocker.py` | PreToolUse (Write/Edit/AskUserQuestion) | Heavy or jargon words in user-facing prose |
 | `pr_converge_bugteam_enforcer.py` | PreToolUse | Enforces that bugteam runs in parallel with bugbot in pr-converge loops |
 | `pr_description_enforcer.py` | PreToolUse (Bash) | `gh pr create`/`edit`/`comment` bodies that fail the Anthropic claude-code style audit, proof-shaped `gh pr comment` bodies missing proof-of-work parts, and `gh pr ready` while the PR carries no passing proof comment |

package/hooks/blocking/fable_spawn_gate.py

@@ -0,0 +1,187 @@
+#!/usr/bin/env python3
+"""PreToolUse gate: deny a fable-tier subagent spawn that carries no marker.
+
+One exact token in the spawn prompt authorizes a spawn at the fable tier::
+
+    model: fable,           no FABLE-SPAWN-AUTHORIZED   flag: deny
+    model: claude-fable-5,  no FABLE-SPAWN-AUTHORIZED   flag: deny
+    model: fable,           FABLE-SPAWN-AUTHORIZED      ok:   allow
+    model: claude-sonnet-4, prompt either way           ok:   allow
+    no model field,         prompt either way           ok:   allow
+
+The gate reads an ``Agent`` or ``Task`` call and finds the tier in the model
+field whether that field carries the bare alias or a full model id, in any
+letter case. Its deny reason points at the advisor-protocol document rather
+than quoting the token, so a denial pasted into a retry authorizes nothing.
+A deny also sets ``additionalContext`` so the spawner sees the recovery path
+(re-spawn at opus / an opus-equivalent tier, or authorize a fable bind).
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import Mapping, TextIO
+
+_hooks_dir = str(Path(__file__).resolve().parent.parent)
+if _hooks_dir not in sys.path:
+    sys.path.insert(0, _hooks_dir)
+
+from hooks_constants.fable_spawn_gate_constants import (  # noqa: E402
+    ALL_SPAWN_TOOL_NAMES,
+    CALLING_HOOK_NAME,
+    DENY_ADDITIONAL_CONTEXT,
+    DENY_PREVIEW_TEMPLATE,
+    DENY_REASON,
+    FABLE_MODEL_ALIAS,
+    FABLE_SPAWN_AUTHORIZATION_MARKER,
+    HOOK_EVENT_NAME,
+    MAXIMUM_PREVIEW_MODEL_LENGTH,
+    MODEL_FIELD_NAME,
+    MODEL_SEGMENT_SPLIT_PATTERN,
+    PROMPT_FIELD_NAME,
+    TOOL_INPUT_FIELD_NAME,
+    TOOL_NAME_FIELD_NAME,
+)
+from hooks_constants.hook_block_logger import log_hook_block  # noqa: E402
+from hooks_constants.pre_tool_use_stdin import (  # noqa: E402
+    read_hook_input_dictionary_from_stdin,
+)
+
+
+def _model_names_the_fable_tier(model_identifier: str) -> bool:
+    """Report whether a model string names the fable tier.
+
+    The field carries either the bare alias or a full model id, so the
+    lowercased string is cut on its delimiters and the tier is looked for as
+    a whole segment::
+
+        fable            -> ['fable']                 flag: fable tier
+        claude-fable-5   -> ['claude', 'fable', '5']  flag: fable tier
+        claude-sonnet-4  -> ['claude', 'sonnet', '4'] ok:   another tier
+        affable          -> ['affable']               ok:   another tier
+
+    Args:
+        model_identifier: The spawn's ``model`` string.
+
+    Returns:
+        True when a model segment reads ``fable`` in any letter case; False
+        for another tier.
+    """
+    all_segments = MODEL_SEGMENT_SPLIT_PATTERN.split(model_identifier.strip().lower())
+    return FABLE_MODEL_ALIAS in all_segments
+
+
+def _prompt_carries_authorization_marker(all_tool_input: Mapping[str, object]) -> bool:
+    """Report whether the spawn prompt holds the exact authorization token.
+
+    Args:
+        all_tool_input: The spawn's ``tool_input`` mapping.
+
+    Returns:
+        True when the prompt is a string holding the marker token; False for
+        an unmarked prompt and for an absent or non-string field.
+    """
+    spawn_prompt = all_tool_input.get(PROMPT_FIELD_NAME)
+    if not isinstance(spawn_prompt, str):
+        return False
+    return FABLE_SPAWN_AUTHORIZATION_MARKER in spawn_prompt
+
+
+def _denied_spawn_model(all_payload_by_field: Mapping[str, object]) -> str | None:
+    """Return the model string of an unauthorized fable spawn, or None.
+
+    The model string travels back as the decision, so the deny path holds a
+    proven fable string and never re-derives one.
+
+    Args:
+        all_payload_by_field: The parsed PreToolUse payload, keyed by
+            top-level field name.
+
+    Returns:
+        The ``model`` string for a spawn tool call at the fable tier whose
+        prompt lacks the authorization marker; None for every allowed call.
+    """
+    if all_payload_by_field.get(TOOL_NAME_FIELD_NAME, "") not in ALL_SPAWN_TOOL_NAMES:
+        return None
+    tool_input = all_payload_by_field.get(TOOL_INPUT_FIELD_NAME, {})
+    if not isinstance(tool_input, dict):
+        return None
+    model_identifier = tool_input.get(MODEL_FIELD_NAME)
+    if not isinstance(model_identifier, str):
+        return None
+    if not _model_names_the_fable_tier(model_identifier):
+        return None
+    if _prompt_carries_authorization_marker(tool_input):
+        return None
+    return model_identifier
+
+
+def _build_denial_preview(model_identifier: str) -> str:
+    """Build the bounded preview the hook-blocks log records for a denial.
+
+    The preview names the model field that tripped the gate, so its length
+    holds steady whatever the spawn prompt carries::
+
+        fable           -> model=fable marker_present=False
+        claude-fable-5  -> model=claude-fable-5 marker_present=False
+
+    Args:
+        model_identifier: The fable model string the denial was decided on.
+
+    Returns:
+        One preview line naming the model text and the marker state.
+    """
+    return DENY_PREVIEW_TEMPLATE.format(
+        model_text=model_identifier[:MAXIMUM_PREVIEW_MODEL_LENGTH]
+    )
+
+
+def _emit_denial(
+    decision_stream: TextIO,
+    all_payload_by_field: Mapping[str, object],
+    model_identifier: str,
+) -> None:
+    """Log the denied spawn and write the PreToolUse deny payload.
+
+    Args:
+        decision_stream: Writable text stream — production code passes
+            ``sys.stdout``; tests pass a ``StringIO`` to capture the JSON.
+        all_payload_by_field: The parsed PreToolUse payload, whose tool name
+            names the denied spawn in the hook-blocks log.
+        model_identifier: The fable model string the denial was decided on.
+    """
+    denial = {
+        "hookSpecificOutput": {
+            "hookEventName": HOOK_EVENT_NAME,
+            "permissionDecision": "deny",
+            "permissionDecisionReason": DENY_REASON,
+            "additionalContext": DENY_ADDITIONAL_CONTEXT,
+        }
+    }
+    log_hook_block(
+        calling_hook_name=CALLING_HOOK_NAME,
+        hook_event=HOOK_EVENT_NAME,
+        block_reason=DENY_REASON,
+        tool_name=str(all_payload_by_field.get(TOOL_NAME_FIELD_NAME, "")),
+        offending_input_preview=_build_denial_preview(model_identifier),
+    )
+    decision_stream.write(json.dumps(denial) + "\n")
+    decision_stream.flush()
+
+
+def main() -> None:
+    """Read the PreToolUse payload and deny an unmarked fable spawn."""
+    hook_payload = read_hook_input_dictionary_from_stdin()
+    if hook_payload is None:
+        sys.exit(0)
+    denied_model = _denied_spawn_model(hook_payload)
+    if denied_model is None:
+        sys.exit(0)
+    _emit_denial(sys.stdout, hook_payload, denied_model)
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()