ai-push-hooks 0.3.0 → 0.3.2

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}`"
@@ -76,29 +76,36 @@ def _safe_input_artifacts(
         # parents immediately before opening each file; this is a same-user
         # race defense, not an OS sandbox.  O_NOFOLLOW and descriptor checks
         # below protect the final open even if the leaf changes concurrently.
-        if (
-            not is_path_within(lexical_path, run_root)
-            or path_has_symlink(run_root, lexical_path)
+        if not is_path_within(lexical_path, run_root) or path_has_symlink(
+            run_root, lexical_path
         ):
             raise HookError(f"Runner artifact must not traverse a symlink: {name}")
         try:
             resolved_path = lexical_path.resolve(strict=True)
         except (OSError, RuntimeError) as exc:
-            raise HookError(f"Unable to safely resolve runner artifact: {name}") from exc
+            raise HookError(
+                f"Unable to safely resolve runner artifact: {name}"
+            ) from exc
         if (
             resolved_path != lexical_path
             or not is_path_within(resolved_path, run_root)
             or not resolved_path.is_file()
         ):
-            raise HookError(f"Runner artifact must be a regular hook-owned file: {name}")
+            raise HookError(
+                f"Runner artifact must be a regular hook-owned file: {name}"
+            )
 
         descriptor: int | None = None
         try:
-            flags = os.O_RDONLY | getattr(os, "O_CLOEXEC", 0) | getattr(os, "O_NOFOLLOW", 0)
+            flags = (
+                os.O_RDONLY | getattr(os, "O_CLOEXEC", 0) | getattr(os, "O_NOFOLLOW", 0)
+            )
             descriptor = os.open(lexical_path, flags)
             metadata = os.fstat(descriptor)
             if not os.path.isfile(lexical_path) or not stat.S_ISREG(metadata.st_mode):
-                raise HookError(f"Runner artifact must be a regular hook-owned file: {name}")
+                raise HookError(
+                    f"Runner artifact must be a regular hook-owned file: {name}"
+                )
             remaining = RUNNER_INPUT_MAX_BYTES - total_bytes
             if metadata.st_size > remaining:
                 raise HookError(
@@ -121,7 +128,9 @@ def _safe_input_artifacts(
             total_bytes += len(content_bytes)
             content = bytes(content_bytes).decode("utf-8")
         except (OSError, UnicodeError) as exc:
-            raise HookError(f"Unable to read hook-owned runner artifact: {name}") from exc
+            raise HookError(
+                f"Unable to read hook-owned runner artifact: {name}"
+            ) from exc
         finally:
             if descriptor is not None:
                 os.close(descriptor)
@@ -143,7 +152,9 @@ def _build_request(
     profile = resolve_runner_profile(context.config, step)
     cwd = pathlib.Path(working_directory).resolve(strict=True)
     if not cwd.is_dir():
-        raise HookError(f"Runner working directory is not a directory: {working_directory}")
+        raise HookError(
+            f"Runner working directory is not a directory: {working_directory}"
+        )
     request = RunnerRequest(
         profile_id=profile.name,
         runner_type=profile.type,
@@ -206,7 +217,9 @@ def _failure_result(
     if not isinstance(session_id, str) or not session_id.strip():
         session_id = fallback_session_id
     session = _session_metadata(runner, session_id.strip()) if session_id else None
-    return RunnerResult(final_text="", returncode=1, stdout="", stderr="", session=session)
+    return RunnerResult(
+        final_text="", returncode=1, stdout="", stderr="", session=session
+    )
 
 
 def _preserve_failure_session(
@@ -214,7 +227,9 @@ def _preserve_failure_session(
     result: RunnerResult,
     fallback_session_id: str | None,
 ) -> RunnerResult:
-    if (result.session is not None and result.session.session_id) or not fallback_session_id:
+    if (
+        result.session is not None and result.session.session_id
+    ) or not fallback_session_id:
         return result
     return RunnerResult(
         final_text=result.final_text,
@@ -250,7 +265,9 @@ def _completion(
     )
 
 
-def _print_normalized_output(context: RuntimeContext, invocation: _RunnerInvocation) -> None:
+def _print_normalized_output(
+    context: RuntimeContext, invocation: _RunnerInvocation
+) -> None:
     if not context.config.logging.print_llm_output or not invocation.result.final_text:
         return
     # This is an explicit opt-in.  Only normalized final text is printed and
@@ -270,7 +287,14 @@ def _request_sensitive_values(request: RunnerRequest) -> tuple[str, ...]:
         if value
         and any(
             marker in name.upper()
-            for marker in ("API_KEY", "TOKEN", "SECRET", "PASSWORD", "AUTH", "CREDENTIAL")
+            for marker in (
+                "API_KEY",
+                "TOKEN",
+                "SECRET",
+                "PASSWORD",
+                "AUTH",
+                "CREDENTIAL",
+            )
         )
     )
     return (
@@ -316,9 +340,7 @@ def _named_error(
             "\n".join(part for part in (reason, streams) if part),
             max_chars=1_200,
         )
-    message = (
-        f"Runner profile `{profile_name}` ({runner_type}) failed at stage `{stage_name}`"
-    )
+    message = f"Runner profile `{profile_name}` ({runner_type}) failed at stage `{stage_name}`"
     if details:
         message += f": {details}"
     return HookError(message)

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

@@ -65,7 +65,9 @@ def resolve_claude_executable() -> str:
     )
 
 
-def _capability_error(reason: str, *, details: str = "") -> RunnerAdapterUnavailableError:
+def _capability_error(
+    reason: str, *, details: str = ""
+) -> RunnerAdapterUnavailableError:
     return RunnerAdapterUnavailableError(
         "Claude Code CLI does not satisfy the required non-interactive contract",
         details=f"{reason}{(': ' + details) if details else ''}",
@@ -102,9 +104,13 @@ def check_claude_capabilities(
         raise _capability_error("help output was truncated")
 
     help_text = f"{help_result.stdout}\n{help_result.stderr}"
-    missing = tuple(marker for marker in REQUIRED_HELP_MARKERS if marker not in help_text)
+    missing = tuple(
+        marker for marker in REQUIRED_HELP_MARKERS if marker not in help_text
+    )
     if missing:
-        raise _capability_error("missing required flags or modes", details=", ".join(missing))
+        raise _capability_error(
+            "missing required flags or modes", details=", ".join(missing)
+        )
 
 
 def _protocol_failure(
@@ -158,13 +164,19 @@ def parse_claude_result(
     try:
         payload: Any = json.loads(raw)
     except json.JSONDecodeError as exc:
-        raise _protocol_failure(request, process_result, "stdout was not valid JSON") from exc
+        raise _protocol_failure(
+            request, process_result, "stdout was not valid JSON"
+        ) from exc
     if not isinstance(payload, dict):
-        raise _protocol_failure(request, process_result, "top-level JSON value was not an object")
+        raise _protocol_failure(
+            request, process_result, "top-level JSON value was not an object"
+        )
 
     message_type = payload.get("type")
     if message_type != "result":
-        raise _protocol_failure(request, process_result, "top-level JSON type was not result")
+        raise _protocol_failure(
+            request, process_result, "top-level JSON type was not result"
+        )
 
     is_error = payload.get("is_error")
     if not isinstance(is_error, bool):

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

@@ -111,14 +111,18 @@ def _parse_codex_jsonl(request: RunnerRequest, process: ProcessResult) -> _Codex
             thread_id = value
         elif event_type == "turn.started":
             if turn_open:
-                raise _protocol_error(request, process, "Codex JSONL turn order was invalid")
+                raise _protocol_error(
+                    request, process, "Codex JSONL turn order was invalid"
+                )
             turn_open = True
             if not terminal_failure:
                 terminal_success = False
         elif event_type == "item.completed":
             item = event.get("item")
             if not isinstance(item, dict):
-                raise _protocol_error(request, process, "Codex item.completed event had no item")
+                raise _protocol_error(
+                    request, process, "Codex item.completed event had no item"
+                )
             if item.get("type") == "agent_message":
                 text = item.get("text")
                 if not isinstance(text, str):
@@ -213,7 +217,9 @@ class CodexRunner:
         if process.stdout_truncated or process.stderr_truncated:
             raise _protocol_error(request, process, "Codex output stream was truncated")
         if not process.stdout.strip():
-            raise _protocol_error(request, process, "Codex emitted an empty JSONL stream")
+            raise _protocol_error(
+                request, process, "Codex emitted an empty JSONL stream"
+            )
 
         parsed = _parse_codex_jsonl(request, process)
         if not parsed.terminal_success:

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

@@ -25,8 +25,10 @@ _PLACEHOLDER_PATTERN = re.compile(r"\{[^{}]*\}")
 
 
 def _is_plain_text(value: object, *, allow_empty: bool = False) -> bool:
-    return isinstance(value, str) and (allow_empty or bool(value.strip())) and not any(
-        ord(character) < 32 for character in value
+    return (
+        isinstance(value, str)
+        and (allow_empty or bool(value.strip()))
+        and not any(ord(character) < 32 for character in value)
     )
 
 
@@ -69,10 +71,14 @@ def _validate_request(request: object) -> RunnerRequest:
         or not math.isfinite(request.timeout_seconds)
         or request.timeout_seconds <= 0
     ):
-        raise RunnerContractError("timeout_seconds must be finite and greater than zero")
+        raise RunnerContractError(
+            "timeout_seconds must be finite and greater than zero"
+        )
 
     if request.model is not None and not _is_plain_text(request.model):
-        raise RunnerContractError("model must be a non-empty NUL-free string when provided")
+        raise RunnerContractError(
+            "model must be a non-empty NUL-free string when provided"
+        )
     if request.variant is not None:
         raise RunnerContractError("variant is not valid for runner type command")
     if request.prompt_transport not in {"stdin", "argv"}:
@@ -85,11 +91,17 @@ def _validate_request(request: object) -> RunnerRequest:
     prompt_count = 0
     for index, argument in enumerate(command, start=1):
         if not isinstance(argument, str) or not argument.strip() or "\x00" in argument:
-            raise RunnerContractError(f"command[{index}] must be a non-empty NUL-free string")
+            raise RunnerContractError(
+                f"command[{index}] must be a non-empty NUL-free string"
+            )
         for placeholder in _PLACEHOLDER_PATTERN.findall(argument):
             if placeholder not in _ALLOWED_PLACEHOLDERS:
-                raise RunnerContractError(f"unknown placeholder {placeholder!r} in command[{index}]")
-        if ("{" in argument or "}" in argument) and argument not in _ALLOWED_PLACEHOLDERS:
+                raise RunnerContractError(
+                    f"unknown placeholder {placeholder!r} in command[{index}]"
+                )
+        if (
+            "{" in argument or "}" in argument
+        ) and argument not in _ALLOWED_PLACEHOLDERS:
             raise RunnerContractError(
                 f"placeholders in command[{index}] must be whole argv elements"
             )
@@ -97,7 +109,9 @@ def _validate_request(request: object) -> RunnerRequest:
             prompt_count += 1
 
     if request.prompt_transport == "stdin" and prompt_count:
-        raise RunnerContractError("command must not contain {prompt} with stdin transport")
+        raise RunnerContractError(
+            "command must not contain {prompt} with stdin transport"
+        )
     if request.prompt_transport == "argv" and prompt_count != 1:
         raise RunnerContractError(
             "command must contain exactly one {prompt} with argv transport"
@@ -142,7 +156,9 @@ class CommandRunner:
         except RunnerExecutableNotFoundError as exc:
             # The rendered argv can contain prompt/model values.  Do not
             # repeat the lower-level adapter's executable detail here.
-            raise RunnerExecutableNotFoundError("runner executable was not found") from exc
+            raise RunnerExecutableNotFoundError(
+                "runner executable was not found"
+            ) from exc
         result = RunnerResult(
             final_text=process_result.stdout,
             returncode=process_result.returncode,

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,