@rmyndharis/aimhooman 0.1.2 → 0.1.3

package/src/hook.mjs

@@ -237,6 +237,14 @@ function hookPreToolUse(input) {
             }
             targetRepo = openRepo(gitCommand.cwd);
             const targetProfile = enforcementPolicy(targetRepo).profile;
+            // Some ref-mutation verbs have read-only listing forms that move no
+            // ref and so cannot bypass the reference-transaction guard. Reading
+            // a repository (`git branch | grep`, `git remote -v | grep origin`,
+            // `git stash list | head`) is everyday work; refusing it behind a
+            // pipeline forced developers out of their normal workflow. A real
+            // mutation still carries a mutating flag or positional and stays
+            // subject to every check below.
+            if (gitReadOnlyRefCommand(gitCommand.verb, gitCommand.args || [])) continue;
             // An unresolved subcommand/alias may itself move a ref. When its
             // hook path or execution context is altered, there is no safe
             // content snapshot to fall back to, so treat it like a direct ref
@@ -285,6 +293,18 @@ function hookPreToolUse(input) {
                     "Run 'aimhooman init' and retry."
                 );
             }
+            // The hooks are installed but this command routes around them. Unlike
+            // --no-verify, which leaves reference-transaction to catch the ref
+            // update, an overridden hooks path removes every managed guard at
+            // once, so there is nothing downstream to delegate to. Persisting the
+            // same override already denies, so this keeps the two forms agreeing.
+            if (gitCommand.verb === 'commit' && gitCommand.hooksPathOverride) {
+                return emitDecision(
+                    'deny',
+                    'aimhooman cannot verify the managed pre-commit and reference-transaction guards for '
+                    + 'git commit when the command overrides the hooks path; run the commit without the override.'
+                );
+            }
             if (targetProfile !== 'strict') continue;
             if (parsed.uncertainShell || gitCommand.classification === 'uncertain') {
                 return emitDecision(
@@ -331,9 +351,9 @@ function hookPreToolUse(input) {
         }
     }
     let eng;
-    // diagnosticWarning is about the rule pack and drives the messages below;
+    // diagnosticWarning is about the rule pack and can stop a strict command;
     // hygieneWarning is housekeeping that never touches the decision. Kept apart
-    // so the "invalid local pack skipped" wording stays true.
+    // because only one of the two is ever grounds to deny.
     let diagnosticWarning = '';
     let hygieneWarning = '';
     try {
@@ -354,7 +374,9 @@ function hookPreToolUse(input) {
             : `aimhooman could not load policy rules: ${e.message}`;
         if (e?.name === 'LocalOverridesError') return emitDecision('deny', reason);
         if (profile === 'strict') return emitDecision('deny', reason);
-        return emitDecision('allow', `${reason}; continuing because profile=${profile}`);
+        // Rules that will not load are the least basis there is for granting an
+        // allow, and clean/compliance do not deny on them. Say nothing instead.
+        return 0;
     }
     // Refreshing the excludes is gitignore hygiene, not part of the verdict:
     // pre-commit never writes them and still answers. Kept out of the block
@@ -381,16 +403,39 @@ function hookPreToolUse(input) {
     // also a potential pre-commit bypass. Strict rejects it above; clean and
     // compliance still need the staged-content backstop so a hook mutation
     // cannot expose a secret that was already in the index.
-    const prefixBypass = parsed.commands.some((candidate) => (
+    const commitPrefixRisk = parsed.commands.some((candidate) => (
         (candidate.verb === 'commit' || candidate.verb === 'unknown')
         && candidate.prefixRisk
-    )) || (parsed.opaqueCommitHiding && parsed.commands.length === 0 && parsed.prefixRisk);
+    ));
+    // Nothing here was modelled, yet the shape can still hide a commit — a pipe
+    // into a shell, a fed script. There is no argv to read a --no-verify out of,
+    // which is the reason to refuse rather than a reason to let it past.
+    const opaqueCommitRisk = parsed.opaqueCommitHiding
+        && parsed.commands.length === 0
+        && parsed.prefixRisk;
+    const prefixBypass = commitPrefixRisk || opaqueCommitRisk;
     const aliasBypass = parsed.commands.some((candidate) => (
         (candidate.verb === 'commit' || candidate.verb === 'unknown')
         && candidate.inlineAliasRisk
     ));
     const hiddenBypass = noVerify || bypassHooks || parsed.uncertainShell
         || prefixBypass || aliasBypass;
+    // Being unmodelled is not the same as being a bypass. Once a commit has been
+    // read out of the command, a prefix earns the refusal below only when it can
+    // take the guard away: it names the hooks, or the commit already bypasses
+    // them. A build, a test run, ls — those leave pre-commit to answer, and
+    // refusing them taught agents to drop the `&&` gate rather than to run the
+    // command separately. hiddenBypass stays wider on purpose; it is what keeps
+    // the staged-content backstop reading the blobs, so a secret already in the
+    // index still stops the commit here.
+    const prefixHookBypass = opaqueCommitRisk
+        || (commitPrefixRisk && (noVerify || bypassHooks || parsed.prefixHooksRisk));
+    // The same distinction, for the deny paths that ask "will anything scan this
+    // commit". hiddenBypass answers a different question — "should the backstop
+    // read the blobs" — and answering the first with the second refuses
+    // `build && git add . && git commit`, which is how most commits get made.
+    const guardBypass = noVerify || bypassHooks || parsed.uncertainShell
+        || prefixHookBypass || aliasBypass;
     const bypassContext = aliasBypass
         ? 'an inline Git alias cannot be proved to preserve the pre-commit guard'
         : prefixBypass
@@ -457,7 +502,7 @@ function hookPreToolUse(input) {
     const indexReplacement = parsed.commands.some((candidate) => (
         candidate.verb === 'commit' && candidate.indexMutationRisk
     ));
-    if (profile !== 'strict' && commit && hiddenBypass
+    if (profile !== 'strict' && commit && guardBypass
         && parsed.commands.some((c) => c.verb === 'commit' && c.futureIndex)) {
         if (indexReplacement) {
             return emitDecision(
@@ -474,18 +519,17 @@ function hookPreToolUse(input) {
         );
     }
     if (blocks.length === 0) {
-        if (profile !== 'strict' && potentialCommit && prefixBypass) {
+        if (profile !== 'strict' && potentialCommit && prefixHookBypass) {
             return emitDecision(
                 'deny',
                 unmodelledPrefixReason,
             );
         }
-        if (diagnosticWarning) {
-            return emitDecision('allow', `aimhooman warning: ${diagnosticWarning}; invalid local pack skipped`);
-        }
-        if (hygieneWarning) {
-            return emitDecision('allow', `aimhooman warning: ${hygieneWarning}`);
-        }
+        // Nothing found and nothing to object to, so emit nothing and leave the
+        // host's permission rules in charge. An allow auto-approves the call and
+        // skips them, and neither warning is an opinion about this command: one
+        // is about the rule pack, the other about a housekeeping write. Both
+        // still reach the notes on the findings path below.
         return 0;
     }
 
@@ -505,7 +549,7 @@ function hookPreToolUse(input) {
             `aimhooman blocked this: ${bypassContext}, so ${reasonParts(blocks).join('; ')} would be committed. Run the commit separately without the bypass, or unstage it. AI works, hoomans ship.`,
         );
     }
-    if (profile !== 'strict' && potentialCommit && prefixBypass) {
+    if (profile !== 'strict' && potentialCommit && prefixHookBypass) {
         return emitDecision(
             'deny',
             unmodelledPrefixReason,
@@ -641,6 +685,7 @@ export function parseGit(cmd, initialCwd = process.cwd()) {
             classification: 'none',
             environmentRisk: [],
             prefixRisk: false,
+            prefixHooksRisk: false,
             addPaths,
             commands,
         };
@@ -656,6 +701,7 @@ export function parseGit(cmd, initialCwd = process.cwd()) {
     const persistentEnvironmentRisk = new Set();
     let prefixRisk = false;
     let prefixIndexMutationRisk = false;
+    let prefixHooksRisk = false;
     let policyTransitionRisk = false;
     for (const unit of shellUnits(cmd)) {
         const precedingOperator = previousOperator;
@@ -792,6 +838,7 @@ export function parseGit(cmd, initialCwd = process.cwd()) {
         if (toks.length < 2) {
             if (toks.length && !READ_ONLY_SHELL_COMMANDS.has(basename(toks[0]))) {
                 prefixIndexMutationRisk ||= commandMayReplaceIndex(toks, unit.text);
+                prefixHooksRisk ||= commandMayTouchHooks(toks, unit.text);
                 prefixRisk = true;
             }
             continue;
@@ -838,6 +885,7 @@ export function parseGit(cmd, initialCwd = process.cwd()) {
             }
             if (!READ_ONLY_SHELL_COMMANDS.has(basename(g0))) {
                 prefixIndexMutationRisk ||= commandMayReplaceIndex(toks, unit.text);
+                prefixHooksRisk ||= commandMayTouchHooks(toks, unit.text);
                 prefixRisk = true;
                 if (CURRENT_SHELL_MUTATORS.has(shellExecutable(g0)) || definesShellFunction) {
                     shellTargetUncertain = true;
@@ -848,6 +896,7 @@ export function parseGit(cmd, initialCwd = process.cwd()) {
         let i = 1;
         let cwd = unwrapped.cwd;
         let commandBypass = environmentRisk.length > 0;
+        let commandHooksPathOverride = environmentRisk.some(gitConfigEnvName);
         let aliasResolutionRisk = !canResolveGitAlias(g0);
         let inlineAliasRisk = false;
         while (i < toks.length && toks[i].startsWith('-')) {
@@ -867,6 +916,7 @@ export function parseGit(cmd, initialCwd = process.cwd()) {
                 i += 1;
             } else if (option === '-c' && toks[i + 1]) {
                 if (hookAffectingConfig(toks[i + 1])) commandBypass = true;
+                if (hooksPathOverrideConfig(toks[i + 1])) commandHooksPathOverride = true;
                 if (aliasAffectingConfig(toks[i + 1])) {
                     aliasResolutionRisk = true;
                     inlineAliasRisk = true;
@@ -874,6 +924,7 @@ export function parseGit(cmd, initialCwd = process.cwd()) {
                 i += 2;
             } else if (option.startsWith('-c') && option.length > 2) {
                 if (hookAffectingConfig(option.slice(2))) commandBypass = true;
+                if (hooksPathOverrideConfig(option.slice(2))) commandHooksPathOverride = true;
                 if (aliasAffectingConfig(option.slice(2))) {
                     aliasResolutionRisk = true;
                     inlineAliasRisk = true;
@@ -881,6 +932,7 @@ export function parseGit(cmd, initialCwd = process.cwd()) {
                 i += 1;
             } else if (option === '--config-env' && toks[i + 1]) {
                 if (hookAffectingConfig(toks[i + 1])) commandBypass = true;
+                if (hooksPathOverrideConfig(toks[i + 1])) commandHooksPathOverride = true;
                 if (aliasAffectingConfig(toks[i + 1])) {
                     aliasResolutionRisk = true;
                     inlineAliasRisk = true;
@@ -945,6 +997,7 @@ export function parseGit(cmd, initialCwd = process.cwd()) {
                 cwd,
                 noVerify: false,
                 bypassHooks: commandBypass,
+                hooksPathOverride: commandHooksPathOverride,
                 futureIndex: true,
                 classification: 'uncertain',
                 environmentRisk,
@@ -970,6 +1023,7 @@ export function parseGit(cmd, initialCwd = process.cwd()) {
                 cwd,
                 noVerify: commandNoVerify,
                 bypassHooks: commandBypass,
+                hooksPathOverride: commandHooksPathOverride,
                 futureIndex,
                 editorRisk: commitOptions.editorRisk,
                 classification: uncertainShell
@@ -1005,9 +1059,16 @@ export function parseGit(cmd, initialCwd = process.cwd()) {
             });
             sawAdd = true;
         } else if (verb === 'config') {
-            prefixRisk ||= gitConfigMayMutate(toks.slice(i + 1));
+            if (gitConfigMayMutate(toks.slice(i + 1))) {
+                prefixRisk = true;
+                prefixHooksRisk ||= commandMayTouchHooks(toks, unit.text);
+            }
         } else if (verb === 'init') {
+            // init copies the hook templates into the hooks directory, and
+            // --separate-git-dir moves the directory itself, so the hooks read
+            // here are not necessarily the ones the commit runs.
             prefixRisk = true;
+            prefixHooksRisk = true;
         } else if (!SAFE_NON_COMMIT_GIT.has(verb)) {
             commands.push({
                 verb: 'unknown',
@@ -1096,6 +1157,7 @@ export function parseGit(cmd, initialCwd = process.cwd()) {
         classification,
         environmentRisk: unique(commands.flatMap((candidate) => candidate.environmentRisk || [])),
         prefixRisk,
+        prefixHooksRisk,
         addPaths,
         commands,
     };
@@ -1201,6 +1263,22 @@ function commandMayReplaceIndex(tokens, source) {
         || /\bgit\s+rev-parse\b[^;&|\n]*\b--git-path(?:=|\s+)index\b/i.test(text);
 }
 
+// The same shape, asking the other question a prefix raises: it runs in the repo
+// before Git starts, with write access to the hooks. A build or a test suite
+// cannot take pre-commit away; writing into the hooks directory or repointing
+// core.hooksPath can. Literal, like the index check above, so an ordinary
+// command does not read as a bypass merely for being unmodelled.
+// An include never names the hooks; it carries a core.hooksPath of its own and
+// the guard is gone all the same. hooksPathOverrideConfig already counts it for
+// the -c spelling, so leaving it out here would let the two spellings of one
+// bypass disagree.
+function commandMayTouchHooks(tokens, source) {
+    const text = `${tokens.join(' ')} ${source}`.replace(/\\/g, '/');
+    return /(?:^|[\s"'=/])\.git\/hooks(?:$|[\s"'/])/i.test(text)
+        || /\bhookspath\b/i.test(text)
+        || /\binclude(?:if\.[^\s"'=]*)?\.path\b/i.test(text);
+}
+
 const GIT_POLICY_TRANSITION_COMMANDS = new Set([
     'am', 'branch', 'checkout', 'cherry-pick', 'commit', 'merge', 'pull', 'read-tree', 'rebase',
     'replace', 'reset', 'restore', 'revert', 'rm', 'switch', 'symbolic-ref', 'update-index',
@@ -1211,9 +1289,94 @@ const GIT_POLICY_TRANSITION_COMMANDS = new Set([
 // safety boundary is the managed reference-transaction hook, so PreToolUse
 // must not let config/environment/prefix indirection disable that boundary.
 const GIT_REF_MUTATION_COMMANDS = new Set([
-    'am', 'bisect', 'branch', 'checkout', 'cherry-pick', 'fetch', 'merge', 'pull', 'push',
-    'rebase', 'remote', 'replace', 'reset', 'revert', 'stash', 'switch', 'symbolic-ref',
-    'update-ref', 'worktree',
+    'am', 'bisect', 'branch', 'checkout', 'cherry-pick', 'fetch', 'maintenance', 'merge', 'notes',
+    'pull', 'push', 'rebase', 'remote', 'replace', 'reset', 'revert', 'stash', 'switch',
+    'symbolic-ref', 'tag', 'update-ref', 'worktree',
+]);
+
+// gitReadOnlyRefCommand reports whether a ref-mutation verb is used in a
+// read-only listing form that cannot move a ref or mutate state, so the
+// reference-transaction guard has nothing to enforce. branch/remote/stash/notes
+// each have listing subcommands developers pipe every day (`git branch | grep`,
+// `git remote -v | grep`, `git stash list | head`); the mutating forms keep a
+// mutating flag or positional and fall through to the full guard. Conservative:
+// any unknown flag combination is treated as a mutation (fail-closed).
+const GIT_BRANCH_MUTATING_FLAGS = new Set([
+    '-d', '--delete', '-D', '-m', '--move', '-M', '-c', '--copy', '-C',
+    '-u', '--set-upstream-to', '--unset-upstream', '--set-upstream', '-t',
+    '--track', '--unset-track', '-f', '--force',
+]);
+const GIT_REMOTE_MUTATING_SUBCOMMANDS = new Set([
+    'add', 'rename', 'rm', 'remove', 'set-url', 'set-head', 'prune', 'update',
+    'get-url', 'set-urladd',
+]);
+const GIT_STASH_MUTATING_SUBCOMMANDS = new Set([
+    'push', 'pop', 'apply', 'drop', 'clear', 'save', 'create', 'store', 'branch',
+]);
+const GIT_NOTES_MUTATING_SUBCOMMANDS = new Set([
+    'add', 'append', 'copy', 'remove', 'rm', 'edit', 'prune',
+]);
+
+function gitReadOnlyRefCommand(verb, args = []) {
+    const flags = args.filter((arg) => arg.startsWith('-'));
+    const positionals = args.filter((arg) => !arg.startsWith('-'));
+    if (verb === 'branch') {
+        // `git branch`, `git branch -a/-r/-l/--list/-v/--verbose/--all/--remotes`
+        // only list. A name, a start-point, or any create/delete/move/copy flag
+        // is a mutation.
+        if (flags.some((flag) => GIT_BRANCH_MUTATING_FLAGS.has(flag))) return false;
+        const listingOnly = flags.every((flag) => (
+            GIT_BRANCH_READONLY_FLAGS.has(flag)
+        ));
+        if (!listingOnly) return false;
+        // A positional without --list/-l creates or moves a branch.
+        if (positionals.length && !flags.some((flag) => flag === '-l' || flag === '--list')) {
+            return false;
+        }
+        return true;
+    }
+    if (verb === 'remote') {
+        // `git remote` and `git remote -v/--verbose` list; `git remote show <n>`
+        // is read-only; everything else mutates.
+        if (positionals.length === 0) return flags.every((flag) => flag === '-v' || flag === '--verbose');
+        const sub = positionals[0];
+        if (GIT_REMOTE_MUTATING_SUBCOMMANDS.has(sub)) return false;
+        return sub === 'show';
+    }
+    if (verb === 'stash') {
+        // No subcommand defaults to `push` (a mutation). Only list/show are read.
+        const sub = positionals[0] || 'push';
+        if (GIT_STASH_MUTATING_SUBCOMMANDS.has(sub)) return false;
+        return sub === 'list' || sub === 'show';
+    }
+    if (verb === 'notes') {
+        // No subcommand defaults to `list` (read). list/show are read-only.
+        const sub = positionals[0] || 'list';
+        if (GIT_NOTES_MUTATING_SUBCOMMANDS.has(sub)) return false;
+        return sub === 'list' || sub === 'show';
+    }
+    if (verb === 'tag') {
+        // `git tag` and `git tag -l/--list` only list. A name, -d/--delete, -f/--force,
+        // -a/--annotate, -s, -m, or -u creates/moves/deletes a tag.
+        if (flags.some((flag) => GIT_TAG_MUTATING_FLAGS.has(flag))) return false;
+        if (positionals.length && !flags.some((flag) => flag === '-l' || flag === '--list')) {
+            return false;
+        }
+        return true;
+    }
+    return false;
+}
+
+const GIT_TAG_MUTATING_FLAGS = new Set([
+    '-d', '--delete', '-f', '--force', '-a', '--annotate', '-s', '--sign',
+    '-m', '-u', '--local-user', '-v', '--verify', '-n',
+]);
+
+const GIT_BRANCH_READONLY_FLAGS = new Set([
+    '-a', '--all', '-r', '--remotes', '-l', '--list', '-v', '--verbose', '-vv',
+    '-q', '--quiet', '--no-color', '--color',
+    '--sort', '--format', '--contains', '--no-contains', '--merged', '--no-merged',
+    '--points-at',
 ]);
 
 function gitCommandMayBypassRefGuard(verb, args = []) {
@@ -1289,17 +1452,25 @@ function gitConfigMayMutate(args) {
     return positionals.length > 1;
 }
 
+// A verb missing from this list is captured as 'unknown' before the ref-mutation
+// branch below is ever reached, so membership here is what lets a verb be
+// modelled at all. Ref-moving verbs need both lists, never this one alone.
 const SAFE_NON_COMMIT_GIT = new Set([
     'add', 'am', 'annotate', 'apply', 'archive', 'bisect', 'blame', 'branch', 'bundle', 'cat-file',
     'check-attr', 'check-ignore', 'check-mailmap', 'check-ref-format', 'checkout',
-    'cherry-pick', 'clean', 'clone', 'column', 'config', 'count-objects', 'credential', 'describe',
+    'cherry-pick', 'clean', 'clone', 'column', 'commit-graph', 'config', 'count-objects',
+    'credential', 'describe',
     'diff', 'diff-files', 'diff-index', 'diff-tree', 'difftool', 'fetch', 'for-each-ref',
-    'fsck', 'gc', 'grep', 'hash-object', 'help', 'index-pack', 'init', 'interpret-trailers',
-    'log', 'ls-files', 'ls-remote', 'ls-tree', 'merge', 'merge-base', 'mktag', 'mktree', 'mv',
-    'name-rev', 'pack-objects', 'prune', 'pull', 'push', 'range-diff', 'read-tree', 'rebase',
-    'reflog', 'remote', 'repack', 'replace', 'reset', 'restore', 'rev-list', 'rev-parse', 'revert',
+    'format-patch', 'fsck', 'gc', 'grep', 'hash-object', 'help', 'index-pack', 'init',
+    'interpret-trailers',
+    'log', 'ls-files', 'ls-remote', 'ls-tree', 'maintenance', 'merge', 'merge-base', 'merge-tree',
+    'mktag', 'mktree', 'mv',
+    'name-rev', 'notes', 'pack-objects', 'prune', 'pull', 'push', 'range-diff', 'read-tree',
+    'rebase',
+    'reflog', 'remote', 'repack', 'replace', 'rerere', 'reset', 'restore', 'rev-list', 'rev-parse',
+    'revert',
     'rm', 'shortlog', 'show', 'show-branch', 'show-ref', 'sparse-checkout', 'stash', 'status',
-    'submodule', 'switch', 'symbolic-ref', 'tag', 'unpack-objects', 'update-index',
+    'stripspace', 'submodule', 'switch', 'symbolic-ref', 'tag', 'unpack-objects', 'update-index',
     'update-ref', 'verify-commit', 'verify-pack', 'verify-tag', 'version', 'whatchanged',
     'worktree', 'write-tree',
 ]);
@@ -1310,6 +1481,11 @@ function resolveGitAliases(parsed) {
     let aliasPolicyTransitionRisk = false;
     let aliasIndexMutationRisk = false;
     let aliasPrefixRisk = false;
+    // parseGit derives prefixHooksRisk from the literal command text, and an
+    // alias hides its expansion from that text entirely. Without this the alias
+    // channel raises prefixRisk but never the hooks half, so a hooks-removing
+    // prefix reached through an alias reads as an ordinary build step.
+    let aliasHooksRisk = false;
     for (const candidate of parsed.commands) {
         let resolved = candidate;
         if (candidate.verb === 'unknown') {
@@ -1344,6 +1520,8 @@ function resolveGitAliases(parsed) {
             || effective.indexMutationRisk
             || gitIndexMutationRisk(effective.verb, effective.args);
         aliasPrefixRisk ||= effective.verb === 'unknown' || effective.prefixMutationRisk;
+        aliasHooksRisk ||= Boolean(effective.prefixMutationRisk)
+            && commandMayTouchHooks(effective.args || [], effective.aliasExpansion || '');
     }
     const commitCommands = commands.filter((candidate) => (
         candidate.verb === 'commit' || candidate.verb === 'unknown'
@@ -1357,6 +1535,7 @@ function resolveGitAliases(parsed) {
         commit: commitCommands.length > 0,
         noVerify,
         bypassHooks,
+        prefixHooksRisk: Boolean(parsed.prefixHooksRisk || aliasHooksRisk),
         addPaths: [...parsed.addPaths, ...aliasAddPaths],
         commands,
         environmentRisk: unique(commitCommands.flatMap((candidate) => candidate.environmentRisk || [])),
@@ -1490,6 +1669,15 @@ function hookAffectingConfig(value) {
     return /^(?:core\.(?:editor|hookspath)|sequence\.editor|include\.path|includeif\..+\.path|remote\..+\.receivepack)$/i.test(key);
 }
 
+// A narrower question than hookAffectingConfig: not "can this change how a hook
+// behaves" but "does this take the managed hooks away". core.editor and
+// sequence.editor leave pre-commit, commit-msg and reference-transaction
+// running; these do not.
+function hooksPathOverrideConfig(value) {
+    const key = String(value).split('=', 1)[0];
+    return /^(?:core\.hookspath|include\.path|includeif\..+\.path)$/i.test(key);
+}
+
 function aliasAffectingConfig(value) {
     const key = String(value).split('=', 1)[0];
     return /^alias\./i.test(key);
@@ -1781,8 +1969,12 @@ function shellUnits(s) {
 // never write files, and cannot bypass Git hooks. Anything not listed is treated
 // as potentially able to hide or feed a commit (fail-closed). Deliberately
 // excluded: shells and interpreters, awk/sed/ed/vim, sqlite3/psql/dc/bc/octave
-// and other stdin-as-program readers, git, tee (writes files), env/xargs/find
-// (run sub-commands), and curl/wget (fetch arbitrary content to a pipe).
+// and other stdin-as-program readers, tee (writes files), env/xargs/find
+// (run sub-commands), and curl/wget (fetch arbitrary content to a pipe). Git is
+// handled separately: a read-only Git subcommand is an allowed pipe SOURCE (see
+// GIT_READONLY_PIPE_SUBCOMMANDS), but Git is never a safe pipe SINK, because a
+// mutating subcommand (apply, am, hash-object --stdin, fast-import) reads its
+// program or patch from stdin.
 const SAFE_PIPE_EXECUTABLES = new Set([
     'cat', 'tac', 'head', 'tail', 'tr', 'cut', 'paste', 'fold', 'fmt', 'expand',
     'unexpand', 'rev', 'nl', 'pr', 'column', 'sort', 'uniq', 'comm', 'tsort',
@@ -1795,6 +1987,100 @@ const SAFE_PIPE_EXECUTABLES = new Set([
     'gh', '[',
 ]);
 
+// SAFE_BUILD_PIPE_EXECUTABLES are build, test, lint and language-toolchain
+// commands permitted as a benign pipe SOURCE. They take data/flag arguments,
+// report to stdout/stderr, and cannot bypass Git hooks or hide a `git commit`
+// invocation from the parser — `npm test | tail`, `cargo build 2>&1 | grep`,
+// `jest | head`, `eslint . | head` are how a developer runs a project every
+// day. A package script could in principle shell out to git, but that is a
+// prefix/indirection risk handled by the same guard that covers `a && b`, not a
+// pipe that feeds code into a sink, so it does not make the pipeline opaque.
+// Deliberately excluded: shells and interpreters reachable with a program on
+// stdin (sh, bash, zsh, python -c, node -e, perl), and anything that runs an
+// arbitrary sub-command (xargs, find -exec, env, make with a generated recipe
+// is kept because its recipe is repository content, not pipe input).
+const SAFE_BUILD_PIPE_EXECUTABLES = new Set([
+    // package managers & task runners
+    'npm', 'npx', 'yarn', 'pnpm', 'pnpx', 'bun', 'bunx', 'deno', 'cargo',
+    'rustc', 'go', 'make', 'cmake', 'ninja', 'bazel', 'buck', 'pants', 'mill',
+    'sbt', 'mvn', 'mvnw', 'gradle', 'gradlew', 'rake', 'bundle', 'gem', 'rake',
+    'pip', 'pip3', 'pipx', 'poetry', 'pdm', 'uv', 'rye', 'conda', 'mamba',
+    // test runners / formatters / linters / type-checkers
+    'jest', 'vitest', 'mocha', 'karma', 'ava', 'tape', 'tap', 'pytest',
+    'py.test', 'tox', 'nox', 'go-test', 'rspec', 'minitest', 'test', 'ctest',
+    'xcodebuild', 'swift', 'swiftc', 'dotnet', 'msbuild', 'tsc', 'tsdx',
+    'eslint', 'biome', 'biome-check', 'standard', 'ts-standard', 'prettier',
+    'stylelint', 'ruff', 'flake8', 'pylint', 'mypy', 'black', 'isort', 'rubocop',
+    'golangci-lint', 'staticcheck', 'revive', 'clippy', 'shellcheck',
+    'hadolint', 'actionlint', 'markdownlint', 'remark', 'knip',
+    // language runtimes used as direct tools
+    'node', 'python', 'python3', 'ruby', 'php', 'java', 'javac', 'dotnet',
+]);
+
+// GIT_READONLY_PIPE_SUBCOMMANDS are Git subcommands safe as the SOURCE of a
+// benign pipeline: they only report (stdout), do not move refs or mutate the
+// index/worktree, do not read a program or patch from stdin, and cannot bypass
+// hooks. `git log | head`, `git status | grep`, `git diff | cat` are how a
+// developer reads a repository every day, and treating them as opaque commit
+// hiding blocked the normal workflow. Anything that can write, move a ref, or
+// consume stdin as input (add, commit, apply, am, hash-object, reset, checkout,
+// push, fetch, merge, rebase, cherry-pick, read-tree, update-index, update-ref,
+// clean, init, clone, bundle, archive, ...) is excluded and stays fail-closed.
+// Dual-mode subcommands (branch, tag, remote, config, stash, notes) are kept:
+// piped use is almost always the read form, their listing forms cannot hide or
+// feed a commit, and a real ref/index mutation is still caught by the managed
+// reference-transaction and pre-commit hooks at commit time.
+const GIT_READONLY_PIPE_SUBCOMMANDS = new Set([
+    'annotate', 'blame', 'branch', 'cat-file', 'check-attr', 'check-ignore',
+    'check-mailmap', 'check-ref-format', 'cherry', 'config', 'count-objects',
+    'describe', 'diff', 'diff-files', 'diff-index', 'diff-tree', 'for-each-ref',
+    'fsck', 'grep', 'help', 'log', 'ls-files', 'ls-remote', 'ls-tree', 'merge-base',
+    'name-rev', 'notes', 'reflog', 'remote', 'rev-list', 'rev-parse', 'shortlog',
+    'show', 'show-branch', 'show-ref', 'stash', 'status', 'var',
+    'verify-commit', 'verify-pack', 'verify-tag', 'version', 'whatchanged',
+]);
+
+// gitPipeSourceSubcommand returns the Git subcommand of a pipe segment that is a
+// read-only Git source (e.g. `git -C repo log --oneline`), or null when the
+// segment is not a Git command or the subcommand is not read-only. It reuses the
+// same global-option skipping the verb parser does, so `-C path`, `-c k=v`,
+// `--git-dir`, `--work-tree`, `--namespace` and `--no-pager`/`-p` style flags do
+// not hide a mutating subcommand.
+function gitPipeSourceSubcommand(segment) {
+    const words = shellWords(segment.trim());
+    let i = 0;
+    while (i < words.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(words[i])) i += 1;
+    if (i >= words.length || !isGitExecutable(words[i])) return null;
+    i += 1;
+    while (i < words.length && words[i].startsWith('-') && words[i] !== '--') {
+        const option = words[i];
+        // Global options that take the next token as their value.
+        if (['-C', '-c', '--config-env', '--git-dir', '--work-tree', '--namespace',
+            '--upload-pack', '--receive-pack'].includes(option) && words[i + 1]) {
+            i += 2;
+        } else if (
+            option.startsWith('-C')
+            || option.startsWith('-c')
+            || option.startsWith('--config-env=')
+            || option.startsWith('--git-dir=')
+            || option.startsWith('--work-tree=')
+            || option.startsWith('--namespace=')
+            || option.startsWith('--upload-pack=')
+            || option.startsWith('--receive-pack=')
+        ) {
+            i += 1;
+        } else {
+            // Flags that take no value (--no-pager, -p, --no-replace-objects,
+            // --literal-pathspecs, --bare, --exec-path, ...). `--` ends options.
+            i += 1;
+        }
+    }
+    if (i < words.length && words[i] === '--') i += 1;
+    const subcommand = words[i];
+    if (!subcommand) return null;
+    return GIT_READONLY_PIPE_SUBCOMMANDS.has(subcommand) ? subcommand : null;
+}
+
 // containsOpaquePipeLexeme is a quote-aware scan for shell constructs that can
 // hide or feed a commit or subcommand: command substitution, subshells, brace
 // expansion/groups, script-feed redirects, and command separators. Output
@@ -1857,22 +2143,85 @@ function pipelineSegmentExecutable(segment) {
     return null;
 }
 
-// benignReadOnlyPipeline reports whether a command is a bare pipeline whose
-// every segment is a known non-code-executing, non-mutating command with no
-// opaque shell syntax. Such a pipe cannot hide or feed a commit, so it is not a
-// "potential commit" for the unmodelled-prefix guard. Fail-closed: any opaque
-// lexeme, unlisted executable, missing executable, or non-pipe returns false.
-function benignReadOnlyPipeline(command) {
-    if (!command.includes('|')) return false;
-    if (containsOpaquePipeLexeme(command)) return false;
-    const segments = splitPipeSegments(command);
-    if (segments.length < 2) return false;
-    return segments.every((segment) => {
+// splitLogicalUnits splits a command line on unquoted command separators that
+// do not move data into a pipe sink: &&, ||, and ;. A pipeline between two
+// separators stays one unit (its internal | is handled by splitPipeSegments).
+function splitLogicalUnits(command) {
+    const units = [];
+    let unit = '';
+    let quote = '';
+    let escaped = false;
+    for (let i = 0; i < command.length; i += 1) {
+        const char = command[i];
+        const next = command[i + 1];
+        if (escaped) { unit += char; escaped = false; continue; }
+        if (char === '\\' && quote !== "'") { unit += char; escaped = true; continue; }
+        if (quote) { unit += char; if (char === quote) quote = ''; continue; }
+        if (char === "'" || char === '"') { unit += char; quote = char; continue; }
+        if ((char === '&' && next === '&') || (char === '|' && next === '|')) {
+            units.push(unit); unit = ''; i += 1; continue;
+        }
+        if (char === ';') { units.push(unit); unit = ''; continue; }
+        unit += char;
+    }
+    units.push(unit);
+    return units;
+}
+
+// benignReadOnlyUnit reports whether a single shell unit (no &&/||/;) is a
+// read-only pipeline or a single read-only command. It is the same fail-closed
+// contract as benignReadOnlyPipeline, applied to one piece of a compound line:
+// the unit cannot hide or feed a commit when every pipe segment is a known safe
+// filter, a read-only Git source, or a build/test toolchain command as source.
+function benignReadOnlyUnit(unit) {
+    const text = unit.trim();
+    if (!text) return true; // an empty piece (e.g. trailing ;) is harmless
+    if (containsOpaquePipeLexeme(text)) return false;
+    const segments = splitPipeSegments(text);
+    if (segments.length < 2) {
+        // A single command (no pipe). Benign when it is a known safe command, a
+        // build/test toolchain command, a read-only Git command, or a directory
+        // change.
+        const words = shellWords(text);
+        while (words.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(words[0])) words.shift();
+        if (!words.length) return true;
+        const executable = shellExecutable(words[0]);
+        if (SAFE_PIPE_EXECUTABLES.has(executable)) return true;
+        if (SAFE_BUILD_PIPE_EXECUTABLES.has(executable)) return true;
+        if (executable === 'cd' || executable === 'pushd' || executable === 'popd') return true;
+        return gitPipeSourceSubcommand(text) !== null;
+    }
+    return segments.every((segment, index) => {
         const executable = pipelineSegmentExecutable(segment);
-        return executable !== null && SAFE_PIPE_EXECUTABLES.has(executable);
+        if (executable !== null && SAFE_PIPE_EXECUTABLES.has(executable)) return true;
+        if (index === 0) {
+            // Source-only segments: a read-only Git command, or a build/test
+            // toolchain command. Build tools and interpreters must never be a
+            // later (sink) segment, where stdin could feed a program or patch.
+            if (executable !== null && SAFE_BUILD_PIPE_EXECUTABLES.has(executable)) return true;
+            if (gitPipeSourceSubcommand(segment) !== null) return true;
+        }
+        return false;
     });
 }
 
+// benignReadOnlyPipeline reports whether a command line is composed entirely of
+// read-only units (joined by &&, ||, or ;) where every piece is a known
+// non-code-executing, non-mutating command or a read-only Git source, with no
+// opaque shell syntax. Such a line cannot hide or feed a commit, so it is not a
+// "potential commit" for the unmodelled-prefix guard. This is how a developer
+// reads a repository every day: `cd repo && git log | head`, `git status | grep`,
+// `git diff | cat`. Fail-closed: any opaque lexeme, unlisted executable, missing
+// executable, mutating Git subcommand, or a non-read-only command returns false.
+// A read-only Git command may appear only as the source (first segment) of a
+// pipeline, never as a later sink where stdin could drive a mutation.
+function benignReadOnlyPipeline(command) {
+    if (!command.includes('|') && !/[;&]/.test(command)) return false;
+    if (containsOpaquePipeLexeme(command)) return false;
+    const units = splitLogicalUnits(command);
+    return units.every(benignReadOnlyUnit);
+}
+
 function pipedShellCommitInvocations(source, initialCwd) {
     const units = shellUnits(source);
     const commits = [];
@@ -2175,7 +2524,7 @@ function unwrapCommand(input, initialCwd) {
         while (isAssignment(toks[0])) assignments.push(toks.shift());
     };
     const stripPrecommands = () => {
-        for (;;) {
+        for (; ;) {
             if (toks[0] === '-' || toks[0] === 'nocorrect' || toks[0] === 'noglob') {
                 toks.shift();
             } else if (toks[0] === 'coproc') {
@@ -2566,16 +2915,22 @@ function updatePersistentEnvironment(words, risks) {
     return false;
 }
 
+// An assignment that can inject arbitrary Git config can set core.hooksPath, so
+// it can remove every managed hook. Named at the key level so both the
+// assignment list and the already-computed risk names can ask the same question.
+function gitConfigEnvName(key) {
+    if (key === 'GIT_CONFIG_PARAMETERS' || key === 'GIT_CONFIG_COUNT') return true;
+    if (/^GIT_CONFIG_(?:KEY|VALUE)_\d+$/.test(key)) return true;
+    if ([
+        'GIT_CONFIG', 'GIT_CONFIG_GLOBAL', 'GIT_CONFIG_SYSTEM', 'GIT_CONFIG_NOSYSTEM',
+    ].includes(key)) return true;
+    return ['HOME', 'XDG_CONFIG_HOME'].includes(key);
+}
+
 function gitConfigAssignmentsBypass(assignments) {
     return assignments.some((assignment) => {
         const separator = assignment.indexOf('=');
-        const key = assignment.slice(0, separator).toUpperCase();
-        if (key === 'GIT_CONFIG_PARAMETERS' || key === 'GIT_CONFIG_COUNT') return true;
-        if (/^GIT_CONFIG_(?:KEY|VALUE)_\d+$/.test(key)) return true;
-        if ([
-            'GIT_CONFIG', 'GIT_CONFIG_GLOBAL', 'GIT_CONFIG_SYSTEM', 'GIT_CONFIG_NOSYSTEM',
-        ].includes(key)) return true;
-        return ['HOME', 'XDG_CONFIG_HOME'].includes(key);
+        return gitConfigEnvName(assignment.slice(0, separator).toUpperCase());
     });
 }