controlzero 1.8.1__tar.gz → 1.8.2__tar.gz

{controlzero-1.8.1 → controlzero-1.8.2}/CHANGELOG.md

@@ -1,5 +1,61 @@
 # Changelog
 
+## 1.8.2 -- 2026-06-15 (Kiro IDE hook contract hotfix, epic gh#877)
+
+### Fixed
+
+The shipped Kiro IDE `.kiro.hook` templates used several **Kiro CLI** schema
+conventions instead of the **Kiro IDE** ones (the two hook systems have
+different event names and field keys). The most visible symptom was a
+customer-reported P0; auditing the templates against Kiro's IDE schema
+surfaced three more latent defects. All four are fixed, and a new regression
+test (`tests/test_kiro_hook_templates.py`) pins each so they cannot ship again.
+
+- **(P0) Prompt-submit hook rejected by the IDE.** `ide-prompt-submit.kiro.hook`
+  declared `"when": {"type": "userPromptSubmit"}`. `userPromptSubmit` is the
+  Kiro **CLI** event name; the IDE event is **`promptSubmit`**. The invalid
+  value made the IDE reject the entire hook file ("Hook file has invalid data
+  structure"), so the only active data-carrying IDE hook (prompt-submit, while
+  preToolUse ships disabled) never loaded and the IDE integration silently did
+  nothing. Now `promptSubmit`, with the matching `cz-kiro-adapter promptSubmit`
+  command. (The shim already accepts both spellings, so no behavior change.)
+
+- **Pre-tool-use tool filter used the wrong key.** `ide-pre-tool-use.kiro.hook`
+  filtered tools with `"patterns": ["*"]`; the Kiro IDE tool filter key for
+  `preToolUse`/`postToolUse` is **`toolTypes`** (array). Now `"toolTypes":
+  ["*"]`, so the hook is schema-correct if/when it is enabled (it still ships
+  `enabled: false` pending the upstream empty-payload bug).
+
+- **File-save hook passed a tool-event arg + could block saves.**
+  `ide-file-save.kiro.hook` ran `cz-kiro-adapter postToolUse`, but a
+  `fileEdited` runCommand does not deliver tool context; the adapter would then
+  fail closed (block) on the empty payload -- i.e. it could block file saves.
+  The command is now `cz-kiro-adapter fileEdited`, and the shim treats file
+  events as a post-write **observation**: it synthesizes a `fileSave` tool
+  call from whatever `USER_PROMPT` carries, still runs `hook-check` for the
+  audit row + secret scan, but **always exits 0** on a file event -- a deny is
+  surfaced on stderr as a warning rather than blocking. The file is already
+  written, so blocking is pointless; only tool events (preToolUse) gate.
+  `when.type` stays the valid `fileEdited` with `patterns`.
+
+- **Timeouts were ~83 minutes, not 5 seconds.** All three templates used
+  `"timeout": 5000`. Kiro IDE `then.timeout` is in **seconds** (default 60,
+  `0` disables), so `5000` meant ~83 minutes. Now `5` (seconds) on all three.
+
+The regression test parses every shipped `*.kiro.hook` and asserts: valid
+JSON; `when.type` in Kiro's 11-value IDE event set; tool events use
+`toolTypes` (not `patterns`) and file events use `patterns` (not `toolTypes`);
+`then.timeout` is a small integer (seconds); and the `runCommand` event
+argument is one the `cz-kiro-adapter` shim recognizes.
+
+### Known upstream Kiro limits (not fixed here -- tracked upstream)
+
+- IDE `preToolUse` delivers `USER_PROMPT={}` (no tool context): kirodotdev/Kiro
+  #7375 / #7408 / #7500. Our pre-tool-use IDE hook stays disabled.
+- IDE `postToolUse` delivers `toolArgs: {}` (kirodotdev/Kiro #6188), so
+  argument-level post-tool policy is bounded on the IDE surface regardless of
+  schema correctness.
+
 ## 1.8.0 -- 2026-06-15 (Kiro, epic gh#877)
 
 ### Added

{controlzero-1.8.1 → controlzero-1.8.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: controlzero
-Version: 1.8.1
+Version: 1.8.2
 Summary: AI agent governance: policies, audit, and observability for tool calls. Works locally with no signup.
 Project-URL: Homepage, https://controlzero.ai
 Project-URL: Documentation, https://docs.controlzero.ai

{controlzero-1.8.1 → controlzero-1.8.2}/controlzero/__init__.py

@@ -40,7 +40,7 @@ from controlzero.hitl.grant_protocol import (
 )
 from controlzero.policy_loader import load_policy
 
-__version__ = "1.8.1"
+__version__ = "1.8.2"
 
 __all__ = [
     "Client",

{controlzero-1.8.1 → controlzero-1.8.2}/controlzero/cli/kiro_adapter.py

@@ -7,8 +7,9 @@ on stdin like the Kiro CLI. This shim normalises that into the snake_case JSON
 shape ``controlzero hook-check`` consumes, marks the surface
 (``CZ_KIRO_SURFACE=ide`` so KiroIDEAdapter claims it), and pipes it through.
 
-Wire it as the IDE's preToolUse / postToolUse / userPromptSubmit hook command,
-e.g.::
+Wire it as the IDE's preToolUse / promptSubmit / fileEdited hook command (the
+IDE `when.type` event names -- note prompt-submit is ``promptSubmit`` on the
+IDE surface, NOT the Kiro CLI's ``userPromptSubmit``), e.g.::
 
     cz-kiro-adapter preToolUse
 
@@ -37,6 +38,12 @@ import subprocess
 import sys
 
 
+# Kiro IDE file events. These are a post-write OBSERVATION surface (scan the
+# saved file / audit it), never a gate, so the adapter must not fail closed on
+# them -- a file save can't be blocked by missing context.
+_FILE_EVENTS = frozenset({"fileEdited", "fileCreated", "fileDeleted"})
+
+
 def _event_from_argv(argv: list[str]) -> str:
     # First non-flag arg is the event name; default to preToolUse.
     for a in argv[1:]:
@@ -66,6 +73,25 @@ def _normalize(event: str, raw: str) -> dict | None:
         base["tool_input"] = {"prompt": raw}
         return base
 
+    if event in _FILE_EVENTS:
+        # File events are a POST-WRITE observation, not a gate: a save must
+        # never be blocked by missing context, so this branch NEVER returns
+        # None (no fail-closed). Kiro IDE does not document a guaranteed
+        # structured payload for a file-event runCommand (USER_PROMPT may be a
+        # path, a JSON object, or empty), so we synthesize a write-class tool
+        # call from whatever arrived and let hook-check scan/audit it.
+        base["tool_name"] = "fileSave"
+        payload: dict = {}
+        text = (raw or "").strip()
+        if text:
+            try:
+                parsed = json.loads(text)
+                payload = parsed if isinstance(parsed, dict) else {"raw": text}
+            except json.JSONDecodeError:
+                payload = {"file_path": text}  # most likely a bare path
+        base["tool_input"] = payload
+        return base
+
     raw = (raw or "").strip()
     if not raw:
         return None
@@ -122,6 +148,20 @@ def main(argv: list[str] | None = None) -> int:
         # controlzero not on PATH: never brick the IDE.
         print("controlzero(kiro): controlzero CLI not found; allowing", file=sys.stderr)
         return 0
+
+    if event in _FILE_EVENTS:
+        # OBSERVE-ONLY: a file event is post-write -- the file is already
+        # saved, so blocking is pointless and only disrupts the editor. We
+        # still run hook-check above for the audit row + secret scan, but a
+        # deny is surfaced as a warning and the save is allowed (exit 0).
+        if proc.returncode == 2:
+            print(
+                "controlzero(kiro): file-save policy flagged this write "
+                "(post-write, observe-only; not blocking the save)",
+                file=sys.stderr,
+            )
+        return 0
+
     return proc.returncode
 
 

{controlzero-1.8.1 → controlzero-1.8.2}/controlzero/cli/main.py

@@ -2699,8 +2699,8 @@ def uninstall_codex_cli(config: Optional[str]):
 # is the block point; Prompt Submit scans the prompt; File Save scans writes.
 _KIRO_IDE_HOOKS = (
     ("preToolUse", "controlzero-pre-tool-use", "ide-pre-tool-use.kiro.hook"),
-    ("userPromptSubmit", "controlzero-prompt-submit", "ide-prompt-submit.kiro.hook"),
-    ("fileSave", "controlzero-file-save", "ide-file-save.kiro.hook"),
+    ("promptSubmit", "controlzero-prompt-submit", "ide-prompt-submit.kiro.hook"),
+    ("fileEdited", "controlzero-file-save", "ide-file-save.kiro.hook"),
 )
 
 # Kiro CLI hook events: command is `controlzero hook-check` directly. Pre/post

{controlzero-1.8.1 → controlzero-1.8.2}/controlzero/cli/templates/kiro/ide-file-save.kiro.hook

@@ -9,7 +9,7 @@
   },
   "then": {
     "type": "runCommand",
-    "command": "cz-kiro-adapter postToolUse",
-    "timeout": 5000
+    "command": "cz-kiro-adapter fileEdited",
+    "timeout": 5
   }
 }

{controlzero-1.8.1 → controlzero-1.8.2}/controlzero/cli/templates/kiro/ide-pre-tool-use.kiro.hook

@@ -5,11 +5,11 @@
   "version": "1",
   "when": {
     "type": "preToolUse",
-    "patterns": ["*"]
+    "toolTypes": ["*"]
   },
   "then": {
     "type": "runCommand",
     "command": "cz-kiro-adapter preToolUse",
-    "timeout": 5000
+    "timeout": 5
   }
 }

{controlzero-1.8.1 → controlzero-1.8.2}/controlzero/cli/templates/kiro/ide-prompt-submit.kiro.hook

@@ -4,11 +4,11 @@
   "description": "Control Zero governance: scan each user prompt submitted to Kiro against your policy. Carries data even where the Pre Tool Use payload is bounded by the upstream empty-payload bug.",
   "version": "1",
   "when": {
-    "type": "userPromptSubmit"
+    "type": "promptSubmit"
   },
   "then": {
     "type": "runCommand",
-    "command": "cz-kiro-adapter userPromptSubmit",
-    "timeout": 5000
+    "command": "cz-kiro-adapter promptSubmit",
+    "timeout": 5
   }
 }

{controlzero-1.8.1 → controlzero-1.8.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "controlzero"
-version = "1.8.1"
+version = "1.8.2"
 description = "AI agent governance: policies, audit, and observability for tool calls. Works locally with no signup."
 readme = "README.md"
 license = {text = "Apache-2.0"}

controlzero-1.8.2/tests/test_kiro_hook_templates.py

@@ -0,0 +1,324 @@
+"""Regression guard for the shipped Kiro IDE hook templates (epic gh#877).
+
+Customer P0 (1.8.0): `ide-prompt-submit.kiro.hook` shipped
+`"when": {"type": "userPromptSubmit"}`. `userPromptSubmit` is NOT a valid
+Kiro IDE hook event -- it is the Kiro *CLI* `hook_event_name` and was copied
+across by mistake. Kiro's IDE hook validator rejects the entire hook file with
+"Hook file has invalid data structure: Hook when.type must be one of: ...",
+so the prompt-submit hook (the only active data-carrying IDE hook while
+preToolUse ships disabled) never loaded and the IDE integration was broken.
+
+Schema research (kiro.dev first-party + kirodotdev/Kiro issues #6188/#7375/
+#7408/#7500) surfaced THREE more latent IDE-schema defects beyond the
+prompt-submit event name, all fixed in 1.8.2 and pinned here:
+
+  A. when.type must be one of the 11 valid Kiro IDE events (the customer bug).
+  B. tool events (preToolUse/postToolUse) filter on `toolTypes` (array), NOT
+     `patterns`. We had `patterns: ["*"]` on the pre-tool-use hook.
+  C. file events (fileEdited/fileCreated/fileDeleted) filter on `patterns`
+     (array of globs).
+  D. `then.timeout` is SECONDS (default 60, 0 = disabled), so the `5000` we
+     shipped meant ~83 minutes, not 5 seconds.
+
+Plus the `then.command` (`cz-kiro-adapter <event>`) must name an event the
+shim recognizes.
+
+If Kiro adds or renames IDE events/fields upstream, update the constants here
+in lockstep -- that is intentional: this file is the single pin for the IDE
+hook contract.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+
+from controlzero.cli import kiro_adapter
+
+# Kiro IDE hook `when.type` allowed set, verbatim from the IDE validator error:
+#   "Hook when.type must be one of: fileEdited, fileCreated, fileDeleted,
+#    userTriggered, promptSubmit, agentStop, preToolUse, postToolUse,
+#    preTaskExecution, postTaskExecution, sessionStart."
+KIRO_IDE_EVENTS = frozenset(
+    {
+        "fileEdited",
+        "fileCreated",
+        "fileDeleted",
+        "userTriggered",
+        "promptSubmit",
+        "agentStop",
+        "preToolUse",
+        "postToolUse",
+        "preTaskExecution",
+        "postTaskExecution",
+        "sessionStart",
+    }
+)
+
+# Tool events filter on `toolTypes`; file events filter on `patterns`. (Kiro
+# first-party docs + real committed .kiro.hook files + issues #7408/#7500.)
+TOOL_EVENTS = frozenset({"preToolUse", "postToolUse"})
+FILE_EVENTS = frozenset({"fileEdited", "fileCreated", "fileDeleted"})
+
+# then.timeout is in SECONDS (default 60, 0 = disabled). A sane upper bound for
+# a synchronous governance hook; the catastrophic value we shipped was 5000
+# (~83 min). 120s is generous headroom and still rejects the ms-as-seconds bug.
+MAX_TIMEOUT_SECONDS = 120
+
+# Events the `cz-kiro-adapter` shim handles end to end. promptSubmit ->
+# raw-prompt branch; file events -> observe-only synthetic fileSave; pre/post
+# tool -> JSON tool-payload branch. userPromptSubmit is kept ONLY as a
+# back-compat alias for the Kiro CLI event name and must never be an IDE
+# when.type or an IDE command arg.
+ADAPTER_RECOGNIZED_EVENTS = frozenset(
+    {"preToolUse", "postToolUse", "promptSubmit", "userPromptSubmit"}
+    | set(FILE_EVENTS)
+)
+
+
+def _templates_dir() -> Path:
+    return Path(kiro_adapter.__file__).resolve().parent / "templates" / "kiro"
+
+
+def _shipped_hook_files() -> list[Path]:
+    files = sorted(_templates_dir().glob("*.kiro.hook"))
+    assert files, "expected at least one shipped *.kiro.hook template"
+    return files
+
+
+_HOOK_FILES = _shipped_hook_files()
+_HOOK_IDS = [p.name for p in _HOOK_FILES]
+
+
+def _load(hook_path: Path) -> dict:
+    return json.loads(hook_path.read_text(encoding="utf-8"))
+
+
+def _adapter_event_arg(command: str) -> str:
+    """Extract the event argument from a `cz-kiro-adapter <event> [flags]`
+    runCommand string, mirroring kiro_adapter._event_from_argv (first
+    non-flag token after the program name)."""
+    tokens = command.split()
+    assert tokens, f"empty runCommand: {command!r}"
+    assert tokens[0] == "cz-kiro-adapter", (
+        f"IDE hook command must invoke the cz-kiro-adapter shim, got {command!r}"
+    )
+    for tok in tokens[1:]:
+        if not tok.startswith("-"):
+            return tok
+    raise AssertionError(f"no event argument in runCommand: {command!r}")
+
+
+@pytest.mark.parametrize("hook_path", _HOOK_FILES, ids=_HOOK_IDS)
+def test_hook_template_is_valid_json(hook_path: Path):
+    """Every shipped .kiro.hook must be a parseable JSON object."""
+    try:
+        data = _load(hook_path)
+    except json.JSONDecodeError as e:  # pragma: no cover - failure path
+        pytest.fail(f"{hook_path.name} is not valid JSON: {e}")
+    assert isinstance(data, dict), f"{hook_path.name} must be a JSON object"
+
+
+@pytest.mark.parametrize("hook_path", _HOOK_FILES, ids=_HOOK_IDS)
+def test_hook_when_type_is_a_valid_kiro_ide_event(hook_path: Path):
+    """FIX A / customer P0: `when.type` MUST be in Kiro's allowed IDE event
+    set, or the IDE rejects the whole hook file as invalid."""
+    data = _load(hook_path)
+    when = data.get("when")
+    assert isinstance(when, dict), f"{hook_path.name} missing object `when`"
+    when_type = when.get("type")
+    assert when_type in KIRO_IDE_EVENTS, (
+        f"{hook_path.name}: when.type={when_type!r} is NOT a valid Kiro IDE "
+        f"event. Kiro rejects the hook file. Allowed: {sorted(KIRO_IDE_EVENTS)}"
+    )
+
+
+@pytest.mark.parametrize("hook_path", _HOOK_FILES, ids=_HOOK_IDS)
+def test_tool_events_use_toolTypes_not_patterns(hook_path: Path):
+    """FIX B: preToolUse/postToolUse filter on `toolTypes` (array), never
+    `patterns`. `patterns` on a tool event is a silent schema error."""
+    data = _load(hook_path)
+    when = data["when"]
+    if when.get("type") not in TOOL_EVENTS:
+        pytest.skip("not a tool event")
+    assert "patterns" not in when, (
+        f"{hook_path.name}: tool event {when['type']!r} must NOT use "
+        f"`patterns` -- the tool filter key is `toolTypes`"
+    )
+    tool_types = when.get("toolTypes")
+    assert isinstance(tool_types, list) and tool_types, (
+        f"{hook_path.name}: tool event {when['type']!r} must declare a "
+        f"non-empty `toolTypes` array, got {tool_types!r}"
+    )
+
+
+@pytest.mark.parametrize("hook_path", _HOOK_FILES, ids=_HOOK_IDS)
+def test_file_events_use_patterns_not_toolTypes(hook_path: Path):
+    """FIX C: file events filter on `patterns` (array of globs), not
+    `toolTypes`."""
+    data = _load(hook_path)
+    when = data["when"]
+    if when.get("type") not in FILE_EVENTS:
+        pytest.skip("not a file event")
+    assert "toolTypes" not in when, (
+        f"{hook_path.name}: file event {when['type']!r} must NOT use "
+        f"`toolTypes` -- the file filter key is `patterns`"
+    )
+    patterns = when.get("patterns")
+    assert isinstance(patterns, list) and patterns, (
+        f"{hook_path.name}: file event {when['type']!r} must declare a "
+        f"non-empty `patterns` array, got {patterns!r}"
+    )
+
+
+@pytest.mark.parametrize("hook_path", _HOOK_FILES, ids=_HOOK_IDS)
+def test_timeout_is_small_integer_seconds(hook_path: Path):
+    """FIX D: `then.timeout` is SECONDS (default 60, 0 = disabled). The 1.8.0
+    templates shipped 5000 (~83 minutes). Pin it to a small integer."""
+    then = _load(hook_path)["then"]
+    timeout = then.get("timeout")
+    assert isinstance(timeout, int) and not isinstance(timeout, bool), (
+        f"{hook_path.name}: then.timeout must be an integer (seconds), "
+        f"got {timeout!r}"
+    )
+    assert 0 <= timeout <= MAX_TIMEOUT_SECONDS, (
+        f"{hook_path.name}: then.timeout={timeout} is out of range for a "
+        f"seconds value (0..{MAX_TIMEOUT_SECONDS}). 5000 was the ms-as-seconds "
+        f"bug (~83 min)."
+    )
+
+
+@pytest.mark.parametrize("hook_path", _HOOK_FILES, ids=_HOOK_IDS)
+def test_hook_runcommand_event_arg_is_recognized(hook_path: Path):
+    """The `cz-kiro-adapter <event>` argument must be an event the shim
+    recognizes AND a valid Kiro event (so the IDE actually fires it)."""
+    then = _load(hook_path)["then"]
+    assert then.get("type") == "runCommand", (
+        f"{hook_path.name}: then.type must be 'runCommand', got {then.get('type')!r}"
+    )
+    command = then.get("command")
+    assert isinstance(command, str) and command, (
+        f"{hook_path.name}: then.command must be a non-empty string"
+    )
+    event_arg = _adapter_event_arg(command)
+    assert event_arg in ADAPTER_RECOGNIZED_EVENTS, (
+        f"{hook_path.name}: cz-kiro-adapter event {event_arg!r} is not "
+        f"recognized by the shim. Recognized: {sorted(ADAPTER_RECOGNIZED_EVENTS)}"
+    )
+    # The command arg is the event the IDE fires the hook for, so it must also
+    # be a valid Kiro IDE event (rules out the CLI-only userPromptSubmit alias
+    # leaking into an IDE template's command).
+    assert event_arg in KIRO_IDE_EVENTS, (
+        f"{hook_path.name}: cz-kiro-adapter event {event_arg!r} is not a valid "
+        f"Kiro IDE event. Allowed: {sorted(KIRO_IDE_EVENTS)}"
+    )
+
+
+# --- per-hook end-to-end behavior pins -------------------------------------
+
+def test_prompt_submit_hook_uses_promptSubmit_not_userPromptSubmit():
+    """Pin the EXACT customer bug: the prompt-submit template must declare the
+    IDE `promptSubmit` event, never the CLI's `userPromptSubmit`, and the shim
+    must normalize it into a prompt payload (end-to-end, not just the string)."""
+    data = _load(_templates_dir() / "ide-prompt-submit.kiro.hook")
+    assert data["when"]["type"] == "promptSubmit", (
+        "ide-prompt-submit.kiro.hook when.type must be 'promptSubmit' "
+        "(was the invalid 'userPromptSubmit' in 1.8.0 -> 1.8.1)"
+    )
+    assert _adapter_event_arg(data["then"]["command"]) == "promptSubmit"
+    normalized = kiro_adapter._normalize("promptSubmit", "scan this prompt text")
+    assert normalized is not None
+    assert normalized["tool_name"] == "prompt"
+    assert normalized["tool_input"]["prompt"] == "scan this prompt text"
+    assert normalized["hook_event_name"] == "promptSubmit"
+
+
+def test_file_save_hook_observes_and_never_fails_closed():
+    """file-save uses the valid `fileEdited` trigger + `patterns`, runs the
+    adapter as `fileEdited`, and the shim treats it as observe-only: it must
+    NEVER return None (which would fail-closed and block the save), even when
+    the IDE delivers no structured payload."""
+    data = _load(_templates_dir() / "ide-file-save.kiro.hook")
+    assert data["when"]["type"] == "fileEdited"
+    assert _adapter_event_arg(data["then"]["command"]) == "fileEdited"
+
+    # Empty payload (the realistic file-event case) -> still a usable tool call,
+    # never None -> the shim allows + audits rather than blocking the save.
+    for raw in ("", "   ", "{}"):
+        normalized = kiro_adapter._normalize("fileEdited", raw)
+        assert normalized is not None, (
+            f"file event with payload {raw!r} must not fail-closed"
+        )
+        assert normalized["tool_name"] == "fileSave"
+
+    # A bare file path -> captured under file_path.
+    n_path = kiro_adapter._normalize("fileEdited", "/etc/secrets.env")
+    assert n_path["tool_input"]["file_path"] == "/etc/secrets.env"
+
+    # A JSON object payload (filePath/content if Kiro ever provides it) is kept.
+    n_json = kiro_adapter._normalize(
+        "fileEdited", json.dumps({"filePath": "a.py", "content": "x=1"})
+    )
+    assert n_json["tool_input"]["filePath"] == "a.py"
+
+
+def test_file_save_runCommand_never_blocks_the_editor(monkeypatch):
+    """End-to-end (observe-only): a fileEdited hook must exit 0 (allow) even
+    when (a) USER_PROMPT is empty AND (b) hook-check itself returns a DENY
+    (exit 2). A file save is post-write -- blocking it is pointless and must
+    never happen. We still run hook-check (for the audit row + secret scan)
+    but never propagate its exit code on a file event."""
+
+    class _DenyProc:
+        # hook-check returns 2 (deny) -- the adapter MUST still allow the save.
+        returncode = 2
+
+    captured = {}
+
+    def _fake_run(cmd, input, text, env):  # noqa: A002
+        captured["payload"] = json.loads(input)
+        return _DenyProc()
+
+    monkeypatch.setattr(kiro_adapter.subprocess, "run", _fake_run)
+    monkeypatch.delenv("CZ_KIRO_UNKNOWN_PAYLOAD", raising=False)
+    monkeypatch.setenv("USER_PROMPT", "")
+    rc = kiro_adapter.main(["cz-kiro-adapter", "fileEdited"])
+    assert rc == 0, (
+        "file save must never be blocked -- not by missing context AND not "
+        "even by a hook-check deny (post-write, observe-only)"
+    )
+    # The audit/scan call still ran with the synthesized fileSave payload.
+    assert captured["payload"]["tool_name"] == "fileSave"
+    assert captured["payload"]["hook_event_name"] == "fileEdited"
+
+
+def test_tool_event_still_propagates_block(monkeypatch):
+    """Contrast guard: a real TOOL event (preToolUse) MUST still propagate a
+    hook-check deny (exit 2). The observe-only relaxation is file-events-only;
+    it must not have weakened tool-call gating."""
+
+    class _DenyProc:
+        returncode = 2
+
+    monkeypatch.setattr(
+        kiro_adapter.subprocess, "run", lambda *a, **k: _DenyProc()
+    )
+    monkeypatch.setenv(
+        "USER_PROMPT", json.dumps({"toolName": "execute_bash", "toolArgs": {}})
+    )
+    rc = kiro_adapter.main(["cz-kiro-adapter", "preToolUse"])
+    assert rc == 2, "tool-event deny must still block (only file events are observe-only)"
+
+
+def test_pre_tool_use_ships_disabled_with_toolTypes():
+    """The IDE preToolUse hook ships disabled (upstream empty-payload bug) and,
+    when someone does enable it, must already be schema-correct: toolTypes not
+    patterns, timeout in seconds."""
+    data = _load(_templates_dir() / "ide-pre-tool-use.kiro.hook")
+    assert data["enabled"] is False
+    assert data["when"]["type"] == "preToolUse"
+    assert data["when"]["toolTypes"] == ["*"]
+    assert "patterns" not in data["when"]
+    assert data["then"]["timeout"] == 5