claude-dev-env 8.117.4 → 8.117.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -26,6 +26,8 @@ On tasks longer than a few steps, aim for an early approach consult and a comple
26
26
 
27
27
  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.
28
28
 
29
+ A session that runs on the advisor model itself plans no advisor consults. A consult there would ask the same model for a second opinion. The rules on this page, the hard rule included, apply only to a session on another model. [Session context hooks](../../hooks/features/session-context.md) covers how the SessionStart prompt tells the two apart.
30
+
29
31
  ## Hard rule
30
32
 
31
33
  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.
@@ -8,7 +8,7 @@ This family injects reminders and task guidance when an agent starts, resumes, s
8
8
  - `session/compaction_recall_prompt.py` returns every message the user typed after a compaction. `session/compaction_user_messages.py` reads them from a Claude Code transcript or a Codex rollout. `session/compaction_trim.py` trims each one in Python: it drops filler, articles, and gratitude, keeps approvals, continuation requests, backtick spans, and paths as typed, and marks a reversed message `(overruled by #N)`. No model runs, so the hook works on Claude Code and Codex with no account.
9
9
  - `session/task_tool_prompt.py` injects a task tracking directive at session start.
10
10
  - `session/working_style_prompt.py` injects the session's working style at session start.
11
- - `session/advisor_rules_prompt.py` injects advisor guidance when the built-in advisor is enabled. For evidence on when an advisor pays, see [Subagents and fan-out](../../docs/model-choice/subagents-and-fan-out.md).
11
+ - `session/advisor_rules_prompt.py` injects advisor guidance when the built-in advisor is enabled. It stays silent when the SessionStart payload's `model` is the `advisorModel` value or is in its family, such as `claude-fable-5-2` against `fable`. When the payload has no `model`, the guidance names the advisor model and tells a session on that model to plan no consults. For evidence on when an advisor pays, see [Subagents and fan-out](../../docs/model-choice/subagents-and-fan-out.md).
12
12
  - `session/orchestrator_auto_starter.py` injects an orchestrator directive when its environment flag is enabled.
13
13
  - `session/plugin_session_baseline_writer.py` records each plugin's `version` and `installPath` from `installed_plugins.json` to a per-session file in the system temp folder. It writes on `startup`, or when the session has no baseline yet, and leaves an existing baseline alone on `resume`, `clear`, and `compact`.
14
14
  - `session/plugin_change_warning.py` compares `installed_plugins.json` with that baseline before each prompt. It names each plugin whose version or install path changed, or that the baseline lacks, once per session, and tells the user to restart Claude Code.
@@ -38,7 +38,7 @@ Preconditions:
38
38
  - **Compaction recall.** Input is a Claude Code transcript or a Codex rollout with typed, meta, sidechain, peer, and harness entries across a compaction. Run `python -m pytest packages/claude-dev-env/hooks/session/test_compaction_user_messages.py packages/claude-dev-env/hooks/session/test_compaction_trim.py packages/claude-dev-env/hooks/session/test_compaction_recall_prompt.py packages/claude-dev-env/hooks/session/test_compaction_trim_eval.py -q`. The tests observe only typed messages, a stable result across a second compaction, the trim rules, the recall budget, and the trimmed lines in the hook's `additionalContext`. `python packages/claude-dev-env/hooks/session/compaction_trim_eval.py` trims each fixture transcript with planted facts, prints the share of facts that survive, the reversals marked, and the compression ratio, and exits 1 on any loss.
39
39
  - **Task tracking.** Input is a SessionStart event. Run `python -m pytest packages/claude-dev-env/hooks/session/test_task_tool_prompt.py -q`. The adjacent test observes a `SessionStart` context directive that names the task tool.
40
40
  - **Working style.** Input is a SessionStart event. Run `python -m pytest packages/claude-dev-env/hooks/session/test_working_style_prompt.py -q`. The adjacent test observes the fixed context text.
41
- - **Advisor guidance.** Input is SessionStart with `advisorModel` set. Run `python -m pytest packages/claude-dev-env/hooks/session/test_advisor_rules_prompt.py -q`. The adjacent test observes guidance only when the advisor setting is enabled.
41
+ - **Advisor guidance.** Input is SessionStart with `advisorModel` set. Run `python -m pytest packages/claude-dev-env/hooks/session/test_advisor_rules_prompt.py -q`. The adjacent test observes guidance only when the advisor setting is enabled and the payload's model is in another family or absent, and silence when the payload's model is the advisor model or shares its family.
42
42
  - **Orchestrator start.** Input is SessionStart with its opt-in flag set. Run `python -m pytest packages/claude-dev-env/hooks/session/test_orchestrator_auto_starter.py -q`. The adjacent test observes an orchestrator directive.
43
43
  - **Plugin restart warning.** Input is a SessionStart event, an `installed_plugins.json` change, and a prompt. Run `python -m pytest packages/claude-dev-env/hooks/session/test_plugin_session_baseline_writer.py packages/claude-dev-env/hooks/session/test_plugin_change_warning.py packages/claude-dev-env/hooks/test_plugin_session_baseline.py -q`. The tests observe one warning for a changed version, a changed install path, and a plugin new since start, silence on a `lastUpdated` refresh and on a second prompt, and a warning that still fires after a `compact` SessionStart.
44
44
  - **Artifact template pointer.** Input is an `Artifact` quickstart call. Run `python -m pytest packages/claude-dev-env/hooks/session/test_artifact_template_pointer.py -q`. The adjacent test observes the status flowchart path first, the html-plan path ahead of the template path in `additionalContext`, and silence on a publish call or another skill.
@@ -51,6 +51,6 @@ Preconditions:
51
51
  - The recall keeps the first message and the newest that fit in 6,000 characters, under the 2,500 token preview limit Codex applies to hook context. A message over 1,500 characters is cut, and the line says how much was left out.
52
52
  - The overruled mark comes from cue phrases such as `instead` or `change of plan` and shared words. A reversal with no cue phrase gets no mark, and the later line still overrides by its place. A cue in a message that agrees with an earlier one, such as `dont use haiku` after `use Python trim instead of Haiku`, marks that earlier line too, so the context tells the agent to follow the later message where the two differ.
53
53
  - `session/skill_loaded_reminder.py` has three registration points. An `Agent` or `Task` helper gets no poteto-mode line from it; a brief that needs the skill names it, or spawns `pstack:poteto-agent`. Its tests cover the compaction restore, the workflow helper reminder, silence on a user turn while the skill stays loaded, silence on a spawn payload, and no `PreToolUse` registration in `hooks.json`.
54
- - The advisor prompt depends on settings and an environment disable flag. The two starter scripts each use separate opt-in checks.
54
+ - The advisor prompt depends on settings, an environment disable flag, and the payload's `model`. Claude Code 2.1.325 sends `model` on an interactive `claude` start and leaves it out under `claude -p` and the desktop app's stream-json launch, so those sessions get the guidance with the advisor model named. The two starter scripts each use separate opt-in checks.
55
55
  - The issue tracker starter requires the checkout to appear in the project path registry.
56
56
  - `advisory/auto_mode_denial_quick_fix.py` lives under `advisory/` but belongs here because its only output is agent context and a one-line user message.
@@ -3,6 +3,8 @@
3
3
  Each sentence in ``ALL_ADVISOR_RULE_SENTENCES`` is copied word for word from
4
4
  ``docs/references/advisor-tool.md``, which stays the one source. A
5
5
  synchronization test fails when a sentence drifts from that document.
6
+ ``ADVISOR_RULES_PROMPT_TEMPLATE`` takes the configured advisor model as
7
+ ``advisor_model``.
6
8
  """
7
9
 
8
10
  from __future__ import annotations
@@ -10,28 +12,34 @@ from __future__ import annotations
10
12
  __all__ = [
11
13
  "ADVISOR_DISABLE_ENV_VAR",
12
14
  "ADVISOR_MODEL_SETTINGS_KEY",
13
- "ADVISOR_RULES_HEADER",
14
- "ADVISOR_RULES_PROMPT",
15
+ "ADVISOR_RULES_HEADER_TEMPLATE",
16
+ "ADVISOR_RULES_PROMPT_TEMPLATE",
15
17
  "ALL_ADVISOR_RULE_SENTENCES",
16
18
  "ALL_ADVISOR_DISABLE_ENV_TRUE_VALUES",
19
+ "ALL_MODEL_FAMILY_NAMES",
17
20
  "CLAUDE_CONFIG_DIR_ENV_VAR",
18
21
  "DEFAULT_CLAUDE_CONFIG_DIRECTORY_NAME",
22
+ "SESSION_MODEL_PAYLOAD_KEY",
19
23
  "USER_SETTINGS_FILE_NAME",
20
24
  ]
21
25
 
22
26
  ADVISOR_MODEL_SETTINGS_KEY = "advisorModel"
27
+ SESSION_MODEL_PAYLOAD_KEY = "model"
28
+ ALL_MODEL_FAMILY_NAMES = ("fable", "opus", "sonnet", "haiku")
23
29
  ADVISOR_DISABLE_ENV_VAR = "CLAUDE_CODE_DISABLE_ADVISOR_TOOL"
24
30
  ALL_ADVISOR_DISABLE_ENV_TRUE_VALUES = frozenset({"1", "true", "yes", "on"})
25
31
  CLAUDE_CONFIG_DIR_ENV_VAR = "CLAUDE_CONFIG_DIR"
26
32
  DEFAULT_CLAUDE_CONFIG_DIRECTORY_NAME = ".claude"
27
33
  USER_SETTINGS_FILE_NAME = "settings.json"
28
34
 
29
- ADVISOR_RULES_HEADER = (
30
- "ADVISOR, when `advisor` is in your tool list. Use your own judgment on when a"
31
- " consult helps. Starting points from ~/.claude/docs/references/advisor-tool.md:"
35
+ ADVISOR_RULES_HEADER_TEMPLATE = (
36
+ "ADVISOR, when `advisor` is in your tool list. The advisor runs on `{advisor_model}`."
37
+ " Use your own judgment on when a consult helps."
38
+ " Starting points from ~/.claude/docs/references/advisor-tool.md:"
32
39
  )
33
40
 
34
41
  ALL_ADVISOR_RULE_SENTENCES = (
42
+ "A session that runs on the advisor model itself plans no advisor consults.",
35
43
  "Call for design, architecture, and risk questions where you will not touch a file.",
36
44
  "On tasks longer than a few steps, aim for an early approach consult and a completion review.",
37
45
  "This cadence guides planning and leaves the task free to follow its evidence.",
@@ -41,4 +49,4 @@ ALL_ADVISOR_RULE_SENTENCES = (
41
49
  "Give the advice serious weight.",
42
50
  )
43
51
 
44
- ADVISOR_RULES_PROMPT = " ".join((ADVISOR_RULES_HEADER, *ALL_ADVISOR_RULE_SENTENCES))
52
+ ADVISOR_RULES_PROMPT_TEMPLATE = " ".join((ADVISOR_RULES_HEADER_TEMPLATE, *ALL_ADVISOR_RULE_SENTENCES))
@@ -6,6 +6,10 @@ adds the team-advisor starting points, such as a consult on a design question,
6
6
  and leaves each call to the session's judgment. It emits them only when the user settings carry an
7
7
  ``advisorModel`` value and ``CLAUDE_CODE_DISABLE_ADVISOR_TOOL`` is not set, so a
8
8
  session without the advisor is never told to call it.
9
+ It also stays silent when the SessionStart payload's ``model`` is the
10
+ ``advisorModel`` value or belongs to its model family, so a session is never
11
+ told to consult itself. When the payload has no ``model``, the guidance names the advisor model
12
+ so the session can tell for itself.
9
13
  The hook writes nothing and runs no tools itself.
10
14
  """
11
15
 
@@ -23,14 +27,17 @@ if _hooks_directory not in sys.path:
23
27
  from hooks_constants.advisor_rules_prompt_constants import (
24
28
  ADVISOR_DISABLE_ENV_VAR,
25
29
  ADVISOR_MODEL_SETTINGS_KEY,
26
- ADVISOR_RULES_PROMPT,
30
+ ADVISOR_RULES_PROMPT_TEMPLATE,
27
31
  ALL_ADVISOR_DISABLE_ENV_TRUE_VALUES,
32
+ ALL_MODEL_FAMILY_NAMES,
28
33
  CLAUDE_CONFIG_DIR_ENV_VAR,
29
34
  DEFAULT_CLAUDE_CONFIG_DIRECTORY_NAME,
35
+ SESSION_MODEL_PAYLOAD_KEY,
30
36
  USER_SETTINGS_FILE_NAME,
31
37
  )
32
38
  from hooks_constants.mod_handoff import is_mod_plugin_enabled
33
39
  from hooks_constants.mod_handoff_constants import SESSION_PROMPTS_PLUGIN_NAME
40
+ from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
34
41
 
35
42
 
36
43
  def user_settings_path() -> Path:
@@ -47,30 +54,67 @@ def is_advisor_disabled_by_environment() -> bool:
47
54
  return raw_value in ALL_ADVISOR_DISABLE_ENV_TRUE_VALUES
48
55
 
49
56
 
50
- def is_advisor_configured(settings_path: Path) -> bool:
51
- """Return True when the settings file names a non-empty advisor model."""
57
+ def configured_advisor_model(settings_path: Path) -> str | None:
58
+ """Return the settings file's non-empty advisor model, or None."""
52
59
  try:
53
60
  settings = json.loads(settings_path.read_text(encoding="utf-8"))
54
61
  except (OSError, ValueError):
55
- return False
62
+ return None
56
63
  if not isinstance(settings, dict):
57
- return False
64
+ return None
58
65
  advisor_model = settings.get(ADVISOR_MODEL_SETTINGS_KEY)
59
- return isinstance(advisor_model, str) and advisor_model.strip() != ""
66
+ if not isinstance(advisor_model, str) or not advisor_model.strip():
67
+ return None
68
+ return advisor_model.strip()
69
+
70
+
71
+ def model_family(model_name: str) -> str | None:
72
+ """Return the family an alias or full model id names, or None.
73
+
74
+ ::
75
+
76
+ "fable" -> "fable" "claude-fable-5-2" -> "fable"
77
+ "claude-mythos-1" -> None
78
+ """
79
+ lowered_model_name = model_name.lower()
80
+ for each_family_name in ALL_MODEL_FAMILY_NAMES:
81
+ if each_family_name in lowered_model_name:
82
+ return each_family_name
83
+ return None
84
+
85
+
86
+ def runs_on_advisor_model(session_model: object, advisor_model: str) -> bool:
87
+ """Return True when the session model is the advisor model or shares its known family.
88
+
89
+ ::
90
+
91
+ "claude-fable-5-2", "fable" -> True "claude-mythos-1", "claude-mythos-1" -> True
92
+ "claude-opus-5-5", "fable" -> False "claude-mythos-1", "custom-advisor" -> False
93
+ """
94
+ if not isinstance(session_model, str):
95
+ return False
96
+ if session_model.strip().lower() == advisor_model.lower():
97
+ return True
98
+ session_family = model_family(session_model)
99
+ return session_family is not None and session_family == model_family(advisor_model)
60
100
 
61
101
 
62
102
  def main() -> None:
63
- """Emit the advisor guidance as SessionStart additionalContext when the advisor is on and the session-prompts mod is off."""
103
+ """Emit the advisor guidance as SessionStart additionalContext when the advisor is on, the session runs on another model, and the session-prompts mod is off."""
64
104
  if is_mod_plugin_enabled(SESSION_PROMPTS_PLUGIN_NAME):
65
105
  return
66
106
  if is_advisor_disabled_by_environment():
67
107
  return
68
- if not is_advisor_configured(user_settings_path()):
108
+ advisor_model = configured_advisor_model(user_settings_path())
109
+ if advisor_model is None:
110
+ return
111
+ session_start_payload = read_hook_input_dictionary_from_stdin() or {}
112
+ if runs_on_advisor_model(session_start_payload.get(SESSION_MODEL_PAYLOAD_KEY), advisor_model):
69
113
  return
70
114
  session_start_output = {
71
115
  "hookSpecificOutput": {
72
116
  "hookEventName": "SessionStart",
73
- "additionalContext": ADVISOR_RULES_PROMPT,
117
+ "additionalContext": ADVISOR_RULES_PROMPT_TEMPLATE.format(advisor_model=advisor_model),
74
118
  }
75
119
  }
76
120
  sys.stdout.write(json.dumps(session_start_output) + "\n")
@@ -19,19 +19,30 @@ import advisor_rules_prompt as starter
19
19
 
20
20
  from hooks_constants.advisor_rules_prompt_constants import (
21
21
  ADVISOR_DISABLE_ENV_VAR,
22
- ADVISOR_RULES_PROMPT,
23
22
  ALL_ADVISOR_RULE_SENTENCES,
24
23
  CLAUDE_CONFIG_DIR_ENV_VAR,
25
24
  )
26
25
 
27
26
 
28
- def _run_main() -> str:
27
+ def _run_main(session_start_payload: object = "") -> str:
28
+ stdin_text = (
29
+ session_start_payload
30
+ if isinstance(session_start_payload, str)
31
+ else json.dumps(session_start_payload)
32
+ )
29
33
  captured_stdout = StringIO()
30
- with patch("sys.stdout", captured_stdout):
34
+ with patch("sys.stdin", StringIO(stdin_text)), patch("sys.stdout", captured_stdout):
31
35
  starter.main()
