ai-push-hooks 0.3.2 → 0.3.4

package/CHANGELOG.md

@@ -4,6 +4,56 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+## [0.3.4] - 2026-09-14
+
+This is the first stable release. Python and npm both use `0.3.4`, the canonical
+Git tag is `v0.3.4`, npm uses the `latest` dist-tag, and GitHub publishes a
+standard release.
+
+### Fixed
+
+- Failed the clean-worktree gate when Git cannot verify checkout status.
+- Rejected apply destinations inside configured Git hooks directories before
+  propagating any changes to the checkout.
+- Isolated npm's Python startup from consuming-repository modules, inherited
+  `PYTHONPATH`, and user-site imports so they cannot replace the installed hook.
+- Excluded Git-ignored local documentation from default model context collection.
+- Required explicit boolean Beads verdicts before commands, report changes, or
+  quality-gate decisions.
+- Kept failed command output in private artifacts rather than terminal errors.
+- Redacted known sensitive values across diagnostic truncation and partial-output
+  boundaries, including timeout errors.
+- Collected review diffs independently of external diff drivers, text conversion,
+  and color settings.
+- Made private runtime directory creation tolerate concurrent OpenCode stages
+  while retaining directory and symlink checks.
+- Included regular-file, symlink, and other Git type changes in pushed-file
+  facts exposed to workflows and Python callbacks.
+- Preserved each Python callback source's annotation semantics and registered
+  callback modules for dataclasses and runtime type-hint introspection.
+- Validated recovered Actions artifacts against their associated push run,
+  release workflow, repository, tag, and commit before downloading archives.
+
+## [0.3.3] - 2026-09-14
+
+This is a beta patch release. Python and npm both use `0.3.3`, the canonical
+Git tag is `v0.3.3`, npm uses the `beta` dist-tag, and GitHub marks the release
+as a prerelease. PyPI does not provide a separate beta channel, so Python users
+must select the exact `0.3.3` version.
+
+This is a documentation and validation patch only; it adds no runtime features.
+
+### Documentation
+
+- Added a tested deterministic postcondition recipe that distinguishes successful
+  runner execution from a verified fix, while preserving legitimate no-op applies.
+- Recorded live runner validation results for OpenCode, Claude Code, and Codex.
+- Clarified the focused pre-push use case and how the tool complements hook
+  managers, background reviewers, and broader agent workflow frameworks.
+- Documented custom-agent CLI support through the custom command runner.
+- Updated the Codex conformance check to 0.152.0 and verified live project reads
+  and allowlisted edits with `gpt-5.6-luna`.
+
 ## [0.3.2] - 2026-09-12
 
 This is a beta patch release. Python and npm both use `0.3.2`, the canonical
@@ -44,8 +94,7 @@ must select the exact `0.3.2` version.
 
 ### Documentation
 
-- Added an agent setup skill, CI/npm beta badges, and a reproducible,
-  deterministic review/fail/fix/commit/pass demo, explicitly not live AI footage.
+- Added an agent setup skill and CI/npm beta badges.
 - Explained the manual-commit assertion and why applied edits are not part of
   the commit already being pushed.
 - Included the configuration guide in the npm package and removed its link to
@@ -196,7 +245,9 @@ the exact `0.2.0` version rather than a PyPI beta channel.
 - Preserved Git porcelain paths and protected pre-existing dirty allowlisted files during apply steps.
 - Clarified module-local artifact references and standardized the repository hook integration.
 
-[Unreleased]: https://github.com/shanebishop1/ai-push-hooks/compare/v0.3.2...HEAD
+[Unreleased]: https://github.com/shanebishop1/ai-push-hooks/compare/v0.3.4...HEAD
+[0.3.4]: https://github.com/shanebishop1/ai-push-hooks/compare/v0.3.3...v0.3.4
+[0.3.3]: https://github.com/shanebishop1/ai-push-hooks/compare/v0.3.2...v0.3.3
 [0.3.2]: https://github.com/shanebishop1/ai-push-hooks/compare/v0.3.1...v0.3.2
 [0.3.1]: https://github.com/shanebishop1/ai-push-hooks/compare/v0.3.0...v0.3.1
 [0.3.0]: https://github.com/shanebishop1/ai-push-hooks/compare/v0.2.1...v0.3.0

package/README.md

@@ -1,12 +1,12 @@
 # ai-push-hooks
 
-[![CI](https://github.com/shanebishop1/ai-push-hooks/actions/workflows/ci.yml/badge.svg)](https://github.com/shanebishop1/ai-push-hooks/actions/workflows/ci.yml) [![npm beta](https://img.shields.io/npm/v/ai-push-hooks/beta?label=npm%20beta)](https://www.npmjs.com/package/ai-push-hooks/v/beta)
+[![CI](https://github.com/shanebishop1/ai-push-hooks/actions/workflows/ci.yml/badge.svg)](https://github.com/shanebishop1/ai-push-hooks/actions/workflows/ci.yml) [![npm](https://img.shields.io/npm/v/ai-push-hooks)](https://www.npmjs.com/package/ai-push-hooks)
 
 **Agentic linting for the rules your coding agent forgot.**
 
 `AGENTS.md` tells an agent how to work. **ai-push-hooks checks whether it followed through.** Think of it as the inverse of `AGENTS.md`: a second pass over outgoing changes before `git push`, catching guidelines the agent forgot or neglected.
 
-Use **OpenCode, Codex, or Claude Code** to check rules that need judgment, not just a regex. Report violations, apply scoped fixes, and block pushes with explicit checks. It's a hedge against missed instructions, not a guarantee that AI catches everything.
+Use **OpenCode, Codex, Claude Code, or your own agentic CLI** to check rules that need judgment, not just a regex. Report violations, apply scoped fixes, and block pushes with explicit checks. It's a hedge against missed instructions, not a guarantee that AI catches everything.
 
 ## Rules Worth Checking
 
@@ -19,16 +19,18 @@ Use **OpenCode, Codex, or Claude Code** to check rules that need judgment, not j
 
 Write your own rules in prompts or supply a rules file as context. These are examples of checks you configure, not built-in guarantees.
 
-## Why Now?
+## Why This Tool?
 
-With lower-cost models such as GPT 5.6 Luna, GLM 5.3 Flash, Muse Spark 1.3, and Gemini Flash, running several focused agentic checks on each push can be practical, rather than reserving AI review for special occasions. Keep context narrow and measure your workflow's cost and latency. GPT 5.6 Luna is the default.
+Keep your coding workflow; add a check before Git sends the commits. ai-push-hooks combines repository-specific AI checks, scripts, and explicit pass/fail gates around the outgoing diff, using your existing coding CLIs. No daemon or hosted review service is required.
+
+Use it alongside [Lefthook](https://github.com/evilmartians/lefthook) for hook management and [roborev](https://github.com/kenn-io/roborev) for background reviews. [Archon](https://github.com/coleam00/Archon) and [TAKT](https://github.com/nrslib/takt) orchestrate development tasks; this tool deliberately stays narrower. Its job is to check your rules before a push, not take over how you build the project.
 
 ## Quick Start
 
 Install the [ai-push-hooks skill](https://github.com/shanebishop1/ai-push-hooks/blob/main/skills/ai-push-hooks/SKILL.md), tell your agent what intelligent checks you want before pushes, and let it set up the modules for you.
 
 ```bash
-npm install --save-dev ai-push-hooks@beta
+npm install --save-dev ai-push-hooks
 npx --no-install ai-push-hooks init
 npx --no-install ai-push-hooks install
 ```
@@ -37,12 +39,6 @@ Install and authenticate your chosen AI CLI. The current `init` starter checks d
 
 [Other installation options](docs/configuration.md#installation) | [Existing hook managers](docs/configuration.md#hook-managers)
 
-## Deterministic Demo
-
-![Review, fail, fix, commit, pass: deterministic demo](https://raw.githubusercontent.com/shanebishop1/ai-push-hooks/main/docs/demo/review-fix.gif)
-
-This generated GIF summarizes actual hook results from a disposable repository with a local deterministic command runner; it is not a live screen recording or live AI. It makes no provider calls, remote pushes, or Beads changes. Regenerate it with `uv run --no-project --with pillow==11.3.0 python docs/demo/generate.py`.
-
 ## Example: Check Your Rules
 
 This workflow supplies the outgoing diff and your root `AGENTS.md` explicitly, asks for violations, and blocks if any are reported. It does not rely on the runner automatically loading agent instructions.
@@ -103,7 +99,7 @@ inputs = ["review/issues.json"]
 
 `docs_issue_array` is the existing schema name for `{file, description}` findings; it works for code rules too. A missing rules file or a failed check blocks the push by default. Findings live in the run artifacts under `.git/ai-push-hooks/`.
 
-**Want fixes too?** Add an `apply` step with the findings, your rules, and an explicit `allow_paths` list, then recheck and run tests. Applied edits are not auto-committed: review the diff, commit approved changes, and retry the push.
+**Want fixes too?** Add an `apply` step with the findings, your rules, and an explicit `allow_paths` list, then recheck and run tests. [Runner completion is not proof that a fix landed](docs/configuration.md#deterministic-postconditions-after-apply): verify the result. Applied edits are not auto-committed: review the diff, commit approved changes, and retry the push.
 
 ## Build Your Workflow
 
@@ -121,7 +117,7 @@ Each module combines the steps it needs:
 
 ## Choose Your AI
 
-OpenCode defaults to **`openai/gpt-5.6-luna`**. Explicit runner profiles use their own model settings. To use Codex or Claude Code, add its profile and change `[llm].runner`:
+OpenCode, Codex, and Claude Code have first-class adapters. OpenCode defaults to **`openai/gpt-5.6-luna`**. Explicit runner profiles use their own model settings. To use Codex or Claude Code, add its profile and change `[llm].runner`:
 
 ```toml
 [runners.codex]
@@ -131,13 +127,14 @@ type = "codex"
 type = "claude"
 ```
 
-Each `ask` or `apply` step can override the runner, so one tool can review and another can fix. Use model identifiers available to your provider. Other tools, including Pi, can use a [custom command runner](docs/configuration.md#custom-runners).
+Each `ask` or `apply` step can override the runner, so one tool can review and another can fix. **Any other agentic CLI, including Pi, can integrate through a [custom command runner](docs/configuration.md#custom-runners)**: supply a noninteractive command or a thin wrapper. Use model identifiers available to your provider.
 
 ## Control And Safety
 
 - Errors block pushes by default. AI judgments can still miss violations or report false positives.
 - `apply` validates file and Git state and limits propagated edits to `allow_paths`. It does not auto-commit.
 - Runners, scripts, and callbacks are trusted local programs, not an OS sandbox.
+- Local hooks can be bypassed; retain CI for required enforcement.
 - Repository content may be sent to your model provider. Review its privacy and billing terms.
 
 Logs and run summaries live under `.git/ai-push-hooks/`. OpenCode transcripts are captured there by default. To intentionally skip one push: `AI_PUSH_HOOKS_SKIP=1 git push`.

package/SECURITY.md

@@ -40,6 +40,14 @@ transcript files as proof that provider-side data was deleted.
 
 ## Repository callbacks and commands
 
+The npm launcher uses Python isolated mode to prevent the consuming checkout,
+inherited `PYTHONPATH`, and the user site directory from shadowing the shipped
+launcher or standard-library modules. It retains the selected interpreter's
+normal system/virtual-environment site-packages for callback dependencies; use
+that environment rather than `--user` installs or `PYTHONPATH`. This is launch
+path isolation, not an operating-system sandbox, and trusted interpreter
+startup customization or callback code is not made safe by it.
+
 The published `0.3.0` beta includes the `ask` spelling, repository Python
 callbacks, and direct `exec`/`assert` commands. The previous `0.2.1` beta used
 `llm` for model-backed workflow steps; there is no compatibility alias, so
@@ -70,9 +78,11 @@ default command timeout is 60 seconds. stdout/stderr are private, unredacted
 is capped at 16 MiB; invalid UTF-8, timeout, signal, missing executable, or
 truncation fails closed. A command may explicitly invoke `bash -c`, and
 `exec`/`assert` commands may modify the real checkout, so these are user-policy
-choices rather than host isolation guarantees. `assert` saves its report before
-blocking on a false/nonzero result. Only the workflow-level fail-open setting
-overrides that block; there is no per-command override.
+choices rather than host isolation guarantees. Failed command diagnostics name
+the step, status/error class, and private artifact namespace only; they never
+include captured stream text. `assert` saves its report before blocking on a
+false/nonzero result. Only the workflow-level fail-open setting overrides that
+block; there is no per-command override.
 
 Read-only `collect` callback work may overlap up to `max_parallel`; trusted
 callback/command authors must provide their own concurrency safety. `exec` and
@@ -117,7 +127,12 @@ The [0.3.0 release record](CHANGELOG.md#030---2026-09-09) documented a pinned
 Lefthook suite reporting **407 tests with no skips**, an OpenCode **1.18.29**
 contract smoke test with an in-process loopback mock provider and no external
 model call, and version/help-only checks for Codex **0.148.0** and Claude
-**2.1.220**. This is historical evidence, not a current suite result or proof
-for every provider, model, authentication mode, platform, or live `apply` path.
+**2.1.220**. The bounded validation snapshot also records Codex **0.152.0** on
+2026-09-14: its synthetic fixture verified a nonce read and an allowlisted marker
+apply followed by a deterministic postcondition. See the [runner validation
+snapshot](docs/configuration.md#live-validation-snapshot). Together, these records
+are historical or bounded evidence, not a current suite result or proof for every
+provider, model, authentication mode, platform, live `apply` path, or a general
+security guarantee.
 Treat generated-hook path checks and the Lefthook runner as integration
 safeguards, not isolation boundaries.

package/bin/ai-push-hooks.js

@@ -5,17 +5,22 @@ const fs = require('node:fs');
 const path = require('node:path');
 
 const packageRoot = path.resolve(__dirname, '..');
-const srcDir = path.join(packageRoot, 'src');
-const tomliWheel = path.join(packageRoot, 'vendor', 'tomli-2.4.0-py3-none-any.whl');
-const args = ['-m', 'ai_push_hooks', ...process.argv.slice(2)];
+const bootstrap = path.join(packageRoot, 'bin', 'bootstrap.py');
+const capabilityEnvironment = 'AI_PUSH_HOOKS_INTERNAL_CAPABILITY';
+const args = ['-I', bootstrap, ...process.argv.slice(2)];
 const pythonCommands = ['python3.14', 'python3.13', 'python3.12', 'python3.11', 'python3.10', 'python3', 'python'];
 
-function buildEnv() {
+function buildEnv(capability = false) {
   const env = { ...process.env };
   env.AI_PUSH_HOOKS_NODE_EXECUTABLE = process.execPath;
   env.AI_PUSH_HOOKS_NODE_SCRIPT = fs.realpathSync(__filename);
-  // Pure-Python wheels are importable archives; no pip or install scripts needed.
-  env.PYTHONPATH = [srcDir, tomliWheel, env.PYTHONPATH].filter(Boolean).join(path.delimiter);
+  // -I intentionally ignores PYTHONPATH.  The bootstrap adds only shipped paths.
+  delete env.PYTHONPATH;
+  if (capability) {
+    env[capabilityEnvironment] = '1';
+  } else {
+    delete env[capabilityEnvironment];
+  }
   return env;
 }
 
@@ -29,11 +34,8 @@ function run(command) {
 function canRunPackage(command) {
   const check = spawnSync(
     command,
-    [
-      '-c',
-      'import sys; assert sys.version_info >= (3, 10); __import__("tomllib" if sys.version_info >= (3, 11) else "tomli")',
-    ],
-    { stdio: 'ignore', env: buildEnv() },
+    ['-I', bootstrap],
+    { stdio: 'ignore', env: buildEnv(true) },
   );
   return check.status === 0;
 }

package/bin/bootstrap.py

@@ -0,0 +1,69 @@
+"""Isolated entry point for the npm launcher.
+
+The npm package is not a Python installation.  This file adds only the Python
+sources and the vendored Python 3.10 TOML dependency shipped beside it, while
+leaving the selected interpreter's regular site-packages available for user
+callbacks.
+"""
+
+from __future__ import annotations
+
+import os
+import pathlib
+import runpy
+import sys
+
+
+_PACKAGE_ROOT = pathlib.Path(__file__).resolve().parent.parent
+_SHIPPED_SOURCE = _PACKAGE_ROOT / "src"
+_SHIPPED_TOMLI = _PACKAGE_ROOT / "vendor" / "tomli-2.4.0-py3-none-any.whl"
+_CAPABILITY_ENVIRONMENT = "AI_PUSH_HOOKS_INTERNAL_CAPABILITY"
+
+
+def _without_working_directory(entries: list[str]) -> list[str]:
+    working_directory = os.path.realpath(os.getcwd())
+    safe_entries: list[str] = []
+    for entry in entries:
+        if not entry or not os.path.isabs(entry):
+            continue
+        try:
+            if os.path.realpath(entry) == working_directory:
+                continue
+        except OSError:
+            continue
+        safe_entries.append(entry)
+    return safe_entries
+
+
+def _configure_imports() -> None:
+    """Retain interpreter site-packages and add only shipped import paths."""
+    sys.path[:] = _without_working_directory(sys.path)
+    sys.path.insert(0, str(_SHIPPED_TOMLI))
+    sys.path.insert(0, str(_SHIPPED_SOURCE))
+
+
+def _has_supported_toml() -> bool:
+    if sys.version_info < (3, 10):
+        return False
+    try:
+        if sys.version_info >= (3, 11):
+            import tomllib  # noqa: F401
+        else:
+            import tomli  # noqa: F401
+    except ImportError:
+        return False
+    return True
+
+
+def main() -> int:
+    _configure_imports()
+    if not _has_supported_toml():
+        return 1
+    if os.environ.get(_CAPABILITY_ENVIRONMENT) == "1":
+        return 0
+    runpy.run_module("ai_push_hooks", run_name="__main__")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/docs/configuration.md

@@ -4,12 +4,14 @@ Define workflows in `ai-push-hooks.toml` at the repository root. Start with the
 
 ## Installation
 
-The [npm quick start](../README.md#quick-start) installs a repository-local wrapper. It needs Node 18+ and Python 3.10-3.13 on the hook's `PATH`; the npm package does not bundle Python.
+The [npm quick start](../README.md#quick-start) installs a repository-local wrapper. Its tested/supported Python range is 3.10-3.13; the Python code requires 3.10+ and the launcher may probe newer interpreters, but newer versions are not part of that compatibility claim. The npm package does not bundle Python. The wrapper starts the selected interpreter in Python isolated mode: it ignores `PYTHONPATH` and the user site directory, then adds only the package's shipped `src` and vendored Tomli wheel. The interpreter's normal system or virtual-environment site-packages remain available.
+
+If a repository callback needs an external dependency, install it with the exact Python executable the wrapper will select (for example, `/path/to/python -m pip install <dependency>`), into that interpreter's normal system or virtual-environment site-packages. The wrapper tests candidates in its ordered list (`python3.14`, `python3.13`, `python3.12`, `python3.11`, `python3.10`, `python3`, then `python`), so activating a virtual environment alone does not guarantee that it wins over a higher-priority executable elsewhere on `PATH`; make the intended candidate discoverable first. Do not rely on `pip install --user` or `PYTHONPATH`; they are intentionally not part of the npm launch path.
 
 For pnpm:
 
 ```bash
-pnpm add -D ai-push-hooks@beta
+pnpm add -D ai-push-hooks
 pnpm exec ai-push-hooks init --template minimal-docs
 pnpm exec ai-push-hooks install
 ```
@@ -22,7 +24,7 @@ ai-push-hooks init --template minimal-docs
 ai-push-hooks install
 ```
 
-`uv tool install ai-push-hooks` or `pipx install ai-push-hooks` can replace the pip command. npm uses the `beta` tag while the package is in beta.
+`uv tool install ai-push-hooks` or `pipx install ai-push-hooks` can replace the pip command.
 
 AI steps need the selected CLI installed and authenticated with an available model. Deterministic-only workflows do not need one. `init` and `install` refuse to overwrite existing files; `--force` explicitly replaces them.
 
@@ -64,6 +66,8 @@ Upgrading from 0.2.1? Rename `type = "llm"` steps to `type = "ask"`.
 
 `[llm].runner` selects the default; a step's `runner` overrides it. Referenced profiles must exist under `[runners.<name>]`, except for the implicit OpenCode default.
 
+OpenCode, Codex, and Claude are first-class adapters. The generic `command` type is for other agentic CLIs and follows the custom runner contract below.
+
 | Profile field | Values / behavior |
 | --- | --- |
 | `type` | Required: `opencode`, `codex`, `claude`, or `command`. |
@@ -81,6 +85,27 @@ OpenCode runs with isolated configuration and permissions; project/global config
 
 Apply requires a single pushed branch whose local commit is the checked-out `HEAD`. Staging excludes Git metadata, `AGENTS.md`, ignored files, symlinks, and special files. These controls are not an OS sandbox or an automatic rollback system. See [Security](../SECURITY.md).
 
+### Live validation snapshot
+
+Live read/review and apply checks on Linux:
+
+| Date | Runner (CLI; model) | Review | Apply |
+| --- | --- | --- | --- |
+| 2026-09-12 | OpenCode (1.18.29; `openai/gpt-5.6-luna`) | Passed | Passed |
+| 2026-09-12 | Claude Code (2.1.220; `sonnet`) | Passed | Passed |
+| 2026-09-14 | Codex (0.152.0; `gpt-5.6-luna`) | Passed | Passed |
+
+The Codex check read a random value from a disposable repository, then verified
+that only the allowlisted README changed. These checks establish the tested
+operations, not compatibility with every model or platform.
+
+#### Local troubleshooting: Codex sandbox
+
+For Codex 0.152, the standalone no-AI sandbox syntax is
+`codex sandbox -- /usr/bin/true`. Resolve host restrictions rather than disabling
+protections, and use a deterministic postcondition to verify the desired checkout
+outcome after an apply.
+
 ### Apply and manual commits
 
 `apply` is generic: it can edit any eligible checkout file matching `allow_paths`; it is not limited to Markdown. The runner edits a temporary staging copy, and only validated changes propagate back to the checkout. Those edits do not enter the commit already being pushed, and `apply` never creates a Git commit.
@@ -97,9 +122,62 @@ inputs = ["apply/result.json"]
 
 The assertion checks `apply/result.json`'s `changed_files` and intentionally blocks when edits were propagated. Review `git diff`, run the relevant checks, commit the approved changes, and retry the push. On the retry, the assertion passes when the apply step reports no changes.
 
+### Deterministic postconditions after apply
+
+An apply process succeeding, or reporting `changed_files = []`, is not proof that
+the requested result is present. The latter can simply mean that the apply was a
+legitimate no-op because the checkout was already correct. Add a deterministic
+postcondition after `apply` and before the manual-commit gate when the desired
+file content has a precise representation:
+
+```toml
+[general]
+require_clean_worktree = true
+
+[workflow]
+modules = ["docs"]
+
+[modules.docs]
+enabled = true
+
+[[modules.docs.steps]]
+id = "apply"
+type = "apply"
+prompt = "In the existing README.md, replace 'Release note: DRAFT.' with 'Release note: READY.' and make no other changes."
+allow_paths = ["README.md"]
+
+[[modules.docs.steps]]
+id = "postcondition"
+type = "assert"
+command = [
+  "{python}",
+  "-c",
+  "import pathlib, sys; sys.exit(0 if pathlib.Path('README.md').read_text(encoding='utf-8') == 'Release note: READY.\\n' else 1)",
+]
+inputs = ["apply/result.json"]
+
+[[modules.docs.steps]]
+id = "manual-commit"
+type = "assert"
+assertion = "docs_apply_requires_manual_commit"
+inputs = ["apply/result.json"]
+```
+
+This is an intentional synthetic example, not a recommendation to overwrite a
+real README: its fixture starts with exactly `Release note: DRAFT.\n`, and its
+desired full content is exactly `Release note: READY.\n`.
+The command is a direct argv vector rather than a Python `assert`; Python
+optimization must not be able to remove the check. The postcondition reads the
+checkout after apply, not the commit being pushed. Keep the clean-worktree
+workflow setting for the hook's starting state and the manual-commit gate for
+the intentionally dirty post-apply checkout: review the resulting diff, run
+relevant checks, commit it, and retry the push. This gate and postcondition
+still do not prove human review, semantic correctness, or that an agent
+complied with every instruction.
+
 ## Custom Runners
 
-Use a command profile for another CLI, including Pi, or your own wrapper. This example expects a local `scripts/review-agent` program that reads the prompt from stdin and writes its final response to stdout:
+Use a `command` profile to invoke any other agentic CLI, including Pi, directly or through a thin wrapper. A wrapper can normalize JSONL events into a final response. The runner must be noninteractive: read the prompt from stdin or argv, write only the final response to stdout, and use exit codes to report success or failure.
 
 ```toml
 [runners.custom]
@@ -111,7 +189,7 @@ project_access = "project"
 
 Select it with `runner = "custom"` on an `ask` or `apply` step. The runner receives the full instruction and artifact packet. For apply, its working directory is the staging copy.
 
-Commands are argv arrays, not shell strings. Whole-argument placeholders are `{model}`, `{cwd}`, `{stage}`, and `{prompt}`. The `argv` transport requires exactly one `{prompt}` argument; stdin avoids exposing prompts in process listings. Custom programs inherit the user environment and own their permissions and session lifecycle.
+Commands are argv arrays, not shell strings. Whole-argument placeholders are `{model}`, `{cwd}`, `{stage}`, and `{prompt}`. The `argv` transport requires exactly one `{prompt}` argument; stdin avoids exposing prompts in process listings. Custom programs inherit the user's environment, including authentication variables, and manage their own permissions and session setup/cleanup. For apply, the working directory is the staging copy.
 
 ## Commands And Callbacks
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-push-hooks",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "Run structured AI-assisted checks and allowlisted maintenance before git push",
   "license": "MIT",
   "author": {

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ai-push-hooks"
-version = "0.3.2"
+version = "0.3.4"
 description = "Run structured AI-assisted checks and allowlisted maintenance before git push"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -12,7 +12,7 @@ license = "MIT"
 authors = [{ name = "Shane Bishop" }]
 keywords = ["git", "lefthook", "docs", "ai", "pre-push"]
 classifiers = [
-  "Development Status :: 4 - Beta",
+  "Development Status :: 5 - Production/Stable",
   "Intended Audience :: Developers",
   "Programming Language :: Python :: 3",
   "Programming Language :: Python :: 3 :: Only",

package/src/ai_push_hooks/cli.py

@@ -10,6 +10,7 @@ from .hook import run_hook
 from .install import install_hook
 from .paths import path_is_link_or_reparse, write_text_no_follow
 from .prompts_builtin import MINIMAL_DOCS_TEMPLATE
+from .executors.runners import RunnerError
 from .types import HookError
 
 
@@ -117,6 +118,6 @@ def main(argv: list[str] | None = None) -> int:
         if args.command == "install":
             return install_hook(args.force)
         raise HookError(f"Unknown command: {args.command}")
-    except HookError as exc:
+    except (HookError, RunnerError) as exc:
         sys.stderr.write(f"[ai-push-hooks] {exc}\n")
         return 1

package/src/ai_push_hooks/executors/apply.py

@@ -213,6 +213,20 @@ def _runtime_metadata_namespaces(context: RuntimeContext) -> tuple[pathlib.Path,
     return namespaces
 
 
+def _resolve_effective_hooks_path(context: RuntimeContext) -> pathlib.Path:
+    raw_hooks_path = run_command(
+        ["git", "rev-parse", "--git-path", "hooks"],
+        cwd=context.repo_root,
+        check=True,
+    ).stdout.strip()
+    if not raw_hooks_path:
+        raise HookError("Git did not return an effective hooks path")
+    hooks_path = pathlib.Path(raw_hooks_path)
+    if not hooks_path.is_absolute():
+        hooks_path = context.repo_root / hooks_path
+    return pathlib.Path(os.path.abspath(hooks_path))
+
+
 def _snapshot_git_control_metadata(context: RuntimeContext) -> MetadataSnapshot:
     git_dir = context.git_dir.resolve(strict=True)
     common_dir = resolve_git_common_dir(context.repo_root).resolve(strict=True)
@@ -323,15 +337,7 @@ def _snapshot_git_control_metadata(context: RuntimeContext) -> MetadataSnapshot:
     for name in ("HEAD", "config", "config.worktree", "packed-refs"):
         record(f"shared:{name}", common_dir / name)
     scan_tree("shared:refs", common_dir / "refs")
-    raw_hooks_path = run_command(
-        ["git", "rev-parse", "--git-path", "hooks"],
-        cwd=context.repo_root,
-        check=True,
-    ).stdout.strip()
-    hooks_path = pathlib.Path(raw_hooks_path)
-    if not hooks_path.is_absolute():
-        hooks_path = context.repo_root / hooks_path
-    hooks_path = pathlib.Path(os.path.abspath(hooks_path))
+    hooks_path = _resolve_effective_hooks_path(context)
     if any(is_path_within(hooks_path, namespace) for namespace in excluded_namespaces):
         raise HookError(
             "Configured core.hooksPath must not overlap ai-push-hooks runtime metadata: "
@@ -582,6 +588,12 @@ def _safe_destination(context: RuntimeContext, relative_path: str) -> pathlib.Pa
         raise HookError(
             f"Apply destination resolves inside Git metadata: {relative_path}"
         )
+    hooks_path = _resolve_effective_hooks_path(context).resolve(strict=False)
+    if is_path_within(resolved_destination, hooks_path):
+        raise HookError(
+            f"Apply destination resolves inside configured Git hooks path: "
+            f"{relative_path}"
+        )
     return destination
 
 
@@ -602,6 +614,12 @@ def _preflight_apply_operations(
     context: RuntimeContext,
     operations: list[ApplyOperation],
 ) -> None:
+    # Validate every destination before the propagation loop can create a
+    # parent directory or write even the first operation.  In particular, a
+    # configured core.hooksPath may not exist yet, so this guard cannot depend
+    # on the hooks tree being present in the checkout.
+    for operation in operations:
+        _safe_destination(context, operation.relative_path)
     conflicts = [
         operation.relative_path
         for operation in operations
@@ -647,7 +665,6 @@ def _propagate_staging_changes(
     operations: list[ApplyOperation] = []
     expected: dict[str, StagedFile | None] = {}
     for relative_path in sorted(changed_paths):
-        _safe_destination(context, relative_path)
         baseline = baselines.get(relative_path, DestinationState("missing"))
         staged = after.get(relative_path)
         if staged is None:

package/src/ai_push_hooks/executors/ask.py

@@ -63,14 +63,20 @@ def validate_schema(schema: str | None, payload: Any) -> Any:
     if schema == "beads_alignment_result":
         if not isinstance(payload, dict):
             raise HookError("Expected schema beads_alignment_result")
-        commands = payload.get("commands", [])
-        if commands is not None and (
-            not isinstance(commands, list)
-            or not all(isinstance(item, str) for item in commands)
+        unresolved = payload.get("unresolved")
+        if type(unresolved) is not bool:
+            raise HookError("beads_alignment_result.unresolved must be a boolean")
+        if "commands" in payload and (
+            not isinstance(payload["commands"], list)
+            or not all(isinstance(item, str) for item in payload["commands"])
         ):
             raise HookError(
                 "beads_alignment_result.commands must be an array of strings"
             )
+        if "report_markdown" in payload and not isinstance(
+            payload["report_markdown"], str
+        ):
+            raise HookError("beads_alignment_result.report_markdown must be a string")
         return payload
     if schema == "pr_create_payload":
         if not isinstance(payload, dict):

package/src/ai_push_hooks/executors/assertions.py

@@ -5,6 +5,7 @@ import pathlib
 from typing import Any
 
 from ..types import RuntimeContext, StepConfig
+from .ask import validate_schema
 
 
 def docs_apply_requires_manual_commit(
@@ -28,8 +29,10 @@ def beads_alignment_clean(
     _step: StepConfig,
     inputs: list[pathlib.Path],
 ) -> dict[str, Any]:
-    payload = json.loads(inputs[0].read_text(encoding="utf-8"))
-    unresolved = bool(payload.get("unresolved", False))
+    payload = validate_schema(
+        "beads_alignment_result", json.loads(inputs[0].read_text(encoding="utf-8"))
+    )
+    unresolved = payload["unresolved"]
     if unresolved:
         return {
             "ok": False,

package/src/ai_push_hooks/executors/exec.py

@@ -209,12 +209,10 @@ def beads_alignment_executor(
             "report_written": False,
             "unresolved": False,
         }
-    payload = json.loads(inputs[0].read_text(encoding="utf-8"))
-    if not isinstance(payload, dict):
-        raise HookError("beads_alignment payload must be an object")
+    payload = validate_schema(
+        "beads_alignment_result", json.loads(inputs[0].read_text(encoding="utf-8"))
+    )
     commands = payload.get("commands", [])
-    if not isinstance(commands, list):
-        raise HookError("beads_alignment commands must be an array")
     if len(commands) > BEADS_ALIGNMENT_MAX_COMMANDS:
         raise HookError(
             f"beads_alignment accepts at most {BEADS_ALIGNMENT_MAX_COMMANDS} commands"
@@ -245,8 +243,8 @@ def beads_alignment_executor(
         )
         commands_run.append(command)
 
-    report_markdown = str(payload.get("report_markdown", "")).strip()
-    unresolved = bool(payload.get("unresolved", False))
+    report_markdown = payload.get("report_markdown", "").strip()
+    unresolved = payload["unresolved"]
     report_written = False
     if report_markdown:
         if not report_markdown.endswith("\n"):

package/src/ai_push_hooks/executors/runners/contracts.py

@@ -403,25 +403,15 @@ def strip_terminal_controls(value: str) -> str:
     return _UNSAFE_TERMINAL_CONTROL_PATTERN.sub("", without_ansi)
 
 
-def redact_diagnostic(value: str, *, secrets: Sequence[str] = ()) -> str:
-    """Redact supplied secrets and common credential-shaped values."""
-
-    redacted = strip_terminal_controls(value)
-    for pattern in _SECRET_PATTERNS:
-        redacted = pattern.sub(
-            lambda match: (
-                f"{match.group(1)}[REDACTED]" if match.lastindex else "[REDACTED]"
-            ),
-            redacted,
-        )
-    redaction_values: list[str] = []
+def _diagnostic_redaction_values(secrets: Sequence[str]) -> tuple[str, ...]:
+    values: list[str] = []
     seen: set[str] = set()
     fragment_count = 0
     for secret in secrets:
         if not isinstance(secret, str) or not secret or secret in seen:
             continue
         seen.add(secret)
-        redaction_values.append(secret)
+        values.append(secret)
         # A bounded fragment set catches a child echoing one prompt token,
         # while skipping a whole large diff avoids the old O(words * stream)
         # behavior.  The request-sensitive helper additionally suppresses
@@ -430,12 +420,72 @@ def redact_diagnostic(value: str, *, secrets: Sequence[str] = ()) -> str:
             for fragment in _DIAGNOSTIC_FRAGMENT_PATTERN.findall(secret):
                 if fragment not in seen:
                     seen.add(fragment)
-                    redaction_values.append(fragment)
+                    values.append(fragment)
                     fragment_count += 1
                     if fragment_count >= 512:
                         break
             if fragment_count >= 512:
                 continue
+    return tuple(values)
+
+
+def _longest_prefix_suffix(value: str, prefix: str) -> int:
+    """Return the longest suffix of ``value`` that is a prefix of ``prefix``."""
+
+    limit = min(len(value), len(prefix))
+    if limit == 0:
+        return 0
+    pattern = prefix[:limit]
+    failure = [0] * limit
+    matched = 0
+    for index in range(1, limit):
+        while matched and pattern[matched] != pattern[index]:
+            matched = failure[matched - 1]
+        if pattern[matched] == pattern[index]:
+            matched += 1
+        failure[index] = matched
+
+    matched = 0
+    for character in value[-limit:]:
+        while matched and (matched == limit or pattern[matched] != character):
+            matched = failure[matched - 1]
+        if pattern[matched] == character:
+            matched += 1
+    return matched
+
+
+def _boundary_redaction_start(value: str, secrets: Sequence[str]) -> int | None:
+    """Find the earliest visible prefix of a known value at a cutoff."""
+
+    earliest: int | None = None
+    for secret in secrets:
+        if len(secret) <= 1:
+            continue
+        # The captured child stream may itself end while a known value is
+        # being emitted, so do not require the value's unseen suffix to exist
+        # in ``value``.  This comparison is bounded by the preview and secret
+        # prefix, rather than scanning an unbounded stream tail.
+        prefix = secret[: min(len(value), len(secret) - 1)]
+        overlap = _longest_prefix_suffix(value, prefix)
+        if overlap:
+            start = len(value) - overlap
+            if earliest is None or start < earliest:
+                earliest = start
+    return earliest
+
+
+def redact_diagnostic(value: str, *, secrets: Sequence[str] = ()) -> str:
+    """Redact supplied secrets and common credential-shaped values."""
+
+    redacted = strip_terminal_controls(value)
+    for pattern in _SECRET_PATTERNS:
+        redacted = pattern.sub(
+            lambda match: (
+                f"{match.group(1)}[REDACTED]" if match.lastindex else "[REDACTED]"
+            ),
+            redacted,
+        )
+    redaction_values = _diagnostic_redaction_values(secrets)
     for secret in sorted(redaction_values, key=len, reverse=True):
         redacted = redacted.replace(secret, "[REDACTED]")
     return redacted
@@ -454,10 +504,18 @@ def bounded_diagnostic(
     raw = str(value)
     # Redact only the bounded preview.  Anything after this point cannot be
     # present in the returned diagnostic, and therefore does not need a scan.
-    # Credential-shaped values which reach the preview boundary are still
-    # handled by the regex redactor before the preview is returned.
-    preview = raw[:max_chars]
+    # A known value can start in the preview and finish after it, though; mask
+    # that visible prefix after ordinary redaction so a complete match cannot
+    # be destroyed first.  Boundary matching is bounded even for large
+    # streams/secrets.
+    preview = strip_terminal_controls(raw[:max_chars])
+    redaction_values = _diagnostic_redaction_values(secrets)
     safe = redact_diagnostic(preview, secrets=secrets)
+    boundary_start = _boundary_redaction_start(safe, redaction_values)
+    if boundary_start is not None:
+        # Several known values can overlap at the cutoff.  Replace their
+        # union once so insertion cannot invalidate another span's index.
+        safe = safe[:boundary_start] + "[REDACTED]"
     if len(raw) <= max_chars and len(safe) <= max_chars:
         return safe
     if max_chars <= len(DIAGNOSTIC_TRUNCATION_MARKER):

package/src/ai_push_hooks/executors/step_commands.py

@@ -9,7 +9,6 @@ engine integration lane.
 from __future__ import annotations
 
 import math
-import os
 import pathlib
 import re
 import sys
@@ -26,7 +25,12 @@ from ..types import (
     RuntimeContext,
     StepConfig,
 )
-from .runners.contracts import bounded_diagnostic, redact_diagnostic
+from .runners.contracts import (
+    RunnerError,
+    RunnerExecutableNotFoundError,
+    RunnerSignalError,
+    RunnerTimeoutError,
+)
 from .runners.process import (
     DEFAULT_MAX_OUTPUT_BYTES,
     ProcessResult,
@@ -297,14 +301,26 @@ def run_step_command(
         inputs=input_paths,
         python_executable=python_executable or sys.executable,
     )
-    process_result = run_process(
-        argv,
-        cwd=pathlib.Path(repo_root).resolve(strict=True),
-        input_path=input_path,
-        timeout_seconds=timeout_seconds,
-        env=None,
-        max_output_bytes=max_output_bytes,
-    )
+    try:
+        process_result = run_process(
+            argv,
+            cwd=pathlib.Path(repo_root).resolve(strict=True),
+            input_path=input_path,
+            timeout_seconds=timeout_seconds,
+            env=None,
+            max_output_bytes=max_output_bytes,
+        )
+    except RunnerError as error:
+        # Do not retain process causes: they can contain rendered argv or
+        # captured stream bytes when displayed as an exception chain.
+        error.__cause__ = None
+        error.__suppress_context__ = True
+        if isinstance(error, RunnerExecutableNotFoundError):
+            # The command vector is configuration-controlled and may contain
+            # credentials.  Do not let the process layer's executable detail
+            # cross the step-command boundary.
+            error.args = ("step command executable was not found",)
+        raise
     result = _from_process_result(process_result)
     if result.stdout_truncated or result.stderr_truncated:
         streams = " and ".join(
@@ -320,31 +336,31 @@ def run_step_command(
         )
         error._step_command_result = result
         raise error
-    _validate_utf8(result)
+    try:
+        _validate_utf8(result)
+    except StepCommandEncodingError as error:
+        error.__cause__ = None
+        error.__suppress_context__ = True
+        raise
     return result
 
 
-def _environment_secrets() -> tuple[str, ...]:
-    markers = ("API_KEY", "TOKEN", "SECRET", "PASSWORD", "AUTH", "CREDENTIAL")
-    return tuple(
-        value
-        for name, value in os.environ.items()
-        if any(marker in name.upper() for marker in markers) and value
-    )
-
-
-def _assert_message(result: StepCommandResult) -> str:
-    # A process error can occur before the normal strict UTF-8 validation pass.
-    # Surrogateescape keeps that diagnostic bounded and non-throwing; the
-    # private stream artifacts still retain the exact original bytes.
-    stdout = result.stdout.decode("utf-8", errors="surrogateescape")
-    stderr = result.stderr.decode("utf-8", errors="surrogateescape")
-    combined = "\n".join(part for part in (stderr.strip(), stdout.strip()) if part)
-    safe = redact_diagnostic(combined, secrets=_environment_secrets())
-    return (
-        bounded_diagnostic(safe, max_chars=1_200)
-        or f"command exited with status {result.returncode}"
-    )
+def _command_failure_status(
+    error: BaseException, result: StepCommandResult | None
+) -> str:
+    if isinstance(error, RunnerTimeoutError):
+        return "timeout"
+    if isinstance(error, RunnerSignalError):
+        return "signal"
+    if isinstance(error, StepCommandEncodingError):
+        return "invalid_utf8"
+    if isinstance(error, StepCommandTruncatedError):
+        return "capture_limit"
+    if isinstance(error, RunnerExecutableNotFoundError):
+        return "not_started"
+    if result is not None:
+        return str(result.returncode)
+    return "error"
 
 
 def step_command_result_payload(
@@ -368,7 +384,7 @@ def step_command_result_payload(
     if step_type == "assert":
         payload["ok"] = result.returncode == 0
         if result.returncode != 0:
-            payload["message"] = _assert_message(result)
+            payload["message"] = f"command exited with status {result.returncode}"
     return payload
 
 
@@ -447,6 +463,7 @@ def execute_step_command(
         input_map = dict(zip(step.inputs, inputs))
     store = artifacts or ArtifactStore(context.run_dir)
     store.prepare()
+    persisted: PersistedStepCommandResult | None = None
     try:
         process_result = run_step_command(
             step.command,
@@ -459,42 +476,63 @@ def execute_step_command(
                 else DEFAULT_STEP_COMMAND_TIMEOUT_SECONDS
             ),
         )
+        payload = step_command_result_payload(process_result, step_type=step.type)
+        persisted = _persist_process_result(
+            store, state, step, process_result, payload=payload
+        )
+        if step.type == "exec" and process_result.returncode != 0:
+            error = StepCommandExecutionError(
+                "step exec command returned a non-zero status"
+            )
+            error._step_command_result = process_result
+            error._step_command_persisted = persisted
+            raise error
+        if step.type == "assert" and process_result.returncode != 0:
+            error = StepCommandAssertionError(str(payload["message"]))
+            error._step_command_result = process_result
+            error._step_command_persisted = persisted
+            raise error
     except BaseException as error:
         captured = _result_from_error(error)
         if captured is None:
             captured = getattr(error, "_step_command_result", None)
-        if isinstance(captured, StepCommandResult):
-            report = None
-            if isinstance(error, StepCommandEncodingError):
-                report = step_command_result_payload(captured, step_type=step.type)
-                report["malformed"] = True
-                report["message"] = "command output was not valid UTF-8"
-            persisted = _persist_process_result(
-                store,
-                state,
-                step,
-                captured,
-                payload=report,
-            )
+        captured_result = captured if isinstance(captured, StepCommandResult) else None
+        if captured_result is not None:
+            if persisted is None:
+                report = None
+                if isinstance(error, StepCommandEncodingError):
+                    report = step_command_result_payload(
+                        captured_result, step_type=step.type
+                    )
+                    report["malformed"] = True
+                    report["message"] = "command output was not valid UTF-8"
+                persisted = _persist_process_result(
+                    store,
+                    state,
+                    step,
+                    captured_result,
+                    payload=report,
+                )
             error._step_command_persisted = persisted
+        if isinstance(error, (RunnerError, StepCommandError)):
+            namespace = f"{state.module.id}/{state.step_index:02d}-{step.id}"
+            run_id = getattr(context, "run_id", store.run_dir.name)
+            location_suffix = "" if persisted is not None else " (not created)"
+            returncode = (
+                f"; returncode={captured_result.returncode}"
+                if captured_result is not None
+                else ""
+            )
+            error.args = (
+                f"command step={state.module.id}.{step.id} failed; "
+                f"status={_command_failure_status(error, captured_result)}; "
+                f"error_class={error.__class__.__name__}; "
+                f"artifact_location={run_id}/{namespace}{location_suffix}"
+                f"{returncode}",
+            )
         raise
-
-    payload = step_command_result_payload(process_result, step_type=step.type)
-    persisted = _persist_process_result(
-        store, state, step, process_result, payload=payload
-    )
-    if step.type == "exec" and process_result.returncode != 0:
-        error = StepCommandExecutionError(
-            "step exec command returned a non-zero status"
-        )
-        error._step_command_result = process_result
-        error._step_command_persisted = persisted
-        raise error
-    if step.type == "assert" and process_result.returncode != 0:
-        error = StepCommandAssertionError(str(payload["message"]))
-        error._step_command_result = process_result
-        error._step_command_persisted = persisted
-        raise error
+    if persisted is None:  # pragma: no cover - successful persistence is required above
+        raise StepCommandError("step command result was not persisted")
     return persisted
 
 

package/src/ai_push_hooks/git_utils.py

@@ -543,8 +543,11 @@ def collect_changed_files(repo_root: pathlib.Path, ranges: list[str]) -> list[st
             [
                 "git",
                 "diff",
+                "--no-ext-diff",
+                "--no-textconv",
+                "--no-color",
                 "--name-only",
-                "--diff-filter=ACMRD",
+                "--diff-filter=ACMRDT",
                 "-z",
                 range_expr,
             ],
@@ -639,7 +642,15 @@ def collect_diff(repo_root: pathlib.Path, ranges: list[str], max_bytes: int) ->
 
         body, body_truncated = _collect_bounded_git_diff(
             repo_root,
-            ["git", "diff", "--unified=3", range_expr],
+            [
+                "git",
+                "diff",
+                "--no-ext-diff",
+                "--no-textconv",
+                "--no-color",
+                "--unified=3",
+                range_expr,
+            ],
             limit - len(output),
         )
         if not body_truncated:

package/src/ai_push_hooks/hook.py

@@ -21,11 +21,11 @@ from .git_utils import (
     current_branch,
     ensure_dir,
     env_bool,
-    git,
     parse_push_updates,
     resolve_git_dir,
     resolve_repo_root,
     resolve_storage_path,
+    run_command,
     should_skip_for_sync_branch,
     unique_range_expressions,
 )
@@ -65,7 +65,10 @@ def _write_summary(context: RuntimeContext, result: dict[str, object]) -> None:
 
 
 def _assert_clean_worktree(repo_root: pathlib.Path) -> None:
-    status = git(repo_root, ["status", "--short"], check=False).strip()
+    completed = run_command(["git", "status", "--short"], cwd=repo_root, check=False)
+    if completed.returncode != 0:
+        raise HookError("Hook requires a clean worktree but Git status failed")
+    status = (completed.stdout or "").strip()
     if status:
         raise HookError("Hook requires a clean worktree but local changes are present")
 

package/src/ai_push_hooks/modules/docs.py

@@ -9,7 +9,13 @@ from pathlib import PurePosixPath
 from typing import Any
 
 from ..types import CollectorResult, RuntimeContext
-from ..git_utils import collect_commit_messages_for_ranges, git, path_matches
+from ..git_utils import (
+    collect_commit_messages_for_ranges,
+    git,
+    path_matches,
+    run_command,
+)
+from ..paths import path_is_link_or_reparse
 
 DOC_INCLUDE_PATTERNS = ("README.md", "docs/**/*.md")
 DOC_IGNORE_PATTERNS = ("docs/archive/**",)
@@ -34,7 +40,7 @@ def _is_safe_doc_file(repo_root: pathlib.Path, candidate: pathlib.Path) -> bool:
         current = repo_root
         for part in relative.parts:
             current /= part
-            if stat.S_ISLNK(current.lstat().st_mode):
+            if path_is_link_or_reparse(current):
                 return False
         candidate_stat = candidate.lstat()
         if not stat.S_ISREG(candidate_stat.st_mode):
@@ -47,18 +53,40 @@ def _is_safe_doc_file(repo_root: pathlib.Path, candidate: pathlib.Path) -> bool:
 
 
 def _expand_doc_files(repo_root: pathlib.Path) -> list[pathlib.Path]:
+    """List safe, relevant docs from Git's tracked/unignored file inventory.
+
+    ``--cached`` retains tracked files even when an ignore rule matches them;
+    ``--others --exclude-standard`` adds only untracked files that Git would
+    consider visible.  Enumerating this way avoids walking ignored directories
+    before any document content is opened.
+    """
     repo_root = repo_root.resolve(strict=True)
+    listed = run_command(
+        ["git", "ls-files", "--cached", "--others", "--exclude-standard", "-z"],
+        cwd=repo_root,
+        check=True,
+    )
+
     files: list[pathlib.Path] = []
-    for candidate in repo_root.rglob("*.md"):
-        relative = candidate.relative_to(repo_root).as_posix()
+    seen: set[str] = set()
+    for relative in listed.stdout.split("\x00"):
+        if not relative or relative in seen:
+            continue
+        seen.add(relative)
         if not _path_matches(relative, DOC_INCLUDE_PATTERNS):
             continue
         if _path_matches(relative, DOC_IGNORE_PATTERNS):
             continue
+        # Git emits POSIX separators even on platforms where a backslash has
+        # path semantics.  Reject such ambiguous names there rather than
+        # allowing a listed filename to change the lexical containment check.
+        if os.name == "nt" and "\\" in relative:
+            continue
+        candidate = repo_root.joinpath(*relative.split("/"))
         if not _is_safe_doc_file(repo_root, candidate):
             continue
         files.append(candidate)
-    return sorted(files)
+    return sorted(files, key=lambda path: path.relative_to(repo_root).as_posix())
 
 
 def _deterministic_seed_queries(diff_text: str, changed_files: list[str]) -> list[str]:

package/src/ai_push_hooks/paths.py

@@ -104,6 +104,18 @@ def resolve_contained_path(base: pathlib.Path, raw: str, label: str) -> pathlib.
     return resolved_candidate
 
 
+def _ensure_private_directory_component(directory: pathlib.Path) -> None:
+    try:
+        directory.mkdir(mode=PRIVATE_DIRECTORY_MODE)
+    except FileExistsError:
+        # Tolerate a concurrent creator winning the mkdir race, then validate
+        # the result before changing its permissions.
+        pass
+    if path_is_link_or_reparse(directory) or not directory.is_dir():
+        raise HookError(f"Private runtime path is not a safe directory: {directory}")
+    os.chmod(directory, PRIVATE_DIRECTORY_MODE)
+
+
 def ensure_private_directory(
     path: pathlib.Path,
     *,
@@ -119,8 +131,7 @@ def ensure_private_directory(
         if path_is_link_or_reparse(current) or not current.is_dir():
             raise HookError(f"Private runtime directory has an unsafe parent: {path}")
         for directory in reversed(missing):
-            directory.mkdir(mode=PRIVATE_DIRECTORY_MODE)
-            os.chmod(directory, PRIVATE_DIRECTORY_MODE)
+            _ensure_private_directory_component(directory)
         if path_is_link_or_reparse(target) or not target.is_dir():
             raise HookError(f"Private runtime directory is unsafe: {path}")
         os.chmod(target, PRIVATE_DIRECTORY_MODE)
@@ -141,11 +152,12 @@ def ensure_private_directory(
             raise HookError(
                 f"Private runtime directory traverses a symlink or reparse point: {directory}"
             )
-        if not directory.exists():
-            directory.mkdir(mode=PRIVATE_DIRECTORY_MODE)
-        if not directory.is_dir():
-            raise HookError(f"Private runtime path is not a directory: {directory}")
-        os.chmod(directory, PRIVATE_DIRECTORY_MODE)
+        if directory.exists():
+            if not directory.is_dir():
+                raise HookError(f"Private runtime path is not a directory: {directory}")
+            os.chmod(directory, PRIVATE_DIRECTORY_MODE)
+        else:
+            _ensure_private_directory_component(directory)
     return target
 
 

package/src/ai_push_hooks/plugin_loader.py

@@ -13,10 +13,12 @@ from __future__ import annotations  # noqa: I001
 import errno
 import hashlib
 import inspect
+import itertools
 import os
 import pathlib
 import re
 import stat
+import sys
 import threading
 from collections.abc import Callable, Mapping, Sequence
 from types import ModuleType
@@ -35,6 +37,8 @@ _CALLABLE_PATTERN = re.compile(r"[A-Za-z_][A-Za-z0-9_]*\Z")
 _SOURCE_ENCODING = "utf-8"
 PLUGIN_SOURCE_MAX_BYTES = 1 * 1024 * 1024
 _SOURCE_READ_CHUNK_BYTES = 64 * 1024
+_MODULE_NUMBER = itertools.count(1)
+_MODULE_NUMBER_LOCK = threading.Lock()
 _OS_OPEN = os.open
 _DESCRIPTOR_RELATIVE_SUPPORTED = bool(
     getattr(os, "O_DIRECTORY", 0)
@@ -221,7 +225,6 @@ class PluginLoader:
         self._cache: dict[tuple[pathlib.Path, pathlib.Path], ModuleType] = {}
         self._lock = threading.RLock()
         self._source_locks: dict[tuple[pathlib.Path, pathlib.Path], threading.Lock] = {}
-        self._module_number = 0
 
     def _source_lock(self, key: tuple[pathlib.Path, pathlib.Path]) -> threading.Lock:
         with self._lock:
@@ -248,7 +251,12 @@ class PluginLoader:
         # to the lexical cache key for a safe repository file.
         try:
             source_text = source.decode(_SOURCE_ENCODING)
-            code = compile(source_text, str(callback_path), "exec")
+            code = compile(
+                source_text,
+                str(callback_path),
+                "exec",
+                dont_inherit=True,
+            )
         except UnicodeDecodeError:
             raise HookError(
                 f"Python plugin {relative_path}:{callable_name} source is not valid UTF-8"
@@ -258,16 +266,18 @@ class PluginLoader:
                 f"Python plugin {relative_path}:{callable_name} could not be compiled"
             ) from None
 
-        with self._lock:
-            self._module_number += 1
-            module_number = self._module_number
+        with _MODULE_NUMBER_LOCK:
+            module_number = next(_MODULE_NUMBER)
         digest = hashlib.sha256(f"{root}\0{callback_path}".encode()).hexdigest()[:16]
         module_name = f"ai_push_hooks_plugin_{digest}_{module_number}"
         module = ModuleType(module_name)
         module.__file__ = str(callback_path)
         module.__package__ = ""
+        imported = False
+        sys.modules[module_name] = module
         try:
             exec(code, module.__dict__)  # noqa: S102
+            imported = True
         except KeyboardInterrupt:
             raise
         except SystemExit:
@@ -290,6 +300,9 @@ class PluginLoader:
             raise HookError(
                 f"Python plugin {relative_path}:{callable_name} failed during import"
             ) from None
+        finally:
+            if not imported and sys.modules.get(module_name) is module:
+                del sys.modules[module_name]
         return module
 
     def load(self, repo_root: pathlib.Path, reference: str) -> Callable[..., Any]:

package/vendor/README.md

@@ -2,7 +2,7 @@
 
 The npm package includes the unmodified pure-Python wheel for [Tomli](https://pypi.org/project/tomli/2.4.0/). Python 3.10 uses it to parse TOML; Python 3.11+ uses the standard-library `tomllib` module.
 
-The wrapper adds the wheel to `PYTHONPATH`, so no pip install, install script, or runtime download is needed. The wheel includes Tomli's MIT license under `tomli-2.4.0.dist-info/licenses/LICENSE`.
+The npm bootstrap adds the wheel directly to Python's import path, so no pip install, install script, or runtime download is needed. It does not inherit `PYTHONPATH`. The wheel includes Tomli's MIT license under `tomli-2.4.0.dist-info/licenses/LICENSE`.
 
 To reproduce the bundled download from the repository root: