ai-push-hooks 0.3.1 → 0.3.2

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

@@ -88,7 +88,9 @@ def _validate_text(
     if allow_controls:
         return value
     allowed_controls = "\r\n\t" if allow_line_breaks else ""
-    if "\x00" in value or any(ord(character) < 32 and character not in allowed_controls for character in value):
+    if "\x00" in value or any(
+        ord(character) < 32 and character not in allowed_controls for character in value
+    ):
         raise RunnerContractError(f"{label} contains control characters")
     return value
 
@@ -156,7 +158,9 @@ class PromptPacket:
         if not isinstance(self.artifacts, (tuple, list)):
             raise RunnerContractError("prompt packet artifacts must be ordered")
         if not all(isinstance(item, RunnerArtifact) for item in self.artifacts):
-            raise RunnerContractError("prompt packet artifacts must contain RunnerArtifact values")
+            raise RunnerContractError(
+                "prompt packet artifacts must contain RunnerArtifact values"
+            )
         object.__setattr__(self, "artifacts", tuple(self.artifacts))
 
     def render(self) -> str:
@@ -208,13 +212,17 @@ class RunnerRequest:
         _validate_text(self.purpose, "purpose")
         if self.mode not in {"ask", "apply"}:
             raise RunnerContractError("mode must be 'ask' or 'apply'")
-        _validate_text(self.instruction, "instruction", allow_empty=True, allow_line_breaks=True)
+        _validate_text(
+            self.instruction, "instruction", allow_empty=True, allow_line_breaks=True
+        )
         if not isinstance(self.artifacts, (tuple, list)):
             raise RunnerContractError("artifacts must be an ordered sequence")
         normalized_artifacts: list[RunnerArtifact] = []
         for artifact in self.artifacts:
             if not isinstance(artifact, RunnerArtifact):
-                raise RunnerContractError("artifacts must contain RunnerArtifact values")
+                raise RunnerContractError(
+                    "artifacts must contain RunnerArtifact values"
+                )
             normalized_artifacts.append(artifact)
         object.__setattr__(self, "artifacts", tuple(normalized_artifacts))
         if not isinstance(self.cwd, pathlib.Path):
@@ -310,7 +318,9 @@ class RunnerResult:
     transcript: str | None = field(default=None, repr=False)
 
     def __post_init__(self) -> None:
-        _validate_text(self.final_text, "final_text", allow_empty=True, allow_controls=True)
+        _validate_text(
+            self.final_text, "final_text", allow_empty=True, allow_controls=True
+        )
         if isinstance(self.returncode, bool) or not isinstance(self.returncode, int):
             raise RunnerContractError("returncode must be an integer")
         _validate_text(self.stdout, "stdout", allow_empty=True, allow_controls=True)
@@ -318,7 +328,9 @@ class RunnerResult:
         if self.session is not None and not isinstance(self.session, SessionMetadata):
             raise RunnerContractError("session must be SessionMetadata or None")
         if self.transcript is not None:
-            _validate_text(self.transcript, "transcript", allow_empty=True, allow_line_breaks=True)
+            _validate_text(
+                self.transcript, "transcript", allow_empty=True, allow_line_breaks=True
+            )
 
     def __repr__(self) -> str:
         return (
@@ -342,18 +354,20 @@ class Runner(Protocol):
 
     capabilities: RunnerCapabilities
 
-    def run(self, request: RunnerRequest) -> RunnerResult:
-        ...
+    def run(self, request: RunnerRequest) -> RunnerResult: ...
 
 
 class RunnerLifecycle(Protocol):
     """Optional lifecycle API, implemented only by adapters that need it."""
 
-    def finalize(self, request: RunnerRequest, result: RunnerResult) -> RunnerResult:
-        ...
+    def finalize(
+        self, request: RunnerRequest, result: RunnerResult
+    ) -> RunnerResult: ...
 
 
-def finalize_runner(runner: Runner, request: RunnerRequest, result: RunnerResult) -> RunnerResult:
+def finalize_runner(
+    runner: Runner, request: RunnerRequest, result: RunnerResult
+) -> RunnerResult:
     """Finalize a result when the adapter explicitly advertises that capability."""
 
     capabilities = getattr(runner, "capabilities", RunnerCapabilities())
@@ -396,9 +410,7 @@ def redact_diagnostic(value: str, *, secrets: Sequence[str] = ()) -> str:
     for pattern in _SECRET_PATTERNS:
         redacted = pattern.sub(
             lambda match: (
-                f"{match.group(1)}[REDACTED]"
-                if match.lastindex
-                else "[REDACTED]"
+                f"{match.group(1)}[REDACTED]" if match.lastindex else "[REDACTED]"
             ),
             redacted,
         )
@@ -450,7 +462,10 @@ def bounded_diagnostic(
         return safe
     if max_chars <= len(DIAGNOSTIC_TRUNCATION_MARKER):
         return DIAGNOSTIC_TRUNCATION_MARKER[:max_chars]
-    return safe[: max_chars - len(DIAGNOSTIC_TRUNCATION_MARKER)] + DIAGNOSTIC_TRUNCATION_MARKER
+    return (
+        safe[: max_chars - len(DIAGNOSTIC_TRUNCATION_MARKER)]
+        + DIAGNOSTIC_TRUNCATION_MARKER
+    )
 
 
 def bounded_redacted_diagnostics(
@@ -465,7 +480,9 @@ def bounded_redacted_diagnostics(
     parts: list[str] = []
     for label, value in (("stdout", stdout), ("stderr", stderr)):
         if value:
-            parts.append(f"{label}: {bounded_diagnostic(value, max_chars=max_chars, secrets=secrets)}")
+            parts.append(
+                f"{label}: {bounded_diagnostic(value, max_chars=max_chars, secrets=secrets)}"
+            )
     combined = "\n".join(parts)
     return bounded_diagnostic(combined, max_chars=max_chars, secrets=secrets)
 
@@ -473,7 +490,14 @@ def bounded_redacted_diagnostics(
 def _credential_environment_values(env: Mapping[str, str] | None) -> tuple[str, ...]:
     if env is None:
         return ()
-    credential_markers = ("API_KEY", "TOKEN", "SECRET", "PASSWORD", "AUTH", "CREDENTIAL")
+    credential_markers = (
+        "API_KEY",
+        "TOKEN",
+        "SECRET",
+        "PASSWORD",
+        "AUTH",
+        "CREDENTIAL",
+    )
     return tuple(
         value
         for name, value in env.items()
@@ -582,14 +606,17 @@ def require_zero_exit(
     """Raise a bounded non-zero diagnostic while preserving normalized results."""
 
     if result.returncode != 0:
-        details = request_sensitive_diagnostics(
-            request,
-            result.stdout,
-            result.stderr,
-            max_chars=diagnostic_limit,
-            env=env,
-            extra=secrets,
-        ) or f"exit code {result.returncode}"
+        details = (
+            request_sensitive_diagnostics(
+                request,
+                result.stdout,
+                result.stderr,
+                max_chars=diagnostic_limit,
+                env=env,
+                extra=secrets,
+            )
+            or f"exit code {result.returncode}"
+        )
         raise RunnerNonzeroExitError(
             f"runner {request.profile_id!r} ({request.runner_type}) failed at {request.stage!r}",
             details=details,

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

@@ -25,7 +25,11 @@ from .opencode_support import (
     sanitize_filename_component,
     validate_hook_owned_artifacts,
 )
-from ...paths import ensure_private_directory, resolve_contained_path, write_text_no_follow
+from ...paths import (
+    ensure_private_directory,
+    resolve_contained_path,
+    write_text_no_follow,
+)
 from .process import ProcessResult
 from .contracts import (
     RunnerCapabilities,
@@ -65,7 +69,9 @@ class OpenCodeRunner:
         session_id: str | None = None
         text_parts: list[str] = []
 
-        def protocol_failure(message: str, *, missing: bool = False) -> RunnerProtocolError:
+        def protocol_failure(
+            message: str, *, missing: bool = False
+        ) -> RunnerProtocolError:
             error: RunnerProtocolError
             if missing:
                 error = RunnerMissingOutputError(message)
@@ -86,7 +92,9 @@ class OpenCodeRunner:
             try:
                 event = json.loads(line)
             except json.JSONDecodeError as exc:
-                raise protocol_failure("OpenCode emitted malformed JSONL output") from exc
+                raise protocol_failure(
+                    "OpenCode emitted malformed JSONL output"
+                ) from exc
             if not isinstance(event, dict):
                 raise protocol_failure("OpenCode emitted a non-object JSONL event")
 
@@ -220,7 +228,11 @@ class OpenCodeRunner:
         *,
         prompt: str,
     ) -> list[str]:
-        agent = OPENCODE_APPLY_AGENT if request.mode == "apply" else OPENCODE_READ_ONLY_AGENT
+        agent = (
+            OPENCODE_APPLY_AGENT
+            if request.mode == "apply"
+            else OPENCODE_READ_ONLY_AGENT
+        )
         config = getattr(getattr(context, "config", None), "llm", None)
         title_prefix = getattr(config, "session_title_prefix", "ai-push-hooks")
         argv = [
@@ -251,7 +263,9 @@ class OpenCodeRunner:
         return argv
 
     @staticmethod
-    def _require_staging_directory(context: Any, working_directory: pathlib.Path) -> None:
+    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.
@@ -262,11 +276,16 @@ class OpenCodeRunner:
         """
 
         repository_root = context.repo_root.resolve(strict=True)
-        if working_directory == repository_root or working_directory.is_relative_to(repository_root):
+        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)):
+        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"
             )
@@ -296,7 +315,9 @@ class OpenCodeRunner:
                     "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")
+                raise RunnerContractError(
+                    "OpenCode request cwd must be an existing directory"
+                )
             if request.mode == "apply":
                 self._require_staging_directory(context, working_directory)
 
@@ -311,12 +332,17 @@ class OpenCodeRunner:
                 working_directory if request.project_access == "project" else None
             ),
         )
-        executable = getattr(context, "opencode_executable", None) or resolve_opencode_executable()
+        executable = (
+            getattr(context, "opencode_executable", None)
+            or resolve_opencode_executable()
+        )
         isolated_env = opencode_isolation_env(context, security_config, request.stage)
         attachment_dir: pathlib.Path | None = None
         session_id: str | None = None
         try:
-            attachments, attachment_dir = self._materialize_attachments(context, request)
+            attachments, attachment_dir = self._materialize_attachments(
+                context, request
+            )
             # Every logical artifact is materialized, including pathless
             # contract artifacts.  Therefore native attachments carry the
             # complete snapshot and the instruction is never duplicated in a
@@ -351,14 +377,18 @@ class OpenCodeRunner:
 
             try:
                 if working_directory is None:
-                    with tempfile.TemporaryDirectory(prefix="ai-push-hooks-readonly-") as directory:
+                    with tempfile.TemporaryDirectory(
+                        prefix="ai-push-hooks-readonly-"
+                    ) as directory:
                         completed = invoke(pathlib.Path(directory).resolve(strict=True))
                 else:
                     completed = invoke(working_directory)
             except (RunnerError,) as error:
                 process_result = getattr(error, "_process_result", None)
                 partial_stdout = (
-                    process_result.stdout if isinstance(process_result, ProcessResult) else ""
+                    process_result.stdout
+                    if isinstance(process_result, ProcessResult)
+                    else ""
                 )
                 setattr(
                     error,
@@ -397,7 +427,9 @@ class OpenCodeRunner:
                 stdout=completed.stdout,
                 stderr=completed.stderr,
                 session=(
-                    SessionMetadata(session_id=session_id, state="persisted", resumable=True)
+                    SessionMetadata(
+                        session_id=session_id, state="persisted", resumable=True
+                    )
                     if session_id
                     else SessionMetadata()
                 ),
@@ -427,7 +459,9 @@ class OpenCodeRunner:
             non_agent_opencode_config(),
             request.stage,
         )
-        with tempfile.TemporaryDirectory(prefix=f"ai-push-hooks-session-{action}-") as directory:
+        with tempfile.TemporaryDirectory(
+            prefix=f"ai-push-hooks-session-{action}-"
+        ) as directory:
             return run_process(
                 argv,
                 cwd=pathlib.Path(directory).resolve(strict=True),
@@ -456,7 +490,10 @@ class OpenCodeRunner:
                     "OpenCode transcript path",
                 )
                 try:
-                    executable = getattr(context, "opencode_executable", None) or resolve_opencode_executable()
+                    executable = (
+                        getattr(context, "opencode_executable", None)
+                        or resolve_opencode_executable()
+                    )
                     exported = self._lifecycle_process(
                         request,
                         context,
@@ -469,10 +506,17 @@ class OpenCodeRunner:
                         and not getattr(exported, "stderr_truncated", False)
                         and exported.stdout.strip()
                     ):
-                        write_text_no_follow(transcript_path, exported.stdout.strip() + "\n")
+                        write_text_no_follow(
+                            transcript_path, exported.stdout.strip() + "\n"
+                        )
                     else:
                         transcript_path = None
-                        self._warn_export(context, request, session_id, "export returned no transcript")
+                        self._warn_export(
+                            context,
+                            request,
+                            session_id,
+                            "export returned no transcript",
+                        )
                 except Exception as exc:  # noqa: BLE001
                     transcript_path = None
                     self._warn_export(context, request, session_id, type(exc).__name__)
@@ -480,7 +524,10 @@ class OpenCodeRunner:
         deleted = False
         if getattr(context.config.llm, "delete_session_after_run", False):
             try:
-                executable = getattr(context, "opencode_executable", None) or resolve_opencode_executable()
+                executable = (
+                    getattr(context, "opencode_executable", None)
+                    or resolve_opencode_executable()
+                )
                 deleted_result = self._lifecycle_process(
                     request,
                     context,
@@ -489,9 +536,13 @@ class OpenCodeRunner:
                 )
                 deleted = deleted_result.returncode == 0
                 if not deleted:
-                    self._warn_export(context, request, session_id, "session deletion failed")
+                    self._warn_export(
+                        context, request, session_id, "session deletion failed"
+                    )
             except Exception as exc:  # noqa: BLE001
-                self._warn_export(context, request, session_id, f"delete {type(exc).__name__}")
+                self._warn_export(
+                    context, request, session_id, f"delete {type(exc).__name__}"
+                )
 
         state = "deleted" if deleted else "persisted"
         finalized_session = SessionMetadata(
@@ -510,7 +561,9 @@ class OpenCodeRunner:
         )
 
     @staticmethod
-    def _warn_export(context: Any, request: RunnerRequest, session_id: str, reason: str) -> None:
+    def _warn_export(
+        context: Any, request: RunnerRequest, session_id: str, reason: str
+    ) -> None:
         logger = getattr(context, "logger", None)
         if logger is not None:
             logger.warn(

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

@@ -71,7 +71,9 @@ def opencode_isolation_env(
         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}")
+        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)}",
@@ -184,7 +186,9 @@ def build_opencode_security_config(
         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")
+            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"
@@ -266,11 +270,17 @@ def validate_hook_owned_artifacts(
     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}")
+            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}")
+            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}")
+            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

@@ -226,8 +226,13 @@ def run_process(
     timeout and signal termination are raised as distinct fail-closed errors.
     """
 
-    if not isinstance(argv, (tuple, list)) or not argv or any(
-        not isinstance(argument, str) or not argument or "\x00" in argument for argument in argv
+    if (
+        not isinstance(argv, (tuple, list))
+        or not argv
+        or any(
+            not isinstance(argument, str) or not argument or "\x00" in argument
+            for argument in argv
+        )
     ):
         raise RunnerError("runner command must be a non-empty NUL-free argv vector")
     if not isinstance(cwd, pathlib.Path):
@@ -261,7 +266,9 @@ def run_process(
         if not isinstance(input_path, pathlib.Path):
             input_path = pathlib.Path(input_path)
         if path_is_link_or_reparse(input_path):
-            raise RunnerError("runner input file must not be a symlink or reparse point")
+            raise RunnerError(
+                "runner input file must not be a symlink or reparse point"
+            )
         descriptor = -1
         try:
             # O_NONBLOCK prevents opening a FIFO from waiting for a writer;
@@ -312,7 +319,9 @@ def run_process(
     except OSError as exc:
         if input_file is not None:
             input_file.close()
-        raise RunnerError("runner process could not be started", details=type(exc).__name__) from exc
+        raise RunnerError(
+            "runner process could not be started", details=type(exc).__name__
+        ) from exc
 
     if process.stdout is None or process.stderr is None or process.stdin is None:
         _stop_process(process, time.monotonic() + PROCESS_CLEANUP_GRACE_SECONDS)
@@ -354,7 +363,11 @@ def run_process(
     stdout_thread.start()
     stderr_thread.start()
 
-    input_bytes = None if input_text is None else input_text.encode("utf-8", errors="surrogateescape")
+    input_bytes = (
+        None
+        if input_text is None
+        else input_text.encode("utf-8", errors="surrogateescape")
+    )
 
     def write_input() -> None:
         try:
@@ -427,9 +440,15 @@ def run_process(
         )
 
     if returncode is None:
-        returncode = process_returncode[0] if process_returncode[0] is not None else 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)
+        timeout_returncode = (
+            returncode if returncode is not None else -getattr(signal, "SIGKILL", 9)
+        )
         process_result = _captured_result(
             timeout_returncode,
             stdout,

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

@@ -53,7 +53,9 @@ class LazyRunnerSpec:
                 details=type(exc).__name__,
             ) from exc
         if not callable(getattr(runner, "run", None)):
-            raise RunnerAdapterUnavailableError("selected runner does not implement run(request)")
+            raise RunnerAdapterUnavailableError(
+                "selected runner does not implement run(request)"
+            )
         return runner
 
 
@@ -68,15 +70,20 @@ _DEFAULT_SPECS = {
 class RunnerRegistry:
     """A fixed registry; it intentionally has no runtime plugin registration API."""
 
-    def __init__(self, specs: Mapping[str, LazyRunnerSpec | Callable[[], Runner]] | None = None) -> None:
+    def __init__(
+        self, specs: Mapping[str, LazyRunnerSpec | Callable[[], Runner]] | None = None
+    ) -> None:
         selected = _DEFAULT_SPECS if specs is None else dict(specs)
         unknown = set(selected) - set(KNOWN_RUNNER_TYPES)
         if unknown:
             raise RunnerContractError(
-                "runner registry contains unsupported adapter types: " + ", ".join(sorted(unknown))
+                "runner registry contains unsupported adapter types: "
+                + ", ".join(sorted(unknown))
             )
         if set(selected) != set(KNOWN_RUNNER_TYPES):
-            raise RunnerContractError("runner registry must contain all four known adapter types")
+            raise RunnerContractError(
+                "runner registry must contain all four known adapter types"
+            )
         self._specs = dict(selected)
         self._loaded: dict[str, Runner] = {}
         self._load_locks = {
@@ -111,7 +118,9 @@ class RunnerRegistry:
 DEFAULT_RUNNER_REGISTRY = RunnerRegistry()
 
 
-def get_runner(runner_type: str, *, registry: RunnerRegistry = DEFAULT_RUNNER_REGISTRY) -> Runner:
+def get_runner(
+    runner_type: str, *, registry: RunnerRegistry = DEFAULT_RUNNER_REGISTRY
+) -> Runner:
     """Resolve one of the four static adapter types lazily."""
 
     return registry.get(runner_type)