@codyswann/lisa 4.28.2 → 4.28.3

package/package.json

@@ -162,7 +162,7 @@
     "zod-validation-error": "^4.0.0"
   },
   "name": "@codyswann/lisa",
-  "version": "4.28.2",
+  "version": "4.28.3",
   "description": "Claude Code governance framework that applies guardrails, guidance, and automated enforcement to projects",
   "main": "dist/index.js",
   "exports": {
@@ -307,6 +307,6 @@
     "test": "tests"
   },
   "types": "./dist/index.d.ts",
-  "lisaReleaseCommit": "c29ccdefd340be9823edcb4ccd85add8e4a62693",
-  "gitHead": "c29ccdefd340be9823edcb4ccd85add8e4a62693"
+  "lisaReleaseCommit": "050e7ef3bffff5eff7e48b93984db171aa46c564",
+  "gitHead": "050e7ef3bffff5eff7e48b93984db171aa46c564"
 }

package/plugins/lisa/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "4.28.2",
+  "version": "4.28.3",
   "description": "Universal governance — agents, skills, commands, hooks, and rules for all projects",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "4.28.2",
+  "version": "4.28.3",
   "description": "Universal governance: agents, skills, commands, hooks, and rules for all projects.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa/hooks/block-no-verify.agy.sh

@@ -26,6 +26,9 @@
 # on PreToolUse. jq parses the JSON envelope (per project rule: never grep/sed
 # JSON); the command string itself is matched with grep (it is a plain string,
 # not JSON). Malformed/empty stdin → allow (fail open, never crash the tool).
+#
+# Capability names below are the canonical guard's, kept identical on every agent.
+# lisa-guard-capabilities: no-verify-abbrev, husky-env, hookspath-allowlist, config-env, env-split-string, git-config-key, git-config-parameters, git-config-parameters-append, git-config-parameters-expansion, heredoc-shell-word, herestring-aware, no-verify-short, nested-shell-no-verify, nested-shell-long-options, env-split-string-abbrev, command-wrapper-normalization
 set -uo pipefail
 
 allow() {
@@ -100,10 +103,42 @@ except ValueError:
 
 normalized_tokens = [token.strip("();|&") for token in tokens]
 
-# Git resolves any UNAMBIGUOUS abbreviation of a long option, so `--no-veri`
-# skips hooks exactly as completely as `--no-verify`. Matched as a prefix
-# rather than by listing abbreviations; `--no-verbose` diverges after
-# `--no-ver` and so is correctly not caught.
+# The only relocations that keep a repo's own hooks in play. `.husky` is the
+# husky convention this fleet runs; `.githooks` is the common hand-rolled one.
+# Anything else — including "" and /dev/null, which are simply the two most
+# obvious members of the blocked set rather than special cases — is refused.
+PERMITTED_HOOKS_PATHS = {".husky", ".githooks"}
+
+
+def is_permitted_hooks_path(value):
+    """Whether a core.hooksPath value relocates hooks rather than disabling them.
+
+    Args:
+        value: The raw core.hooksPath value as it appeared on the command line.
+
+    Returns:
+        True if the path is an established in-repo hooks directory.
+    """
+    cleaned = value.strip().strip("'\"")
+    if cleaned.startswith("./"):
+        cleaned = cleaned[2:]
+    return cleaned.rstrip("/") in PERMITTED_HOOKS_PATHS
+
+
+# Git resolves any UNAMBIGUOUS abbreviation of a long option, so `--no-verify`
+# is only the longest of the spellings that disable verification: `git commit
+# --no-veri` skips hooks exactly as completely. An equality check therefore
+# enforced the guard against the one spelling nobody in a hurry types.
+#
+# Matched as "a prefix of --no-verify" rather than by listing abbreviations,
+# because the set of accepted abbreviations is a property of git's parser and
+# changes with the surrounding options. `--no-verbose` is NOT caught, and must
+# not be: it diverges from `--no-verify` at the character after `--no-ver`, so
+# it fails the prefix test.
+#
+# The floor is `--no-v`. Shorter is refused anyway — bare `--no-` is not a flag
+# — and blocking an abbreviation git would reject as ambiguous costs nothing,
+# while missing one git accepts costs the whole guard.
 NO_VERIFY = "--no-verify"
 NO_VERIFY_MIN_PREFIX = len("--no-v")
 
@@ -123,89 +158,113 @@ def disables_verification(token):
         and NO_VERIFY.startswith(token)
     )
 
-# The only relocations that keep a repo's own hooks in play. Anything else —
-# including "" and /dev/null, which are simply the two most obvious members of
-# the blocked set rather than special cases — is refused.
-PERMITTED_HOOKS_PATHS = {".husky", ".githooks"}
-
-
-def is_permitted_hooks_path(value):
-    """Whether a core.hooksPath value relocates hooks rather than disabling them.
-
-    Args:
-        value: The raw core.hooksPath value as it appeared on the command line.
-
-    Returns:
-        True if the path is an established in-repo hooks directory.
-    """
-    cleaned = value.strip().strip("'\"")
-    if cleaned.startswith("./"):
-        cleaned = cleaned[2:]
-    return cleaned.rstrip("/") in PERMITTED_HOOKS_PATHS
-
 
 # `git commit -n` is the short spelling of --no-verify and skips pre-commit and
-# commit-msg identically; so does a cluster such as `-nm "msg"`. Matching it
-# needs SCOPE, which is why it was long excluded: `-n` means --dry-run to `git
-# push`, --no-stat to `git merge`, and a line count to head/tail/sort/grep. Only
-# `git commit` reads it as a hook bypass, so only that invocation's argv is
-# scanned. Parity with the Claude block-no-verify.sh, which carries the full
-# rationale for why a tokenizer can make this distinction and a grep could not.
+# commit-msg identically. Matching it needs one thing the `--no-verify` scan
+# above does not: SCOPE. `-n` means --dry-run to `git push`, --no-stat to `git
+# merge`, and a line count to head/tail/sort/grep, so a token-anywhere match
+# would refuse ordinary commands all day. Only `git commit` reads it as a hook
+# bypass, so only that invocation's argv is scanned.
 #
-# A SECOND tokenizer pass, deliberately not shared with the checks above:
-# `shlex.split` glues `|` and `;` to their neighbours, so `git commit -m x &&
-# grep -n foo` would read as one long git invocation and refuse the grep.
-# `punctuation_chars=True` emits the operators as their own tokens, giving the
-# scan a boundary to stop at.
+# The tokenizer below is a SECOND pass, deliberately not shared with the one the
+# checks above use. `shlex.split` leaves `|` and `;` glued to their neighbours,
+# which those checks paper over by stripping the punctuation off each token —
+# fine when the question is "does this token look like a bypass anywhere in the
+# line", fatal when the question is "where does this command end", because
+# `git commit -m x && grep -n foo` would then read as one long git invocation
+# and refuse the grep. `punctuation_chars=True` emits the operators as their own
+# tokens, so the invocation's boundary is a token the scan can stop at.
 COMMAND_SEPARATORS = {
     ";", "|", "||", "&", "&&", "(", ")", "<", ">", ">>", "<<", "&|",
 }
 
-# GNU env's long options in FULL, so an ABBREVIATION can be resolved against
-# them: getopt_long accepts any prefix naming exactly one option, and nothing
-# but --split-string starts with `s`, so `env --s` splits a string just as
-# completely as `env --split-string` does.
+SHELL_PROGRAMS = {"bash", "dash", "ksh", "sh", "zsh"}
+MAX_SHELL_NESTING = 8
+
+# GNU env's long options, listed in FULL so an abbreviation can be resolved
+# against them. getopt_long accepts any prefix that names exactly one option,
+# and no other env option begins with `s` — so `env --s`, `env --sp`, and
+# `env --split` are `env --split-string` just as completely as the full
+# spelling is. Matching only the full spelling is bypassed by deleting
+# characters, which is why the set below exists instead of a literal list of
+# the two spellings the guard used to know.
 ENV_LONG_OPTIONS = {
     "--argv0", "--block-signals", "--chdir", "--debug", "--default-signal",
     "--help", "--ignore-environment", "--ignore-signal",
     "--list-signal-handling", "--null", "--split-string", "--unset",
     "--version",
 }
-# Of those, the ones whose value is a SEPARATE token. The signal options take
-# an OPTIONAL value, which GNU reads only when attached with `=`.
+# Of those, the ones whose value is a SEPARATE token, so the operand is never
+# mistaken for the command (`env -u bash -c ...` consumes `bash` as the
+# variable name). The signal options take an OPTIONAL value, which GNU reads
+# only when it is attached with `=`, so they never consume a following token.
 ENV_LONG_SEPARATE_VALUE = {"--argv0", "--chdir", "--split-string", "--unset"}
+
+# env's single-letter options, by whether the rest of a cluster is more
+# options or the option's value.
 ENV_SHORT_NO_VALUE = frozenset("i0v")
 ENV_SHORT_TAKES_VALUE = frozenset("uCaS")
 
-# Builtins and wrappers that run whatever FOLLOWS them without changing what it
-# is, so `command env -S ...` runs exactly the `env` that `env -S ...` runs.
+# Builtins and wrappers that run whatever FOLLOWS them without changing what
+# it is: `command env -S ...` runs exactly the `env` that `env -S ...` runs,
+# and `env -- env -S ...` runs exactly the inner `env`. Reading the wrapper as
+# the command is how a payload hides from a guard that inspects only the first
+# word of an invocation.
 COMMAND_PREFIX_WRAPPERS = {"command", "exec", "builtin", "nohup", "setsid"}
+# The only option of those that consumes a separate following token
+# (`exec -a NAME env -S ...`).
 COMMAND_PREFIX_SEPARATE_VALUE = {"-a"}
 
-# git's own options taking a SEPARATE value token, skipped when looking for the
-# subcommand so `git -c core.hooksPath=x commit` still reaches `commit`.
+# Shell options whose following token is an operand, not another option. The
+# generic recursive scanner must step over these before looking for `-c`.
+SHELL_OPTIONS_SEPARATE_VALUE = {
+    "-o", "+o", "-O", "+O", "--rcfile", "--init-file", "--emulate",
+}
+SHELL_OPTIONS_INLINE_VALUE = ("--rcfile=", "--init-file=", "--emulate=")
+
+# Boolean long options of the recognized shells. Listed only for PRECISION:
+# a long option is never the command-string flag either way, but naming the
+# ordinary ones keeps `bash --norc script.sh` from being treated as a possible
+# value-taking option whose operand must be scanned past. zsh and ksh accept a
+# long option per shell setting, so this set is deliberately not exhaustive —
+# the scanner stays correct on the ones it does not name.
+SHELL_LONG_OPTIONS_NO_VALUE = {
+    "--debugger", "--dump-po-strings", "--dump-strings", "--emacs",
+    "--globalrcs", "--help", "--interactive", "--login", "--monitor",
+    "--no-globalrcs", "--no-rcs", "--noediting", "--noprofile", "--norc",
+    "--norcs", "--posix", "--pretty-print", "--privileged", "--protected",
+    "--rcs", "--restricted", "--verbose", "--version", "--vi", "--wordexp",
+    "--xtrace",
+}
+
+# git's own options that take a SEPARATE value token, which therefore must be
+# skipped when looking for the subcommand: `git -c core.hooksPath=x commit` and
+# `git -C /repo commit` both reach `commit`.
 GIT_GLOBAL_SEPARATE_VALUE = {
     "-c", "-C", "--config-env", "--git-dir", "--work-tree",
     "--namespace", "--exec-path", "--super-prefix",
 }
 
-# `git commit` long options whose value can be a separate token, listed so the
-# VALUE is never read as a flag (`git commit --author "A -n B" -m x` is fine).
-# Only genuinely value-taking options belong here: a boolean added by mistake
-# would swallow the next token and miss `git commit --amend -n`.
+# `git commit` long options whose value can be a separate token. Listed so the
+# VALUE is never mistaken for a flag — `git commit --author "A -n B" -m x`
+# must stay allowed. Only genuinely value-taking options belong here: adding a
+# boolean one by mistake would swallow the token after it, and `git commit
+# --amend -n` would go unnoticed.
 COMMIT_LONG_SEPARATE_VALUE = {
     "--message", "--file", "--author", "--date", "--template", "--cleanup",
     "--reuse-message", "--reedit-message", "--fixup", "--squash",
     "--pathspec-from-file", "--trailer",
 }
 
-# Short options REQUIRING a value. In a cluster the value is whatever follows in
-# the same token, or the next token when nothing does — which is why `-mn` is
-# the message "n" and not a bypass, while `-nm msg` is one.
+# Short `git commit` options that REQUIRE a value: `-m`/`-F`/`-c`/`-C`/`-t`.
+# In a cluster the value is whatever follows them in the same token, or the next
+# token when nothing does — which is why `-mn` is the message "n" and not a
+# bypass, and `-nm msg` IS one.
 COMMIT_SHORT_REQUIRED_VALUE = set("mFcCt")
 
-# Short options taking an OPTIONAL value, which git reads only when attached:
-# `-uno` is --untracked-files=no, so `-un` is a mode and not a bypass.
+# Short options taking an OPTIONAL value, which git only ever reads attached:
+# `-uno` is --untracked-files=no, `-Skeyid` is --gpg-sign=keyid. The cluster
+# ends at them either way, so `-un` is untracked-files "n" rather than a bypass.
 COMMIT_SHORT_OPTIONAL_VALUE = set("uS")
 
 
@@ -245,8 +304,8 @@ def shell_tokens(text):
         line_boundaries_as_separators(text), posix=True, punctuation_chars=True
     )
     lexer.whitespace_split = True
-    # shlex treats `#` as a comment introducer and would truncate the line;
-    # `shlex.split` disables it, and so must this.
+    # shlex treats `#` as a comment introducer by default and would silently
+    # truncate the rest of the line; `shlex.split` disables it, and so must this.
     lexer.commenters = ""
     return list(lexer)
 
@@ -258,13 +317,17 @@ def cluster_skips_verification(cluster):
         cluster: A single token beginning with one `-`, e.g. `-nm` or `-mn`.
 
     Returns:
-        A pair (bypasses, consumes_next_token).
+        A pair (bypasses, consumes_next_token). `bypasses` is True when a real
+        `-n` option is present; `consumes_next_token` is True when the cluster
+        ends in a value-taking option whose value is the following token.
     """
     body = cluster[1:]
     for offset, letter in enumerate(body):
         if letter == "n":
             return (True, False)
         if letter in COMMIT_SHORT_REQUIRED_VALUE:
+            # Everything after this letter is the value. It is a separate token
+            # only when nothing is attached.
             return (False, offset == len(body) - 1)
         if letter in COMMIT_SHORT_OPTIONAL_VALUE:
             return (False, False)
@@ -284,12 +347,15 @@ def commit_bypasses_verification(argv):
     while index < len(argv):
         token = argv[index]
         index += 1
-        # `--` ends the options; a file legitimately named `-n` is not a bypass.
+        # `--` ends the options; everything after it is a pathspec, and a file
+        # legitimately named `-n` is not a bypass.
         if token in COMMAND_SEPARATORS or token == "--":
             return False
         if token.startswith("--"):
             if token in COMMIT_LONG_SEPARATE_VALUE:
                 index += 1
+            elif disables_verification(token):
+                return True
             continue
         # A bare `-` is git's stdin placeholder, not an option cluster.
         if not token.startswith("-") or token == "-":
@@ -324,10 +390,14 @@ def subcommand_after_git(tokens, start):
 
 
 def resolve_env_long_option(name):
-    """Resolve one env long option, abbreviations included.
+    """Resolve one GNU env long option, abbreviations included.
 
-    Returns the full spelling, "" when the abbreviation names several options
-    (real env refuses those), or None when nothing matches.
+    Args:
+        name: A token beginning with `--`, with any `=value` already removed.
+
+    Returns:
+        The full option spelling; "" when the abbreviation names more than one
+        option, which real env refuses; None when nothing matches at all.
     """
     if not name.startswith("--") or name == "--":
         return None
@@ -340,17 +410,24 @@ def resolve_env_long_option(name):
 
 
 def env_option_kind(token):
-    """Classify one token in an `env` option position.
+    """Classify one token sitting in an `env` option position.
 
-    Returns "split-string", "separate-value", "no-value", "ambiguous" when env
-    accepts the token but this parser cannot name it, or None when the token is
-    not an option at all.
+    Returns:
+        "split-string" when env will reparse an argv value as shell words,
+        "separate-value" when the NEXT token is this option's operand,
+        "no-value" when the token stands alone, "ambiguous" when env accepts
+        the token but this parser cannot say which option it is, or None when
+        the token is not an option.
     """
     if not token.startswith("-") or token in {"-", "--"}:
         return None
     if token.startswith("--"):
-        resolved = resolve_env_long_option(token.split("=", 1)[0])
+        name = token.split("=", 1)[0]
+        resolved = resolve_env_long_option(name)
         if not resolved:
+            # Either unknown to this parser or an abbreviation naming several
+            # options. Neither can be reasoned about, so say so and let the
+            # caller fail closed rather than read past it.
             return "ambiguous"
         if resolved == "--split-string":
             return "split-string"
@@ -363,8 +440,8 @@ def env_option_kind(token):
         if letter == "S":
             return "split-string"
         if letter in ENV_SHORT_TAKES_VALUE:
-            # The rest of the cluster is the option's value when there is one;
-            # otherwise the value is the following token.
+            # The rest of this cluster is the option's value when there is
+            # one; otherwise the value is the following token.
             return "no-value" if position <= len(token) - 1 else "separate-value"
         if letter not in ENV_SHORT_NO_VALUE:
             return "ambiguous"
@@ -372,17 +449,24 @@ def env_option_kind(token):
 
 
 def strip_command_prefix(prefix):
-    """Drop tokens that precede a command without changing what it is.
+    """Drop the tokens that precede a command without changing what it is.
+
+    Variable assignments, the `command`/`exec`/`builtin` builtins, and nested
+    `env` wrappers all leave the following word in command position. Reading
+    any of them as the command itself is what let `command env -S ...` and
+    `env -- env -S ...` slip past the split-string check: the prefix failed
+    the "assignments only" test, so the wrapped `env` was never classified.
 
-    Assignments, the `command`/`exec`/`builtin` builtins, and nested `env`
-    wrappers all leave the following word in command position. Reading any of
-    them as the command is what let `command env -S ...` and `env -- env -S
-    ...` past the split-string check: the prefix failed the assignments-only
-    test, so the wrapped `env` was never classified.
+    Args:
+        prefix: The tokens between the last command separator and the
+            candidate program.
 
-    Returns a pair (status, remainder): "ok" with whatever still stands before
-    the candidate, "operand" when the candidate is a wrapper option's value,
-    or "ambiguous" when an option could not be classified.
+    Returns:
+        A pair (status, remainder). "ok" carries the tokens still standing
+        between the separator and the candidate — empty means the candidate is
+        in command position. "operand" means the candidate is a wrapper
+        option's value rather than a command. "ambiguous" means a wrapper
+        option could not be classified and the caller must fail closed.
     """
     cursor = 0
     while cursor < len(prefix):
@@ -417,6 +501,8 @@ def strip_command_prefix(prefix):
                 if kind == "ambiguous":
                     return ("ambiguous", [])
                 if kind == "split-string":
+                    # Everything after `-S` is env's own opaque payload, so the
+                    # candidate is not a command at all.
                     return ("operand", [])
                 if kind == "separate-value":
                     if cursor + 1 >= len(prefix):
@@ -429,8 +515,33 @@ def strip_command_prefix(prefix):
     return ("ok", prefix[cursor:])
 
 
+def shell_starts_command(tokens, index):
+    """Whether a recognized shell token occupies command position."""
+    start = index - 1
+    while start >= 0 and tokens[start] not in COMMAND_SEPARATORS:
+        start -= 1
+    status, remainder = strip_command_prefix(tokens[start + 1:index])
+    if status == "ambiguous":
+        # A prefix option this parser cannot classify may still be launching
+        # the shell. Fail closed rather than trusting the wrapper.
+        return True
+    return status == "ok" and not remainder
+
+
 def env_uses_split_string(tokens, index):
-    """Whether a command-position env invocation reparses an opaque payload."""
+    """Whether a command-position env invocation uses split-string parsing.
+
+    `env -S` reparses one opaque argv value as shell-like words. Inspecting the
+    outer command cannot prove what executable or nested shell that second
+    parse will produce, so the verification guard refuses the ambiguous form.
+
+    Args:
+        tokens: The full operator-aware token list.
+        index: Index of the candidate env executable.
+
+    Returns:
+        True when env will reparse a split-string payload.
+    """
     start = index - 1
     while start >= 0 and tokens[start] not in COMMAND_SEPARATORS:
         start -= 1
@@ -444,9 +555,11 @@ def env_uses_split_string(tokens, index):
         if token in COMMAND_SEPARATORS or token == "--":
             return False
         kind = env_option_kind(token)
-        if kind in {"split-string", "ambiguous"}:
-            # An option this parser cannot name makes the rest of the
-            # invocation unreadable; refuse instead of reading past it.
+        if kind == "split-string":
+            return True
+        if kind == "ambiguous":
+            # An option env accepts but this parser cannot name makes the rest
+            # of the invocation unreadable; refuse instead of reading past it.
             return True
         if kind is None:
             if "=" in token and not token.startswith(("=", "-")):
