fix(agent-guard): fail closed on lefthook install behind global options and package runners

The lefthook hooks-path guard took the first bare word as the subcommand,
so `lefthook --colors off install --force` read `off` and was allowed, and
`npx lefthook install --force` never reached the guard at all. Any
`install` word now makes the segment an install, and npx, pnpm, yarn, bun
and npm exec are looked through when they launch lefthook.

argv[0] is normalised once with the helper guarded_head uses, so git.exe
or a path-qualified git also reaches the git:* contributed guards.

Closes #1918

Author: mickwd

plugins/magpie-agent-guard/tools/agent-guard/src/agent_guard/__init__.py

@@ -325,13 +325,14 @@ def __init__(self, tokens: list[str], raw: str, command: str = "") -> None:
         #: The command head as written (`~/.claude/scripts/x.sh`, `/usr/bin/git`),
         #: for the rules that care how a command is spelled, not just its name.
         self.head = argv[0] if argv else ""
-        # Normalise the command head to its basename so a path-qualified
-        # invocation (`/usr/bin/git`, `./git`) is guarded identically to the
-        # bare name. Guard rules only inspect argv[0] as a command *name*; the
-        # real execution path is untouched (exec_main hands the original argv
-        # to os.execvp).
+        # Normalise the command head to its name so a path-qualified invocation
+        # (`/usr/bin/git`, `./git`, `C:\Git\cmd\git.exe`) is guarded identically
+        # to the bare name. Guard rules only inspect argv[0] as a command *name*;
+        # the real execution path is untouched (exec_main hands the original
+        # argv to os.execvp).
         if argv:
-            argv[0] = os.path.basename(argv[0])
+            argv[0] = command_name(argv[0])
+            argv = _package_runner_target(argv) or argv
         self.argv: list[str] = argv
         self.raw = raw
         #: The whole command line as written, before tokenising: the one place
@@ -2598,6 +2599,43 @@ def run(self, args: list[str]) -> str | None:
         return _run(args, cwd=self.cwd)
 
 
+def command_name(head: str) -> str:
+    """The name a command head runs: its basename on any platform, without ``.exe``.
+
+    :class:`Segment` stores ``argv[0]`` in this form, so the rules that key on
+    a literal ``argv[0] == "git"`` see the same name :func:`guarded_head` does.
+    """
+    base = head.replace("\\", "/").rsplit("/", 1)[-1]
+    if base.lower().endswith(".exe"):
+        base = base[:-4]
+    return base
+
+
+# Package runners that reach a package's binary without it being on PATH
+# (`npx lefthook`, `pnpm exec lefthook`, `yarn dlx lefthook`, `bunx lefthook`).
+_PACKAGE_RUNNERS = frozenset({"npx", "pnpx", "bunx", "npm", "pnpm", "yarn", "bun"})
+_RUNNER_TARGETS = frozenset({"lefthook"})
+
+
+def _package_runner_target(argv: list[str]) -> list[str] | None:
+    """The guarded command a package runner launches, or None.
+
+    Fails closed: the first word naming a guarded package (``lefthook``,
+    ``lefthook@1.11``, ``@evilmartians/lefthook``) is taken as the command, so
+    the runner's own options and subcommand never need parsing. Only package
+    managers whose CLI can run a package's binary are looked through.
+    """
+    if not argv or argv[0] not in _PACKAGE_RUNNERS:
+        return None
+    for index, token in enumerate(argv[1:], start=1):
+        if token.startswith("-"):
+            continue
+        package = token.rsplit("/", 1)[-1].split("@", 1)[0]
+        if package in _RUNNER_TARGETS:
+            return [package, *argv[index + 1 :]]
+    return None
+
+
 def guarded_head(argv: list[str]) -> str | None:
     """The guarded command family a segment runs, or None.
 
@@ -2607,13 +2645,8 @@ def guarded_head(argv: list[str]) -> str | None:
     """
     if not argv:
         return None
-    head = argv[0]
-    if head in GUARDED_HEADS:
-        return head
-    base = head.replace("\\", "/").rsplit("/", 1)[-1]
-    if base.lower().endswith(".exe"):
-        base = base[:-4]
-    return base if base in GUARDED_HEADS else None
+    name = command_name(argv[0])
+    return name if name in GUARDED_HEADS else None
 
 
 def command_kinds(seg: Segment) -> set[str]:
@@ -2637,10 +2670,14 @@ def command_kinds(seg: Segment) -> set[str]:
         sub = gh_subcommand(seg.argv)
         kinds.add(f"{head}:{sub[0] if sub else seg.argv[1]}")
     elif head == "lefthook":
-        # lefthook accepts global flags before the subcommand.
+        # lefthook accepts global flags before the subcommand, and one can take
+        # its value as a separate word (`--colors off install`), so the first
+        # bare word is not always the subcommand. Fail closed on `install`.
         lefthook_sub = next((tok for tok in seg.argv[1:] if not tok.startswith("-")), None)
         if lefthook_sub:
             kinds.add(f"lefthook:{lefthook_sub}")
+        if "install" in seg.argv[1:]:
+            kinds.add("lefthook:install")
     return kinds
 
 

plugins/magpie-setup/skills/isolated-setup-install/guards/lefthook_hooks_path.py

@@ -32,12 +32,14 @@
 
 
 def _install_arguments(argv):
-    """The arguments after the ``install`` subcommand, or an empty list."""
-    for index, token in enumerate(argv[1:], start=1):
-        if token.startswith("-"):
-            continue
-        return argv[index + 1 :] if token == "install" else []
-    return []
+    """Every argument of a ``lefthook install``, or an empty list.
+
+    A global option can take its value as a separate word (`lefthook --colors
+    off install --force`), so the first bare word is not always the subcommand.
+    Fail closed: any ``install`` word makes this an install, and every argument
+    is checked for a destructive flag.
+    """
+    return argv[1:] if "install" in argv[1:] else []
 
 
 def _destructive_flag(argument):

tools/agent-guard/README.md

@@ -136,7 +136,7 @@ way — see [Contributing guards](#contributing-guards)):
 | `mention` | `pr-management-triage` | `gh pr comment` / `gh issue comment` that `@`-mentions anyone other than the PR/issue author; **any** `@`-mention in `gh pr edit --body[-file]` | denoise: author-directed feedback never pings maintainers; body edits stay silent. Exempt: the operator commenting on their **own** PR/issue (author == authenticated `gh` user), and the `MAGPIE_ALLOW_MENTIONS=1` override |
 | `mark-ready` | `pr-management-triage` | adding `ready for maintainer review` while the PR head SHA has GitHub Actions runs awaiting approval | Golden rule 1b |
 | `security-language` | `security-issue-fix` | a CVE id / security-fix language in a **public** `gh pr create`/`gh pr edit` title/body (not comments) | public-PR scrubbing |
-| `lefthook-hooks-path` | `setup-isolated-setup-install` | `lefthook install --force` / `-f` or `--reset-hooks-path` / `-r` while the global `core.hooksPath` is the framework's | the first writes over the dispatcher for every repository, the second unsets the whole-user setup; the shim hides the global path, so a plain `lefthook install` is all that is needed. Override: `MAGPIE_ALLOW_LEFTHOOK_HOOKS_PATH=1` |
+| `lefthook-hooks-path` | `setup-isolated-setup-install` | `lefthook install --force` / `-f` or `--reset-hooks-path` / `-r` while the global `core.hooksPath` is the framework's, also behind global options and package runners (`npx`, `pnpm exec`, `yarn exec` / `dlx`, `bunx`) | the first writes over the dispatcher for every repository, the second unsets the whole-user setup; the shim hides the global path, so a plain `lefthook install` is all that is needed. Override: `MAGPIE_ALLOW_LEFTHOOK_HOOKS_PATH=1` |
 
 A denied command is **not** posted/run; the model is shown the reason and the
 deterministic fix (e.g. "use a backtick `` `login` `` instead of `@login`").

tools/agent-guard/src/agent_guard/__init__.py

@@ -325,13 +325,14 @@ def __init__(self, tokens: list[str], raw: str, command: str = "") -> None:
         #: The command head as written (`~/.claude/scripts/x.sh`, `/usr/bin/git`),
         #: for the rules that care how a command is spelled, not just its name.
         self.head = argv[0] if argv else ""
-        # Normalise the command head to its basename so a path-qualified
-        # invocation (`/usr/bin/git`, `./git`) is guarded identically to the
-        # bare name. Guard rules only inspect argv[0] as a command *name*; the
-        # real execution path is untouched (exec_main hands the original argv
-        # to os.execvp).
+        # Normalise the command head to its name so a path-qualified invocation
+        # (`/usr/bin/git`, `./git`, `C:\Git\cmd\git.exe`) is guarded identically
+        # to the bare name. Guard rules only inspect argv[0] as a command *name*;
+        # the real execution path is untouched (exec_main hands the original
+        # argv to os.execvp).
         if argv:
-            argv[0] = os.path.basename(argv[0])
+            argv[0] = command_name(argv[0])
+            argv = _package_runner_target(argv) or argv
         self.argv: list[str] = argv
         self.raw = raw
         #: The whole command line as written, before tokenising: the one place
@@ -2598,6 +2599,43 @@ def run(self, args: list[str]) -> str | None:
         return _run(args, cwd=self.cwd)
 
 
+def command_name(head: str) -> str:
+    """The name a command head runs: its basename on any platform, without ``.exe``.
+
+    :class:`Segment` stores ``argv[0]`` in this form, so the rules that key on
+    a literal ``argv[0] == "git"`` see the same name :func:`guarded_head` does.
+    """
+    base = head.replace("\\", "/").rsplit("/", 1)[-1]
+    if base.lower().endswith(".exe"):
+        base = base[:-4]
+    return base
+
+
+# Package runners that reach a package's binary without it being on PATH
+# (`npx lefthook`, `pnpm exec lefthook`, `yarn dlx lefthook`, `bunx lefthook`).
+_PACKAGE_RUNNERS = frozenset({"npx", "pnpx", "bunx", "npm", "pnpm", "yarn", "bun"})
+_RUNNER_TARGETS = frozenset({"lefthook"})
+
+
+def _package_runner_target(argv: list[str]) -> list[str] | None:
+    """The guarded command a package runner launches, or None.
+
+    Fails closed: the first word naming a guarded package (``lefthook``,
+    ``lefthook@1.11``, ``@evilmartians/lefthook``) is taken as the command, so
+    the runner's own options and subcommand never need parsing. Only package
+    managers whose CLI can run a package's binary are looked through.
+    """
+    if not argv or argv[0] not in _PACKAGE_RUNNERS:
+        return None
+    for index, token in enumerate(argv[1:], start=1):
+        if token.startswith("-"):
+            continue
+        package = token.rsplit("/", 1)[-1].split("@", 1)[0]
+        if package in _RUNNER_TARGETS:
+            return [package, *argv[index + 1 :]]
+    return None
+
+
 def guarded_head(argv: list[str]) -> str | None:
     """The guarded command family a segment runs, or None.
 
@@ -2607,13 +2645,8 @@ def guarded_head(argv: list[str]) -> str | None:
     """
     if not argv:
         return None
-    head = argv[0]
-    if head in GUARDED_HEADS:
-        return head
-    base = head.replace("\\", "/").rsplit("/", 1)[-1]
-    if base.lower().endswith(".exe"):
-        base = base[:-4]
-    return base if base in GUARDED_HEADS else None
+    name = command_name(argv[0])
+    return name if name in GUARDED_HEADS else None
 
 
 def command_kinds(seg: Segment) -> set[str]:
@@ -2637,10 +2670,14 @@ def command_kinds(seg: Segment) -> set[str]:
         sub = gh_subcommand(seg.argv)
         kinds.add(f"{head}:{sub[0] if sub else seg.argv[1]}")
     elif head == "lefthook":
-        # lefthook accepts global flags before the subcommand.
+        # lefthook accepts global flags before the subcommand, and one can take
+        # its value as a separate word (`--colors off install`), so the first
+        # bare word is not always the subcommand. Fail closed on `install`.
         lefthook_sub = next((tok for tok in seg.argv[1:] if not tok.startswith("-")), None)
         if lefthook_sub:
             kinds.add(f"lefthook:{lefthook_sub}")
+        if "install" in seg.argv[1:]:
+            kinds.add("lefthook:install")
     return kinds
 
 

tools/agent-guard/tests/test_guards.py

@@ -433,6 +433,14 @@ def test_no_verify_guard_denied_past_a_global_flag():
     assert reason and "no-verify" in reason
 
 
+@pytest.mark.parametrize("head", ["/usr/bin/git", "/mingw64/bin/git.exe", "git.exe"])
+def test_no_verify_guard_denied_for_a_path_qualified_git(head):
+    # guarded_head let these through to the guards, but the `git:commit`
+    # TRIGGERS pre-filter keyed on a literal argv[0] == "git".
+    reason = dispatch(f'{head} commit -m "x" --no-verify')
+    assert reason and "no-verify" in reason
+
+
 # --------------------------------------------------------------------------- #
 # contributed-guard discovery
 # --------------------------------------------------------------------------- #

tools/agent-guard/tests/test_skill_guards.py

@@ -608,6 +608,20 @@ def handler(args):
         ("lefthook install -rf=false", "--reset-hooks-path"),
         ("lefthook --verbose install --force", "--force"),
         ("./node_modules/.bin/lefthook install --force", "--force"),
+        ("lefthook --colors off install --force", "--force"),
+        ("lefthook --colors off install -r", "--reset-hooks-path"),
+        ("lefthook install pre-commit --force", "--force"),
+        ("npx lefthook install --force", "--force"),
+        ("npx -y lefthook@1.11.0 install -f", "--force"),
+        ("npx @evilmartians/lefthook install --force", "--force"),
+        ("npm exec -- lefthook install --force", "--force"),
+        ("pnpm exec lefthook install --reset-hooks-path", "--reset-hooks-path"),
+        ("pnpm --filter app exec lefthook install -f", "--force"),
+        ("pnpm dlx lefthook install --force", "--force"),
+        ("yarn exec lefthook install -f", "--force"),
+        ("yarn dlx lefthook install --force", "--force"),
+        ("bunx lefthook install -r", "--reset-hooks-path"),
+        ("env CI=1 npx lefthook --colors off install --force", "--force"),
     ],
 )
 def test_lefthook_destructive_install_denied(monkeypatch, hooks_path, command, flag):
@@ -623,6 +637,12 @@ def test_lefthook_destructive_install_denied(monkeypatch, hooks_path, command, f
         "lefthook install --verbose",
         "lefthook run pre-commit",
         "lefthook --version",
+        "lefthook --colors off install",
+        "npx lefthook install",
+        "npx lefthook run pre-commit --force",
+        "npm install --save-dev lefthook --force",
+        "pnpm add -D lefthook",
+        "npx prettier --write install",
     ],
 )
 def test_lefthook_plain_invocations_allowed(monkeypatch, command):