Hook System Overview

Hooks are scripts that GigiKit runs automatically before or after specific tool calls. They let you enforce policies, inject runtime context, and customize agent behavior without modifying prompts or agent code.

What Are Hooks?

A hook is a script (bash, Python, or Node.js) that the GigiKit runtime invokes at a defined lifecycle point. Hooks receive structured JSON describing the tool call about to happen (or that just happened), and they can:

Block the tool call and return an error or prompt
Inject additional context into the agent’s environment
Log tool activity for auditing
Transform inputs or outputs

Hook Types

Hook type	Timing	Common uses
`PreToolUse`	Before a tool call executes	Block sensitive file reads, validate inputs, inject context
`PostToolUse`	After a tool call completes	Log output, trigger follow-up actions, validate results
`SubagentStart`	When a subagent session begins	Inject plan context, set working paths, announce team role
`Stop`	When an agent session ends	Flush reports, notify lead, clean up temp files

Directory Structure

All hooks live under .claude/hooks/:

.claude/
└── hooks/
    ├── pre-tool-use/
    │   ├── privacy-block.sh        # blocks reads of sensitive files
    │   └── file-naming-guidance.sh # injects naming rules for Write calls
    ├── post-tool-use/
    │   └── compile-check.sh        # runs compiler after file writes
    ├── subagent-start/
    │   └── inject-plan-context.sh  # injects active plan path into subagent
    └── stop/
        └── flush-reports.sh        # ensures reports are written before exit

Each subdirectory maps to a lifecycle event. Every script in the directory runs for that event.

Hook Lifecycle

Agent requests tool call
        ↓
[PreToolUse hooks run]
  - Hook blocks? → Agent receives error/prompt, tool call cancelled
  - Hook passes? → Tool call executes
        ↓
Tool call executes
        ↓
[PostToolUse hooks run]
  - Hook can log, trigger side effects, or modify reported output
        ↓
Agent receives tool result

Hook Input Format

Hooks receive a JSON payload on stdin describing the intercepted event:

// Example PreToolUse hook input
{
  "tool": "Write",
  "params": {
    "file_path": "/project/src/auth/user-service.ts",
    "content": "..."
  },
  "session_id": "abc123",
  "cwd": "/project"
}

Hook Output Format

A hook communicates its decision via exit code and stdout:

Exit code	Meaning
`0`	Allow the tool call to proceed
`1`	Block the tool call; stdout is returned to the agent as an error message
`2`	Block and inject context; stdout is appended to the agent’s next message

Common Built-in Hooks

Privacy block hook — prevents agents from reading files that match sensitive patterns (.env, *.key, credential files) without explicit user approval. See Building Custom Hooks for the full implementation.

File naming guidance hook — fires on every Write call and injects kebab-case naming rules into the agent’s context so generated files follow project conventions.

Subagent start hook — fires when a subagent session begins, injecting the active plan directory, reports path, and agent role from the orchestration context.

Building Custom Hooks — step-by-step guide to writing your own hooks
The 6-Step Development Workflow — how hooks integrate with the development pipeline
Development Rules: YAGNI, KISS, DRY — rules that hooks help enforce automatically