ai-push-hooks 0.2.1 → 0.3.1

package/SECURITY.md

@@ -8,9 +8,29 @@ Please do not open a public issue for a suspected vulnerability. Report it priva
 
 ai-push-hooks treats repository content, Git paths and metadata, configuration, model output, and concurrent local filesystem changes as potentially unsafe. Its controls constrain model-visible inputs and apply destinations, protect Git metadata and instruction files, validate filesystem state before propagation, and fail closed by default. They are designed to prevent accidental or model-directed changes outside configured boundaries, not to protect against a malicious user or process with the same operating-system permissions.
 
-OpenCode is a separate local process and communicates with the model provider selected in `[llm].model`. Diffs, changed-file context, prompts, and step artifacts can therefore leave the machine under that provider's terms. ai-push-hooks retains OpenCode's existing authentication data directory and forwards recognized provider credential environment variables, including `OPENAI_API_KEY`; OpenCode itself chooses authentication using its normal precedence. Built-in authentication plugins remain available, while `--pure` excludes external plugins and the isolated project/config setup excludes project/global plugins, MCP servers, instructions, and custom-provider configuration. Do not commit secrets, and review provider retention and privacy policies before use on sensitive repositories.
+Every selected runner is a separate local process. Diffs, changed-file context,
+prompts, artifacts, and (in project mode) more repository content can therefore
+leave the machine under the selected provider's terms. OpenCode retains its
+existing authentication data directory and forwards recognized provider
+environment variables, including `OPENAI_API_KEY`; OpenCode itself chooses the
+authentication path. Codex, Claude, and custom commands inherit the user's
+normal environment/home needed by their tooling. Authentication is user-owned:
+ai-push-hooks does not log environment values, manage credentials, invoke login,
+or provide a credential broker. Do not commit secrets, and review provider
+retention, privacy, and billing policies before use on sensitive repositories.
 
-Hook logs, summaries, run artifacts, and transcripts are stored locally under `.git/ai-push-hooks/` with private runtime permissions. Transcript capture defaults to **on** at `.git/ai-push-hooks/transcripts`; set `logging.capture_llm_transcript = false` to disable it. OpenCode session deletion defaults to on, but provider-side retention is controlled by the provider.
+OpenCode's `--pure` and isolated configuration exclude external plugins,
+project/global configuration, MCP servers, instructions, and global custom
+providers while retaining built-in plugins such as Codex OAuth. The default
+OpenCode profile remains artifact-only; project access is an explicit opt-in.
+
+Hook logs, summaries, run artifacts, and OpenCode transcripts are stored locally
+under `.git/ai-push-hooks/` with private runtime permissions. Transcript capture
+defaults to **on** at `.git/ai-push-hooks/transcripts`; set
+`logging.capture_llm_transcript = false` to disable it. OpenCode session deletion
+defaults to on, but provider-side retention is controlled by the provider.
+Codex and Claude are ephemeral/no-persistence by default, and command profiles
+have no inferred transcript lifecycle.
 
 Transcript export is best effort. If export fails or produces no usable output,
 the run emits a warning and still applies the configured session-deletion
@@ -18,18 +38,86 @@ policy; it does not claim that a transcript was captured. A provider may have
 already received the request even when local export fails. Do not use local
 transcript files as proof that provider-side data was deleted.
 
-## Sandbox limitation
+## Repository callbacks and commands
+
+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
+configurations must be updated when upgrading.
+
+A callback reference is one contained, no-follow regular `.py` file plus one
+top-level callable. It is loaded lazily only after module, environment, and
+input gates, and cached once per run. Loading does not mutate `sys.path`, cwd,
+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 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
+that boundary is required.
+
+Command steps use direct argv with no implicit shell, repository-root cwd,
+inherited environment, and EOF on stdin unless an exact declared input is
+selected. `{repo}`, `{python}`, and `{input:<logical-ref>}` are substituted only
+as whole argv elements; unknown tokens in the reserved grammar and embedded
+recognized tokens are rejected, while ordinary brace text is preserved. The
+default command timeout is 60 seconds. stdout/stderr are private, unredacted
+`stdout.txt`/`stderr.txt` artifacts and are not printed by default. Each stream
+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.
+
+Read-only `collect` callback work may overlap up to `max_parallel`; trusted
+callback/command authors must provide their own concurrency safety. `exec` and
+`assert` remain serialized, and `apply` remains a separate staged, allowlisted
+operation.
+
+## Boundary and apply limitations
+
+OpenCode permissions and temporary-workspace isolation are **not an
+operating-system sandbox**. There is no mandatory command allowlist, shell
+parser, container, credential broker, or trust prompt. Custom commands are
+arbitrary user-authorized argv programs and a nominally read-only custom `ask`
+profile is not enforced as read-only. `collect`/`ask` work may overlap up to
+`max_parallel`; trusted custom commands must tolerate that. `apply` is globally
+serialized, but this does not prevent a same-user process from changing the
+host.
+
+Project apply uses a point-in-time staging projection. It excludes ignored files
+including tracked-but-ignored files, Git metadata, casefolded/Unicode-normalized
+`AGENTS.md` paths, symlinks/reparse points, and special files. Propagation still
+requires `allow_paths` plus destination and Git-state checks. Runner inputs and
+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 [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.
 
-OpenCode permissions and temporary-workspace isolation are **not an operating-system sandbox**. The process retains the invoking user's OS-level access, and bounded snapshots cannot observe every ignored path, Git object/LFS store, shared reflog, other linked-worktree metadata, or race with an independent local process. Use an OS sandbox, container, VM, or dedicated low-privilege account when stronger isolation is required. See the README's [OpenCode isolation limits](README.md#opencode-isolation-limits) for the detailed guarantees and exclusions.
+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
+## Historical 0.3.0 security evidence
 
-The beta evidence covers the real OpenCode **1.18.29** permission contract in a
-no-network Docker fixture and a limited synthetic provider run using a model
-that was listed as free at test time,
-`opencode/muse-spark-1.3-contributor-free`. Free-model catalogs and pricing can
-change; verify the current catalog before use. This evidence does not cover
-every provider, model, authentication mode, or live `apply` path. Windows has
-no native beta evidence. Treat the generated hook's repository-local path
-checks and the Lefthook runner as integration safeguards, not isolation
-boundaries.
+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/ai-push-hooks.toml

@@ -6,6 +6,11 @@ skip_on_sync_branch = true
 base_branch = "main"
 
 [llm]
+# Compatibility default: OpenCode receives validated hook artifacts only.
+# Define [runners.<name>] and select it with [llm].runner, or override an
+# individual ask/apply step with runner = "<name>". Project access is explicit.
+# Repository callbacks use python = "path/to/file.py:callable" and command
+# steps use a direct argv array; both are trusted local code.
 runner = "opencode"
 model = "openai/gpt-5.6-terra"
 variant = ""
@@ -17,6 +22,8 @@ json_retry_new_session = true
 delete_session_after_run = true
 
 [logging]
+# Transcripts are OpenCode-only lifecycle exports; other runners are ephemeral
+# or command-owned. print_llm_output, when enabled, is normalized/redacted text.
 level = "status"
 jsonl = true
 dir = ".git/ai-push-hooks/logs"
@@ -37,7 +44,7 @@ collector = "docs_context"
 
 [[modules.docs.steps]]
 id = "query"
-type = "llm"
+type = "ask"
 prompt = """
 Given the attached diff and changed file list, output a JSON array of concise
 documentation search queries. Return JSON only.
@@ -48,7 +55,7 @@ schema = "string_array"
 
 [[modules.docs.steps]]
 id = "analyze"
-type = "llm"
+type = "ask"
 prompt = """
 Review the diff and matched docs excerpts. Return JSON issues only for factual
 documentation drift caused by the code changes.

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.2.1",
+  "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.2.1"
+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

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import json
 import pathlib
+from collections.abc import Mapping
 from datetime import datetime, timezone
 from typing import Any
 from uuid import uuid4
@@ -13,11 +14,16 @@ from .paths import (
     path_is_link_or_reparse,
     resolve_contained_path,
     validate_path_component,
+    atomic_write_bytes,
     write_text_no_follow,
 )
 from .types import HookError, ModuleRuntimeState
 
 
+PLUGIN_ARTIFACT_MAX_BYTES = 16 * 1024 * 1024
+PLUGIN_COLLECT_ARTIFACTS_MAX_BYTES = 64 * 1024 * 1024
+
+
 def generate_run_id() -> str:
     timestamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%S%fZ")
     return f"{timestamp}-{uuid4().hex[:8]}"
@@ -94,6 +100,22 @@ class ArtifactStore:
         write_text_no_follow(path, content)
         return self.register(state, step_id, artifact_name, path)
 
+    def write_bytes(
+        self,
+        state: ModuleRuntimeState,
+        step_index: int,
+        step_id: str,
+        artifact_name: str,
+        content: bytes,
+    ) -> pathlib.Path:
+        """Write an exact, private byte artifact and register it."""
+
+        if not isinstance(content, bytes):
+            raise TypeError("Artifact byte content must be bytes")
+        path = self._artifact_path(state.module.id, step_index, step_id, artifact_name)
+        atomic_write_bytes(path, content)
+        return self.register(state, step_id, artifact_name, path)
+
     def write_json(
         self,
         state: ModuleRuntimeState,
@@ -106,6 +128,51 @@ class ArtifactStore:
         write_text_no_follow(path, json.dumps(payload, ensure_ascii=True, indent=2) + "\n")
         return self.register(state, step_id, artifact_name, path)
 
+    def serialize_plugin_artifacts(
+        self,
+        artifacts: Mapping[str, str | dict[str, Any] | list[Any]],
+        *,
+        max_artifact_bytes: int = PLUGIN_ARTIFACT_MAX_BYTES,
+        max_total_bytes: int = PLUGIN_COLLECT_ARTIFACTS_MAX_BYTES,
+    ) -> dict[str, bytes]:
+        """Serialize callback artifacts before any output is written.
+
+        Plugin results are intentionally serialized in the same format as the
+        existing collector path.  Doing the complete serialization and budget
+        check up front prevents a later oversized artifact from leaving an
+        earlier callback artifact registered in the run.
+        """
+
+        if max_artifact_bytes < 0 or max_total_bytes < 0:
+            raise HookError("Plugin artifact budgets must not be negative")
+        serialized: dict[str, bytes] = {}
+        total_bytes = 0
+        for artifact_name, payload in artifacts.items():
+            validate_path_component(artifact_name, "CollectorResult artifact name")
+            try:
+                if isinstance(payload, (dict, list)) or artifact_name.endswith(".json"):
+                    content = (
+                        json.dumps(payload, ensure_ascii=True, indent=2, allow_nan=False) + "\n"
+                    ).encode("utf-8")
+                elif isinstance(payload, str):
+                    content = payload.encode("utf-8")
+                else:
+                    raise TypeError
+            except (RecursionError, TypeError, ValueError, UnicodeError):
+                raise HookError(
+                    f"CollectorResult artifact {artifact_name!r} could not be serialized"
+                ) from None
+
+            if len(content) > max_artifact_bytes:
+                raise HookError(
+                    f"CollectorResult artifact {artifact_name!r} exceeds the per-artifact size limit"
+                )
+            total_bytes += len(content)
+            if total_bytes > max_total_bytes:
+                raise HookError("CollectorResult artifacts exceed the aggregate size limit")
+            serialized[artifact_name] = content
+        return serialized
+
     def resolve_input(self, state: ModuleRuntimeState, reference: str) -> pathlib.Path:
         if ":" in reference:
             try:
@@ -127,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