agentseam 0.1.0__py3-none-any.whl

agentseam/__init__.py

@@ -0,0 +1,83 @@
+"""agentseam — the primitives layer for every coding agent.
+
+Write one handler; run it on Claude Code, Cursor, VS Code Copilot and friends.
+agentseam owns the per-agent differences: payload shapes, response dialects, config
+file formats, and an explicit capability matrix that says what each agent can
+actually enforce.
+
+    from agentseam import run, Decision
+
+    def handler(event):
+        if event.event == "pre_tool" and event.command == "rm -rf /":
+            return Decision.deny("no")
+        return Decision.allow()
+
+    run(handler)
+"""
+
+__version__ = "0.1.0"
+
+from . import adapters, bundler, instructions, packaging, permissions
+from .contract import (
+    ALLOW,
+    ASK,
+    DENY,
+    EVENTS,
+    FILE_CHANGED,
+    INSTRUCTIONS_LOADED,
+    POST_TOOL,
+    PRE_COMPACT,
+    PRE_TOOL,
+    PROMPT_SUBMIT,
+    REWRITE,
+    SESSION_END,
+    SESSION_START,
+    STOP,
+    SUBAGENT_START,
+    SUBAGENT_STOP,
+    TOOL_FAILURE,
+    UNKNOWN,
+    Decision,
+    Event,
+)
+from .dispatch import degrade, handle, run
+from .matrix import MATRIX, adapted_agents, agents, can_block, can_rewrite, capability, enforcement_level
+
+__all__ = [
+    "run",
+    "handle",
+    "degrade",
+    "Event",
+    "Decision",
+    "EVENTS",
+    "adapters",
+    "bundler",
+    "instructions",
+    "packaging",
+    "permissions",
+    "ALLOW",
+    "DENY",
+    "ASK",
+    "REWRITE",
+    "MATRIX",
+    "agents",
+    "capability",
+    "can_block",
+    "can_rewrite",
+    "enforcement_level",
+    "adapted_agents",
+    "SESSION_START",
+    "SESSION_END",
+    "PROMPT_SUBMIT",
+    "PRE_TOOL",
+    "POST_TOOL",
+    "TOOL_FAILURE",
+    "PRE_COMPACT",
+    "STOP",
+    "SUBAGENT_START",
+    "SUBAGENT_STOP",
+    "INSTRUCTIONS_LOADED",
+    "FILE_CHANGED",
+    "UNKNOWN",
+    "__version__",
+]

agentseam/adapters/__init__.py

@@ -0,0 +1,69 @@
+"""Per-agent adapters: parse a vendor payload -> Event; speak a Decision in vendor dialect.
+
+An adapter is the ONLY place vendor knowledge lives. Adding an agent = adding a module
+here plus a matrix row; no consumer changes.
+"""
+
+from __future__ import annotations
+
+from . import (
+    antigravity,
+    claude_code,
+    codex_cli,
+    cursor,
+    devin,
+    gemini_cli,
+    grok,
+    junie,
+    kimi_code,
+    tabnine,
+    vscode_copilot,
+    windsurf,
+)
+
+ADAPTERS = {
+    antigravity.AGENT: antigravity,
+    claude_code.AGENT: claude_code,
+    codex_cli.AGENT: codex_cli,
+    cursor.AGENT: cursor,
+    devin.AGENT: devin,
+    gemini_cli.AGENT: gemini_cli,
+    grok.AGENT: grok,
+    junie.AGENT: junie,
+    kimi_code.AGENT: kimi_code,
+    tabnine.AGENT: tabnine,
+    vscode_copilot.AGENT: vscode_copilot,
+    windsurf.AGENT: windsurf,
+}
+
+
+def get(agent):
+    try:
+        return ADAPTERS[agent]
+    except KeyError:
+        raise KeyError("no adapter for agent %r (have: %s)" % (agent, ", ".join(sorted(ADAPTERS))))
+
+
+def detect(raw):
+    """Best-effort agent identification from a raw payload.
+
+    Used by the universal dispatcher when the caller did not say which agent it is.
+    Returns an agent name or None; never guesses when two adapters both claim it.
+    """
+    claims = [name for name, mod in sorted(ADAPTERS.items()) if mod.claims(raw)]
+    return claims[0] if len(claims) == 1 else None
+
+
+def shell_tools(agent):
+    """Tool names a shell command arrives under, or () where none is established.
+
+    The one question a caller wiring a shell gate must answer, and the one whose wrong answer
+    is silent: a `matcher` naming a tool the vendor does not use matches nothing, so the hook
+    never fires and the install still reports success.
+
+    () is a claim in the usual sense here -- "not established", not "no shell tool". Guessing
+    is the failure this returns () to prevent: a sibling guardrail hardcodes "Bash" for four
+    vendors, which is right for the two that speak Claude Code's protocol and unverified for
+    the rest.
+    """
+    return tuple(getattr(get(agent), "SHELL_TOOLS", ()))

agentseam/adapters/_windows.py

@@ -0,0 +1,32 @@
+"""PowerShell's one rule that breaks hook commands, shared by the vendors it affects.
+
+Two adapters here need this and for the same reason, so the explanation lives once rather
+than twice: a copy that drifts is how a vendor fact becomes two disagreeing vendor facts.
+"""
+
+from __future__ import annotations
+
+
+def powershell_command(command):
+    """`command` rewritten so PowerShell will actually run it.
+
+    A command line that BEGINS with a quoted path is parsed by PowerShell as a string
+    expression, not an invocation -- and a bare string followed by more arguments is a
+    parse error, so nothing runs at all. `&` is PowerShell's call operator, and it makes a
+    quoted path executable.
+
+    Witnessed live (Codex CLI 0.150.1, Windows, 2026-08-28): the quoted form failed with
+    "hook exited with code 1" on every event, and a `> file 2>&1` redirect appended to it
+    produced NO file -- proof the line never reached execution, since PowerShell sets up
+    redirection only for a command it could parse. Prefixing `&` ran the hook immediately.
+    A bare `python3 "..."` also works, because it parses in command mode; the difference is
+    the leading quote, not the interpreter.
+
+    Both vendors route hooks through PowerShell on Windows. Codex wraps them itself;
+    VS Code Copilot does it in hookExecutor.ts's getShellCommand, which spawns
+    `powershell.exe -ExecutionPolicy Bypass -NoProfile -NoLogo -Command <hookCommand>`
+    whenever ComSpec is cmd.exe -- i.e. by default. Each adapter passes the result through
+    its own per-platform override field, so the POSIX `command` keeps the exact quoted
+    interpreter path that installed the hook.
+    """
+    return command if command.lstrip().startswith("&") else "& " + command

agentseam/adapters/antigravity.py

@@ -0,0 +1,189 @@
+"""Antigravity adapter.
+
+Two things make this one different from every other adapter here.
+
+**The payload does not name its event.** There is no `hookEventName` field, so the event has
+to be inferred from shape. That inference has a genuine ambiguity in it: PreToolUse and
+PostToolUse carry the same `toolCall` and `stepIdx`, separated only by PostToolUse's `error`
+field, which is documented as empty rather than absent on success. So the tie is broken
+*toward* PRE_TOOL, deliberately. Guessing post-tool on a pre-tool payload would skip the gate
+and let the call through; guessing pre-tool on a post-tool payload only produces a decision
+that Antigravity ignores, because PostToolUse output is `{}`. One direction fails open, the
+other fails harmlessly.
+
+`PreInvocation` and `PostInvocation` are left unmapped for the same reason taken to its
+conclusion: their payloads are documented as *identical*, so nothing could tell them apart,
+and neither has a canonical counterpart worth bending one into.
+
+**The decision vocabulary is richer than ours.** PreToolUse accepts `allow`, `deny`, `ask`,
+`force_ask` and `deny_unless_prior_grant`. agentseam's contract has three of those, so the
+last two are reachable only by a handler writing Antigravity's dialect directly -- recorded
+here rather than quietly dropped. `ask` is honoured, but respects a user's "Always Allow";
+`force_ask` is the one that ignores cached permissions, and a handler that means "prompt
+every time" is not getting it through this contract today.
+
+Tool arguments are PascalCase (`CommandLine`, `TargetFile`, `CodeContent`), which is why the
+field extraction below is explicit rather than a generic lookup.
+
+Verified against Antigravity's hooks documentation (2026-08-26).
+"""
+
+from __future__ import annotations
+
+import json as _json
+
+from ..contract import ASK, DENY, POST_TOOL, PRE_TOOL, REWRITE, STOP, UNKNOWN, Event, degraded_from
+
+AGENT = "antigravity"
+
+#: Canonical -> the event key used in hooks.json.
+REVERSE_EVENT_MAP = {PRE_TOOL: "PreToolUse", POST_TOOL: "PostToolUse", STOP: "Stop"}
+
+#: Per-tool argument names. Antigravity's tools take PascalCase args that differ by tool,
+#: so a guardrail asking "which file, what content" needs this table to get an answer.
+_COMMAND_ARG = "CommandLine"
+_PATH_ARGS = ("TargetFile", "AbsolutePath")
+_CONTENT_ARGS = ("CodeContent", "ReplacementContent")
+
+
+def claims(raw):
+    """Structural: `conversationId` with `workspacePaths` is Antigravity's own envelope.
+
+    Cursor's near-equivalents are `conversation_id` and `workspace_roots`, so the two do not
+    collide. No event name is checked because the payload does not carry one.
+    """
+    if not isinstance(raw, dict):
+        return False
+    return "conversationId" in raw and isinstance(raw.get("workspacePaths"), list)
+
+
+def _infer_event(raw):
+    """Name the event from shape. See the module docstring for why ties go to PreToolUse."""
+    if "terminationReason" in raw or "fullyIdle" in raw:
+        return "Stop"
+    if isinstance(raw.get("toolCall"), dict):
+        return "PostToolUse" if "error" in raw else "PreToolUse"
+    # PreInvocation / PostInvocation are indistinguishable from each other and unmapped.
+    return None
+
+
+def _content_of(args):
+    for key in _CONTENT_ARGS:
+        if args.get(key):
+            return args[key]
+    chunks = args.get("ReplacementChunks")
+    if isinstance(chunks, list):
+        joined = "\n".join(str(c.get("ReplacementContent", "")) for c in chunks if isinstance(c, dict))
+        return joined or None
+    return None
+
+
+def parse(raw):
+    name = _infer_event(raw)
+    call = raw.get("toolCall") if isinstance(raw.get("toolCall"), dict) else {}
+    args = call.get("args") if isinstance(call.get("args"), dict) else {}
+    roots = raw.get("workspacePaths") or []
+    path = None
+    for key in _PATH_ARGS:
+        if args.get(key):
+            path = args[key]
+            break
+    return Event(
+        AGENT,
+        # An event this adapter has no mapping for resolves to UNKNOWN, never to the
+        # nearest canonical one: relabelling it invites a guardrail to evaluate the
+        # wrong policy against it.
+        {"PreToolUse": PRE_TOOL, "PostToolUse": POST_TOOL, "Stop": STOP}.get(name, UNKNOWN),
+        tool=call.get("name"),
+        command=args.get(_COMMAND_ARG),
+        path=path,
+        content=_content_of(args),
+        output=raw.get("error") or None,
+        session_id=raw.get("conversationId"),
+        # The docstring's own pre/post correlation key -- PreToolUse and PostToolUse carry
+        # the same stepIdx. Left unplumbed, a handler correlating a gate decision with its
+        # post-tool result (timing, verifying a denied call produced no output, per-call
+        # audit trails) found tool_use_id always None on the one agent that names one.
+        tool_use_id=str(raw["stepIdx"]) if "stepIdx" in raw else None,
+        cwd=args.get("Cwd") or (roots[0] if roots else None),
+        raw=raw,
+    )
+
+
+#: Decision words this vendor accepts. PreToolUse takes the five in the docstring above;
+#: Stop takes continue/stop, where anything but "continue" lets the stop happen.
+DECISION_VOCABULARY = frozenset({"allow", "deny", "ask", "force_ask", "deny_unless_prior_grant", "continue", "stop"})
+
+
+def respond(decision, event):
+    name = _infer_event(event.raw or {})
+
+    if name == "PostToolUse":
+        # Documented as returning an empty object. Nothing here can undo the call.
+        return _json.dumps({}), 0
+
+    if name == "Stop":
+        # "continue" re-enters the execution loop; any other value lets the stop happen.
+        # ASK and REWRITE need the same degradation annotation the gate branch below gives
+        # them -- without it, "continue" with the handler's raw reason reads as though the
+        # handler asked to keep working, when it actually asked for confirmation or a
+        # change Stop cannot express either of.
+        if decision.outcome == ASK:
+            note = (
+                "Antigravity cannot modify a tool call"
+                if degraded_from(decision) == REWRITE
+                else "Antigravity cannot prompt at Stop"
+            )
+            reason = _because(decision.reason, note)
+            return _json.dumps({"decision": "continue", "reason": reason}), 0
+        if decision.outcome == REWRITE:
+            reason = _because(decision.reason, "Antigravity cannot modify a tool call")
+            return _json.dumps({"decision": "continue", "reason": reason}), 0
+        if decision.outcome == DENY:
+            return _json.dumps({"decision": "continue", "reason": decision.reason or "policy requires more work"}), 0
+        return _json.dumps({"decision": "stop"}), 0
+
+    if decision.outcome == REWRITE:
+        # No updatedInput equivalent: permissionOverrides widens permissions, it does not
+        # change arguments. Allowing the unmodified call through would be the wrong read.
+        return _json.dumps(
+            {"decision": "deny", "reason": _because(decision.reason, "Antigravity cannot modify a tool call")}
+        ), 0
+    if decision.outcome == ASK:
+        if degraded_from(decision) == REWRITE:
+            # A rewrite the dispatcher reduced. Prompting would offer the user the
+            # *unmodified* call to approve, which is the thing the handler rejected.
+            return _json.dumps(
+                {"decision": "deny", "reason": _because(decision.reason, "Antigravity cannot modify a tool call")}
+            ), 0
+        # A real ask is honoured, but a user's "Always Allow" still applies. force_ask is
+        # the variant that ignores cached permissions, and our contract cannot request it.
+        return _json.dumps({"decision": "ask", "reason": decision.reason or "confirmation required"}), 0
+    if decision.outcome == DENY:
+        return _json.dumps({"decision": "deny", "reason": decision.reason or "blocked by policy"}), 0
+    return _json.dumps({"decision": "allow"}), 0
+
+
+def _because(reason, note):
+    return "%s (%s)" % (reason, note) if reason else note
+
+
+#: The group name we own in hooks.json. Antigravity keys the file by hook *name*, which
+#: gives ownership a natural home: our entries live under one key nobody else writes.
+GROUP = "agentseam"
+
+
+def hook_config(canonical_events, command, matcher=None):
+    group = {}
+    for ev in canonical_events:
+        name = REVERSE_EVENT_MAP.get(ev)
+        if not name:
+            continue
+        entry = {"hooks": [{"type": "command", "command": command}]}
+        if matcher:
+            entry["matcher"] = matcher
+        group.setdefault(name, []).append(entry)
+    return {GROUP: group}
+
+
+CONFIG_PATH = ".agents/hooks.json"

agentseam/adapters/claude_code.py

@@ -0,0 +1,299 @@
+"""Claude Code adapter.
+
+Payload: {"tool_name", "tool_input", "session_id", "tool_use_id", "hook_event_name", ...}
+Response: {"hookSpecificOutput": {"hookEventName", "permissionDecision", ...}} on stdout;
+exit 2 also blocks. Verified live against Claude Code 2.1.245 (2026-08-25)."""
+
+from __future__ import annotations
+
+from ..contract import (
+    ALLOW,
+    ASK,
+    DENY,
+    FILE_CHANGED,
+    INSTRUCTIONS_LOADED,
+    POST_TOOL,
+    PRE_COMPACT,
+    PRE_TOOL,
+    PROMPT_SUBMIT,
+    REWRITE,
+    SESSION_END,
+    SESSION_START,
+    STOP,
+    SUBAGENT_START,
+    SUBAGENT_STOP,
+    TOOL_FAILURE,
+    UNKNOWN,
+    VOUCH,
+    Event,
+    tool_input_of,
+)
+
+AGENT = "claude_code"
+
+# vendor event name -> canonical
+EVENT_MAP = {
+    "PreToolUse": PRE_TOOL,
+    "PostToolUse": POST_TOOL,
+    "PostToolUseFailure": TOOL_FAILURE,
+    "UserPromptSubmit": PROMPT_SUBMIT,
+    "SessionStart": SESSION_START,
+    "SessionEnd": SESSION_END,
+    "Stop": STOP,
+    "PreCompact": PRE_COMPACT,
+    "SubagentStart": SUBAGENT_START,
+    "SubagentStop": SUBAGENT_STOP,
+    # Both were claimed by the matrix long before they were mapped here, so an install for
+    # them wired nothing at all and said nothing about it. FileChanged fires when a watched
+    # file changes on disk (the matcher names the files); InstructionsLoaded fires when a
+    # CLAUDE.md or .claude/rules/*.md is read into context, at session start and again
+    # whenever one is loaded lazily.
+    "InstructionsLoaded": INSTRUCTIONS_LOADED,
+    "FileChanged": FILE_CHANGED,
+}
+REVERSE_EVENT_MAP = {v: k for k, v in EVENT_MAP.items()}
+
+# Tools whose input carries file content rather than a shell command.
+WRITE_TOOLS = ("Write", "Edit", "MultiEdit", "NotebookEdit")
+
+#: The tool a shell command arrives under, and therefore what a PreToolUse `matcher` must say
+#: to gate shell. A wrong value fails silently: it matches nothing, and the install looks fine.
+SHELL_TOOLS = ("Bash",)
+
+
+#: Fields observed in real Claude Code payloads (live capture, v3.17.8 era, 2026-08-27) that
+#: no other adapter's documented envelope lists. Positive evidence, not inferred absence --
+#: which is the distinction that broke detection here. `prompt_id` was once treated as proof
+#: a payload was NOT Claude Code's; Claude Code now sends it on nearly every event, so that
+#: negative test rejected 38 of 42 real payloads and handed them to Devin instead.
+OBSERVED_MARKERS = (
+    "transcript_path",
+    "permission_mode",
+    "stop_hook_active",
+    "agent_transcript_path",
+    "background_tasks",
+    "session_crons",
+    "custom_instructions",
+    "effort",
+)
+
+
+def looks_like_claude_code(raw):
+    """True when the payload carries a field only Claude Code has been seen to send.
+
+    Imported by the adapters that share this envelope, so the discriminator lives in one
+    place and cannot drift into two disagreeing copies.
+    """
+    return isinstance(raw, dict) and any(marker in raw for marker in OBSERVED_MARKERS)
+
+
+def claims(raw):
+    """True when this payload looks like Claude Code's shape."""
+    if not isinstance(raw, dict):
+        return False
+    if raw.get("hook_event_name") in EVENT_MAP:
+        # Codex reuses tool_input but adds turn identifiers, and Devin reuses the whole
+        # event vocabulary but adds a per-turn prompt_id. Claiming either would make
+        # detect() ambiguous, and an unidentified payload is allowed through.
+        # Kimi Code CLI is Claude Code's envelope exactly -- same PascalCase events, same
+        # snake_case fields -- and names itself only in client_type.
+        if raw.get("client_type") not in (None, "claude_code"):
+            return False
+        # Junie reuses this whole event vocabulary on purpose -- it says so -- and sends
+        # project_path, which Claude Code does not. Without this the two are one payload.
+        # Foreign nameplates: Codex's turn_id, Junie's project_path, Tabnine's timestamp.
+        # None appears in any real Claude Code payload observed live, and each is the only
+        # documented thing separating that vendor's identically-named events from ours.
+        if "turn_id" in raw or "project_path" in raw or "timestamp" in raw:
+            return False
+        # `prompt_id` used to be treated as proof this was Devin's payload, not ours. Claude
+        # Code now sends it too, so the field alone settles nothing: it is only Devin's when
+        # nothing we have actually observed from Claude Code is alongside it.
+        if "prompt_id" in raw and not looks_like_claude_code(raw):
+            return False
+        return True
+    return False
+
+
+def parse(raw):
+    ti = raw.get("tool_input")
+    # A guard that crashes is a guard that allows: dispatch only wraps the JSON decode, so
+    # an exception here kills the hook with exit 1, which most vendors treat as a
+    # non-blocking error and let the call through. tool_input is whatever the agent chose
+    # to serialise, so it is not ours to assume the shape of.
+    ti = tool_input_of(ti)
+    tool = raw.get("tool_name")
+    # new_source is NotebookEdit's cell body -- the tool is in WRITE_TOOLS, so claiming to
+    # handle it while dropping its content is an internal contradiction, not a vendor guess.
+    content = ti.get("content") or ti.get("new_string") or ti.get("new_source") or None
+    if content is None and isinstance(ti.get("edits"), list):
+        joined = "\n".join(str(e.get("new_string", "")) for e in ti["edits"] if isinstance(e, dict))
+        content = joined or None
+    out = raw.get("tool_output")
+    if isinstance(out, (dict, list)):
+        import json as _json
+
+        out = _json.dumps(out)
+    return Event(
+        AGENT,
+        # An event this adapter has no mapping for resolves to UNKNOWN, never to the
+        # nearest canonical one: relabelling it invites a guardrail to evaluate the
+        # wrong policy against it.
+        EVENT_MAP.get(raw.get("hook_event_name"), UNKNOWN),
+        tool=tool,
+        command=ti.get("command"),
+        # InstructionsLoaded and FileChanged carry no tool_input at all -- file_path (and,
+        # for InstructionsLoaded, content) sit at the top level instead, per the project's
+        # own recorded example payloads (examples/generated/claude_code.md).
+        path=ti.get("file_path") or ti.get("path") or ti.get("notebook_path") or raw.get("file_path"),
+        content=content or raw.get("content"),
+        output=out,
+        prompt=raw.get("prompt"),
+        session_id=raw.get("session_id"),
+        tool_use_id=raw.get("tool_use_id"),
+        cwd=raw.get("cwd"),
+        raw=raw,
+    )
+
+
+#: Events that read a TOP-LEVEL {"decision": "block", "reason": ...} and ignore
+#: hookSpecificOutput.permissionDecision entirely. Established live against 2.1.247
+#: (2026-08-28) -- two reads of the vendor page gave contradictory answers. See respond().
+_BLOCK_DIALECT_EVENTS = (PROMPT_SUBMIT, STOP)
+
+
+def _refusal_reason(decision):
+    """One reason string for the events that can only block -- no ask, no rewrite.
+
+    Both degrade to a block with the degradation named rather than being dropped: silence
+    at a blocking event is the dispatcher's allow, which is not what the caller asked for.
+    """
+    reason = decision.reason or "blocked by policy"
+    if decision.outcome == ASK:
+        return reason + " (confirmation requested; this event cannot prompt, so it blocks)"
+    if decision.outcome == REWRITE:
+        return reason + " (input rewrite requested; this event cannot modify input, so it blocks)"
+    return reason
+
+
+#: Decision words this vendor accepts. allow/deny/ask are permissionDecision's, honoured at
+#: pre_tool; "block" is the top-level dialect prompt_submit and stop read. Established live
+#: against 2.1.247 (2026-08-28).
+DECISION_VOCABULARY = frozenset({"allow", "deny", "ask", "block"})
+
+
+#: hookSpecificOutput.additionalContext -- docs-basis, NOT the live-verified 2.1.247
+#: experiment below. code.claude.com/docs/en/hooks documents this as how a hook injects text
+#: into Claude's own context, explicitly nested (top-level is silently ignored), with a
+#: SessionStart example naming it and a UserPromptSubmit section for the same purpose.
+def _additional_context_output(event, context):
+    return {
+        "hookSpecificOutput": {
+            "hookEventName": REVERSE_EVENT_MAP.get(event.event, "PreToolUse"),
+            "additionalContext": context,
+        }
+    }
+
+
+def respond(decision, event):
+    """(stdout_text, exit_code) for this decision -- three dialects, not one.
+
+    Until 2026-08-28 this emitted hookSpecificOutput.permissionDecision at EVERY event.
+    A live experiment against Claude Code 2.1.247 settled what each event actually reads,
+    by wiring one candidate shape per trial and watching the agent rather than the hook:
+
+        event             {"decision": "block"}   hookSpecificOutput   exit 2
+        UserPromptSubmit  honoured                IGNORED              honoured
+        Stop              honoured                IGNORED              honoured
+        PreToolUse        --                      honoured             --
+
+    So every prompt_submit and stop deny this library has ever produced on its most-used
+    adapter was silently discarded: the handler refused, the dispatcher reported a block,
+    and the prompt reached the model anyway. At prompt_submit the trial prompt asked the
+    agent to write a marker file and the file appeared; at stop the agent carried on and
+    the Stop hook re-fired with stop_hook_active set. Both signals are things the agent
+    did, not things the probe claimed.
+
+    exit 2 works at both, and is deliberately NOT used: it collapses to 1 under the
+    PowerShell wrapper some vendors apply, and it leaks the full hook command line into the
+    UI where the JSON form does not. The JSON block also carries the reason into context.
+
+    pre_tool keeps hookSpecificOutput.permissionDecision, and that was verified in the same
+    round rather than assumed: a deny there blocked the Write outright, and the agent's next
+    Bash call too, so the gate fires for every tool. It must keep this shape in any case --
+    it is the only one carrying updatedInput, which rewrite depends on. Everything else is
+    observation-only in this row and gets silence: a verdict there was never read.
+
+    A bare ALLOW is SILENCE, not permissionDecision:"allow".
+
+    "The handler has no objection" and "skip the user's own permission prompt" are different
+    statements, and only the first is what a guardrail means. The vendor's documentation
+    settles what silence does, verbatim: "Exit code 0 with no output means the hook has no
+    decision to report, so the tool call continues through the normal permission flow."
+    What an explicit "allow" does there is NOT documented -- so the recorded option keeps
+    the user's own protection. VS Code's languageModelToolsService, read from source, returns
+    `autoConfirmed: ConfirmationNotNeeded` on exactly this value -- which VOUCH exists to
+    speak on purpose (see below, and allow_semantics.VOUCH_SPEAKS) on the two vendors this is
+    established for. REWRITE still sends an explicit allow, since updatedInput is the only
+    way to express one and approving the *substituted* call is what was asked for.
+    """
+    import json as _json
+
+    if event.event in _BLOCK_DIALECT_EVENTS:
+        # VOUCH has no word here either -- only ever spoken at pre_tool below -- so it is a
+        # louder allow this dialect cannot hear.
+        out = {} if decision.outcome in (ALLOW, VOUCH) else {"decision": "block", "reason": _refusal_reason(decision)}
+        # additionalContext is a second, independent key; only UserPromptSubmit of this pair
+        # is documented to take it.
+        if event.event == PROMPT_SUBMIT and decision.context:
+            out.update(_additional_context_output(event, decision.context))
+        return (_json.dumps(out), 0) if out else ("", 0)
+
+    if event.event == SESSION_START:
+        # Silent regardless of outcome (no block/rewrite claimed here) except for context.
+        if decision.context:
+            return _json.dumps(_additional_context_output(event, decision.context)), 0
+        return "", 0
+
+    if event.event != PRE_TOOL:
+        return "", 0
+
+    if decision.outcome == ALLOW:
+        return "", 0
+
+    out = {"hookEventName": REVERSE_EVENT_MAP.get(event.event, "PreToolUse")}
+    if decision.outcome == VOUCH:
+        # Reaches here undegraded only because allow_semantics.VOUCH_SPEAKS names
+        # claude_code (see dispatch.degrade()) -- the word a bare ALLOW withholds above.
+        out["permissionDecision"] = "allow"
+        if decision.reason:
+            out["permissionDecisionReason"] = decision.reason
+    elif decision.outcome == DENY:
+        out["permissionDecision"] = "deny"
+        out["permissionDecisionReason"] = decision.reason or "blocked"
+    elif decision.outcome == ASK:
+        out["permissionDecision"] = "ask"
+        out["permissionDecisionReason"] = decision.reason or "confirmation required"
+    elif decision.outcome == REWRITE:
+        out["permissionDecision"] = "allow"
+        out["updatedInput"] = decision.updated_input
+        if decision.reason:
+            out["permissionDecisionReason"] = decision.reason
+    return _json.dumps({"hookSpecificOutput": out}), 0
+
+
+def hook_config(canonical_events, command, matcher=None):
+    """A settings.json `hooks` fragment wiring `command` for these canonical events."""
+    hooks = {}
+    for ev in canonical_events:
+        name = REVERSE_EVENT_MAP.get(ev)
+        if not name:
+            continue
+        entry = {"hooks": [{"type": "command", "command": command}]}
+        if matcher:
+            entry["matcher"] = matcher
+        hooks.setdefault(name, []).append(entry)
+    return {"hooks": hooks}
+
+
+CONFIG_PATH = ".claude/settings.json"