ai-push-hooks 0.3.0 → 0.3.1

package/src/ai_push_hooks/executors/runner_workflow.py

@@ -54,15 +54,15 @@ def _safe_input_artifacts(
 ) -> tuple[RunnerArtifact, ...]:
     """Build the ordered logical artifact list shared by every adapter.
 
-    ``validate_opencode_attachments`` is retained as the hook-owned artifact
-    boundary used by the shipped implementation.  The logical names are the
+    ``validate_hook_owned_artifacts`` is the hook-owned artifact boundary used
+    before adapter dispatch.  The logical names are the
     configured input references, rather than filesystem basenames, so command,
     Codex, Claude, and OpenCode receive the same ordered context.
     """
 
-    from .ask import validate_opencode_attachments
+    from .runners.opencode_support import validate_hook_owned_artifacts
 
-    validated = validate_opencode_attachments(context, input_paths)
+    validated = validate_hook_owned_artifacts(context, input_paths)
     if len(validated) != len(step.inputs):
         raise HookError(
             f"Runner input count does not match configured inputs for step `{step.id}`"

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

@@ -1,8 +1,8 @@
 """OpenCode adapter for the internal runner boundary.
 
-The compatibility invocation deliberately remains the shipped ``opencode
-run`` shape.  This module owns the adapter-level protocol and lifecycle
-semantics; workflow retries and JSON/schema handling remain in orchestration.
+The adapter deliberately retains the shipped ``opencode run`` shape.  This
+module owns the adapter-level protocol and lifecycle semantics; workflow
+retries and JSON/schema handling remain in orchestration.
 """
 
 from __future__ import annotations
@@ -14,7 +14,7 @@ import sys
 import tempfile
 from typing import Any
 
-from ..ask import (
+from .opencode_support import (
     OPENCODE_APPLY_AGENT,
     OPENCODE_READ_ONLY_AGENT,
     _transcript_dir,
@@ -23,10 +23,9 @@ from ..ask import (
     opencode_isolation_env,
     resolve_opencode_executable,
     sanitize_filename_component,
-    validate_opencode_attachments,
+    validate_hook_owned_artifacts,
 )
-from ...paths import resolve_contained_path, write_text_no_follow
-from ...paths import ensure_private_directory
+from ...paths import ensure_private_directory, resolve_contained_path, write_text_no_follow
 from .process import ProcessResult
 from .contracts import (
     RunnerCapabilities,
@@ -159,7 +158,7 @@ class OpenCodeRunner:
         # Validate source ownership and symlink traversal before making any
         # copy.  The source is then never reopened: its logical snapshot is
         # the only content sent through OpenCode's native --file transport.
-        validate_opencode_attachments(
+        validate_hook_owned_artifacts(
             context,
             [path for path in original_paths if path is not None],
         )
@@ -251,6 +250,27 @@ class OpenCodeRunner:
         argv.extend(["--", prompt])
         return argv
 
+    @staticmethod
+    def _require_staging_directory(context: Any, working_directory: pathlib.Path) -> None:
+        """Reject repository worktrees as apply targets.
+
+        The apply workflow supplies a disposable, non-VCS staging projection.
+        A runner request can identify the repository root and the selected cwd,
+        but it cannot turn an arbitrary host directory into a sandbox.  Refuse
+        the known unsafe cases at this boundary instead of granting edit
+        permissions to the checked-out repository.
+        """
+
+        repository_root = context.repo_root.resolve(strict=True)
+        if working_directory == repository_root or working_directory.is_relative_to(repository_root):
+            raise RunnerContractError(
+                "OpenCode apply requests require an isolated staging directory"
+            )
+        if any((parent / ".git").exists() for parent in (working_directory, *working_directory.parents)):
+            raise RunnerContractError(
+                "OpenCode apply requests require a non-VCS isolated staging directory"
+            )
+
     def run(self, request: RunnerRequest) -> RunnerResult:
         if request.runner_type != "opencode":
             raise RunnerContractError(
@@ -268,8 +288,17 @@ class OpenCodeRunner:
         else:
             working_directory = None
 
-        if working_directory is not None and not working_directory.is_dir():
-            raise RunnerContractError("OpenCode request cwd must be an existing directory")
+        if working_directory is not None:
+            try:
+                working_directory = working_directory.resolve(strict=True)
+            except (OSError, RuntimeError) as exc:
+                raise RunnerContractError(
+                    "OpenCode request cwd must be an existing directory"
+                ) from exc
+            if not working_directory.is_dir():
+                raise RunnerContractError("OpenCode request cwd must be an existing directory")
+            if request.mode == "apply":
+                self._require_staging_directory(context, working_directory)
 
         agent = "apply" if request.mode == "apply" else "read-only"
         _agent_name, security_config = build_opencode_security_config(
@@ -325,7 +354,7 @@ class OpenCodeRunner:
                     with tempfile.TemporaryDirectory(prefix="ai-push-hooks-readonly-") as directory:
                         completed = invoke(pathlib.Path(directory).resolve(strict=True))
                 else:
-                    completed = invoke(working_directory.resolve(strict=True))
+                    completed = invoke(working_directory)
             except (RunnerError,) as error:
                 process_result = getattr(error, "_process_result", None)
                 partial_stdout = (

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

@@ -0,0 +1,276 @@
+"""Shared OpenCode isolation and hook-owned artifact policy helpers.
+
+This module contains only the OpenCode-specific filesystem, environment, and
+permission policy used by the active adapter.  Workflow orchestration remains
+runner-neutral and the adapter owns invocation and session lifecycle.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import pathlib
+import re
+import shutil
+from typing import Any
+
+from ...paths import (
+    ensure_private_directory,
+    is_path_within,
+    path_has_symlink,
+    resolve_contained_path,
+)
+from ...git_utils import ensure_dir, resolve_storage_path
+from ...types import HookError, RuntimeContext
+
+
+OPENCODE_READ_ONLY_AGENT = "ai-push-hooks-readonly"
+OPENCODE_APPLY_AGENT = "ai-push-hooks-apply"
+PROVIDER_ENV_PREFIXES = (
+    "ANTHROPIC_",
+    "AWS_",
+    "AZURE_",
+    "COHERE_",
+    "DEEPSEEK_",
+    "GEMINI_",
+    "GOOGLE_",
+    "GROQ_",
+    "MISTRAL_",
+    "OPENAI_",
+    "OPENROUTER_",
+    "VERTEX_",
+    "XAI_",
+)
+SAFE_PROCESS_ENV_NAMES = frozenset(
+    {
+        "PATH",
+        "TMPDIR",
+        "TMP",
+        "TEMP",
+        "LANG",
+        "LC_ALL",
+        "LC_CTYPE",
+        "SYSTEMROOT",
+    }
+)
+
+
+def _actual_xdg_data_home() -> pathlib.Path:
+    configured = os.environ.get("XDG_DATA_HOME", "").strip()
+    if configured:
+        return pathlib.Path(configured).expanduser().resolve(strict=False)
+    return (pathlib.Path.home() / ".local" / "share").resolve(strict=False)
+
+
+def opencode_isolation_env(
+    context: RuntimeContext,
+    security_config: dict[str, Any],
+    stage_name: str,
+) -> dict[str, str | None]:
+    lexical_isolation_root = (
+        context.run_dir / "opencode-isolation" / sanitize_filename_component(stage_name)
+    )
+    if path_has_symlink(context.run_dir, lexical_isolation_root):
+        raise HookError(f"OpenCode isolation directory must not traverse a symlink: {stage_name}")
+    isolation_root = resolve_contained_path(
+        context.run_dir,
+        f"opencode-isolation/{sanitize_filename_component(stage_name)}",
+        "OpenCode isolation directory",
+    )
+    home = isolation_root / "home"
+    config_home = isolation_root / "config"
+    cache_home = isolation_root / "cache"
+    state_home = isolation_root / "state"
+    ensure_private_directory(isolation_root)
+    for path in (home, config_home, cache_home, state_home):
+        ensure_private_directory(path, private_root=isolation_root)
+
+    isolated: dict[str, str | None] = {
+        name: value
+        for name, value in os.environ.items()
+        if name in SAFE_PROCESS_ENV_NAMES or name.startswith(PROVIDER_ENV_PREFIXES)
+    }
+    isolated.update(
+        {
+            "HOME": str(home),
+            "XDG_CONFIG_HOME": str(config_home),
+            "XDG_CACHE_HOME": str(cache_home),
+            "XDG_STATE_HOME": str(state_home),
+            "XDG_DATA_HOME": str(_actual_xdg_data_home()),
+            "OPENCODE_CONFIG_CONTENT": json.dumps(security_config, ensure_ascii=True),
+            "OPENCODE_CONFIG_DIR": str(config_home),
+            "OPENCODE_PURE": "true",
+            "OPENCODE_DISABLE_PROJECT_CONFIG": "true",
+            "OPENCODE_DISABLE_EXTERNAL_SKILLS": "true",
+            "OPENCODE_DISABLE_CLAUDE_CODE": "true",
+            "OPENCODE_DISABLE_CLAUDE_CODE_PROMPT": "true",
+            "OPENCODE_DISABLE_CLAUDE_CODE_SKILLS": "true",
+            "OPENCODE_DISABLE_LSP_DOWNLOAD": "true",
+            "OPENCODE_DISABLE_SHARE": "true",
+            "OPENCODE_DISABLE_AUTOUPDATE": "true",
+        }
+    )
+    return isolated
+
+
+def non_agent_opencode_config() -> dict[str, Any]:
+    return {
+        "$schema": "https://opencode.ai/config.json",
+        "plugin": [],
+        "mcp": {},
+        "share": "disabled",
+        "instructions": [],
+        "formatter": False,
+        "lsp": False,
+        "command": {},
+        "permission": {"*": "deny"},
+    }
+
+
+def sanitize_filename_component(value: str) -> str:
+    cleaned = re.sub(r"[^A-Za-z0-9._-]+", "-", value.strip())
+    return cleaned.strip("-") or "value"
+
+
+def resolve_opencode_executable() -> str:
+    opencode_path = shutil.which("opencode")
+    if opencode_path:
+        return opencode_path
+    cli_path = shutil.which("opencode-cli")
+    if cli_path:
+        return cli_path
+    raise HookError("opencode is required but not installed")
+
+
+def _transcript_dir(context: RuntimeContext) -> pathlib.Path | None:
+    if not context.config.logging.capture_llm_transcript:
+        return None
+    return ensure_dir(
+        resolve_storage_path(
+            context.repo_root,
+            context.git_dir,
+            context.config.logging.transcript_dir,
+        )
+    )
+
+
+def build_opencode_security_config(
+    agent_policy: str,
+    allow_paths: tuple[str, ...] = (),
+    *,
+    non_vcs_working_directory: pathlib.Path | None = None,
+    project_read_root: pathlib.Path | None = None,
+) -> tuple[str, dict[str, Any]]:
+    permissions: dict[str, Any] = {
+        "*": "deny",
+        "read": "deny",
+        "glob": "deny",
+        "grep": "deny",
+        "list": "deny",
+        "edit": "deny",
+        "bash": "deny",
+        "task": "deny",
+        "external_directory": "deny",
+        "webfetch": "deny",
+        "websearch": "deny",
+        "lsp": "deny",
+        "skill": "deny",
+        "todowrite": "deny",
+        "question": "deny",
+        "doom_loop": "deny",
+    }
+    if agent_policy == "read-only":
+        agent_name = OPENCODE_READ_ONLY_AGENT
+        description = "Read-only ai-push-hooks analysis agent"
+    elif agent_policy == "apply":
+        if not allow_paths:
+            raise HookError("OpenCode apply agent requires an explicit non-empty allow_paths")
+        agent_name = OPENCODE_APPLY_AGENT
+        description = "Path-restricted ai-push-hooks apply agent"
+        permissions["read"] = "allow"
+        permission_patterns: set[str] = set()
+        for pattern in allow_paths:
+            permission_patterns.add(pattern)
+            collapsed = pattern
+            while "**/" in collapsed:
+                collapsed = collapsed.replace("**/", "", 1)
+                permission_patterns.add(collapsed)
+        protected_patterns = {".git", ".git/**"}
+        if non_vcs_working_directory is not None:
+            # OpenCode assigns `/` as the worktree for a directory without VCS
+            # metadata, so qualify allowlisted paths with that filesystem root.
+            anchor = pathlib.Path(non_vcs_working_directory.anchor)
+            prefix = non_vcs_working_directory.relative_to(anchor).as_posix()
+            permission_patterns = {
+                f"{prefix}/{pattern}" if prefix else pattern
+                for pattern in permission_patterns
+            }
+            protected_patterns = {
+                f"{prefix}/{pattern}" if prefix else pattern
+                for pattern in protected_patterns
+            }
+        edit_permissions = {
+            "*": "deny",
+            **{pattern: "allow" for pattern in sorted(permission_patterns)},
+        }
+        for pattern in sorted(protected_patterns):
+            edit_permissions[pattern] = "deny"
+        permissions["edit"] = edit_permissions
+    else:
+        raise HookError(f"Unsupported OpenCode agent policy: {agent_policy}")
+
+    if project_read_root is not None:
+        root = project_read_root.resolve(strict=False)
+        if (root / ".git").exists():
+            rooted_permissions: str | dict[str, str] = "allow"
+        else:
+            anchor = pathlib.Path(root.anchor)
+            prefix = root.relative_to(anchor).as_posix()
+            rooted_permissions = {
+                "*": "deny",
+                prefix: "allow",
+                f"{prefix}/**": "allow",
+            }
+        for tool in ("read", "list", "glob", "grep"):
+            permissions[tool] = (
+                dict(rooted_permissions)
+                if isinstance(rooted_permissions, dict)
+                else rooted_permissions
+            )
+
+    return agent_name, {
+        "$schema": "https://opencode.ai/config.json",
+        "plugin": [],
+        "mcp": {},
+        "share": "disabled",
+        "instructions": [],
+        "formatter": False,
+        "lsp": False,
+        "command": {},
+        "agent": {
+            agent_name: {
+                "mode": "primary",
+                "description": description,
+                "permission": permissions,
+            }
+        },
+    }
+
+
+def validate_hook_owned_artifacts(
+    context: RuntimeContext,
+    files: list[pathlib.Path],
+) -> list[pathlib.Path]:
+    run_root = context.run_dir.resolve(strict=True)
+    validated: list[pathlib.Path] = []
+    for file_path in files:
+        lexical_path = pathlib.Path(os.path.abspath(file_path))
+        if not is_path_within(lexical_path, run_root):
+            raise HookError(f"OpenCode attachment is not a hook-owned artifact: {file_path}")
+        if path_has_symlink(run_root, lexical_path):
+            raise HookError(f"OpenCode attachment must not traverse a symlink: {file_path}")
+        resolved_path = lexical_path.resolve(strict=True)
+        if not is_path_within(resolved_path, run_root) or not resolved_path.is_file():
+            raise HookError(f"OpenCode attachment must be a regular hook-owned file: {file_path}")
+        validated.append(resolved_path)
+    return validated

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

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import math
 import os
 import pathlib
 import signal
@@ -58,6 +59,7 @@ def _read_bounded(
     output: bytearray,
     truncated: list[bool],
     output_lock: threading.Lock,
+    output_limit_reached: threading.Event,
 ) -> None:
     read = getattr(stream, "read")
     try:
@@ -74,6 +76,7 @@ def _read_bounded(
                     output.extend(chunk[:remaining])
                 if len(chunk) > remaining:
                     truncated[0] = True
+                    output_limit_reached.set()
     finally:
         _close_pipe(stream)
 
@@ -213,6 +216,7 @@ def run_process(
     timeout_seconds: float,
     env: Mapping[str, str] | None = None,
     max_output_bytes: int = DEFAULT_MAX_OUTPUT_BYTES,
+    max_stderr_bytes: int | None = None,
 ) -> ProcessResult:
     """Run an argv vector directly, with bounded concurrent stream capture.
 
@@ -230,10 +234,26 @@ def run_process(
         cwd = pathlib.Path(cwd)
     if not cwd.is_dir():
         raise RunnerError("runner cwd must be an existing directory")
-    if timeout_seconds <= 0:
-        raise RunnerError("runner timeout must be greater than zero")
-    if max_output_bytes < 0:
+    if (
+        isinstance(timeout_seconds, bool)
+        or not isinstance(timeout_seconds, (int, float))
+        or not math.isfinite(timeout_seconds)
+        or timeout_seconds <= 0
+    ):
+        raise RunnerError("runner timeout must be a finite number greater than zero")
+    if (
+        isinstance(max_output_bytes, bool)
+        or not isinstance(max_output_bytes, int)
+        or max_output_bytes < 0
+    ):
         raise RunnerError("runner output bound must not be negative")
+    stderr_limit = max_output_bytes if max_stderr_bytes is None else max_stderr_bytes
+    if (
+        isinstance(stderr_limit, bool)
+        or not isinstance(stderr_limit, int)
+        or stderr_limit < 0
+    ):
+        raise RunnerError("runner stderr output bound must not be negative")
     if input_text is not None and input_path is not None:
         raise RunnerError("runner input_text and input_path are mutually exclusive")
     input_file = None
@@ -306,14 +326,29 @@ def run_process(
     stderr_lock = threading.Lock()
     stdout_truncated = [False]
     stderr_truncated = [False]
+    output_limit_reached = threading.Event()
     stdout_thread = threading.Thread(
         target=_read_bounded,
-        args=(process.stdout, max_output_bytes, stdout, stdout_truncated, stdout_lock),
+        args=(
+            process.stdout,
+            max_output_bytes,
+            stdout,
+            stdout_truncated,
+            stdout_lock,
+            output_limit_reached,
+        ),
         daemon=True,
     )
     stderr_thread = threading.Thread(
         target=_read_bounded,
-        args=(process.stderr, max_output_bytes, stderr, stderr_truncated, stderr_lock),
+        args=(
+            process.stderr,
+            stderr_limit,
+            stderr,
+            stderr_truncated,
+            stderr_lock,
+            output_limit_reached,
+        ),
         daemon=True,
     )
     stdout_thread.start()
@@ -350,23 +385,49 @@ def run_process(
 
     input_thread = threading.Thread(target=write_input, daemon=True)
     input_thread.start()
+    process_exited = threading.Event()
+    process_returncode: list[int | None] = [None]
+
+    def wait_for_process_exit() -> None:
+        process_returncode[0] = process.wait()
+        process_exited.set()
+
+    process_wait_thread = threading.Thread(target=wait_for_process_exit, daemon=True)
+    process_wait_thread.start()
     returncode: int | None = None
     timeout_cause: subprocess.TimeoutExpired | None = None
+    output_limit_cause = False
     try:
-        returncode = process.wait(timeout=timeout_seconds)
-    except subprocess.TimeoutExpired as exc:
-        timeout_cause = exc
+        deadline = time.monotonic() + timeout_seconds
+        while True:
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                timeout_cause = subprocess.TimeoutExpired(list(argv), timeout_seconds)
+                break
+            if output_limit_reached.is_set():
+                # A short grace period preserves the natural exit status for
+                # commands that wrote their final bounded chunk and were
+                # already exiting.  A still-live child is stopped below
+                # rather than allowed to drain discarded output until timeout.
+                if process_exited.wait(timeout=min(remaining, 0.05)):
+                    returncode = process_returncode[0]
+                else:
+                    output_limit_cause = True
+                break
+            if process_exited.wait(timeout=min(remaining, 0.05)):
+                returncode = process_returncode[0]
+                break
     finally:
         cleanup_deadline = time.monotonic() + PROCESS_CLEANUP_GRACE_SECONDS
         _stop_process(process, cleanup_deadline)
         _finish_capture(
             (process.stdin, process.stdout, process.stderr),
-            (input_thread, stdout_thread, stderr_thread),
+            (input_thread, stdout_thread, stderr_thread, process_wait_thread),
             cleanup_deadline,
         )
 
     if returncode is None:
-        returncode = process.poll()
+        returncode = process_returncode[0] if process_returncode[0] is not None else process.poll()
     if timeout_cause is not None:
         timeout_returncode = returncode if returncode is not None else -getattr(signal, "SIGKILL", 9)
         process_result = _captured_result(
@@ -393,7 +454,7 @@ def run_process(
         stdout_lock,
         stderr_lock,
     )
-    if returncode < 0:
+    if returncode < 0 and not output_limit_cause:
         error = RunnerSignalError(
             "runner process terminated by signal",
             details=str(-returncode),

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

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import importlib
+import threading
 from dataclasses import dataclass
 from types import ModuleType
 from typing import Callable, Mapping
@@ -78,6 +79,9 @@ class RunnerRegistry:
             raise RunnerContractError("runner registry must contain all four known adapter types")
         self._specs = dict(selected)
         self._loaded: dict[str, Runner] = {}
+        self._load_locks = {
+            runner_type: threading.Lock() for runner_type in KNOWN_RUNNER_TYPES
+        }
 
     @property
     def known_types(self) -> tuple[str, ...]:
@@ -86,10 +90,19 @@ class RunnerRegistry:
     def get(self, runner_type: str) -> Runner:
         if runner_type not in self._specs:
             raise RunnerContractError(f"unknown runner type: {runner_type!r}")
-        if runner_type not in self._loaded:
-            spec = self._specs[runner_type]
-            self._loaded[runner_type] = spec.load() if isinstance(spec, LazyRunnerSpec) else spec()
-        return self._loaded[runner_type]
+        runner = self._loaded.get(runner_type)
+        if runner is not None:
+            return runner
+        # Initialization is serialized only for the selected adapter.  Other
+        # runner types may load concurrently, which matters for capability
+        # probes such as Claude's --help check.
+        with self._load_locks[runner_type]:
+            runner = self._loaded.get(runner_type)
+            if runner is None:
+                spec = self._specs[runner_type]
+                runner = spec.load() if isinstance(spec, LazyRunnerSpec) else spec()
+                self._loaded[runner_type] = runner
+            return runner
 
     def __contains__(self, runner_type: object) -> bool:
         return runner_type in self._specs

package/src/ai_push_hooks/executors/step_commands.py

@@ -19,7 +19,13 @@ from typing import Any
 
 from ..artifacts import ArtifactStore
 from ..paths import path_is_link_or_reparse
-from ..types import HookError, ModuleRuntimeState, RuntimeContext, StepConfig
+from ..types import (
+    DEFAULT_STEP_COMMAND_TIMEOUT_SECONDS,
+    HookError,
+    ModuleRuntimeState,
+    RuntimeContext,
+    StepConfig,
+)
 from .runners.contracts import bounded_diagnostic, redact_diagnostic
 from .runners.process import (
     DEFAULT_MAX_OUTPUT_BYTES,
@@ -27,7 +33,6 @@ from .runners.process import (
     run_process,
 )
 
-DEFAULT_STEP_COMMAND_TIMEOUT_SECONDS = 60
 STEP_COMMAND_STDOUT_ARTIFACT = "stdout.txt"
 STEP_COMMAND_STDERR_ARTIFACT = "stderr.txt"
 STEP_COMMAND_RESULT_ARTIFACT = "result.json"