skarn guardhook events

How the guard decides

The host pipes a pending action to skarn guard on stdin - a tool call, a submitted prompt, a spawning subagent, a resolved batch of tool outputs - and the guard scans that single action with the full detection engine before it proceeds. It returns one of three verdicts: deny (block the action), ask (escalate to the user's permission prompt), or allow (silent - nothing is emitted at all). Skarn only ever speaks up to tighten, never to auto-approve.

Where a host offers no ask channel, a would-be ask degrades to a block rather than to an allow. Every reason names the matched rule and a redacted preview - never the raw secret. In audit mode (the default, and the only mode an unlicensed guard runs) the guard never decides: it reports the would-be verdict on a non-deciding channel and writes it to the guard log, so you can measure your real would-block rate before enforcing.

This page is generated from the same model that generates the binary's own manual page, and a build gate asserts it against the guard's source and the shipped hook configs - so it describes what the shipped binary does, not what it once did. The equivalent offline reference is man skarn-guard.

Claude Code

Claude Code fires PascalCase events with a JSON envelope on stdin. Five events are wired by default; the two output-scanning events are supported but opt-in because they fire on every tool result.

Routing. Codex shares Claude's PreToolUse and PermissionRequest names, so auto-detection keys on a Codex-only tell (turn_id, or the apply_patch/spawn_agent tools); a Claude event carries none of them and routes to the Claude adapter. VS Code Copilot also shares the envelope, so its own tool-name vocabulary routes it to the Copilot adapter. The shipped Claude PermissionRequest hooks pass --agent claude explicitly anyway.

Fail mode. A non-zero guard exit fails closed on the blocking events. An unparseable event asks in enforce mode.

"Shipped" means the hook configs in the Skarn repository wire the event by default. An opt-in event is fully supported by the binary - add a block for it to your own config to enable it.

PreToolUse

A deny blocks the call even under bypassPermissions: hooks run before permission-mode checks.

PermissionRequest

A second chokepoint for a call PreToolUse deferred or allowed. The decision has only allow/deny and no reason field, so a would-be ask degrades to deny and additionalContext is invalid here.

UserPromptSubmit

The channel ships content off the machine, so a secret on it is exfiltration. A lone secret is enough to deny here - the destination is not ambiguous. The block is recoverable: the user edits and resubmits.

UserPromptExpansion

The channel ships content off the machine, so a secret on it is exfiltration. The post-expansion text of a slash or custom command - content UserPromptSubmit never sees - gated before it reaches the model.

TaskCreated

The channel ships content off the machine, so a secret on it is exfiltration. A task is subagent fan-out, so it is modeled as the canonical spawn_agent tool. The event has no decision channel and does not support additionalContext.

PostToolUse

Output scanning: catches a secret in a tool RESULT before the model sees it. Opt-in - it fires on every tool result. Prefer PostToolBatch, which sees the same content once per batch.

PostToolBatch

The batch analog of PostToolUse: one invocation per resolved parallel batch, so the cheaper of the two output gates. Opt-in. The batch is scanned as one synthetic interaction named after its first in-scope call.

Stop

The stop advisory. Claude fires Stop at the end of each response, not only at session end; the hourly throttle paces it, so at most once an hour it reports a redacted count and the highest severity of credential exposures found in recent sessions, and points at skarn assess. Never egresses, never prints a secret value.

Cursor

Cursor fires camelCase events, each with its own stdin shape and its own verdict schema - unlike Claude's single envelope. All four blocking events are wired by default.

Routing. The camelCase event names are unique to Cursor, so auto-detection is unambiguous.

Fail mode. Fail-open by default; --strict plus enforce exits 2 (Cursor's schema-agnostic hard block) on an unparseable event.

"Shipped" means the hook configs in the Skarn repository wire the event by default. An opt-in event is fully supported by the binary - add a block for it to your own config to enable it.

beforeReadFile

Gated only under --strict, exactly like Claude's Read; the shipped Cursor config passes --strict on this event alone.

beforeSubmitPrompt

The channel ships content off the machine, so a secret on it is exfiltration. No permission channel, so a would-be ask blocks too. The block is recoverable: the user edits and resubmits.

Codex CLI

Codex's hook system mirrors Claude's - PascalCase events and a near-identical PreToolUse JSON - but its verdict semantics differ: permissionDecision ask and a bare allow both FAIL OPEN, so a would-be ask degrades to deny. Codex fires more events than Skarn wires; the rest are evaluated and deliberately left off the matrix (verified against the OpenAI Hooks guide, 2026-07-21): SessionStart and SubagentStart carry only session and subagent metadata (model, permission_mode, agent_id/type), no credential-bearing tool or prompt content; PreCompact and PostCompact carry only a compaction trigger over already-seen transcript the recall scan covers; SubagentStop carries last_assistant_message (so it is NOT content-free), but that post-hoc subagent output lands in the session store the recall scan and the turn-end advisory already cover, so it is a deliberate deferral pending the cross-action daemon the codex README names. Codex has no SessionEnd event in the current reference; if one lands in a later release it is additive.

Routing. Codex shares Claude's event names, so pass --agent codex explicitly. Auto-detection falls back to a Codex-only tell: turn_id (on every turn-scoped event, PermissionRequest included) or the apply_patch/spawn_agent tools.

Fail mode. Fail-open by default; --strict plus enforce emits an explicit deny JSON on an unparseable event.

"Shipped" means the hook configs in the Skarn repository wire the event by default. An opt-in event is fully supported by the binary - add a block for it to your own config to enable it.

PermissionRequest

The approval-flow gate: any deny wins, closing PreToolUse's updatedInput and ask fail-open edges.

UserPromptSubmit

The channel ships content off the machine, so a secret on it is exfiltration.

PostToolUse

Output scanning. Opt-in - it fires on every tool result.

Stop

The turn-end advisory - Codex Stop is turn-scoped (it fires when the agent finishes a turn), not a session-end signal. Handled at run() level by isSessionEndEvent (guard.zig), which scans with --agent codex; at most once an hour it reports a redacted count and the highest severity of credential exposures in recent codex sessions and points at skarn assess. Claude and Codex share one hourly advisory budget (the guard-assess-advisory throttle), so activity on either host can suppress the other's nudge for that hour - a deliberate global budget, not a per-host one. Never egresses, never prints a secret value.

GitHub Copilot CLI

The Copilot CLI's native payload is camelCase (toolName / toolArgs / sessionId) and carries no event-name field, so the event is inferred from the field shape - except permissionRequest, whose payload is a subset of preToolUse's and which the config entry therefore names with --event permissionRequest. preToolUse and permissionRequest both block; the other events run full detection and write the audit log but cannot decide. GitHub documents fourteen Copilot CLI hook events; Skarn declares five of them (preToolUse, permissionRequest, userPromptSubmitted, userPromptTransformed, postToolUse) plus preMcpToolCall, and evaluates the rest as deliberately not wired (verified against the GitHub hooks reference, 2026-07-30): sessionStart carries an initialPrompt (scannable), but a session-open detection arm beyond userPromptTransformed is out of this round's scope; subagentStart and subagentStop carry subagent metadata (agentName, transcriptPath), and the subagent's own tool calls are gated by preToolUse while any post-hoc output lands in the session store the recall scan covers; postToolUseFailure carries the failed call's toolArgs plus its error text, which can hold output preToolUse never saw, so leaving it unwired is a deliberate coverage deferral of the same class as the opt-in postToolUse output scan; errorOccurred and notification carry human-readable error and message text (a low-value surface deferred this round, not a claim they can never carry a secret); preCompact carries a compaction trigger and any customInstructions over already-seen transcript; agentStop (Stop) and sessionEnd carry only a stopReason/reason over transcript the recall scan covers. Every one of these is a deliberate coverage deferral, not an assertion that the event can never carry a credential.

Routing. The camelCase field set is the CLI tell. A Copilot payload in Claude-compat mode is byte-indistinguishable from a real Claude event (field names AND tool names), so the shipped Copilot configs always pass --agent copilot explicitly. The CLI loads hooks from policy, then the repository, then the user, then inline repository settings, then inline user settings, then plugins, and how several hooks for one event compose differs by event. On preToolUse any hook returning deny blocks the tool, so a Skarn deny there is final; measured on CLI 1.0.70 the entries after the denying one did not run at all, and on 1.0.61 under SDK 1.0.1 the host's own SDK-registered callback was never invoked for that call either. On permissionRequest every configured hook runs and their outputs are MERGED with later outputs overriding earlier ones, so a Skarn deny there is not final: a hook loading after it that answers allow replaces the decision. That is why preToolUse remains the durable gate and permissionRequest is a second chokepoint rather than a stronger one. A top-level disableAllHooks: true in the repository's .github/copilot/settings.json skips the user- and repository-delivered hooks for that repository, the operator's own included, and logs nothing when it does; whether machine policy hooks survive it is unverified. It silences the layers it reaches across events (sessionStart as well as preToolUse) and leaves the host application's own SDK-registered callbacks running, so doctor reads that file and reports the file layer as inert rather than counting it as protection or calling the machine unprotected.

Fail mode. preToolUse fails CLOSED on a non-zero exit, but a hook TIMEOUT fails OPEN (the shipped configs set timeoutSec 10). permissionRequest treats exit 2 as a deny.

"Shipped" means the hook configs in the Skarn repository wire the event by default. An opt-in event is fully supported by the binary - add a block for it to your own config to enable it.

preToolUse

The durable gate on this host: a deny from ANY hook blocks the tool, so Skarn's answer here cannot be replaced by a later one. It is also the only Copilot event where ask is a real interactive prompt rather than a degraded deny.

permissionRequest

The second chokepoint on this host: the permission-decision step for a call preToolUse deferred or allowed. GitHub documents its payload as a subset of preToolUse's and no field separates the two, so the guard never infers it - the shipped config entries pass --event permissionRequest, and an unpinned payload is read as preToolUse. A would-be ask degrades to deny (the schema has allow and deny and no ask value). Its deny is not final the way a preToolUse deny is: outputs from several permissionRequest hooks merge last-writer-wins, and the load order is policy, repository, user, inline settings, plugins - so a policy-delivered Skarn deny is the MOST overridable placement and a plugin-delivered one the least. Audit is silent by design: the only other output fields are message and an interrupt that stops the whole agent, and a message with no behavior would ride into another hook's merged decision, so there is no channel here that advises without deciding.

userPromptSubmitted

The channel ships content off the machine, so a secret on it is exfiltration. A secret typed into a Copilot CLI prompt is detected and logged but NOT blocked before it reaches the provider - unlike Claude Code and Codex, whose prompt-submit hooks can block. A host limitation, not a Skarn one.

userPromptTransformed

The channel ships content off the machine, so a secret on it is exfiltration. On this event Skarn detects and writes the audit log only; it never blocks or decides, because the event's sole output channel is modifiedTransformedPrompt (a prompt rewrite) which Skarn declines by policy - it observes and blocks but never rewrites model-facing content, a Skarn policy rather than a host limitation. Opt-in, not wired in the shipped configs: a config update reaches users independently of the binary, and a binary predating this event would scan the payload as userPromptSubmitted (it carries prompt), so the opt-in row avoids that ambiguity until a release carrying the arm is current.

preMcpToolCall

Supported but not wired in the shipped configs: it cannot block or advise, so it buys detection coverage in the guard log only. Added in Copilot CLI 1.0.51 and still firing (no removal through 1.0.73), and still absent from GitHub's hooks-reference event table on re-verification 2026-07-30, which is why it gains no decision channel here: the one output the SDK documents for it is metaToUse, MCP request metadata, and Skarn does not emit a verdict schema the vendor does not publish. The row is kept version-scoped because older supported CLIs still fire it.

postToolUse

Output scanning. Opt-in - it fires on every tool result.

GitHub Copilot (VS Code agent mode)

VS Code agent mode speaks a second Copilot dialect: PascalCase event names in a Claude-shaped envelope, camelCase tool_input keys, and VS Code's own tool-name vocabulary (run_in_terminal, create_file, ...), which Skarn maps to canonical names. MCP calls arrive as PreToolUse with an mcp_<server>_<tool> name.

Routing. VS Code discovers hooks from ~/.claude/settings.json (chat.hookFilesLocations), so a machine already running Skarn's Claude guard receives VS Code Copilot events. The VS Code tool-name vocabulary routes them to the Copilot adapter instead of a silent Claude fast-allow; the shipped configs pin --agent copilot.

Fail mode. VS Code blocks only on exit 2; any other non-zero exit fails OPEN.

"Shipped" means the hook configs in the Skarn repository wire the event by default. An opt-in event is fully supported by the binary - add a block for it to your own config to enable it.

UserPromptSubmit

The channel ships content off the machine, so a secret on it is exfiltration. Unlike the Copilot CLI, the VS Code host honors a prompt-submit block. On the cloud agent an ask degrades to deny (non-interactive).

PostToolUse

Output scanning. Opt-in - it fires on every tool result.

Gemini CLI

Gemini CLI fires eleven PascalCase events with a JSON envelope on stdin; hooks ship on by default since v0.26.0. Skarn gates three of them - BeforeTool (the enforcing pre-execution gate), BeforeAgent (the submitted prompt, an egress channel), and AfterTool (the tool result, opt-in) - and every other event fast-allows. The stdout protocol is strict: the host requires that a hook print nothing to stdout but its final JSON object, so the guard's emit arm is the sole stdout writer and an allow prints nothing at all. Gemini's PUBLISHED output schema documents only allow and deny (alias block), with no ask value; gemini-cli 0.49.0 does route an undocumented decision "ask" on BeforeTool to an interactive confirmation, but skarn deliberately does not emit it: a version that drops the undocumented behavior would read "ask" as no decision and let the call through, so a would-be ask degrades to deny (fail-closed on an undocumented channel). Timeouts are MILLISECONDS here, not seconds (the shipped entries use 5000).

Routing. The Before*/After* event vocabulary is unique to Gemini - no other host uses those names - so auto-detection is unambiguous; the shipped configs pin --agent gemini anyway, the same policy every other host follows. MCP tools arrive named mcp_<server>_<tool> with SINGLE underscores, so the guard keys MCP treatment on that prefix rather than on the canonical mcp__ form.

Fail mode. A non-2 non-zero exit is a warning and fails open; exit 2 blocks with stderr as the reason. --strict plus enforce exits 2 on an unparseable event.

"Shipped" means the hook configs in the Skarn repository wire the event by default. An opt-in event is fully supported by the binary - add a block for it to your own config to enable it.

BeforeTool

The entry timeout is in milliseconds (5000), unlike Claude's seconds. Gemini reads ONE command field on every platform - there is no windows variant - so setup renders the form the machine it configures needs, and a project-scope file committed from POSIX fails open (a warning) on a native-Windows teammate. MCP calls arrive as mcp_<server>_<tool>; skarn always rewrites the name to the canonical mcp__ form so every tool-keyed detector sees an MCP call, recovering the real server/tool split from mcp_context when it is present, and never fast-allows either way. The event also offers hookSpecificOutput.tool_input, which rewrites the model's arguments - skarn surfaces and blocks but never rewrites, so that channel is deliberately unused.

BeforeAgent

The channel ships content off the machine, so a secret on it is exfiltration. A lone secret is enough to deny here - the destination is not ambiguous. A deny blocks the turn and discards the message from history; it is recoverable, the user edits and resubmits.

AfterTool

Output scanning. Opt-in - it fires on every tool result.

Wiring it up

skarn setup detects the AI coding agents installed on the machine and merges the guard hook into each one's native config in audit mode - existing hooks untouched, every modified file backed up and rewritten atomically, and the run ends with a self-test that proves the wiring end to end. skarn doctor then verifies it stays alive: it names any event your installed config does not gate, and it catches a dead hook (a wired command whose binary no longer exists), which every host silently fails open on.

Full option reference: the guard, setup, and doctor sections of the manual.