Skip to content

armelhbobdad/bmad-module-ultracode-goal / skills/ultracode-goal

ultracode-goal

Flagged

Runs a BMAD Epic autonomously to a machine-checked Definition-of-Done. Use when the user requests to 'run an epic autonomously', 'execute this epic', 'ultracode goal', or 'autonomously deliver the epic'.

FileKindSize
SKILL.mdskill md15.9 KB
assets/module-help.csvother2.1 KB
assets/module-setup.mdmarkdown5.9 KB
assets/module.yamlconfig1.9 KB
assets/ucg-awareness/bmad-architecture.tomlconfig2.5 KB
assets/ucg-awareness/bmad-create-epics-and-stories.tomlconfig3.3 KB
assets/ucg-awareness/bmad-prd.tomlconfig2.1 KB
assets/ucg-awareness/bmad-testarch-nfr.tomlconfig1.8 KB
assets/ucg-awareness/bmad-testarch-test-design.tomlconfig3.1 KB
assets/ucg-awareness/shaping-decision.mdmarkdown6.8 KB
assets/ucg-awareness/ucg-create-story.tomlconfig3.3 KB
customize.tomlconfig9.8 KB
references/define-done.mdmarkdown15.4 KB
references/execute.mdmarkdown116.7 KB
references/finalize.mdmarkdown39.2 KB
references/gate.mdmarkdown134.5 KB
references/health-check.mdmarkdown27.0 KB
references/ingest-and-scope.mdmarkdown28.2 KB
references/preflight.mdmarkdown83.6 KB
scripts/carry_build_cache.pyscript18.6 KB
scripts/claim_check.pyscript36.3 KB
scripts/drive_epic.pyexecutablescript64.1 KB
scripts/formalize_check.pyscript83.7 KB
scripts/gate_eval.pyexecutablescript67.8 KB
scripts/gate_trail.pyexecutablescript52.6 KB
scripts/headless_envelope.pyscript12.6 KB
scripts/health_check_fp.pyscript66.5 KB
scripts/hooks/budget_stop.pyexecutablescript18.7 KB
scripts/hooks/guard_pretooluse.pyexecutablescript180.1 KB
scripts/lib/mem_common.pyscript64.6 KB
scripts/link_worktree_deps.pyscript7.1 KB
scripts/mem_observation.pyscript35.5 KB
scripts/mem_recall.pyscript19.9 KB
scripts/merge_config.pyexecutablescript13.8 KB
scripts/merge_customization.pyscript18.7 KB
scripts/merge_help_csv.pyscript9.5 KB
scripts/moved_ac_check.pyscript10.0 KB
scripts/mutate_check.pyscript64.4 KB
scripts/operator_owed.pyscript17.0 KB
scripts/preflight_check.pyscript115.2 KB
scripts/probe_servers.pyscript38.7 KB
scripts/red_ids.pyscript14.0 KB
scripts/status_render.pyscript26.0 KB
scripts/story_sizing.pyexecutablescript11.7 KB
scripts/tests/bench_ucg_formalize.mdmarkdown7.3 KB
scripts/tests/fixtures/claude_mem_real_payload.jsonconfig3.4 KB
scripts/tests/fixtures/engine-6.12/README.mdmarkdown957 B
scripts/tests/fixtures/engine-6.12/config_utils.pyscript4.1 KB
scripts/tests/fixtures/engine-6.12/resolve_customization.pyexecutablescript5.1 KB
scripts/tests/fixtures/engine/README.mdmarkdown1.0 KB
scripts/tests/fixtures/engine/resolve_customization.pyexecutablescript8.0 KB
scripts/tests/fixtures/execute_pre_verification_axes.mdmarkdown29.1 KB
scripts/tests/fixtures/execute_resume_clause_no_baseline.mdmarkdown215 B
scripts/tests/fixtures/execute_run_status_preedit.mdmarkdown1.2 KB
scripts/tests/fixtures/execute_spine_end_no_escalation_fire.mdmarkdown194 B
scripts/tests/fixtures/execute_step0_baseline_no_sha.mdmarkdown1.0 KB
scripts/tests/fixtures/execute_ticker_line.mdmarkdown332 B
scripts/tests/fixtures/finalize_epic_complete_hook_no_escalation.mdmarkdown579 B
scripts/tests/fixtures/finalize_headless_output_hand_composed.mdmarkdown1.2 KB
scripts/tests/fixtures/finalize_no_graphify_section.mdmarkdown19.4 KB
scripts/tests/fixtures/floor/all_clean/impl-artifacts/7-1-clean.mdmarkdown477 B
scripts/tests/fixtures/floor/all_clean/impl-artifacts/sprint-status.yamlconfig88 B
scripts/tests/fixtures/floor/all_clean/planning-artifacts/architecture-fixture.mdmarkdown236 B
scripts/tests/fixtures/floor/all_clean/planning-artifacts/prd-fixture.mdmarkdown225 B
scripts/tests/fixtures/floor/all_clean/tea/config.yamlconfig104 B
scripts/tests/fixtures/floor/all_clean/tea/traceability/e2e-trace-summary.jsonconfig48 B
scripts/tests/fixtures/floor/invented_threshold/impl-artifacts/61-1-threshold.mdmarkdown564 B
scripts/tests/fixtures/floor/invented_threshold/impl-artifacts/sprint-status.yamlconfig94 B
scripts/tests/fixtures/floor/invented_threshold/planning-artifacts/architecture-fixture.mdmarkdown236 B
scripts/tests/fixtures/floor/invented_threshold/planning-artifacts/prd-fixture.mdmarkdown225 B
scripts/tests/fixtures/floor/invented_threshold/tea/config.yamlconfig104 B
scripts/tests/fixtures/floor/invented_threshold/tea/traceability/e2e-trace-summary.jsonconfig48 B
scripts/tests/fixtures/floor/invented_threshold_unknown/impl-artifacts/61-1-threshold.mdmarkdown644 B
scripts/tests/fixtures/floor/invented_threshold_unknown/impl-artifacts/sprint-status.yamlconfig94 B
scripts/tests/fixtures/floor/invented_threshold_unknown/planning-artifacts/architecture-fixture.mdmarkdown236 B
scripts/tests/fixtures/floor/invented_threshold_unknown/planning-artifacts/prd-fixture.mdmarkdown225 B
scripts/tests/fixtures/floor/invented_threshold_unknown/tea/config.yamlconfig104 B
scripts/tests/fixtures/floor/invented_threshold_unknown/tea/traceability/e2e-trace-summary.jsonconfig48 B
scripts/tests/fixtures/floor/leaked_tea/impl-artifacts/9-1-leak.mdmarkdown475 B
scripts/tests/fixtures/floor/leaked_tea/impl-artifacts/sprint-status.yamlconfig87 B
scripts/tests/fixtures/floor/leaked_tea/impl-artifacts/test-design-9-1.mdmarkdown291 B
scripts/tests/fixtures/floor/leaked_tea/planning-artifacts/architecture-fixture.mdmarkdown236 B
scripts/tests/fixtures/floor/leaked_tea/planning-artifacts/prd-fixture.mdmarkdown225 B
scripts/tests/fixtures/floor/leaked_tea/tea/config.yamlconfig104 B
scripts/tests/fixtures/floor/leaked_tea/tea/traceability/e2e-trace-summary.jsonconfig48 B
scripts/tests/fixtures/floor/leaked_tea_clean/impl-artifacts/9-1-leak.mdmarkdown475 B
scripts/tests/fixtures/floor/leaked_tea_clean/impl-artifacts/sprint-status.yamlconfig87 B
scripts/tests/fixtures/floor/leaked_tea_clean/planning-artifacts/architecture-fixture.mdmarkdown236 B
scripts/tests/fixtures/floor/leaked_tea_clean/planning-artifacts/prd-fixture.mdmarkdown225 B
scripts/tests/fixtures/floor/leaked_tea_clean/tea/config.yamlconfig104 B
scripts/tests/fixtures/floor/leaked_tea_clean/tea/traceability/e2e-trace-summary.jsonconfig48 B
scripts/tests/fixtures/floor/leaked_tea_clean/tea/traceability/test-design-9-1.mdmarkdown296 B
scripts/tests/fixtures/floor/orphaned_index/impl-artifacts/10-1-orphan.mdmarkdown513 B
scripts/tests/fixtures/floor/orphaned_index/impl-artifacts/sprint-status.yamlconfig91 B
scripts/tests/fixtures/floor/orphaned_index/planning-artifacts/architecture-fixture.mdmarkdown236 B
scripts/tests/fixtures/floor/orphaned_index/planning-artifacts/prd-fixture.mdmarkdown225 B
scripts/tests/fixtures/floor/orphaned_index/tea/config.yamlconfig104 B
scripts/tests/fixtures/floor/orphaned_index/tea/traceability/e2e-trace-summary.jsonconfig48 B
scripts/tests/fixtures/floor/orphaned_index_resolved/impl-artifacts/10-1-orphan.mdmarkdown508 B
scripts/tests/fixtures/floor/orphaned_index_resolved/impl-artifacts/10-2-helper.mdmarkdown479 B
scripts/tests/fixtures/floor/orphaned_index_resolved/impl-artifacts/sprint-status.yamlconfig120 B
scripts/tests/fixtures/floor/orphaned_index_resolved/planning-artifacts/architecture-fixture.mdmarkdown236 B
scripts/tests/fixtures/floor/orphaned_index_resolved/planning-artifacts/prd-fixture.mdmarkdown225 B
scripts/tests/fixtures/floor/orphaned_index_resolved/tea/config.yamlconfig104 B
scripts/tests/fixtures/floor/orphaned_index_resolved/tea/traceability/e2e-trace-summary.jsonconfig48 B
scripts/tests/fixtures/floor/sourced_threshold/impl-artifacts/61-1-threshold.mdmarkdown609 B
scripts/tests/fixtures/floor/sourced_threshold/impl-artifacts/sprint-status.yamlconfig94 B
scripts/tests/fixtures/floor/sourced_threshold/planning-artifacts/architecture-fixture.mdmarkdown236 B
scripts/tests/fixtures/floor/sourced_threshold/planning-artifacts/prd-fixture.mdmarkdown225 B
scripts/tests/fixtures/floor/sourced_threshold/tea/config.yamlconfig104 B
scripts/tests/fixtures/floor/sourced_threshold/tea/traceability/e2e-trace-summary.jsonconfig48 B
scripts/tests/fixtures/floor/unclassified_signal/impl-artifacts/12-1-signal.mdmarkdown552 B
scripts/tests/fixtures/floor/unclassified_signal/impl-artifacts/sprint-status.yamlconfig91 B
scripts/tests/fixtures/floor/unclassified_signal/planning-artifacts/architecture-fixture.mdmarkdown236 B
scripts/tests/fixtures/floor/unclassified_signal/planning-artifacts/prd-fixture.mdmarkdown225 B
scripts/tests/fixtures/floor/unclassified_signal/tea/config.yamlconfig104 B
scripts/tests/fixtures/floor/unclassified_signal/tea/traceability/e2e-trace-summary.jsonconfig48 B
scripts/tests/fixtures/floor/unclassified_signal_removed/impl-artifacts/12-1-signal.mdmarkdown483 B
scripts/tests/fixtures/floor/unclassified_signal_removed/impl-artifacts/sprint-status.yamlconfig91 B
scripts/tests/fixtures/floor/unclassified_signal_removed/planning-artifacts/architecture-fixture.mdmarkdown236 B
scripts/tests/fixtures/floor/unclassified_signal_removed/planning-artifacts/prd-fixture.mdmarkdown225 B
scripts/tests/fixtures/floor/unclassified_signal_removed/tea/config.yamlconfig104 B
scripts/tests/fixtures/floor/unclassified_signal_removed/tea/traceability/e2e-trace-summary.jsonconfig48 B
scripts/tests/fixtures/floor/vacuous_ac/impl-artifacts/8-1-vacuous.mdmarkdown435 B
scripts/tests/fixtures/floor/vacuous_ac/impl-artifacts/sprint-status.yamlconfig90 B
scripts/tests/fixtures/floor/vacuous_ac/planning-artifacts/architecture-fixture.mdmarkdown236 B
scripts/tests/fixtures/floor/vacuous_ac/planning-artifacts/prd-fixture.mdmarkdown225 B
scripts/tests/fixtures/floor/vacuous_ac/tea/config.yamlconfig104 B
scripts/tests/fixtures/floor/vacuous_ac/tea/traceability/e2e-trace-summary.jsonconfig48 B
scripts/tests/fixtures/floor/vacuous_ac_sound/impl-artifacts/8-1-vacuous.mdmarkdown482 B
scripts/tests/fixtures/floor/vacuous_ac_sound/impl-artifacts/sprint-status.yamlconfig90 B
scripts/tests/fixtures/floor/vacuous_ac_sound/planning-artifacts/architecture-fixture.mdmarkdown236 B
scripts/tests/fixtures/floor/vacuous_ac_sound/planning-artifacts/prd-fixture.mdmarkdown225 B
scripts/tests/fixtures/floor/vacuous_ac_sound/tea/config.yamlconfig104 B
scripts/tests/fixtures/floor/vacuous_ac_sound/tea/traceability/e2e-trace-summary.jsonconfig48 B
scripts/tests/fixtures/formalize/epic-clean-control/LABEL.mdmarkdown751 B
scripts/tests/fixtures/formalize/epic-clean-control/impl-artifacts/7-1-clean.mdmarkdown477 B
scripts/tests/fixtures/formalize/epic-clean-control/impl-artifacts/sprint-status.yamlconfig88 B
scripts/tests/fixtures/formalize/epic-clean-control/planning-artifacts/architecture-fixture.mdmarkdown236 B
scripts/tests/fixtures/formalize/epic-clean-control/planning-artifacts/prd-fixture.mdmarkdown225 B
scripts/tests/fixtures/formalize/epic-clean-control/tea/config.yamlconfig104 B
scripts/tests/fixtures/formalize/epic-clean-control/tea/traceability/e2e-trace-summary.jsonconfig48 B
scripts/tests/fixtures/formalize/epic-judgment-seed/LABEL.mdmarkdown1.1 KB
scripts/tests/fixtures/formalize/epic-judgment-seed/impl-artifacts/61-1-threshold.mdmarkdown564 B
scripts/tests/fixtures/formalize/epic-judgment-seed/impl-artifacts/sprint-status.yamlconfig94 B
scripts/tests/fixtures/formalize/epic-judgment-seed/planning-artifacts/architecture-fixture.mdmarkdown236 B
scripts/tests/fixtures/formalize/epic-judgment-seed/planning-artifacts/prd-fixture.mdmarkdown225 B
scripts/tests/fixtures/formalize/epic-judgment-seed/tea/config.yamlconfig104 B
scripts/tests/fixtures/formalize/epic-judgment-seed/tea/traceability/e2e-trace-summary.jsonconfig48 B
scripts/tests/fixtures/formalize/low_ratio_zero_gap_epic/impl-artifacts/6-1-experience.mdmarkdown1.3 KB
scripts/tests/fixtures/formalize/low_ratio_zero_gap_epic/impl-artifacts/sprint-status.yamlconfig93 B
scripts/tests/fixtures/formalize/low_ratio_zero_gap_epic/planning-artifacts/architecture-fixture.mdmarkdown93 B
scripts/tests/fixtures/formalize/low_ratio_zero_gap_epic/planning-artifacts/prd-fixture.mdmarkdown84 B
scripts/tests/fixtures/formalize/low_ratio_zero_gap_epic/tea/config.yamlconfig104 B
scripts/tests/fixtures/formalize/low_ratio_zero_gap_epic/tea/traceability/.keepother32 B
scripts/tests/fixtures/formalize/ready_epic/impl-artifacts/1-1-kernel.mdmarkdown848 B
scripts/tests/fixtures/formalize/ready_epic/impl-artifacts/1-2-floor.mdmarkdown538 B
scripts/tests/fixtures/formalize/ready_epic/impl-artifacts/sprint-status.yamlconfig110 B
scripts/tests/fixtures/formalize/ready_epic/planning-artifacts/architecture-fixture.mdmarkdown218 B
scripts/tests/fixtures/formalize/ready_epic/planning-artifacts/prd-fixture.mdmarkdown207 B
scripts/tests/fixtures/formalize/ready_epic/tea/config.yamlconfig104 B
scripts/tests/fixtures/formalize/ready_epic/tea/traceability/e2e-trace-summary.jsonconfig49 B
scripts/tests/fixtures/formalize/remediable_epic/impl-artifacts/2-1-thin.mdmarkdown202 B
scripts/tests/fixtures/formalize/remediable_epic/impl-artifacts/sprint-status.yamlconfig87 B
scripts/tests/fixtures/formalize/remediable_epic/planning-artifacts/architecture-fixture.mdmarkdown94 B
scripts/tests/fixtures/formalize/remediable_epic/planning-artifacts/prd-fixture.mdmarkdown85 B
scripts/tests/fixtures/formalize/remediable_epic/tea/config.yamlconfig104 B
scripts/tests/fixtures/formalize/remediable_epic/tea/traceability/.keepother32 B
scripts/tests/fixtures/formalize/unclassified_signal_epic/impl-artifacts/4-1-signal.mdmarkdown546 B
scripts/tests/fixtures/formalize/unclassified_signal_epic/impl-artifacts/sprint-status.yamlconfig89 B
scripts/tests/fixtures/formalize/unclassified_signal_epic/planning-artifacts/architecture-fixture.mdmarkdown103 B
scripts/tests/fixtures/formalize/unclassified_signal_epic/planning-artifacts/prd-fixture.mdmarkdown94 B
scripts/tests/fixtures/formalize/unclassified_signal_epic/tea/config.yamlconfig104 B
scripts/tests/fixtures/formalize/unclassified_signal_epic/tea/traceability/.keepother32 B
scripts/tests/fixtures/formalize/unreadable_epic/impl-artifacts/3-1-broken.mdbinary28 B
scripts/tests/fixtures/formalize/unreadable_epic/impl-artifacts/sprint-status.yamlconfig89 B
scripts/tests/fixtures/formalize/unreadable_epic/tea/config.yamlconfig85 B
scripts/tests/fixtures/formalize/unreadable_epic/tea/traceability/.keepother14 B
scripts/tests/fixtures/formalize/wrong_root_epic/impl-artifacts/5-1-place.mdmarkdown420 B
scripts/tests/fixtures/formalize/wrong_root_epic/impl-artifacts/prd-fixture.mdmarkdown226 B
scripts/tests/fixtures/formalize/wrong_root_epic/impl-artifacts/sprint-status.yamlconfig88 B
scripts/tests/fixtures/formalize/wrong_root_epic/planning-artifacts/architecture-fixture.mdmarkdown187 B
scripts/tests/fixtures/formalize/wrong_root_epic/tea/config.yamlconfig104 B
scripts/tests/fixtures/formalize/wrong_root_epic/tea/traceability/.keepother32 B
scripts/tests/fixtures/gate_run_the_gate_no_ticker.mdmarkdown5.7 KB
scripts/tests/fixtures/gate_trail/light/decision-log.mdmarkdown341 B
scripts/tests/fixtures/gate_trail/light/impl-artifacts/.baseline-2-4other41 B
scripts/tests/fixtures/gate_trail/light/impl-artifacts/.baseline-2-6other41 B
scripts/tests/fixtures/gate_trail/light/test-artifacts/traceability/gate-decision-2-4.jsonconfig751 B
scripts/tests/fixtures/gate_trail/light/test-artifacts/traceability/gate-decision-2-6.jsonconfig755 B
scripts/tests/fixtures/gate_trail/light/test-artifacts/traceability/trace-2-4.mdmarkdown1.4 KB
scripts/tests/fixtures/gate_trail/light/test-artifacts/traceability/trace-2-6.mdmarkdown1.3 KB
scripts/tests/fixtures/gate_trail/production/decision-log.mdmarkdown783 B
scripts/tests/fixtures/gate_trail/production/impl-artifacts/.baseline-7-1other41 B
scripts/tests/fixtures/gate_trail/production/impl-artifacts/.baseline-7-2other41 B
scripts/tests/fixtures/gate_trail/production/impl-artifacts/.baseline-7-3other41 B
scripts/tests/fixtures/gate_trail/production/test-artifacts/atdd-checklist-7-1.mdmarkdown509 B
scripts/tests/fixtures/gate_trail/production/test-artifacts/atdd-checklist-7-2.mdmarkdown300 B
scripts/tests/fixtures/gate_trail/production/test-artifacts/traceability/gate-decision-7-1.jsonconfig648 B
scripts/tests/fixtures/gate_trail/production/test-artifacts/traceability/gate-decision-7-2.jsonconfig679 B

scripts/hooks/guard_pretooluse.py

View on GitHub
#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.11"
# dependencies = []
# ///
"""UltraCode-Goal PreToolUse guard (Claude Code hook).

Enforces invariants that must NOT live in memory (context, not enforcement):
  1. No `git commit`/`git push` while on a protected branch. The branch is read
     from the hook event's `cwd`, i.e. the session's working directory, NOT the
     repository the command targets, so a `cd /other/repo && git commit` is
     denied while the session's own repo sits on a protected branch. Deliberate
     for now (it errs toward denying), but it is the reason a legitimate commit
     in an unrelated checkout can be refused.
  2. No `git commit` until a "tests-ran" marker exists for the current story.
     A `git commit --dry-run` meets this check and every other commit check,
     as a commit does: preflight step 5's probe relies on that, since with no
     story set a guard the session runs refuses it here
     (references/preflight.md).
  3. Marker freshness: no `git commit` unless that marker carries a
     `baseline=<sha>` line matching, character for character, the SHA the story
     recorded when it started. A bare existence check accepts a marker replayed
     from an earlier code state; this ties the marker to the story it claims to
     be green for. Both values are READ from disk (two file reads, no git call)
     and neither is recomputed, so a story spanning several commits stays valid
     after HEAD moves. Fail closed: a marker with no `baseline=` line, or an
     unreadable baseline file, denies.
  4. No `git commit` while the staged index is empty (a commit that captures no
     work), or while the staged-index probe cannot answer (fail closed). An
     intent-to-add entry (`git add -N`, which Execute's step 2 makes for a
     story's new files) is no staged work here. Then, no `git commit` while
     the index holds any intent-to-add entry, or while that probe cannot
     answer (fail closed): a commit leaves such an entry out while the index
     keeps it (over a path HEAD holds, it deletes HEAD's file), and
     `git show :<path>` reads it as an empty blob. The deny names each entry.
  5. Un-skip proof: in production (an atdd-checklist for the current story is on
     disk), no `git commit` while the STAGED CONTENT of any acceptance-test file
     that checklist enumerates still contains `test.skip(`. The files are the
     ones its `generatedTestFiles` frontmatter lists; only a checklist with no
     such list, or one naming no JS/TS test file, is scanned whole for
     test-file paths. A list that cannot be read as a list denies. This reads
     the blob being committed, not a diff, so it also catches a story's first
     commit, where there is no prior blob to compare against. It runs after
     invariant 4, so it never reads an intent-to-add entry's empty blob.
  6. Cross-Session Recall, claude-mem: while a run latch (.mem-state.json) is
     present, every claude-mem MCP call (the plugin form and both bare-server
     forms, an MCP resource read or listing on a claude-mem server, and a
     resource listing that names no server, which lists them all) and every
     reach into .claude-mem is denied, whatever the latch's version (v1 or
     v2) or colour. There is no green path: UCG no longer uses claude-mem.
     With no latch, the user's own claude-mem usage is never touched.
     Accepted residual, as for the store below: a search of a folder above
     .claude-mem (a Grep, a `grep -r` or a `**` glob from the home folder).
  7. Cross-Session Recall, local run store and latch file: while a run latch
     is present, the model's tool calls may read the latch but not change it,
     and may not reach the store the latch names.
     - The latch file, whatever the latch holds: a Write, Edit, MultiEdit or
       NotebookEdit call that names the latch path is denied, and so is a Bash
       segment that names it, by path or by its file name on its own
       (_names_file_name), and is not a plain read (_read_segment). Read,
       Grep and Glob are left alone, since Finalize reads the latch.
     - The store, when the latch names a usable store path: a Read, Grep,
       Glob, Write, Edit, MultiEdit, NotebookEdit or Bash call that names that
       path is denied.
     Both read a Bash command without each heredoc body the guard can tell
     bash only hands to a `cat` or `tee` that leads its simple command, as
     data (_without_heredoc_data, whose section comment lists the
     conditions); every other body is read as commands.
     A Bash segment is exempt from both only when it runs this skill's own
     scripts/mem_recall.py or scripts/mem_observation.py, by path, as
     `uv run <path> ...` or `python <path> ...`, with no redirection, command
     substitution or wrapper, in a command that changes no environment or
     command lookup. So only mem_recall.py changes the latch: `latch` writes
     it, and `unlatch` removes it when it carries the caller's run_id.
     Accepted residual, stated like the exec-wrapper one below: indirection
     (for the store, a `cd` then a relative path; a glob that matches a
     symlink on the way to it or a folder before that symlink, such as the
     `[H]` or `?` in `cat [H]/.ultracode-goal/recall/*` after `ln -s ~ H`,
     or the `d*` in `cat d*/H/.ultracode-goal/recall/*` with H such a link
     in d, a brace group in a word longer than _BRACE_WORD_CAP counting as
     such a glob; and a `..` that climbs back over a symlink, as in
     `cat L/../recall/*` with L a link to the store. Each at any length: the
     guard expands no glob against the file system, and resolves the links a
     path spells only after abspath has applied its `..` steps to the path
     as written. For both, a variable holding part of the path or the name,
     a script that names the store or the latch in its contents, whether a
     file tool or a heredoc fed to `cat` or `tee` wrote it), commands on an
     ancestor directory (a search of it, removing the implementation
     artifacts folder, a `git clean` or `git stash --all`), repo-wide
     searches that reach a store inside the workspace, the interpreter `uv`
     or `python` resolves to, with the configuration it reads, and a pinned
     call itself: the exemption checks the script's path, not its arguments,
     so a model that ignores the deny note can still run `latch` or
     `unlatch` on its own.
  Accepted residual for 6 and 7, on time: while a latch is present they
  resolve the symlinks of every path a call names, and nothing bounds that
  short of Claude Code's hook timeout. _MAX_LONG_LOOKUPS caps the names
  realpath is handed for one path longer than _MAX_RESOLVED, not the names
  inside the targets of the links it follows (some 2,000 in a target on
  Linux, looked up again by each stretch), nor a call that names many paths
  (many words, or the variants of a brace group). With such links behind a
  folder some 2,000 levels deep, where each lookup is slow, a crafted call
  can keep the guard past the timeout. Preflight arms the guard with
  "onFailure": "block", so Claude Code then refuses the call: a stall, not a
  way past the guard.
  Invariants 6 and 7 count a present latch as a live run: the guard reads no
  clock and detects no dead run, so a latch a dead run left behind keeps
  denying until the next Stage 1 replaces it or the user deletes it by hand.
  Every deny a latch causes names the latch path and ends with a note for the
  person: a latch left behind is theirs to delete by hand, and the model must
  not try to remove it.

Hook contract (reads one JSON object on stdin):
  in : {tool_name, tool_input:{command,...}, cwd, ...}
  out: exit 0 + JSON {hookSpecificOutput:{hookEventName,permissionDecision,
       permissionDecisionReason}} where permissionDecision is "deny" to block.
  Defensive fallback: also exit 2 with the reason on stderr (older clients
  honor exit-code-2-blocks even when they ignore the JSON).
  Exit codes: 0 (allow, silent) or 2 (deny), never another. An error the
  guard raises while deciding (an event that is not a JSON object, a Bash
  tool_input that is not one, JSON nested past Python's recursion limit, or
  any other) denies the call and names the error, rather than ending the
  hook with no decision, which Claude Code reads as no objection.

This hook is invoked standalone from settings.local.json. It MUST stay fully
self-contained: no sibling imports (the shared library lib/mem_common.py et al.
are NOT imported).

Config resolution (all optional, env wins so the conductor can inject per run):
  ULTRACODE_PROTECTED_BRANCHES  comma-separated; default "main,master"
  ULTRACODE_IMPL_ARTIFACTS      dir holding run state (story id + markers)
  ULTRACODE_STORY_ID            current story id (blank counts as unset);
                                else read from <impl_artifacts>/.current-story
  ULTRACODE_TEST_ARTIFACTS      TEA test-artifacts root; arms the un-skip proof.
                                No default is derived here on purpose (see
                                _test_artifacts): unset means the check is out
                                of scope, never a deny.
  Marker file checked: <impl_artifacts>/.tests-ran-<story_id>
  Baseline read:       <impl_artifacts>/.baseline-<story_id>, the SHA the story
                  recorded before any implementation. Compared as a verbatim,
                  whitespace-stripped string against the marker's `baseline=`
                  line: no `git rev-parse`, no short-SHA normalization, no
                  case-folding. Same <impl_artifacts> and same <story_id> the
                  tests-ran marker uses, deliberately, so there is one
                  resolution path rather than two that can drift apart.
  State latch checked: <impl_artifacts>/.mem-state.json (Cross-Session Recall),
                  read v1 or v2 by this file's own copy of lib/mem_common.py's
                  read_state() and latch_view(), so both read one latch the
                  same way (pinned by a parity test).
  Skill root:     this file's own location, <skill-root>/scripts/hooks/, so
                  the pinned recall scripts are <skill-root>/scripts/
                  mem_recall.py and mem_observation.py (see _pinned_scripts).
  Checklist read: <test_artifacts>/atdd-checklist-<story_id>.md, keyed by the
                  SAME story id the tests-ran marker uses (the id resolved by
                  _current_story). A story_key/story_id drift here would make
                  the un-skip proof silently inert, the worst failure mode a
                  deny guard has. The paths come from its `generatedTestFiles`
                  frontmatter, the list TEA's ATDD writes of the test files it
                  scaffolded (see _listed_test_files).
  Skip token matched: the literal `test.skip(`. That token is JS/Vitest-specific
                  (the Playwright/Vitest form TEA's ATDD generates, which is
                  web/JS-only today); a pytest or Go acceptance suite marks
                  skips differently and this check would not see them.
"""

import bisect
import fnmatch
import functools
import json
import os
import re
import shlex
import subprocess
import sys
import unicodedata
from pathlib import Path
from typing import NamedTuple, NoReturn

DEFAULT_PROTECTED = ["main", "master"]


def _read_event() -> dict:
    try:
        raw = sys.stdin.read()
        return json.loads(raw) if raw.strip() else {}
    except (json.JSONDecodeError, ValueError):
        return {}


def _allow() -> NoReturn:
    """No decision needed: stay silent, let the normal permission flow run."""
    sys.exit(0)


def _deny(reason: str, hint: str = "") -> NoReturn:
    reason += hint
    print(
        json.dumps(
            {
                "hookSpecificOutput": {
                    "hookEventName": "PreToolUse",
                    "permissionDecision": "deny",
                    "permissionDecisionReason": reason,
                }
            }
        )
    )
    # Belt-and-suspenders: clients that ignore JSON still block on exit 2.
    print(reason, file=sys.stderr)
    sys.exit(2)


def _note(message: str) -> None:
    """Say something on stderr and RETURN (no decision, no exit).

    stdout is the decision channel: anything printed there is parsed as the
    hook's verdict, so a path that reaches no decision must stay off it.
    """
    print(message, file=sys.stderr)


def _protected_branches() -> list[str]:
    env = os.environ.get("ULTRACODE_PROTECTED_BRANCHES")
    if env:
        return [b.strip() for b in env.split(",") if b.strip()]
    return DEFAULT_PROTECTED


def _current_branch(cwd: str | None) -> str | None:
    # Git prints a branch name as the bytes it stores it as, and the platform's
    # text decoding could not read every name (a byte that is not UTF-8, or on
    # Windows a UTF-8 name its ANSI code page lacks): the hook raised instead
    # of reporting the branch. The bytes are decoded as os.environ decodes
    # ULTRACODE_PROTECTED_BRANCHES (os.fsdecode: the locale's encoding with
    # surrogateescape on POSIX, UTF-8 on Windows). Read as UTF-8 whatever the
    # locale, a non-ASCII name under a locale that is not UTF-8 read one way
    # here and another in the list, and matched no protected name.
    try:
        out = subprocess.run(
            ["git", "rev-parse", "--abbrev-ref", "HEAD"],
            cwd=cwd or None,
            capture_output=True,
            timeout=10,
        )
    except (OSError, subprocess.SubprocessError):
        return None
    if out.returncode == 0:
        branch = os.fsdecode(out.stdout).strip()
        return branch or None
    # An unborn HEAD (a fresh `git init`, nothing committed) fails rev-parse
    # while still printing the literal `HEAD`, which matched no protected name
    # and let a commit through on an unborn `main`. The symbolic ref still
    # names the branch; outside a repository it fails too, and None stands.
    try:
        ref = subprocess.run(
            ["git", "symbolic-ref", "--short", "-q", "HEAD"],
            cwd=cwd or None,
            capture_output=True,
            timeout=10,
        )
    except (OSError, subprocess.SubprocessError):
        return None
    if ref.returncode != 0:
        return None
    return os.fsdecode(ref.stdout).strip() or None


def _staged_index_nonempty(cwd: str | None) -> bool:
    """True only when something is provably staged for the next commit.

    `git diff --cached --quiet` implies `--exit-code`: 0 means nothing is
    staged, 1 means something is, and any other code (128 outside a repo, for
    one) means the probe could not answer. Unlike _current_branch above, which
    swallows the same failures and fails OPEN by returning None, this one fails
    CLOSED: an unanswerable probe reports "nothing staged" so the caller blocks
    the commit rather than waving through a commit it could not inspect.
    """
    try:
        out = subprocess.run(
            ["git", "diff", "--cached", "--quiet"],
            cwd=cwd or None,
            capture_output=True,
            text=True,
            timeout=10,
        )
    except (OSError, subprocess.SubprocessError):
        return False  # git missing, timeout, ...: cannot answer -> fail closed
    if out.returncode == 0:
        return False  # nothing staged
    if out.returncode == 1:
        return True  # something staged
    return False  # any other exit code is a probe failure -> fail closed


def _intent_to_add_entries(cwd: str | None) -> list[str] | None:
    """The index's intent-to-add entries (`git add -N`), named from the top
    level, or None when git cannot say (the caller fails closed on None).

    Porcelain `git diff --cached` reads such an entry as absent from the
    index, which is why the empty-index probe above never counts one as
    staged work, and the same command with `--ita-visible-in-index` reads it
    as an empty file. An entry that is no mark reads the same in both, so
    the marks are the paths of the (status, path) pairs only one of them
    lists. Pairs, not names, and both directions: a mark over a path HEAD
    holds (`git rm --cached p`, then `git add -N p`, status `DA`) is listed
    as `M` with marks visible and `D` without, so a name-only subtraction
    dropped it; over a file HEAD holds empty (an `__init__.py`), the visible
    form lists nothing at all (the mark's empty blob is HEAD's) and only the
    other lists `D`. Either way the commit deletes HEAD's file.
    Both compare the index with HEAD (with the empty tree on an unborn HEAD),
    so a marked file since deleted or moved out of the work tree is still
    listed, where `git status` would show it as ` D` or pair it into a
    rename. `diff.relative=false` keeps both lists whole and named from the
    top level whatever folder the hook runs in. Its own probe on purpose:
    this hook imports nothing from its siblings.
    """
    listed: list[set[tuple[bytes, bytes]]] = []
    for visible in (["--ita-visible-in-index"], []):
        try:
            out = subprocess.run(
                ["git", "-c", "diff.relative=false", "diff", "--cached", *visible,
                 "--name-status", "--no-renames", "-z"],
                cwd=cwd or None,
                capture_output=True,
                timeout=10,
            )
        except (OSError, subprocess.SubprocessError):
            return None  # git missing, timeout, ...: cannot answer -> fail closed
        if out.returncode != 0:
            return None  # any non-zero exit is a probe failure -> fail closed
        # `-z` with `--no-renames`: a status field, then its path, each
        # NUL-terminated, so the fields pair up in order.
        fields = out.stdout.split(b"\0")[:-1]
        if len(fields) % 2:
            return None  # a status with no path: unreadable output -> fail closed
        listed.append(set(zip(fields[0::2], fields[1::2])))
    visible_pairs, plain_pairs = listed
    return sorted({os.fsdecode(path) for _, path in visible_pairs ^ plain_pairs})


def _impl_artifacts(cwd: str | None) -> Path | None:
    env = os.environ.get("ULTRACODE_IMPL_ARTIFACTS")
    if env:
        return Path(env)
    if cwd:
        return Path(cwd) / "_bmad-output" / "implementation-artifacts"
    return None


def _test_artifacts() -> Path | None:
    """TEA test-artifacts root, from env ONLY.

    Mirrors _impl_artifacts above but deliberately WITHOUT its cwd-derived
    fallback. Hooks armed by a run that predates the un-skip proof inject no
    ULTRACODE_TEST_ARTIFACTS; synthesizing a path here would pull every such
    session into scope and brick its commits on a checklist it never wrote.
    Unset means out of scope (an advisory note, never a deny); fail-closed
    behavior applies only *within* scope, once the var is set.
    """
    env = os.environ.get("ULTRACODE_TEST_ARTIFACTS")
    if env:
        return Path(env)
    return None


def _current_story(impl: Path | None) -> str | None:
    # A blank ULTRACODE_STORY_ID counts as unset, as the Stop hook reads it, so
    # both hooks resolve the same story from the same .current-story marker.
    sid = (os.environ.get("ULTRACODE_STORY_ID") or "").strip()
    if sid:
        return sid
    if impl is not None:
        marker = impl / ".current-story"
        if marker.is_file():
            # A pointer that cannot be read or decoded names no story, so the
            # tests-ran gate denies: an exception here would end the hook with
            # no decision, and the commit would go through.
            try:
                return marker.read_text(encoding="utf-8").strip() or None
            except (OSError, UnicodeDecodeError):
                return None
    return None


# --- git write detection ----------------------------------------------------
# `git commit` and `git push` are the targets. A shell segment counts as a git
# write only when `git` is its LEADING token — once leading `VAR=val`
# assignments and known exec wrappers are stripped — and the subcommand it would
# run is exactly one of those verbs. Anchoring on the leading token is what
# keeps a verb merely MENTIONED (inside an `echo`, a log line, a here-string)
# from being read as a real commit; matching the verb by exact token equality is
# what keeps `git commit-tree`-style near-misses out, which a trailing `\b`
# never did (`-` is itself a word boundary). A subcommand that is not one git
# runs before any alias counts as both verbs (_unknown_subcommand_verbs).

_WRITE_VERBS = frozenset({"commit", "push"})

# Legacy matches-anywhere scan. Kept ONLY as the fail-closed fallback for a
# segment this tokenizer cannot honestly read (see _segment_write_verbs): for
# those, biasing toward a deny beats guessing.
_GIT_WRITE_ANYWHERE = re.compile(
    r"\bgit\b[^\n;&|]*?\b(?P<verb>commit|push)\b", re.IGNORECASE
)

# Commands that exec another command, so the real leading token sits further
# right. Extendable on purpose: add a name here and its prefixed form anchors
# too. A wrapper NOT on this list leaves a non-`git` leading token and its
# segment is allowed through — the accepted residual, stated in
# references/preflight.md rather than hidden.
_EXEC_WRAPPERS = frozenset(
    {
        "env",
        "command",
        "sudo",
        "time",
        "nice",
        "nohup",
        "timeout",
        "setsid",
        "stdbuf",
        "ionice",
        "doas",
        "exec",
        "builtin",
    }
)
# The most wrappers read ahead of a segment's head, by the git reading
# (_token_write_verbs) and by the rebinding scan (_segment_rebinds): a bound,
# not a behavior anyone should rely on. Past it each fails closed, so a long
# run of wrappers can neither overflow the stack nor cost time quadratic in
# its length.
_MAX_WRAPPERS = 32

# Shells whose `-c` string payload is re-entered as a command in its own right.
_SHELL_WRAPPERS = frozenset({"sh", "bash", "zsh", "dash"})

# Shell keywords and group openers that occupy the command position inside a
# compound command. Without these, `then git commit`, `do git commit` and
# `( git commit )` lead with a token that is neither `git` nor any wrapper, so
# the segment classified as "no git write" and skipped EVERY commit gate.
# Stripping them is biased toward finding the `git`, exactly as _EXEC_WRAPPERS
# is: a keyword consumed here can only ever make the guard see more, never less.
_SHELL_KEYWORDS = frozenset(
    {
        "if",
        "then",
        "elif",
        "else",
        "fi",
        "for",
        "while",
        "until",
        "do",
        "done",
        "case",
        "esac",
        "select",
        "function",
        "coproc",
        "!",
        "{",
        "}",
        "(",
        ")",
    }
)

# Group openers can also sit glued to the command name (`(git commit -m x)` is
# a valid subshell), where they are part of the first token rather than a token
# of their own.
_GROUP_OPENERS = "({"

# A redirection operator, with its descriptor, at the start of a word; what
# follows it in the same word is its target.
_REDIRECTION = re.compile(r"^\d*(?:&>>|&>|>>|>&|>\||<<<|<<-|<<|<>|<&|>|<)")

# Global `git` options taking a SEPARATE value. The value must be skipped along
# with the option, or `git -C <path> commit` would read <path> as the
# subcommand and wave a real commit through.
_GIT_VALUE_OPTIONS = frozenset(
    {
        "-C",
        "-c",
        "--git-dir",
        "--work-tree",
        "--namespace",
        "--exec-path",
        "--config-env",
        "--super-prefix",
        "--attr-source",
        "--shallow-file",
    }
)

_ASSIGNMENT = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*=")

# Openers of a substitution that runs a command this tokenizer cannot see. A
# segment carrying one takes the fail-closed path instead of being anchored.
_SUBSTITUTION_MARKERS = ("$(", "`", "<(")

# Depth cap on `sh -c` recursion: a bound, not a behavior anyone should rely on.
# Past it, a `git` the guard cannot read deeper counts as both verbs.
_MAX_SHELL_DEPTH = 4
_GIT_WORD = re.compile(r"\bgit\b")

# A short-option cluster that carries `-c`, whose operand is the command string.
# Matching only the bare `-c` token was a fail-open: every real combined form
# (`bash -lc`, `sh -lc`, `bash -cx`, `zsh -ic`, `bash -ec`) located no payload,
# so the segment classified as carrying no git write and took the allow path
# BEFORE the protected-branch, tests-ran, marker-freshness and empty-index gates.
# The `c` is matched anywhere in the cluster, not just at the end, because the
# shells treat it positionally-indifferently: `bash -cx` and `bash -xc` both run
# the next token (verified against bash, sh and dash). A long option (`--login`)
# cannot match, since the character after the lone leading dash must be a letter.
_PAYLOAD_FLAG = re.compile(r"^-[A-Za-z]*c[A-Za-z]*$")


# --- git subcommands that are not git's own --------------------------------
# `git ci` runs `git commit` when `alias.ci = commit`, and nothing in the
# command says what an alias runs: git reads it from configuration the command
# can change before git starts. Whether `git <name>` is an external
# `git-<name>` command instead depends on PATH, which can differ between this
# hook and the shell that runs the command, or change inside it. So the guard
# reads neither. A git subcommand counts as no write only when it is one of
# git's built-in commands, which git runs before any alias and which nothing
# can move or shadow, spelled as git spells it (git matches its command names
# case-sensitively, so `git LOG` runs `alias.log`), or one of the commands git
# ships as scripts in its exec-path, while the command does not mention that
# path. Every other subcommand (an alias, an external command such as `git
# lfs`, a typo) counts as both verbs, so the commit and push gates judge it,
# and the deny names it (_unknown_hint). A built-in whose job is to run another
# git subcommand stays off the list (`for-each-repo`). Only commands built in on every
# supported build belong on the first list: none newer than Git 2.30, and no
# `whatchanged`, which Git 3.0 drops. A test checks both lists on both CI legs.
_GIT_COMMANDS = frozenset(
    {
        "add", "am", "annotate", "apply", "archive", "bisect", "blame",
        "branch", "bugreport", "bundle", "cat-file", "check-attr",
        "check-ignore", "check-mailmap", "check-ref-format", "checkout",
        "checkout-index", "cherry", "cherry-pick", "clean", "clone", "column",
        "commit-graph", "commit-tree", "config", "count-objects", "credential",
        "describe", "diff", "diff-files", "diff-index", "diff-tree",
        "difftool", "fast-export", "fast-import", "fetch", "fetch-pack",
        "fmt-merge-msg", "for-each-ref", "format-patch",
        "fsck", "gc", "grep", "hash-object", "help", "index-pack", "init",
        "init-db", "interpret-trailers", "log", "ls-files", "ls-remote",
        "ls-tree", "mailinfo", "mailsplit", "maintenance", "merge",
        "merge-base", "merge-file", "merge-index", "merge-tree", "mktag",
        "mktree", "multi-pack-index", "mv", "name-rev", "notes",
        "pack-objects", "pack-refs", "patch-id", "prune", "prune-packed",
        "pull", "range-diff", "read-tree", "rebase", "receive-pack", "reflog",
        "remote", "repack", "replace", "rerere", "reset", "restore",
        "rev-list", "rev-parse", "revert", "rm", "send-pack", "shortlog",
        "show", "show-branch", "show-index", "show-ref", "sparse-checkout",
        "stage", "stash", "status", "stripspace", "switch", "symbolic-ref",
        "tag", "unpack-objects", "update-index", "update-ref",
        "update-server-info", "upload-archive", "upload-pack", "var",
        "verify-commit", "verify-pack", "verify-tag", "version", "worktree",
        "write-tree",
    }
)
# Commands git ships as scripts in its exec-path, which it also runs before an
# alias of the name, unless the command moves that path (`--exec-path`,
# `GIT_EXEC_PATH`): a mention of it anywhere in the command, a nested shell's
# included, makes them count as both verbs too.
_GIT_SCRIPT_COMMANDS = frozenset({"filter-branch", "mergetool", "quiltimport", "request-pull", "submodule"})
_EXEC_PATH_TEXT = re.compile(r"exec[-_]path", re.IGNORECASE)

# What a git subcommand that is not git's own counts as: both verbs, so the
# commit and push gates judge it, which is where the doubt belongs.
_UNRESOLVED_VERBS = frozenset(_WRITE_VERBS)

# A subcommand the deny's hint may quote: the shape of a command or alias name,
# so a fragment torn from a quoted argument never reaches the reason.
_NAME_SHAPE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$")


class _CommandScope:
    """What classifying one command collects and reuses along the way."""

    def __init__(self, command: str = "") -> None:
        self.moves_exec_path = bool(_EXEC_PATH_TEXT.search(command))
        # The subcommands counted as both verbs, in the order first met.
        self.unknown: dict[str, None] = {}
        # Each substitution body's verbs at a depth, so the four readings of a
        # command, and their own readings of a nested body, classify it once
        # there (a body met at the depth cap is read more shallowly elsewhere).
        self.bodies: dict[tuple[str, int], set[str]] = {}


class _Lexer(shlex.shlex):
    """shlex.shlex with a token built in a list, so a long word lexes in
    linear time.

    The stdlib's read_token adds each character to the token with
    `self.token += nextchar`, and CPython copies the whole string for every
    such add to an attribute, so a word of n characters cost time in n
    squared: a Bash command holding one word of about 2.5 MB kept the guard
    past Claude Code's 600 s hook timeout, which under the guard item's
    `"onFailure": "block"` refuses the call. This read_token is the stdlib's
    (CPython 3.11 to 3.14 ship the same one), branch for branch, with the
    token kept as a list of characters and joined once at its end; only its
    debug prints are left out, since the guard never sets `debug`. Every
    other method is shlex's own, and the tests compare the two readings on
    generated text.
    """

    def read_token(self):  # noqa: C901, PLR0912  (the stdlib's state machine, kept whole)
        quoted = False
        escapedstate = " "
        token: list[str] = []
        while True:
            if self.punctuation_chars and self._pushback_chars:
                nextchar = self._pushback_chars.pop()
            else:
                nextchar = self.instream.read(1)
            if nextchar == "\n":
                self.lineno += 1
            if self.state is None:
                token = []  # past end of file
                break
            elif self.state == " ":
                if not nextchar:
                    self.state = None  # end of file
                    break
                elif nextchar in self.whitespace:
                    if token or (self.posix and quoted):
                        break  # emit current token
                    else:
                        continue
                elif nextchar in self.commenters:
                    self.instream.readline()
                    self.lineno += 1
                elif self.posix and nextchar in self.escape:
                    escapedstate = "a"
                    self.state = nextchar
                elif nextchar in self.wordchars:
                    token = [nextchar]
                    self.state = "a"
                elif nextchar in self.punctuation_chars:
                    token = [nextchar]
                    self.state = "c"
                elif nextchar in self.quotes:
                    if not self.posix:
                        token = [nextchar]
                    self.state = nextchar
                elif self.whitespace_split:
                    token = [nextchar]
                    self.state = "a"
                else:
                    token = [nextchar]
                    if token or (self.posix and quoted):
                        break  # emit current token
                    else:
                        continue
            elif self.state in self.quotes:
                quoted = True
                if not nextchar:  # end of file
                    raise ValueError("No closing quotation")
                if nextchar == self.state:
                    if not self.posix:
                        token.append(nextchar)
                        self.state = " "
                        break
                    else:
                        self.state = "a"
                elif self.posix and nextchar in self.escape and self.state in self.escapedquotes:
                    escapedstate = self.state
                    self.state = nextchar
                else:
                    token.append(nextchar)
            elif self.state in self.escape:
                if not nextchar:  # end of file
                    raise ValueError("No escaped character")
                # In posix shells, only the quote itself or the escape
                # character may be escaped within quotes.
                if escapedstate in self.quotes and nextchar != self.state and nextchar != escapedstate:
                    token.append(self.state)
                token.append(nextchar)
                self.state = escapedstate
            elif self.state in ("a", "c"):
                if not nextchar:
                    self.state = None  # end of file
                    break
                elif nextchar in self.whitespace:
                    self.state = " "
                    if token or (self.posix and quoted):
                        break  # emit current token
                    else:
                        continue
                elif nextchar in self.commenters:
                    self.instream.readline()
                    self.lineno += 1
                    if self.posix:
                        self.state = " "
                        if token or (self.posix and quoted):
                            break  # emit current token
                        else:
                            continue
                elif self.state == "c":
                    if nextchar in self.punctuation_chars:
                        token.append(nextchar)
                    else:
                        if nextchar not in self.whitespace:
                            self._pushback_chars.append(nextchar)
                        self.state = " "
                        break
                elif self.posix and nextchar in self.quotes:
                    self.state = nextchar
                elif self.posix and nextchar in self.escape:
                    escapedstate = "a"
                    self.state = nextchar
                elif (
                    nextchar in self.wordchars
                    or nextchar in self.quotes
                    or (self.whitespace_split and nextchar not in self.punctuation_chars)
                ):
                    token.append(nextchar)
                else:
                    if self.punctuation_chars:
                        self._pushback_chars.append(nextchar)
                    else:
                        self.pushback.appendleft(nextchar)
                    self.state = " "
                    if token or (self.posix and quoted):
                        break  # emit current token
                    else:
                        continue
        result = "".join(token)
        self.token = ""
        if self.posix and not quoted and result == "":
            result = None
        return result


def _tokenize(segment: str) -> list[str]:
    """Split one shell segment into words; raises ValueError on bad quoting.

    A named seam on purpose: it gives the fail-closed fallback below a single
    trigger to catch, instead of scattering shlex handling through the caller.
    It is shlex.split's own reading (posix, split at whitespace, no comments),
    through _Lexer, so a long word costs time linear in its length.
    """
    lexer = _Lexer(segment, posix=True)
    lexer.whitespace_split = True
    lexer.commenters = ""
    return list(lexer)


def _git_subcommand_index(tokens: list[str]) -> int | None:
    """Where the subcommand `git` would run sits among the tokens after `git`."""
    index = 0
    while index < len(tokens):
        token = tokens[index]
        if token in _GIT_VALUE_OPTIONS:
            index += 2  # skip the option AND its separate value
            continue
        if token.startswith("-"):
            index += 1
            continue
        return index
    return None


def _unknown_subcommand_verbs(name: str, scope: _CommandScope | None) -> set[str]:
    """Both verbs for `git <name> ...` when `name` is not one of git's own commands.

    Empty for a built-in command (_GIT_COMMANDS) and, while the command does
    not mention git's exec-path, for one git ships as a script there
    (_GIT_SCRIPT_COMMANDS). Anything else counts as both verbs and is recorded
    on the scope, when it has a name's shape, for the deny's hint.
    """
    if name in _GIT_COMMANDS:
        return set()
    if name in _GIT_SCRIPT_COMMANDS and not (scope and scope.moves_exec_path):
        return set()
    if scope is not None and _NAME_SHAPE.match(name):
        scope.unknown.setdefault(name, None)
    return set(_UNRESOLVED_VERBS)


def _substitution_bodies(text: str) -> list[str]:
    """The commands inside each `$(...)`, `<(...)`, `>(...)` and backtick pair.

    Text in single quotes is skipped, since the shell substitutes nothing
    there (`echo 'run `git ci` later'`), and so is a backslash-escaped
    character; double quotes do not stop a substitution. Parentheses are
    counted, not parsed, and a heredoc is read as plain text: a body that comes
    out wrong is classified anyway, which can only add verbs.
    """
    bodies: list[str] = []
    index = 0
    in_double = False
    while index < len(text):
        char = text[index]
        if char == "\\":
            index += 2
        elif char == "'" and not in_double:
            end = text.find("'", index + 1)
            index = len(text) if end == -1 else end + 1
        elif char == '"':
            in_double = not in_double
            index += 1
        elif text.startswith(("$(", "<(", ">("), index):
            start = index = index + 2
            level = 1
            while index < len(text) and level:
                if text[index] == "(":
                    level += 1
                elif text[index] == ")":
                    level -= 1
                index += 1
            bodies.append(text[start : index - 1 if level == 0 else index])
        elif char == "`":
            end = text.find("`", index + 1)
            end = len(text) if end == -1 else end
            bodies.append(text[index + 1 : end])
            index = end + 1
        else:
            index += 1
    return bodies


# shlex's punctuation mode yields a run of these characters as one token (a
# newline is one of them, so it ends a segment as it does in bash). The run is
# split into bash's own operators, longest first: a control operator ends a
# segment (`;`, `&&`, `|&`, a newline, the `()` of a function definition, a
# process substitution's `<(` or `>(`, so `true;>(git commit)` reads its
# body), and a redirection (`>&`, `>|`, `<<`) stays in the segment it opens,
# where _strip_leading_noise reads it.
_PUNCTUATION = "();<>|&\n"
_OPERATORS = (
    ";;&", "&>>", "<<<", "<<-", ";;", ";&", "&&", "||", "|&", "&>", ">>", ">&",
    "<&", ">|", "<>", "<<", "<(", ">(", ";", "&", "|", "<", ">", "(", ")", "\n",
)  # fmt: skip
_CONTROL_OPERATORS = frozenset(
    {";;&", ";;", ";&", "&&", "||", "|&", ";", "&", "|", "(", ")", "\n", "<(", ">("}
)


# Punctuation inside quotes, or escaped, is a word's text, not an operator, but
# shlex hands a quoted `')>'` back as `)>`, which reads as one. So it is masked
# before lexing, with a quote scan that follows shlex's own posix rules (a
# backslash escapes outside single quotes; single quotes take everything up to
# the next one; double quotes take an escaped character as it is), and unmasked
# in the tokens after.
_MASK_BASE = 0xE000


def _mask_quoted(text: str) -> str:
    """`text` with each punctuation character inside quotes or escaped masked.

    Unbalanced quotes leave the text as it is, for shlex to refuse.
    """
    out: list[str] = []
    index = 0
    size = len(text)

    def masked(char: str) -> str:
        return chr(_MASK_BASE + ord(char)) if char in _PUNCTUATION else char

    while index < size:
        char = text[index]
        if char == "\\" and index + 1 < size:
            out.append(char + masked(text[index + 1]))
            index += 2
        elif char == "'":
            end = text.find("'", index + 1)
            if end == -1:
                return text
            out.append("'" + "".join(masked(c) for c in text[index + 1 : end]) + "'")
            index = end + 1
        elif char == '"':
            end = index + 1
            body: list[str] = []
            while end < size and text[end] != '"':
                if text[end] == "\\" and end + 1 < size:
                    body.append(text[end] + masked(text[end + 1]))
                    end += 2
                else:
                    body.append(masked(text[end]))
                    end += 1
            if end >= size:
                return text
            out.append('"' + "".join(body) + '"')
            index = end + 1
        else:
            out.append(char)
            index += 1
    return "".join(out)


def _unmask(token: str) -> str:
    return "".join(
        chr(ord(c) - _MASK_BASE) if _MASK_BASE <= ord(c) < _MASK_BASE + 128 else c for c in token
    )


def _operators(token: str) -> list[str] | None:
    """A run of punctuation as bash's operators, longest first; None for a word."""
    if not token or not set(token) <= set(_PUNCTUATION):
        return None
    found: list[str] = []
    index = 0
    while index < len(token):
        operator = next(op for op in _OPERATORS if token.startswith(op, index))
        found.append(operator)
        index += len(operator)
    return found

# A heredoc's start, with its delimiter, quoted or not.
_HEREDOC_START = re.compile(r"<<-?[ \t]*(['\"]?)([A-Za-z_][A-Za-z0-9_]*)\1")


def _lexable(command: str) -> str:
    """The command with what shlex reads unlike bash taken out, for a reading
    of its own.

    A comment (a `#` that starts a word, outside quotes, up to its line's end),
    an ANSI-C string `$'...'`, whose backslash escapes shlex does not know and
    in which nothing is substituted (it becomes an empty word), and a heredoc's
    body (the lines up to its delimiter, which may hold any text, apostrophes
    included). The rest is copied as it is, quotes and escapes included, for
    shlex to read. Its reading of comments and heredocs is rough (a `#` after
    `$(...)`, a `<<` in arithmetic), and a misread takes out text bash runs, so
    this text is only ever read beside the command as it is
    (_command_write_verbs): it can add a reading, never replace one.
    """
    out: list[str] = []
    pending: list[str] = []  # heredoc delimiters whose bodies start at the next newline
    index = 0
    size = len(command)
    word_start = True
    while index < size:
        char = command[index]
        if char == "\\":
            out.append(command[index : index + 2])
            index += 2
            word_start = False
        elif command.startswith("$'", index):
            end = index + 2
            while end < size and command[end] != "'":
                end += 2 if command[end] == "\\" else 1
            out.append("''")
            index = end + 1
            word_start = False
        elif char in "'\"":
            end = index + 1
            while end < size and command[end] != char:
                end += 2 if char == '"' and command[end] == "\\" else 1
            out.append(command[index : end + 1])
            index = end + 1
            word_start = False
        elif char == "#" and word_start:
            end = command.find("\n", index)
            index = size if end == -1 else end
        elif command.startswith("<<", index) and not command.startswith("<<<", index):
            match = _HEREDOC_START.match(command, index)
            if match:
                pending.append(match.group(2))
                out.append(command[index : match.end()])
                index = match.end()
            else:
                out.append("<<")
                index += 2
            word_start = False
        elif char == "\n":
            out.append("\n")
            index += 1
            word_start = True
            for delimiter in pending:
                while index < size:
                    end = command.find("\n", index)
                    line = command[index : size if end == -1 else end]
                    index = size if end == -1 else end + 1
                    if line.lstrip("\t") == delimiter:
                        break
            pending.clear()
        else:
            out.append(char)
            index += 1
            word_start = char in " \t;&|()<>"
    return "".join(out)


def _quoted_segments(command: str) -> list[list[str]]:
    """The command's segments as quote-aware tokens, or none when it cannot be read.

    The quote-blind splits in _command_write_verbs tear a quoted `;`, `&&` or
    `|` apart (`git ci -m 'fix: a; b'`), and each fragment then tokenizes to
    nothing. shlex in punctuation mode keeps it inside its word.
    """
    lexer = _Lexer(_mask_quoted(command), posix=True, punctuation_chars=_PUNCTUATION)
    lexer.whitespace = " \t\r"  # a newline is punctuation, so it ends a segment
    lexer.whitespace_split = True
    lexer.commenters = ""  # shlex would start one mid-word; bash does not
    try:
        tokens = list(lexer)
    except ValueError:
        return []
    segments: list[list[str]] = [[]]
    for token in tokens:
        operators = _operators(token)
        if operators is None:
            segments[-1].append(_unmask(token))
            continue
        for operator in operators:
            if operator in _CONTROL_OPERATORS:
                segments.append([])
            else:
                segments[-1].append(operator)
    return [segment for segment in segments if segment]


def _shell_payload_verbs(
    tokens: list[str], depth: int, scope: _CommandScope | None = None
) -> set[str] | None:
    """Verbs written by the string payload of a `sh -c '…'`-style invocation.

    Returns ``None`` — not an empty set — when the payload cannot be located at
    all, so the caller can fall back to the anywhere-scan instead of reading
    "no payload found" as "no git write here". A LISTED shell wrapper failing
    open is not part of the accepted residual (an UNLISTED one is; see
    test_unlisted_wrapper_is_an_accepted_fail_open), and every other lane that
    cannot honestly read a segment — unbalanced quotes, `$(…)`/backticks —
    already biases toward the deny. This one now matches them.
    """
    if depth >= _MAX_SHELL_DEPTH:
        # The cap is a recursion bound, not a verdict: refusing to look deeper
        # is exactly the "cannot read it" case, so it fails closed too, and a
        # `git` in what it cannot read counts as both verbs (the
        # matches-anywhere scan knows only the literal verbs, not an alias).
        return set(_UNRESOLVED_VERBS) if any(_GIT_WORD.search(t) for t in tokens) else None
    for index, token in enumerate(tokens):
        if _PAYLOAD_FLAG.match(token) and index + 1 < len(tokens):
            return _command_write_verbs(tokens[index + 1], depth + 1, scope)
    return None


def _strip_leading_noise(tokens: list[str]) -> list[str]:
    """Drop leading `VAR=val` assignments, shell keywords, group openers and
    redirections.

    Applied repeatedly because they nest: `if ! FOO=1 git commit …` puts three
    different kinds of noise ahead of the verb. A name after `function`, or
    after `coproc` ahead of a group, names the function, not a command; a
    redirection ahead of the command (`>/dev/null git commit`, `2>&1 git
    commit`, `> out git commit`) is no command either. Every strip here can
    only turn an unclassifiable segment into a classifiable one, so this
    direction is fail-closed by construction.

    One pass over the words, moving an index and copying the rest once: a copy
    per word dropped took time quadratic in a long run of them (a segment that
    opens with thousands of `!`), and a hook past its timeout lets the call
    through.
    """
    index, size = 0, len(tokens)
    # The word at `index`, less any group opener a strip took off its front.
    head = tokens[0] if tokens else ""
    while index < size:
        left = size - index
        bare = head.lstrip(_GROUP_OPENERS)
        redirect = _REDIRECTION.match(head)
        if _ASSIGNMENT.match(head):
            index += 1
        elif bare != head:
            # `(git commit …)`: an opener glued to the command name.
            if bare:
                head = bare
                continue
            index += 1
        elif head == "function" and left > 1:
            index += 2
        elif head == "coproc" and left > 2 and tokens[index + 2] in ("{", "("):
            index += 2
        elif head.lower() in _SHELL_KEYWORDS:
            index += 1
        elif redirect:
            # An operator alone (`>`, `2>&`) takes the next word as its
            # target, unless that word is `git`: a quoted punctuation word
            # (`exec -a ')>' git ci`) reads as an operator here, and the
            # git after it must not be taken for its target.
            alone = redirect.end() == len(head)
            target_is_git = alone and left > 1 and os.path.basename(tokens[index + 1]).lower() == "git"
            index += 2 if alone and not target_is_git else 1
        elif head.isdigit() and left > 1 and _REDIRECTION.match(tokens[index + 1]):
            index += 1  # the descriptor of `2 >&1`, split by the quote-aware reading
        else:
            break
        head = tokens[index] if index < size else ""
    rest = tokens[index:]
    if rest and rest[0] != head:
        rest[0] = head
    return rest


def _token_write_verbs(
    tokens: list[str], depth: int, scope: _CommandScope | None = None
) -> set[str] | None:
    """Classify one tokenized segment: which write verbs would it actually run?

    ``None`` propagates the "cannot honestly read this" signal up to
    :func:`_segment_write_verbs`, which owns the raw segment the fallback needs.

    A loop, not a recursion, over the exec wrappers ahead of the head, and a
    bounded one, as _segment_rebinds bounds its own: a run of a thousand
    wrappers overflowed Python's recursion limit, and a hook that exits on an
    exception makes no decision, so the command went through. Past
    _MAX_WRAPPERS wrappers the reading stops, and the segment counts as both
    verbs whatever follows: a search of the unread words for a `git` would
    miss one that bash spells only once it removes quotes (`bash -c 'g""it
    commit'`, `G''IT commit`), which reading them finds.
    """
    wrappers = 0
    while True:
        tokens = _strip_leading_noise(tokens)
        if not tokens:
            return set()
        head = os.path.basename(tokens[0]).lower()
        if head == "git":
            index = _git_subcommand_index(tokens[1:])
            if index is None:
                return set()
            if tokens[1 + index].lower() in _WRITE_VERBS:
                return {tokens[1 + index].lower()}
            return _unknown_subcommand_verbs(tokens[1 + index], scope)
        if head in _SHELL_WRAPPERS:
            return _shell_payload_verbs(tokens[1:], depth, scope)
        if head == "eval":
            # `eval` runs its arguments, joined, as a command of its own, after a
            # `--` it skips.
            if depth >= _MAX_SHELL_DEPTH:
                return set(_UNRESOLVED_VERBS) if any(_GIT_WORD.search(t) for t in tokens) else None
            args = tokens[2:] if tokens[1:2] == ["--"] else tokens[1:]
            return _command_write_verbs(" ".join(args), depth + 1, scope)
        if head not in _EXEC_WRAPPERS:
            return set()
        wrappers += 1
        if wrappers > _MAX_WRAPPERS:
            return set(_UNRESOLVED_VERBS)
        # Every wrapper has its own option grammar (`timeout 30 …`, `nice -n 10
        # …`, `sudo -u u …`, `stdbuf -oL …`), and modelling them one by one is
        # exactly how a LISTED wrapper turns into a fail-open. So read the rest
        # of the segment again from the first token that could start a command,
        # biased toward finding the git, not toward parsing the wrapper.
        for index in range(1, len(tokens)):
            name = os.path.basename(tokens[index]).lower()
            if name in ("git", "eval") or name in _SHELL_WRAPPERS or name in _EXEC_WRAPPERS:
                tokens = tokens[index:]
                break
        else:
            return set()


def _anywhere_write_verbs(segment: str) -> set[str]:
    """Fail-closed fallback: the legacy scan for the verb anywhere in a segment."""
    match = _GIT_WRITE_ANYWHERE.search(segment)
    return {match.group("verb").lower()} if match else set()


def _body_verbs(segment: str, depth: int, scope: _CommandScope | None) -> set[str]:
    """The write verbs of each substitution body in the segment, each read as a
    command of its own, once per body and depth; past the depth cap, both verbs
    for a `git` the guard cannot read deeper."""
    if depth >= _MAX_SHELL_DEPTH:
        return set(_UNRESOLVED_VERBS) if _GIT_WORD.search(segment) else set()
    verbs: set[str] = set()
    for body in _substitution_bodies(segment):
        if scope is None:
            verbs |= _command_write_verbs(body, depth + 1, scope)
            continue
        key = (body, depth)
        if key not in scope.bodies:
            scope.bodies[key] = set()  # a body that holds itself stops here
            scope.bodies[key] = _command_write_verbs(body, depth + 1, scope)
        verbs |= scope.bodies[key]
    return verbs


def _without_comments(segment: str) -> str:
    """The segment with its line continuations joined and each line's trailing
    `#` comment, and a trailing backslash, taken out. Read quote-blind, so it
    can cut a quoted `#` too: it is only ever an extra reading."""
    lines = segment.replace("\\\n", " ").split("\n")
    return "\n".join(re.sub(r"(^|\s)#.*$", r"\1", line) for line in lines).rstrip().rstrip("\\")


def _uncommented_verbs(segment: str, depth: int, scope: _CommandScope | None) -> set[str]:
    """The verbs of the segment read without its comments, when it does not
    tokenize as it is: an apostrophe in a trailing comment (`git ci # it's`)
    leaves no tokens, and the matches-anywhere scan knows no alias."""
    stripped = _without_comments(segment)
    if stripped == segment:
        return set()
    try:
        tokens = _tokenize(stripped)
    except ValueError:
        return set()
    return _token_write_verbs(tokens, depth, scope) or set()


def _segment_write_verbs(segment: str, depth: int, scope: _CommandScope | None = None) -> set[str]:
    if any(marker in segment for marker in _SUBSTITUTION_MARKERS):
        # The real command hides inside the substitution; anchoring would read
        # the outer word and allow it. Fall back rather than fail open. Each
        # substitution's body is classified as a command of its own, and the
        # outer words too where they tokenize, so a git alias inside one
        # (`echo "$(git ci)"`) or around one (`git ci -m "$(date)"`) is seen.
        verbs = _anywhere_write_verbs(segment) | _body_verbs(segment, depth, scope)
        try:
            tokens = _tokenize(segment)
        except ValueError:
            return verbs | _uncommented_verbs(segment, depth, scope)
        return verbs | (_token_write_verbs(tokens, depth, scope) or set())
    # An output process substitution's body is a command too. It is read on its
    # own, not through the matches-anywhere scan, which would deny a read whose
    # words name a verb (`git log --grep=push > >(cat)`).
    verbs = _body_verbs(segment, depth, scope) if ">(" in segment else set()
    try:
        tokens = _tokenize(segment)
    except ValueError:
        # Unbalanced quotes: there are no trustworthy tokens, so fall back to
        # the legacy scan rather than wave the segment through, and read the
        # segment once more without its comments. Letting the exception escape
        # would exit non-zero, which is neither a clean allow nor a clean deny.
        return verbs | _anywhere_write_verbs(segment) | _uncommented_verbs(segment, depth, scope)
    found = _token_write_verbs(tokens, depth, scope)
    if found is None:
        # A listed shell wrapper whose payload could not be located. Same
        # treatment as the two lanes above: scan the raw segment rather than
        # let an unreadable invocation classify as carrying no write.
        return verbs | _anywhere_write_verbs(segment)
    return verbs | found


def _command_write_verbs(command: str, depth: int, scope: _CommandScope | None = None) -> set[str]:
    verbs: set[str] = set()
    # Classified under BOTH separator sets, unioned. Neither alone is safe:
    #
    #   - Without the newline, `printf ok > .tests-ran-1\ngit commit -m x` is one
    #     segment led by `printf`, which anchors to nothing and waves through a
    #     real commit — bypassing the protected-branch, tests-ran, freshness AND
    #     empty-index gates in a single Bash call.
    #   - With ONLY the newline set, the split is quote-blind, so a newline inside
    #     a quoted argument that sits between `git` and its verb
    #     (`git -c foo.bar="a\nb" commit -m x`, and every other
    #     `_GIT_VALUE_OPTIONS` form) tears the command into two fragments that
    #     each fail to tokenize and each miss the newline-anchored fallback
    #     regex — a real commit, allowed.
    #
    # Unioning makes the result a strict SUPERSET of what the separator-only set
    # detects, so this cannot classify less than it did before the newline was
    # added. That property is what is being bought here, and it is why this is a
    # union rather than one cleverer regex: a quote-aware splitter would be a
    # second hand-rolled shell parser whose every disagreement with `shlex` is a
    # new fail-open, and getting it wrong in the do-not-split direction silently
    # restores the newline bypass above.
    #
    #   - Neither of those two sets matches a LONE `&`, which is a real bash
    #     separator (background-then-continue), so `npm run build & git commit`
    #     stayed ONE segment led by `npm` and was waved through. It gets its own
    #     set rather than an `&` bolted onto the two above, for the same reason
    #     the newline did: splitting on `&` is quote-blind too, so
    #     `git -c a.b='x&y' commit -m z` would tear into two fragments that each
    #     fail to tokenize AND each miss the fallback regex (fragment one has no
    #     verb, fragment two has no `git`) — turning a deny into an allow. Added
    #     as a third member of the union, it can only ever classify MORE.
    #
    # The `\|\|` alternative must precede `\|` so `||` is consumed whole, and
    # `&&` must precede `&` for the same reason. `\r` rides along with `\n` for
    # CRLF-authored commands.
    for separators in (
        r"&&|\|\||;|\|",
        r"&&|\|\||;|\||\n|\r",
        r"&&|\|\||;|\||&|\n|\r",
    ):
        for segment in re.split(separators, command):
            verbs |= _segment_write_verbs(segment, depth, scope)
    # Quote-aware readings join the union: they keep a quoted separator inside
    # its word (`git ci -m 'fix: a; b'`), which the three quote-blind splits
    # tear into fragments that classify as nothing, and like them they can
    # only add verbs. One reads the command as it is; the other reads it with
    # what shlex cannot lex taken out (_lexable: a comment holding an
    # apostrophe, `$'...'`, a heredoc body), and adds to the first, never
    # replaces it. A text shlex cannot read adds none.
    lexable = _lexable(command)
    for text in (command,) if lexable == command else (command, lexable):
        for tokens in _quoted_segments(text):
            verbs |= _token_write_verbs(tokens, depth, scope) or set()
    return verbs


def _classify(command: str) -> tuple[set[str], list[str]]:
    """The {'commit','push'} subset the command would perform, and the git
    subcommands that are not git's own it counted as both, for the git gates'
    deny hint (_unknown_hint)."""
    scope = _CommandScope(command)
    return _command_write_verbs(command, 0, scope), list(scope.unknown)


def _git_writes(command: str) -> set[str]:
    """Return the {'commit','push'} subset the command would perform.

    Classifies each shell segment independently, so a chained
    `git add && git commit` is still caught. A git subcommand that is not one
    of git's own counts as both (_unknown_subcommand_verbs).
    """
    return _classify(command)[0]


def _unknown_hint(names: list[str]) -> str:
    """The note a git gate's deny adds when the command runs a subcommand that
    is not git's own: it may be why the command was denied, and what to do."""
    if not names:
        return ""
    shown = ", ".join(f"`git {name}`" for name in names[:3])
    return (
        f" Note: this command runs {shown}, which is not one of git's built-in "
        "commands, so this guard counts it as a commit and a push: it cannot tell "
        "what an alias runs. If that is why it was denied, run the git command an "
        "alias stands for, or an external command by its own name (`git-lfs pull` "
        "for `git lfs pull`)."
    )


# --- Marker freshness -------------------------------------------------------
# A tests-ran marker proves that a suite once ran green. Nothing in a bare
# existence check stops that marker from being REPLAYED: written against an
# earlier code state, or left over from a previous story, it satisfies the check
# forever. So the marker carries the commit the story started from, and this
# clause requires it to equal the SHA the story recorded.
#
# Both sides are read as strings from files that already exist for other
# reasons, so this costs two file reads and one comparison — no `git rev-parse`.
# That is not an optimization: recomputing the SHA here would compare against a
# HEAD that has already moved on any story that commits more than once, and
# would deny its second commit. Read, never derive.

_MARKER_BASELINE_RE = re.compile(r"^baseline=(.*)$", re.MULTILINE)


def _marker_baseline_sha(marker: Path) -> str | None:
    """The SHA on the marker's FIRST `baseline=` line, whitespace-stripped.

    None when the marker cannot be read at all or carries no such line — both
    of which the caller treats as a deny, not as "check not applicable".
    """
    try:
        text = marker.read_text(encoding="utf-8")
    except (OSError, UnicodeDecodeError):
        return None
    match = _MARKER_BASELINE_RE.search(text)
    return match.group(1).strip() if match else None


def _recorded_baseline_sha(baseline: Path) -> str | None:
    """The story's recorded baseline SHA, read verbatim off its own file.

    Deliberately NOT `git rev-parse HEAD`: the story is anchored to where it
    started, and HEAD walks away from that as soon as the story's first commit
    lands.
    """
    try:
        return baseline.read_text(encoding="utf-8").strip() or None
    except (OSError, UnicodeDecodeError):
        return None


def _marker_freshness_gate(marker: Path, baseline: Path) -> None:
    """Deny a commit whose tests-ran marker was not written for this baseline.

    Fail closed on both absences. There is no inert path here (unlike the
    un-skip proof's unset-env case): a marker that cannot be tied to a baseline
    is exactly the replayed marker this clause exists to refuse, so "cannot
    tell" and "does not match" get the same answer.
    """
    marker_sha = _marker_baseline_sha(marker)
    if marker_sha is None:
        _deny(
            "Marker-freshness guard: refusing `git commit` — the tests-ran "
            f"marker {marker} carries no `baseline=<sha>` line, so it cannot be "
            f"tied to the commit this story started from ({baseline}) and may "
            "be a marker replayed from an earlier code state. Failing closed. "
            "Re-run the story's test/lint/build to green, then rewrite "
            f"{marker} with a `baseline=<sha>` line copied verbatim from "
            f"{baseline}, then commit. The rewrite must be its own, prior tool "
            "call: this guard pre-evaluates the command string, so a marker "
            "written in the same compound command as the commit does not exist "
            "yet when the commit is evaluated."
        )
    baseline_sha = _recorded_baseline_sha(baseline)
    if baseline_sha is None:
        _deny(
            "Marker-freshness guard: refusing `git commit` — this story's "
            f"recorded baseline {baseline} is missing or unreadable, so the "
            f"tests-ran marker {marker} cannot be checked against it. Failing "
            "closed. If this story has already committed, restore that file "
            "(the full 40-hex commit this story started from, one line); if it "
            "has not yet committed — a fresh story at a resume boundary never "
            "had one — write it now from `git rev-parse HEAD` exactly as step 0 "
            "does. Then re-run the story's test/lint/build to green, rewrite "
            f"{marker} with a `baseline=<sha>` line copied verbatim from it, "
            "and commit — each write its own, prior tool call, never chained "
            "into the commit command."
        )
    if marker_sha != baseline_sha:
        _deny(
            "Marker-freshness guard: refusing `git commit` — the tests-ran "
            f"marker {marker} records baseline={marker_sha}, but this story's "
            f"recorded baseline {baseline} is {baseline_sha}. The marker was "
            "written against a different code state, so it proves nothing "
            "about the tree being committed now. Re-run the story's "
            f"test/lint/build to green, then rewrite {marker} with a "
            f"`baseline=<sha>` line copied verbatim from {baseline} (copied, "
            "never re-derived from `git rev-parse HEAD` — the baseline does "
            "not move while the story runs), then commit. The rewrite must be "
            "its own, prior tool call: the guard pre-evaluates the command "
            "string, so a marker written in the same compound command as the "
            "commit does not exist yet when the commit is evaluated."
        )


# --- Un-skip proof ----------------------------------------------------------
# In production the story's atdd-checklist is the ground truth for which files
# carry its acceptance tests. This clause reads the STAGED post-image of each of
# them and refuses a commit that would capture a still-skipped acceptance test.
# It asserts absence in the blob being committed, so it holds on a story's first
# commit as well as on later ones; it is not a diff of "was the marker removed".

_SKIP_TOKEN = "test.skip("

# Path-shaped tokens naming a JS/TS acceptance-test file. Deliberately loose on
# the leading segment ({project-root}/…, an absolute path, a bare relative one)
# and strict on the extension, so prose around the paths is not mistaken for one.
_TEST_FILE = re.compile(
    r"""[^\s`'"()\[\],]+\.(?:spec|test)\.(?:[cm]?[jt]sx?)\b"""
)


def _checklist_test_files(text: str) -> list[str]:
    """Every acceptance-test path the checklist names, in order, deduplicated."""
    found: list[str] = []
    for match in _TEST_FILE.finditer(text):
        token = match.group(0)
        if token not in found:
            found.append(token)
    return found


# TEA's ATDD writes the test files it scaffolded to the checklist's
# `generatedTestFiles` frontmatter (step-04c sets it, step-05 keeps it). Its
# prose and tables also cite files the story only read (`inputDocuments`), bare
# `file::case` references, globs and partial paths, none of which `git show :`
# can read, so when that list names a test file it is the whole set. A
# checklist with no such list (hand-written, or older) is scanned whole, as is
# one whose list names no JS/TS test file (TEA starts it as `[]`).
_LISTED_KEY = re.compile(r"generatedTestFiles\s*:(.*)$")


def _strip_comment(
    line: str, quote: str = "", depth: int = 0, start: bool = True
) -> tuple[str, str, int, bool]:
    """`line` up to its YAML comment, the quote still open at its end, and how
    many `[` or `{` collections are still open there.

    A `#` starts a comment at the start of the line or after whitespace, and
    only outside a single- or double-quoted scalar, so the `#3` of
    `['a.spec.ts (AC #3)', 'b.spec.ts']` cuts off neither the rest of its
    entry nor the entry after it. A quote opens a scalar only where one may
    start: at the start of the line, after a `- `, `? ` or `: ` indicator, or
    inside a `[` or `{` collection after its opening bracket or a `,`. So the
    `'` of a plain `it's`, or of a plain block entry's `(AC 2, 'til done)`,
    opens nothing. `quote` and `depth` are what the line before left open,
    since a quoted scalar or a collection may run over lines.
    """
    # whether a scalar may start here; inside a flow collection a line break
    # is only whitespace, so the line before decides it
    start = not quote and (start or depth == 0)
    i = 0
    while i < len(line):
        char = line[i]
        if quote:
            if char == "\\" and quote == '"':
                i += 1  # an escaped character, such as \"
            elif char == quote == "'" and line[i + 1:i + 2] == "'":
                i += 1  # '' is a quote inside a single-quoted scalar
            elif char == quote:
                quote = ""
        elif char == "#" and (i == 0 or line[i - 1].isspace()):
            return line[:i], "", depth, start
        elif char in "'\"" and start:
            quote, start = char, False
        elif char in "&!" and start:
            while i + 1 < len(line) and not line[i + 1].isspace():
                i += 1  # a node property: a node may still start after it
        elif not char.isspace():
            spaced = i + 1 == len(line) or line[i + 1].isspace()
            indicator = spaced and (char == ":" or (start and char in "-?"))
            opens = char in "[{" and (start or depth > 0)
            if opens:
                depth += 1
            elif char in "]}" and depth:
                depth -= 1
            start = opens or (char == "," and depth > 0) or indicator
        i += 1
    return line, quote, depth, start


def _listed_test_files(text: str) -> list[str] | None:
    """The acceptance-test paths the checklist's `generatedTestFiles` lists.

    None when the checklist has no frontmatter or its frontmatter has no such
    key. Raises ValueError, saying what is wrong, when the key is there but its
    value is not a list this reader can take apart: `- ` items on the lines
    under it, or a `[...]` list on one line or several. Comments are cut off
    as _strip_comment reads them, so a `#` in a quoted note keeps the rest of
    its line, and a line a quoted entry or an open `[` list runs onto, even at
    column 0, continues it. Entries go through _TEST_FILE, so a listed source file, a Rust
    test or a note in parentheses after a path is not read as an
    acceptance-test file.
    """
    lines = text.lstrip("\ufeff").splitlines()
    if not lines or lines[0].rstrip() != "---":
        return None
    end = next(
        (i for i in range(1, len(lines)) if lines[i].rstrip() in ("---", "...")),
        None,
    )
    if end is None:
        return None
    block = lines[1:end]
    keys = [i for i, line in enumerate(block) if _LISTED_KEY.match(line)]
    if not keys:
        return None
    if len(keys) > 1:
        raise ValueError("the key appears more than once")
    key_line, quote, depth, start = _strip_comment(block[keys[0]])
    inline = _LISTED_KEY.match(key_line).group(1).strip()
    items: list[str] = []
    for line in block[keys[0] + 1:]:
        carried, nested = quote, depth
        item, quote, depth, start = _strip_comment(line, quote, depth, start)
        item = item.strip()
        if not item:
            continue
        if carried and items:
            items[-1] += " " + item  # the quoted entry the line before left open
            continue
        if not line[0].isspace() and not nested and not item.startswith(("-", "]")):
            break  # the next key; a `- ` item, a `]` or a line in an open list may sit at column 0
        items.append(item)
    if inline or (items and items[0].startswith("[")):
        flow = " ".join([inline, *items]).strip()
        if not flow.startswith("["):
            raise ValueError("its value is not a list")
        if not flow.endswith("]"):
            raise ValueError("its `[` list is not closed by `]`")
        return _checklist_test_files(flow[1:-1])
    if any(not item.startswith("-") for item in items):
        raise ValueError("a line under it is not a `- ` item")
    return _checklist_test_files("\n".join(item[1:] for item in items))


def _repo_relative(raw: str, cwd: str | None) -> str:
    """Normalize a checklist entry to the repo-relative form `git show :` needs.

    Checklist entries may be `{project-root}`-prefixed or absolute; `git show :`
    accepts neither. Anything that still cannot be made repo-relative is passed
    through unchanged so the read fails loudly rather than being skipped.
    """
    text = raw.replace("\\", "/")
    if "{project-root}" in text:
        return text.split("{project-root}", 1)[1].lstrip("/")
    if text.startswith("./"):
        text = text[2:]
    if text.startswith("/") and cwd:
        try:
            return str(Path(text).relative_to(Path(cwd)))
        except ValueError:
            return text
    return text


def _staged_blob(path: str, cwd: str | None) -> tuple[bool, str]:
    """Return (readable, staged content) for one path via `git show :<path>`.

    `:<path>` addresses the index, i.e. the bytes this commit would write for
    a staged path. An intent-to-add entry is the exception: it reads as the
    empty blob with exit 0, and the commit leaves it out, so _git_write_gates
    refuses any commit while the index holds one before this read runs.
    readable is False when the probe could not answer at all (git missing,
    timeout, path not in the index): the caller fails closed on it.
    """
    try:
        out = subprocess.run(
            ["git", "show", f":{path}"],
            cwd=cwd or None,
            capture_output=True,
            text=True,
            timeout=10,
        )
    except (OSError, subprocess.SubprocessError, UnicodeDecodeError):
        return False, ""
    if out.returncode != 0:
        return False, ""
    return True, out.stdout


def _unskip_gate(cwd: str | None, story: str | None) -> None:
    """Deny a commit whose staged acceptance tests still carry the skip marker.

    Scope, in order:
      - test-artifacts root unresolvable (env unset) -> out of scope, note only.
      - no story id -> nothing to look up.
      - no checklist for this story -> inert. That is the `--light` profile,
        where acceptance tests are not generated at all.
      - checklist present but unreadable -> deny (in scope, cannot verify).
      - `generatedTestFiles` present but not readable as a list -> deny.
      - checklist naming no acceptance-test file -> inert. Doc-only and refactor
        stories are legitimate and must not be blocked.
    The files are the JS/TS test paths `generatedTestFiles` lists, or, when it
    is absent or lists none, every such path the checklist's text names.
    Every enumerated file is read from the index whether or not this commit
    touched it: the checklist, not the diff, says what the story must deliver.
    """
    tests_root = _test_artifacts()
    if tests_root is None:
        _note(
            "Un-skip proof: ULTRACODE_TEST_ARTIFACTS is unset, so the staged "
            "acceptance-test check is out of scope for this commit and made no "
            "decision. Inject it on the guard's hook command (preflight step 5) "
            "to arm the check."
        )
        return
    if not story:
        return

    checklist = tests_root / f"atdd-checklist-{story}.md"
    if not checklist.is_file():
        return  # no acceptance tests for this story: nothing to prove
    try:
        text = checklist.read_text(encoding="utf-8")
    except (OSError, UnicodeDecodeError):
        _deny(
            "Un-skip proof: refusing `git commit` — the acceptance-test "
            f"checklist {checklist} exists but could not be read, so the staged "
            "acceptance tests cannot be verified un-skipped. Failing closed. "
            "Repair or regenerate the checklist, then commit."
        )

    try:
        listed = _listed_test_files(text)
    except ValueError as problem:
        _deny(
            "Un-skip proof: refusing `git commit` because the `generatedTestFiles` "
            f"list in the frontmatter of {checklist} cannot be read ({problem}), "
            "so the story's acceptance-test files cannot be enumerated. Failing "
            "closed. Rewrite it as a YAML list, one repo-relative path per "
            "`- '<path>'` line, in a prior, SEPARATE tool call, then commit."
        )
    source = (
        f"the generatedTestFiles list of {checklist.name}" if listed else checklist.name
    )
    entries = listed or _checklist_test_files(text)
    files = [_repo_relative(entry, cwd) for entry in entries]
    if not files:
        return  # checklist names no acceptance-test file (doc-only story)

    still_skipped: list[str] = []
    for rel in files:
        readable, blob = _staged_blob(rel, cwd)
        if not readable:
            _deny(
                "Un-skip proof: refusing `git commit` — `git show :"
                f"{rel}` failed, so the staged content of an acceptance-test "
                f"file named by {source} could not be read. Failing "
                "closed. Stage that file (`git add <path>`) in a prior, "
                "SEPARATE tool call, or fix the path the checklist names."
            )
        if _SKIP_TOKEN in blob:
            still_skipped.append(rel)
    if still_skipped:
        _deny(
            "Un-skip proof: refusing `git commit` — the staged content of "
            f"{', '.join(still_skipped)} still contains `{_SKIP_TOKEN}`, so this "
            "commit would capture a story whose acceptance tests are skipped "
            "rather than green. Un-skip every acceptance test the checklist "
            f"({checklist.name}) enumerates, drive them to green, restage those "
            "paths in a prior, SEPARATE tool call, then commit."
        )


# --- Cross-Session Recall gate ----------------------------------------------
# While a UCG run is active, nothing reaches claude-mem, and only the pinned
# recall scripts reach the local run store or change the latch. The run is
# signalled by a machine latch written at Stage 1 Ingest and removed at every
# terminal (Finalize, a preflight STOP, the headless envelope path) by
# `mem_recall.py unlatch`. Its presence arms this gate, not any env flag and
# not its colour: a present latch counts as live. The guard reads no clock and
# detects no dead run, so a latch a dead run left behind keeps denying until
# the next Stage 1 replaces it or the user deletes it by hand, and every deny
# it causes names it and tells the person how to clear it.

_MEM_STATE_FILENAME = ".mem-state.json"

# A claude-mem MCP call is one of two segment-exact forms:
#   plugin-install form: mcp__plugin_claude-mem_<server-seg>__<op>
#       the trailing '_' after 'plugin_claude-mem' blocks plugin_claude-memoir_*
#   bare-server form:    mcp__claude-mem__<op>  (also claude_mem; exact segment)
# Claude Code writes `_` in a tool name for any character of the server name
# outside letters, digits, `_` and `-` (_MCP_NAME_UNSAFE), so the plugin's
# server segment may hold a `_` (a server key `mem.search` or `mem_search`).
# Case-exact on purpose (real tool names are lowercase); missing/empty -> no match.
_CLAUDE_MEM_SERVER_NAME = r"(?:plugin_claude-mem_[A-Za-z0-9_-]+|claude[-_]mem)"
_CLAUDE_MEM_TOOL = re.compile(rf"^mcp__{_CLAUDE_MEM_SERVER_NAME}__.+$")
_MCP_NAME_UNSAFE = re.compile(r"[^A-Za-z0-9_-]")


# The client's own MCP resource tools reach a server named in their `server`
# input rather than in the tool name. That input is the server's own name,
# `plugin:claude-mem:<server>` for the plugin install, so it is matched as the
# tool name spells it: a server whose tools the form above denies is
# claude-mem's. A listing that names no server lists every server's resources,
# claude-mem's included.
_MCP_RESOURCE_TOOLS = frozenset(
    {"ListMcpResourcesTool", "ReadMcpResourceTool", "ReadMcpResourceDirTool"}
)
_MCP_LIST_RESOURCES = "ListMcpResourcesTool"
_CLAUDE_MEM_SERVER = re.compile(rf"^{_CLAUDE_MEM_SERVER_NAME}$")


def _mem_state_path(impl: Path | None) -> Path | None:
    return (impl / _MEM_STATE_FILENAME) if impl is not None else None


def _is_claude_mem_tool(tool_name: object) -> bool:
    """True iff tool_name is a claude-mem MCP call (segment-exact dual form)."""
    if not isinstance(tool_name, str) or not tool_name:
        return False
    return _CLAUDE_MEM_TOOL.match(tool_name) is not None


def _claude_mem_resource_server(tool_name: object, tool_input: dict) -> str | None:
    """The claude-mem server an MCP resource read or listing names, or None."""
    if tool_name not in _MCP_RESOURCE_TOOLS:
        return None
    server = tool_input.get("server")
    if isinstance(server, str) and _CLAUDE_MEM_SERVER.match(_MCP_NAME_UNSAFE.sub("_", server)):
        return server
    return None


# --- The latch, read the way lib/mem_common.py reads it ----------------------
# This hook imports nothing from lib/ (module docstring), so it keeps its own
# copy of mem_common.read_state() and mem_common.latch_view(). The two must
# read one latch file the same way: the parity test in test_guard_pretooluse.py
# drives both over one corpus of latch files, resolved store path included, so
# a change to either side reds until it is made to both.

_LATCH_V2 = 2
_STORE_BACKEND = "jsonl"

# A real latch is a few hundred bytes. The latch is opened without blocking (a
# FIFO there would otherwise hold this read until the hook timed out) and a
# latch past this size reads as unreadable. Only a hostile file differs from
# mem_common.read_state() here, which would block or read on.
_LATCH_READ_CAP = 1 << 20


def _latch_present(state_path: Path) -> bool:
    """True when anything sits at the latch path, or when that cannot be told.

    Only a clean "no such file" reads as absent (no active run). Any other
    failure to look may hide a latch, so it reads as present: fail closed. A
    present latch that cannot be read or parsed still arms the claude-mem deny.
    """
    try:
        os.lstat(state_path)
    except (FileNotFoundError, NotADirectoryError):
        return False
    except (OSError, ValueError):
        return True
    return True


def _read_latch(state_path: Path) -> dict | None:
    """mem_common.read_state(): the latch object, or None. Never raises.

    Missing, unreadable, blank, unparseable and non-object latches all read as
    None. It also swallows the errors a hostile path can raise (a NUL in the
    path, a folder), opens the latch without blocking and reads at most
    _LATCH_READ_CAP bytes: an exception or a hang here would end with no
    decision at all.
    """
    flags = os.O_RDONLY | getattr(os, "O_NONBLOCK", 0) | getattr(os, "O_BINARY", 0)
    try:
        fd = os.open(state_path, flags)
    except (OSError, ValueError):
        return None
    try:
        chunks: list[bytes] = []
        size = 0
        while size <= _LATCH_READ_CAP:
            chunk = os.read(fd, _LATCH_READ_CAP + 1 - size)
            if not chunk:
                break
            chunks.append(chunk)
            size += len(chunk)
    except OSError:
        return None
    finally:
        os.close(fd)
    if size > _LATCH_READ_CAP:
        return None
    text = b"".join(chunks).decode("utf-8", errors="replace")
    if not text.strip():
        return None
    try:
        data = json.loads(text)
    except (ValueError, RecursionError):
        return None
    return data if isinstance(data, dict) else None


def _is_int(value: object) -> bool:
    """True for a real int (bool is an int subclass and is not one here)."""
    return isinstance(value, int) and not isinstance(value, bool)


def _latch_store_path(value: object) -> Path | None:
    """mem_common._latch_store_path(): a latch's `store` as an absolute path.

    Taken as written (the latch holds the resolved root, which may carry a
    `$` or braces of its own); only a leading `~` is expanded. Anything that is
    not then absolute, a string holding a NUL, or a non-string reads as None.
    """
    if not isinstance(value, str) or not value or "\0" in value:
        return None
    try:
        path = Path(value).expanduser() if value.startswith("~") else Path(value)
        if not path.is_absolute():
            return None
        return Path(os.path.abspath(path))
    except (RuntimeError, ValueError):
        return None


def _latch_view(state: object) -> dict:
    """mem_common.latch_view(): how a latch reads, version and colour.

    {"latch_version": int|None, "store_ok": bool, "store": str|None,
     "run_id": object, "recall": object}. `store` is set for a v2 latch whose
    `store` is an absolute path, whatever its colour; `store_ok` is green only
    for a v2 latch with store_ok literally true, the jsonl backend, recall on
    and a store. A v1 latch, any other version and a non-object read as red
    with no store.
    """
    if not isinstance(state, dict):
        return {
            "latch_version": None,
            "store_ok": False,
            "store": None,
            "run_id": None,
            "recall": None,
        }
    version = state.get("latch_version")
    version = version if _is_int(version) else None
    store: Path | None = None
    green = False
    if version == _LATCH_V2:
        store = _latch_store_path(state.get("store"))
        green = (
            state.get("store_ok") is True
            and state.get("backend") == _STORE_BACKEND
            and state.get("recall") == "on"
            and store is not None
        )
    return {
        "latch_version": version,
        "store_ok": green,
        "store": None if store is None else str(store),
        "run_id": state.get("run_id"),
        "recall": state.get("recall"),
    }


# --- Store-path rule ----------------------------------------------------------
# A latch naming a usable store arms one more deny: a model tool call that
# names the store path. Each file tool is read on the keys it names a path in;
# `file_path` and `path` are read for every one of them, as the gate read them
# before the store existed. A relative `pattern` or `glob` is taken against the
# tool's own `path` as well as against the cwd.
#
# "Names" is read wide, and every widening is on the deny side: the store root
# found anywhere inside a word (`-o<store>`, `@<store>`, `file://<store>`), a
# word or a piece of one that resolves under it as written or with its
# symlinks resolved, a brace expansion or a glob that can match it, and the
# home and working-folder spellings a shell expands. The same matching finds a
# path, glob or brace expansion that reaches claude-mem's own folder under a
# home, beside the literal `.claude-mem` check.

_PATH_KEYS = ("file_path", "path")
_TOOL_EXTRA_KEYS = {
    "Read": (),
    "Write": (),
    "Edit": (),
    "MultiEdit": (),
    "NotebookEdit": ("notebook_path",),
    "Glob": ("pattern",),
    "Grep": ("glob",),
}
_PATTERN_KEYS = frozenset({"pattern", "glob"})

# The three separator sets _command_write_verbs splits a command under, kept
# equal to them by a test. Each one exposes a segment the others can leave
# inside an exempt-looking one (a newline, a lone `&`), so a segment that names
# the store is looked for under all three.
_STORE_SEPARATOR_SETS = (
    r"&&|\|\||;|\|",
    r"&&|\|\||;|\||\n|\r",
    r"&&|\|\||;|\||&|\n|\r",
)

# $HOME, ${HOME} and %USERPROFILE%, and the same three spellings of the other
# variable: every one is read as each home folder this process knows of, so a
# spelling the shell expands one way is not missed for being read another. A
# `${HOME<op>...}` form (`${HOME:-x}`, `${HOME%/}`) reads as the home too.
_HOME_VAR = re.compile(
    r"\$\{(?:HOME|USERPROFILE)(?:[^}A-Za-z0-9_][^}]*)?\}"
    r"|\$(?:HOME|USERPROFILE)(?![A-Za-z0-9_])"
    r"|%(?:HOME|USERPROFILE)%",
    re.IGNORECASE,
)

# $PWD and ${PWD...}, read as the event's cwd, as a leading `~+` is, and the
# `$(pwd)` and backtick `pwd` substitutions that print it.
_PWD_VAR = re.compile(
    r"\$\{PWD(?:[^}A-Za-z0-9_][^}]*)?\}|\$PWD(?![A-Za-z0-9_])"
    r"|\$\(\s*pwd(?:\s+-[LP])?\s*\)|`\s*pwd(?:\s+-[LP])?\s*`"
)

# A bash extglob group, ?(...) *(...) +(...) @(...) !(...), read as a `*`
# standing for whatever it matches: a wider match, never a narrower one.
_EXTGLOB = re.compile(r"[?*+@!]\([^()]*\)")

# Bash ANSI-C quoting, $'...', whose escapes can spell any character. Such a
# word is read decoded as well, so `$'\x2f'` counts as `/`.
_ANSI_C = re.compile(r"\$'((?:[^'\\]|\\.)*)'", re.DOTALL)
_ANSI_C_ESCAPE = re.compile(
    r"\\(x[0-9A-Fa-f]{1,2}|u[0-9A-Fa-f]{1,4}|U[0-9A-Fa-f]{1,8}|[0-7]{1,3}|c.|.)",
    re.DOTALL,
)
_ANSI_C_SIMPLE = {
    "a": "\a",
    "b": "\b",
    "e": "\x1b",
    "E": "\x1b",
    "f": "\f",
    "n": "\n",
    "r": "\r",
    "t": "\t",
    "v": "\v",
}

# Quotes and backslashes, taken out before the literal `.claude-mem` check so
# `.claude-m'e'm` and `.claude-m\em` still read as the folder.
_QUOTING = re.compile(r"""["'\\]""")

# What ends a path inside one shell word: whitespace, quotes, `=` (the
# `--opt=<path>` and `FOO=<path>` forms), redirection and control operators,
# and the paren, brace and comma of substitutions, brace expansion and lists.
_PATH_BREAK = re.compile(r"""[\s=<>|&;(){},'"`]+""")

# A character that, right after the store root inside a longer text, would
# continue its last folder name (`recall2` is not `recall`). Anything else
# there (the end, a separator, a quote, an operator, a glob or brace
# character, `:` or `=`) ends the name, so the text names the store.
_ROOT_CONTINUES = re.compile(r"""[^\s/\\'"`;|&<>(){}\[\],=:*?!$]""")

# Glob characters, and the cap on how many words one brace expansion yields.
# Past the cap, or in a word longer than _BRACE_WORD_CAP, a brace group is read
# as a `*` standing for whatever it expands to: a wider match, never a
# narrower one, and a bounded cost.
_GLOB_CHARS = re.compile(r"[*?\[]")
_BRACE_LIMIT = 64
_BRACE_STEPS = 256
_BRACE_WORD_CAP = 1024
_BRACE_SEQUENCE = re.compile(r"^(-?\d+|[A-Za-z])\.\.(-?\d+|[A-Za-z])(?:\.\.(-?\d+))?$")

# The scripts the exemption admits, under <skill-root>/scripts/.
_RECALL_SCRIPTS = ("mem_recall.py", "mem_observation.py")

# The leading command of an exempt segment is `uv run` or python, matched on
# the bare word: an interpreter given by path (`./python`) is not exempt.
_EXEMPT_PYTHON = re.compile(r"^python(?:3(?:\.\d+)?)?$")

# Any of these anywhere in a segment refuses the exemption. Every redirection
# form (`>`, `>>`, `<`, `2>`, `&>`, `>|`, `&>>`, `<<<`, `>&2`, and `<(...)` and
# `>(...)`) carries a `<` or a `>`; command substitution is `$(` or a backtick.
_EXEMPT_REFUSED = ("<", ">", "`", "$(")

# A leading assignment that changes which interpreter, which modules, which
# libraries, which configuration or which home folder the exempt call would
# use refuses the exemption.
_EXEMPT_UNSAFE_ASSIGNMENT = re.compile(
    r"^[({]*(?:PATH|VIRTUAL_ENV|CONDA_\w*|PYTHON\w*|UV_\w*|LD_\w*|DYLD_\w*"
    r"|HOME|USERPROFILE|APPDATA|LOCALAPPDATA|XDG_\w*|GIT_\w*)="
)

# A directory change anywhere in the command moves where a relative script
# path lands when the command runs, so it refuses a relative operand.
_CHDIR = re.compile(r"""(?:^|[\s;&|(){}'"`])(?:cd|pushd|popd)(?=$|[\s;&|(){}'"`])""")

# What can change, for the rest of a command, what a later `uv` or `python`
# resolves to or the environment it runs with: these builtins at the head of
# any segment, these keywords ahead of it (a loop or coprocess variable, a
# function), a segment of assignments only (`PATH=/x; ...`), a function
# definition, `printf -v`, and arithmetic or a `${VAR:=...}` default, which
# assign as well. Any one of them refuses the exemption to every segment of
# that command; the leading assignments of an exempt segment itself are
# checked against _EXEMPT_UNSAFE_ASSIGNMENT instead.
_REBINDING_WORDS = frozenset(
    {
        ".",
        "source",
        "export",
        "declare",
        "typeset",
        "readonly",
        "local",
        "unset",
        "alias",
        "hash",
        "enable",
        "eval",
        "shopt",
        "builtin",
        "trap",
        "read",
        "mapfile",
        "readarray",
        "let",
        "getopts",
    }
)
_REBINDING_KEYWORDS = frozenset({"for", "select", "function", "coproc"})
# Words that run what follows them in this shell, so a rebinding builtin behind
# them rebinds as it does at the head (`command export PATH=...`), and so does
# an assignment behind the `time` keyword (`time PATH=...`). `command -v` and
# `-V` only look a name up and run nothing.
_CURRENT_SHELL_WRAPPERS = frozenset({"command", "time"})
# Rebinding shapes the word scan in _command_rebinds cannot reach, because it
# splits a command at blanks and reads only each segment's head. Each changes
# command lookup or the environment where a bare `NAME=` head does not sit:
#   - `((` and `$[` open arithmetic (a `$((` holds `((`), which can assign;
#   - the hash and alias arrays rebind a command name by entry. Any mention of
#     them counts, even one that only reads them (`${#BASH_CMDS[@]}`, a search
#     for the word): a command whose name the text does not spell can write an
#     entry (`"$(printf %s r e a d)" 'BASH_CMDS[cat]' <<< /bin/rm` runs `read`),
#     and then the array's name is all the text shows of the write.
_REBINDING_TEXT = re.compile(r"\(\(|\$\[|(?<![A-Za-z0-9_])BASH_(?:CMDS|ALIASES)(?![A-Za-z0-9_])")
# A subscript may nest (`PATH[a[0]]=x`), and bash reads one with blanks in it
# (`PATH[ 0 ]=x`) as a single assignment word, which shlex splits at the blanks:
# _command_rebinds also matches a head that opens a subscript against the
# segment's words joined again.
_ANY_ASSIGNMENT = re.compile(r"^[({]*[A-Za-z_][A-Za-z0-9_]*(?:\[.*\])?\+?=")
_OPEN_SUBSCRIPT_HEAD = re.compile(r"^[({]*[A-Za-z_][A-Za-z0-9_]*\[")

# A mutation: a `=` that is not a comparison (`==`, `!=`, `<=`, `>=`, `=~`), a
# compound assignment (`+= -= *= /= %= &= ^= |= <<= >>=`), or `++`/`--`. Where
# bash evaluates arithmetic, it assigns.
_MUTATION = r"(?:(?<![=!<>])=(?![=~])|\+=|-=|\*=|/=|%=|\^=|\|=|&=|<<=|>>=|\+\+|--)"
# A mutation in arithmetic: after a name or a subscript's `]`, blanks allowed
# between (`PATH = 1`, `BASH_CMDS[cat]++`), or a `++`/`--` before a name.
_ARITHMETIC_MUTATION = re.compile(
    rf"(?:(?<![A-Za-z0-9_])[A-Za-z_][A-Za-z0-9_]*|\])[ \t]*(?P<op>{_MUTATION})"
    r"|(?P<pre>\+\+|--)[ \t]*[A-Za-z_]"
)
# A mutation glued to a name or a subscript's `]`, the only kind read in a
# `[[ ]]` test: there a lone `=` compares strings, and `--help` is a word.
_GLUED_MUTATION = re.compile(rf"(?:(?<![A-Za-z0-9_])[A-Za-z_][A-Za-z0-9_]*|\])(?P<op>{_MUTATION})")

# Where bash evaluates arithmetic outside `((` and `$[`, so a mutation there
# assigns (_arithmetic_rebinds):
#   - the offset and length of a `${...}` substring (`${PWD:PATH=1}`);
#   - a subscript inside a `${...}` (`${a[PATH=1]}`, `${a[BASH_CMDS[cat]++]}`),
#     in a word that assigns to it (`a[PATH=1]=x`), and in a name that `-v` or
#     `-R` reads in a `test`, `[` or `[[` (`test -v 'a[PATH=1]'`);
#   - a `[[ ]]` test that compares numbers (`-eq`, `-ne`, `-lt`, `-le`, `-gt`,
#     `-ge`), whose operands are arithmetic (`[[ 1 -eq PATH=1 ]]`), with the
#     subscripts inside it.
# A bracket anywhere else is no subscript bash evaluates (`grep 'a[b=c]'` hands
# grep a character class), so a mutation in it does not count. A `${...}` also
# assigns by its operator: a `=` or `:=` right after the name and any subscript
# (`${x=1}`, `${x:=1}`, `${BASH_CMDS[cat]:=/bin/rm}`, `${!x:=1}`); a `=` later in
# it (`${PWD#*=}`, `${line%=*}`, `${x:-a=b}`, `${x/=/-}`) is only text. Brackets
# and braces are paired quote-blind in one pass and every span is found from
# them, so the reading stays linear in the command's length. In order below: a
# `${` with its `!` or `#` and its parameter, a `NAME[` that opens a subscript,
# `[[` and `]]` where they stand as words, `test` or `[` as a word, a `-v` or
# `-R` operand, and the text between two of `;`, `&`, `|` and a newline.
_PARAMETER =re.compile(r"\$\{([!#]?)([A-Za-z_][A-Za-z0-9_]*|[0-9]+|[@*#?$!-])")
_SUBSCRIPT = re.compile(r"(?<![A-Za-z0-9_])[A-Za-z_][A-Za-z0-9_]*\[")
_TEST_BOUND = re.compile(r"(?<![^\s;&|(){}!])\[\[(?=\s)|(?<=\s)\]\](?![^\s;&|()])")
_TEST_COMMAND = re.compile(r"""(?<![^\s;&|(){}!'"])(?:test|\[)(?=[\s'"])""")
_NAME_OPERAND = re.compile(r"""(?<![^\s!('"])-[vR](?=[\s'"])""")
_ARITH_COMPARISON = re.compile(r"(?<![A-Za-z0-9_])-(?:eq|ne|lt|le|gt|ge)(?![A-Za-z0-9_])")
_SIMPLE_PIECE = re.compile(r"[^;&|\n]+")
# An assignment whose value OPENS a command substitution, for a name that
# changes command lookup or the interpreter (the names _EXEMPT_UNSAFE_ASSIGNMENT
# lists). shlex splits the substitution at its blanks, so _strip_leading_noise
# would eat `PATH=$(printf` and read the rest as a command; this keeps the whole
# assignment a rebinding (`PATH=$(printf %s /x):$PATH`). The opener must sit
# right after the `=`, so a markdown code span such as `` `PYTHON_COLORS=0` ``
# in a heredoc body is not read as one.
_VALUE_SUBSTITUTION = re.compile(
    r"(?:^|[\s;&|(){}])(?:PATH|VIRTUAL_ENV|CONDA_\w*|PYTHON\w*|UV_\w*|LD_\w*"
    r"|DYLD_\w*|HOME|USERPROFILE|APPDATA|LOCALAPPDATA|XDG_\w*|GIT_\w*)"
    r"(?:\[[^][]*\])?\+?=(?:\$\(|`)"
)


def _closers(text: str, opener: str, closer: str) -> dict[int, int]:
    """Where each `opener` in the text closes, paired quote-blind the way
    nested brackets pair; one that never closes runs to the text's end."""
    closes: dict[int, int] = {}
    unclosed: list[int] = []
    for match in re.finditer(f"[{re.escape(opener)}{re.escape(closer)}]", text):
        if match.group() == opener:
            unclosed.append(match.start())
        elif unclosed:
            closes[unclosed.pop()] = match.start()
    for index in unclosed:
        closes[index] = len(text)
    return closes


def _mutation_within(command: str, pattern: re.Pattern[str], spans: list[tuple[int, int]]) -> bool:
    """True when a mutation `pattern` finds has its operator inside one of the
    (start, end) spans."""
    if not spans:
        return False
    starts: list[int] = []
    ends: list[int] = []
    for start, end in sorted(spans):
        if starts and start <= ends[-1]:
            ends[-1] = max(ends[-1], end)
        else:
            starts.append(start)
            ends.append(end)
    for match in pattern.finditer(command):
        at = match.start("op") if match.group("op") is not None else match.start("pre")
        index = bisect.bisect_right(starts, at) - 1
        if index >= 0 and at < ends[index]:
            return True
    return False


def _arithmetic_rebinds(command: str) -> bool:
    """True when a `${...}` assigns by its operator, or a mutation stands where
    bash evaluates arithmetic outside `((` and `$[` (see the comment above)."""
    brackets = _closers(command, "[", "]") if "[" in command else {}
    braces: dict[int, int] | None = None
    spaced: list[tuple[int, int]] = []  # blanks may stand around the operator
    glued: list[tuple[int, int]] = []  # `[[ ]]` number tests: glued to a name

    def subscripts(start: int, end: int) -> None:
        for match in _SUBSCRIPT.finditer(command, start, end):
            spaced.append((match.end(), brackets[match.end() - 1]))

    for match in _PARAMETER.finditer(command):
        after = match.end()
        if command.startswith("[", after):
            spaced.append((after + 1, brackets[after]))
            after = brackets[after] + 1
        if command.startswith(("=", ":="), after):
            return True
        if command.startswith(":", after) and command[after + 1 : after + 2] not in ("-", "=", "+", "?"):
            if braces is None:
                braces = _closers(command, "{", "}")
            spaced.append((after + 1, braces[match.start() + 1]))
    for match in _SUBSCRIPT.finditer(command):
        close = brackets[match.end() - 1]
        if command.startswith(("=", "+="), close + 1):
            spaced.append((match.end(), close))
    tests: list[tuple[int, int]] = []
    opened: int | None = None
    for match in _TEST_BOUND.finditer(command):
        if match.group() == "[[":
            if opened is None:
                opened = match.end()
        elif opened is not None:
            tests.append((opened, match.start()))
            opened = None
    if opened is not None:
        tests.append((opened, len(command)))
    for start, end in tests:
        numbers = _ARITH_COMPARISON.search(command, start, end) is not None
        if numbers:
            glued.append((start, end))
        if numbers or _NAME_OPERAND.search(command, start, end):
            subscripts(start, end)
    for piece in _SIMPLE_PIECE.finditer(command):
        start, end = piece.span()
        if _TEST_COMMAND.search(command, start, end) and _NAME_OPERAND.search(command, start, end):
            subscripts(start, end)
    return _mutation_within(command, _ARITHMETIC_MUTATION, spaced) or _mutation_within(
        command, _GLUED_MUTATION, glued
    )


def _rebinding_text(command: str) -> bool:
    """The rebinding shapes the per-segment word scan in _command_rebinds
    cannot reach (see _REBINDING_TEXT): `((` or `$[`, any mention of the hash
    or alias arrays, a `${...}` that assigns or a mutation where bash evaluates
    arithmetic (_arithmetic_rebinds), and an assignment whose value opens a
    substitution. Read quote-blind, like the word scan and the separator
    split, and in time linear in the command's length."""
    if _REBINDING_TEXT.search(command) or _VALUE_SUBSTITUTION.search(command):
        return True
    return _arithmetic_rebinds(command)


# How much of a denied segment its deny reason quotes.
_SEGMENT_SHOWN = 160

# macOS file systems ignore case and Unicode normalization by default, so on
# macOS the deny side compares paths NFC-normalized and casefolded.
_FOLD_CASE_AND_FORM = sys.platform == "darwin"


def _scripts_dir() -> str:
    """<skill-root>/scripts, from this file's own path (scripts/hooks/<this>)."""
    return os.path.dirname(os.path.dirname(os.path.abspath(__file__)))


def _pinned_paths() -> list[str]:
    """The two recall scripts the exemption admits, as absolute paths.

    The skill root comes from this file's location, not from an env var: the
    guard ships in <skill-root>/scripts/hooks/ beside the scripts it pins, its
    own path cannot be absent or set by a tool call, and an env var would mean
    a new value on the hook command that preflight writes, which an older
    arming lacks. Both the path this file runs from and its symlink-resolved
    form count, so a skill reached through a symlinked folder still matches.
    """
    here = os.path.abspath(__file__)
    pinned: list[str] = []
    for hook in (here, os.path.realpath(here)):
        scripts = os.path.dirname(os.path.dirname(hook))
        for name in _RECALL_SCRIPTS:
            path = os.path.join(scripts, name)
            if path not in pinned:
                pinned.append(path)
    return pinned


def _pinned_scripts() -> frozenset[str]:
    """The pinned paths as written, folded by os.path.normcase only."""
    return frozenset(os.path.normcase(path) for path in _pinned_paths())


def _pinned_real_scripts() -> frozenset[str]:
    """The files the pinned paths lead to, symlinks resolved, normcased."""
    return frozenset(os.path.normcase(_real(path)) for path in _pinned_paths())


def _home_dirs() -> list[str]:
    """Every home folder a spelling can mean: HOME, USERPROFILE and `~`."""
    homes: list[str] = []
    for value in (
        os.environ.get("HOME"),
        os.environ.get("USERPROFILE"),
        os.path.expanduser("~"),
    ):
        if value and not value.startswith("~") and value not in homes:
            homes.append(value)
    return homes


def _fold(path: str) -> str:
    """A path or text as the deny side compares it.

    os.path.normcase (case and separators on Windows), and on macOS, whose
    file systems ignore case and Unicode normalization by default, NFC and
    casefolded too. Never used to grant the exemption, where a wider match
    would let another file through.
    """
    folded = os.path.normcase(path)
    if _FOLD_CASE_AND_FORM:
        folded = unicodedata.normalize("NFC", folded).casefold()
    return folded


# No system looks up a path longer than this (Linux takes 4096 bytes, macOS
# 1024, Windows 32767 UTF-16 units). os.path.realpath walks a path one name at
# a time and hands the system the whole path resolved so far at each step,
# which costs time in the square of its length: one Bash word of a few MB
# spelled as a path (`a/a/a/...`) kept the guard past Claude Code's 600 s hook
# timeout while a run latch is present. A longer word can still name a file,
# though: the shell reads a glob of 33,000 `*` as the short name it matches,
# and `mkdir -p` walks a path a folder at a time. So _real_long still resolves
# it, in stretches no longer than this.
_MAX_RESOLVED = 32_768

# The most names _real_long hands realpath for one path: twice as many as
# realpath looks up for the names of a path within _MAX_RESOLVED, which holds
# at most half as many names as it has characters, since a name and its
# separator take two. Each realpath call on a stretch looks up every name of
# the path it is handed, the path resolved so far again and then the stretch,
# and each lookup hands the system the whole path up to that name. A link to
# `.` keeps the resolved path short however often it repeats, and as deep as
# the system looks up (on Linux some 2,000 folders, each walked again by every
# lookup), so the time a run of them took grew with its length at about 70 s
# a MB, and a word of a few MB could outlast the hook's timeout. A path whose
# names would come to more than this is refused, unresolved (_TooManyLookups).
# The count leaves out the names inside the targets of the links realpath
# follows (some 2,000 in a target on Linux, looked up again by each stretch)
# and covers one path, not a call: the module docstring states that residual.
_MAX_LONG_LOOKUPS = _MAX_RESOLVED


class _TooManyLookups(Exception):
    """A path longer than _MAX_RESOLVED whose links keep it short, so that
    its names, counted again for each stretch, come to more than
    _MAX_LONG_LOOKUPS lookups. Nothing catches it short of _mem_gate, which
    runs the checks that resolve paths only while a run latch is present, and
    refuses the call (failing closed)."""


@functools.lru_cache(maxsize=None)
def _real(path: str) -> str:
    """os.path.realpath, memoized; the path unchanged when it cannot resolve.
    A path longer than _MAX_RESOLVED gets realpath's answer from _real_long,
    in time linear in its length, or raises _TooManyLookups."""
    try:
        if len(path) > _MAX_RESOLVED:
            return _real_long(path)
        return os.path.realpath(path)
    except (OSError, ValueError, RuntimeError):
        return path


def _real_long(path: str) -> str:
    """os.path.realpath of a path longer than _MAX_RESOLVED, from realpath
    calls on stretches of it no longer than the bound.

    realpath looks up the path resolved so far with the next name joined to
    it, follows a symlink it finds there, and keeps a name it cannot look up
    as written. So resolving the path a stretch of whole names at a time,
    with the path resolved so far in front, gives realpath's answer; and once
    that path joined to the next name is longer than the bound, no lookup of
    it or of any longer path succeeds, and the rest is kept as written. It is
    the path resolved so far that is measured, not the path as written: a
    link to `.` keeps the resolved path short however often it repeats, and
    realpath follows a link after it. Rather than hand realpath more than
    _MAX_LONG_LOOKUPS names in all, counting the names of the path resolved
    so far that each stretch looks up again, it raises _TooManyLookups. The
    names inside the targets of the links realpath follows are not counted
    (the module docstring states that residual).

    Before Python 3.13, realpath stops at a symlink loop and keeps the rest of
    the path as written, and abspath then applies any `..` the targets met on
    the way left in it, which can take the loop out of the path and leave a
    link after it unresolved. So when a stretch stops at a loop, every later
    name is kept as written too (_realpath_stretch says when it does), rather
    than handed to the next stretch, which would follow that link.

    From Python 3.13 realpath goes on past a loop, keeping the loop's link in
    the path, and within one call reuses what each link it met resolved to,
    a loop's links included; a stretch looks such a link up afresh. So from
    3.13, and only for a path through a symlink loop, the answer can differ
    from realpath's: with lm -> ln/C and ln -> lm, a path through lm that
    goes on past a stretch's end comes back with C twice. The system refuses
    any path through a loop (ELOOP), so a call reaches nothing through such
    a path either way.

    Windows looks a path up whole, never one longer than a written path can
    be, so there the first stretch is resolved and the rest kept: that finds
    every link realpath on the whole path could. A path with a `..` step,
    which realpath applies to the path resolved so far, goes to realpath
    whole: the deny side (_abs_forms, _roots) hands only abspath's output,
    which has none, and _is_pinned never hands a long path.
    """
    sep = os.sep
    drive, rest = os.path.splitdrive(path)
    names = rest.split(sep)
    if not os.path.isabs(path) or os.pardir in names:
        return os.path.realpath(path)
    names = [name for name in names if name and name != os.curdir]
    resolved = drive + sep
    done = lookups = 0
    while done < len(names):
        size, end = len(resolved), done
        while end < len(names) and size + len(sep) + len(names[end]) <= _MAX_RESOLVED:
            size += len(sep) + len(names[end])
            end += 1
        if end == done:
            break
        lookups += resolved.count(sep) + end - done
        if lookups > _MAX_LONG_LOOKUPS:
            raise _TooManyLookups(f"{lookups:,} lookups for a {len(path):,}-character path")
        resolved, whole = _realpath_stretch(_joined(resolved, names[done:end]))
        done = end
        if os.name == "nt" or not whole:
            break
    return _joined(resolved, names[done:])


def _realpath_stretch(path: str) -> tuple[str, bool]:
    """os.path.realpath(path), with False when realpath stopped at a symlink
    loop and kept the rest as written, which it does before Python 3.13.

    There realpath returns abspath of what posixpath._joinrealpath returns,
    whose second value is False after a loop. That helper is private, so it
    is called only on the versions that have it, with the arguments realpath
    hands it, and should a release take other arguments, realpath's own
    answer is returned. From 3.13, and on Windows, the answer is realpath's,
    with True.
    """
    join_real = getattr(os.path, "_joinrealpath", None) if sys.version_info < (3, 13) else None
    if join_real is None:
        return os.path.realpath(path), True
    try:
        resolved, whole = join_real(path[:0], path, False, {})
    except TypeError:  # a release whose helper takes other arguments
        return os.path.realpath(path), True
    return os.path.abspath(resolved), bool(whole)


def _joined(head: str, names: list[str]) -> str:
    """The names joined under head, by the separator alone (os.path.join
    would read a name holding a drive as a new start)."""
    if not names:
        return head
    sep = os.sep
    return (head if head.endswith(sep) else head + sep) + sep.join(names)


def _roots(path: str) -> tuple[str, ...]:
    """A folder as written and with its symlinks resolved, both folded."""
    try:
        absolute = os.path.abspath(path)
    except (TypeError, ValueError):
        return (_fold(path),)
    forms = (_fold(absolute), _fold(_real(absolute)))
    return forms if forms[0] != forms[1] else forms[:1]


def _claude_mem_roots(homes: list[str]) -> tuple[str, ...]:
    """claude-mem's own folder under each home, written and resolved, folded."""
    roots: list[str] = []
    for home in homes:
        for root in _roots(os.path.join(home, ".claude-mem")):
            if root not in roots:
                roots.append(root)
    return tuple(roots)


def _ansi_c_char(match: re.Match) -> str:
    body = match.group(1)
    try:
        if body[0] in "xuU" and len(body) > 1:
            return chr(int(body[1:], 16))
        if body[0] in "01234567":
            return chr(int(body, 8) & 0xFF)
    except (ValueError, OverflowError):
        return ""
    if body[0] == "c" and len(body) == 2:
        return chr(ord(body[1]) & 0x1F)
    return _ANSI_C_SIMPLE.get(body, body)


def _decode_ansi_c(text: str) -> str:
    """Each $'...' word decoded and quoted again, so shlex reads it as one word."""
    return _ANSI_C.sub(
        lambda match: shlex.quote(_ANSI_C_ESCAPE.sub(_ansi_c_char, match.group(1))),
        text,
    )


def _mentions_claude_mem(value: str) -> bool:
    """True when `.claude-mem` sits anywhere in the value, read with its quotes
    and backslashes taken out and its $'...' words decoded."""
    target = _fold(".claude-mem")
    texts = [value, _decode_ansi_c(value)] if "$'" in value else [value]
    return any(target in _fold(_QUOTING.sub("", text)) for text in texts)


def _spellings(text: str, homes: list[str], cwd: str) -> list[str]:
    """The text as written, plus copies with each extglob group read as a `*`,
    with $PWD (or `$(pwd)`) read as the cwd, and with each home variable
    spelling read as each home folder, in every combination."""
    out = [text]
    if _EXTGLOB.search(text):
        out.append(_EXTGLOB.sub("*", text))
    if _PWD_VAR.search(text):
        out.extend([_PWD_VAR.sub(lambda _match: cwd, variant) for variant in list(out)])
    if _HOME_VAR.search(text):
        for variant in list(out):
            for home in homes:
                out.append(_HOME_VAR.sub(lambda _match, home=home: home, variant))
    return out


def _brace_sequence(body: str) -> list[str] | None:
    """The words of a `{a..b}` or `{a..b..step}` sequence, or None."""
    match = _BRACE_SEQUENCE.match(body)
    if not match:
        return None
    first, last, step_text = match.groups()
    step = abs(int(step_text)) if step_text else 1
    step = step or 1
    numeric = [part.lstrip("-").isdigit() for part in (first, last)]
    if all(numeric):
        start, end = int(first), int(last)
        to_text = str
    elif not any(numeric):
        start, end = ord(first), ord(last)
        to_text = chr
    else:
        return None
    count = abs(end - start) // step + 1
    if count > _BRACE_LIMIT:
        return ["*"]
    direction = 1 if end >= start else -1
    return [to_text(start + direction * step * index) for index in range(count)]


def _brace_group(word: str) -> tuple[int, int, list[str]] | None:
    """The leftmost brace expansion in a word: (open, close, alternatives).

    A group is a `{...}` holding a comma of its own, or a `{a..b}` sequence;
    other braces are literal, as in bash. Quoting is not tracked, so a quoted
    group expands too: a wider match, never a narrower one. One pass.
    """
    stack: list[tuple[int, list[int]]] = []
    best: tuple[int, int, list[str]] | None = None
    for pos, char in enumerate(word):
        if char == "{":
            stack.append((pos, []))
        elif char == "," and stack:
            stack[-1][1].append(pos)
        elif char == "}" and stack:
            start, commas = stack.pop()
            if best is not None and best[0] < start:
                continue
            if commas:
                edges = [start, *commas, pos]
                alternatives = [word[a + 1 : b] for a, b in zip(edges, edges[1:])]
            else:
                alternatives = _brace_sequence(word[start + 1 : pos])
            if alternatives is not None:
                best = (start, pos, alternatives)
    return best


def _brace_flatten(word: str) -> str:
    """Every outermost brace group as one `*`, in one pass."""
    closes: dict[int, int] = {}
    stack: list[int] = []
    for pos, char in enumerate(word):
        if char == "{":
            stack.append(pos)
        elif char == "}" and stack:
            closes[stack.pop()] = pos
    out: list[str] = []
    pos = 0
    while pos < len(word):
        end = closes.get(pos)
        if end is None:
            out.append(word[pos])
            pos += 1
        else:
            out.append("*")
            pos = end + 1
    return "".join(out)


def _brace_variants(word: str) -> list[str]:
    """Every word a brace expansion of `word` yields, within the caps."""
    if "{" not in word or "}" not in word:
        return [word]
    if len(word) > _BRACE_WORD_CAP:
        return [_brace_flatten(word)]
    done: list[str] = []
    pending = [word]
    steps = 0
    while pending:
        current = pending.pop()
        group = _brace_group(current)
        if group is None:
            done.append(current)
            continue
        steps += 1
        start, end, alternatives = group
        if steps > _BRACE_STEPS or len(done) + len(pending) + len(alternatives) > _BRACE_LIMIT:
            done.append(_brace_flatten(current))
            continue
        pending.extend(current[:start] + alt + current[end + 1 :] for alt in alternatives)
    return done


def _holds_root(folded: str, root: str) -> bool:
    """True when a root sits anywhere in the (folded) text and its last folder
    name ends there: the `-o<store>`, `@<store>`, `file://<store>`,
    `host:<store>`, `//<store>` and `/proc/self/root<store>` forms."""
    if root.endswith(os.sep):  # a file-system root
        return root in folded
    start = folded.find(root)
    while start != -1:
        end = start + len(root)
        if end == len(folded) or not _ROOT_CONTINUES.match(folded[end]):
            return True
        start = folded.find(root, start + 1)
    return False


def _components(path: str) -> list[str]:
    return [part for part in path.split(os.sep) if part]


def _under(path: str, root: str) -> bool:
    """True when `path` is the root, lies under it, or is a glob that can match
    it or a path under it (both folded). A `**` above the root's depth is a
    search from an ancestor, the accepted residual, so it is not a match."""
    if path == root:
        return True
    if path.startswith(root if root.endswith(os.sep) else root + os.sep):
        return True
    if not _GLOB_CHARS.search(path):
        return False
    pattern, names = _components(path), _components(root)
    if len(pattern) < len(names):
        return False
    for part, name in zip(pattern, names):
        if part == "**" or not fnmatch.fnmatchcase(name, part):
            return False
    return True


def _pathlike(piece: str) -> bool:
    """A piece of a word that reads as a path: `~`, `.` or a drive in front, or
    a separator in it. A bare word is left to the whole-word check, so a word
    of a commit message that equals a relative store name is not a path."""
    if not piece:
        return False
    if piece[0] in "~." or "/" in piece or os.sep in piece:
        return True
    return bool(os.path.splitdrive(piece)[0])


def _abs_forms(candidate: str, base: str, homes: list[str], cwd: str) -> list[str]:
    """Every absolute path a candidate can mean, as written and with symlinks
    resolved, folded.

    A leading `~` is read as each home folder and `~+` as the cwd; a relative
    candidate is taken against `base`. The resolved form also collapses the
    POSIX `//` prefix that abspath keeps.
    """
    forms = [candidate]
    if candidate.startswith("~"):
        rest = candidate[1:]
        if rest[:1] == "+" and (len(rest) == 1 or rest[1] in "/\\"):
            forms = [cwd + rest[1:]]
        elif not rest or rest[0] in "/\\":
            forms = [home + rest for home in homes]
        try:
            forms.append(os.path.expanduser(candidate))
        except (KeyError, ValueError):
            pass
    out: list[str] = []
    for form in forms:
        try:
            path = os.path.abspath(form if os.path.isabs(form) else os.path.join(base, form))
        except (TypeError, ValueError):
            continue
        out.append(_fold(path))
        out.append(_fold(_real(path)))
    return out


def _names_store(
    text: str,
    roots: tuple[str, ...],
    bases: list[str],
    homes: list[str],
    cwd: str,
    *,
    whole: bool,
) -> bool:
    """True when the text names a root: holding it anywhere, as a whole
    (`whole`), or through any path-like piece of it, in any home or cwd
    spelling and any brace expansion, against any base."""
    for spelling in _spellings(text, homes, cwd):
        for variant in _brace_variants(spelling):
            folded = _fold(variant)
            if any(_holds_root(folded, root) for root in roots):
                return True
            candidates = [variant] if whole else []
            candidates.extend(p for p in _PATH_BREAK.split(variant) if _pathlike(p))
            for candidate in candidates:
                for base in bases:
                    forms = _abs_forms(candidate, base, homes, cwd)
                    if any(_under(path, root) for path in forms for root in roots):
                        return True
    return False


@functools.lru_cache(maxsize=None)
def _word_names(
    word: str, roots: tuple[str, ...], cwd: str, homes: tuple[str, ...], whole: bool
) -> bool:
    """_names_store for one shell word or raw chunk against the cwd, memoized:
    a long command repeats its words across segments and separator sets."""
    return _names_store(word, roots, [cwd], list(homes), cwd, whole=whole)


@functools.lru_cache(maxsize=None)
def _words(text: str) -> tuple[str, ...]:
    """The shell words of a text, or none when its quoting does not parse."""
    try:
        return tuple(_tokenize(text))
    except ValueError:
        return ()


@functools.lru_cache(maxsize=None)
def _bash_names(segment: str, roots: tuple[str, ...], cwd: str, homes: tuple[str, ...]) -> bool:
    """True when one shell segment names a root.

    The whole text is searched for a root; each shell word counts whole and by
    its pieces; each whitespace-separated chunk of the raw text counts by its
    pieces too, since it keeps what shlex drops (an unquoted Windows backslash
    path) and still reads a segment whose quoting does not parse. A segment
    with a $'...' word is read decoded as well.
    """
    texts = [segment, _decode_ansi_c(segment)] if "$'" in segment else [segment]
    for text in texts:
        for spelling in _spellings(text, list(homes), cwd):
            folded = _fold(spelling)
            if any(_holds_root(folded, root) for root in roots):
                return True
        if any(_word_names(word, roots, cwd, homes, True) for word in _words(text)):
            return True
        if any(_word_names(chunk, roots, cwd, homes, False) for chunk in text.split()):
            return True
    return False


def _exempt_operand(segment: str) -> str | None:
    """The script operand of a segment shaped like an exempt call, or None.

    After the leading assignment, keyword and group-opener strip, the segment
    must lead with `uv run` or a python and name the script right after it:
    an option first (`uv run --with x`, `python -c ...`) is not exempt, so no
    payload can sit ahead of the pinned path. A wrapper (`env`, `sudo`,
    `bash -c`) leads with another word and is never exempt.
    """
    if any(marker in segment for marker in _EXEMPT_REFUSED):
        return None
    try:
        words = _tokenize(segment)
    except ValueError:
        return None
    rest = _strip_leading_noise(words)
    if any(_EXEMPT_UNSAFE_ASSIGNMENT.match(w) for w in words[: len(words) - len(rest)]):
        return None
    if len(rest) >= 3 and rest[0] == "uv" and rest[1] == "run":
        return rest[2]
    if len(rest) >= 2 and _EXEMPT_PYTHON.match(rest[0]):
        return rest[1]
    return None


@functools.lru_cache(maxsize=64)
def _command_rebinds(command: str) -> bool:
    """True when some segment of the command can change what a later `uv` or
    `python` resolves to, or the environment it runs with: a rebinding builtin
    or keyword at a segment head (_REBINDING_WORDS), or one of the shapes the
    head scan cannot reach (_rebinding_text): `((` or `$[`, a mutation where
    bash evaluates arithmetic (a `[[ ... -eq NAME=1 ]]` test, a `${...}`
    substring, a subscript in a `${...}`, in an assignment word or in a test
    with `-v` or `-R`), any mention of the hash or alias arrays, a `${...}`
    whose operator assigns, and an assignment to an interpreter or path
    variable whose value opens a substitution. Read under every separator
    set, quote-blind like them. A head behind `command` or `time`
    (_CURRENT_SHELL_WRAPPERS) is read as a head."""
    if _rebinding_text(command):
        return True
    for separators in _STORE_SEPARATOR_SETS:
        for segment in re.split(separators, command):
            try:
                words = _tokenize(segment)
            except ValueError:
                words = segment.split()
            if _segment_rebinds(words):
                return True
    return False


def _segment_rebinds(words: list[str]) -> bool:
    """True when one segment's words rebind at its head (see _command_rebinds).
    A loop, not a recursion, over the wrappers ahead of the head, and a bounded
    one: each pass re-reads the rest of the segment, so a run of more wrappers
    than _MAX_WRAPPERS counts as a rebind (fail closed) rather than costing
    time quadratic in its length."""
    for _ in range(_MAX_WRAPPERS + 1):
        rest = _strip_leading_noise(words)
        prefix = words[: len(words) - len(rest)]
        if any(w.lower().lstrip(_GROUP_OPENERS) in _REBINDING_KEYWORDS for w in prefix):
            return True
        if not rest:
            return any(_ANY_ASSIGNMENT.match(w) for w in prefix)
        head = rest[0]
        if head not in _CURRENT_SHELL_WRAPPERS:
            break
        index = 1
        while index < len(rest) and rest[index].startswith("-"):
            option = rest[index]
            index += 1
            if option == "--":
                break
            if head == "command" and ("v" in option or "V" in option):
                return False
        words = rest[index:]
    else:
        return True
    if head in _REBINDING_WORDS or _ANY_ASSIGNMENT.match(head):
        return True
    if _OPEN_SUBSCRIPT_HEAD.match(head) and _ANY_ASSIGNMENT.match(" ".join(rest)):
        return True
    if "()" in head or (len(rest) > 1 and rest[1].startswith("()")):
        return True
    return head == "printf" and len(rest) > 1 and rest[1].startswith("-v")


def _operand_path(operand: str, cwd: str) -> str | None:
    """The operand as an absolute path, a relative one joined to cwd, with its
    `.` and `..` steps still in it (see _is_pinned).

    No `~` or variable expansion: a script spelled that way is not exempt,
    which fails closed (recall off), never open.
    """
    try:
        return operand if os.path.isabs(operand) else os.path.join(cwd, operand)
    except (TypeError, ValueError):
        return None


def _is_pinned(path: str | None) -> bool:
    """True when the path is a pinned script as written (lexically, `.` and
    `..` folded away) AND leads to one when walked step by step with its
    symlinks resolved, so a `..` that leaves a symlinked folder for another
    file of the pinned name is not exempt.

    A path longer than _MAX_RESOLVED is never exempt: its `..` steps are
    still in it, and realpath on such a path costs time in the square of its
    length. Withholding the exemption fails closed."""
    if path is None or len(path) > _MAX_RESOLVED:
        return False
    try:
        lexical = os.path.normcase(os.path.abspath(path))
    except (TypeError, ValueError):
        return False
    if lexical not in _pinned_scripts():
        return False
    return os.path.normcase(_real(path)) in _pinned_real_scripts()


def _exempt_segment(segment: str, cwd: str, command: str) -> bool:
    """True when the segment runs one of the pinned recall scripts.

    Checked per segment, never on the whole command, and pinned by path, not
    by basename.
    """
    operand = _exempt_operand(segment)
    if not operand:
        return False
    if not os.path.isabs(operand) and _CHDIR.search(command):
        return False
    absolute = _operand_path(operand, cwd)
    return _is_pinned(absolute)


# --- Latch-path rule ----------------------------------------------------------
# Decision 11: while a latch is present, whatever it holds, a model tool call
# may read the latch but not change it. Only mem_recall.py changes it: `latch`
# writes or replaces it, and `unlatch` removes it when it carries the caller's
# run_id. The latch path is matched as the store rule matches the store, every
# spelling, glob, brace expansion and symlink included, and the pinned script
# exemption applies to it per segment. In a Bash segment the latch's file name
# on its own counts too (_names_file_name), so a `cd` into its folder is no
# way around the rule.
#
# The tools that write files (_LATCH_CHANGING_TOOLS) are denied on the path.
# Read, Grep and Glob only read, so this rule does not look at them. A Bash
# segment that names the latch counts as a change unless it can be told to
# only read it (_read_segment, in a command _command_allows_reads accepts).
# So rm, mv, cp, ln, tee, a redirection, sed -i, truncate and python -c are
# examples of a change, not a list of them: anything the guard cannot tell
# only reads the latch is denied.
#
# A read is led, by bare name, by a command that writes no file whatever its
# options. `less` is not one (`less -o FILE` copies its input into FILE), nor
# `sed` (`-i`, and its `w` command), `find` (`-delete`, `-fprint`), `sort -o`,
# `uniq IN OUT` or `file -C`. The name is matched bare, so a `./cat` the model
# wrote is not a read, and the command must leave command lookup alone, so a
# function or alias named `cat` is not one either.
_LATCH_CHANGING_TOOLS = frozenset({"Bash", "Write", "Edit", "MultiEdit", "NotebookEdit"})
_LATCH_READERS = frozenset(
    {"cat", "head", "tail", "wc", "grep", "egrep", "fgrep", "jq", "ls", "stat", "test", "[", "[["}
)

# Any of these in a segment makes it more than a read: every output
# redirection (`>`, `>>`, `2>`, `&>`, `>|`, `<>`, `>(...)`), command
# substitution, process substitution, which runs a command of its own, and
# the `[[ ... =~ ... ]]` match, which hands what it matched on through
# BASH_REMATCH (`[[ <latch> =~ .* ]] && rm "$BASH_REMATCH"`), as `$_` does.
_READ_REFUSED = (">", "`", "$(", "<(", "=~")

# Bash's `$_`, the last word of the previous command: `cat <latch>; rm "$_"`
# hands the path on without naming it again, so in a command holding one, no
# segment counts as a read.
_LAST_WORD = re.compile(r"\$\{?_(?![A-Za-z0-9_])")

# A pipe, `|` or `|&`, but not `||`. A read piped into another command can
# hand the path on (`ls <latch> | xargs rm`), so in a command holding one,
# every segment must be a read for any of them to count as one.
_PIPE = re.compile(r"(?<!\|)\|(?!\|)")


def _read_segment(segment: str) -> bool:
    """True when the segment can only read: after the leading assignment,
    keyword and group-opener strip, it is led by one of _LATCH_READERS, by
    bare name, with nothing of _READ_REFUSED in it and no leading assignment
    that changes command lookup or what the command loads. A segment that
    runs nothing (a bare `fi`, a closing brace) counts as one too."""
    if any(marker in segment for marker in _READ_REFUSED):
        return False
    try:
        words = _tokenize(segment)
    except ValueError:
        return False
    rest = _strip_leading_noise(words)
    if any(_EXEMPT_UNSAFE_ASSIGNMENT.match(w) for w in words[: len(words) - len(rest)]):
        return False
    return not rest or rest[0] in _LATCH_READERS


@functools.lru_cache(maxsize=64)
def _command_allows_reads(command: str) -> bool:
    """True when a read segment of this command counts as a read: the command
    changes nothing about the environment or command lookup (_command_rebinds),
    uses no `$_`, and, when it holds a pipe, is made of reads only, under
    every separator set."""
    if _command_rebinds(command) or _LAST_WORD.search(command):
        return False
    if not _PIPE.search(command):
        return True
    return all(
        _read_segment(segment)
        for separators in _STORE_SEPARATOR_SETS
        for segment in re.split(separators, command)
    )


# The latch's file name on its own, beside its path: a `cd` into the artifacts
# folder and then `rm .mem-state.json`, a `find -name .mem-state.json -delete`,
# a path an interpreter joins at run time (`os.path.join(dir, '.mem-state.json')`)
# and a `**/` glob all name the file without spelling its path. The name
# counts when nothing that could extend it (a letter, digit, `_`, `.` or `-`)
# sits right before it and nothing that would continue it sits right after,
# past any trailing dots: Windows drops those from a file name, so there
# `.mem-state.json.` is the latch. A path needs no such step: on Windows
# os.path.abspath calls GetFullPathNameW, which trims trailing dots the way
# opening the path would, and elsewhere `<store>.` is another folder.
_NAME_EXTENDS = re.compile(r"[A-Za-z0-9_.-]")


def _dot_glob(word: str) -> bool:
    """A glob that starts with a literal dot and holds a literal character
    after it (`.m*`, `.mem-state.js?n`, `.*json`). A bare `.*`, `.??*` or
    `.[!.]*`, which matches every dotfile, is not one: it is how a search
    such as `find -not -path '*/.*'` skips hidden folders."""
    if not word.startswith(".") or not _GLOB_CHARS.search(word):
        return False
    return bool(re.sub(r"\[[^\]]*\]|[*?]", "", word[1:]))


@functools.lru_cache(maxsize=256)
def _names_file_name(segment: str, name: str) -> bool:
    """True when the segment holds the file name `name` on its own, or a word
    piece whose last step is a _dot_glob that matches it. Read with quotes
    taken out, backslashes taken out or read as separators, $'...' decoded,
    each extglob group read as a `*` and each brace expansion expanded."""
    target = _fold(name)
    texts = [segment, _decode_ansi_c(segment)] if "$'" in segment else [segment]
    for text in texts:
        plains = (_QUOTING.sub("", text), re.sub(r"[\"']", "", text.replace("\\", "/")))
        for plain in dict.fromkeys(plains):
            for spelling in dict.fromkeys((plain, _EXTGLOB.sub("*", plain))):
                for variant in _brace_variants(spelling):
                    folded = _fold(variant)
                    start = folded.find(target)
                    while start != -1:
                        end = start + len(target)
                        while folded[end : end + 1] == ".":
                            end += 1
                        if (start == 0 or not _NAME_EXTENDS.match(folded[start - 1])) and (
                            end == len(folded) or not _ROOT_CONTINUES.match(folded[end])
                        ):
                            return True
                        start = folded.find(target, start + 1)
                    for piece in _PATH_BREAK.split(variant):
                        last = _fold(piece.replace("\\", "/").rsplit("/", 1)[-1])
                        if _dot_glob(last) and fnmatch.fnmatchcase(target, last):
                            return True
    return False


# --- Heredoc bodies that are data ---------------------------------------------
# The latch and store rules split a command at its separators whatever the
# quoting, so a heredoc's body was read line by line as shell segments (issue
# #176): a report appended with `cat >> <file> <<'EOF'` from the latch's own
# folder was denied for a markdown line ending `row 6).**`, whose `.**` reads as
# a dot glob that matches the latch, and a table's `|` made the whole command
# count as piped. Bash hands a body to its command on standard input and, when
# the delimiter is quoted, runs none of it, so the two rules read a command
# without the bodies that are only data to it (_without_heredoc_data).
#
# Leaving text out is the direction that can let a call through, so the
# reading is narrow, and wherever it is unsure it keeps the whole command:
#   - A body is data only when its simple command is led by `cat` or `tee`
#     (_HEREDOC_SINKS), by bare name, after plain assignments that leave command
#     lookup alone, with no keyword, `{`, `!` or redirection in front. Any other
#     command may run what it reads (`bash`, `python3 -`, `xargs`,
#     `source /dev/stdin`, `git apply`, `ed`, `sqlite3`, a `while read` loop),
#     so its body is read as before.
#   - A sink with a `|` after it, before the next `;`, `&`, `&&`, `||` or the
#     end of its line, keeps its body: `cat <<'EOF' | sh` hands it to a shell,
#     and so does `cat <<'EOF' |` with `sh` on the line after the delimiter. A
#     `|` anywhere else in the command cannot reach the body.
#   - Nothing before a sink may change what `cat` or `tee` runs: no rebinding
#     _command_rebinds finds, and no assignment at all (_HEREDOC_ASSIGNS).
#     What follows the sink runs after it, unless a group, a subshell, a loop
#     or a function wraps it, and then a `|` or such a change anywhere in the
#     command keeps the body: `{ cat <<'EOF'; } | sh`, a loop that changes
#     PATH after the sink, and `f() {` with a later `f | sh` all reach it. A
#     `(` that opens no substitution or arithmetic, and `{`, `if`, `while`,
#     `until`, `for`, `select`, `function` or `coproc` where a word starts,
#     count as such a wrapper for every sink after them (_HEREDOC_COMPOUNDS).
#   - A `<(` or `>(` outside the bodies, even inside quotes, keeps every body.
#   - A quoted delimiter (`<<'EOF'`, `<<"EOF"`, `<<\EOF`) expands nothing in the
#     body. An unquoted one runs each `$(...)`, `$((...))`, `${...}`, `$[...]`
#     and backtick in it, so those stay in the reading, each read wide
#     (_heredoc_expansions).
#   - A `<<` counts only where bash reads one: outside quotes, comments and
#     arithmetic. One inside `[[ ]]`, `$(...)` or backticks keeps the whole
#     command, since bash ends a body inside a substitution at a line that only
#     starts with its delimiter (`EOF)`), and so does a `case`, whose patterns'
#     `)` the reading does not pair. A body ends at the first line equal to its
#     delimiter, leading tabs stripped for `<<-`, and several heredocs on one
#     line take consecutive bodies. In an unquoted body a line ending in a
#     backslash joins the next before bash compares it, so such a body keeps
#     the whole command too, and so does a body no delimiter line ends.
#   - A quote-aware second reading (_quoted_segments) must find the same
#     heredocs, in the same order, with the same delimiters.
# What follows a delimiter line is a command again, and is read as one. The
# claude-mem rule keeps reading every body: it denies `.claude-mem` anywhere in
# a call, by design. Accepted residual, the one stated for a script that names
# the store or the latch: a body written to a file that another command runs
# (a FIFO reader can start before the writer, so not only a later one).
_HEREDOC_SINKS = frozenset({"cat", "tee"})

# A heredoc operator and its delimiter word: a name, bare, quoted whole in
# single or double quotes, or behind a backslash, ended by a metacharacter. A
# word of any other shape keeps the whole command.
_HEREDOC_OPERATOR = re.compile(
    r"<<(?P<dash>-?)[ \t]*(?:'(?P<single>[A-Za-z_][A-Za-z0-9_]*)'"
    r"|\"(?P<double>[A-Za-z_][A-Za-z0-9_]*)\"|\\(?P<escaped>[A-Za-z_][A-Za-z0-9_]*)"
    r"|(?P<bare>[A-Za-z_][A-Za-z0-9_]*))(?![^ \t\n;&|()<>])"
)

# The head of a heredoc's simple command that makes its body data: plain
# assignments (no quote, expansion or operator in the value), then a sink by
# bare name, ended by a blank, a redirection or the command's end.
_HEREDOC_SINK = re.compile(
    r"[ \t]*((?:[A-Za-z_][A-Za-z0-9_]*=[^\s$`'\"\\(){};&|<>]*[ \t]+)*)"
    rf"(?:{'|'.join(sorted(_HEREDOC_SINKS))})(?![^ \t<>])"
)

# What ends a word where a keyword (`case`, `[[`, `]]`) can stand.
_HEREDOC_METACHARS = " \t\n;&|()<>"

# The keywords that open a group, a loop or a function, which can wrap a sink
# in a pipeline or run it again. A `(` counts too, wherever it stands, unless
# it opens a substitution or arithmetic (`$(`, `$((`, `((`).
_HEREDOC_COMPOUNDS = ("{", "if", "while", "until", "for", "select", "function", "coproc")

# What _command_rebinds still does not count (see _rebinding_text), because
# flagging it everywhere would over-deny the read and exemption paths: a plain
# `NAME=` or `NAME[...]=` anywhere, read quote-blind. The heredoc path is
# stricter than those, so it treats ANY such assignment before a sink as able
# to change what `cat` or `tee` runs, an argument such as `CC=gcc` included;
# one led by `-`, `.` or `/` (`--format=`, `user.name=`) cannot assign and does
# not. A `${...}` counts as it does there, where its operator assigns
# (`${x:=1}`), and here also where it holds such a `NAME=` (`${x:+a=b}`); a `=`
# after no name, or after one led by `-` (`${PWD#*=}`, `${x:-a=b}`), is text.
_HEREDOC_ASSIGNS = re.compile(r"(?<![A-Za-z0-9_./-])[A-Za-z_][A-Za-z0-9_]*(?:\[[^][]*\])?\+?=")


class _Unsure(Exception):
    """A command whose heredocs the reading cannot vouch for: it is read whole."""


class _Heredoc(NamedTuple):
    """One heredoc, as _HeredocScan finds it."""

    word: str  # its delimiter, `-` in front for `<<-`, as _quoted_heredoc_words reads it
    quoted: bool  # the delimiter was quoted, so bash expands nothing in the body
    head: str  # the simple command its operator sits in
    start: int  # where that simple command starts
    piped: bool  # a `|` follows that command in its pipeline
    body: int  # where its body starts
    close: int  # where its delimiter line starts
    end: int  # past its delimiter line


class _HeredocScan:
    """One pass over a command that finds its heredocs where bash does, or
    raises _Unsure. What it reads, and why, is in the section comment above."""

    def __init__(self, text: str) -> None:
        self.text = text
        self.found: list[_Heredoc] = []
        # The operators read on the current line, each with the start and,
        # once read, the end of its simple command; their bodies start at the
        # next line.
        self.pending: list[dict] = []
        # Where the first group, subshell, loop or function opens, if any
        # does (_HEREDOC_COMPOUNDS).
        self.compound: int | None = None

    def run(self) -> list[_Heredoc]:
        self.command(0, None, True)
        return self.found

    def keyword(self, index: int, word: str) -> bool:
        end = index + len(word)
        return self.text.startswith(word, index) and (
            end == len(self.text) or self.text[end] in _HEREDOC_METACHARS
        )

    def command(self, index: int, closer: str | None, heredocs: bool) -> int:
        """Shell text from `index` to the `)` that closes it (`closer`), or to
        the end at the top; returns the index past it. `heredocs` is false in a
        substitution, where a `<<` keeps the whole command."""
        text = self.text
        size = len(text)
        start = index  # where the current simple command starts
        current: list[dict] = []
        # The operators read in the current pipeline, up to a `;`, `&`, `&&`,
        # `||` or the line's end: a `|` after one hands its command's output on.
        pipeline: list[dict] = []
        word_start = True
        in_test = False

        def end_command(at: int) -> None:
            for entry in current:
                entry["end"] = at
            current.clear()

        while index < size:
            char = text[index]
            if (
                word_start
                and self.compound is None
                and any(self.keyword(index, word) for word in _HEREDOC_COMPOUNDS)
            ):
                self.compound = index
            if char == "\\":
                index += 2  # an escaped character, a line continuation included
                word_start = False
            elif char == "#" and word_start:
                end = text.find("\n", index)
                index = size if end == -1 else end
            elif char == "'":
                index = self.single(index + 1)
                word_start = False
            elif text.startswith("$'", index):
                index = self.ansi_c(index + 2)
                word_start = False
            elif char == '"':
                index = self.double(index + 1)
                word_start = False
            elif char == "`":
                index = self.backtick(index + 1)
                word_start = False
            elif text.startswith("$((", index):
                index = self.arithmetic(index + 3)
                word_start = False
            elif text.startswith("$(", index):
                index = self.command(index + 2, ")", False)
                word_start = False
            elif text.startswith("${", index):
                index = self.braced(index + 2)
                word_start = False
            elif text.startswith(("$[", "<(", ">("), index):
                raise _Unsure
            elif word_start and text.startswith("((", index):
                index = self.arithmetic(index + 2)
                word_start = False
            elif word_start and self.keyword(index, "case"):
                raise _Unsure  # a pattern's `)` would close a `(` early
            elif word_start and self.keyword(index, "[["):
                in_test = True
                index += 2
            elif word_start and self.keyword(index, "]]"):
                in_test = False
                index += 2
            elif text.startswith("<<<", index):
                index += 3
                word_start = True
            elif text.startswith("<<", index):
                match = _HEREDOC_OPERATOR.match(text, index)
                if in_test or not heredocs or match is None:
                    raise _Unsure
                entry = {"match": match, "start": start, "end": None, "piped": False}
                self.pending.append(entry)
                current.append(entry)
                pipeline.append(entry)
                index = match.end()
                word_start = True
            elif char in "<>":
                index += 2 if text.startswith((">>", ">&", ">|", "<&", "<>"), index) else 1
                word_start = True
            elif text.startswith("&>", index):
                index += 3 if text.startswith("&>>", index) else 2
                word_start = True
            elif char == "|" and not text.startswith("||", index):
                end_command(index)
                for entry in pipeline:
                    entry["piped"] = True
                index += 2 if text.startswith("|&", index) else 1
                start = index
                word_start = True
            elif char in ";&|":
                end_command(index)
                pipeline.clear()
                index += 2 if text.startswith(("&&", "||"), index) else 1
                start = index
                word_start = True
            elif char == "(":
                if self.compound is None:
                    self.compound = index
                end_command(index)
                # A `(` glued to a word (an array, an extglob group, a function
                # name) opens no subshell, so no heredoc counts inside it.
                index = self.command(index + 1, ")", heredocs and word_start)
                start = index
                word_start = True
            elif char == ")":
                if closer is None:
                    raise _Unsure
                end_command(index)
                return index + 1
            elif char == "\n":
                if in_test:
                    raise _Unsure
                end_command(index)
                pipeline.clear()
                index = self.bodies(index + 1, heredocs)
                start = index
                word_start = True
            else:
                index += 1
                word_start = char in " \t"
        if closer is not None or self.pending:
            raise _Unsure  # an unclosed `(`, or an operator with no line after it
        end_command(size)
        return index

    def bodies(self, index: int, heredocs: bool) -> int:
        """The bodies of the operators on the line just ended, in order, from
        `index`; returns the index past the last delimiter line."""
        if not self.pending:
            return index
        if not heredocs:
            raise _Unsure
        text = self.text
        size = len(text)
        for entry in self.pending:
            match = entry["match"]
            if entry["end"] is None:
                raise _Unsure
            name = match["single"] or match["double"] or match["escaped"] or match["bare"]
            quoted = match["bare"] is None
            body = index
            while True:
                if index >= size:
                    raise _Unsure  # no delimiter line ends the body
                newline = text.find("\n", index)
                line_end = size if newline == -1 else newline
                line = text[index:line_end]
                if (line.lstrip("\t") if match["dash"] else line) == name:
                    break
                if not quoted and line.endswith("\\"):
                    raise _Unsure  # bash joins it to the next line first
                index = line_end + 1
            after = min(line_end + 1, size)
            head = text[entry["start"] : entry["end"]]
            self.found.append(
                _Heredoc(match["dash"] + name, quoted, head, entry["start"], entry["piped"], body, index, after)
            )
            index = after
        self.pending.clear()
        return index

    def single(self, index: int) -> int:
        end = self.text.find("'", index)
        if end == -1 or (self.pending and "\n" in self.text[index:end]):
            raise _Unsure
        return end + 1

    def ansi_c(self, index: int) -> int:
        text = self.text
        while index < len(text):
            if text[index] == "\\":
                index += 2
                continue
            if text[index] == "'":
                return index + 1
            if text[index] == "\n" and self.pending:
                raise _Unsure
            index += 1
        raise _Unsure

    def double(self, index: int) -> int:
        """A double-quoted string from past its opening quote, the
        substitutions in it read as bash reads them."""
        text = self.text
        while index < len(text):
            char = text[index]
            if char == "\\":
                index += 2
            elif char == '"':
                return index + 1
            elif char == "`":
                index = self.backtick(index + 1)
            elif text.startswith("$((", index):
                index = self.arithmetic(index + 3)
            elif text.startswith("$(", index):
                index = self.command(index + 2, ")", False)
            elif text.startswith("${", index):
                index = self.braced(index + 2)
            elif text.startswith("$[", index) or (char == "\n" and self.pending):
                raise _Unsure
            else:
                index += 1
        raise _Unsure

    def backtick(self, index: int) -> int:
        """Old-style substitution, which bash ends at the first backtick no
        backslash escapes; a `<<` in it keeps the whole command."""
        text = self.text
        start = index
        while index < len(text):
            if text[index] == "\\":
                index += 2
            elif text[index] == "`":
                inner = text[start:index]
                if "<<" in inner or (self.pending and "\n" in inner):
                    raise _Unsure
                return index + 1
            else:
                index += 1
        raise _Unsure

    def arithmetic(self, index: int) -> int:
        """Arithmetic, `$((...))` or `((...))`, up to its `))`, where a `<<` is
        a shift. One that spans lines, holds a quote or a backslash, or does
        not close as arithmetic keeps the whole command."""
        text = self.text
        depth = 0
        while index < len(text):
            char = text[index]
            if char in "\n'\"`\\" or text.startswith("$[", index):
                raise _Unsure
            if text.startswith("$((", index):
                index = self.arithmetic(index + 3)
                continue
            if text.startswith("$(", index):
                index = self.command(index + 2, ")", False)
                continue
            if text.startswith("${", index):
                index = self.braced(index + 2)
                continue
            if char == "(":
                depth += 1
            elif char == ")":
                if depth:
                    depth -= 1
                elif text.startswith("))", index):
                    return index + 2
                else:
                    raise _Unsure
            index += 1
        raise _Unsure

    def braced(self, index: int) -> int:
        """A `${...}` from past its `{`, up to its `}`; one that quotes,
        substitutes or spans lines keeps the whole command."""
        text = self.text
        depth = 1
        while index < len(text):
            char = text[index]
            if char in "\n'\"`\\" or text.startswith(("$(", "$["), index):
                raise _Unsure
            if char == "{":
                depth += 1
            elif char == "}":
                depth -= 1
                if not depth:
                    return index + 1
            index += 1
        raise _Unsure


def _heredoc_lookup_changes(text: str) -> bool:
    """True when the text can change what a later `cat` or `tee` runs: what
    _command_rebinds finds, and any assignment it can miss (_HEREDOC_ASSIGNS)."""
    return _command_rebinds(text) or _HEREDOC_ASSIGNS.search(text) is not None


def _heredoc_sink(head: str) -> bool:
    """True when a heredoc's simple command hands its body to a command that
    only reads it as data (_HEREDOC_SINK), after no assignment that changes
    command lookup or what the command loads."""
    match = _HEREDOC_SINK.match(head)
    if match is None:
        return False
    return not any(_EXEMPT_UNSAFE_ASSIGNMENT.match(word) for word in match.group(1).split())


def _heredoc_expansions(body: str) -> list[str]:
    """What bash runs in an unquoted heredoc body: each backtick span, up to
    the first backtick no backslash escapes, and each `$(`, `${` or `$[` from
    its opener up to the body's last `)`, `}` or `]`, which holds its real
    closer whatever nests in it. Quotes mean nothing in a body, so none is
    read as one."""
    spans: list[str] = []
    index = 0
    size = len(body)
    while index < size:
        char = body[index]
        if char == "\\":
            index += 2
        elif char == "`":
            end = index + 1
            while end < size and body[end] != "`":
                end += 2 if body[end] == "\\" else 1
            spans.append(body[index : end + 1])
            index = end + 1
        elif char == "$" and body[index + 1 : index + 2] in ("(", "{", "["):
            closer = body.rfind({"(": ")", "{": "}", "[": "]"}[body[index + 1]])
            end = closer + 1 if closer > index + 1 else size
            spans.append(body[index:end])
            index = end
        else:
            index += 1
    return spans


def _quoted_heredoc_words(text: str) -> list[str]:
    """The delimiter after each `<<` the quote-aware reading finds, in order,
    `-` in front for `<<-`; none when the text does not lex."""
    words: list[str] = []
    for tokens in _quoted_segments(text):
        for index, token in enumerate(tokens):
            if token != "<<":
                continue
            after = tokens[index + 1 : index + 3]
            if after[:1] == ["-"] and len(after) == 2:
                words.append("-" + after[1])
            else:
                words.append(after[0] if after else "")
    return words


def _cut(text: str, cuts: list[tuple[int, int, str]]) -> str:
    """The text with each (start, end) span, in order, replaced by its string."""
    out: list[str] = []
    index = 0
    for start, end, kept in cuts:
        out.append(text[index:start])
        out.append(kept)
        index = end
    out.append(text[index:])
    return "".join(out)


@functools.lru_cache(maxsize=64)
def _without_heredoc_data(command: str) -> str:
    """The command as the latch and store rules read it: each heredoc body bash
    only hands to `cat` or `tee` as data left out, with its delimiter line, and
    of an unquoted one only what bash runs in it kept, a line each. Any other
    body is kept, and the command is kept as it is wherever the reading is
    unsure (see the section comment above)."""
    if "<<" not in command:
        return command
    scan = _HeredocScan(command)
    try:
        heredocs = scan.run()
    except (_Unsure, RecursionError):  # a substitution nested past the stack is unsure too
        return command
    if not heredocs:
        return command
    bodies = [(heredoc.body, heredoc.end, "") for heredoc in heredocs]
    skeleton = _cut(command, bodies)
    if (
        "<(" in skeleton
        or ">(" in skeleton
        or _quoted_heredoc_words(skeleton) != [heredoc.word for heredoc in heredocs]
    ):
        return command
    cuts: list[tuple[int, int, str]] = []
    # A lookup change before a sink, in the already-data-cut prefix, keeps its
    # body. A sink's simple command starts at a top-level boundary (a `<<`
    # inside `[[ ]]`, `(( ))`, `${...}`, a substitution or a `(` raises _Unsure
    # or opens a compound, so no boundary here sits inside one), and no
    # rebinding shape spans such a boundary. So each sink's prefix extends the
    # last one's, and once something before a sink changes lookup so does every
    # later prefix: carry a flag and read only the text added since the last
    # check, which keeps the whole pass linear in the command's length.
    lookup_changed = False
    checked = 0
    for heredoc in heredocs:
        if not _heredoc_sink(heredoc.head):
            continue
        if heredoc.piped:
            continue
        if scan.compound is not None and scan.compound < heredoc.start:
            # A group, subshell, loop or function may wrap the sink, so what
            # follows it can reach it too.
            if _PIPE.search(skeleton) or _heredoc_lookup_changes(skeleton):
                continue
        else:
            # Only the bodies already left out as data leave this text: any
            # other body may run in this shell before the sink does. Read the
            # slice added since the last check (checked..start), with the data
            # bodies cut in that slice left out, and keep the running flag.
            if not lookup_changed and heredoc.start > checked:
                delta = _cut(
                    command[checked : heredoc.start],
                    [(s - checked, e - checked, k) for s, e, k in cuts if checked <= s and e <= heredoc.start],
                )
                lookup_changed = _heredoc_lookup_changes(delta)
                checked = heredoc.start
            if lookup_changed:
                continue
        kept = ""
        if not heredoc.quoted:
            spans = _heredoc_expansions(command[heredoc.body : heredoc.close])
            kept = "".join(f"{span}\n" for span in spans)
        cuts.append((heredoc.body, heredoc.end, kept))
    return _cut(command, cuts)


def _store_segment(
    command: str,
    roots: tuple[str, ...],
    cwd: str,
    homes: list[str],
    *,
    exempt: bool = True,
    reads: bool = False,
    name: str | None = None,
    data: bool = False,
) -> str | None:
    """The first shell segment that names a root and is not let through.

    With `exempt` false (the claude-mem folder) no segment is exempt. A
    command that can rebind `uv` or `python` (_command_rebinds) exempts none
    of its segments either. With `reads` true (the latch), a segment that
    only reads is let through as well, in a command that allows reads. With
    a `name` (the latch's file name), a segment that holds that name on its
    own (_names_file_name) counts as naming the root. With `data` true (the
    latch and the store), the command is read without the heredoc bodies bash
    only hands to `cat` or `tee` (_without_heredoc_data), by every check here:
    bash runs none of that text, so it can neither name a root nor rebind,
    pipe, change folder or hand on a `$_`.
    """
    if data:
        command = _without_heredoc_data(command)
    home_key = tuple(homes)
    reads = reads and _command_allows_reads(command)
    for separators in _STORE_SEPARATOR_SETS:
        for segment in re.split(separators, command):
            if not _bash_names(segment, roots, cwd, home_key) and not (
                name and _names_file_name(segment, name)
            ):
                continue
            if (
                exempt
                and not _command_rebinds(command)
                and _exempt_segment(segment, cwd, command)
            ):
                continue
            if reads and _read_segment(segment):
                continue
            return segment
    return None


def _input_names(
    key: str,
    value: str,
    tool_input: dict,
    roots: tuple[str, ...],
    cwd: str,
    homes: list[str],
    *,
    exempt: bool,
    reads: bool = False,
    name: str | None = None,
    data: bool = False,
) -> str | None:
    """What in one input names a root: the Bash segment, or the file-tool
    value; None when nothing does. `reads` lets a Bash read through and
    `name` matches a Bash segment on the file name alone too (both for the
    latch rule), and `data` reads a Bash command without the heredoc bodies
    that are only data (the latch and store rules); a file tool is matched on
    its value alone."""
    if key == "command":
        return _store_segment(
            value, roots, cwd, homes, exempt=exempt, reads=reads, name=name, data=data
        )
    bases = [cwd]
    own_path = tool_input.get("path")
    if key in _PATTERN_KEYS and isinstance(own_path, str) and own_path:
        bases.append(os.path.join(cwd, os.path.expanduser(own_path)))
    return value if _names_store(value, roots, bases, homes, cwd, whole=True) else None


def _tool_inputs(tool_name: object, tool_input: dict) -> list[tuple[str, str]]:
    """(key, value) for every non-empty string input the gate reads."""
    if tool_name == "Bash":
        keys: tuple[str, ...] = ("command",)
    elif isinstance(tool_name, str) and tool_name in _TOOL_EXTRA_KEYS:
        keys = _PATH_KEYS + _TOOL_EXTRA_KEYS[tool_name]
    else:
        return []
    out: list[tuple[str, str]] = []
    for key in keys:
        value = tool_input.get(key)
        if isinstance(value, str) and value:
            out.append((key, value))
    return out


def _event_cwd(event: dict) -> str:
    cwd = event.get("cwd")
    return cwd if isinstance(cwd, str) and cwd else os.getcwd()


def _shown(segment: str) -> str:
    """A denied segment as its deny reason quotes it, cut to _SEGMENT_SHOWN."""
    text = segment.strip()
    if len(text) > _SEGMENT_SHOWN:
        text = text[:_SEGMENT_SHOWN] + "..."
    return repr(text)


def _latch_deny(state_path: Path, what: str) -> NoReturn:
    """Deny for a reason the latch causes. The reason names the latch and ends
    with a note for the person, not the model (AC-33): a latch a run left
    behind is theirs to delete by hand, and the model must not try to remove
    it, which the latch-path rule denies anyway."""
    _deny(
        f"Cross-Session Recall guard: {what} The run latch {state_path} is "
        "present, and a present latch counts as a live UltraCode-Goal run, "
        "whatever its version or colour. For the user: if no UltraCode-Goal "
        "run is active, a run ended without removing this latch. Delete "
        f"{state_path} by hand. The model must not try to remove it itself."
    )


def _latch_rule_text() -> str:
    """The one rule a latch-path deny states: the model may read the latch,
    never change it, and what counts as a read. It gives no recipe for
    changing the latch: the run's own steps already carry the one call that
    may, and a deny is no cue to make it."""
    return (
        "While a run latch is present, the model's tool calls may read it but "
        "not change it, by its path or by its file name. Reading it stays "
        "allowed: Read, Grep and Glob, or a Bash segment led by one of "
        f"{', '.join(f'`{name}`' for name in sorted(_LATCH_READERS))}, with no "
        "output redirection, command substitution or `=~`, piped only into "
        "another such read (a `|` counts as a pipe even inside quotes)."
    )


def _store_rule_text() -> str:
    """The one rule a store deny states: what may reach the store."""
    return (
        "While a run latch is present, only this skill's recall scripts reach "
        "the store: `uv run`, `python`, `python3` or `python3.N` followed "
        f"directly by {os.path.join(_scripts_dir(), _RECALL_SCRIPTS[0])} or "
        f"{os.path.join(_scripts_dir(), _RECALL_SCRIPTS[1])}, as a shell segment "
        "of its own, with no redirection, command substitution or wrapper, in a "
        "command that changes nothing about the environment or about what `uv` "
        "and `python` resolve to."
    )


_CLAUDE_MEM_REFUSED = (
    "UltraCode-Goal no longer uses claude-mem, so while a run latch is present "
    "every claude-mem call is denied."
)


def _latch_gate(event: dict, state_path: Path) -> None:
    """The denies a present latch causes; returns when none applies."""
    tool_name = event.get("tool_name")
    tool_input = event.get("tool_input")
    if not isinstance(tool_input, dict):
        tool_input = {}

    # 1) claude-mem MCP calls, every name form, whatever the latch says, an MCP
    # resource read or listing on a claude-mem server, and a listing that
    # names no server, which lists claude-mem's resources too.
    if _is_claude_mem_tool(tool_name):
        _latch_deny(
            state_path,
            f"refusing the claude-mem MCP call {tool_name}. {_CLAUDE_MEM_REFUSED}",
        )
    server = _claude_mem_resource_server(tool_name, tool_input)
    if server is not None:
        _latch_deny(
            state_path,
            f"refusing a {tool_name} call on the claude-mem MCP server {server}. "
            f"{_CLAUDE_MEM_REFUSED}",
        )
    if tool_name == _MCP_LIST_RESOURCES and not tool_input.get("server"):
        _latch_deny(
            state_path,
            f"refusing a {tool_name} call that names no server: it lists every "
            "server's resources, claude-mem's included. Name the server whose "
            f"resources you need. {_CLAUDE_MEM_REFUSED}",
        )

    inputs = _tool_inputs(tool_name, tool_input)
    cwd = _event_cwd(event)
    homes = _home_dirs()

    # 2) Reach into claude-mem's own files, through every inspected input: the
    # folder's name anywhere, or a path, glob or brace expansion that reaches
    # it under a home. A heredoc body is read too, data or not.
    mem_roots = _claude_mem_roots(homes)
    for key, value in inputs:
        if _mentions_claude_mem(value) or (
            _input_names(key, value, tool_input, mem_roots, cwd, homes, exempt=False)
            is not None
        ):
            _latch_deny(
                state_path,
                f"refusing a {tool_name} call whose {key} reaches into "
                "'.claude-mem'. While a run latch is present, nothing reads or "
                "writes claude-mem's files.",
            )

    # 3) The latch-path rule (decision 11), whatever the latch holds: a call
    # that names the latch and may change it. Read, Grep and Glob only read,
    # so they are not looked at; a Bash segment that only reads passes, and a
    # heredoc body that is only data to its command is not read.
    if tool_name in _LATCH_CHANGING_TOOLS:
        latch_roots = _roots(str(state_path))
        for key, value in inputs:
            found = _input_names(
                key,
                value,
                tool_input,
                latch_roots,
                cwd,
                homes,
                exempt=True,
                reads=True,
                name=state_path.name,
                data=True,
            )
            if found is None:
                continue
            if key == "command":
                _latch_deny(
                    state_path,
                    f"refusing a Bash command whose segment {_shown(found)} names "
                    f"the run latch and may change it. {_latch_rule_text()}",
                )
            _latch_deny(
                state_path,
                f"refusing a {tool_name} call whose {key} names the run latch. "
                f"{_latch_rule_text()}",
            )

    # 4) The store-path rule, for a latch that names a usable store. A latch
    # with none (a v1 latch, an unset store, an unreadable latch) has no path
    # to match, so it denies only through 1) to 3). A heredoc body that is
    # only data to its command is not read, as for the latch.
    store = _latch_view(_read_latch(state_path))["store"]
    if store is None:
        return
    roots = _roots(store)
    for key, value in inputs:
        found = _input_names(key, value, tool_input, roots, cwd, homes, exempt=True, data=True)
        if found is None:
            continue
        if key == "command":
            _latch_deny(
                state_path,
                f"refusing a Bash command whose segment {_shown(found)} names the "
                f"recall store {store}. {_store_rule_text()}",
            )
        _latch_deny(
            state_path,
            f"refusing a {tool_name} call whose {key} names the recall store "
            f"{store}. {_store_rule_text()}",
        )


def _mem_gate(event: dict, impl: Path | None) -> None:
    """Apply the Cross-Session Recall gate for ALL tool names.

    Runs before any Bash-only git logic and re-reads the latch per call. With
    no latch (no active run) it returns: the user's own claude-mem usage
    outside a run is never touched.
    """
    state_path = _mem_state_path(impl)
    if state_path is None:
        # Cannot locate impl-artifacts (no cwd in the event, env unset): the
        # run state is UNKNOWABLE, not provably absent. Uncertain implies deny
        # for claude-mem calls; everything else passes through untouched.
        if _is_claude_mem_tool(event.get("tool_name")):
            _deny(
                "Cross-Session Recall guard: cannot locate impl-artifacts "
                "(event carries no cwd and ULTRACODE_IMPL_ARTIFACTS is unset), "
                "so whether a run latch is present cannot be told, and this "
                "claude-mem MCP call is refused (failing closed). Set "
                "ULTRACODE_IMPL_ARTIFACTS on the hook command to restore latch "
                "resolution."
            )
        return
    # No latch -> no active UCG run -> nothing to gate.
    if not _latch_present(state_path):
        return
    try:
        _latch_gate(event, state_path)
    except _TooManyLookups:
        _latch_deny(
            state_path,
            f"refusing this {event.get('tool_name')} call, because it names a "
            f"path longer than {_MAX_RESOLVED:,} characters whose symlinks keep "
            "it short (a run of links to `.`, say), so resolving it takes more "
            f"than {_MAX_LONG_LOOKUPS:,} lookups and could outlast the hook's "
            "timeout: whether the path reaches the recall store or claude-mem's "
            "files cannot be told, and the call is refused (failing closed). "
            "Spell the path without the repeated links.",
        )
    except Exception as exc:  # noqa: BLE001  fail closed on the unforeseen
        # A crash would exit non-zero, which the client reads as no decision,
        # letting the call through. A present latch means deny instead.
        _latch_deny(
            state_path,
            f"could not evaluate this {event.get('tool_name')} call against the "
            f"run latch ({type(exc).__name__}), so it is refused (failing closed).",
        )


def _json_kind(value: object) -> str:
    """The JSON name of a decoded value's type, for a deny reason."""
    if value is None:
        return "null"
    if isinstance(value, bool):
        return "boolean"
    if isinstance(value, (int, float)):
        return "number"
    if isinstance(value, str):
        return "string"
    if isinstance(value, list):
        return "array"
    return "object" if isinstance(value, dict) else type(value).__name__


def main() -> None:
    """Decide on one tool call, and end with exit 0 (allow) or 2 (deny) only.

    An error raised anywhere while deciding, one no narrower catch below
    handles, denies the call and names the error. Without this catch the hook
    exits 1 with no decision, which Claude Code reads as no objection unless
    the hook entry carries `"onFailure": "block"`, and the call runs
    unchecked. What the guard cannot catch itself (an interpreter that cannot
    start, an error before this code runs, a timeout) is left to that setting.
    """
    try:
        _decide()
    except Exception as exc:  # noqa: BLE001  fail closed on the unforeseen
        detail = " ".join(str(exc).split())[:160]
        _deny(
            "UltraCode-Goal guard: refusing this tool call, because the guard "
            f"raised an error while deciding on it ({type(exc).__name__}: "
            f"{detail}), so the call was not checked and is refused (failing "
            "closed) rather than let through unchecked. The error is the "
            "guard's, not the call's: report it, with the call that met it."
        )


def _decide() -> None:
    event = _read_event()
    if not isinstance(event, dict):
        # A JSON value that is not an object: no tool name, input or cwd can
        # be read from it, so whether the call it stands for is safe cannot
        # be told.
        _deny(
            "UltraCode-Goal guard: refusing this tool call, because the hook "
            f"event on stdin is a JSON {_json_kind(event)}, not an object, so "
            "the call it describes cannot be read, and it is refused (failing "
            "closed) rather than let through unchecked."
        )

    cwd = event.get("cwd")
    impl = _impl_artifacts(cwd)

    # Cross-Session Recall gate runs for EVERY tool name, before the Bash-only
    # git logic below. It either denies (and exits) or returns to let the rest
    # of the guard proceed unchanged.
    _mem_gate(event, impl)

    if event.get("tool_name") != "Bash":
        _allow()

    tool_input = event.get("tool_input") or {}
    if not isinstance(tool_input, dict):
        # A tool_input that holds no command (null, an empty array) is the
        # empty input it always was; any other non-object cannot be read.
        _deny(
            "Commit/push guard: refusing this Bash command, because its "
            f"tool_input is a JSON {_json_kind(tool_input)}, not an object, so "
            "the command cannot be read for a `git commit` or `git push`, and "
            "it is refused (failing closed) rather than let past the "
            "protected-branch, tests-ran, freshness, empty-index, intent-to-add "
            "and un-skip checks."
        )
    command = tool_input.get("command") or ""
    if not isinstance(command, str):
        _allow()

    try:
        verbs, unknown = _classify(command)
    except Exception as exc:  # noqa: BLE001  fail closed on the unforeseen
        # A crash would exit non-zero, which the client reads as no decision,
        # letting the command past every git gate. A command the guard
        # cannot read is refused instead, as a segment it cannot lex is read
        # toward the deny.
        _deny(
            "Commit/push guard: refusing this Bash command, because reading it "
            f"for a `git commit` or `git push` failed ({type(exc).__name__}): "
            "whether it runs one cannot be told, so it is refused (failing "
            "closed) rather than let past the protected-branch, tests-ran, "
            "freshness, empty-index, intent-to-add and un-skip checks. Run it as "
            "shorter, plainer commands."
        )
    if not verbs:
        _allow()
    try:
        _git_write_gates(cwd, verbs, unknown)
    except Exception as exc:  # noqa: BLE001  fail closed on the unforeseen
        # The checks read files and ask git, and an input none of them was
        # written for (a NUL byte in a test-file path the checklist lists)
        # raised out of them: the hook exited with no decision, and the
        # command went past every check still to run. It is refused instead.
        detail = " ".join(str(exc).split())[:160]
        _deny(
            f"Commit/push guard: refusing this `git {'/'.join(sorted(verbs))}`, "
            f"because checking it raised an error ({type(exc).__name__}: {detail}), "
            "so the protected-branch, tests-ran, freshness, empty-index, "
            "intent-to-add and un-skip checks could not all run, and it is "
            "refused (failing closed) rather than let through unchecked. Fix "
            "what the error names, then run it again."
        )


def _git_write_gates(cwd: str | None, verbs: set[str], unknown: list[str]) -> NoReturn:
    """The checks a Bash command that commits or pushes must pass: the
    protected branch for either verb, then, for a commit, the tests-ran
    marker, its freshness, a staged index, an index with no intent-to-add
    entry and the un-skip proof. Each one denies; a command that passes them
    all is allowed."""
    hint = _unknown_hint(unknown)

    protected = _protected_branches()
    branch = _current_branch(cwd)

    if branch is not None and branch in protected:
        _deny(
            f"Protected-branch guard: refusing `git {'/'.join(sorted(verbs))}` "
            f"on '{branch}'. UltraCode-Goal commits one green story per commit "
            f"on an epic branch ('{os.environ.get('ULTRACODE_EPIC_BRANCH_PREFIX', 'ultracode/epic-')}<id>'), "
            f"never on {protected}. Switch to the epic branch first.",
            hint,
        )

    if "commit" in verbs:
        impl = _impl_artifacts(cwd)
        story = _current_story(impl)
        marker = (impl / f".tests-ran-{story}") if (impl and story) else None
        # Same impl-artifacts dir and same story id as the marker, on purpose:
        # one resolution path, so the two files cannot drift apart.
        baseline = (impl / f".baseline-{story}") if (impl and story) else None
        if marker is None or baseline is None or not marker.is_file():
            target = str(marker) if marker else "<impl-artifacts>/.tests-ran-<story>"
            _deny(
                "Tests-ran guard: refusing `git commit` — no tests-ran marker "
                f"for the current story ({story or 'unknown'}). Run the story's "
                f"test/lint/build to green and write {target} before committing. "
                "Commit only at a verified-green story boundary.",
                hint,
            )
        _marker_freshness_gate(marker, baseline)
        if not _staged_index_nonempty(cwd):
            _deny(
                "Empty-index guard: refusing `git commit` — the staged index is "
                "empty (or could not be read), so this commit would capture no "
                "work. Stage this story's paths in a prior, SEPARATE tool call "
                "(`git add <this story's paths>`), then commit as a second, "
                "distinct tool call. `git commit -a` and commit-time pathspecs "
                "are unsupported inside a story loop: the guard evaluates the "
                "command string before it runs, so anything they would stage "
                "does not exist yet at that point.",
                hint,
            )
        marked = _intent_to_add_entries(cwd)
        if marked is None:
            _deny(
                "Intent-to-add guard: refusing `git commit`, because the index "
                "could not be read for intent-to-add entries (`git add -N`), so "
                "whether this commit would leave one out cannot be told. Failing "
                "closed. Check that git can read this repository's index, then "
                "commit.",
                hint,
            )
        if marked:
            _deny(
                "Intent-to-add guard: refusing `git commit`, because the index "
                "holds intent-to-add entries (`git add -N`) for "
                f"{', '.join(f'`{path}`' for path in marked)}. A commit leaves "
                "such an entry out while the index keeps it (over a path HEAD "
                "holds, it deletes HEAD's file), and its staged content reads as "
                "an empty file. Stage each one the story ships "
                "(`git add -- <path>`) in a prior, SEPARATE tool call. A mark on "
                "a path HEAD already holds is cleared the same way, staging the "
                "file in place, since moving it aside would stage its deletion. "
                "For a new file the story will not ship, move it aside into the "
                "story's `.scratch-<story_id>/` folder, run `git add -- <path>`, "
                "which clears its entry, then move it back, where it is untracked "
                "again (delete it only when nothing needs it). Then commit as a "
                "second, distinct tool call.",
                hint,
            )
        _unskip_gate(cwd, story)

    _allow()


if __name__ == "__main__":
    main()
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall