ai-push-hooks 0.1.19 → 0.2.0

package/pyproject.toml

@@ -4,25 +4,32 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ai-push-hooks"
-version = "0.1.19"
-description = "Modular AI push-hook workflow runner"
+version = "0.2.0"
+description = "Run structured AI-assisted checks and allowlisted maintenance before git push"
 readme = "README.md"
 requires-python = ">=3.10"
 license = "MIT"
-authors = [{ name = "ai-push-hooks contributors" }]
+authors = [{ name = "Shane Bishop" }]
 keywords = ["git", "lefthook", "docs", "ai", "pre-push"]
 classifiers = [
-  "Development Status :: 3 - Alpha",
+  "Development Status :: 4 - Beta",
   "Intended Audience :: Developers",
   "Programming Language :: Python :: 3",
   "Programming Language :: Python :: 3 :: Only",
   "Programming Language :: Python :: 3.10",
   "Programming Language :: Python :: 3.11",
   "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
   "Topic :: Software Development :: Version Control :: Git",
 ]
 dependencies = ["tomli>=2.0.0; python_version < '3.11'"]
 
+[project.urls]
+Homepage = "https://github.com/shanebishop1/ai-push-hooks"
+Repository = "https://github.com/shanebishop1/ai-push-hooks.git"
+Issues = "https://github.com/shanebishop1/ai-push-hooks/issues"
+Changelog = "https://github.com/shanebishop1/ai-push-hooks/blob/main/CHANGELOG.md"
+
 [project.scripts]
 ai-push-hooks = "ai_push_hooks.cli:main"
 

package/src/ai_push_hooks/artifacts.py

@@ -6,6 +6,15 @@ from datetime import datetime, timezone
 from typing import Any
 from uuid import uuid4
 
+from .paths import (
+    ensure_private_directory,
+    is_path_within,
+    path_has_symlink,
+    path_is_link_or_reparse,
+    resolve_contained_path,
+    validate_path_component,
+    write_text_no_follow,
+)
 from .types import HookError, ModuleRuntimeState
 
 
@@ -19,13 +28,42 @@ class ArtifactStore:
         self.run_dir = run_dir
 
     def prepare(self) -> pathlib.Path:
-        self.run_dir.mkdir(parents=True, exist_ok=True)
-        return self.run_dir
+        if path_is_link_or_reparse(self.run_dir):
+            raise HookError(
+                f"Artifact run directory must not be a symlink or reparse point: {self.run_dir}"
+            )
+        return ensure_private_directory(self.run_dir)
 
     def step_dir(self, module_id: str, step_index: int, step_id: str) -> pathlib.Path:
-        path = self.run_dir / module_id / f"{step_index:02d}-{step_id}"
-        path.mkdir(parents=True, exist_ok=True)
-        return path
+        module_name = validate_path_component(module_id, "Artifact module id")
+        step_name = validate_path_component(step_id, "Artifact step id")
+        lexical_module_path = self.run_dir / module_name
+        if path_has_symlink(self.run_dir, lexical_module_path):
+            raise HookError(f"Artifact module path must not traverse a symlink: {module_id}")
+        module_path = resolve_contained_path(self.run_dir, module_name, "Artifact module path")
+        lexical_step_path = module_path / f"{step_index:02d}-{step_name}"
+        if path_has_symlink(self.run_dir, lexical_step_path):
+            raise HookError(f"Artifact step path must not traverse a symlink: {step_id}")
+        path = resolve_contained_path(
+            module_path,
+            f"{step_index:02d}-{step_name}",
+            "Artifact step path",
+        )
+        return ensure_private_directory(path)
+
+    def _artifact_path(
+        self,
+        module_id: str,
+        step_index: int,
+        step_id: str,
+        artifact_name: str,
+    ) -> pathlib.Path:
+        name = validate_path_component(artifact_name, "Artifact name")
+        return resolve_contained_path(
+            self.step_dir(module_id, step_index, step_id),
+            name,
+            "Artifact output path",
+        )
 
     def register(
         self,
@@ -34,6 +72,13 @@ class ArtifactStore:
         artifact_name: str,
         path: pathlib.Path,
     ) -> pathlib.Path:
+        validate_path_component(step_id, "Artifact step id")
+        validate_path_component(artifact_name, "Artifact name")
+        resolved_run_dir = self.run_dir.resolve(strict=False)
+        if path_has_symlink(self.run_dir, path):
+            raise HookError(f"Artifact path must not traverse a symlink: {path}")
+        if not is_path_within(path.resolve(strict=False), resolved_run_dir):
+            raise HookError(f"Artifact path escapes run directory: {path}")
         state.artifacts[f"{step_id}/{artifact_name}"] = path
         return path
 
@@ -45,8 +90,8 @@ class ArtifactStore:
         artifact_name: str,
         content: str,
     ) -> pathlib.Path:
-        path = self.step_dir(state.module.id, step_index, step_id) / artifact_name
-        path.write_text(content, encoding="utf-8")
+        path = self._artifact_path(state.module.id, step_index, step_id, artifact_name)
+        write_text_no_follow(path, content)
         return self.register(state, step_id, artifact_name, path)
 
     def write_json(
@@ -57,8 +102,8 @@ class ArtifactStore:
         artifact_name: str,
         payload: Any,
     ) -> pathlib.Path:
-        path = self.step_dir(state.module.id, step_index, step_id) / artifact_name
-        path.write_text(json.dumps(payload, ensure_ascii=True, indent=2) + "\n", encoding="utf-8")
+        path = self._artifact_path(state.module.id, step_index, step_id, artifact_name)
+        write_text_no_follow(path, json.dumps(payload, ensure_ascii=True, indent=2) + "\n")
         return self.register(state, step_id, artifact_name, path)
 
     def resolve_input(self, state: ModuleRuntimeState, reference: str) -> pathlib.Path:
@@ -91,4 +136,7 @@ class ArtifactStore:
         artifact_name: str,
         path: pathlib.Path,
     ) -> None:
+        validate_path_component(module_id, "Artifact module id")
+        validate_path_component(step_id, "Artifact step id")
+        validate_path_component(artifact_name, "Artifact name")
         state.artifacts[f"{module_id}:{step_id}/{artifact_name}"] = path

package/src/ai_push_hooks/cli.py

@@ -1,10 +1,14 @@
 from __future__ import annotations
 
 import argparse
+import os
 import pathlib
+import stat
 import sys
 
 from .hook import run_hook
+from .install import install_hook
+from .paths import path_is_link_or_reparse, write_text_no_follow
 from .prompts_builtin import MINIMAL_DOCS_TEMPLATE
 from .types import HookError
 
@@ -20,6 +24,11 @@ def _build_parser() -> argparse.ArgumentParser:
     init_parser = subparsers.add_parser("init", help="Write a starter config")
     init_parser.add_argument("--template", default="minimal-docs")
     init_parser.add_argument("--force", action="store_true")
+
+    install_parser = subparsers.add_parser(
+        "install", help="Install a repo-local pre-push hook"
+    )
+    install_parser.add_argument("--force", action="store_true")
     return parser
 
 
@@ -28,9 +37,55 @@ def init_config(template: str, force: bool, cwd: pathlib.Path | None = None) ->
         raise HookError("Only `minimal-docs` is supported")
     target_dir = cwd or pathlib.Path.cwd()
     config_path = target_dir / "ai-push-hooks.toml"
-    if config_path.exists() and not force:
-        raise HookError(f"Refusing to overwrite existing config without --force: {config_path}")
-    config_path.write_text(MINIMAL_DOCS_TEMPLATE, encoding="utf-8")
+    if force:
+        try:
+            metadata = config_path.lstat()
+        except FileNotFoundError:
+            metadata = None
+        except OSError as exc:
+            raise HookError(f"Could not inspect config path {config_path}: {exc}") from exc
+        if metadata is not None:
+            if path_is_link_or_reparse(config_path):
+                raise HookError(f"Refusing to replace symlink or reparse point: {config_path}")
+            if not stat.S_ISREG(metadata.st_mode):
+                raise HookError(f"Refusing to replace non-regular config path: {config_path}")
+        try:
+            write_text_no_follow(config_path, MINIMAL_DOCS_TEMPLATE)
+        except HookError:
+            raise
+        except OSError as exc:
+            raise HookError(f"Could not write config file {config_path}: {exc}") from exc
+    else:
+        try:
+            metadata = config_path.lstat()
+        except FileNotFoundError:
+            metadata = None
+        except OSError as exc:
+            raise HookError(f"Could not inspect config path {config_path}: {exc}") from exc
+        if metadata is not None:
+            if path_is_link_or_reparse(config_path):
+                raise HookError(f"Refusing to overwrite symlink or reparse point: {config_path}")
+            if not stat.S_ISREG(metadata.st_mode):
+                raise HookError(f"Refusing to overwrite non-regular config path: {config_path}")
+        flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_CLOEXEC", 0)
+        flags |= getattr(os, "O_NOFOLLOW", 0)
+        try:
+            descriptor = os.open(config_path, flags, 0o600)
+        except FileExistsError as exc:
+            raise HookError(
+                f"Refusing to overwrite existing config without --force: {config_path}"
+            ) from exc
+        except OSError as exc:
+            raise HookError(f"Could not create config file {config_path}: {exc}") from exc
+        try:
+            with os.fdopen(descriptor, "w", encoding="utf-8") as handle:
+                descriptor = -1
+                handle.write(MINIMAL_DOCS_TEMPLATE)
+                handle.flush()
+                os.fsync(handle.fileno())
+        finally:
+            if descriptor >= 0:
+                os.close(descriptor)
     sys.stdout.write(str(config_path) + "\n")
     return 0
 
@@ -43,6 +98,8 @@ def main(argv: list[str] | None = None) -> int:
             return run_hook(args.remote_name, args.remote_url)
         if args.command == "init":
             return init_config(args.template, args.force)
+        if args.command == "install":
+            return install_hook(args.force)
         raise HookError(f"Unknown command: {args.command}")
     except HookError as exc:
         sys.stderr.write(f"[ai-push-hooks] {exc}\n")

package/src/ai_push_hooks/config.py

@@ -2,9 +2,18 @@ from __future__ import annotations
 
 import os
 import pathlib
+import stat
 from typing import Any
 
-from .executors.exec import env_bool
+from .executors.exec import env_bool, resolve_git_common_dir, resolve_git_dir
+from .paths import (
+    is_path_within,
+    normalized_component,
+    path_has_symlink,
+    relative_path_parts,
+    resolve_contained_path,
+    validate_path_component,
+)
 from .prompts_builtin import BUILTIN_PROMPTS
 from .types import GeneralConfig, HookConfig, HookError, LlmConfig, LoggingConfig, ModuleConfig, StepConfig, SUPPORTED_STEP_TYPES, WorkflowConfig
 
@@ -14,6 +23,173 @@ except ModuleNotFoundError:  # pragma: no cover
     import tomli as tomllib
 
 ALLOWED_TOP_LEVEL_KEYS = {"general", "llm", "logging", "workflow", "modules"}
+STORAGE_NAMESPACE_PARTS = (".git", "ai-push-hooks")
+GENERAL_KEYS = {
+    "enabled",
+    "allow_push_on_error",
+    "require_clean_worktree",
+    "skip_on_sync_branch",
+    "base_branch",
+}
+LLM_KEYS = {
+    "runner",
+    "model",
+    "variant",
+    "timeout_seconds",
+    "max_parallel",
+    "json_max_retries",
+    "invalid_json_feedback_max_chars",
+    "json_retry_new_session",
+    "delete_session_after_run",
+    "max_diff_bytes",
+    "session_title_prefix",
+}
+LOGGING_KEYS = {
+    "level",
+    "jsonl",
+    "dir",
+    "capture_llm_transcript",
+    "transcript_dir",
+    "summary_dir",
+    "print_llm_output",
+}
+STEP_KEYS = {
+    "id",
+    "type",
+    "inputs",
+    "output",
+    "schema",
+    "prompt",
+    "prompt_file",
+    "fallback_prompt_id",
+    "collector",
+    "allow_paths",
+    "executor",
+    "assertion",
+    "when_env",
+}
+
+
+def _require_table(value: Any, label: str) -> dict[str, Any]:
+    if not isinstance(value, dict):
+        raise HookError(f"{label} must be a table")
+    return value
+
+
+def _validate_unknown_keys(table: dict[str, Any], allowed: set[str], label: str) -> None:
+    unknown = set(table) - allowed
+    if unknown:
+        raise HookError(f"Unknown field(s) in {label}: {', '.join(sorted(unknown))}")
+
+
+def _validate_bool(table: dict[str, Any], key: str, label: str) -> None:
+    if key in table and type(table[key]) is not bool:
+        raise HookError(f"{label}.{key} must be a TOML boolean")
+
+
+def _validate_string(
+    table: dict[str, Any], key: str, label: str, *, allow_none: bool = False
+) -> None:
+    if key in table and (table[key] is None and allow_none):
+        return
+    if key in table and not isinstance(table[key], str):
+        raise HookError(f"{label}.{key} must be a string")
+
+
+def _validate_string_list(table: dict[str, Any], key: str, label: str) -> None:
+    if key not in table:
+        return
+    value = table[key]
+    if not isinstance(value, (list, tuple)) or any(
+        not isinstance(item, str) for item in value
+    ):
+        raise HookError(f"{label}.{key} must be an array of strings")
+
+
+def _validate_integer(
+    table: dict[str, Any], key: str, label: str, *, minimum: int | None = None
+) -> None:
+    if key not in table:
+        return
+    value = table[key]
+    if type(value) is not int:
+        raise HookError(f"{label}.{key} must be an integer")
+    if minimum is not None and value < minimum:
+        raise HookError(f"{label}.{key} must be at least {minimum}")
+
+
+def _validate_config_types(raw: dict[str, Any]) -> None:
+    unknown = set(raw) - ALLOWED_TOP_LEVEL_KEYS
+    if unknown:
+        raise HookError(
+            "Legacy or unsupported config keys are not allowed: " + ", ".join(sorted(unknown))
+        )
+
+    general = _require_table(raw.get("general", {}), "general")
+    _validate_unknown_keys(general, GENERAL_KEYS, "general")
+    for key in (
+        "enabled",
+        "allow_push_on_error",
+        "require_clean_worktree",
+        "skip_on_sync_branch",
+    ):
+        _validate_bool(general, key, "general")
+    _validate_string(general, "base_branch", "general")
+
+    llm = _require_table(raw.get("llm", {}), "llm")
+    _validate_unknown_keys(llm, LLM_KEYS, "llm")
+    for key in ("runner", "model", "variant", "session_title_prefix"):
+        _validate_string(llm, key, "llm")
+    for key in ("json_retry_new_session", "delete_session_after_run"):
+        _validate_bool(llm, key, "llm")
+    _validate_integer(llm, "timeout_seconds", "llm", minimum=1)
+    _validate_integer(llm, "max_parallel", "llm", minimum=1)
+    _validate_integer(llm, "json_max_retries", "llm", minimum=0)
+    _validate_integer(llm, "invalid_json_feedback_max_chars", "llm", minimum=1)
+    _validate_integer(llm, "max_diff_bytes", "llm", minimum=1)
+
+    logging = _require_table(raw.get("logging", {}), "logging")
+    _validate_unknown_keys(logging, LOGGING_KEYS, "logging")
+    for key in ("level", "dir", "transcript_dir", "summary_dir"):
+        _validate_string(logging, key, "logging")
+    for key in ("jsonl", "capture_llm_transcript", "print_llm_output"):
+        _validate_bool(logging, key, "logging")
+
+    workflow = _require_table(raw.get("workflow", {}), "workflow")
+    _validate_unknown_keys(workflow, {"modules"}, "workflow")
+    _validate_string_list(workflow, "modules", "workflow")
+
+    modules = _require_table(raw.get("modules", {}), "modules")
+    for module_id, module_value in modules.items():
+        if not isinstance(module_id, str):
+            raise HookError("modules keys must be strings")
+        module = _require_table(module_value, f"modules.{module_id}")
+        _validate_unknown_keys(module, {"enabled", "steps"}, f"modules.{module_id}")
+        _validate_bool(module, "enabled", f"modules.{module_id}")
+        if "steps" in module:
+            steps = module["steps"]
+            if not isinstance(steps, (list, tuple)):
+                raise HookError(f"modules.{module_id}.steps must be an array of tables")
+            for index, step_value in enumerate(steps, start=1):
+                step = _require_table(step_value, f"modules.{module_id}.steps[{index}]")
+                label = f"modules.{module_id}.steps[{index}]"
+                _validate_unknown_keys(step, STEP_KEYS, label)
+                for key in ("id", "type"):
+                    _validate_string(step, key, label)
+                for key in (
+                    "collector",
+                    "executor",
+                    "assertion",
+                    "output",
+                    "schema",
+                    "prompt",
+                    "prompt_file",
+                    "fallback_prompt_id",
+                    "when_env",
+                ):
+                    _validate_string(step, key, label, allow_none=True)
+                for key in ("inputs", "allow_paths"):
+                    _validate_string_list(step, key, label)
 
 
 def _normalize_step(raw: dict[str, Any]) -> StepConfig:
@@ -41,6 +217,15 @@ def _normalize_step(raw: dict[str, Any]) -> StepConfig:
     )
     if not step.id:
         raise HookError("Every workflow step requires a non-empty id")
+    validate_path_component(step.id, "Workflow step id")
+    if step.output:
+        validate_path_component(step.output, f"Output for step `{step.id}`")
+    for pattern in step.allow_paths:
+        parts = relative_path_parts(pattern, f"allow_paths entry for step `{step.id}`")
+        if any(normalized_component(part) == ".git" for part in parts):
+            raise HookError(f"Apply step `{step.id}` may not allow Git metadata paths")
+        if normalized_component(parts[-1]) == "agents.md":
+            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:
@@ -57,6 +242,9 @@ def _normalize_step(raw: dict[str, Any]) -> StepConfig:
 
 
 def _build_config(raw: dict[str, Any]) -> HookConfig:
+    if not isinstance(raw, dict):
+        raise HookError("Config document must contain a top-level table")
+    _validate_config_types(raw)
     unknown = set(raw) - ALLOWED_TOP_LEVEL_KEYS
     if unknown:
         raise HookError(
@@ -73,6 +261,7 @@ def _build_config(raw: dict[str, Any]) -> HookConfig:
 
     modules: dict[str, ModuleConfig] = {}
     for module_id in workflow_modules:
+        validate_path_component(module_id, "Workflow module id")
         if module_id not in module_payload:
             raise HookError(f"workflow.modules references unknown module `{module_id}`")
         module_raw = module_payload[module_id]
@@ -88,6 +277,14 @@ def _build_config(raw: dict[str, Any]) -> HookConfig:
     general = GeneralConfig(**raw.get("general", {}))
     llm = LlmConfig(**raw.get("llm", {}))
     logging = LoggingConfig(**raw.get("logging", {}))
+    for label, storage_path in (
+        ("logging.dir", logging.dir),
+        ("logging.transcript_dir", logging.transcript_dir),
+        ("logging.summary_dir", logging.summary_dir),
+    ):
+        parts = relative_path_parts(storage_path, label)
+        if parts[:2] != STORAGE_NAMESPACE_PARTS or len(parts) < 3:
+            raise HookError(f"{label} must be inside .git/ai-push-hooks/")
     return HookConfig(
         general=general,
         llm=llm,
@@ -117,16 +314,27 @@ def _apply_env_overrides(config: HookConfig) -> HookConfig:
             "steps": [step.__dict__.copy() for step in module.steps],
         }
 
-    skip = env_bool("AI_PUSH_HOOKS_SKIP")
+    def read_env_bool(name: str) -> bool | None:
+        value = os.getenv(name)
+        if value is None:
+            return None
+        parsed = env_bool(name)
+        if parsed is None:
+            raise HookError(
+                f"Invalid boolean environment override {name}: expected true/false"
+            )
+        return parsed
+
+    skip = read_env_bool("AI_PUSH_HOOKS_SKIP")
     if skip is True:
         raw["general"]["enabled"] = False
-    allow_on_error = env_bool("AI_PUSH_HOOKS_ALLOW_PUSH_ON_ERROR")
+    allow_on_error = read_env_bool("AI_PUSH_HOOKS_ALLOW_PUSH_ON_ERROR")
     if allow_on_error is not None:
         raw["general"]["allow_push_on_error"] = allow_on_error
-    require_clean = env_bool("AI_PUSH_HOOKS_REQUIRE_CLEAN")
+    require_clean = read_env_bool("AI_PUSH_HOOKS_REQUIRE_CLEAN")
     if require_clean is not None:
         raw["general"]["require_clean_worktree"] = require_clean
-    allow_dirty = env_bool("AI_PUSH_HOOKS_ALLOW_DIRTY")
+    allow_dirty = read_env_bool("AI_PUSH_HOOKS_ALLOW_DIRTY")
     if allow_dirty is True:
         raw["general"]["require_clean_worktree"] = False
     base_branch = os.getenv("AI_PUSH_HOOKS_BASE_BRANCH")
@@ -136,7 +344,7 @@ def _apply_env_overrides(config: HookConfig) -> HookConfig:
     logging_level = os.getenv("AI_PUSH_HOOKS_LOG_LEVEL")
     if logging_level:
         raw["logging"]["level"] = logging_level.strip().lower()
-    print_output = env_bool("AI_PUSH_HOOKS_PRINT_LLM_OUTPUT")
+    print_output = read_env_bool("AI_PUSH_HOOKS_PRINT_LLM_OUTPUT")
     if print_output is not None:
         raw["logging"]["print_llm_output"] = print_output
     model = os.getenv("AI_PUSH_HOOKS_MODEL")
@@ -146,8 +354,20 @@ def _apply_env_overrides(config: HookConfig) -> HookConfig:
     if variant is not None:
         raw["llm"]["variant"] = variant.strip()
     timeout = os.getenv("AI_PUSH_HOOKS_TIMEOUT_SECONDS")
-    if timeout:
-        raw["llm"]["timeout_seconds"] = int(timeout)
+    if timeout is not None:
+        try:
+            parsed_timeout = int(timeout.strip())
+        except ValueError as exc:
+            raise HookError(
+                "Invalid numeric environment override AI_PUSH_HOOKS_TIMEOUT_SECONDS: "
+                f"{timeout!r}"
+            ) from exc
+        if parsed_timeout < 1:
+            raise HookError(
+                "Invalid numeric environment override AI_PUSH_HOOKS_TIMEOUT_SECONDS: "
+                "must be at least 1"
+            )
+        raw["llm"]["timeout_seconds"] = parsed_timeout
     return _build_config(raw)
 
 
@@ -158,10 +378,21 @@ def load_config(repo_root: pathlib.Path) -> tuple[HookConfig, pathlib.Path]:
             "Missing required config file `ai-push-hooks.toml` in repo root. "
             "Run `ai-push-hooks init --template minimal-docs` first"
         )
-    text = config_path.read_text(encoding="utf-8")
-    loaded = tomllib.loads(text)
+    try:
+        text = config_path.read_text(encoding="utf-8")
+    except UnicodeDecodeError as exc:
+        raise HookError(f"Config file is not valid UTF-8: {config_path}") from exc
+    except OSError as exc:
+        raise HookError(f"Could not read config file {config_path}: {exc}") from exc
+    try:
+        loaded = tomllib.loads(text)
+    except ValueError as exc:
+        location = ""
+        if hasattr(exc, "lineno") and hasattr(exc, "colno"):
+            location = f" at line {exc.lineno}, column {exc.colno}"
+        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}")
+        raise HookError(f"Invalid config format in {config_path}: expected a top-level table")
     return _apply_env_overrides(_build_config(loaded)), config_path
 
 
@@ -169,11 +400,46 @@ def resolve_prompt_text(repo_root: pathlib.Path, step: StepConfig) -> str:
     if step.prompt and step.prompt.strip():
         return step.prompt.strip()
     if step.prompt_file:
-        prompt_path = pathlib.Path(step.prompt_file)
-        if not prompt_path.is_absolute():
-            prompt_path = (repo_root / prompt_path).resolve()
+        parts = relative_path_parts(step.prompt_file, f"Prompt file for step `{step.id}`")
+        if any(normalized_component(part) == ".git" for part in parts):
+            raise HookError(f"Prompt file for step `{step.id}` must not reference Git metadata")
+        lexical_prompt_path = repo_root.joinpath(*parts)
+        if path_has_symlink(repo_root, lexical_prompt_path):
+            raise HookError(f"Prompt file for step `{step.id}` must not traverse a symlink")
+        prompt_path = resolve_contained_path(
+            repo_root,
+            step.prompt_file,
+            f"Prompt file for step `{step.id}`",
+        )
+        resolved_prompt_path = prompt_path.resolve(strict=False)
+        try:
+            git_roots = (
+                resolve_git_dir(repo_root).resolve(strict=True),
+                resolve_git_common_dir(repo_root).resolve(strict=True),
+            )
+        except HookError:
+            git_roots = ()
+        if any(is_path_within(resolved_prompt_path, git_root) for git_root in git_roots):
+            raise HookError(f"Prompt file for step `{step.id}` must not resolve inside Git metadata")
         if prompt_path.exists():
-            text = prompt_path.read_text(encoding="utf-8").strip()
+            flags = os.O_RDONLY | getattr(os, "O_CLOEXEC", 0) | getattr(os, "O_NOFOLLOW", 0)
+            try:
+                descriptor = os.open(prompt_path, flags)
+            except OSError as exc:
+                raise HookError(
+                    f"Prompt file could not be opened safely for step `{step.id}`: {prompt_path}"
+                ) from exc
+            try:
+                if not stat.S_ISREG(os.fstat(descriptor).st_mode):
+                    raise HookError(
+                        f"Prompt file is not a regular file for step `{step.id}`: {prompt_path}"
+                    )
+                with os.fdopen(descriptor, "r", encoding="utf-8") as handle:
+                    descriptor = -1
+                    text = handle.read().strip()
+            finally:
+                if descriptor >= 0:
+                    os.close(descriptor)
             if text:
                 return text
         if step.fallback_prompt_id:

package/src/ai_push_hooks/engine.py

@@ -64,8 +64,6 @@ class WorkflowEngine:
                         continue
                     if any(not running_step.is_read_only for _future, (_state, running_step) in futures.items()):
                         continue
-                    if not step.is_read_only and futures:
-                        continue
                     if step.is_read_only and len(futures) >= max(1, self.context.config.llm.max_parallel):
                         continue
                     future = pool.submit(self._execute_step, state, step)