Hooks — reference

Hook events

Both plugin manifests carry the same entries, and every entry runs src/cli/hook.mjs (src/cli/housekeeping.mjs for SessionStart). Copilot CLI sends its own tool names (bash, create, str_replace, view, …); adapters/api/hooks/harness-input.mjs maps them to the names above before any guard runs.

G7 and G8 read a shell command by its form: redirections, tee, rewriting and copying verbs, in-place sed and perl, inline node -e or python -c scripts, behind VAR=value assignments and wrappers such as sudo or env. A write hidden behind bash -c, a variable, a subshell or find -delete is not recognised.

Phase gate (state CLI, G4/G5)

Phase completion is not a hook. The orchestrator records artifacts and verdicts after a subagent returns, so the check runs when the phase closes: state.mjs transition and state.mjs close-phase refuse with PHASE_GATE unless

• G4 — every required tracked output of the phase is recorded and present on disk;
• G5 — the deciding review artifact is recorded and present, its verdict equals the recorded verdict, and a closing DELIVER phase has a commit since the phase started.

The gate fails closed: a phase that cannot be checked does not close.

Verification status

Every guard above is covered by unit and acceptance tests under tests/skraft-framework/. A live harness run is a separate receipt: scripts/copilot-hook-smoke.mjs and scripts/claude-plugin-smoke.mjs drive a real session through one allowed shell command and one G7 refusal. The last recorded pass is Copilot CLI 1.0.83 for those two probes; the other guards have no live receipt, and Vally evaluations do not load plugin hooks.

Decision types (internal vocabulary)

Handlers return one of four decisions, built by plugins/skraft-framework/src/adapters/api/hooks/decision.mjs:

allow()                                  // { decision: 'allow' }
deny('Reason for denial')                // { decision: 'deny', message: … }
block('Reason for block')                // { decision: 'block', message: … }
additionalContext('Added information')   // { decision: 'additionalContext', context: … }

This vocabulary never reaches the harness. It is the framework’s own language, translated at the CLI boundary by plugins/skraft-framework/src/adapters/api/hooks/harness-output.mjs.

Harness wire format (what is actually written to stdout)

Both harnesses type the root decision key as "approve" | "block". Writing {"decision":"allow"} or {"decision":"deny"} invalidates the whole payload — Claude Code logs Hook JSON output validation failed — (root): Invalid input, discards the output and lets the tool run. A guard emitting the internal vocabulary is therefore inert.

A single envelope satisfies both runtimes: Claude Code reads hookSpecificOutput and drops unknown root keys, Copilot CLI reads the root keys and ignores hookSpecificOutput.

// deny / block on PreToolUse — the tool alone is refused, the session keeps going
{
  "permissionDecision": "deny",
  "permissionDecisionReason": "Reason for denial",
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Reason for denial"
  }
}

// deny / block on any other event
{ "decision": "block", "reason": "Reason for block" }

// additionalContext
{
  "additionalContext": "Added information",
  "hookSpecificOutput": { "hookEventName": "PostToolUse", "additionalContext": "Added information" }
}

hookSpecificOutput.hookEventName must match the event currently running, otherwise Claude Code drops the block. A block on PreToolUse maps onto permissionDecision: "deny" and never continue: false: a hook bug must not freeze the pipeline.

If the hook writes nothing or exits 0 without output, both runtimes interpret it as allow.

Payload normalisation

All incoming payloads are normalised to camelCase before routing:

Implemented in plugins/skraft-framework/src/adapters/api/hooks/payload.mjs.

Environment variables

The hooks and the CLIs read these variables; none is required.

src/application/config-loader.mjs implements an env → ~/.skraft/config.json → .skraftrc.json cascade, but no hook or CLI reads it.

Source files

See also

• Guardrails (hooks) — why hooks exist
• Clean Architecture — framework layers