32
36
  return captured_stdout.getvalue()
33
37
 
34
38
 
39
+ def _session_start_payload(session_model: str | None) -> dict[str, str]:
40
+ payload = {"hook_event_name": "SessionStart", "source": "startup"}
41
+ if session_model is not None:
42
+ payload["model"] = session_model
43
+ return payload
44
+
45
+
35
46
  @pytest.fixture
36
47
  def config_directory(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
37
48
  monkeypatch.setenv(CLAUDE_CONFIG_DIR_ENV_VAR, str(tmp_path))
@@ -49,7 +60,62 @@ class TestAdvisorRulesPrompt:
49
60
  _write_settings(config_directory, {"advisorModel": "fable"})
50
61
  hook_output = json.loads(_run_main())["hookSpecificOutput"]
51
62
  assert hook_output["hookEventName"] == "SessionStart"
52
- assert hook_output["additionalContext"] == ADVISOR_RULES_PROMPT
63
+ for each_rule_sentence in ALL_ADVISOR_RULE_SENTENCES:
64
+ assert each_rule_sentence in hook_output["additionalContext"]
65
+
66
+ def test_should_name_the_configured_advisor_model(self, config_directory: Path) -> None:
67
+ _write_settings(config_directory, {"advisorModel": "fable"})
68
+ hook_output = json.loads(_run_main())["hookSpecificOutput"]
69
+ assert "The advisor runs on `fable`." in hook_output["additionalContext"]
70
+
71
+ @pytest.mark.parametrize(
72
+ ("advisor_model", "session_model"),
73
+ [
74
+ ("fable", "claude-fable-5-2"),
75
+ ("claude-fable-5-2", "claude-fable-5-2"),
76
+ ("opus", "claude-opus-5-5[1m]"),
77
+ ("claude-opus-4-7", "claude-opus-5"),
78
+ ("claude-mythos-1", "claude-mythos-1"),
79
+ ("Custom-Advisor", "custom-advisor"),
80
+ ],
81
+ )
82
+ def test_should_emit_nothing_when_session_runs_on_the_advisor_model(
83
+ self, config_directory: Path, advisor_model: str, session_model: str
84
+ ) -> None:
85
+ _write_settings(config_directory, {"advisorModel": advisor_model})
86
+ assert _run_main(_session_start_payload(session_model)) == ""
87
+
88
+ @pytest.mark.parametrize(
89
+ ("advisor_model", "session_model"),
90
+ [
91
+ ("fable", "claude-opus-5-5"),
92
+ ("opus", "claude-sonnet-5-5"),
93
+ ("fable", "claude-mythos-1"),
94
+ ("custom-advisor", "claude-fable-5-2"),
95
+ ("custom-advisor", "claude-mythos-1"),
96
+ ],
97
+ )
98
+ def test_should_emit_rules_when_session_runs_on_another_model(
99
+ self, config_directory: Path, advisor_model: str, session_model: str
100
+ ) -> None:
101
+ _write_settings(config_directory, {"advisorModel": advisor_model})
102
+ hook_output = json.loads(_run_main(_session_start_payload(session_model)))
103
+ assert hook_output["hookSpecificOutput"]["hookEventName"] == "SessionStart"
104
+
105
+ @pytest.mark.parametrize("session_start_payload", [_session_start_payload(None), "", "{not json", "[]"])
106
+ def test_should_emit_rules_when_payload_names_no_model(
107
+ self, config_directory: Path, session_start_payload: object
108
+ ) -> None:
109
+ _write_settings(config_directory, {"advisorModel": "fable"})
110
+ hook_output = json.loads(_run_main(session_start_payload))
111
+ assert hook_output["hookSpecificOutput"]["hookEventName"] == "SessionStart"
112
+
113
+ def test_should_emit_rules_when_payload_model_is_not_a_string(
114
+ self, config_directory: Path
115
+ ) -> None:
116
+ _write_settings(config_directory, {"advisorModel": "fable"})
117
+ hook_output = json.loads(_run_main({"hook_event_name": "SessionStart", "model": 5}))
118
+ assert hook_output["hookSpecificOutput"]["hookEventName"] == "SessionStart"
53
119
 
54
120
  def test_should_emit_nothing_when_advisor_model_is_missing(
55
121
  self, config_directory: Path
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "claude-dev-env",
3
- "version": "8.117.4",
3
+ "version": "8.117.5",
4
4
  "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
5
5
  "type": "module",
6
6
  "bin": {