Guard rails: the brake layer between model and action

A small task, far too many permissions

You give the agent a small task: fix validation in a module. To be safe it scans a few extra directories, opens a sensitive config file, then conveniently bundles some unrelated cleanup into the same PR.

At first glance everything looks fine. Tests still pass. But context has been polluted with junk files, secrets may have entered the transcript (the complete record of the conversation between you and the agent), and the review is diluted because the intended change and the "convenient" additions sit in the same PR.

What are guard rails in agentic coding

A guard rail is the layer that stands between the agent and an action: blocking risky operations, warning on suspicious ones. It is like a railing on the edge of a staircase: it doesn't make you walk better, but it reduces the chance that a misstep becomes an accident. Unlike instructions in the prompt, i.e. prompt instructions, guard rails run at the tool-orchestration layer and do not depend on the model "remembering" them.

Guard rail vs. instruction

How guard rails work

Harness is the runtime layer wrapping the model. The model only decides "I want to read this file" or "I want to run this command"; it is the harness that receives the tool call, manages permissions, invokes hooks, lets the tool run or blocks it, then returns the result to the model. Hooks are small scripts the harness calls at fixed points in a tool call's lifecycle — on prompt receipt, before a tool, after a tool — to intervene and check. Because every real action goes through the harness, this is where guard rails attach.

For conceptual background, read: What is Harness Engineering? by Duy /zuey/.

ClaudeKit Hooks Map

For more detail on ClaudeKit Hooks, see VividKit Guides.

Hooks do not live inside the model. They live in Claude Code's lifecycle: settings.json decides which hooks are called, .ck.json/ENV decides runtime behavior, and hook output can allow, block, inject context, or write state/artifacts after a tool or session ends.

Flow of a tool call through guard rails

The key point: a pre-tool hook returns an exit code. Exit 0 lets the tool run; exit 2 blocks and pushes the reason back to the model. The three main injection points in the flow have corresponding technical names: UserPromptSubmit (on prompt receipt), PreToolUse (before a tool), PostToolUse (after a tool). Stop/SubagentStop run when a session or subagent ends, so they appear on the lifecycle map above.

Two kinds of blocking

Seven guard rail groups in CK

Where each group is documented

9 familiar situations

Settings and config layers

Two config layers determine which guards run: settings.json attaches hooks to Claude Code's lifecycle; .ck.json enables/disables individual hooks and adjusts thresholds.

# Global scope
~/.claude/settings.json
~/.claude/.ck.json
~/.claude/hooks/*.cjs

# Project scope
.claude/settings.json
.claude/.ck.json
.claude/hooks/*.cjs

settings.json: which hook runs at which point

The snippet below illustrates just one slice of PreToolUse from a fresh CK install: CK provides scout-block and privacy-block, then wires them into the lifecycle so Claude Code calls them before a tool runs. The full hook config on an installed machine has more lifecycle events; the place to check is Claude Code's settings.json.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash|Glob|Grep|Read|Edit|Write",
        "hooks": [
          { "command": "node \".claude/hooks/scout-block.cjs\"" },
          { "command": "node \".claude/hooks/privacy-block.cjs\"" }
        ]
      }
    ]
  }
}

settings.json is the lifecycle map: which hook runs when the user submits a prompt, which is called before a tool runs, which handles things after a tool finishes. For a global install the CLI rewrites relative commands in the template to the form node "$HOME/.claude/hooks/scout-block.cjs"; for a project install, paths usually stay as .claude/hooks/....

Reading the hook table with 3 labels

Don't collapse everything into "on by default / off by default". The state of a hook has three distinct layers:

The table below is a snapshot of the hook list for stable claudekit-engineer@2.19.1. Update 2026-06-09: claudekit-engineer@2.19.2-beta is preparing to remove task-completed-handler and teammate-idle-handler; when upstream ClaudeKit releases a new version, this list may become 14 hooks.

Easy to miss: isHookEnabled() only disables when hooks.<name> is false. A missing key is usually treated as enabled. But some guards also have their own switches: privacy-block still reads the legacy key privacyBlock=false, while simplify-gate has simplify.gate.enabled and ENV CK_SIMPLIFY_DISABLED=1.

Manually enabling/disabling and self-testing hooks

For quick adjustments, edit .ck.json at the scope you want to affect. Project config takes priority over global when a key is explicitly set; missing keys continue to inherit/default. For hooks already wired in settings.json, setting false turns them off; setting true re-enables them after a higher scope has disabled them. The hook name in the Hook column is also the key used in hooks.<name>.

// .claude/.ck.json or ~/.claude/.ck.json
{
  "hooks": {
    "scout-block": false,
    "privacy-block": true
  },
  "privacyBlock": true,
  "simplify": {
    "gate": {
      "enabled": true
    }
  }
}

To know whether a hook gets triggered, look at the lifecycle event, not the file name. The same hook script only runs when the event/matcher in settings.json matches the current action. The table below is a quick-check for each hook; not wired hooks need to be wired first, or called via manual CLI if the script supports it.

// ~/.claude/settings.json or .claude/settings.json
{
  "env": {
    "CK_SIMPLIFY_DISABLED": "1"
  }
}

scout-block — block reads of junk directories

Agents often read node_modules/, glob **/*.ts at root (glob is a path-matching pattern; **/*.ts means every .ts file in every subdirectory), or cat dist/index.js. Each time that's tens of thousands of tokens stuffed into context, driving up cost and degrading the quality of subsequent turns. scout-block.cjs registers PreToolUse and runs before every Read/Bash/Glob/Grep.

# Baseline .ckignore — processed by pattern-matcher.cjs
node_modules
dist
build
.next
.nuxt
__pycache__
.venv
venv
vendor
target
.git
coverage

privacy-block — block secrets, require explicit user approval

Agent touches .env, id_rsa, *.pem, credentials.yaml — secrets leak into the transcript. Once in context, they can be logged, quoted in reviewer output, or pasted into a PR.

@@PRIVACY_PROMPT_START@@
{ "type": "PRIVACY_PROMPT", "question": {...}, "options": [...] }
@@PRIVACY_PROMPT_END@@

Claude parses JSON and calls AskUserQuestion. If the user approves, the hook message instructs reading the file through an approved path, e.g. cat ".env" after asking; the code also supports the APPROVED: prefix. The key point: explicit approval is required — the model must not be allowed to self-interpret consent.

simplify-gate — block shipping when diff has ballooned past scope

A small task can balloon into a PR touching too many files: fix validation, add cleanup, change formatting, tweak a few nearby helpers. When the agent says "OK ship", simplify-gate.cjs registers UserPromptSubmit, reads git diff HEAD, and only acts when the prompt contains: ship merge pr deploy publish.

Defaults from simplify.threshold: total added+removed lines, touched-file count, and the largest added-line count in one file. The gate only blocks when simplify.gate.enabled=true; these values can be overridden in .ck.json.

// project .ck.json — actually enable
{ "simplify": { "gate": { "enabled": true } } }

matchedSeverity() skips "don't ship" and "ship on" → "ship on Friday" also passes through. To disable the gate for all sessions at that scope, set CK_SIMPLIFY_DISABLED=1 in settings.json under the env key.

workflow-artifact-gate — 5 artifact JSONs

Full pipeline → each phase leaves a JSON file recording its decisions, like a receipt after every step. This hook is designed to attach to UserPromptSubmit + PreToolUse(Bash), but is not in the hook set that runs out of the box after a fresh install; you must opt in to use it.

This gate has two processing levels. At high-risk steps such as ship, push, PR, or deploy, the hook can stop the flow immediately and return the reason to the model (emitBlock()). At lighter steps such as finalize or commit, the hook lets the flow continue but injects a warning into context for the model to self-correct (emitSoft()).

Hard-gate XML in skill markdown

Hooks only block tool calls. Some failures are not tool calls but sequence errors: coding before planning, fixing before scouting. CK embeds <HARD-GATE> in skill markdown.

<HARD-GATE>
Do NOT write implementation code until a plan exists
and has been reviewed. Exception: --fast skips research
but still requires a plan step. User override: if user
explicitly says 'just code it', respect their instruction.
</HARD-GATE>

ck:cook and ck:fix each have 4 hard-gates (plan/scout-first, exact-req or root-cause, no-side-effects).

dev-rules-reminder — bring rules into context

dev-rules-reminder.cjs registers UserPromptSubmit and injects rules text into every prompt. Two layers need to be distinguished here: the hook is the context-injection mechanism, while the rules in CLAUDE.md are the content being injected. TTL is 5 minutes keyed on (sessionId, baseDir) to avoid burning tokens.

Guard skills — guard layers the user invokes

code-reviewer agent runs a 9-item checklist: concurrency, error boundary, API contract, backwards compat, input validation, auth/authz, N+1, data leak, fact-check. Final guard before merge.

Known gaps

Best practices & pitfalls

6 questions to ask before trusting a guard rail

• Which hooks is settings.json currently attaching to which lifecycle events?
• Which hooks has .ck.json disabled? (outer + inner config)
• Is the current Claude Code session running with permission prompts suppressed?
• Is there a project .ckignore override? Is node_modules !-allowlisted?
• Are rule files in CLAUDE.md complete?
• Has any hook crashed silently in this session (check stderr)?

Quick terms