@opengsd/gsd-path 1.6.1 → 1.7.0

package/scripts/guard_hook.py

@@ -424,6 +424,10 @@ GIT_REASONS = {
         "(STATE.branch); create a new branch instead"
     ),
     "update-ref": "git update-ref deletion destroys refs the recovery protocol inspects",
+    "owned-refspec": (
+        "git commands naming refs/gsd-path/ or runtime-hotfix are denied: that "
+        "namespace holds orchestrator-owned authorizations an agent must not create or move"
+    ),
     "worktree": (
         "git worktree remove --force discards uncommitted task work the recovery "
         "protocol needs; commit or stash it, then remove without --force"
@@ -1431,6 +1435,133 @@ def command_can_destroy_files(invocation):
     )
 
 
+def _deletion_overlaps(candidate, root):
+    """Whether a recursive delete of `candidate` could remove `root`.
+
+    A candidate inside the root deletes its contents, and a candidate that
+    CONTAINS the root deletes it wholesale (`rm -r` of a parent directory), so
+    both directions deny. Existing-path identity covers case variants that a
+    lexical comparison misses on case-insensitive filesystems.
+    """
+    try:
+        candidate.relative_to(root)
+        return True
+    except ValueError:
+        pass
+    try:
+        root.relative_to(candidate)
+        return True
+    except ValueError:
+        pass
+    return _within_existing_root(candidate, root) or _within_existing_root(root, candidate)
+
+
+def _strictly_inside(candidate, root):
+    if candidate == root:
+        return False
+    try:
+        candidate.relative_to(root)
+        return True
+    except ValueError:
+        return any(_same_existing_path(ancestor, root) for ancestor in candidate.parents)
+
+
+def destructive_state_root_reason(operands, working_directories):
+    """Why a destructive operand is pipeline state, or None when outside it.
+
+    Delete restrictions cover the pipeline's state directories, not only the
+    repository (#468): the guard's home tree, the configured worktree root,
+    and every pinned workspace root sit outside any repository, so the path
+    kinds alone would call them external. Unresolvable workspace state denies
+    rather than guesses.
+    """
+    directories = working_directories or [os.getcwd()]
+    commons = set()
+    checkouts = set()
+    for directory in directories:
+        result = subprocess.run(
+            ["git", "-C", str(directory), "rev-parse", "--show-toplevel", "--git-common-dir"],
+            capture_output=True, encoding="utf-8", errors="replace", check=False,
+            env={**os.environ, "GIT_OPTIONAL_LOCKS": "0"},
+        )
+        lines = result.stdout.splitlines()
+        if result.returncode == 0 and len(lines) == 2:
+            checkouts.add(Path(lines[0]).resolve(strict=False))
+            common = Path(lines[1])
+            if not common.is_absolute():
+                common = Path(directory) / common
+            commons.add(common.resolve(strict=False))
+    try:
+        roots = _workspace_roots_for_commons(commons)
+    except ValueError as error:
+        return f"pipeline workspace state cannot be resolved: {error}"
+    for operand in operands:
+        for candidate in target_paths(operand, directories, Path(os.getcwd())):
+            for root in roots:
+                # A managed worktree under a state root is the agent's own
+                # checkout; deletes inside it are ordinary product work.
+                if _deletion_overlaps(candidate, root) and not any(
+                    _strictly_inside(candidate, checkout) and _strictly_inside(checkout, root)
+                    for checkout in checkouts
+                ):
+                    return f"destructive target is pipeline state: {operand}"
+    return None
+
+
+def _closed_repo_root(working_directories):
+    """The closed-milestone repository for these working directories, if any."""
+    for directory in working_directories or [os.getcwd()]:
+        root = subprocess.run(
+            ["git", "-C", str(directory), "rev-parse", "--show-toplevel"],
+            capture_output=True, encoding="utf-8", errors="replace", check=False,
+        )
+        if root.returncode != 0:
+            continue
+        repo = Path(root.stdout.strip())
+        if closed_milestone_reason(repo):
+            return repo
+    return None
+
+
+def closed_destructive_scope_reason(arguments, working_directories):
+    """Why a destructive command stays inside pipeline scope, or None outside it.
+
+    A closed milestone accepts no new work, but a scratch file entirely outside
+    the repository and every state root is no work (#468). The allowance needs
+    every operand provably external to the closed repository — the path kinds
+    check the lexical path, the symlink-resolved path, control aliases, and
+    member checkouts — and the state-root check covers the directories that
+    live outside the repository.
+    """
+    end = arguments.index("--") if "--" in arguments else len(arguments)
+    operands = [
+        argument for argument in arguments[:end] if argument and not argument.startswith("-")
+    ] + [argument for argument in arguments[end + 1:] if argument]
+    if not operands:
+        return "destructive command names no target"
+    repo = _closed_repo_root(working_directories)
+    if repo is None:
+        return "pipeline scope cannot be classified"
+    control_roots = repository_control_roots(repo)
+    try:
+        import members  # the guard's runtime directory
+        member_roots = [Path(member["checkout"]) for member in members.read_members(repo)]
+    except Exception as error:
+        return f"member scope cannot be resolved: {error}"
+    for operand in operands:
+        if target_kind(operand, working_directories, repo, control_roots) != "external":
+            return f"destructive target stays inside the repository: {operand}"
+        # A recursive delete of an ancestor removes the repository (and any
+        # member checkout) even though the operand itself classifies external.
+        for candidate in target_paths(operand, working_directories, repo):
+            if _deletion_overlaps(candidate, repo.resolve()):
+                return f"destructive target contains the repository: {operand}"
+            for member_root in member_roots:
+                if _deletion_overlaps(candidate, member_root.resolve(strict=False)):
+                    return f"destructive target contains a member checkout: {operand}"
+    return destructive_state_root_reason(operands, working_directories)
+
+
 def literal_path(operand):
     if len(operand) >= 2 and operand[0] in "\"'" and operand[-1] == operand[0]:
         operand = operand[1:-1]
@@ -2687,6 +2818,114 @@ def unresolved_runner_word(token):
     ) and not parameters_double_quoted(token)
 
 
+POWERSHELL_ASSIGNMENT_TARGET = re.compile(r"^\$(?:env:)?[A-Za-z_][A-Za-z0-9_]*$")
+POWERSHELL_LITERAL_VALUE = re.compile(r"[A-Za-z0-9_][A-Za-z0-9_.:/\\ +,-]*")
+POWERSHELL_STATIC_CALL = re.compile(r"\[(?P<type>[^\]()]+)\]::")
+POWERSHELL_PURE_TYPES = frozenset(
+    {
+        "math", "string", "int", "int32", "long", "int64", "double", "bool",
+        "byte", "char", "decimal", "single", "guid", "datetime", "timespan",
+        "version",
+        "system.math", "system.string", "system.int32", "system.int64",
+        "system.double", "system.boolean", "system.guid", "system.datetime",
+        "system.timespan", "system.version",
+    }
+)
+POWERSHELL_DYNAMIC_COMMANDS = frozenset(
+    {
+        "invoke-expression", "iex", "invoke-command", "icm", "add-type",
+        "start-process", "saps", "sap", "start-job", "new-object",
+    }
+)
+
+
+def powershell_assignment_invocation(segment, unwrap_runners=True):
+    """The invocation a validated PowerShell assignment runs, or None.
+
+    ``$name = literal`` and ``$env:NAME = literal`` set a process-local
+    variable or environment entry. PowerShell runs a bare-word value as a
+    pipeline, so the value is judged as the command it would run. The value
+    must be plain literals; anything richer — expansions, substitutions,
+    member access — keeps the unresolvable denial rather than guessing at
+    expression semantics. An environment name that changes where Git reads
+    its configuration is refused exactly like the shell form (#468).
+    """
+    if len(segment) < 3 or segment[1] != "=":
+        return None
+    if POWERSHELL_ASSIGNMENT_TARGET.fullmatch(segment[0]) is None:
+        return None
+    name = segment[0].removeprefix("$")
+    folded = name.casefold()
+    if ":" in name:
+        variable, _, scope = name.partition(":")
+        if variable != "env":
+            return None
+        if scope.casefold() in {"home", "xdg_config_home"} or scope.casefold().startswith("git_"):
+            raise ValueError(
+                f"{name} changes where Git reads its configuration, which the guard "
+                "cannot validate; run git without it"
+            )
+    elif folded in {"home", "xdg_config_home"} or folded.startswith("git_"):
+        return None  # shell-style names keep their shell semantics, not PowerShell's
+    if any(POWERSHELL_LITERAL_VALUE.fullmatch(token) is None for token in segment[2:]):
+        return None
+    # A value naming a write or dynamic command runs it; deny without resolving paths.
+    command_names = SHELL_WRITE_COMMANDS | POWERSHELL_DYNAMIC_COMMANDS
+    if any(token.casefold().removesuffix(".exe") in command_names for token in segment[2:]):
+        return None
+    return command_invocation(segment[2:], unwrap_runners)
+
+
+def powershell_expression_reason(tokens, depth=0):
+    """Why a PowerShell expression form stays denied, or None when safe.
+
+    PowerShell expression statements are not executables: assignments are
+    process-local, while .NET static member calls run arbitrary code
+    (``[System.IO.File]::WriteAllText`` writes a file the write-target
+    classification never sees). The guard allows the provably pure type
+    members and denies every other static call — wherever the token appears,
+    including inside a script block or a wrapped ``-Command`` payload — plus
+    every dynamic-execution command (aliases included) inside a block or as
+    the executable, and the call operator (#468).
+    """
+    previous = None
+    for token in tokens:
+        if token == "&" and (
+            previous is None
+            or previous.endswith("{")
+            or set(previous) <= set("|;&()\n\r")
+        ):
+            return "the PowerShell call operator target cannot be resolved"
+        previous = token
+    for segment in command_segments(tokens):
+        wrapped = wrapped_command_tokens(segment, expand_parameters=False)
+        if wrapped is not None:
+            if depth >= 4:
+                return "nested command payloads exceed the guard's inspection depth"
+            reason = powershell_expression_reason(wrapped, depth + 1)
+            if reason:
+                return reason
+            continue
+        invocation = command_invocation(list(segment))
+        if invocation is None:
+            continue
+        executable = invocation[0]
+        if executable in POWERSHELL_DYNAMIC_COMMANDS:
+            return f"dynamic execution cannot be inspected by the guard: {executable}"
+        block_depth = 0
+        for token in segment:
+            match = POWERSHELL_STATIC_CALL.search(token)
+            if match is not None and match.group("type").strip().casefold() not in POWERSHELL_PURE_TYPES:
+                return (f"static member call is not on the guard's read-only type "
+                        f"whitelist: {token}")
+            word = token.lstrip("{")
+            block_depth += len(token) - len(word)
+            if block_depth and word.rstrip("}").casefold() in POWERSHELL_DYNAMIC_COMMANDS:
+                return f"dynamic execution cannot be inspected by the guard: {token}"
+            block_depth = max(0, block_depth - (len(word) - len(word.rstrip("}"))))
+    return None
+
+
 def command_invocation(segment, unwrap_runners=True):
     """`unwrap_runners` is False where a command runner itself must be judged."""
     index = 0
@@ -2781,6 +3020,9 @@ def command_invocation(segment, unwrap_runners=True):
             break
     arguments = segment[index + 1 :]
     if SHELL_PARAMETER_SYNTAX.search(executable):
+        assignment = powershell_assignment_invocation(list(segment[index:]), unwrap_runners)
+        if assignment is not None:
+            return assignment
         raise ValueError(
             f"executable {segment[index]} cannot be resolved by the guard; "
             "name the program literally"
@@ -2918,6 +3160,16 @@ def git_command(segment, assignments=None):
             if option != "-C":
                 require_resolved_git_word(value)
             index += 1
+        if option not in {"-C", "-c", "--config-env"} and git_option_in(
+            option, GIT_PARAMETER_DENIED_OPTIONS
+        ):
+            # A denied global option executes a program git runs
+            # (--upload-pack/--exec/...); it must never slip past as a
+            # pre-subcommand token the subcommand checks never see (#468).
+            # -c/--config-env keep their dedicated config-key checks below.
+            raise ValueError(
+                f"git option {option} cannot be verified by the guard"
+            )
         if option in {"-c", "--config-env"}:
             config_key, _, config_value = str(value).partition("=")
             config_key = config_key.casefold()
@@ -3589,6 +3841,10 @@ def _update_ref_names(target, refs, context, no_deref):
 
 
 def _workspace_roots(contexts):
+    return _workspace_roots_for_commons({context["common"] for context in contexts})
+
+
+def _workspace_roots_for_commons(commons):
     roots = [(Path.home() / ".gsd-path").resolve()]
     configured = os.environ.get("GSD_PATH_WORKTREE_ROOT")
     if configured:
@@ -3596,7 +3852,7 @@ def _workspace_roots(contexts):
         if not configured_root.is_absolute():
             raise ValueError("GSD_PATH_WORKTREE_ROOT must be absolute")
         roots.append(configured_root.resolve())
-    for common in {context["common"] for context in contexts}:
+    for common in commons:
         receipts = common / "gsd-path" / "workspaces"
         if not os.path.lexists(receipts):
             continue
@@ -4089,6 +4345,12 @@ def destructive_git_reason(
         if invocation is None:
             continue
         command, arguments, git_options = invocation
+        if any(
+            protected in word.casefold()
+            for word in words
+            for protected in ("refs/gsd-path/", "runtime-hotfix")
+        ):
+            return GIT_REASONS["owned-refspec"]
         # Git matches its own commands by exact case, but alias names in any case.
         built_in = (
             command_invocation(words)[1][-len(arguments) - 1] in GIT_BUILT_IN_COMMANDS
@@ -4307,20 +4569,48 @@ def bundled_helper_invocation(command, tokens, working_directories, helpers=PIPE
     runtime = here / "runtime"
     if (here / "runtime.json").exists():
         try:
-            from status_runtime import resolve_runtime
-            runtime = resolve_runtime(here.parent)
-        except (OSError, ValueError):
+            # Option (i) on #468: acceptance is the pinned runtime plus the
+            # validated successors its own hashed manifest names. The walk
+            # comes from the PINNED runtime's own bytes — never the project
+            # launcher's preloaded module, which may be stale or divergent —
+            # and exactly the bytes whose sha256 the pinned manifest names:
+            # read once, hash against the digest-proven manifest, execute
+            # the verified buffer, so no swap between check and exec can
+            # run unproven code.
+            import hashlib
+            import types
+
+            from status_runtime import (
+                declaration, manifest_digest, runtime_home, validate_runtime,
+            )
+            pin = declaration(here.parent)
+            validate_runtime(pin)
+            root = runtime_home() / pin["digest"]
+            manifest = json.loads((root / "manifest.json").read_text(encoding="utf-8"))
+            if (not isinstance(manifest, dict)
+                    or manifest_digest(manifest) != pin["digest"]):
+                return False
+            expected = manifest.get("files", {}).get("status_runtime.py")
+            data = (root / "status_runtime.py").read_bytes()
+            if (not isinstance(expected, str)
+                    or hashlib.sha256(data).hexdigest() != expected):
+                return False
+            module = types.ModuleType("gsd_path_pinned_status_runtime")
+            exec(compile(data, str(root / "status_runtime.py"), "exec"), module.__dict__)
+            runtimes = module.accepted_runtime_dirs(here.parent)
+        except (OSError, ValueError, TypeError, ImportError, AttributeError):
             return False
-    elif not runtime.exists():
-        runtime = here
-    runtime = runtime.resolve()
+    else:
+        if not runtime.exists():
+            runtime = here
+        runtimes = {runtime.resolve()}
     for base in working_directories or [os.getcwd()]:
         try:
             # A Git Bash /c/... operand names the C: drive, not a folder named c.
             script = (Path(base) / native_path_text(operand)).resolve()
             if (
                 script.name in helpers
-                and (script.is_relative_to(runtime) or (
+                and (any(script.is_relative_to(runtime_dir) for runtime_dir in runtimes) or (
                     script.name == "status_runtime.py" and script == here / "status_runtime.py"
                 ))
                 and script.is_file()
@@ -4522,6 +4812,106 @@ def closed_git_listing(tokens):
     return not positionals
 
 
+REMOTE_NAME = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]*$")
+FETCH_DESTINATION = re.compile(r"^refs/remotes/[^\s]+/")
+
+
+FETCH_BEHAVIOR_KEYS = (
+    "remote.{remote}.uploadpack", "fetch.uploadpack",
+    "remote.{remote}.prune", "fetch.prune",
+    "remote.{remote}.pruneTags", "fetch.pruneTags",
+    "remote.{remote}.mirror", "remote.{remote}.tagopt",
+)
+
+
+def _configured_fetch_read_only(repo, remote) -> bool:
+    """The configured remote fetches into remote-tracking refs only.
+
+    Repo config can change what a bare `git fetch REMOTE` does, so the
+    guard proves it instead of assuming it: the remote has a URL (an
+    unconfigured name makes git fetch from a local directory of that
+    name); none of uploadpack (runs a program), prune/pruneTags (delete
+    refs), mirror (rewrites every ref) or tagopt (forces tag fetches) is
+    set at any scope; and every `remote.<name>.fetch` refspec writes only
+    under refs/remotes/ (a hand-added `+refs/heads/main:refs/heads/retired`
+    moves a local branch). Default tag auto-follow still creates missing
+    tags that point at fetched commits; it never moves an existing ref.
+    """
+    def config(*arguments):
+        try:
+            return subprocess.run(
+                ["git", "config", *arguments], cwd=repo, capture_output=True,
+                encoding="utf-8", errors="replace", check=False,
+            )
+        except OSError:
+            return None
+
+    url = config("--get", f"remote.{remote}.url")
+    if url is None or url.returncode != 0 or not url.stdout.strip():
+        return False
+    for key in FETCH_BEHAVIOR_KEYS:
+        result = config("--get", key.format(remote=remote))
+        if result is None or result.returncode != 1:
+            return False
+    refspecs = config("--get-all", f"remote.{remote}.fetch")
+    if refspecs is None or refspecs.returncode not in (0, 1):
+        return False
+    for line in refspecs.stdout.splitlines():
+        destination = line.rsplit(":", 1)[-1].strip()
+        if not FETCH_DESTINATION.match(destination):
+            return False
+    return True
+
+
+def _closed_fetch_allowed(git, segment, directories) -> bool:
+    """A read-only fetch on a closed milestone (#468).
+
+    `git fetch [REMOTE]` is allowed only once these properties are PROVEN,
+    never assumed:
+    (1) the raw segment is `git (-C DIR)* fetch`: no other global option
+    precedes the subcommand (walked on raw tokens, consuming each -C with
+    its value, so neither valueless flags like -p nor a -C value named
+    fetch can slip past; --upload-pack/--exec additionally raise in
+    git_command);
+    (2) the remote's configuration fetches read-only (see
+    _configured_fetch_read_only).
+    Any refspec or option on the command line stays denied.
+    """
+    if git is None:
+        return False
+    subcommand, arguments, _options = git
+    if subcommand != "fetch":
+        return False
+    words = [str(token) for token in segment]
+    index = 1
+    while words[index:index + 1] == ["-C"]:
+        index += 2
+    if words[index:index + 1] != ["fetch"]:
+        return False
+    remote = arguments[0] if arguments else None
+    if remote is not None and not REMOTE_NAME.fullmatch(remote):
+        return False
+    if len(arguments) > 1:
+        return False
+    if remote is None:
+        # No argument fetches the current branch's remote, else origin.
+        remote = "origin"
+        if directories:
+            branch = _git_output([], directories[0], "branch", "--show-current")
+            if branch:
+                configured_branch_remote = subprocess.run(
+                    ["git", "config", "--get", f"branch.{branch}.remote"],
+                    cwd=directories[0], capture_output=True, encoding="utf-8",
+                    errors="replace", check=False,
+                ).stdout.strip()
+                if configured_branch_remote:
+                    remote = configured_branch_remote
+    return all(
+        _configured_fetch_read_only(Path(directory), remote)
+        for directory in directories or [Path.cwd()]
+    )
+
+
 def closed_shell_execution_reason(
     command, tokens, working_directories, initial_assignments=None
 ):
@@ -4568,17 +4958,54 @@ def closed_shell_execution_reason(
         if invocation is None:
             continue
         executable, _ = invocation
-        if executable in DIRECTORY_CHANGE_COMMANDS or checked_segment == ["git", "fetch", "origin"]:
+        if executable in DIRECTORY_CHANGE_COMMANDS or _closed_fetch_allowed(
+            git, segment, directories
+        ):
             continue
         plain = checked_segment[:next((i for i, token in enumerate(checked_segment) if is_redirection(token)), len(checked_segment))]
         if executable in {"echo", "printf"} or closed_git_listing(plain) or archive_command_is_read_only(
             shlex.join(plain), plain, True, CLOSED_READ_GIT_COMMANDS
         ):
             continue
+        if command_can_destroy_files(invocation) and closed_destructive_scope_reason(
+            list(invocation[1]), directories
+        ) is None:
+            # A literal delete entirely outside the repository and every state
+            # root is scratch cleanup, not new work on the closed milestone (#468).
+            continue
         return closed
     return None
 
 
+def runtime_hotfix_invocation(tokens):
+    """True when any simple command, prefixed or wrapped, names isolation.py then runtime-hotfix."""
+    for segment in command_segments(tokens):
+        for index, (token, following) in enumerate(zip(segment, [*segment[1:], ""])):
+            if following != "runtime-hotfix":
+                continue
+            clustered = re.fullmatch(r"-[A-Za-ln-z]*m(.+)", token)
+            if clustered:
+                module = clustered.group(1)
+            elif any(
+                earlier.startswith("-") and not earlier.startswith("--") and "m" in earlier
+                for earlier in segment[:index]
+            ):
+                module = token
+            else:
+                module = None
+            if token == "-" or token.replace("\\", "/").rsplit("/", 1)[-1] == "isolation.py" or (
+                module is not None and module.rsplit(".", 1)[-1] == "isolation"
+            ):
+                return True
+        try:
+            wrapped = wrapped_command_tokens(segment, expand_parameters=False)
+        except ValueError:  # the shape checks below refuse what cannot be unwrapped
+            continue
+        if wrapped is not None and runtime_hotfix_invocation(wrapped):
+            return True
+    return False
+
+
 def command_denial(command, working_directories, allow_destructive=True):
     """Return why a shell command is denied, or None when it may run."""
     working_directories = working_directories or [os.getcwd()]
@@ -4592,6 +5019,16 @@ def command_denial(command, working_directories, allow_destructive=True):
         ):
             return None
         bundled_helper = bundled_helper_invocation(command, tokens, working_directories)
+        # runtime-hotfix is an operator-only recovery (#480): its receipt is
+        # the owner authorization a landing later trusts, so an agent running
+        # the command self-authorizes. Deny by subcommand name regardless of
+        # the script's path.
+        if runtime_hotfix_invocation(tokens):
+            return (
+                "isolation.py runtime-hotfix records the owner authorization a "
+                "landing trusts; it is operator-only — request the hotfix from "
+                "the orchestrator instead of running it"
+            )
         destructive = list(destructive_shell_invocations(tokens))
         if destructive and (
             not allow_destructive
@@ -4605,6 +5042,16 @@ def command_denial(command, working_directories, allow_destructive=True):
             )
         ):
             return DESTRUCTIVE_SHAPE_REASON
+        if destructive:
+            state_reason = destructive_state_root_reason(
+                [operand for _, operands in destructive for operand in operands],
+                working_directories,
+            )
+            if state_reason:
+                return state_reason
+        expression_reason = powershell_expression_reason(tokens)
+        if expression_reason:
+            return expression_reason
         reason = closed_shell_execution_reason(command, tokens, working_directories)
         if reason:
             return reason

package/scripts/install.py

@@ -345,6 +345,9 @@ def install_member_hooks(coordinator: Path, member: Path, dry_run: bool = False)
     plan = []
     for name in GIT_HOOK_NAMES:
         hook, chained = hooks_dir / name, hooks_dir / f"{name}{CHAINED_HOOK_SUFFIX}"
+        if _hook_is_disabled(hooks_dir, name):
+            plan.append((name, hook, chained, False, True))
+            continue
         if hook.is_symlink() or chained.is_symlink():
             raise InstallerError(f"refusing a symlinked git hook: {hook}")
         if _lexists(hook) and not hook.is_file():
@@ -357,17 +360,21 @@ def install_member_hooks(coordinator: Path, member: Path, dry_run: bool = False)
         )
         if chain and _lexists(chained):
             raise InstallerError(f"cannot chain {hook}: {chained} already exists")
-        plan.append((name, hook, chained, chain))
+        plan.append((name, hook, chained, chain, False))
     lines = []
-    for name, hook, chained, chain in plan:
+    for name, hook, chained, chain, disabled in plan:
         note = " (keeps the existing hook as a chained hook)" if chain else ""
+        if disabled:
+            note = " (left disabled)"
         lines.append(f"member hook: {hook}{note}" + (" (dry run)" if dry_run else ""))
     if dry_run:
         return lines
     hooks_dir.mkdir(parents=True, exist_ok=True)
     staged = []
     try:
-        for name, _, _, _ in plan:
+        for name, _, _, _, disabled in plan:
+            if disabled:
+                continue
             temporary = hooks_dir / f".{name}.gsd-path-tmp"
             # O_EXCL already refuses any existing name; O_NOFOLLOW (absent on
             # Windows) adds defense in depth where it exists.
@@ -379,7 +386,9 @@ def install_member_hooks(coordinator: Path, member: Path, dry_run: bool = False)
                 if hasattr(os, "fchmod"):  # Windows before 3.13; Git for Windows needs no exec bit.
                     os.fchmod(output.fileno(), 0o755)
                 output.write(member_hook(interpreter, name).encode("utf-8"))
-        for name, hook, chained, chain in plan:
+        for name, hook, chained, chain, disabled in plan:
+            if disabled:
+                continue
             if chain:
                 os.replace(hook, chained)
             os.replace(hooks_dir / f".{name}.gsd-path-tmp", hook)
@@ -1308,11 +1317,25 @@ def _project_destinations(
         if hooks_dir is not None:
             for hook_name, generator in GIT_HOOKS:
                 hook = hooks_dir / hook_name
+                if _hook_is_disabled(hooks_dir, hook_name):
+                    continue
                 chained = _lexists(_chained_hook_path(hook)) or _foreign_git_hook(hook)
                 destinations.append((hook, None, generator(interpreter, chained), True))
     return destinations
 
 
+def _hook_is_disabled(hooks_dir: Path, hook_name: str) -> bool:
+    """Whether the user deliberately disabled this hook (#469).
+
+    A hook renamed to `<name>.disabled*` stays disabled: reinstalling beside
+    the rename would silently re-enable it. The rename only disables while
+    the active hook is absent — a leftover active hook next to a rename is
+    inspected and refreshed normally, never hidden. The convention matches
+    the installer's own `disabled-gsd-skills-<n>` rename style.
+    """
+    return not _lexists(hooks_dir / hook_name) and any(hooks_dir.glob(f"{hook_name}.disabled*"))
+
+
 def _native_settings_mergers(
     project: Path, selected: Sequence[str], hooks: bool
 ) -> Mapping[Path, Callable[[Path, str], str]]:
@@ -3050,6 +3073,13 @@ def doctor(
                     label = _describe_project_path(project, hook_path)
                     if hook_path in unreadable_git_hooks:
                         continue
+                    if _hook_is_disabled(hooks_dir, hook_name):
+                        push(
+                            "ok",
+                            f"hooks: {hook_name} is deliberately disabled "
+                            f"({hook_name}.disabled* present in {hooks_dir})",
+                        )
+                        continue
                     if not _lexists(hook_path):
                         push(
                             "fail",