claude-dev-env 1.90.0 → 1.92.0

package/CLAUDE.md

@@ -4,19 +4,6 @@ The user is short on time and appreciates brevity in replies. When you reply, al
 
 The user delegates execution to you and expects zero manual steps unless strictly necessary. Execute every command you can directly. Only instruct the user to do something manually when you are technically unable to do it yourself. When a task involves credentials or other sensitive input, display a minimal secure UI (e.g., a password dialog) to collect it rather than asking the user to paste it into chat or run the command themselves. When direction is ambiguous, use AskUserQuestion to clarify before acting.
 
-You have access to an `advisor` tool backed by a stronger reviewer model. It takes NO parameters — when you call advisor(), your entire conversation history is automatically forwarded. They see the task, every tool call you've made, every result you've seen.
-
-Call advisor BEFORE substantive work — before writing, before committing to an interpretation, before building on an assumption. If the task requires orientation first (finding files, fetching a source, seeing what's there), do that, then call advisor. Orientation is not substantive work. Writing, editing, and declaring an answer are.
-
-Also call advisor:
-- When you believe the task is complete. BEFORE this call, make your deliverable durable: write the file, save the result, commit the change. The advisor call takes time; if the session ends during it, a durable result persists and an unwritten one doesn't.
-- When stuck — errors recurring, approach not converging, results that don't fit.
-- When considering a change of approach.
-
-On tasks longer than a few steps, call advisor 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 don't need to keep calling — the advisor adds most of its value on the first call, before the approach crystallizes.
-
-ALWAYS call the AskUserQuestion tool if you have a question for the user. Provide content-appropriate default options, with a flag for the recommended one.
-
 ## Timeless Documentation (all `.md` files)
 
 Every Markdown file I write or edit describes the system's **current** state only. The test: a reader a year out, with zero prior context, finds every sentence true and complete without knowing what came before. State what **is**, not what changed — git history records change; docs record the contract.

package/agents/clean-coder.md

@@ -159,7 +159,7 @@ Use logging for application and runtime output. `print()` is allowed when stdout
 
 ### Comment preservation
 
-Existing comments on lines that remain otherwise unchanged stay exactly as you found them. The hook enforces both directions: the gate fires on a new inline `#` or `//` in production code, and the gate also fires when an existing comment disappears from a line you touched. New code self-documents via names; new docstrings on functions, methods, classes, and modules remain allowed.
+Existing comments on lines you leave otherwise unchanged stay exactly as you found them. The hook treats the two directions differently: the gate fires and blocks the edit on a new inline `#` or `//` in production code, while an existing comment disappearing from a line you touched prints a stderr advisory and lets the edit through. New code self-documents via names; new docstrings on functions, methods, classes, and modules stay allowed.
 
 ### Centralized configuration
 
@@ -338,7 +338,7 @@ These gates are checked by `code_rules_enforcer.py`. Satisfying each gate lets y
 | Rule | What this rule looks for |
 |------|--------------------------|
 | Self-documenting names only | New `#` or `//` in production code (shebangs, `# type:`, `# noqa`, eslint-directives, docstrings exempt) |
-| Comment preservation | Removal of existing comments on lines that remain otherwise unchanged |
+| Comment preservation | Advisory — removal of existing comments on lines you leave otherwise unchanged prints a stderr advisory and does not block |
 | Imports at top | `import` statements placed inside function bodies |
 | Logging format | `log_*(f"...")` — replace with `log_*("...", arg)` |
 | File length | Advisory at 400 lines (soft), strong nudge at 1000 — emitted to stderr; the write proceeds |

package/agents/code-verifier.md

@@ -3,7 +3,6 @@ name: code-verifier
 description: Post-hoc verification agent for the two-phase code workflow. Spawned by the main session after coder agents finish. Runs every check itself in a fresh context — named gates, tests against recorded baselines, two-way diff-vs-task reading — and ends with a fenced verdict block the verifier_verdict_minter hook turns into the commit-gate verdict. Read and execute only; it never edits files.
 tools: Read, Grep, Glob, Bash
 model: sonnet
-effort: medium
 color: orange
 ---
 

package/agents/test_agent_frontmatter.py

@@ -0,0 +1,78 @@
+"""Behavior tests for agent-definition YAML frontmatter.
+
+Every agent `.md` in this directory opens with a frontmatter block the Claude
+Code subagent loader reads. The loader accepts a fixed key set; an unrecognized
+top-level key breaks the spawn — the subagent starts with a broken definition,
+idles, and dies without a report::
+
+    ok:   name / description / tools / model / color
+    flag: effort            <- unrecognized, subagent dies delivering nothing
+
+The accepted set is the one `agents/CLAUDE.md` documents (name, description,
+tools, color) plus the `model` pin the working agents carry (clean-coder pins
+opus, pr-description-writer pins haiku). Top-level keys are read with a line
+scan so an agent whose `description` embeds informal `<example>` prose is not
+mistaken for one carrying extra keys.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+import pytest
+import yaml
+
+ACCEPTED_FRONTMATTER_KEYS = frozenset(
+    {"name", "description", "tools", "model", "color"}
+)
+FRONTMATTER_FENCE = "---"
+FRONTMATTER_SEGMENT_COUNT = 3
+CODE_VERIFIER_AGENT_NAME = "code-verifier"
+TOP_LEVEL_KEY_PATTERN = re.compile(r"^([a-z][a-z0-9_]*):", re.MULTILINE)
+
+
+def _agent_definition_paths() -> list[Path]:
+    agents_directory = Path(__file__).parent
+    all_markdown_files = sorted(agents_directory.glob("*.md"))
+    return [
+        each_markdown_file
+        for each_markdown_file in all_markdown_files
+        if each_markdown_file.read_text(encoding="utf-8").startswith(FRONTMATTER_FENCE)
+    ]
+
+
+def _frontmatter_block(agent_definition_path: Path) -> str:
+    agent_text = agent_definition_path.read_text(encoding="utf-8")
+    fence_segments = agent_text.split(FRONTMATTER_FENCE, FRONTMATTER_SEGMENT_COUNT - 1)
+    return fence_segments[1]
+
+
+def _top_level_keys(frontmatter_block: str) -> set[str]:
+    return set(TOP_LEVEL_KEY_PATTERN.findall(frontmatter_block))
+
+
+@pytest.mark.parametrize(
+    "agent_definition_path",
+    _agent_definition_paths(),
+    ids=lambda each_path: each_path.name,
+)
+def test_agent_frontmatter_uses_only_accepted_keys(
+    agent_definition_path: Path,
+) -> None:
+    declared_keys = _top_level_keys(_frontmatter_block(agent_definition_path))
+    unaccepted_keys = declared_keys - ACCEPTED_FRONTMATTER_KEYS
+    assert not unaccepted_keys, (
+        f"{agent_definition_path.name} carries frontmatter keys the subagent "
+        f"loader does not accept: {sorted(unaccepted_keys)}"
+    )
+
+
+def test_code_verifier_frontmatter_parses_and_names_the_agent() -> None:
+    agents_directory = Path(__file__).parent
+    code_verifier_block = _frontmatter_block(
+        agents_directory / f"{CODE_VERIFIER_AGENT_NAME}.md"
+    )
+    parsed_frontmatter = yaml.safe_load(code_verifier_block)
+    assert parsed_frontmatter["name"] == CODE_VERIFIER_AGENT_NAME
+    assert set(parsed_frontmatter) <= ACCEPTED_FRONTMATTER_KEYS

package/audit-rubrics/category_rubrics/category-j-code-rules-compliance.md

@@ -24,7 +24,7 @@
 | J5 | Abbreviations | `ctx`, `cfg`, `msg`, `btn`, `idx`, `cnt`, `elem`, `val`, `tmp`, `str`, `num`, `arr`, `obj`, `fn`, `cb`, `req`, `res`. (Loop counters `i`/`j`/`k` and `e` for exceptions are exempt.) |
 | J6 | Vague names | `result`, `data`, `output`, `response`, `value`, `item`, `temp`, `info`, `stuff`, `thing`. Vague prefixes: `handle`, `process`, `manage`, `do`. |
 | J7 | Type hints | Missing type annotation on a parameter or return; presence of `Any` or `# type: ignore`. |
-| J8 | New inline comments | New `#` or `//` comments in production code added by this diff. (Existing comments are NEVER removed — Comment Preservation rule.) |
+| J8 | New inline comments | New `#` or `//` comments in production code added by this diff. (Removing an existing comment is a Comment Preservation concern the hook flags with a stderr advisory rather than a block.) |
 | J9 | Logging format | `log_*(f"...")` rather than `log_*("...", arg)`. |
 | J10 | Imports inside functions | `import` statements placed inside function bodies. |
 | J11 | sys.path.insert dedup | `sys.path.insert(0, X)` must be guarded by `if X not in sys.path:` (test files exempt). |

package/audit-rubrics/prompts/category-j-code-rules-compliance.md

@@ -69,7 +69,7 @@ A `test_*.py` name or a `.mjs` extension takes the line out of the write-time ga
 **J8. New inline comments**
 - Every `#` or `//` comment line **added** by this diff in production code — flag, except for exempt markers (shebangs, `# type:`, `# noqa`, `# pylint:`, `# pragma:`, `// @ts-`, `// eslint-`, `// prettier-`, `/// `).
 - Module/function/class docstrings are always allowed.
-- Existing comments are NEVER removed (Comment Preservation rule); if the diff removes an existing comment, that is a separate violation outside J8 (also blocked by the hook).
+- Existing comments are NEVER removed (Comment Preservation rule); if the diff removes an existing comment, that is a separate violation outside J8 (the hook emits a stderr advisory for it rather than blocking).
 - Test files are exempt.
 - Adversarial probes: (a) is there any `# type:` or marker comment that is actually inert prose rather than a real type-checker / linter directive? (b) is any docstring carrying inline-comment content (line-level explanations rather than module/function description)? (c) does any newly-added blank line between code stanzas function as a comment substitute, suggesting the author wanted to add a comment but couldn't?
 

package/bin/install.mjs

@@ -147,6 +147,7 @@ const INSTALL_GROUPS = {
     core: {
         description: 'Development standards, hooks, agents, commands',
         skills: [
+            'team-advisor', 'team-advisor-refresh',
             'anthropic-plan', 'everything-search',
             'pr-review-responder',
             'recall', 'remember', 'task-build', 'verified-build'

package/docs/CODE_RULES.md

@@ -4,9 +4,9 @@ Compact reference for agents. ⚡ marks rules enforced by `code_rules_enforcer.p
 
 ---
 
-## COMMENT PRESERVATION (ABSOLUTE RULE)
+## COMMENT PRESERVATION
 
-**NEVER remove existing comments.** Existing comments are SACRED. Only evaluate comments on lines you are actively changing. Do not add new inline comments in production code — write self-documenting code. Docstrings (module/class/function) are always allowed. Test files are exempt. The hook enforces both directions: it blocks new inline comments AND blocks deletion of existing ones.
+**Keep existing comments in place.** Only evaluate comments on lines you are actively changing. Do not add new inline comments in production code — write self-documenting code. Docstrings (module/class/function) are always allowed. Test files are exempt. The hook treats the two directions differently: adding a new inline comment blocks the edit, while removing an existing comment prints a stderr advisory and lets the edit through.
 
 ---
 

package/hooks/blocking/CLAUDE.md

@@ -24,7 +24,7 @@ The check modules it calls are the `code_rules_<concern>.py` files below.
 | `code_rules_banned_identifiers.py` | Banned short names (`ctx`, `cfg`, `msg`, etc.), banned prefixes (`handle_`, `process_`, etc.) |
 | `code_rules_boolean_mustcheck.py` | Boolean naming (`is_`/`has_`/… prefixes) and must-check return values |
 | `code_rules_command_dispatch.py` | A `hooks/blocking/` command classifier matching a multi-word command regex without a start anchor or first-word tokenization |
-| `code_rules_comments.py` | No new inline comments; no deletion of existing ones |
+| `code_rules_comments.py` | No new inline comments; advisory on deletion of existing ones |
 | `code_rules_constants_config.py` | Constants must live in `config/`; file-global constant use-count |
 | `code_rules_dead_argparse_argument.py` | Argparse arguments with no references in the same file |
 | `code_rules_dead_config_field.py` | `*Config` / `*Selectors` dataclass fields with no live references |
@@ -78,10 +78,11 @@ The check modules it calls are the `code_rules_<concern>.py` files below.
 | `hook_prose_detector_consistency.py` | PreToolUse (Write/Edit) | Hook docstrings/messages that claim a trigger the detector cannot fire on |
 | `intent_only_ending_blocker.py` | Stop | Responses that end on a plan or intent without doing the work |
 | `open_questions_in_plans_blocker.py` | PreToolUse (Write/Edit) | Plan documents with unresolved open questions |
+| `nas_ssh_binary_enforcer.py` | PreToolUse (Bash) | A bare `ssh`/`scp`/`sftp` command word targeting the NAS at `192.168.1.100` (Git Bash's MSYS ssh stalls on an interactive password prompt), or the full `System32/OpenSSH` binary to that host without `-o BatchMode=yes` |
 | `package_inventory_stale_blocker.py` | PreToolUse (Write) | A new production code file created in a directory whose `README.md`/`CLAUDE.md` inventory (or a parent skill's `SKILL.md` Layout table mapping the `scripts/` subdirectory) names two or more sibling files but no entry for the new file |
 | `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 |
+| `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 |
 | `precommit_code_rules_gate.py` | PreToolUse (Bash) | Staged changes that fail the CODE_RULES gate at commit time |
 | `pytest_testpaths_orphan_blocker.py` | PreToolUse (Write/Edit/MultiEdit) | New `test_*.py` files created under a directory absent from a package's explicit pytest `testpaths` allowlist |
 | `question_to_user_enforcer.py` | Stop | User-directed questions not routed through `AskUserQuestion` |
@@ -111,8 +112,10 @@ The check modules it calls are the `code_rules_<concern>.py` files below.
 | `pr_description_body_audit.py` | Body audit logic for `pr_description_enforcer.py` |
 | `pr_description_command_parser.py` | `gh` command parsing for `pr_description_enforcer.py` |
 | `pr_description_pr_number.py` | PR number extraction logic |
+| `pr_description_proof_of_work.py` | Proof-of-work comment audit and `gh pr ready` gate logic for `pr_description_enforcer.py` |
 | `pr_description_readability.py` | Readability checks on PR description bodies |
 | `verification_verdict_store.py` | Reads and writes verdict files under `~/.claude/verification/` |
+| `verified_commit_config_bootstrap.py` | Binds `config.verified_commit_constants` to the sibling `config/` file by explicit location, so the gate family resolves its constants regardless of a foreign `config` package's `sys.path` order |
 
 ## Conventions
 

package/hooks/blocking/code_rules_comments.py

@@ -147,7 +147,7 @@ def check_comment_changes(old_content: str, new_content: str, file_path: str) ->
 
     Inline comments (after code on same line): BLOCK when added.
     Standalone comment lines: NUDGE (print advisory) when added.
-    Existing comments being removed: BLOCK (comment preservation principle).
+    Existing comments being removed: NUDGE (print advisory) — comment preservation is advisory.
 
     When the file is Python and either *old_content* or *new_content* cannot
     be tokenized (common for mid-edit Edit fragments), the comparison is
@@ -188,7 +188,7 @@ def check_comment_changes(old_content: str, new_content: str, file_path: str) ->
         code_was_removed = new_line_count < old_line_count - len(removed_comments)
         if not code_was_removed:
             sample = next(iter(removed_comments))
-            issues.append(f"Existing comment removed: {sample[:60]} - NEVER delete existing comments")
+            print(f"[CODE_RULES advisory] Existing comment removed: {sample[:60]} - comment preservation is advisory", file=sys.stderr)
 
     return issues
 

package/hooks/blocking/code_verifier_spawn_preflight_gate.py

@@ -43,9 +43,11 @@ from verification_verdict_store import (  # noqa: E402
 )
 
 from hooks_constants.code_verifier_spawn_preflight_gate_constants import (  # noqa: E402
+    ALL_MERGE_HEAD_PROBE_FLAGS,
     ALL_MERGE_TREE_COMMAND_FLAGS,
     ALL_NAME_ONLY_WORKTREE_DIFF_FLAGS,
     ALL_UNIFIED_ZERO_DIFF_FLAGS,
+    ALL_UNMERGED_PATHS_DIFF_FLAGS,
     CODE_RULES_SECTION_HEADER,
     CODE_VERIFIER_SUBAGENT_TYPE,
     DENY_REASON_LEAD,
@@ -145,9 +147,49 @@ def _run_trial_merge(repo_root: str, base_ref: str) -> tuple[int, str] | None:
     return completed_process.returncode, completed_process.stdout
 
 
+def _merge_in_progress(repo_root: str) -> bool:
+    """Decide whether an unfinished merge is recorded in the work tree.
+
+    Args:
+        repo_root: The repository top-level directory.
+
+    Returns:
+        True when ``MERGE_HEAD`` resolves — a merge is started but not yet
+        committed; False when no merge is in progress or git fails.
+    """
+    return run_git(repo_root, *ALL_MERGE_HEAD_PROBE_FLAGS) is not None
+
+
+def _staged_merge_conflicts(repo_root: str) -> list[str] | None:
+    """Return the unmerged paths of an in-progress merge from the index.
+
+    A merge whose conflicts are fully resolved and staged leaves zero unmerged
+    index entries, so the resolved state is committable and this returns an
+    empty list. A merge with conflicts still open returns those paths, so the
+    caller keeps denying until the resolution is staged.
+
+    Args:
+        repo_root: The repository top-level directory.
+
+    Returns:
+        The still-unmerged paths (empty when the resolution is fully staged),
+        or None when git fails — the caller fails OPEN on None.
+    """
+    unmerged_text = run_git(repo_root, *ALL_UNMERGED_PATHS_DIFF_FLAGS)
+    if unmerged_text is None:
+        return None
+    return [each_line for each_line in unmerged_text.splitlines() if each_line]
+
+
 def _conflicting_files(repo_root: str, base_ref: str) -> list[str] | None:
     """Return the files that conflict when HEAD trial-merges against the base.
 
+    While a merge is in progress the branch tip has not yet recorded the
+    resolution, so the trial-merge of the base against HEAD would re-report
+    conflicts the staged index already fixed. In that state the index is the
+    authority: an empty unmerged set is a committable resolution, and any
+    remaining unmerged path is a live conflict.
+
     Args:
         repo_root: The repository top-level directory.
         base_ref: The base ref to trial-merge HEAD against.
@@ -158,6 +200,8 @@ def _conflicting_files(repo_root: str, base_ref: str) -> list[str] | None:
         timeout, or an exit code that is neither clean nor conflict) — the
         caller fails OPEN on None.
     """
+    if _merge_in_progress(repo_root):
+        return _staged_merge_conflicts(repo_root)
     merge_outcome = _run_trial_merge(repo_root, base_ref)
     if merge_outcome is None:
         return None

package/hooks/blocking/config/verified_commit_constants.py

@@ -86,6 +86,8 @@ TEST_FILE_SUFFIX = "_test.py"
 CONFTEST_FILE_NAME = "conftest.py"
 MINIMUM_STATUS_FIELD_COUNT = 2
 ALL_FALLBACK_BASE_REFERENCES = ("origin/main", "origin/master")
+DETACHED_HEAD_LABEL = "HEAD"
+BRANCH_REMOTE_CONFIG_KEY_TEMPLATE = "branch.{branch_name}.remote"
 ALL_TOOLING_STATE_PREFIXES = (
     ".claude/verification/",
     ".claude/worktrees/",

package/hooks/blocking/conftest.py

@@ -0,0 +1,115 @@
+"""Pytest fixture that reproduces foreign-``config`` shadowing for the gate family.
+
+The verified-commit gate hooks import shared constants as
+``from config.verified_commit_constants import ...``. This fixture mirrors the
+installed layout that breaks that import -- a real ``hooks/blocking`` package
+beside a decoy ``hooks/config`` regular package -- and runs a caller-supplied
+driver as a subprocess whose ``sys.path`` places the decoy ahead of
+``blocking``, the ordering under which the wrong ``config`` wins resolution.
+"""
+
+import shutil
+import subprocess
+import sys
+import textwrap
+from collections.abc import Callable
+from pathlib import Path
+
+import pytest
+
+_BLOCKING_SOURCE_DIRECTORY = Path(__file__).resolve().parent
+_HOOKS_CONSTANTS_SOURCE_DIRECTORY = _BLOCKING_SOURCE_DIRECTORY.parent / "hooks_constants"
+_SUBPROCESS_TIMEOUT_SECONDS = 60
+_MIRRORED_BLOCKING_FILE_NAMES = (
+    "verified_commit_gate.py",
+    "verification_verdict_store.py",
+    "verifier_verdict_minter.py",
+    "verdict_directory_write_blocker.py",
+    "verified_commit_config_bootstrap.py",
+)
+_DECOY_CONFIG_INIT_SOURCE = '"""Foreign config package that must never win resolution."""\n'
+_DECOY_CONFIG_CONSTANTS_SOURCE = (
+    '"""Stale stand-in carrying none of the real gate constants."""\n\nIS_DECOY_CONFIG = True\n'
+)
+
+
+def _build_shadowed_hook_tree(tmp_path: Path) -> tuple[Path, Path]:
+    """Mirror the hook tree with a decoy ``config`` package beside ``blocking``.
+
+    Args:
+        tmp_path: The directory the mirrored tree is built under.
+
+    Returns:
+        The mirrored ``hooks`` directory and its ``blocking`` subdirectory.
+    """
+    mirrored_hooks_directory = tmp_path / "hooks"
+    mirrored_blocking_directory = mirrored_hooks_directory / "blocking"
+    mirrored_blocking_directory.mkdir(parents=True)
+
+    for each_file_name in _MIRRORED_BLOCKING_FILE_NAMES:
+        source_file = _BLOCKING_SOURCE_DIRECTORY / each_file_name
+        if source_file.exists():
+            shutil.copy2(source_file, mirrored_blocking_directory / each_file_name)
+
+    shutil.copytree(
+        _BLOCKING_SOURCE_DIRECTORY / "config",
+        mirrored_blocking_directory / "config",
+    )
+    shutil.copytree(
+        _HOOKS_CONSTANTS_SOURCE_DIRECTORY,
+        mirrored_hooks_directory / "hooks_constants",
+    )
+
+    decoy_config_directory = mirrored_hooks_directory / "config"
+    decoy_config_directory.mkdir()
+    (decoy_config_directory / "__init__.py").write_text(_DECOY_CONFIG_INIT_SOURCE, encoding="utf-8")
+    (decoy_config_directory / "verified_commit_constants.py").write_text(
+        _DECOY_CONFIG_CONSTANTS_SOURCE, encoding="utf-8"
+    )
+    return mirrored_hooks_directory, mirrored_blocking_directory
+
+
+@pytest.fixture
+def run_under_config_shadow(
+    tmp_path: Path,
+) -> Callable[[str], subprocess.CompletedProcess[str]]:
+    """Return a runner that executes a driver under a foreign-``config`` sys.path.
+
+    ::
+
+        completed = run_under_config_shadow("import verified_commit_gate")
+        ok:   completed.returncode == 0 once the bootstrap seeds the real module
+        flag: nonzero with ModuleNotFoundError while the decoy config wins
+
+    The runner prefixes the driver with a ``sys.path`` preamble that puts the
+    mirrored ``hooks`` directory (holding the decoy ``config``) ahead of
+    ``blocking``, then runs the probe with the active interpreter.
+
+    Args:
+        tmp_path: Pytest's per-test temporary directory, fixture-injected.
+
+    Returns:
+        A function taking driver source text and returning the finished
+        subprocess result.
+    """
+    mirrored_hooks_directory, mirrored_blocking_directory = _build_shadowed_hook_tree(tmp_path)
+
+    def run_driver(driver_body: str) -> subprocess.CompletedProcess[str]:
+        probe_script = tmp_path / "probe.py"
+        sys_path_preamble = textwrap.dedent(
+            f"""\
+            import sys
+            sys.path.insert(0, {str(mirrored_blocking_directory)!r})
+            sys.path.insert(0, {str(mirrored_hooks_directory)!r})
+            """
+        )
+        probe_script.write_text(sys_path_preamble + textwrap.dedent(driver_body), encoding="utf-8")
+        return subprocess.run(
+            [sys.executable, str(probe_script)],
+            check=False,
+            capture_output=True,
+            text=True,
+            timeout=_SUBPROCESS_TIMEOUT_SECONDS,
+        )
+
+    return run_driver

package/hooks/blocking/nas_ssh_binary_enforcer.py

@@ -0,0 +1,191 @@
+#!/usr/bin/env python3
+"""PreToolUse hook: force the Windows OpenSSH binary for NAS ssh/scp/sftp commands.
+
+Root cause: Git Bash's MSYS ssh reads ``~/.ssh/id_ed25519`` as world-readable
+through its ACL mapping, rejects the key as "bad permissions", offers no key, and
+falls back to an interactive password prompt that hangs unattended agent sessions.
+The Windows OpenSSH binary under ``System32/OpenSSH`` authenticates the same key
+without prompting.
+
+Detection strategy: this hook fires only on the Bash tool. The command is
+shlex-tokenized (quotes removed), glued shell control operators are exploded off
+the tokens, and the tokens are split into simple-command segments on ``&&`` /
+``||`` / ``;`` / ``|&`` / ``|`` / ``&``. For each segment the effective leading program is
+found by skipping ``VAR=value`` assignments and launcher wrappers (``timeout``,
+``nohup``, ``nice``, ``stdbuf``, ``setsid``, ``env``) with their flags and duration
+arguments. A segment is evaluated only when its leading program's basename is
+``ssh``/``scp``/``sftp`` (with or without a ``.exe`` suffix) AND a token in that same
+segment holds the NAS address ``192.168.1.100`` as a connection host — bare,
+``user@host``, or a ``host:path`` target. The address inside a remote-command
+argument or a remote path component on another host does not count.
+
+An evaluated segment is DENIED with the binary-swap message when its leading program
+is a bare ssh-family word rather than a path ending in ``OpenSSH/ssh.exe`` (or
+``scp.exe`` / ``sftp.exe``). An evaluated segment whose leading program is that full
+OpenSSH path is DENIED with the batch-mode message when no token in the segment
+carries ``BatchMode=yes``, so an authentication regression fails loudly rather than
+prompting. Everything else is allowed: ssh to any other host, the full OpenSSH path
+with ``BatchMode=yes``, non-Bash tools, a command that only mentions the address
+without an ssh-family leading program, and a command shlex cannot tokenize.
+"""
+
+import json
+import shlex
+import sys
+from pathlib import Path
+
+_hooks_dir = str(Path(__file__).resolve().parent.parent)
+if _hooks_dir not in sys.path:
+    sys.path.insert(0, _hooks_dir)
+
+from hooks_constants.hook_block_logger import log_hook_block  # noqa: E402
+from hooks_constants.nas_ssh_binary_enforcer_constants import (  # noqa: E402
+    ALL_LAUNCHER_WRAPPER_COMMANDS,
+    ALL_OPENSSH_BINARY_PATH_SUFFIXES,
+    ALL_SHELL_CONTROL_OPERATOR_TOKENS,
+    ALL_SSH_FAMILY_COMMAND_BASENAMES,
+    BARE_SSH_BINARY_MESSAGE,
+    BASH_TOOL_NAME,
+    BATCH_MODE_PATTERN,
+    CONTROL_OPERATOR_SPLIT_PATTERN,
+    LAUNCHER_DURATION_PATTERN,
+    LEADING_ASSIGNMENT_PATTERN,
+    MISSING_BATCH_MODE_MESSAGE,
+    NAS_HOST_TOKEN_PATTERN,
+)
+
+
+def _token_basename(token: str) -> str:
+    return token.replace("\\", "/").rsplit("/", 1)[-1].lower()
+
+
+def _is_openssh_binary_path(token: str) -> bool:
+    normalized_token = token.replace("\\", "/").lower()
+    return any(
+        normalized_token.endswith(each_suffix)
+        for each_suffix in ALL_OPENSSH_BINARY_PATH_SUFFIXES
+    )
+
+
+def _split_into_segments(all_command_tokens: list[str]) -> list[list[str]]:
+    all_exploded_tokens: list[str] = []
+    for each_token in all_command_tokens:
+        for each_fragment in CONTROL_OPERATOR_SPLIT_PATTERN.split(each_token):
+            if each_fragment:
+                all_exploded_tokens.append(each_fragment)
+    all_segments: list[list[str]] = []
+    current_segment: list[str] = []
+    for each_token in all_exploded_tokens:
+        if each_token in ALL_SHELL_CONTROL_OPERATOR_TOKENS:
+            all_segments.append(current_segment)
+            current_segment = []
+            continue
+        current_segment.append(each_token)
+    all_segments.append(current_segment)
+    return all_segments
+
+
+def _effective_leading_program(all_segment_tokens: list[str]) -> str | None:
+    has_seen_launcher_wrapper = False
+    for each_token in all_segment_tokens:
+        if LEADING_ASSIGNMENT_PATTERN.match(each_token):
+            continue
+        if _token_basename(each_token) in ALL_LAUNCHER_WRAPPER_COMMANDS:
+            has_seen_launcher_wrapper = True
+            continue
+        if has_seen_launcher_wrapper and (
+            each_token.startswith("-") or LAUNCHER_DURATION_PATTERN.match(each_token)
+        ):
+            continue
+        return each_token
+    return None
+
+
+def _segment_references_nas(all_segment_tokens: list[str]) -> bool:
+    return any(NAS_HOST_TOKEN_PATTERN.search(each_token) for each_token in all_segment_tokens)
+
+
+def _segment_carries_batch_mode(all_segment_tokens: list[str]) -> bool:
+    return any(BATCH_MODE_PATTERN.search(each_token) for each_token in all_segment_tokens)
+
+
+def _find_nas_ssh_violation(command: str) -> str | None:
+    """Return the deny message for a NAS ssh-family command, or None to allow.
+
+    ::
+
+        ssh -p 9222 jon@192.168.1.100 "ls"          flag: bare-binary message
+        "…/OpenSSH/ssh.exe" -p 9222 jon@192.168…    flag: missing-batch-mode message
+        "…/OpenSSH/ssh.exe" -o BatchMode=yes …NAS   ok:   None
+        ssh jon@example.com "ls"                     ok:   None
+
+    Tokenizes the command, splits it into simple-command segments, and evaluates
+    each segment whose leading program is an ssh-family word AND whose tokens carry
+    the NAS address. A bare ssh-family leader returns the binary-swap message; the
+    full OpenSSH path leader without a ``BatchMode=yes`` token returns the batch-mode
+    message. Returns None when shlex cannot tokenize the command.
+
+    Args:
+        command: The raw Bash command string from the tool input.
+
+    Returns:
+        The deny message string when a segment violates the NAS ssh policy, else None.
+    """
+    try:
+        all_command_tokens = shlex.split(command)
+    except ValueError:
+        return None
+    for each_segment in _split_into_segments(all_command_tokens):
+        leading_program = _effective_leading_program(each_segment)
+        if leading_program is None:
+            continue
+        if _token_basename(leading_program) not in ALL_SSH_FAMILY_COMMAND_BASENAMES:
+            continue
+        if not _segment_references_nas(each_segment):
+            continue
+        if not _is_openssh_binary_path(leading_program):
+            return BARE_SSH_BINARY_MESSAGE
+        if not _segment_carries_batch_mode(each_segment):
+            return MISSING_BATCH_MODE_MESSAGE
+    return None
+
+
+def main() -> None:
+    try:
+        hook_input = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        sys.exit(0)
+
+    tool_name = hook_input.get("tool_name", "")
+    if tool_name != BASH_TOOL_NAME:
+        sys.exit(0)
+
+    command = hook_input.get("tool_input", {}).get("command", "")
+    if not command:
+        sys.exit(0)
+
+    deny_reason = _find_nas_ssh_violation(command)
+    if deny_reason is None:
+        sys.exit(0)
+
+    deny_payload = {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "deny",
+            "permissionDecisionReason": deny_reason,
+        }
+    }
+    log_hook_block(
+        calling_hook_name="nas_ssh_binary_enforcer.py",
+        hook_event="PreToolUse",
+        block_reason=deny_reason,
+        tool_name=tool_name,
+        offending_input_preview=command,
+    )
+    print(json.dumps(deny_payload))
+    sys.stdout.flush()
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()