ai-push-hooks 0.2.0 → 0.3.0

package/src/ai_push_hooks/config.py

@@ -1,8 +1,11 @@
 from __future__ import annotations
 
+import math
 import os
 import pathlib
+import re
 import stat
+from collections.abc import Mapping
 from typing import Any
 
 from .executors.exec import env_bool, resolve_git_common_dir, resolve_git_dir
@@ -15,14 +18,25 @@ from .paths import (
     validate_path_component,
 )
 from .prompts_builtin import BUILTIN_PROMPTS
-from .types import GeneralConfig, HookConfig, HookError, LlmConfig, LoggingConfig, ModuleConfig, StepConfig, SUPPORTED_STEP_TYPES, WorkflowConfig
+from .types import (
+    SUPPORTED_STEP_TYPES,
+    GeneralConfig,
+    HookConfig,
+    HookError,
+    LlmConfig,
+    LoggingConfig,
+    ModuleConfig,
+    RunnerProfile,
+    StepConfig,
+    WorkflowConfig,
+)
 
 try:
     import tomllib
 except ModuleNotFoundError:  # pragma: no cover
     import tomli as tomllib
 
-ALLOWED_TOP_LEVEL_KEYS = {"general", "llm", "logging", "workflow", "modules"}
+ALLOWED_TOP_LEVEL_KEYS = {"general", "llm", "logging", "workflow", "modules", "runners"}
 STORAGE_NAMESPACE_PARTS = (".git", "ai-push-hooks")
 GENERAL_KEYS = {
     "enabled",
@@ -66,8 +80,34 @@ STEP_KEYS = {
     "allow_paths",
     "executor",
     "assertion",
+    "python",
+    "options",
+    "command",
+    "stdin",
+    "timeout_seconds",
     "when_env",
+    "runner",
 }
+RUNNER_TYPES = frozenset({"opencode", "codex", "claude", "command"})
+PROJECT_ACCESS_VALUES = frozenset({"artifacts", "project"})
+PROMPT_TRANSPORT_VALUES = frozenset({"stdin", "argv"})
+RUNNER_KEYS = {
+    "type",
+    "model",
+    "variant",
+    "project_access",
+    "command",
+    "prompt_transport",
+}
+RUNNER_PLACEHOLDERS = frozenset({"{prompt}", "{model}", "{cwd}", "{stage}"})
+PYTHON_CALLABLE_PATTERN = re.compile(r"[A-Za-z_][A-Za-z0-9_]*\Z")
+COMMAND_PLACEHOLDER_PATTERN = re.compile(r"\{([A-Za-z0-9_./:-]+)\}\Z")
+EMBEDDED_COMMAND_PLACEHOLDER_PATTERN = re.compile(
+    r"\{(?:repo|python|input:[A-Za-z0-9_./:-]+)\}"
+)
+COMMAND_PLACEHOLDER_NAMES = frozenset({"repo", "python"})
+DEFAULT_STEP_COMMAND_TIMEOUT_SECONDS = 60
+RUNNER_PLACEHOLDER_PATTERN = re.compile(r"\{[^{}]*\}")
 
 
 def _require_table(value: Any, label: str) -> dict[str, Any]:
@@ -106,6 +146,122 @@ def _validate_string_list(table: dict[str, Any], key: str, label: str) -> None:
         raise HookError(f"{label}.{key} must be an array of strings")
 
 
+def _validate_non_empty_string(table: dict[str, Any], key: str, label: str) -> None:
+    _validate_string(table, key, label)
+    if key in table and not table[key].strip():
+        raise HookError(f"{label}.{key} must be a non-empty string")
+
+
+def _validate_no_control_chars(value: str, label: str) -> None:
+    if any(ord(character) < 32 or ord(character) == 127 for character in value):
+        raise HookError(f"{label} must not contain NUL or control characters")
+
+
+def _validate_model_override(value: str | None) -> None:
+    if value is not None and not value.strip():
+        raise HookError("AI_PUSH_HOOKS_MODEL must be a non-empty model identifier")
+    if value is not None:
+        _validate_no_control_chars(value, "AI_PUSH_HOOKS_MODEL")
+
+
+def _validate_variant_override(value: str | None) -> None:
+    if value is not None:
+        _validate_no_control_chars(value, "AI_PUSH_HOOKS_VARIANT")
+
+
+def _validate_runner_command_placeholders(
+    command: list[str] | tuple[str, ...],
+    label: str,
+    transport: str,
+    model: Any,
+    effective_model: str | None = None,
+) -> None:
+    prompt_count = 0
+    for index, argument in enumerate(command, start=1):
+        argument_label = f"{label}.command[{index}]"
+        _validate_no_control_chars(argument, argument_label)
+        for placeholder in RUNNER_PLACEHOLDER_PATTERN.findall(argument):
+            if placeholder not in RUNNER_PLACEHOLDERS:
+                raise HookError(f"Unknown placeholder {placeholder!r} in {argument_label}")
+        if ("{" in argument or "}" in argument) and argument not in RUNNER_PLACEHOLDERS:
+            raise HookError(
+                f"Placeholders in {argument_label} must be whole argv elements"
+            )
+        if argument == "{prompt}":
+            prompt_count += 1
+    if transport == "stdin" and prompt_count:
+        raise HookError(f"{label}.command must not contain {{prompt}} with stdin transport")
+    if transport == "argv" and prompt_count != 1:
+        raise HookError(
+            f"{label}.command must contain exactly one {{prompt}} with argv transport"
+        )
+    if "{model}" in command and not (model or effective_model):
+        raise HookError(f"{label}.command uses {{model}} but {label}.model is not configured")
+
+
+def _validate_runner_profiles(
+    raw: dict[str, Any], effective_model: str | None = None
+) -> None:
+    runners = _require_table(raw.get("runners", {}), "runners")
+    for name, profile_value in runners.items():
+        if not isinstance(name, str) or not name.strip():
+            raise HookError("runners profile names must be non-empty strings")
+        _validate_no_control_chars(name, f"runners profile name `{name}`")
+        label = f"runners.{name}"
+        profile = _require_table(profile_value, label)
+        _validate_unknown_keys(profile, RUNNER_KEYS, label)
+        if "type" not in profile:
+            raise HookError(f"{label}.type is required")
+        _validate_non_empty_string(profile, "type", label)
+        runner_type = profile["type"].strip()
+        _validate_no_control_chars(profile["type"], f"{label}.type")
+        if runner_type not in RUNNER_TYPES:
+            raise HookError(f"{label}.type must be one of: {', '.join(sorted(RUNNER_TYPES))}")
+        _validate_string(profile, "model", label)
+        if "model" in profile and not profile["model"].strip():
+            raise HookError(f"{label}.model must be a non-empty string when provided")
+        if "model" in profile:
+            _validate_no_control_chars(profile["model"], f"{label}.model")
+        _validate_string(profile, "variant", label)
+        if "variant" in profile:
+            _validate_no_control_chars(profile["variant"], f"{label}.variant")
+        _validate_string(profile, "project_access", label)
+        _validate_string(profile, "prompt_transport", label)
+        if "project_access" in profile and profile["project_access"] not in PROJECT_ACCESS_VALUES:
+            raise HookError(f"{label}.project_access must be one of: artifacts, project")
+
+        type_specific_keys = {
+            "variant": runner_type == "opencode",
+            "command": runner_type == "command",
+            "prompt_transport": runner_type == "command",
+        }
+        for key, applicable in type_specific_keys.items():
+            if key in profile and not applicable:
+                raise HookError(f"{label}.{key} is only valid for runner type {('opencode' if key == 'variant' else 'command')}")
+
+        if runner_type != "command":
+            continue
+        if "command" not in profile:
+            raise HookError(f"{label}.command is required for runner type command")
+        _validate_string_list(profile, "command", label)
+        command = profile["command"]
+        if not command:
+            raise HookError(f"{label}.command must be a non-empty array")
+        for index, argument in enumerate(command, start=1):
+            if not argument.strip():
+                raise HookError(f"{label}.command[{index}] must be a non-empty string")
+        transport = profile.get("prompt_transport", "stdin")
+        if transport not in PROMPT_TRANSPORT_VALUES:
+            raise HookError(f"{label}.prompt_transport must be one of: argv, stdin")
+        _validate_runner_command_placeholders(
+            command,
+            label,
+            transport,
+            profile.get("model"),
+            effective_model,
+        )
+
+
 def _validate_integer(
     table: dict[str, Any], key: str, label: str, *, minimum: int | None = None
 ) -> None:
@@ -118,6 +274,198 @@ def _validate_integer(
         raise HookError(f"{label}.{key} must be at least {minimum}")
 
 
+def _validate_json_options(value: Any, label: str, *, path: str = "") -> None:
+    """Validate TOML options as finite, null-free JSON data."""
+
+    location = f"{label}{path}"
+    if value is None:
+        raise HookError(f"{location} must not be null")
+    if isinstance(value, (bool, str, int)):
+        return
+    if isinstance(value, float):
+        if not math.isfinite(value):
+            raise HookError(f"{location} must be a finite number")
+        return
+    if isinstance(value, list):
+        for index, item in enumerate(value, start=1):
+            _validate_json_options(item, label, path=f"{path}[{index}]")
+        return
+    if isinstance(value, dict):
+        for key, item in value.items():
+            if not isinstance(key, str):
+                raise HookError(f"{location} must use string keys")
+            _validate_json_options(item, label, path=f"{path}.{key}")
+        return
+    raise HookError(
+        f"{location} must contain only JSON-compatible null-free values"
+    )
+
+
+def _validate_python_reference(
+    value: str,
+    label: str,
+    repo_root: pathlib.Path | None = None,
+) -> str:
+    """Validate a repository-local callback reference without importing it."""
+
+    if value.count(":") != 1:
+        raise HookError(
+            f"{label} must be a repository-relative .py path followed by :callable"
+        )
+    path_value, callable_name = value.split(":", 1)
+    if not callable_name or not PYTHON_CALLABLE_PATTERN.fullmatch(callable_name):
+        raise HookError(f"{label} callable must be one top-level identifier")
+    try:
+        parts = relative_path_parts(path_value, f"{label} path")
+    except HookError as exc:
+        raise HookError(str(exc)) from exc
+    if not parts[-1].endswith(".py"):
+        raise HookError(f"{label} path must name a .py file")
+    normalized = "/".join(parts) + ":" + callable_name
+
+    if repo_root is None:
+        return normalized
+
+    root = pathlib.Path(repo_root).resolve(strict=False)
+    lexical_path = root.joinpath(*parts)
+    if path_has_symlink(root, lexical_path):
+        raise HookError(f"{label} path must not traverse a symlink or reparse point")
+    try:
+        callback_path = resolve_contained_path(
+            root, "/".join(parts), f"{label} path"
+        )
+    except HookError as exc:
+        raise HookError(str(exc)) from exc
+    try:
+        metadata = callback_path.lstat()
+    except FileNotFoundError as exc:
+        raise HookError(f"{label} path must reference an existing regular file") from exc
+    reparse_flag = getattr(stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0x400)
+    if stat.S_ISLNK(metadata.st_mode) or bool(
+        getattr(metadata, "st_file_attributes", 0) & reparse_flag
+    ):
+        raise HookError(f"{label} path must not be a symlink or reparse point")
+    if not stat.S_ISREG(metadata.st_mode):
+        raise HookError(f"{label} path must reference an ordinary regular file")
+
+    flags = os.O_RDONLY | getattr(os, "O_CLOEXEC", 0) | getattr(os, "O_NOFOLLOW", 0)
+    try:
+        descriptor = os.open(callback_path, flags)
+    except OSError as exc:
+        raise HookError(f"{label} path could not be opened safely") from exc
+    try:
+        descriptor_metadata = os.fstat(descriptor)
+        if not stat.S_ISREG(descriptor_metadata.st_mode):
+            raise HookError(f"{label} path must reference an ordinary regular file")
+    finally:
+        os.close(descriptor)
+    return normalized
+
+
+def _validate_step_extensions(
+    step: dict[str, Any],
+    label: str,
+    *,
+    repo_root: pathlib.Path | None = None,
+) -> None:
+    """Validate the implementation seams shared by config type checking/building."""
+
+    step_type = step.get("type")
+    if not isinstance(step_type, str):
+        return
+
+    implementation_keys = {
+        "collect": ("collector", "python"),
+        "exec": ("executor", "python", "command"),
+        "assert": ("assertion", "python", "command"),
+    }
+    implementations = implementation_keys.get(step_type)
+    if implementations is not None:
+        for key in implementations:
+            if key in {"collector", "executor", "assertion", "python"}:
+                value = step.get(key)
+                if isinstance(value, str) and not value.strip():
+                    raise HookError(f"{label}.{key} must be a non-empty string")
+        if "command" in step and not step["command"]:
+            raise HookError(f"{label}.command must be a non-empty array")
+        selected = [key for key in implementations if step.get(key) not in (None, "")]
+        if len(selected) != 1:
+            choices = ", ".join(implementations)
+            raise HookError(
+                f"{label} requires exactly one implementation field: {choices}"
+            )
+
+    applicable = {
+        "collector": {"collect"},
+        "executor": {"exec"},
+        "assertion": {"assert"},
+        "python": {"collect", "exec", "assert"},
+        "command": {"exec", "assert"},
+        "stdin": {"exec", "assert"},
+        "timeout_seconds": {"exec", "assert"},
+        "options": {"collect", "exec", "assert"},
+    }
+    for key, allowed_types in applicable.items():
+        if key in step and step_type not in allowed_types:
+            raise HookError(f"{label}.{key} is not valid for {step_type} steps")
+
+    has_python = step.get("python") not in (None, "")
+    has_command = bool(step.get("command"))
+    if "options" in step:
+        if not has_python:
+            raise HookError(f"{label}.options requires {label}.python")
+        _validate_json_options(step["options"], f"{label}.options")
+    if "stdin" in step and not has_command:
+        raise HookError(f"{label}.stdin is only valid with {label}.command")
+    if "timeout_seconds" in step and not has_command:
+        raise HookError(f"{label}.timeout_seconds is only valid with {label}.command")
+
+    if has_python:
+        inputs = step.get("inputs", [])
+        if len(inputs) != len(set(inputs)):
+            raise HookError(
+                f"{label}.inputs must not contain duplicate references for Python steps"
+            )
+        _validate_python_reference(step["python"], f"{label}.python", repo_root)
+
+    if has_command:
+        command = step["command"]
+        declared_inputs = set(step.get("inputs", []))
+        for index, argument in enumerate(command, start=1):
+            match = COMMAND_PLACEHOLDER_PATTERN.fullmatch(argument)
+            if match is not None:
+                token = match.group(1)
+                if token in COMMAND_PLACEHOLDER_NAMES:
+                    continue
+                if token.startswith("input:"):
+                    logical_ref = token.removeprefix("input:")
+                    if logical_ref not in declared_inputs:
+                        raise HookError(
+                            f"{label}.command[{index}] references undeclared input "
+                            f"`{logical_ref}`"
+                        )
+                    continue
+                raise HookError(
+                    f"Unknown command placeholder {{{token}}} in {label}.command[{index}]"
+                )
+            if EMBEDDED_COMMAND_PLACEHOLDER_PATTERN.search(argument):
+                raise HookError(
+                    f"Recognized command placeholders in {label}.command[{index}] "
+                    "must be whole argv elements"
+                )
+
+    if "stdin" in step and step.get("stdin") not in step.get("inputs", []):
+        raise HookError(f"{label}.stdin must exactly match a declared input")
+
+
+def _reject_legacy_step_type(step_type: str, label: str) -> None:
+    if step_type in {"llm", "agent"}:
+        raise HookError(
+            f"Legacy workflow step type `{step_type}` is not supported at {label}.type; "
+            "use `ask` instead"
+        )
+
+
 def _validate_config_types(raw: dict[str, Any]) -> None:
     unknown = set(raw) - ALLOWED_TOP_LEVEL_KEYS
     if unknown:
@@ -140,6 +488,12 @@ def _validate_config_types(raw: dict[str, Any]) -> None:
     _validate_unknown_keys(llm, LLM_KEYS, "llm")
     for key in ("runner", "model", "variant", "session_title_prefix"):
         _validate_string(llm, key, "llm")
+    _validate_non_empty_string(llm, "runner", "llm")
+    if "runner" in llm:
+        _validate_no_control_chars(llm["runner"], "llm.runner")
+    for key in ("model", "variant"):
+        if key in llm:
+            _validate_no_control_chars(llm[key], f"llm.{key}")
     for key in ("json_retry_new_session", "delete_session_after_run"):
         _validate_bool(llm, key, "llm")
     _validate_integer(llm, "timeout_seconds", "llm", minimum=1)
@@ -176,26 +530,66 @@ def _validate_config_types(raw: dict[str, Any]) -> None:
                 _validate_unknown_keys(step, STEP_KEYS, label)
                 for key in ("id", "type"):
                     _validate_string(step, key, label)
+                if isinstance(step.get("type"), str):
+                    _reject_legacy_step_type(step["type"].strip(), label)
                 for key in (
                     "collector",
                     "executor",
                     "assertion",
+                    "python",
                     "output",
                     "schema",
                     "prompt",
                     "prompt_file",
                     "fallback_prompt_id",
                     "when_env",
+                    "runner",
                 ):
                     _validate_string(step, key, label, allow_none=True)
-                for key in ("inputs", "allow_paths"):
+                for key in ("inputs", "allow_paths", "command"):
                     _validate_string_list(step, key, label)
+                if "options" in step and not isinstance(step["options"], dict):
+                    raise HookError(f"{label}.options must be a table")
+                _validate_string(step, "stdin", label, allow_none=True)
+                _validate_integer(step, "timeout_seconds", label, minimum=1)
+                if "runner" in step and step["runner"] is not None and not step["runner"].strip():
+                    raise HookError(f"{label}.runner must be a non-empty string")
+                if "runner" in step and step["runner"] is not None:
+                    _validate_no_control_chars(step["runner"], f"{label}.runner")
+                if (
+                    step.get("runner") is not None
+                    and isinstance(step.get("type"), str)
+                    and step["type"] in {"collect", "exec", "assert"}
+                ):
+                    raise HookError(f"{label}.runner is only valid on ask and apply steps")
+                _validate_step_extensions(step, label)
+
+def _normalize_runner_profile(name: str, raw: dict[str, Any]) -> RunnerProfile:
+    runner_type = str(raw["type"]).strip()
+    return RunnerProfile(
+        name=name,
+        type=runner_type,
+        model=str(raw["model"]) if raw.get("model") is not None else None,
+        variant=str(raw["variant"]) if raw.get("variant") is not None else None,
+        project_access=str(
+            raw.get(
+                "project_access",
+                "artifacts" if runner_type == "opencode" else "project",
+            )
+        ),
+        command=tuple(str(item) for item in raw.get("command", []) or []),
+        prompt_transport=str(raw.get("prompt_transport", "stdin")),
+    )
 
 
-def _normalize_step(raw: dict[str, Any]) -> StepConfig:
+def _normalize_step(
+    raw: dict[str, Any], label: str, *, repo_root: pathlib.Path | None = None
+) -> StepConfig:
     step_type = str(raw.get("type", "")).strip()
+    _reject_legacy_step_type(step_type, label)
     if step_type not in SUPPORTED_STEP_TYPES:
-        raise HookError(f"Unknown step type: {step_type}")
+        raise HookError(f"Unknown step type at {label}.type: {step_type}")
+    _validate_step_extensions(raw, label, repo_root=repo_root)
     step = StepConfig(
         id=str(raw.get("id", "")).strip(),
         type=step_type,
@@ -213,7 +607,17 @@ def _normalize_step(raw: dict[str, Any]) -> StepConfig:
         allow_paths=tuple(str(item) for item in raw.get("allow_paths", []) or []),
         executor=str(raw.get("executor")).strip() if raw.get("executor") is not None else None,
         assertion=str(raw.get("assertion")).strip() if raw.get("assertion") is not None else None,
+        python=str(raw.get("python")).strip() if raw.get("python") is not None else None,
+        options=dict(raw.get("options", {}) or {}),
+        command=tuple(str(item) for item in raw.get("command", []) or []),
+        stdin=str(raw.get("stdin")).strip() if raw.get("stdin") is not None else None,
+        timeout_seconds=(
+            int(raw["timeout_seconds"])
+            if raw.get("timeout_seconds") is not None
+            else (DEFAULT_STEP_COMMAND_TIMEOUT_SECONDS if raw.get("command") else None)
+        ),
         when_env=str(raw.get("when_env")).strip() if raw.get("when_env") is not None else None,
+        runner=str(raw.get("runner")).strip() if raw.get("runner") is not None else None,
     )
     if not step.id:
         raise HookError("Every workflow step requires a non-empty id")
@@ -228,23 +632,27 @@ def _normalize_step(raw: dict[str, Any]) -> StepConfig:
             raise HookError(f"Apply step `{step.id}` may not allow AGENTS.md")
     if step.is_promptable and not any([step.prompt, step.prompt_file, step.fallback_prompt_id]):
         raise HookError(f"Promptable step `{step.id}` requires prompt, prompt_file, or fallback_prompt_id")
-    if step.type == "collect" and not step.collector:
-        raise HookError(f"Collect step `{step.id}` requires collector")
-    if step.type == "llm" and not step.output:
-        raise HookError(f"LLM step `{step.id}` requires output")
+    if step.type == "collect" and not (step.collector or step.python):
+        raise HookError(f"Collect step `{step.id}` requires collector or python")
+    if step.type == "ask" and not step.output:
+        raise HookError(f"Ask step `{step.id}` requires output")
     if step.type == "apply" and not step.allow_paths:
         raise HookError(f"Apply step `{step.id}` requires allow_paths")
-    if step.type == "exec" and not step.executor:
-        raise HookError(f"Exec step `{step.id}` requires executor")
-    if step.type == "assert" and not step.assertion:
-        raise HookError(f"Assert step `{step.id}` requires assertion")
+    if step.type == "exec" and not (step.executor or step.python or step.command):
+        raise HookError(f"Exec step `{step.id}` requires executor, python, or command")
+    if step.type == "assert" and not (step.assertion or step.python or step.command):
+        raise HookError(f"Assert step `{step.id}` requires assertion, python, or command")
     return step
 
 
-def _build_config(raw: dict[str, Any]) -> HookConfig:
+def _build_config(
+    raw: dict[str, Any], *, effective_model: str | None = None,
+    repo_root: pathlib.Path | None = None,
+) -> HookConfig:
     if not isinstance(raw, dict):
         raise HookError("Config document must contain a top-level table")
     _validate_config_types(raw)
+    _validate_runner_profiles(raw, effective_model)
     unknown = set(raw) - ALLOWED_TOP_LEVEL_KEYS
     if unknown:
         raise HookError(
@@ -271,12 +679,50 @@ def _build_config(raw: dict[str, Any]) -> HookConfig:
         modules[module_id] = ModuleConfig(
             id=module_id,
             enabled=bool(module_raw.get("enabled", True)),
-            steps=tuple(_normalize_step(step) for step in steps_raw),
+            steps=tuple(
+                _normalize_step(
+                    step,
+                    f"modules.{module_id}.steps[{index}]",
+                    repo_root=repo_root,
+                )
+                for index, step in enumerate(steps_raw, start=1)
+            ),
         )
 
+    # Validate repository-local callback paths in disabled/unselected modules too,
+    # while preserving the existing runtime model that only workflow modules are
+    # materialized in HookConfig.modules.
+    if repo_root is not None:
+        for module_id, module_raw in module_payload.items():
+            for index, step_raw in enumerate(module_raw.get("steps", []) or [], start=1):
+                python_ref = step_raw.get("python")
+                if python_ref is not None:
+                    _validate_python_reference(
+                        python_ref,
+                        f"modules.{module_id}.steps[{index}].python",
+                        repo_root,
+                    )
+
     general = GeneralConfig(**raw.get("general", {}))
     llm = LlmConfig(**raw.get("llm", {}))
     logging = LoggingConfig(**raw.get("logging", {}))
+    runner_payload = raw.get("runners", {})
+    runners = {
+        name: _normalize_runner_profile(name, profile)
+        for name, profile in runner_payload.items()
+    }
+    if llm.runner != "opencode" and llm.runner not in runners:
+        raise HookError(f"llm.runner references missing runner profile `{llm.runner}`")
+    for module_id, module_raw in module_payload.items():
+        for index, step_raw in enumerate(module_raw.get("steps", []) or [], start=1):
+            step_runner = step_raw.get("runner")
+            if step_runner is None or step_runner == "opencode":
+                continue
+            if step_runner not in runners:
+                raise HookError(
+                    f"modules.{module_id}.steps[{index}].runner references missing runner profile "
+                    f"`{step_runner}`"
+                )
     for label, storage_path in (
         ("logging.dir", logging.dir),
         ("logging.transcript_dir", logging.transcript_dir),
@@ -291,10 +737,60 @@ def _build_config(raw: dict[str, Any]) -> HookConfig:
         logging=logging,
         workflow=WorkflowConfig(modules=workflow_modules),
         modules=modules,
+        runners=runners,
+    )
+
+
+def resolve_runner_profile(
+    config: HookConfig,
+    step: StepConfig,
+    env: Mapping[str, str] | None = None,
+) -> RunnerProfile:
+    """Resolve the runner selected by a promptable step and apply final env overrides."""
+    if step.type not in {"ask", "apply"} and step.runner is not None:
+        raise HookError(f"Step `{step.id}` may not select a runner")
+
+    selected_name = step.runner or config.llm.runner
+    profile = config.runners.get(selected_name)
+    if profile is None:
+        if selected_name != "opencode":
+            raise HookError(f"Runner profile `{selected_name}` does not exist")
+        profile = RunnerProfile(
+            name="opencode",
+            type="opencode",
+            model=config.llm.model,
+            variant=config.llm.variant,
+            project_access="artifacts",
+        )
+
+    environment = os.environ if env is None else env
+    model = profile.model
+    model_override = environment.get("AI_PUSH_HOOKS_MODEL")
+    _validate_model_override(model_override)
+    if model_override is not None:
+        model = model_override
+
+    variant = profile.variant
+    if profile.type == "opencode":
+        variant_override = environment.get("AI_PUSH_HOOKS_VARIANT")
+        _validate_variant_override(variant_override)
+        if variant_override is not None:
+            variant = variant_override.strip()
+
+    return RunnerProfile(
+        name=selected_name,
+        type=profile.type,
+        model=model,
+        variant=variant,
+        project_access=profile.project_access,
+        command=profile.command,
+        prompt_transport=profile.prompt_transport,
     )
 
 
-def _apply_env_overrides(config: HookConfig) -> HookConfig:
+def _apply_env_overrides(
+    config: HookConfig, *, repo_root: pathlib.Path | None = None
+) -> HookConfig:
     raw = {
         "general": {
             "enabled": config.general.enabled,
@@ -306,13 +802,47 @@ def _apply_env_overrides(config: HookConfig) -> HookConfig:
         "llm": config.llm.__dict__.copy(),
         "logging": config.logging.__dict__.copy(),
         "workflow": {"modules": list(config.workflow.modules)},
-        "modules": {},
+    "modules": {},
+        "runners": {},
     }
     for module_id, module in config.modules.items():
+        step_payloads: list[dict[str, Any]] = []
+        for step in module.steps:
+            step_payload = step.__dict__.copy()
+            for key in (
+                "collector",
+                "executor",
+                "assertion",
+                "python",
+                "stdin",
+                "timeout_seconds",
+                "when_env",
+                "runner",
+            ):
+                if step_payload[key] is None:
+                    step_payload.pop(key)
+            if not step_payload["options"]:
+                step_payload.pop("options")
+            if not step_payload["command"]:
+                step_payload.pop("command")
+            step_payloads.append(step_payload)
         raw["modules"][module_id] = {
             "enabled": module.enabled,
-            "steps": [step.__dict__.copy() for step in module.steps],
+            "steps": step_payloads,
+        }
+    for name, profile in config.runners.items():
+        runner_raw: dict[str, Any] = {
+            "type": profile.type,
+            "project_access": profile.project_access,
         }
+        if profile.model is not None:
+            runner_raw["model"] = profile.model
+        if profile.variant is not None:
+            runner_raw["variant"] = profile.variant
+        if profile.type == "command":
+            runner_raw["command"] = list(profile.command)
+            runner_raw["prompt_transport"] = profile.prompt_transport
+        raw["runners"][name] = runner_raw
 
     def read_env_bool(name: str) -> bool | None:
         value = os.getenv(name)
@@ -348,9 +878,11 @@ def _apply_env_overrides(config: HookConfig) -> HookConfig:
     if print_output is not None:
         raw["logging"]["print_llm_output"] = print_output
     model = os.getenv("AI_PUSH_HOOKS_MODEL")
-    if model:
+    _validate_model_override(model)
+    if model is not None:
         raw["llm"]["model"] = model
     variant = os.getenv("AI_PUSH_HOOKS_VARIANT")
+    _validate_variant_override(variant)
     if variant is not None:
         raw["llm"]["variant"] = variant.strip()
     timeout = os.getenv("AI_PUSH_HOOKS_TIMEOUT_SECONDS")
@@ -368,7 +900,7 @@ def _apply_env_overrides(config: HookConfig) -> HookConfig:
                 "must be at least 1"
             )
         raw["llm"]["timeout_seconds"] = parsed_timeout
-    return _build_config(raw)
+    return _build_config(raw, effective_model=model, repo_root=repo_root)
 
 
 def load_config(repo_root: pathlib.Path) -> tuple[HookConfig, pathlib.Path]:
@@ -393,7 +925,14 @@ def load_config(repo_root: pathlib.Path) -> tuple[HookConfig, pathlib.Path]:
         raise HookError(f"Invalid TOML in {config_path}{location}: {exc}") from exc
     if not isinstance(loaded, dict):
         raise HookError(f"Invalid config format in {config_path}: expected a top-level table")
-    return _apply_env_overrides(_build_config(loaded)), config_path
+    model_override = os.getenv("AI_PUSH_HOOKS_MODEL")
+    variant_override = os.getenv("AI_PUSH_HOOKS_VARIANT")
+    _validate_model_override(model_override)
+    _validate_variant_override(variant_override)
+    return _apply_env_overrides(
+        _build_config(loaded, effective_model=model_override, repo_root=repo_root),
+        repo_root=repo_root,
+    ), config_path
 
 
 def resolve_prompt_text(repo_root: pathlib.Path, step: StepConfig) -> str: