hook-authoring

SessionStart

When: New Claude Code session begins

Use Cases: Load context, initialize state, capture metadata

Stop

When: Claude completes a response (not user)

Use Cases: Extract completion info, update tab titles, capture work

UserPromptSubmit

When: User submits a prompt

Use Cases: Pre-processing, context injection, tab updates

SubagentStop

When: A subagent (Task) completes

Use Cases: Agent tracking, result capture, coordination

Notification

When: Notifications are triggered

Use Cases: Alerts, external integrations

---

Location: ${PAI_DIR}/.claude/settings.json or ~/.claude/settings.json

```json

{

"hooks": {

"SessionStart": [

{

"matcher": {},

"hooks": [

{

"type": "command",

"command": "${PAI_DIR}/hooks/my-hook.ts"

}

]

}

]

}

}

```

---

Input (stdin JSON)

```typescript

interface HookInput {

session_id: string;

transcript_path: string;

// Event-specific fields...

}

```

Output (stdout)

• Continue: { "continue": true }
• Block: { "continue": false, "reason": "..." }
• Inject content: { "result": "..." }
• Add context (CC 2.1.9+): { "decision": "continue", "additionalContext": "..." }

Session ID Tracking (CC 2.1.9+)

Hooks receive session_id in input JSON. For persistent storage:

```typescript

// Use session_id from hook input

const sessionFile = ${PAI_DIR}/state/sessions/${input.session_id}.json;

// Or use ${CLAUDE_SESSION_ID} substitution in settings.json:

{

"hooks": {

"SessionStart": [{

"hooks": [{

"type": "command",

"command": "${PAI_DIR}/hooks/init-session.ts --session ${CLAUDE_SESSION_ID}"

}]

}]

}

}

```

---

| Hook | Event | Purpose |

|------|-------|---------|

| session-start.ts | SessionStart | Load CORE skill, set tab |

| stop-hook.ts | Stop | Extract COMPLETED, update tab |

| subagent-stop-hook.ts | SubagentStop | Track agent completion |

| capture-all-events.ts | All | JSONL logging |

---

1. Fail gracefully - Hooks should never block Claude
2. Timeout protection - Use timeouts for external calls
3. Async by default - Don't block the main process
4. TypeScript preferred - Use Bun for execution
5. Log errors - Don't fail silently

---

```typescript

#!/usr/bin/env bun

// ${PAI_DIR}/hooks/my-hook.ts

import { readFileSync } from 'fs';

const input = JSON.parse(readFileSync('/dev/stdin', 'utf-8'));

// Your logic here

// Output (choose one):

console.log(JSON.stringify({ continue: true }));

// console.log(JSON.stringify({ result: "..." }));

```

Make executable: chmod +x my-hook.ts

---

• See agent-observability skill for event analysis
• See capture-all-events.ts for JSONL logging pattern