@@ -457,11 +570,55 @@ def env_uses_split_string(tokens, index):
     return False
 
 
-def git_commit_skips_verification(text):
+def nested_shell_payload(tokens, index):
+    """Return a shell `-c` payload, or True when option parsing is ambiguous."""
+    cursor = index + 1
+    opaque_option_seen = False
+    while cursor < len(tokens):
+        option = tokens[cursor]
+        if option in COMMAND_SEPARATORS or option == "--":
+            return None
+        if not option.startswith(("-", "+")):
+            # Ordinarily the script operand, which ends option parsing. After
+            # a long option this parser cannot name it may instead be that
+            # option's value (`zsh --emulate ksh -c ...`), so keep scanning
+            # rather than concluding there is no command string.
+            if not opaque_option_seen:
+                return None
+            cursor += 1
+            continue
+        if option in SHELL_OPTIONS_SEPARATE_VALUE:
+            if cursor + 1 >= len(tokens) or tokens[cursor + 1] in COMMAND_SEPARATORS:
+                return True
+            cursor += 2
+            continue
+        if option.startswith(SHELL_OPTIONS_INLINE_VALUE):
+            cursor += 1
+            continue
+        # A LONG option is never the command-string flag, and testing it for a
+        # bare `c` was the bug: `--norc` and `--restricted` merely CONTAIN one,
+        # so the real `-c` that followed was consumed as their payload and the
+        # nested `git commit --no-verify` was never classified at all. The
+        # command string lives only in a single-dash cluster (`-c`, `-lc`).
+        if option.startswith("--"):
+            if option not in SHELL_LONG_OPTIONS_NO_VALUE:
+                opaque_option_seen = True
+            cursor += 1
+            continue
+        if "c" in option[1:]:
+            if cursor + 1 >= len(tokens) or tokens[cursor + 1] in COMMAND_SEPARATORS:
+                return True
+            return tokens[cursor + 1]
+        cursor += 1
+    return None
+
+
+def git_commit_skips_verification(text, depth=0):
     """Whether the command runs `git commit` with the short `-n` bypass.
 
     Args:
         text: The command line, heredoc payloads already stripped.
+        depth: Number of recognized shell payloads already traversed.
 
     Returns:
         True if any `git commit` invocation on the line skips verification.
@@ -483,6 +640,21 @@ def git_commit_skips_verification(text):
         found = subcommand_after_git(scoped_tokens, index + 1)
         if found and found[0] == "commit" and commit_bypasses_verification(found[1]):
             return True
+    if depth >= MAX_SHELL_NESTING:
+        return True
+    for index, token in enumerate(scoped_tokens):
+        program = token.rsplit("/", 1)[-1]
+        if program not in SHELL_PROGRAMS or not shell_starts_command(
+            scoped_tokens, index
+        ):
+            continue
+        payload = nested_shell_payload(scoped_tokens, index)
+        if payload is True:
+            return True
+        if isinstance(payload, str) and git_commit_skips_verification(
+            payload, depth + 1
+        ):
+            return True
     return False
 
 
@@ -494,11 +666,19 @@ for i, token in enumerate(normalized_tokens):
         sys.exit(1)
     if token == "HUSKY=0" or token.startswith("HUSKY_SKIP_HOOKS="):
         sys.exit(1)
-    # Allowlist the destinations, do not denylist the disabling ones: hooks are
-    # disabled just as completely by any directory that happens to contain none
-    # (`-c core.hooksPath=/tmp/empty`), so the set that DISABLES hooks is
-    # unbounded while the set that legitimately relocates them is tiny. Matched
-    # case-insensitively because git config names are.
+    # Allowlist the destinations, do not denylist the disabling ones.
+    #
+    # This used to block only "" and /dev/null. But hooks are disabled just as
+    # completely by pointing hooksPath at any directory that happens to contain
+    # none — `-c core.hooksPath=/tmp/empty` bypassed every hook while reading as
+    # an ordinary path — so a denylist of "obviously disabling" values can
+    # always be stepped around by naming a third thing. The set of paths that
+    # DISABLE hooks is unbounded; the set that legitimately relocates them is
+    # tiny and known, so the allowlist is the only side that can be enumerated.
+    #
+    # Matched case-insensitively because git config variable names are:
+    # `CORE.HOOKSPATH=/x` and `core.hookspath=/x` are the same setting to git,
+    # so a case-sensitive check is bypassed by holding down shift.
     lowered = token.lower()
     if lowered.startswith("core.hookspath="):
         if not is_permitted_hooks_path(token.split("=", 1)[1]):
@@ -506,30 +686,55 @@ for i, token in enumerate(normalized_tokens):
     if lowered == "core.hookspath" and i + 1 < len(normalized_tokens):
         if not is_permitted_hooks_path(normalized_tokens[i + 1]):
             sys.exit(1)
-    # `--config-env=core.hooksPath=SOMEVAR` reads the path out of the named env
-    # var, so it is not in the command at all and cannot be allowlisted.
+    # `git --config-env=core.hooksPath=SOMEVAR` sets the same config, reading
+    # the value out of the named environment variable. The path therefore is
+    # not in the command at all, so there is nothing to allowlist against —
+    # SOMEVAR can hold anything by the time git reads it. Any core.hooksPath
+    # routed through --config-env is refused outright.
     if lowered.startswith("--config-env="):
         spec = token.split("=", 1)[1]
         if spec.split("=", 1)[0].strip().lower() == "core.hookspath":
             sys.exit(1)
-    # git also accepts `--config-env <name>=<envvar>` as two tokens. Guarding
-    # only the `=` spelling let the trailing `core.hooksPath=.husky` fall
-    # through to the allowlist above, which reads `.husky` as a path — but here
-    # it names an ENVIRONMENT VARIABLE, which can hold /dev/null. Checked at the
-    # `--config-env` token, which the loop reaches first.
+    # git accepts `--config-env <name>=<envvar>` as TWO tokens as well as one,
+    # and guarding only the `=` spelling was worse than missing the separate
+    # form outright: the trailing `core.hooksPath=.husky` then fell through to
+    # the allowlist above, which reads `.husky` as a PATH and permits it. But
+    # here it is an ENVIRONMENT VARIABLE NAME, and `env '.husky=/dev/null' git
+    # --config-env core.hooksPath=.husky` really does resolve hooksPath to
+    # /dev/null. The allowlist was being used as the bypass.
+    #
+    # Checked at the `--config-env` token, which the loop reaches first, so the
+    # refusal happens before the value token can be mistaken for a path.
     if lowered == "--config-env" and i + 1 < len(normalized_tokens):
         spec = normalized_tokens[i + 1]
         if spec.split("=", 1)[0].strip().strip("'\"").lower() == "core.hookspath":
             sys.exit(1)
     # `GIT_CONFIG_COUNT=1 GIT_CONFIG_KEY_0=core.hooksPath
-    # GIT_CONFIG_VALUE_0=/dev/null git ...` sets the same command-scope config
-    # via env-var-style assignments. The index is arbitrary below
-    # GIT_CONFIG_COUNT, so it is matched as `\d+` rather than pinned to 0.
+    # GIT_CONFIG_VALUE_0=/dev/null git commit` sets command-scope config the
+    # same way `-c core.hooksPath=...` does — env-var-style assignments ahead of
+    # the invocation instead of a flag — so it disables every hook just as
+    # completely while matching none of the token shapes above. Upstream missed
+    # this until a downstream fork hardened its own copy against it, which is
+    # the one direction a guard must never be caught in.
+    #
+    # The index is matched as `\d+` rather than pinned to 0: git accepts any
+    # index below GIT_CONFIG_COUNT, so a single-index check is evaded by typing
+    # a 1. Refused outright, like --config-env=, because the path lives in a
+    # separate GIT_CONFIG_VALUE_<n> token that can be exported earlier,
+    # reordered, or left out entirely — there is nothing here to allowlist
+    # against.
     key_match = re.match(r"git_config_key_\d+=(.*)$", lowered, re.DOTALL)
     if key_match and key_match.group(1).strip().strip("'\"") == "core.hookspath":
         sys.exit(1)
+    # `git -c` propagates command-scope config through GIT_CONFIG_PARAMETERS.
+    # Parsing the value as Git's shell-quoted parameter list distinguishes the
+    # key from an unrelated value that merely contains the same text.
     if re.match(r"git_config_parameters\+?=", lowered):
         parameters = token.split("=", 1)[1]
+        # The guard sees the command before the shell expands assignments. A
+        # variable or command substitution can therefore hide hooksPath from
+        # this parser and reveal it only to Git. Refuse unresolved values; the
+        # guard cannot safely prove what configuration they will become.
         if "$" in parameters or "`" in parameters:
             sys.exit(1)
         try: