Skip to content

Make git_ops_guard classify Git by outcome and effective target (#4751) - #5341

Merged
Trecek merged 46 commits into
developfrom
impl-rectify_git_outcome_target_immunity-20261105-115626
Nov 6, 2026
Merged

Trecek merged 46 commits into
developfrom
impl-rectify_git_outcome_target_immunity-20261105-115626

Conversation

@Trecek

@Trecek Trecek commented Nov 6, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

Addresses #4751. In an interactive autoskillit cook session anchored at the primary checkout, git checkout -b pr-issue-4726-step2 <sha> passed git_ops_guard and moved the primary off develop.

Two structural habits of the guard made that whole family of bugs possible, and this PR removes both:

  1. It classified Git commands by marker tokens, not by what the command does. Bundled, stuck, =-joined, abbreviated and reordered spellings of Git options, and misread wrappers or interpreters (bash -lc '…', sudo -n git …), slipped past the exact-token checks.
  2. It guessed which repository a segment acts on. A failed guess became "another repository" or "no repository", and both meant allow (GIT_DIR=…, --git-dir, env -C, nested cd, a cd that is failed/conditional/piped/backgrounded, a cwd inside .git or a bare repository, aliases, git $P …).

Interactive cook also had no rule protecting its primary checkout's HEAD, and its shared-ref preflight depended on a project-wide kitchen marker.

Everything stays inside the existing git_ops_guard and its hook runtime. No new hook, registry or state machine.

Changes

Phase Commit What
A 513c92d21 One Git parse-options engine over per-subcommand option tables maps argv to what Git will do (which ref is rewritten, whether HEAD moves, whether paths are restored, or ambiguous). Fetch moves onto the same engine. Unexpected exceptions in main() now fail closed.
B 46ce6af2a The write scanner's scoped shell walk becomes the single cwd authority. analyze_git_segment returns invocation, target (resolved / not a repository / unresolved) and outcome, and never resolves to a guessed repository. Tokenizer no longer drops the operator on a newline or swallows a command after a trailing comment. Codex workdir is honoured.
C 5bc50b7f2 In cook, a segment whose outcome moves HEAD (or is ambiguous) is denied when its target is the anchor repository's main worktree or is unresolved. Every launched interactive session runs the shared-ref preflight without the marker, and AUTOSKILLIT_STATE_ROOT is set on every interactive launch.
D a5dd9408c The headless destructive-operation blocklist matches outcome predicates over the same engine and analysis, instead of tokens.
— 6434f5441 Keeps revision spellings out of the whole-tree checkout pathspecs.
E 05531c9fd Per-wrapper arity tables and a bundle-aware shell/Python -c extractor replace the shared wrapper sets. Anything not modelled is reported unresolved out of band and fails closed only when it mentions a Git mutation.
F b84b5019d Arch test that fails when Git-classification code tests raw option tokens again.
— 5d42e3198 _WrapperSpec is a frozen dataclass, per the *Spec naming rule.

Tests added or updated: option-grammar and option-table units, a live completeness contract (version-gated, against git <sub> --git-completion-helper-all), a real-Git Hypothesis differential that proves the outcome mapping sound, walk/target/payload units, and guard matrices for spelling, effective-target and cook primary-HEAD cases across session shapes.

Audit remediation

An implementation audit against the plan returned NO GO with seven blocking findings. Each is addressed below, and every departure from the plan or the audit is listed with its reason.

Fixed

Finding Fix
Bash workdir hid a malformed session cwd from github_mutation_guard RELATIVE_CWD / NON_STRING_CWD are reported next to the workdir result; RELATIVE_WORKDIR alone still does not trip the deny. Rows added at the parser and at the guard.
_unwrapped_prefix kept its own wrapper list The blockers come from the _WRAPPER_SPECS keys plus env; see the first deviation below.
printf x | tee "$TARGET" allowed verdict was unpinned Added as its own allowed test beside the ref-storage row that stays denied.
Git-spawning tests missed the hygiene rules Guard test modules skip without git and isolate Git config; the option-table contract builds its repository with the shared topology helper; git --version context lives in the shared harness and is on every attribution assertion.
Residual-risk list omitted two entries core.fsmonitor and core.sshCommand added to hooks/guards/AGENTS.md.
Two module docstrings omitted public members _GIT_TABLES_REFERENCE_VERSION, risky_git_operation and _RISKY_PREDICATES named.
Notes Stale spec-location pointer corrected; env-contract justification regains the plan's wording; issue reference dropped from the contains_blocked_git_op docstring.

Departures, with justification

  • Whole-tree checkout pathspecs (kept the wider predicate). The plan names five spellings. Git 2.43.0 also restores the whole tree for *, d/.., :(top)* and :/* (checked in a scratch repo: root, nested and dotfile changes all reverted). Narrowing would let a headless skill run git checkout -- '*' and discard all uncommitted work, which is a spelling of the operation RISKY_GIT_OPERATIONS already names, so it stays inside the Phase D sign-off. Pinned in the outcome matrix and added to the real-Git dirty-state differential. Easy to narrow if you want the plan's set.
  • time and command are not blockers. Taking every _WRAPPER_SPECS key literally would leave the walk's directory behind the shell's after time cd d, since bash runs a builtin behind time and command in the current shell. It would also change the write scan's verb_cwd, against the byte-identical requirement. Every other key is a blocker, and a test iterates the whole table.
  • No HOME/XDG redirect. GIT_CONFIG_GLOBAL replaces both ~/.gitconfig and $XDG_CONFIG_HOME/git/config, so the plan's isolated_git_config fixture is sufficient (verified).
  • git --version not retrofitted onto every older assertion in test_git_ops_guard.py; the matrix classes this PR adds carry it.
  • Plan defects, code unchanged: git push --repo=r main pushes to main (the positional wins; verified); fetch --unshallow / --refetch / --refmap are not negatable in Git 2.43.0; _resolve_git_common_dir stays because _same_repository calls it; _classify_git_segment stays removed; per-phase red logs do not exist.
  • _WrapperSpec is a frozen dataclass per the repository's *Spec rule.

Probe re-runs against this branch. The incident reproduction ends guard=DENY with HEAD unchanged; cook denies HEAD moves in the primary while order and headless keep their verdicts; the spelling, redirection and relative-cwd probes are all DENY. In a wider sweep of the flag probes, every row where Git changed state and the headless guard allowed it involved an operation RISKY_GIT_OPERATIONS does not name (path restores, restore, stash, rm, branch -D, push --delete), with three exceptions: pushes whose + refspec comes only from Git config (remote.origin.push=+... set through -c, git config or GIT_CONFIG_COUNT). The plan covers config channels only for clean, so this is an existing gap rather than a regression, and it is not addressed here.

Test plan

  • pre-commit run --all-files passes
  • task test-local-gate (full run): 55006 passed, 614 skipped, 26 xfailed

🤖 Generated with Claude Code

Trecek and others added 30 commits November 5, 2026 13:30
Phase A of the git outcome and effective-target immunity work (#4751).

A parse-options engine over per-subcommand option tables now maps branch,
checkout, switch, symbolic-ref, update-ref, reset, push and fetch argv to
what Git will do: which branch ref is rewritten and whether HEAD moves.
Bundled, stuck, abbreviated, negated and reordered spellings are read the
way Git reads them, and unknown or ambiguous options classify as ambiguous
instead of falling through to allow.

git_ops_guard now fails closed on any unexpected exception while
classifying a command.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Phase B of the git outcome and effective-target immunity work (#4751).

The write scanner's shell walk becomes the single cwd authority
(_shell_segment_walk). Beyond the shell's logical directory it records
whether a cd certainly ran, so a failed, dynamic, conditional, piped,
backgrounded, function-body or compound-body cd leaves the cwd uncertain
instead of being guessed. The tokenizer now keeps the operator that joined
each segment, keeps it across newlines, and no longer lets a trailing
comment swallow the command boundary.

analyze_git_segment (_git_target) returns one analysis per segment: the
invocation, the target (resolved, not a repository, or unresolved) and the
outcome. It expands aliases, covers git-core executables and dynamic command
words, and treats layout overrides and unparseable global options as
unresolved rather than as another repository. git_ops_guard drops its own
cwd tracking, judges every raw write target against its own repository, and
skips commands that mention neither Git nor ref storage.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Phase C of the git outcome and effective-target immunity work (#4751).

An interactive cook session anchored at the primary checkout could move that
checkout off its branch with git checkout -b <name> <sha>, because nothing
protected the primary's HEAD and the shared-ref preflight only ran while the
kitchen marker existed. git_ops_guard now denies a cook-session Git segment
whose outcome moves HEAD, or is ambiguous, when its target is the anchor
repository's main worktree or cannot be resolved. Path-only forms and linked
worktrees are unaffected.

Every autoskillit-launched interactive session (cook, order, managed fleet)
now runs the shared-ref preflight without depending on the project-wide
marker, and every interactive launch carries AUTOSKILLIT_STATE_ROOT so hook
state resolves from the project root. The make-groups skill creates its
feature branch with git branch so it no longer switches the checkout.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Phase D of the git outcome and effective-target immunity work (#4751).

The headless blocklist matched RISKY_GIT_OPERATIONS by option token, so
push -fu, +refspec, --force-w, reset --har, clean -df/-xdf/--forc,
commit --amen, checkout -f, clean.requireForce=false and aliases all
bypassed it, while commit -m '--amend' was blocked in error. The names in
RISKY_GIT_OPERATIONS are unchanged; matching moves onto outcome predicates
over the same option engine and the same per-segment analysis, keyed
exactly by that registry. Option values are never read as flags, any
non-dry-run clean is risky (which covers every config channel), push
--mirror counts as a force, and whole-tree checkout pathspecs are matched
after normalization. Among several matching operations the choice is
deterministic.

contains_blocked_git_op moves next to its dependencies in _git_target and
reads commands through the evaluated-segment walk with the shared cwd and
analysis cache.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
The whole-tree pathspec normalization stripped the top-of-tree magic from
:/. as well, so checkout :/. (a revision named by message that detaches
HEAD) was treated as a destructive whole-tree restore. The :/ magic now
counts only before nothing or a wildcard.

Also declares the cook launch tests' dependency on the hooks package in the
file-level test cascade map.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Phase E of the git outcome and effective-target immunity work (#4751).
The source for this phase landed in the preceding commit; this commit adds
its tests and documentation.

Shell and Python -c programs are found through their bundled, stuck and
value-taking options (bash -lc, python3 -Bc, -W error -c), and a wrapper's
command word through its own option table (timeout -k 5 10, sudo -n,
stdbuf -o L, nice -n 5, time -p, exec -a n, env --ignore-signal). Anything
the tables do not model, and opaque launchers such as xargs, find -exec,
uv run, setsid and node -e, make the command position unresolved. That
signal travels out of band on the walked segment, so the other guards keep
their verb, while git_ops_guard denies an unresolved position only when the
command also mentions a Git mutation.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Phase F of the git outcome and effective-target immunity work (#4751).

A membership test, index lookup or prefix test against one literal option
spelling silently allows every other spelling Git accepts. An arch test now
fails when git_ops_guard or the Git classification modules compare against,
index, count or prefix-test an option-looking string literal; option
semantics are decided through the _option_grammar tables instead. The bare
-, -- and + and dict-literal dispatch keys are exempt.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
The *Spec convention requires a dataclass or TypedDict; _WrapperSpec was a
NamedTuple, which tests/arch/test_def_spec_naming.py rejects.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…from the wrapper table

A Bash payload carrying a per-call workdir no longer hides a malformed
session cwd: RELATIVE_CWD and NON_STRING_CWD are still reported next to the
workdir result, so github_mutation_guard's malformed-cwd deny keeps firing
for that combination while RELATIVE_WORKDIR alone still does not trip it.

The walk's list of wrappers that keep a cd builtin from running in the
current shell is now the _WRAPPER_SPECS keys plus env, instead of a second
literal set. time and command stay out of it: bash runs a builtin behind
them in the current shell, so treating them as blockers would leave the
tracked directory behind the real one.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…e pathspecs

Guard test modules skip without git and isolate Git config; the shared
harness owns the git --version assertion context that two modules had
copied, and every verdict assertion in the attribution matrix carries it.
The option-table contract builds its repository with the shared topology
helper. printf x | tee "$TARGET" is pinned as allowed.

Whole-tree checkout spellings that Git itself treats as a full restore
(*, d/.., :(top)*) are pinned in the outcome matrix and in the real-Git
dirty-state differential.

Docstrings name _GIT_TABLES_REFERENCE_VERSION, risky_git_operation and
_RISKY_PREDICATES; the residual-risk list names core.fsmonitor and
core.sshCommand; the env-contract justification regains its wording.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Inline the regex-gated python_c_program call in evaluated_payloads and remove
the wrapper, its re-export bindings and the now-unused imports so the
_invocation_flags leaf is the only Python -c extractor.

Addresses review findings bce825d26d, a37c97583f, d86a35a2e0, aa978f2103

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Addresses review finding 8e0b527df8

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…ec extraction

Addresses review finding 8aebc8e3a2

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…izer

Addresses review finding 11d86f5404

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Addresses review finding 413584c1f0

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…uiltin

Addresses review finding c26d24f0e7

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Addresses review finding 922135c298

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Delete the parallel _command_start_index walk; extract_git_subcommand_and_flags
and the wc protected-path arm now use _verb_start_index, so the prefix rules
cover leading shell keywords too. Behaviour change (intended, strictly
tighter): keyword-led segments such as `if true; then sudo wc -l <protected>; fi`
and a bare keyword-led `wc -l <protected>` are now denied, closing a bypass of
the pinned wc prefix rejection. Git keyword-led segments were already denied.
Adds the keyword x prefix matrices for the wc and git arms and a parity pin
between the git invocation prefix and the verb start index.

Addresses review findings b223fb7253, a520362272

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Decode the repository probe output inside one guard so non-UTF-8 paths and
short output yield UNRESOLVED(git_query_failed) instead of an exception that
denies even read-only Git commands.

Addresses review findings 2092feb24f

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
The layout channel regex matched any "include." token, so filenames such as
include.txt marked every Git segment UNRESOLVED(layout_override). Match the
include.path and includeIf. config keys only.

Addresses review findings 590da0ca4c

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…cstring

List contains_blocked_git_op and the guard-imported helpers in the Members
line, and say why the matcher lives in this module.

Addresses review findings 78f5d21299 cf4a5419a1 610206901b

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Replace the inline ambiguous GitRefOutcome in analyze_git_segment with the
helper _git_outcome already provides, dropping the single-use GitHeadEffect
import.

Addresses review findings d508c2a1e4

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
… cwd

A present non-string workdir silently attributed the command to the session
cwd. Follow the RELATIVE_WORKDIR precedent: record NON_STRING_WORKDIR and
leave the execution cwd unknown so ref-mutating Git commands fail closed.

Addresses review findings 16652de20e

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…he sed table

Addresses review findings 72491a2f11

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…tch parsers

PushArgs and FetchArgs were field-for-field identical and unused outside
_git_outcome; collapse them into RemoteArgs.

Addresses review findings 709440d12d

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Only a dry run is non-destructive: Git reads the clean menu from stdin, so a
piped or scripted answer deletes untracked files with no human involved. Move
the pinned interactive rows to the risky side, pin the piped forms through the
guard, and let the differential feed the menu answer so it can see the effect.

Addresses review findings 0852e4c2d7

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…e Git

Add a version-gated whole-set equality test of _GIT_BUILTIN_SUBCOMMANDS
against git --list-cmds=builtins, skipping when the installed Git differs
from the reference version like the sibling option-table tests, and name
the pin in the constant's comment.

Addresses review findings d8e3b783c5

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Finding ids: e182a71837

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Finding ids: 7804712b96, db5f2acb68

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…e_interactive_launch

Finding ids: 877287bcda

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Trecek and others added 16 commits November 6, 2026 11:25
…n hooks docs

Finding ids: 2a35a11458, 1de02cee24

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
… feature-branch step

Finding ids: a406b39b7b

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…opology

Findings: 9435d0b167, 2ff9449345

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Findings: 2f1a68e9aa, 9832c39dad

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Findings: e11cf197a5, ef9e87e8ba

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…pt to name HEAD

Finding: ee70109347

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…py naming

Finding: c2464b834d

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…gh tests/_git_topology

Findings: 8277e30dc7, 434126cafd

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
… scrub

Finding: 359caa872e

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Finding: d895f6d4d7

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…k test module

Finding: 72741edbe5

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Finding: 2cadf7c6a8

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…rity constant

Finding: 545f6b6036

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…ome isolation fixture

Finding: 6067ce793c

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…ration table

Finding: afe3096825

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…git_ops_guard harness

Findings: 163bdb8c1d, 17329eb339, a42fc88dee, 5f3c20b9c6

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@Trecek
Trecek enabled auto-merge November 6, 2026 20:39
@Trecek
Trecek added this pull request to the merge queue Nov 6, 2026
Merged via the queue into develop with commit 476ec4c Nov 6, 2026
11 checks passed
@Trecek
Trecek deleted the impl-rectify_git_outcome_target_immunity-20261105-115626 branch November 6, 2026 21:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant