ai-push-hooks 0.2.0 → 0.3.0

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 forwards recognized provider credential environment variables and retains OpenCode's existing authentication data directory, but disables sharing and does not inherit project/global plugins, MCP servers, instructions, or 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,81 @@ 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 enforceable hard
+timeout. 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 the README's [runner
+profiles and access modes](README.md#runner-profiles-and-access-modes).
 
-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
 
-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 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.

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-push-hooks",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "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.2.0"
+version = "0.3.0"
 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: