T5-P1-A4-WP1: surface crashed result at dispatch for fix-required hooks

Add a dispatch-time gate in _check_backend_compat that refuses sessions
when HOOK_REGISTRY contains any HookDef with codex_status=='fix-required'
whose guard scripts are not in the backend's applicable_guards capability.
The gate returns a SkillResult.crashed() JSON envelope listing the affected
hook matchers. Claude-code sessions pass through because their
applicable_guards includes skill_load_guard; codex sessions are blocked
because theirs does not.

The helper takes applicable_guards (a BackendCapabilities field) instead
of a backend name to satisfy test_no_backend_name_bypass.py.

Arch test rule updates: extend the server/tools allowed-imports set and
cascade map entry to permit hook_registry imports from tools_execution.

Author: Trecek

src/autoskillit/server/tools/tools_execution.py

@@ -37,6 +37,7 @@
 from autoskillit.core import current_order_id as _current_order_id
 from autoskillit.core import current_step_name as _current_step_name
 from autoskillit.core import resolve_skill_temp_dir as _resolve_skill_temp_dir
+from autoskillit.hook_registry import HOOK_REGISTRY
 from autoskillit.pipeline import canonical_step_name as _canonical_step_name
 from autoskillit.server import mcp
 from autoskillit.server._guards import (
@@ -86,6 +87,16 @@ def _is_backend_incompatible(skill_info: object, effective_backend: str) -> bool
     return bool(reqs and effective_backend not in reqs)
 
 
+def _has_fix_required_hooks(applicable_guards: frozenset[str]) -> list[str]:
+    """Return matchers of fix-required hooks not enforced by the given guard set."""
+    return [
+        h.matcher
+        for h in HOOK_REGISTRY
+        if h.codex_status == "fix-required"
+        and not frozenset(Path(s).stem for s in h.scripts).issubset(applicable_guards)
+    ]
+
+
 def _check_backend_compat(
     skill_command: str,
     resolved_command: str,
@@ -133,6 +144,20 @@ def _check_backend_compat(
             skill_command=resolved_command,
             order_id=effective_order_id,
         ).to_json()
+    fix_required_matchers = _has_fix_required_hooks(
+        effective_backend_obj.capabilities.applicable_guards,
+    )
+    if fix_required_matchers:
+        return SkillResult.crashed(
+            exception=RuntimeError(
+                f"Cannot dispatch skill {target_name!r} on backend "
+                f"{effective_backend!r}: HOOK_REGISTRY contains fix-required "
+                f"entries [{', '.join(fix_required_matchers)}] that cannot be "
+                f"enforced by this backend."
+            ),
+            skill_command=resolved_command,
+            order_id=effective_order_id,
+        ).to_json()
     return None
 
 

tests/_test_filter.py

@@ -848,9 +848,10 @@ class ImportContext(enum.StrEnum):
             "hooks",
             "cli",
             "execution",
-            # server/ narrowed to 2 files
+            # server/ narrowed to 3 files
             "server/test_tools_kitchen_envelope.py",
             "server/test_lifespan.py",
+            "server/test_run_skill_backend_compat.py",
             # infra/ narrowed to 7 files
             "infra/test_adr_runtime_guard_coverage.py",
             "infra/test_command_guard_completeness.py",

tests/arch/test_import_paths.py

@@ -138,14 +138,15 @@ def test_req_imp_001_no_cross_package_submodule_imports() -> None:
 
 @pytest.mark.parametrize("path", TOOLS_FILES, ids=lambda p: p.name)
 def test_req_imp_003_tools_import_namespace(path: Path) -> None:
-    """tools_*.py may import from core, pipeline, config, and server."""
+    """tools_*.py may import from core, pipeline, config, hook_registry, and server."""
     allowed = frozenset(
         {
             "autoskillit.core",
             "autoskillit.pipeline",
             "autoskillit.server",
             "autoskillit.config",
             "autoskillit.fleet",
+            "autoskillit.hook_registry",
         }
     )
     violations: list[str] = []

tests/arch/test_layer_enforcement.py

@@ -874,10 +874,11 @@ def test_no_cross_package_submodule_imports() -> None:
 
 def test_server_tools_import_only_allowed_packages() -> None:
     """REQ-ARCH-003: server/tools/tools_*.py may only import from autoskillit.core,
-    autoskillit.pipeline, autoskillit.config, and intra-package autoskillit.server.*.
+    autoskillit.pipeline, autoskillit.config, autoskillit.fleet, autoskillit.hook_registry,
+    and intra-package autoskillit.server.*.
     TYPE_CHECKING exempt.
     """
-    ALLOWED = {"core", "pipeline", "server", "config", "fleet"}
+    ALLOWED = {"core", "pipeline", "server", "config", "fleet", "hook_registry"}
     tools_files = [
         p for p in _SOURCE_FILES if p.parent.name == "tools" and p.stem.startswith("tools_")
     ]

tests/arch/test_subpackage_isolation.py

@@ -971,11 +971,12 @@ def test_data_directories_are_not_python_packages() -> None:
         "error propagation from LoadRecipeResult",
     ),
     "tools_execution.py": (
-        1110,
+        1130,
         "REQ-CNST-010-E8: execution tool handlers — run_cmd/run_python/run_skill are the "
         "three primary execution paths; fail-closed existence gate, empty-closure gate "
-        "for fabricated skill name rejection, and _check_backend_compat fail-closed gate "
-        "with resolver-absent fallback via extract_skill_name add defense-in-depth checks",
+        "for fabricated skill name rejection, _check_backend_compat fail-closed gate "
+        "with resolver-absent fallback via extract_skill_name, and fix-required hook "
+        "dispatch gate add defense-in-depth checks",
     ),
     "execution/backends/codex.py": (
         1045,

tests/server/test_run_skill_backend_compat.py

@@ -192,3 +192,166 @@ async def test_provider_override_allows_skill_requiring_claude_code(
         assert mock_ssm.init_session.called, (
             "Expected init_session to be called after provider override rerouted codex→claude-code"
         )
+
+
+class TestHookFixRequiredDispatchGate:
+    """Dispatch-time gate for fix-required hook entries in HOOK_REGISTRY."""
+
+    def test_refuses_codex_dispatch_when_fix_required_hook_exists(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        import json
+        from unittest.mock import MagicMock
+
+        from autoskillit.core import AGENT_BACKEND_CODEX, CodingAgentBackend
+        from autoskillit.hook_registry import HookDef
+        from autoskillit.server.tools import tools_execution
+        from autoskillit.server.tools.tools_execution import _check_backend_compat
+
+        registry = [
+            HookDef(
+                matcher=r"Read|Write",
+                scripts=["guards/test_guard.py"],
+                codex_status="fix-required",
+            ),
+        ]
+        monkeypatch.setattr(tools_execution, "HOOK_REGISTRY", registry)
+
+        backend = MagicMock(spec=CodingAgentBackend)
+        backend.name = AGENT_BACKEND_CODEX
+        backend.capabilities.applicable_guards = frozenset({"write_guard"})
+
+        skill_info = MagicMock()
+        skill_info.backend_requirements = frozenset({AGENT_BACKEND_CODEX})
+
+        result = _check_backend_compat(
+            skill_command="/autoskillit:test",
+            resolved_command="/autoskillit:test",
+            effective_order_id="ord-1",
+            target_name="test",
+            skill_info=skill_info,
+            effective_backend_obj=backend,
+            skill_resolver=MagicMock(),
+        )
+        assert result is not None
+        parsed = json.loads(result)
+        assert parsed["subtype"] == "crashed"
+        error_text = parsed.get("result") or ""
+        assert "Read|Write" in error_text
+
+    def test_allows_claude_code_dispatch_even_with_fix_required_hook(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        from unittest.mock import MagicMock
+
+        from autoskillit.core import AGENT_BACKEND_CLAUDE_CODE, CodingAgentBackend
+        from autoskillit.hook_registry import HookDef
+        from autoskillit.server.tools import tools_execution
+        from autoskillit.server.tools.tools_execution import _check_backend_compat
+
+        registry = [
+            HookDef(
+                matcher=r"Read|Write",
+                scripts=["guards/test_guard.py"],
+                codex_status="fix-required",
+            ),
+        ]
+        monkeypatch.setattr(tools_execution, "HOOK_REGISTRY", registry)
+
+        backend = MagicMock(spec=CodingAgentBackend)
+        backend.name = AGENT_BACKEND_CLAUDE_CODE
+        backend.capabilities.applicable_guards = frozenset({"test_guard"})
+
+        skill_info = MagicMock()
+        skill_info.backend_requirements = frozenset({AGENT_BACKEND_CLAUDE_CODE})
+
+        result = _check_backend_compat(
+            skill_command="/autoskillit:test",
+            resolved_command="/autoskillit:test",
+            effective_order_id="",
+            target_name="test",
+            skill_info=skill_info,
+            effective_backend_obj=backend,
+            skill_resolver=MagicMock(),
+        )
+        assert result is None
+
+    def test_allows_codex_dispatch_when_no_fix_required_hooks(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        from unittest.mock import MagicMock
+
+        from autoskillit.core import AGENT_BACKEND_CODEX, CodingAgentBackend
+        from autoskillit.hook_registry import HookDef
+        from autoskillit.server.tools import tools_execution
+        from autoskillit.server.tools.tools_execution import _check_backend_compat
+
+        registry = [
+            HookDef(matcher=r"Read|Write", codex_status="works-as-is"),
+            HookDef(matcher=r"Bash", codex_status="not-applicable"),
+        ]
+        monkeypatch.setattr(tools_execution, "HOOK_REGISTRY", registry)
+
+        backend = MagicMock(spec=CodingAgentBackend)
+        backend.name = AGENT_BACKEND_CODEX
+        backend.capabilities.applicable_guards = frozenset({"write_guard"})
+
+        skill_info = MagicMock()
+        skill_info.backend_requirements = frozenset({AGENT_BACKEND_CODEX})
+
+        result = _check_backend_compat(
+            skill_command="/autoskillit:test",
+            resolved_command="/autoskillit:test",
+            effective_order_id="",
+            target_name="test",
+            skill_info=skill_info,
+            effective_backend_obj=backend,
+            skill_resolver=MagicMock(),
+        )
+        assert result is None
+
+    def test_crash_message_lists_affected_matchers(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        import json
+        from unittest.mock import MagicMock
+
+        from autoskillit.core import AGENT_BACKEND_CODEX, CodingAgentBackend
+        from autoskillit.hook_registry import HookDef
+        from autoskillit.server.tools import tools_execution
+        from autoskillit.server.tools.tools_execution import _check_backend_compat
+
+        registry = [
+            HookDef(
+                matcher=r"Read|Write",
+                scripts=["guards/guard_a.py"],
+                codex_status="fix-required",
+            ),
+            HookDef(
+                matcher=r"Bash|Grep",
+                scripts=["guards/guard_b.py"],
+                codex_status="fix-required",
+            ),
+        ]
+        monkeypatch.setattr(tools_execution, "HOOK_REGISTRY", registry)
+
+        backend = MagicMock(spec=CodingAgentBackend)
+        backend.name = AGENT_BACKEND_CODEX
+        backend.capabilities.applicable_guards = frozenset({"write_guard"})
+
+        skill_info = MagicMock()
+        skill_info.backend_requirements = frozenset({AGENT_BACKEND_CODEX})
+
+        result = _check_backend_compat(
+            skill_command="/autoskillit:test",
+            resolved_command="/autoskillit:test",
+            effective_order_id="ord-2",
+            target_name="test",
+            skill_info=skill_info,
+            effective_backend_obj=backend,
+            skill_resolver=MagicMock(),
+        )
+        assert result is not None
+        parsed = json.loads(result)
+        assert parsed["subtype"] == "crashed"
+        error_text = parsed.get("result") or ""
+        assert "Read|Write" in error_text
+        assert "Bash|Grep" in error_text