From dab37256018e8b6490e3985de6fe1f3b4b34a9fc Mon Sep 17 00:00:00 2001 From: Trecek Date: Sun, 25 Oct 2026 12:38:46 -0700 Subject: [PATCH 01/10] fix: emit only consumer-defined hook document keys --- src/autoskillit/cli/_hooks.py | 3 +- src/autoskillit/hook_registry/_rendering.py | 10 +-- .../_projected_artifact/_hook_repair.py | 2 +- tests/_test_filter.py | 1 - .../test_durable_artifact_writers_guard.py | 4 +- tests/cli/test_cli_hooks.py | 35 +++++++++ .../test_claude_code_interface_contracts.py | 76 +++++++++++++++++++ .../test_durable_artifact_relocatability.py | 8 +- .../test_hook_path_relocatability.py | 47 ++---------- tests/hooks/test_hook_executability.py | 20 ++--- tests/server/test_lifespan.py | 22 ------ 11 files changed, 138 insertions(+), 90 deletions(-) diff --git a/src/autoskillit/cli/_hooks.py b/src/autoskillit/cli/_hooks.py index cf9a679901..7806953ef1 100644 --- a/src/autoskillit/cli/_hooks.py +++ b/src/autoskillit/cli/_hooks.py @@ -104,6 +104,7 @@ def _evict_stale_autoskillit_hooks(settings_path: Path) -> None: entry["hooks"] = non_autoskillit cleaned.append(entry) hooks[event_type] = cleaned + data.pop("_autoskillit_registry_hash", None) _write_settings_data(settings_path, data) @@ -120,7 +121,6 @@ def sync_hooks_to_settings(settings_path: Path, *, force: bool = False) -> None: correctly checks plugin status before writing. """ from autoskillit.cli._init_helpers import _is_plugin_installed - from autoskillit.hook_registry import HOOK_REGISTRY_HASH root = pkg_root() if is_git_worktree(root): @@ -159,7 +159,6 @@ def sync_hooks_to_settings(settings_path: Path, *, force: bool = False) -> None: for (event_type, _), entry in groups.items(): event_list: list[dict] = data.setdefault("hooks", {}).setdefault(event_type, []) event_list.append(entry) - data["_autoskillit_registry_hash"] = HOOK_REGISTRY_HASH _write_settings_data(settings_path, data) diff --git a/src/autoskillit/hook_registry/_rendering.py b/src/autoskillit/hook_registry/_rendering.py index 2a250bbf41..d7f209c029 100644 --- a/src/autoskillit/hook_registry/_rendering.py +++ b/src/autoskillit/hook_registry/_rendering.py @@ -12,7 +12,6 @@ from collections.abc import Sequence from pathlib import Path -from ._hashing import compute_registry_hash from ._hooks_defs import ( _LOGICAL_HOOK_COMPONENT, HookDef, @@ -23,7 +22,6 @@ LIFECYCLE_CONTRACTS, PLUGIN_ROOT_TOKEN, PROTECTION_WAIVERS, - RETIRED_SCRIPT_BASENAMES, ) @@ -174,10 +172,4 @@ def generate_hooks_json( by_event: dict[str, list] = {} for (event_type, _), entry in groups.items(): by_event.setdefault(event_type, []).append(entry) - registry_hash = compute_registry_hash( - registry, - RETIRED_SCRIPT_BASENAMES, - lifecycle_contracts, - PROTECTION_WAIVERS, - ) - return {"hooks": by_event, "_autoskillit_registry_hash": registry_hash} + return {"hooks": by_event} diff --git a/src/autoskillit/workspace/_projected_artifact/_hook_repair.py b/src/autoskillit/workspace/_projected_artifact/_hook_repair.py index 41df817659..f4e06d22f0 100644 --- a/src/autoskillit/workspace/_projected_artifact/_hook_repair.py +++ b/src/autoskillit/workspace/_projected_artifact/_hook_repair.py @@ -358,7 +358,7 @@ def _repair_hook_payload_under_lease( try: atomic_write( hooks_json_path, - json.dumps(fresh, indent=2) + "\n", + json.dumps({"hooks": fresh["hooks"]}, indent=2) + "\n", strict_durability=True, ) write_manifest_refresh(manifest_refresh) diff --git a/tests/_test_filter.py b/tests/_test_filter.py index f8e23a5295..1f1ef26986 100644 --- a/tests/_test_filter.py +++ b/tests/_test_filter.py @@ -1583,7 +1583,6 @@ class SourceMapRejection(enum.StrEnum): "server/test_preflight_explicit_backend.py", "server/test_managed_join_prelaunch.py", "server/test_tools_fleet_dispatch_preflight.py", - "server/test_lifespan.py", # file-level: live output-budget E2E imports the hook registry directly "server/test_output_budget_e2e.py", "execution/backends/test_claude_join_recovery_live_gate.py", diff --git a/tests/arch/test_durable_artifact_writers_guard.py b/tests/arch/test_durable_artifact_writers_guard.py index df199cbb1b..e9c63e3016 100644 --- a/tests/arch/test_durable_artifact_writers_guard.py +++ b/tests/arch/test_durable_artifact_writers_guard.py @@ -96,9 +96,7 @@ ("workspace/_projected_artifact/_publication.py", "materialize_sanitized_plugin_root"), # Verbatim byte-for-byte asset copy — no path is baked into the copy. ("workspace/_projected_artifact/_publication.py", "_copy_non_skill_plugin_assets"), - # Drift-check re-renders hooks.json from the registry hash; same content - # unless the registry changes, so this is the canonical hook-config writer, - # not a hook-artifact writer. + # Drift-check re-renders hooks.json when its bytes differ from render_hooks_json_text(). ("server/lifecycle/_lifespan/_startup_checks.py", "run_startup_drift_check"), } ) diff --git a/tests/cli/test_cli_hooks.py b/tests/cli/test_cli_hooks.py index ea407016e4..d3ba12b30e 100644 --- a/tests/cli/test_cli_hooks.py +++ b/tests/cli/test_cli_hooks.py @@ -226,6 +226,41 @@ def test_evict_stale_hooks_removes_legacy_formats(tmp_path): assert len(quota_commands) == 1 +def test_evict_removes_orphaned_registry_hash_key(tmp_path: Path) -> None: + from autoskillit.cli._hooks import _evict_stale_autoskillit_hooks + + settings = tmp_path / "settings.json" + user_group = {"matcher": "Bash", "hooks": [{"type": "command", "command": "echo hi"}]} + seed = { + "permissions": {"allow": ["Bash(git status)"]}, + "env": {"PROJECT_MODE": "test"}, + "_autoskillit_registry_hash": "legacy", + "hooks": { + "PreToolUse": [ + { + "matcher": "Read", + "hooks": [ + { + "type": "command", + "command": "python3 /old/hooks/_dispatch.py guards/tool_guard", + } + ], + }, + user_group, + ] + }, + } + settings.write_text(json.dumps(seed)) + + _evict_stale_autoskillit_hooks(settings) + + data = json.loads(settings.read_text()) + assert "_autoskillit_registry_hash" not in data + assert data["permissions"] == seed["permissions"] + assert data["env"] == seed["env"] + assert data["hooks"]["PreToolUse"] == [user_group] + + # T-REG-1 def test_install_production_order_includes_quota_check(tmp_path, monkeypatch): """install() must register quota_guard.py in hooks.json (plugin authority path).""" diff --git a/tests/contracts/test_claude_code_interface_contracts.py b/tests/contracts/test_claude_code_interface_contracts.py index 25679c8c8e..d9bccfb94d 100644 --- a/tests/contracts/test_claude_code_interface_contracts.py +++ b/tests/contracts/test_claude_code_interface_contracts.py @@ -20,6 +20,8 @@ import autoskillit.cli.session._session_process as _patch_session__session_process import autoskillit.cli.session._session_reload as _patch_session__session_reload import autoskillit.cli.ui._timed_input as _patch_ui__timed_input +import autoskillit.hooks # noqa: F401 +from autoskillit.hook_registry import render_hooks_json_text pytestmark = [pytest.mark.layer("contracts"), pytest.mark.medium] @@ -402,6 +404,80 @@ def test_mcp_json_autoskillit_has_command_key(self) -> None: ) +# Supported keys of a Claude Code plugin hooks/hooks.json. Sources (retrieved 2026-10-25): +# https://code.claude.com/docs/en/hooks.md — top level description, hooks; matcher group +# matcher, hooks; handler fields type, if, timeout, statusMessage, and command +# fields command, args, async, asyncRewake, shell +# https://code.claude.com/docs/en/plugins/mods/reference.md — top level modules +# Claude Code CHANGELOG 2.1.274 — top level $schema; 2.1.295 — handler onFailure +_CLAUDE_HOOKS_FILE_KEYS = frozenset({"$schema", "description", "hooks", "modules"}) +_CLAUDE_MATCHER_GROUP_KEYS = frozenset({"matcher", "hooks"}) +# once is honored only in skill frontmatter. +_CLAUDE_COMMAND_HANDLER_KEYS = frozenset( + { + "type", + "command", + "args", + "async", + "asyncRewake", + "shell", + "onFailure", + "timeout", + "if", + "statusMessage", + } +) + + +def _unknown_claude_hook_keys(doc) -> dict[str, set[str]]: + unknown = {} + if extra := set(doc) - _CLAUDE_HOOKS_FILE_KEYS: + unknown["$"] = extra + for event, groups in doc["hooks"].items(): + for group_index, group in enumerate(groups): + group_path = f"$.hooks.{event}[{group_index}]" + if extra := set(group) - _CLAUDE_MATCHER_GROUP_KEYS: + unknown[group_path] = extra + for handler_index, handler in enumerate(group["hooks"]): + if extra := set(handler) - _CLAUDE_COMMAND_HANDLER_KEYS: + unknown[f"{group_path}.hooks[{handler_index}]"] = extra + return unknown + + +class TestClaudeHooksJsonContract: + """Strict key hygiene for generated command hooks, not full schema validation. + + Recheck the upstream hooks reference and CHANGELOG when revising these key sets. + """ + + def test_rendered_hooks_json_uses_only_claude_accepted_keys(self) -> None: + import json + + doc = json.loads(render_hooks_json_text()) + assert "hooks" in doc + unknown = _unknown_claude_hook_keys(doc) + assert not unknown, {path: sorted(keys) for path, keys in unknown.items()} + + @pytest.mark.parametrize( + "path", + [None, "$", "$.hooks.PreToolUse[0]", "$.hooks.PreToolUse[0].hooks[0]"], + ids=["valid", "root", "matcher-group", "handler"], + ) + def test_hooks_key_checker_reports_unknown_keys_by_path(self, path: str | None) -> None: + handler = {"type": "command", "command": "echo ok"} + group = {"matcher": "Bash", "hooks": [handler]} + doc = {"hooks": {"PreToolUse": [group]}} + if path is not None: + target = { + "$": doc, + "$.hooks.PreToolUse[0]": group, + "$.hooks.PreToolUse[0].hooks[0]": handler, + }[path] + target["_unexpected"] = True + expected = {} if path is None else {path: {"_unexpected"}} + assert _unknown_claude_hook_keys(doc) == expected + + # --------------------------------------------------------------------------- # CC-007: plugin.json structure contract # --------------------------------------------------------------------------- diff --git a/tests/contracts/test_durable_artifact_relocatability.py b/tests/contracts/test_durable_artifact_relocatability.py index a70d7da259..06405f5979 100644 --- a/tests/contracts/test_durable_artifact_relocatability.py +++ b/tests/contracts/test_durable_artifact_relocatability.py @@ -384,6 +384,7 @@ def test_plugin_cache_repair_output_is_relocatable(self, tmp_path: Path) -> None (hooks_dir / "hooks.json").write_text( json.dumps( { + "_autoskillit_registry_hash": "legacy", "hooks": { "PreToolUse": [ { @@ -399,7 +400,7 @@ def test_plugin_cache_repair_output_is_relocatable(self, tmp_path: Path) -> None ], } ] - } + }, } ) ) @@ -412,6 +413,11 @@ def test_plugin_cache_repair_output_is_relocatable(self, tmp_path: Path) -> None outcomes = repair_broken_plugin_cache_hooks(cache_dir, home=managed_home_for(tmp_path)) assert outcomes[0].status is PluginHookRepairStatus.REPAIRED + payload = json.loads((hooks_dir / "hooks.json").read_text()) + assert set(payload) == {"hooks"} + assert payload["hooks"]["PreToolUse"][0]["hooks"][0]["command"].endswith( + " guards/tool_guard" + ) _assert_relocatable((hooks_dir / "hooks.json").read_text()) def test_projection_repair_outputs_are_relocatable(self, tmp_path: Path) -> None: diff --git a/tests/contracts/test_hook_path_relocatability.py b/tests/contracts/test_hook_path_relocatability.py index 3498158822..e170b5f912 100644 --- a/tests/contracts/test_hook_path_relocatability.py +++ b/tests/contracts/test_hook_path_relocatability.py @@ -19,7 +19,6 @@ import pytest -import autoskillit.cli._init_helpers as _patch_cli__init_helpers from autoskillit.hook_registry import PLUGIN_ROOT_TOKEN, generate_hooks_json pytestmark = [pytest.mark.layer("contracts"), pytest.mark.medium] @@ -53,36 +52,6 @@ def test_generate_hooks_json_commands_are_relocatable() -> None: ) -def test_compute_registry_hash_is_identical_for_absolute_and_relocatable_renderings( - tmp_path: Path, monkeypatch: pytest.MonkeyPatch -) -> None: - """compute_registry_hash hashes logical registry rows (scripts, event - type, matcher, timeout) — never the rendered command string — so the - embedded ``_autoskillit_registry_hash`` must be identical whether the - hooks are rendered in relocatable (hooks.json) form or absolute - (settings.json, dev-mode) form. This test pins the invariant so a future - refactor that accidentally threads the rendered command into the hash - cannot regress silently. - """ - import autoskillit.cli._hooks as _hooks_mod - from autoskillit.cli._hooks import sync_hooks_to_settings - - # sync_hooks_to_settings() refuses to run from a git worktree (its own - # dev-machine safety guard, unrelated to the property under test) and - # short-circuits to an eviction-only no-op when the plugin is installed - # — same idiom as tests/cli/conftest.py's autouse fixture. - monkeypatch.setattr(_hooks_mod, "is_git_worktree", lambda _path: False) - monkeypatch.setattr(_patch_cli__init_helpers, "_is_plugin_installed", lambda **kwargs: False) - - relocatable_hash = generate_hooks_json()["_autoskillit_registry_hash"] - - settings_path = tmp_path / "settings.json" - sync_hooks_to_settings(settings_path) - absolute_hash = json.loads(settings_path.read_text())["_autoskillit_registry_hash"] - - assert relocatable_hash == absolute_hash - - # --------------------------------------------------------------------------- # Self-healed bundled hooks.json is canonical and machine-independent. # --------------------------------------------------------------------------- @@ -117,15 +86,10 @@ def test_self_healed_bundled_hooks_json_is_relocatable( assert PLUGIN_ROOT_TOKEN in regenerated -def test_content_complete_drift_healing_catches_hash_matching_staleness( +def test_content_complete_drift_healing_replaces_legacy_key_and_stale_commands( tmp_path: Path, monkeypatch: pytest.MonkeyPatch ) -> None: - """T-A2: Drift healing detects stale commands even when the registry hash matches. - - The incident precondition: _autoskillit_registry_hash equals the live - HOOK_REGISTRY_HASH but the command strings are absolute-path pinned. - The previous hash-only gate was blind to this shape. - """ + """T-A2: Drift healing removes a legacy registry key and stale absolute commands.""" import autoskillit.core.paths as _paths from autoskillit.hook_registry import HOOK_REGISTRY_HASH, render_hooks_json_text from autoskillit.server.lifecycle._lifespan import run_startup_drift_check @@ -133,7 +97,7 @@ def test_content_complete_drift_healing_catches_hash_matching_staleness( fake_pkg_root = tmp_path / "pkg" hooks_dir = fake_pkg_root / "hooks" hooks_dir.mkdir(parents=True) - # Plant: correct hash, stale absolute commands + # Plant: legacy key with the live hash, plus stale absolute commands. stale_json = { "_autoskillit_registry_hash": HOOK_REGISTRY_HASH, "hooks": { @@ -161,10 +125,11 @@ def test_content_complete_drift_healing_catches_hash_matching_staleness( run_startup_drift_check() regenerated = (hooks_dir / "hooks.json").read_text() + assert "_autoskillit_registry_hash" not in json.loads(regenerated) expected = render_hooks_json_text() assert regenerated == expected, ( - "content-complete drift check failed to heal a stale file whose " - "registry hash matched but whose commands were absolute" + "content-complete drift check failed to replace a legacy " + "_autoskillit_registry_hash key plus stale absolute commands" ) diff --git a/tests/hooks/test_hook_executability.py b/tests/hooks/test_hook_executability.py index b0806bd713..282fac2ae7 100644 --- a/tests/hooks/test_hook_executability.py +++ b/tests/hooks/test_hook_executability.py @@ -223,14 +223,7 @@ def test_generated_hooks_json_includes_ask_user_question_gate() -> None: assert "AskUserQuestion" in matchers -def test_generated_hooks_json_embeds_registry_hash() -> None: - from autoskillit.hook_registry import HOOK_REGISTRY_HASH, generate_hooks_json - - h = generate_hooks_json() - assert h.get("_autoskillit_registry_hash") == HOOK_REGISTRY_HASH - - -def test_synced_settings_json_embeds_registry_hash(tmp_path: Path, monkeypatch) -> None: +def test_synced_settings_json_adds_only_the_hooks_key(tmp_path: Path, monkeypatch) -> None: import autoskillit.cli._hooks as _hooks_mod import autoskillit.cli._init_helpers as init_helpers @@ -238,9 +231,16 @@ def test_synced_settings_json_embeds_registry_hash(tmp_path: Path, monkeypatch) monkeypatch.setattr(init_helpers, "_is_plugin_installed", lambda **kwargs: False) from autoskillit.cli._hooks import sync_hooks_to_settings - from autoskillit.hook_registry import HOOK_REGISTRY_HASH settings_path = tmp_path / "settings.json" + seed = { + "permissions": {"allow": ["Bash(git status)"]}, + "env": {"PROJECT_MODE": "test"}, + "includeCoAuthoredBy": False, + } + settings_path.write_text(json.dumps(seed)) sync_hooks_to_settings(settings_path) data = json.loads(settings_path.read_text()) - assert data.get("_autoskillit_registry_hash") == HOOK_REGISTRY_HASH + assert set(data) - set(seed) == {"hooks"} + for key, value in seed.items(): + assert data[key] == value diff --git a/tests/server/test_lifespan.py b/tests/server/test_lifespan.py index adc078e818..1f16b73037 100644 --- a/tests/server/test_lifespan.py +++ b/tests/server/test_lifespan.py @@ -390,28 +390,6 @@ def test_startup_install_state_levels_follow_severity(monkeypatch: pytest.Monkey assert not [entry for entry in logs if "remediation" in entry] -def test_serve_startup_regenerates_on_hash_mismatch(tmp_path: Path, monkeypatch) -> None: - """run_startup_drift_check() regenerates hooks.json when hash is mismatched.""" - import json as _json - - import autoskillit.core.paths as _paths - from autoskillit.hook_registry import HOOK_REGISTRY_HASH - from autoskillit.server.lifecycle import _lifespan - - fake_pkg_root = tmp_path / "pkg" - hooks_dir = fake_pkg_root / "hooks" - hooks_dir.mkdir(parents=True) - stale_json = {"_autoskillit_registry_hash": "deadbeef", "hooks": {}} - (hooks_dir / "hooks.json").write_text(_json.dumps(stale_json)) - - monkeypatch.setattr(_paths, "pkg_root", lambda: fake_pkg_root) - - _lifespan.run_startup_drift_check() - - updated = _json.loads((hooks_dir / "hooks.json").read_text()) - assert updated.get("_autoskillit_registry_hash") == HOOK_REGISTRY_HASH - - def test_startup_refuses_when_a_fixed_set_backend_omits_a_join_guard(monkeypatch) -> None: """Startup names the incomplete fixed-set backend and its missing guard.""" import autoskillit.server.lifecycle._lifespan._startup_checks as startup_checks From 86821853beb7a2c6c2f1b207f1984234044d0e4e Mon Sep 17 00:00:00 2001 From: Trecek Date: Sun, 25 Oct 2026 15:05:49 -0700 Subject: [PATCH 02/10] fix(review): share hook document serialization with repair --- src/autoskillit/hook_registry/__init__.py | 2 ++ src/autoskillit/hook_registry/_rendering.py | 17 ++++++++++++++++- .../_projected_artifact/_hook_repair.py | 3 ++- .../test_durable_artifact_relocatability.py | 4 +++- 4 files changed, 23 insertions(+), 3 deletions(-) diff --git a/src/autoskillit/hook_registry/__init__.py b/src/autoskillit/hook_registry/__init__.py index ecd22d75db..b5d36eda97 100644 --- a/src/autoskillit/hook_registry/__init__.py +++ b/src/autoskillit/hook_registry/__init__.py @@ -66,6 +66,7 @@ render_hook_scope_table, render_hooks_json_text, render_relocatable_hook_command, + serialize_hooks_json, ) from ._risky_operations import ( _contract_session_scopes, @@ -133,6 +134,7 @@ "quarantine_hook_payload", "render_hook_scope_table", "render_hooks_json_text", + "serialize_hooks_json", "render_relocatable_hook_command", "validate_lifecycle_contracts", "validate_protection_coverage", diff --git a/src/autoskillit/hook_registry/_rendering.py b/src/autoskillit/hook_registry/_rendering.py index d7f209c029..37f2b7b7f7 100644 --- a/src/autoskillit/hook_registry/_rendering.py +++ b/src/autoskillit/hook_registry/_rendering.py @@ -100,7 +100,22 @@ def render_hooks_json_text( digests them; keeping the serialization in one place prevents the three from drifting apart. """ - return json.dumps(generate_hooks_json(registry, lifecycle_contracts), indent=2) + "\n" + return serialize_hooks_json(generate_hooks_json(registry, lifecycle_contracts)) + + +def serialize_hooks_json(payload: dict) -> str: + """Serialize a hook document without AutoSkillit's retired private key. + + Repair uses the installed incarnation's payload rather than the running + registry, preserving its hooks and consumer-owned document metadata. + """ + return ( + json.dumps( + {key: value for key, value in payload.items() if key != "_autoskillit_registry_hash"}, + indent=2, + ) + + "\n" + ) def render_hook_scope_table( diff --git a/src/autoskillit/workspace/_projected_artifact/_hook_repair.py b/src/autoskillit/workspace/_projected_artifact/_hook_repair.py index f4e06d22f0..7ae29663f9 100644 --- a/src/autoskillit/workspace/_projected_artifact/_hook_repair.py +++ b/src/autoskillit/workspace/_projected_artifact/_hook_repair.py @@ -34,6 +34,7 @@ is_hook_payload_quarantined, quarantine_hook_payload, render_relocatable_hook_command, + serialize_hooks_json, ) from autoskillit.workspace._installed._artifact import ( write_installed_plugin_artifact_manifest_locked, @@ -358,7 +359,7 @@ def _repair_hook_payload_under_lease( try: atomic_write( hooks_json_path, - json.dumps({"hooks": fresh["hooks"]}, indent=2) + "\n", + serialize_hooks_json(fresh), strict_durability=True, ) write_manifest_refresh(manifest_refresh) diff --git a/tests/contracts/test_durable_artifact_relocatability.py b/tests/contracts/test_durable_artifact_relocatability.py index 06405f5979..1034c6094c 100644 --- a/tests/contracts/test_durable_artifact_relocatability.py +++ b/tests/contracts/test_durable_artifact_relocatability.py @@ -385,6 +385,7 @@ def test_plugin_cache_repair_output_is_relocatable(self, tmp_path: Path) -> None json.dumps( { "_autoskillit_registry_hash": "legacy", + "description": "Installed incarnation hooks", "hooks": { "PreToolUse": [ { @@ -414,7 +415,8 @@ def test_plugin_cache_repair_output_is_relocatable(self, tmp_path: Path) -> None assert outcomes[0].status is PluginHookRepairStatus.REPAIRED payload = json.loads((hooks_dir / "hooks.json").read_text()) - assert set(payload) == {"hooks"} + assert set(payload) == {"hooks", "description"} + assert payload["description"] == "Installed incarnation hooks" assert payload["hooks"]["PreToolUse"][0]["hooks"][0]["command"].endswith( " guards/tool_guard" ) From 6247e716b34c93582cd19fbc28f3789b650292bc Mon Sep 17 00:00:00 2001 From: Trecek Date: Sun, 25 Oct 2026 15:07:21 -0700 Subject: [PATCH 03/10] style(review): keep hook contract JSON import at module scope --- tests/contracts/test_claude_code_interface_contracts.py | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/tests/contracts/test_claude_code_interface_contracts.py b/tests/contracts/test_claude_code_interface_contracts.py index d9bccfb94d..9be9dabff1 100644 --- a/tests/contracts/test_claude_code_interface_contracts.py +++ b/tests/contracts/test_claude_code_interface_contracts.py @@ -10,6 +10,7 @@ from __future__ import annotations +import json from pathlib import Path import pytest @@ -451,8 +452,6 @@ class TestClaudeHooksJsonContract: """ def test_rendered_hooks_json_uses_only_claude_accepted_keys(self) -> None: - import json - doc = json.loads(render_hooks_json_text()) assert "hooks" in doc unknown = _unknown_claude_hook_keys(doc) From 46ee02881b4f0deae37770d3ae53c12581f8b11a Mon Sep 17 00:00:00 2001 From: Trecek Date: Sun, 25 Oct 2026 15:08:10 -0700 Subject: [PATCH 04/10] test(review): pin the generated hook document envelope --- tests/contracts/test_claude_code_interface_contracts.py | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/tests/contracts/test_claude_code_interface_contracts.py b/tests/contracts/test_claude_code_interface_contracts.py index 9be9dabff1..f7105be2db 100644 --- a/tests/contracts/test_claude_code_interface_contracts.py +++ b/tests/contracts/test_claude_code_interface_contracts.py @@ -22,7 +22,7 @@ import autoskillit.cli.session._session_reload as _patch_session__session_reload import autoskillit.cli.ui._timed_input as _patch_ui__timed_input import autoskillit.hooks # noqa: F401 -from autoskillit.hook_registry import render_hooks_json_text +from autoskillit.hook_registry import generate_hooks_json, render_hooks_json_text pytestmark = [pytest.mark.layer("contracts"), pytest.mark.medium] @@ -451,6 +451,9 @@ class TestClaudeHooksJsonContract: Recheck the upstream hooks reference and CHANGELOG when revising these key sets. """ + def test_generated_hooks_json_contains_only_hooks(self) -> None: + assert set(generate_hooks_json()) == {"hooks"} + def test_rendered_hooks_json_uses_only_claude_accepted_keys(self) -> None: doc = json.loads(render_hooks_json_text()) assert "hooks" in doc From 80ea08fb6dfef726d68e5e2151a9df41399703e1 Mon Sep 17 00:00:00 2001 From: Trecek Date: Sun, 25 Oct 2026 15:08:47 -0700 Subject: [PATCH 05/10] test(review): document the hook key checker input contract --- tests/contracts/test_claude_code_interface_contracts.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/tests/contracts/test_claude_code_interface_contracts.py b/tests/contracts/test_claude_code_interface_contracts.py index f7105be2db..025d1a9126 100644 --- a/tests/contracts/test_claude_code_interface_contracts.py +++ b/tests/contracts/test_claude_code_interface_contracts.py @@ -430,7 +430,8 @@ def test_mcp_json_autoskillit_has_command_key(self) -> None: ) -def _unknown_claude_hook_keys(doc) -> dict[str, set[str]]: +def _unknown_claude_hook_keys(doc: dict) -> dict[str, set[str]]: + """Report unsupported keys in a document with a required hooks mapping.""" unknown = {} if extra := set(doc) - _CLAUDE_HOOKS_FILE_KEYS: unknown["$"] = extra From b93a05c9e7730c9e53e5a39795124059fd72f42f Mon Sep 17 00:00:00 2001 From: Trecek Date: Sun, 25 Oct 2026 15:09:21 -0700 Subject: [PATCH 06/10] style(review): index the hook document contract section --- tests/contracts/test_claude_code_interface_contracts.py | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/tests/contracts/test_claude_code_interface_contracts.py b/tests/contracts/test_claude_code_interface_contracts.py index 025d1a9126..8ee79d4e99 100644 --- a/tests/contracts/test_claude_code_interface_contracts.py +++ b/tests/contracts/test_claude_code_interface_contracts.py @@ -405,6 +405,11 @@ def test_mcp_json_autoskillit_has_command_key(self) -> None: ) +# --------------------------------------------------------------------------- +# CC-HOOKS: Claude Code hooks.json key contract +# --------------------------------------------------------------------------- + + # Supported keys of a Claude Code plugin hooks/hooks.json. Sources (retrieved 2026-10-25): # https://code.claude.com/docs/en/hooks.md — top level description, hooks; matcher group # matcher, hooks; handler fields type, if, timeout, statusMessage, and command From c282fb218c530ef1755af723f5b420e1accd95c5 Mon Sep 17 00:00:00 2001 From: Trecek Date: Sun, 25 Oct 2026 15:09:55 -0700 Subject: [PATCH 07/10] docs(review): explain hook registry initialization in contracts --- tests/contracts/test_claude_code_interface_contracts.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/tests/contracts/test_claude_code_interface_contracts.py b/tests/contracts/test_claude_code_interface_contracts.py index 8ee79d4e99..76d12b08cb 100644 --- a/tests/contracts/test_claude_code_interface_contracts.py +++ b/tests/contracts/test_claude_code_interface_contracts.py @@ -21,6 +21,8 @@ import autoskillit.cli.session._session_process as _patch_session__session_process import autoskillit.cli.session._session_reload as _patch_session__session_reload import autoskillit.cli.ui._timed_input as _patch_ui__timed_input + +# Populate HOOK_REGISTRY before rendering; hook_registry defers this to avoid an import cycle. import autoskillit.hooks # noqa: F401 from autoskillit.hook_registry import generate_hooks_json, render_hooks_json_text From 1640e9b3e076be55552d14788a27efa308e29d3d Mon Sep 17 00:00:00 2001 From: Trecek Date: Sun, 25 Oct 2026 15:10:40 -0700 Subject: [PATCH 08/10] test(review): cover legacy hook key cleanup through public sync --- tests/hooks/test_hook_executability.py | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/tests/hooks/test_hook_executability.py b/tests/hooks/test_hook_executability.py index 282fac2ae7..c5478a6a21 100644 --- a/tests/hooks/test_hook_executability.py +++ b/tests/hooks/test_hook_executability.py @@ -223,7 +223,10 @@ def test_generated_hooks_json_includes_ask_user_question_gate() -> None: assert "AskUserQuestion" in matchers -def test_synced_settings_json_adds_only_the_hooks_key(tmp_path: Path, monkeypatch) -> None: +@pytest.mark.parametrize("legacy_hash", [None, "legacy"], ids=["clean", "legacy"]) +def test_synced_settings_json_adds_only_the_hooks_key( + tmp_path: Path, monkeypatch, legacy_hash: str | None +) -> None: import autoskillit.cli._hooks as _hooks_mod import autoskillit.cli._init_helpers as init_helpers @@ -238,9 +241,13 @@ def test_synced_settings_json_adds_only_the_hooks_key(tmp_path: Path, monkeypatc "env": {"PROJECT_MODE": "test"}, "includeCoAuthoredBy": False, } - settings_path.write_text(json.dumps(seed)) + initial = dict(seed) + if legacy_hash is not None: + initial["_autoskillit_registry_hash"] = legacy_hash + settings_path.write_text(json.dumps(initial)) sync_hooks_to_settings(settings_path) data = json.loads(settings_path.read_text()) + assert "_autoskillit_registry_hash" not in data assert set(data) - set(seed) == {"hooks"} for key, value in seed.items(): assert data[key] == value From 6f0e9e2d58807ebd6bbc000c3799dbccf65b457c Mon Sep 17 00:00:00 2001 From: Trecek Date: Sun, 25 Oct 2026 15:22:37 -0700 Subject: [PATCH 09/10] fix(review): remove legacy metadata at the shared settings writer --- src/autoskillit/cli/_hooks.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/autoskillit/cli/_hooks.py b/src/autoskillit/cli/_hooks.py index 7806953ef1..ca6055ba20 100644 --- a/src/autoskillit/cli/_hooks.py +++ b/src/autoskillit/cli/_hooks.py @@ -25,6 +25,7 @@ def _write_settings_data(settings_path: Path, data: dict) -> None: """Write settings data back atomically, creating parent dirs if needed.""" + data.pop("_autoskillit_registry_hash", None) settings_path.parent.mkdir(parents=True, exist_ok=True) atomic_write(settings_path, json.dumps(data, indent=2)) @@ -104,7 +105,6 @@ def _evict_stale_autoskillit_hooks(settings_path: Path) -> None: entry["hooks"] = non_autoskillit cleaned.append(entry) hooks[event_type] = cleaned - data.pop("_autoskillit_registry_hash", None) _write_settings_data(settings_path, data) From 6349005ad585466132b5316c85f5a0efc3eaebd6 Mon Sep 17 00:00:00 2001 From: Trecek Date: Sun, 25 Oct 2026 15:23:51 -0700 Subject: [PATCH 10/10] test(review): refresh hook repair source ledgers --- tests/_retention_surface.py | 26 +++++++++---------- tests/infra/test_schema_version_convention.py | 9 ------- 2 files changed, 13 insertions(+), 22 deletions(-) diff --git a/tests/_retention_surface.py b/tests/_retention_surface.py index 47a8d6b96b..8a7c7de8b8 100644 --- a/tests/_retention_surface.py +++ b/tests/_retention_surface.py @@ -1382,50 +1382,50 @@ def assert_second_pass_is_quiet( "A shared lease is currently contended, so the legacy candidate waits for its holder." ), # -- workspace._projected_artifact._hook_repair::repair_broken_plugin_cache_hooks -- - f"{_HC}::L480": _self_limiting( + f"{_HC}::L481": _self_limiting( "The plugin cache root is absent, leaving no hook incarnation to repair." ), # -- workspace._projected_artifact._hook_repair::repair_broken_projection_hooks -- - f"{_HP}::L550": _self_limiting( + f"{_HP}::L551": _self_limiting( "The projections root is absent, leaving no projection hook payload to repair." ), # -- workspace._projected_artifact._hook_repair::_hook_repair_needed -- - f"{_HRP}::L307": _self_limiting( + f"{_HRP}::L308": _self_limiting( "An incarnation without hooks.json has no hook payload this repairer can own." ), - f"{_HRP}::L310": _self_limiting( + f"{_HRP}::L311": _self_limiting( "The content-fingerprinted quarantine marker already records this hooks payload's " "terminal result." ), - f"{_HRP}::L314": _self_limiting( + f"{_HRP}::L315": _self_limiting( "A malformed preflight payload is routed into the held-lease repair path before any " "durable quarantine decision is made." ), # -- workspace._projected_artifact._hook_repair::_repair_hook_incarnation -- - f"{_HR}::L406": _self_limiting( + f"{_HR}::L407": _self_limiting( "The unleased preflight found no relocatable or dispatcher repair work for this payload." ), - f"{_HR}::L408": _self_limiting( + f"{_HR}::L409": _self_limiting( "The lease-held transaction owns the final repaired, quarantined, or quiet outcome." ), - f"{_HR}::L418": _resolves_with_contention( + f"{_HR}::L419": _resolves_with_contention( "An exclusive hook lease is held by another live repairer and will release." ), - f"{_HR}::L424": _retries_after_input_changes( + f"{_HR}::L425": _retries_after_input_changes( "A transient hook read, write, or rollback failure leaves the candidate retryable." ), # -- workspace._projected_artifact._hook_repair::_repair_hook_payload_under_lease -- - f"{_HRL}::L331": _self_limiting( + f"{_HRL}::L332": _self_limiting( "The payload changed to a marked incarnation before the lease, completing its disposition." ), - f"{_HRL}::L336": _self_limiting( + f"{_HRL}::L337": _self_limiting( "A durable quarantine marker and QUARANTINED outcome complete this invalid payload's " "lifecycle." ), - f"{_HRL}::L342": _self_limiting( + f"{_HRL}::L343": _self_limiting( "The hook payload became valid under the lease and no repair remains necessary." ), - f"{_HRL}::L348": _self_limiting( + f"{_HRL}::L349": _self_limiting( "Identity validation writes a durable quarantine marker before reporting the terminal " "outcome." ), diff --git a/tests/infra/test_schema_version_convention.py b/tests/infra/test_schema_version_convention.py index 00c2691d1d..66372e05a0 100644 --- a/tests/infra/test_schema_version_convention.py +++ b/tests/infra/test_schema_version_convention.py @@ -135,15 +135,6 @@ def _legacy_write_problems(expected: Mapping[str, int], observed: Counter[str]) "src/autoskillit/workspace/clone/_registry.py::CloneRegistry.__exit__": 1, # staleness_cache.py — cache dict "src/autoskillit/recipe/contracts/staleness_cache.py::write_staleness_cache": 1, - # _hook_repair.py — hooks.json self-heal for plugin cache and projection scopes, - # triggered by the in-process repair primitive instead of startup drift detection - # (co-owned with Claude plugin system). The shared lease-held hook transaction in - # _repair_hook_payload_under_lease rewrites hooks.json for both cache and projection - # artifacts. Manifest refresh stays versioned separately. - ( - "src/autoskillit/workspace/_projected_artifact/_hook_repair.py::" - "_repair_hook_payload_under_lease" - ): 1, # tools_kitchen/_hook_config.py — hook config, quota guard, and git_ops_policy "src/autoskillit/server/tools/tools_kitchen/_hook_config.py::_write_hook_config": 1, (