claude-dev-env 8.72.0 → 8.72.2

package/bin/install.mjs

@@ -1247,6 +1247,7 @@ export const RETIRED_HOOK_REGISTRATION_RELATIVE_PATHS = new Set([
     'blocking/send_user_file_open_locally_blocker.py',
     'blocking/question_to_user_enforcer.py',
     'blocking/session_handoff_blocker.py',
+    'session/issue_tracker_session_starter.py',
 ]);
 
 export const MOVED_HOOK_RELATIVE_PATHS = new Set([

package/bin/install.test.mjs

@@ -1230,6 +1230,7 @@ test('retired hook registrations stay managed so reinstall removes them', () =>
         'blocking/send_user_file_open_locally_blocker.py',
         'blocking/question_to_user_enforcer.py',
         'blocking/session_handoff_blocker.py',
+        'session/issue_tracker_session_starter.py',
     ]);
     const shippedHooks = JSON.parse(
         readFileSync(new URL('../hooks/hooks.json', import.meta.url), 'utf8')

package/docs/rule-guides/asd-ste100-language.md

@@ -28,6 +28,7 @@ definitions and dictionary decisions.
 - Use inclusive, neutral language.
 - Use periods, commas, colons, and bullets to show structure.
 - Preserve exact quoted labels, identifiers, formulas, titles, and interface text.
+- Say each fact once in content read together. Preserve accessible text alternatives for pictures and essential prerequisites or warnings at each point of use.
 - Send the reader only a result, a blocker, or a question. Leave out a line that says nothing is needed from them, and leave out which agent, session, or coordinator did the work.
 - Use `WARNING` for a risk of injury or death. Use `CAUTION` for a risk of equipment, tool, or machine damage. State the command or condition first, then state the result.
 - Aim for 20 words or fewer in a procedure sentence when the technical content allows.
@@ -38,5 +39,14 @@ and durable repository text. Named contracts can add behavior-specific structure
 question routing, current-state documentation, completion, docstring, or publication rules.
 Those contracts use this policy for their language.
 
+## Repeated-points check
+
+Run this check on each reply or page you draft, before you send it. Run it also when asked to check text for repeated points.
+
+1. List each fact the text states, with where it appears. Include each fact that a picture, diagram, or table shows: its labels, its order, what moves, and the end state it draws.
+2. Mark repeated facts within content read together. Exclude accessibility text, alternate representations, and prerequisites or warnings needed at each point of use.
+3. Keep each marked fact in the one place that shows it best. Delete each other statement of it, or rewrite that line to carry a new fact. Outside these exceptions, a bullet under a picture keeps only what the picture cannot show, such as a cause, a condition, a command, or a warning.
+4. Keep routine self-check results silent. When asked to review repeated points, report each restatement you removed, or report that each fact appears once.
+
 Treat automated output and language checks as drafting aids. A responsible human verifies
 technical accuracy, terminology, safety, confidentiality, and intended meaning.

package/hooks/blocking/bash_pre_tool_use_dispatcher.py

@@ -41,6 +41,7 @@ from hooks_constants.hosted_hook_runner import (
     HostedHookRun,
     resolved_hook_script_path,
 )
+from hooks_constants.mod_handoff import is_mod_plugin_enabled
 
 _PERMISSION_DECISION_KEY = "permissionDecision"
 _PERMISSION_REASON_KEY = "permissionDecisionReason"
@@ -87,11 +88,18 @@ class _ParsedHookDecision:
 
 
 def select_applicable_entries(tool_name: str) -> list[BashHostedHookEntry]:
-    """Return the ordered hosted-hook entries that apply to tool_name."""
+    """Return the ordered hosted-hook entries that apply to tool_name.
+
+    An entry whose mod plugin is on drops out, because the mod does its work.
+    """
     return [
         each_entry
         for each_entry in ALL_BASH_HOSTED_HOOK_ENTRIES
         if tool_name in each_entry.applicable_tool_names
+        and not (
+            each_entry.replaced_by_plugin_name is not None
+            and is_mod_plugin_enabled(each_entry.replaced_by_plugin_name)
+        )
     ]
 
 

package/hooks/blocking/headless_claude_broker_gate.py

@@ -9,6 +9,9 @@ The broker form runs ``python``, so its ``-- claude -p ...`` tail passes.
 Interactive ``claude`` and its subcommands, such as ``claude plugin eval`` or
 ``claude --version``, pass.
 
+A Claude Code cloud session, where ``CLAUDE_CODE_REMOTE`` is ``true``, has one
+account, so the gate passes every command there.
+
 Hosted by ``blocking/bash_pre_tool_use_dispatcher.py`` for the Bash and
 PowerShell tools.
 """
@@ -16,6 +19,7 @@ PowerShell tools.
 from __future__ import annotations
 
 import json
+import os
 import sys
 from pathlib import Path
 
@@ -34,6 +38,8 @@ try:
         BROKER_COMMAND_DENY_REASON,
         CLAUDE_PROFILE_LAUNCHER_PREFIX,
         CLAUDE_PROGRAM_NAME,
+        CLOUD_SESSION_ENV_TRUE_VALUE,
+        CLOUD_SESSION_ENV_VAR,
         GATE_HOOK_NAME,
         PRINT_MODE_LONG_FLAG_WITH_VALUE_PREFIX,
     )
@@ -113,8 +119,15 @@ def starts_unbrokered_headless_claude(command: str) -> bool:
     )
 
 
+def is_cloud_session() -> bool:
+    """Return True when this hook runs inside a Claude Code cloud session."""
+    return os.environ.get(CLOUD_SESSION_ENV_VAR, "").strip().lower() == CLOUD_SESSION_ENV_TRUE_VALUE
+
+
 def main() -> None:
-    """Deny a headless Claude start that skips the broker, or stay quiet."""
+    """Deny a headless Claude start that skips the broker outside a cloud session, or stay quiet."""
+    if is_cloud_session():
+        return
     hook_payload = read_hook_input_dictionary_from_stdin()
     if hook_payload is None:
         return

package/hooks/blocking/test_bash_dispatcher_interpreter_starts.py

@@ -31,9 +31,11 @@ def test_bash_roster_starts_only_the_msys_rewriter_and_the_two_gates() -> None:
         BashHostedHookEntry(
             script_relative_path="blocking/headless_claude_broker_gate.py",
             applicable_tool_names=ALL_BASH_AND_POWERSHELL_TOOL_NAMES,
+            replaced_by_plugin_name="shell-guards",
         ),
         BashHostedHookEntry(
             script_relative_path="blocking/gh_global_account_switch_gate.py",
             applicable_tool_names=ALL_BASH_AND_POWERSHELL_TOOL_NAMES,
+            replaced_by_plugin_name="shell-guards",
         ),
     )

package/hooks/blocking/test_bash_pre_tool_use_dispatcher.py

@@ -251,3 +251,49 @@ def test_emit_decision_sends_a_rewrite_through_the_permission_prompt(
     assert hook_specific["updatedInput"] == {
         "command": "MSYS2_ARG_CONV_EXCL='*' git show HEAD:a.py"
     }
+
+
+def _enable_shell_guards(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    """Turn the shell-guards plugin on in a temp user settings file."""
+    user_directory = tmp_path / "user-config"
+    user_directory.mkdir()
+    (user_directory / "settings.json").write_text(
+        json.dumps({"enabledPlugins": {"shell-guards@mods-marketplace": True}}), encoding="utf-8"
+    )
+    monkeypatch.setenv("CLAUDE_CONFIG_DIR", str(user_directory))
+    monkeypatch.delenv("CLAUDE_CODE_REMOTE", raising=False)
+    monkeypatch.setenv("CLAUDE_PROJECT_DIR", str(tmp_path))
+
+
+def test_should_drop_the_gates_the_shell_guards_mod_holds_while_it_is_on(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    _enable_shell_guards(tmp_path, monkeypatch)
+    all_script_paths = [each_entry.script_relative_path for each_entry in select_applicable_entries(BASH_TOOL_NAME)]
+    assert all_script_paths == ["blocking/msys_rev_path_rewriter.py"]
+
+
+def test_should_pass_a_headless_claude_command_while_the_shell_guards_mod_is_on(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    _enable_shell_guards(tmp_path, monkeypatch)
+    completed = subprocess.run(
+        [sys.executable, _DISPATCHER_SCRIPT],
+        check=False,
+        input=_bash_payload("claude -p 'say hello'"),
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        env={**os.environ},
+    )
+    assert _decision_from_stdout(completed.stdout) == ("", "")
+
+
+def test_should_deny_a_headless_claude_command_while_no_mod_is_on(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setenv("CLAUDE_CONFIG_DIR", str(tmp_path))
+    monkeypatch.delenv("CLAUDE_CODE_REMOTE", raising=False)
+    monkeypatch.setenv("CLAUDE_PROJECT_DIR", str(tmp_path))
+    completed = _run_process(_DISPATCHER_SCRIPT, _bash_payload("claude -p 'say hello'"))
+    assert _decision_from_stdout(completed.stdout)[0] == "deny"

package/hooks/blocking/test_headless_claude_broker_gate.py

@@ -86,3 +86,15 @@ def test_broker_command_payload_emits_nothing() -> None:
 
 def test_other_tool_payload_emits_nothing() -> None:
     assert _stdout_from_main({"tool_name": "Write", "tool_input": {"command": 'claude -p "task"'}}) == ""
+
+
+def test_should_pass_bare_headless_claude_in_a_cloud_session(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("CLAUDE_CODE_REMOTE", "true")
+    assert _stdout_from_main({"tool_name": "Bash", "tool_input": {"command": 'claude -p "task"'}}) == ""
+
+
+def test_should_report_a_cloud_session_only_when_the_marker_is_true(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("CLAUDE_CODE_REMOTE", "false")
+    assert gate.is_cloud_session() is False
+    monkeypatch.setenv("CLAUDE_CODE_REMOTE", "true")
+    assert gate.is_cloud_session() is True

package/hooks/conftest.py

@@ -22,6 +22,10 @@ _CLAUDE_SESSION_ID_ENVIRONMENT_VARIABLE_NAME = importlib.import_module(
     "hooks_constants.harness_scratchpad_constants"
 ).CLAUDE_SESSION_ID_ENVIRONMENT_VARIABLE_NAME
 
+_CLOUD_SESSION_ENVIRONMENT_VARIABLE_NAME = importlib.import_module(
+    "hooks_constants.headless_claude_broker_gate_constants"
+).CLOUD_SESSION_ENV_VAR
+
 _ROOT_ANCHORED_PROBE_PATH = "/tmp/scratch.py"
 
 
@@ -40,6 +44,20 @@ def isolate_from_live_session_scratchpad(monkeypatch: pytest.MonkeyPatch) -> Non
     monkeypatch.delenv(_CLAUDE_SESSION_ID_ENVIRONMENT_VARIABLE_NAME, raising=False)
 
 
+@pytest.fixture(autouse=True)
+def isolate_from_live_cloud_session(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Remove the cloud session marker before each hooks test.
+
+    A Claude Code cloud session exports CLAUDE_CODE_REMOTE=true, and gates
+    that stand aside in cloud would then pass every case. Tests that exercise the
+    cloud path set the variable themselves.
+
+    Args:
+        monkeypatch: Pytest's environment-variable patcher, torn down after the test.
+    """
+    monkeypatch.delenv(_CLOUD_SESSION_ENVIRONMENT_VARIABLE_NAME, raising=False)
+
+
 @pytest.fixture
 def ephemeral_exempt_off(monkeypatch: pytest.MonkeyPatch) -> None:
     """Turn off the ephemeral scratch-path exemption for the current test.

package/hooks/features/session-context.md

@@ -9,14 +9,13 @@ This family injects reminders and task guidance when an agent starts, resumes, s
 - `session/working_style_prompt.py` injects the session's working style at session start.
 - `session/advisor_rules_prompt.py` injects advisor guidance when the built-in advisor is enabled.
 - `session/orchestrator_auto_starter.py` injects an orchestrator directive when its environment flag is enabled.
-- `session/issue_tracker_session_starter.py` injects issue tracker guidance when enabled for a registered repository.
 - `session/artifact_template_pointer.py` points an agent that starts an artifact page at `docs/templates/html-plan/README.md`. When the request names the older artifact page template, it points at `docs/templates/artifact-page/README.md`, which names the tracker template and the diagram template and which ask each fits.
 - `advisory/auto_mode_denial_quick_fix.py` proposes one `autoMode.allow` entry and a PowerShell block that writes it after an auto mode denial. It never retries the denied call.
 
 ## When it fires
 
 - `session/skill_loaded_reminder.py` runs on `PreToolUse` matcher `Agent|Task` at `10` seconds, `UserPromptSubmit` matcher empty at `10` seconds, `SessionStart` matcher `compact` at `10` seconds, and `SubagentStart` matcher `workflow-subagent` at `10` seconds in `hooks.json`.
-- `session/task_tool_prompt.py`, `session/working_style_prompt.py`, `session/advisor_rules_prompt.py`, `session/orchestrator_auto_starter.py`, and `session/issue_tracker_session_starter.py` run on `SessionStart`, matcher empty, timeout `10` seconds each in `hooks.json`.
+- `session/task_tool_prompt.py`, `session/working_style_prompt.py`, `session/advisor_rules_prompt.py`, and `session/orchestrator_auto_starter.py` run on `SessionStart`, matcher empty, timeout `10` seconds each in `hooks.json`.
 - `session/artifact_template_pointer.py` runs on `PreToolUse` matcher `Artifact|Skill` at `10` seconds in `hooks.json`. It speaks only on an `Artifact` call with action `quickstart` or a `Skill` call that loads `artifact-design`.
 - `advisory/auto_mode_denial_quick_fix.py` runs on `PermissionDenied`, matcher `*`, timeout `10` seconds in `hooks.json`.
 
@@ -31,7 +30,6 @@ Preconditions:
 - **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.
 - **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.
 - **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.
-- **Issue tracker start.** Input is SessionStart with its opt-in flag and a registered checkout. Run `python -m pytest packages/claude-dev-env/hooks/session/test_issue_tracker_session_starter.py -q`. The adjacent test observes issue tracker context.
 - **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 html-plan path ahead of the template path in `additionalContext`, and silence on a publish call or another skill.
 - **Denial quick fix.** Input is a `PermissionDenied` event with a bracketed rule label and a classifier verdict. Run `python -m pytest packages/claude-dev-env/hooks/advisory/test_auto_mode_denial_quick_fix.py -q`. The adjacent test observes the named rule, the allow entry, and the PowerShell block; a denial with no verdict gets a note and no block.
 

package/hooks/hooks.json

@@ -279,11 +279,6 @@
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/session/orchestrator_auto_starter.py",
             "timeout": 10
           },
-          {
-            "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/session/issue_tracker_session_starter.py",
-            "timeout": 10
-          },
           {
             "type": "command",
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/lifecycle/nested_project_hooks.py",

package/hooks/hooks_constants/bash_pre_tool_use_dispatcher_constants.py

@@ -9,6 +9,8 @@ from __future__ import annotations
 
 from dataclasses import dataclass
 
+from hooks_constants.mod_handoff_constants import SHELL_GUARDS_PLUGIN_NAME
+
 __all__ = [
     "DENY_DECISION",
     "ASK_DECISION",
@@ -48,10 +50,14 @@ class BashHostedHookEntry:
         script_relative_path: Hook path relative to the hooks/ directory.
         applicable_tool_names: Tool names this hook runs for. The dispatcher
             skips the hook when the payload's tool is not in this set.
+        replaced_by_plugin_name: The plugin whose mod holds this hook. The
+            dispatcher skips the hook while that plugin is on, so a session
+            runs the hook or the mod and never both.
     """
 
     script_relative_path: str
     applicable_tool_names: frozenset[str]
+    replaced_by_plugin_name: str | None = None
 
 
 ALL_BASH_HOSTED_HOOK_ENTRIES: tuple[BashHostedHookEntry, ...] = (
@@ -62,9 +68,11 @@ ALL_BASH_HOSTED_HOOK_ENTRIES: tuple[BashHostedHookEntry, ...] = (
     BashHostedHookEntry(
         script_relative_path="blocking/headless_claude_broker_gate.py",
         applicable_tool_names=ALL_BASH_AND_POWERSHELL_TOOL_NAMES,
+        replaced_by_plugin_name=SHELL_GUARDS_PLUGIN_NAME,
     ),
     BashHostedHookEntry(
         script_relative_path="blocking/gh_global_account_switch_gate.py",
         applicable_tool_names=ALL_BASH_AND_POWERSHELL_TOOL_NAMES,
+        replaced_by_plugin_name=SHELL_GUARDS_PLUGIN_NAME,
     ),
 )

package/hooks/hooks_constants/headless_claude_broker_gate_constants.py

@@ -3,7 +3,9 @@
 Holds the Claude program name and its profile-launcher prefix, the Windows
 launcher suffixes stripped before the name check, the two print-mode flags, the
 hook name the block log records, and the deny message that names the broker
-command to run instead.
+command to run instead. It also names the environment variable a Claude Code
+cloud session sets, where the gate stands aside because the session has one
+account.
 """
 
 from __future__ import annotations
@@ -16,6 +18,8 @@ __all__ = [
     "PRINT_MODE_LONG_FLAG_WITH_VALUE_PREFIX",
     "GATE_HOOK_NAME",
     "BROKER_COMMAND_DENY_REASON",
+    "CLOUD_SESSION_ENV_VAR",
+    "CLOUD_SESSION_ENV_TRUE_VALUE",
 ]
 
 CLAUDE_PROGRAM_NAME: str = "claude"
@@ -24,6 +28,8 @@ ALL_WINDOWS_LAUNCHER_SUFFIXES: tuple[str, ...] = (".cmd", ".exe", ".ps1", ".bat"
 ALL_PRINT_MODE_FLAGS: frozenset[str] = frozenset({"-p", "--print"})
 PRINT_MODE_LONG_FLAG_WITH_VALUE_PREFIX: str = "--print="
 GATE_HOOK_NAME: str = "headless_claude_broker_gate.py"
+CLOUD_SESSION_ENV_VAR: str = "CLAUDE_CODE_REMOTE"
+CLOUD_SESSION_ENV_TRUE_VALUE: str = "true"
 BROKER_COMMAND_DENY_REASON: str = (
     "BLOCKED: Start a headless Claude session through the account broker. "
     "Run: python \"$HOME/.claude/scripts/account_broker.py\" run --product claude "

package/hooks/hooks_constants/mod_handoff.py

@@ -0,0 +1,91 @@
+"""Tell a settings hook whether the mod plugin that holds its work is on.
+
+Claude Code reads ``enabledPlugins`` from the user settings file, then the
+project's ``.claude/settings.json``, then its ``.claude/settings.local.json``,
+and a later file overrides an earlier one. A key names a plugin as
+``<plugin>@<marketplace>``, so a match on the plugin name holds wherever the
+plugin ships.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+from hooks_constants.mod_handoff_constants import (
+    ALL_SETTINGS_FILE_NAMES_IN_PRECEDENCE_ORDER,
+    CLOUD_SESSION_ENV_TRUE_VALUE,
+    CLOUD_SESSION_ENV_VAR,
+    CLAUDE_CONFIG_DIR_ENV_VAR,
+    CLAUDE_PROJECT_DIR_ENV_VAR,
+    DEFAULT_CLAUDE_CONFIG_DIRECTORY_NAME,
+    ENABLED_PLUGINS_SETTINGS_KEY,
+    PLUGIN_MARKETPLACE_SEPARATOR,
+    PROJECT_SETTINGS_DIRECTORY_NAME,
+    USER_SETTINGS_FILE_NAME,
+)
+
+
+def all_settings_paths_in_precedence_order() -> list[Path]:
+    """Return the user, project and local settings files, lowest precedence first."""
+    configured_directory = os.environ.get(CLAUDE_CONFIG_DIR_ENV_VAR, "").strip()
+    user_directory = (
+        Path(configured_directory)
+        if configured_directory
+        else Path.home() / DEFAULT_CLAUDE_CONFIG_DIRECTORY_NAME
+    )
+    all_paths = [user_directory / USER_SETTINGS_FILE_NAME]
+    project_directory = os.environ.get(CLAUDE_PROJECT_DIR_ENV_VAR, "").strip() or os.getcwd()
+    project_settings_directory = Path(project_directory) / PROJECT_SETTINGS_DIRECTORY_NAME
+    all_paths.extend(
+        project_settings_directory / each_file_name
+        for each_file_name in ALL_SETTINGS_FILE_NAMES_IN_PRECEDENCE_ORDER
+    )
+    return all_paths
+
+
+def plugin_state_in_settings_file(settings_path: Path, plugin_name: str) -> bool | None:
+    """Return the file's on or off setting for plugin_name, or None when it names none.
+
+    Args:
+        settings_path: A Claude Code settings file.
+        plugin_name: The plugin name before the ``@marketplace`` part of the key.
+    """
+    try:
+        settings = json.loads(settings_path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return None
+    if not isinstance(settings, dict):
+        return None
+    enabled_plugins = settings.get(ENABLED_PLUGINS_SETTINGS_KEY)
+    if not isinstance(enabled_plugins, dict):
+        return None
+    all_states = [
+        each_state
+        for each_key, each_state in enabled_plugins.items()
+        if isinstance(each_key, str)
+        and isinstance(each_state, bool)
+        and each_key.split(PLUGIN_MARKETPLACE_SEPARATOR, 1)[0] == plugin_name
+    ]
+    if not all_states:
+        return None
+    return any(all_states)
+
+
+def is_mod_plugin_enabled(plugin_name: str) -> bool:
+    """Return True when the settings files leave plugin_name on outside a cloud session.
+
+    A cloud session runs no mods, so it keeps every hook whatever the settings say.
+
+    Args:
+        plugin_name: The plugin that holds the mod replacing the calling hook.
+    """
+    if os.environ.get(CLOUD_SESSION_ENV_VAR, "").strip().lower() == CLOUD_SESSION_ENV_TRUE_VALUE:
+        return False
+    is_enabled = False
+    for each_path in all_settings_paths_in_precedence_order():
+        state = plugin_state_in_settings_file(each_path, plugin_name)
+        if state is not None:
+            is_enabled = state
+    return is_enabled

package/hooks/hooks_constants/mod_handoff_constants.py

@@ -0,0 +1,38 @@
+"""Names a settings hook reads to tell whether a mod plugin holds its work.
+
+A converted hook stays silent when the plugin that holds its mod is on in
+``enabledPlugins``, so a session runs the hook or the mod and never both.
+"""
+
+from __future__ import annotations
+
+__all__ = [
+    "ALL_SETTINGS_FILE_NAMES_IN_PRECEDENCE_ORDER",
+    "CLOUD_SESSION_ENV_TRUE_VALUE",
+    "CLOUD_SESSION_ENV_VAR",
+    "CLAUDE_CONFIG_DIR_ENV_VAR",
+    "CLAUDE_PROJECT_DIR_ENV_VAR",
+    "DEFAULT_CLAUDE_CONFIG_DIRECTORY_NAME",
+    "ENABLED_PLUGINS_SETTINGS_KEY",
+    "PLUGIN_MARKETPLACE_SEPARATOR",
+    "PROJECT_SETTINGS_DIRECTORY_NAME",
+    "SESSION_PROMPTS_PLUGIN_NAME",
+    "SHELL_GUARDS_PLUGIN_NAME",
+    "USER_SETTINGS_FILE_NAME",
+]
+
+ENABLED_PLUGINS_SETTINGS_KEY = "enabledPlugins"
+CLOUD_SESSION_ENV_VAR = "CLAUDE_CODE_REMOTE"
+CLOUD_SESSION_ENV_TRUE_VALUE = "true"
+PLUGIN_MARKETPLACE_SEPARATOR = "@"
+SHELL_GUARDS_PLUGIN_NAME = "shell-guards"
+SESSION_PROMPTS_PLUGIN_NAME = "session-prompts"
+CLAUDE_CONFIG_DIR_ENV_VAR = "CLAUDE_CONFIG_DIR"
+CLAUDE_PROJECT_DIR_ENV_VAR = "CLAUDE_PROJECT_DIR"
+DEFAULT_CLAUDE_CONFIG_DIRECTORY_NAME = ".claude"
+PROJECT_SETTINGS_DIRECTORY_NAME = ".claude"
+USER_SETTINGS_FILE_NAME = "settings.json"
+ALL_SETTINGS_FILE_NAMES_IN_PRECEDENCE_ORDER: tuple[str, ...] = (
+    "settings.json",
+    "settings.local.json",
+)

package/hooks/hooks_constants/test_bash_pre_tool_use_dispatcher_constants.py

@@ -12,7 +12,7 @@ ALL_BASH_AND_POWERSHELL_TOOL_NAMES = ALL_CONSTANT_BINDINGS["ALL_BASH_AND_POWERSH
 BashHostedHookEntry = ALL_CONSTANT_BINDINGS["BashHostedHookEntry"]
 
 
-def test_roster_hosts_the_msys_rewriter_the_broker_gate_and_the_gh_account_gate() -> None:
+def test_roster_hosts_the_three_gates_and_hands_two_to_the_shell_guards_mod() -> None:
     assert ALL_BASH_HOSTED_HOOK_ENTRIES == (
         BashHostedHookEntry(
             script_relative_path="blocking/msys_rev_path_rewriter.py",
@@ -21,9 +21,11 @@ def test_roster_hosts_the_msys_rewriter_the_broker_gate_and_the_gh_account_gate(
         BashHostedHookEntry(
             script_relative_path="blocking/headless_claude_broker_gate.py",
             applicable_tool_names=ALL_BASH_AND_POWERSHELL_TOOL_NAMES,
+            replaced_by_plugin_name="shell-guards",
         ),
         BashHostedHookEntry(
             script_relative_path="blocking/gh_global_account_switch_gate.py",
             applicable_tool_names=ALL_BASH_AND_POWERSHELL_TOOL_NAMES,
+            replaced_by_plugin_name="shell-guards",
         ),
     )

package/hooks/hooks_constants/test_mod_handoff.py

@@ -0,0 +1,100 @@
+"""Behavioral tests for the mod handoff check that silences a converted hook."""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+import pytest
+
+_HOOKS_ROOT = Path(__file__).resolve().parent.parent
+if str(_HOOKS_ROOT) not in sys.path:
+    sys.path.insert(0, str(_HOOKS_ROOT))
+
+from hooks_constants.mod_handoff import (
+    all_settings_paths_in_precedence_order,
+    is_mod_plugin_enabled,
+    plugin_state_in_settings_file,
+)
+
+
+@pytest.fixture
+def settings_homes(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> tuple[Path, Path]:
+    """Point the user config and project directories at empty temp folders."""
+    user_directory = tmp_path / "user-config"
+    project_directory = tmp_path / "project"
+    (project_directory / ".claude").mkdir(parents=True)
+    user_directory.mkdir()
+    monkeypatch.setenv("CLAUDE_CONFIG_DIR", str(user_directory))
+    monkeypatch.setenv("CLAUDE_PROJECT_DIR", str(project_directory))
+    monkeypatch.delenv("CLAUDE_CODE_REMOTE", raising=False)
+    return user_directory, project_directory
+
+
+def _write_enabled_plugins(settings_path: Path, enabled_plugins: object) -> None:
+    settings_path.write_text(json.dumps({"enabledPlugins": enabled_plugins}), encoding="utf-8")
+
+
+def test_should_list_user_then_project_then_local_settings(
+    settings_homes: tuple[Path, Path],
+) -> None:
+    user_directory, project_directory = settings_homes
+    assert all_settings_paths_in_precedence_order() == [
+        user_directory / "settings.json",
+        project_directory / ".claude" / "settings.json",
+        project_directory / ".claude" / "settings.local.json",
+    ]
+
+
+def test_should_match_the_plugin_under_any_marketplace(tmp_path: Path) -> None:
+    settings_path = tmp_path / "settings.json"
+    _write_enabled_plugins(settings_path, {"shell-guards@any-marketplace": True})
+    assert plugin_state_in_settings_file(settings_path, "shell-guards") is True
+
+
+def test_should_report_no_state_for_a_plugin_the_file_never_names(tmp_path: Path) -> None:
+    settings_path = tmp_path / "settings.json"
+    _write_enabled_plugins(settings_path, {"shell-guards-extra@market": True})
+    assert plugin_state_in_settings_file(settings_path, "shell-guards") is None
+
+
+def test_should_report_no_state_for_a_missing_or_broken_file(tmp_path: Path) -> None:
+    broken_path = tmp_path / "broken.json"
+    broken_path.write_text("{not json", encoding="utf-8")
+    assert plugin_state_in_settings_file(tmp_path / "missing.json", "shell-guards") is None
+    assert plugin_state_in_settings_file(broken_path, "shell-guards") is None
+
+
+def test_should_stay_off_when_no_settings_file_names_the_plugin(
+    settings_homes: tuple[Path, Path],
+) -> None:
+    assert is_mod_plugin_enabled("session-prompts") is False
+
+
+def test_should_turn_on_from_the_user_settings(settings_homes: tuple[Path, Path]) -> None:
+    user_directory, _ = settings_homes
+    _write_enabled_plugins(user_directory / "settings.json", {"session-prompts@market": True})
+    assert is_mod_plugin_enabled("session-prompts") is True
+
+
+def test_should_let_local_project_settings_turn_a_user_plugin_off(
+    settings_homes: tuple[Path, Path],
+) -> None:
+    user_directory, project_directory = settings_homes
+    _write_enabled_plugins(user_directory / "settings.json", {"session-prompts@market": True})
+    _write_enabled_plugins(
+        project_directory / ".claude" / "settings.local.json", {"session-prompts@market": False}
+    )
+    assert is_mod_plugin_enabled("session-prompts") is False
+
+
+def test_should_keep_the_hook_in_a_cloud_session_with_the_plugin_on(
+    settings_homes: tuple[Path, Path], monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    _, project_directory = settings_homes
+    _write_enabled_plugins(
+        project_directory / ".claude" / "settings.json", {"session-prompts@market": True}
+    )
+    monkeypatch.setenv("CLAUDE_CODE_REMOTE", "true")
+    assert is_mod_plugin_enabled("session-prompts") is False

package/hooks/session/advisor_rules_prompt.py

@@ -29,6 +29,8 @@ from hooks_constants.advisor_rules_prompt_constants import (
     DEFAULT_CLAUDE_CONFIG_DIRECTORY_NAME,
     USER_SETTINGS_FILE_NAME,
 )
+from hooks_constants.mod_handoff import is_mod_plugin_enabled
+from hooks_constants.mod_handoff_constants import SESSION_PROMPTS_PLUGIN_NAME
 
 
 def user_settings_path() -> Path:
@@ -58,7 +60,9 @@ def is_advisor_configured(settings_path: Path) -> bool:
 
 
 def main() -> None:
-    """Emit the advisor guidance as SessionStart additionalContext when the advisor is on."""
+    """Emit the advisor guidance as SessionStart additionalContext when the advisor is on and the session-prompts mod is off."""
+    if is_mod_plugin_enabled(SESSION_PROMPTS_PLUGIN_NAME):
+        return
     if is_advisor_disabled_by_environment():
         return
     if not is_advisor_configured(user_settings_path()):

package/hooks/session/orchestrator_auto_starter.py

@@ -19,6 +19,8 @@ _hooks_dir = str(Path(__file__).resolve().parent.parent)
 if _hooks_dir not in sys.path:
     sys.path.insert(0, _hooks_dir)
 
+from hooks_constants.mod_handoff import is_mod_plugin_enabled
+from hooks_constants.mod_handoff_constants import SESSION_PROMPTS_PLUGIN_NAME
 from hooks_constants.orchestrator_auto_starter_constants import (  # noqa: E402
     ALL_ORCHESTRATOR_STARTER_ENABLED_ENV_VALUES,
     ORCHESTRATOR_AUTO_STARTER_ENABLED_ENV_VAR,
@@ -88,7 +90,9 @@ def run_orchestrator_auto_starter(
 
 
 def main() -> None:
-    """Emit orchestrator additionalContext when opt-in is enabled; else exit 0."""
+    """Emit orchestrator additionalContext when opt-in is enabled and the session-prompts mod is off; else exit 0."""
+    if is_mod_plugin_enabled(SESSION_PROMPTS_PLUGIN_NAME):
+        return
     payload_by_key = read_hook_input_dictionary_from_stdin()
     if payload_by_key is None:
         return

package/hooks/session/task_tool_prompt.py

@@ -14,6 +14,8 @@ import sys
 
 import _path_setup  # noqa: F401
 
+from hooks_constants.mod_handoff import is_mod_plugin_enabled
+from hooks_constants.mod_handoff_constants import SESSION_PROMPTS_PLUGIN_NAME
 from hooks_constants.task_tool_prompt_constants import TASK_TOOL_DIRECTIVE
 
 
@@ -23,7 +25,9 @@ def build_session_directive() -> str:
 
 
 def main() -> None:
-    """Emit the task-tool directive as SessionStart additionalContext."""
+    """Emit the task-tool directive as SessionStart additionalContext, unless the session-prompts mod is on."""
+    if is_mod_plugin_enabled(SESSION_PROMPTS_PLUGIN_NAME):
+        return
     payload = {
         "hookSpecificOutput": {
             "hookEventName": "SessionStart",