ai-push-hooks 0.3.0 → 0.3.1

package/SECURITY.md

@@ -52,8 +52,9 @@ or the environment. A single-file callback may import dependencies already
 installed in the interpreter running the hook, but the host never runs `pip`;
 sibling/package-relative imports and installed-module references are not a
 supported loading mechanism. The callback runs in-process as trusted user code:
-there is no SDK, sandbox, filesystem write prevention, or enforceable hard
-timeout. Its `PluginContext` has frozen mappings/snapshots and validated `Path`
+there is no SDK, sandbox, filesystem write prevention, or in-process timeout.
+The configured timeout applies to child runner processes, not callback code.
+Its `PluginContext` has frozen mappings/snapshots and validated `Path`
 values, but those paths do not make file contents read-only. Callback prints and
 direct writes can disclose or modify host data and are outside host
 sanitization. Use a separately managed low-privilege process/container/VM when
@@ -97,22 +98,26 @@ captured stdout/stderr are each bounded to 16 MiB; staging is bounded to 10,000
 entries/256 MiB and Git metadata snapshots to 20,000 entries/64 MiB. These
 limits are resource and scope controls, not isolation. Existing baseline checks
 are not an atomic CAS against arbitrary external writers, and automatic rollback
-is avoided to protect pre-existing user changes. See the README's [runner
-profiles and access modes](README.md#runner-profiles-and-access-modes).
+is avoided to protect pre-existing user changes. See [runner profiles and
+access modes](docs/configuration.md#runner-profiles).
+
+Apply intentionally repeats integrity and state scans: it snapshots the checkout
+and Git metadata, inventories staging before and after the runner, checks each
+propagation operation against its baseline, and verifies the propagated result
+and protected state afterward. These repeated checks are defense in depth, not
+an atomic CAS or an automatic rollback.
 
 Timeout cleanup has platform limits: POSIX uses a private process group on a
 best-effort basis, while Windows can terminate only the direct child. Neither
 is a sandbox; Windows has no native beta evidence.
 
-## Tested security boundary
-
-The final pinned-Lefthook suite passed **407 tests with no skips**. The current
-evidence also includes the real OpenCode **1.18.29** contract smoke test with an
-in-process loopback mock provider and no external model call; its read probe
-checks that no Git-visible project files were mutated. It does not cover every
-provider, model, authentication mode, or live `apply` path.
-Installed Codex **0.148.0** and Claude **2.1.220** checks use only version/help
-output. Live Codex/Pi verification was intentionally not run pending separate
-approval; Claude live verification is pending because no subscription is
-available. Treat generated-hook path checks and the Lefthook runner as
-integration safeguards, not isolation boundaries.
+## Historical 0.3.0 security evidence
+
+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.
+Treat generated-hook path checks and the Lefthook runner as integration
+safeguards, not isolation boundaries.

package/bin/ai-push-hooks.js

@@ -6,16 +6,16 @@ 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 pythonCommands = ['python3.14', 'python3.13', 'python3.12', 'python3.11', 'python3', 'python'];
+const pythonCommands = ['python3.14', 'python3.13', 'python3.12', 'python3.11', 'python3.10', 'python3', 'python'];
 
 function buildEnv() {
   const env = { ...process.env };
   env.AI_PUSH_HOOKS_NODE_EXECUTABLE = process.execPath;
   env.AI_PUSH_HOOKS_NODE_SCRIPT = fs.realpathSync(__filename);
-  env.PYTHONPATH = env.PYTHONPATH
-    ? `${srcDir}${path.delimiter}${env.PYTHONPATH}`
-    : srcDir;
+  // Pure-Python wheels are importable archives; no pip or install scripts needed.
+  env.PYTHONPATH = [srcDir, tomliWheel, env.PYTHONPATH].filter(Boolean).join(path.delimiter);
   return env;
 }
 
@@ -33,7 +33,7 @@ function canRunPackage(command) {
       '-c',
       'import sys; assert sys.version_info >= (3, 10); __import__("tomllib" if sys.version_info >= (3, 11) else "tomli")',
     ],
-    { stdio: 'ignore' },
+    { stdio: 'ignore', env: buildEnv() },
   );
   return check.status === 0;
 }
@@ -41,7 +41,7 @@ function canRunPackage(command) {
 const pythonCommand = pythonCommands.find(canRunPackage);
 if (!pythonCommand) {
   console.error(
-    '[ai-push-hooks] Python 3.11+ is required for npm installs. Python 3.10 can be used if tomli is installed.',
+    '[ai-push-hooks] Python 3.10+ is required and must be available on PATH.',
   );
   process.exit(1);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-push-hooks",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Run structured AI-assisted checks and allowlisted maintenance before git push",
   "license": "MIT",
   "author": {
@@ -30,12 +30,13 @@
     "ai-push-hooks": "bin/ai-push-hooks.js"
   },
   "scripts": {
-    "test": "uv run --no-project --with pytest pytest tests -q",
+    "test": "uv run --no-project --with pytest --with build --with pip --with \"tomli; python_version < '3.11'\" pytest tests -q",
     "test:npm-pack": "node tests/npm-pack-smoke.mjs"
   },
   "files": [
     "bin",
     "src/**/*.py",
+    "vendor",
     "README.md",
     "CHANGELOG.md",
     "SECURITY.md",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ai-push-hooks"
-version = "0.3.0"
+version = "0.3.1"
 description = "Run structured AI-assisted checks and allowlisted maintenance before git push"
 readme = "README.md"
 requires-python = ">=3.10"

package/src/ai_push_hooks/artifacts.py

@@ -194,16 +194,3 @@ class ArtifactStore:
                 )
             raise HookError(f"Unknown artifact reference: {reference}")
         return path
-
-    def register_external(
-        self,
-        state: ModuleRuntimeState,
-        module_id: str,
-        step_id: str,
-        artifact_name: str,
-        path: pathlib.Path,
-    ) -> None:
-        validate_path_component(module_id, "Artifact module id")
-        validate_path_component(step_id, "Artifact step id")
-        validate_path_component(artifact_name, "Artifact name")
-        state.artifacts[f"{module_id}:{step_id}/{artifact_name}"] = path

package/src/ai_push_hooks/config.py

@@ -8,7 +8,7 @@ import stat
 from collections.abc import Mapping
 from typing import Any
 
-from .executors.exec import env_bool, resolve_git_common_dir, resolve_git_dir
+from .git_utils import env_bool, resolve_git_common_dir, resolve_git_dir
 from .paths import (
     is_path_within,
     normalized_component,
@@ -19,6 +19,7 @@ from .paths import (
 )
 from .prompts_builtin import BUILTIN_PROMPTS
 from .types import (
+    DEFAULT_STEP_COMMAND_TIMEOUT_SECONDS,
     SUPPORTED_STEP_TYPES,
     GeneralConfig,
     HookConfig,
@@ -106,7 +107,6 @@ EMBEDDED_COMMAND_PLACEHOLDER_PATTERN = re.compile(
     r"\{(?:repo|python|input:[A-Za-z0-9_./:-]+)\}"
 )
 COMMAND_PLACEHOLDER_NAMES = frozenset({"repo", "python"})
-DEFAULT_STEP_COMMAND_TIMEOUT_SECONDS = 60
 RUNNER_PLACEHOLDER_PATTERN = re.compile(r"\{[^{}]*\}")
 
 
@@ -683,7 +683,9 @@ def _build_config(
                 _normalize_step(
                     step,
                     f"modules.{module_id}.steps[{index}]",
-                    repo_root=repo_root,
+                    # Repository filesystem checks are performed once below,
+                    # after environment overrides have been resolved.
+                    repo_root=None,
                 )
                 for index, step in enumerate(steps_raw, start=1)
             ),
@@ -693,10 +695,14 @@ def _build_config(
     # while preserving the existing runtime model that only workflow modules are
     # materialized in HookConfig.modules.
     if repo_root is not None:
+        validated_python_references: set[str] = set()
         for module_id, module_raw in module_payload.items():
             for index, step_raw in enumerate(module_raw.get("steps", []) or [], start=1):
                 python_ref = step_raw.get("python")
                 if python_ref is not None:
+                    if python_ref in validated_python_references:
+                        continue
+                    validated_python_references.add(python_ref)
                     _validate_python_reference(
                         python_ref,
                         f"modules.{module_id}.steps[{index}].python",
@@ -789,7 +795,10 @@ def resolve_runner_profile(
 
 
 def _apply_env_overrides(
-    config: HookConfig, *, repo_root: pathlib.Path | None = None
+    config: HookConfig,
+    *,
+    repo_root: pathlib.Path | None = None,
+    raw_modules: dict[str, Any] | None = None,
 ) -> HookConfig:
     raw = {
         "general": {
@@ -830,6 +839,10 @@ def _apply_env_overrides(
             "enabled": module.enabled,
             "steps": step_payloads,
         }
+    if raw_modules is not None:
+        # Keep disabled and unselected modules in the final build so their
+        # callback references are validated without materializing them.
+        raw["modules"] = raw_modules
     for name, profile in config.runners.items():
         runner_raw: dict[str, Any] = {
             "type": profile.type,
@@ -930,8 +943,9 @@ def load_config(repo_root: pathlib.Path) -> tuple[HookConfig, pathlib.Path]:
     _validate_model_override(model_override)
     _validate_variant_override(variant_override)
     return _apply_env_overrides(
-        _build_config(loaded, effective_model=model_override, repo_root=repo_root),
+        _build_config(loaded, effective_model=model_override, repo_root=None),
         repo_root=repo_root,
+        raw_modules=loaded.get("modules", {}),
     ), config_path
 
 

package/src/ai_push_hooks/engine.py

@@ -8,7 +8,8 @@ from .artifacts import ArtifactStore
 from .config import resolve_prompt_text
 from .executors.apply import run_apply_step
 from .executors.assertions import ASSERTION_HANDLERS
-from .executors.exec import EXEC_HANDLERS, env_bool
+from .executors.exec import EXEC_HANDLERS
+from .git_utils import env_bool
 from .executors.ask import run_ask_step
 from .executors.step_commands import execute_step_command
 from .modules import COLLECTORS

package/src/ai_push_hooks/executors/apply.py

@@ -21,15 +21,15 @@ from ..paths import (
     sanitize_file_mode,
 )
 from ..types import HookError, ModuleRuntimeState, RuntimeContext, StepConfig
-from .exec import (
+from ..git_utils import (
     list_repo_changes,
     path_matches,
     resolve_git_common_dir,
     resolve_git_dir,
     run_command,
 )
-from .ask import validate_opencode_attachments
 from .runner_workflow import run_runner_once
+from .runners.opencode_support import validate_hook_owned_artifacts
 
 METADATA_MAX_FILES = 20_000
 METADATA_MAX_BYTES = 64 * 1024 * 1024
@@ -815,7 +815,7 @@ def run_apply_step(
     input_paths: list[pathlib.Path],
     stage_name: str,
 ) -> dict[str, object]:
-    validated_inputs = validate_opencode_attachments(context, input_paths)
+    validated_inputs = validate_hook_owned_artifacts(context, input_paths)
     for input_path in validated_inputs:
         if input_path.name.endswith("issues.json"):
             issues = json.loads(input_path.read_text(encoding="utf-8"))