@shaykec/bridge 0.4.25 → 0.4.26

package/modules/hiring-interviews/walkthrough.md

@@ -0,0 +1,75 @@
+# Technical Hiring — Walkthrough
+
+## Before We Begin
+
+**Diagnostic Question:** What's the difference between a structured interview and an unstructured one? When might each be appropriate?
+
+**Checkpoint:** You recognize that structured interviews use consistent questions and rubrics for fairness; unstructured interviews feel more natural but risk bias. Both have tradeoffs.
+
+---
+
+## Step 1: Create an Interview Scorecard
+
+<!-- hint:list style="cards" -->
+
+**Task:** For a role you hire for (or a hypothetical mid-level engineer), create a scorecard. List 4–6 competencies. Mark each as must-have or nice-to-have. For each, specify how you'll assess it (behavioral, technical, system design, resume).
+
+**Question:** How do you avoid "kitchen sink" scorecards? What makes a competency truly must-have?
+
+**Checkpoint:** Scorecard has 4–6 competencies, must/nice classification, and assessment method for each.
+
+---
+
+## Step 2: Write a Behavioral Question + Rubric
+
+<!-- hint:buttons type="single" prompt="Which format structures behavioral answers?" options="STAR,SMART,DRY" -->
+
+**Task:** Pick one must-have competency from your scorecard. Write a behavioral question in STAR format. Then write a 3-level rubric: strong, medium, weak. What would each look like in practice?
+
+**Question:** How do you make the rubric useful without being rigid? What if the candidate's story doesn't fit the expected mold?
+
+**Checkpoint:** One question and rubric; usable by another interviewer.
+
+---
+
+## Step 3: Write a Technical Question + Rubric
+
+**Task:** Pick one technical competency. Write a coding or debugging question that's bounded (15–20 min). Write a rubric: what does strong/medium/weak look like? Include: correctness, edge cases, explanation quality.
+
+**Question:** How do you balance "can they code?" with "can they think?"? When do hints help vs. hurt?
+
+**Checkpoint:** Question is unambiguous; rubric has clear levels.
+
+---
+
+## Step 4: Design Your Debrief Process
+
+**Task:** Document your debrief process: Who attends? Do interviewers score before or during? How do you resolve disagreement? What's the hire/no-hire bar? Keep it to one page.
+
+**Question:** What happens when two interviewers strongly disagree? How do you avoid groupthink?
+
+**Checkpoint:** Process is documented; disagreement resolution is clear.
+
+---
+
+## Step 5: Audit for Bias
+
+<!-- hint:card type="warning" title="Bias" -->
+
+**Task:** Review your current (or a past) interview process. List 3 potential bias sources (e.g., similarity bias, halo effect, anchoring). For each, propose one mitigation.
+
+**Question:** What's the tension between "culture fit" and bias? How do you assess culture add without filtering for similarity?
+
+**Checkpoint:** Three bias sources identified; three mitigations proposed.
+
+---
+
+## Step 6: Improve Candidate Experience
+
+<!-- hint:celebrate -->
+
+**Task:** Map the candidate journey from application to offer/reject. Identify 3 pain points (e.g., long wait, unclear feedback, disorganized onsite). Propose one improvement for each.
+
+**Question:** What does a great candidate experience cost? What does a bad one cost?
+
+**Checkpoint:** Journey mapped; three improvements proposed.

package/modules/hooks/content.md

@@ -0,0 +1,97 @@
+# Claude Code Hooks
+
+> **Level: 🌿 Intermediate**
+
+## What Are Hooks?
+
+Hooks are shell commands that Claude Code executes automatically in response to lifecycle events. They let you automate workflows without manual intervention — run linters after edits, track usage statistics, validate changes before commits, and more.
+
+## Lifecycle Events
+
+| Event | When It Fires | Use Cases |
+|---|---|---|
+| **PostToolUse** | After any tool is used (Edit, Write, Bash, etc.) | Linting, formatting, usage tracking |
+| **UserPromptSubmit** | When the user sends a message | Input validation, command detection |
+| **Stop** | When the agent finishes a response | Session tracking, cleanup, notifications |
+
+## Configuration
+
+Hooks are defined in `hooks.json` (for plugins) or in `.claude/settings.json` (for user hooks):
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "command": "./scripts/on-tool-use.sh",
+        "timeout": 5000
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "command": "./scripts/on-prompt.sh",
+        "timeout": 3000
+      }
+    ],
+    "Stop": [
+      {
+        "command": "./scripts/on-stop.sh",
+        "timeout": 5000
+      }
+    ]
+  }
+}
+```
+
+## Environment Variables
+
+Hook scripts receive context via environment variables:
+
+### PostToolUse
+- `TOOL_NAME` — name of the tool that was used (e.g., "Edit", "Bash")
+- `TOOL_INPUT` — JSON string of the tool's input parameters
+- `TOOL_OUTPUT` — JSON string of the tool's output
+
+### UserPromptSubmit
+- `USER_PROMPT` — the text the user submitted
+
+### Stop
+- `STOP_REASON` — why the agent stopped (e.g., "end_turn", "max_tokens")
+- `TOKEN_USAGE` — JSON with input/output token counts
+
+## Example: Auto-Format on Edit
+
+```bash
+#!/bin/bash
+# scripts/auto-format.sh — runs after PostToolUse
+if [ "$TOOL_NAME" = "Edit" ] || [ "$TOOL_NAME" = "Write" ]; then
+  FILE=$(echo "$TOOL_INPUT" | jq -r '.file_path // empty')
+  if [ -n "$FILE" ] && [ -f "$FILE" ]; then
+    npx prettier --write "$FILE" 2>/dev/null
+  fi
+fi
+```
+
+## Example: Track Tool Usage
+
+```bash
+#!/bin/bash
+# scripts/track-usage.sh — counts tool usage per category
+DATA_FILE=".local/usage.json"
+CATEGORY=$(echo "$TOOL_NAME" | tr '[:upper:]' '[:lower:]')
+
+if [ ! -f "$DATA_FILE" ]; then
+  echo '{}' > "$DATA_FILE"
+fi
+
+jq --arg cat "$CATEGORY" '.[$cat] = ((.[$cat] // 0) + 1)' "$DATA_FILE" > "${DATA_FILE}.tmp"
+mv "${DATA_FILE}.tmp" "$DATA_FILE"
+```
+
+## Best Practices
+
+1. **Keep hooks fast** — they block the agent while running. Use the `timeout` field.
+2. **Fail gracefully** — a hook error shouldn't break the user's workflow.
+3. **Use exit codes** — exit 0 for success, non-zero to signal the agent.
+4. **Log, don't print** — write to files, not stdout (stdout goes back to the agent).
+5. **Test independently** — run your hook scripts manually before configuring them.

package/modules/hooks/exercises.md

@@ -0,0 +1,69 @@
+# Claude Code Hooks — Exercises
+
+## Exercise 1: Write a Linting Hook
+
+**Task:** Create a PostToolUse hook that runs a linter (e.g., ESLint, ShellCheck, or a language-appropriate linter) on files when the Edit or Write tool is used. Only run on files that match your project's conventions (e.g., `*.js`, `*.sh`).
+
+**Validation:**
+- [ ] Hook configured in `.claude/settings.json` under PostToolUse
+- [ ] Hook checks `TOOL_NAME` and only runs for Edit/Write
+- [ ] File path extracted from `TOOL_INPUT` (e.g., via `jq`)
+- [ ] Linter runs on the edited file and results are written to a log file (not stdout)
+- [ ] Hook has a reasonable timeout (e.g., 5000ms)
+
+**Hints:**
+1. Parse `TOOL_INPUT` with `jq`: `FILE=$(echo "$TOOL_INPUT" | jq -r '.file_path // empty')`
+2. Check file extension before invoking the linter
+3. Redirect linter output to a file: `eslint "$FILE" >> .local/lint.log 2>&1`
+
+---
+
+## Exercise 2: Write a Usage Tracking Hook
+
+**Task:** Create a PostToolUse hook that increments a counter for each tool category in a JSON file (e.g., `.local/usage.json`). Structure: `{"edit": 5, "write": 3, "bash": 2}`. Use the hook's env vars to determine the tool.
+
+**Validation:**
+- [ ] Hook writes to a JSON file (create it if missing)
+- [ ] Each tool use increments the correct key
+- [ ] File is updated atomically (write to temp, then mv) to avoid corruption
+- [ ] Hook exits 0 on success so it doesn't break the session
+
+**Hints:**
+1. Use `jq` to merge: `jq --arg cat "$TOOL_NAME" '.[$cat] = ((.[$cat] // 0) + 1)' file.json`
+2. For atomic write: `jq ... file.json > file.json.tmp && mv file.json.tmp file.json`
+3. Normalize tool name: `$(echo "$TOOL_NAME" | tr '[:upper:]' '[:lower:]')`
+
+---
+
+## Exercise 3: Write a Validation Hook
+
+**Task:** Create a UserPromptSubmit hook that checks if the user's prompt contains a blocklisted word or pattern (e.g., "delete everything"). If detected, write a warning to a file and optionally append the prompt to an audit log. Do not block the agent — just log.
+
+**Validation:**
+- [ ] Hook reads `USER_PROMPT` from the environment
+- [ ] Pattern matching implemented (grep, case statement, or simple `[[ == *pattern* ]]`)
+- [ ] Warning written to a file when pattern matches
+- [ ] Hook fails gracefully (handles empty `USER_PROMPT`, missing files)
+- [ ] Hook has a short timeout (e.g., 2000ms)
+
+**Hints:**
+1. `if [[ "$USER_PROMPT" == *"delete everything"* ]]; then ...`
+2. Write audit trail: `echo "$(date -Iseconds) $USER_PROMPT" >> .local/audit.log`
+3. Use `set +e` or ensure script exits 0 even when pattern matches — you're logging, not blocking
+
+---
+
+## Exercise 4: Chain Multiple Hooks
+
+**Task:** Configure at least two different hooks for the same project: (1) a PostToolUse hook that runs your linter, and (2) a Stop hook that logs token usage. Verify both run correctly in a single session.
+
+**Validation:**
+- [ ] PostToolUse hook runs during the session (check log/file output)
+- [ ] Stop hook runs when the agent finishes (check log/file output)
+- [ ] Both hooks are in `.claude/settings.json`
+- [ ] Session completes without errors from the hooks
+
+**Hints:**
+1. Hooks are arrays — you can have multiple commands per event: `"PostToolUse": [{...}, {...}]`
+2. Run a quick Edit in Claude Code, then check your hook output files
+3. Ensure each script has a unique log file so you can distinguish them

package/modules/hooks/module.yaml

@@ -0,0 +1,39 @@
+slug: hooks
+title: "Claude Code Hooks"
+version: 1.0.0
+description: "Automate workflows with lifecycle hooks — PostToolUse, UserPromptSubmit, Stop events."
+category: claude-code
+tags: [hooks, automation, claude-code, lifecycle]
+difficulty: intermediate
+
+xp:
+  read: 15
+  walkthrough: 30
+  exercise: 20
+  quiz: 15
+  quiz-perfect-bonus: 10
+  game: 25
+  game-perfect-bonus: 15
+
+time:
+  quick: 5
+  read: 10
+  guided: 45
+
+prerequisites: []
+related: [skills, sub-agents]
+
+triggers:
+  - "How do hooks work in Claude Code?"
+  - "How do I run a script after every tool use?"
+  - "What lifecycle events are available?"
+
+visuals:
+  diagrams: [diagram-flow, diagram-architecture]
+  quiz-types: [quiz-timed-choice, quiz-fill-blank, quiz-drag-order]
+  playground: javascript
+  workshop: true
+
+sources:
+  - url: "https://docs.anthropic.com/en/docs/claude-code"
+    label: "Claude Code Documentation"

package/modules/hooks/quick-ref.md

@@ -0,0 +1,93 @@
+# Claude Code Hooks — Quick Reference
+
+## Lifecycle Events
+
+| Event | When It Fires | Use Cases |
+|---|---|---|
+| **PostToolUse** | After any tool is used (Edit, Write, Bash, etc.) | Linting, formatting, usage tracking |
+| **UserPromptSubmit** | When the user sends a message | Input validation, command detection |
+| **Stop** | When the agent finishes a response | Session tracking, cleanup, notifications |
+
+## Environment Variables by Event
+
+### PostToolUse
+| Variable | Description |
+|---|---|
+| `TOOL_NAME` | Name of the tool (e.g., "Edit", "Write", "Bash") |
+| `TOOL_INPUT` | JSON string of the tool's input parameters |
+| `TOOL_OUTPUT` | JSON string of the tool's output |
+
+### UserPromptSubmit
+| Variable | Description |
+|---|---|
+| `USER_PROMPT` | The text the user submitted |
+
+### Stop
+| Variable | Description |
+|---|---|
+| `STOP_REASON` | Why the agent stopped (e.g., "end_turn", "max_tokens") |
+| `TOKEN_USAGE` | JSON with input/output token counts |
+
+## Configuration Syntax
+
+Hooks are defined in `.claude/settings.json` or `hooks.json`:
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "command": "./scripts/on-tool-use.sh",
+        "timeout": 5000
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "command": "./scripts/on-prompt.sh",
+        "timeout": 3000
+      }
+    ],
+    "Stop": [
+      {
+        "command": "./scripts/on-stop.sh",
+        "timeout": 5000
+      }
+    ]
+  }
+}
+```
+
+## Parsing Tool Input (PostToolUse)
+
+```bash
+# Get file path from Edit/Write tool input
+FILE=$(echo "$TOOL_INPUT" | jq -r '.file_path // empty')
+
+# Check if it's a code file
+if [ -n "$FILE" ] && [[ "$FILE" == *.js ]]; then
+  npx eslint "$FILE" >> .local/lint.log 2>&1
+fi
+```
+
+## Best Practices
+
+| Practice | Reason |
+|---|---|
+| **Keep hooks fast** | They block the agent; use `timeout` |
+| **Fail gracefully** | A hook error shouldn't break the user's workflow |
+| **Log, don't print** | Stdout can be fed back to the agent |
+| **Test independently** | Run scripts manually with fake env vars first |
+| **Use exit codes** | Exit 0 for success; document non-zero semantics |
+
+## Testing Hooks Manually
+
+```bash
+# Simulate PostToolUse
+TOOL_NAME=Edit TOOL_INPUT='{"file_path":"src/app.js"}' TOOL_OUTPUT='{}' ./scripts/on-tool-use.sh
+
+# Simulate UserPromptSubmit
+USER_PROMPT="Review this PR" ./scripts/on-prompt.sh
+
+# Simulate Stop
+STOP_REASON=end_turn TOKEN_USAGE='{"input":1000,"output":500}' ./scripts/on-stop.sh
+```

package/modules/hooks/quiz.md

@@ -0,0 +1,81 @@
+# Claude Code Hooks — Quiz
+
+## Question 1
+
+What are Claude Code hooks?
+
+A) AI-generated code snippets
+B) Shell commands that run automatically in response to lifecycle events
+C) Plugins that extend the Claude Code UI
+D) Environment variables set by the user
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: Hooks are shell commands defined in hooks.json or .claude/settings.json. Claude Code executes them automatically when events like PostToolUse, UserPromptSubmit, or Stop occur. -->
+
+## Question 2
+
+<!-- VISUAL: fill-blank -->
+
+Complete the hook configuration. To run a script after every tool use, you add it under the __________ key in `.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "__________": [
+      { "command": "./scripts/on-tool-use.sh", "timeout": 5000 }
+    ]
+  }
+}
+```
+
+<!-- ANSWER: PostToolUse -->
+<!-- EXPLANATION: PostToolUse is the lifecycle event that fires after any tool is used (Edit, Write, Bash, etc.). The configuration key must match the exact event name. -->
+
+## Question 3
+
+Which environment variable is available in a PostToolUse hook?
+
+A) `USER_PROMPT`
+B) `TOOL_NAME`
+C) `STOP_REASON`
+D) `TOKEN_USAGE`
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: PostToolUse hooks receive TOOL_NAME, TOOL_INPUT, and TOOL_OUTPUT. USER_PROMPT is for UserPromptSubmit; STOP_REASON and TOKEN_USAGE are for Stop. -->
+
+## Question 4
+
+<!-- VISUAL: drag-order -->
+
+Put these lifecycle events in the order they occur during a single agent turn:
+
+A) Stop
+B) UserPromptSubmit
+C) PostToolUse (may fire multiple times)
+
+<!-- ANSWER: B,C,A -->
+<!-- EXPLANATION: UserPromptSubmit fires when the user sends a message (start of turn). PostToolUse fires after each tool call during the turn. Stop fires when the agent finishes its response (end of turn). -->
+
+## Question 5
+
+Why should hook scripts "log, don't print"?
+
+A) Printing is slower than file I/O
+B) Stdout from hooks can be fed back to the agent and confuse it
+C) Logs are required by Claude Code
+D) Printing only works in certain shells
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: When a hook runs, its stdout may be captured and sent to the agent as context. Writing diagnostic output to stdout could pollute the agent's context. Writing to files keeps the agent's input clean. -->
+
+## Question 6
+
+What is a key reason to set a `timeout` on a hook?
+
+A) Hooks are asynchronous by default
+B) Hooks block the agent — a slow or stuck hook delays the whole session
+C) Timeouts are required for security
+D) Without a timeout, hooks run indefinitely in the background
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: Hooks run synchronously. While a hook is executing, the agent waits. A hung or very slow hook (e.g., a network call) would block the user's workflow. The timeout field prevents runaway hooks. -->

package/modules/hooks/resources.md

@@ -0,0 +1,34 @@
+# Claude Code Hooks — Resources
+
+## Official Docs
+
+- [Claude Code Documentation](https://docs.anthropic.com/en/docs/claude-code) — Main reference for hooks configuration, lifecycle events, and environment variables.
+- [Claude Code Settings](https://docs.anthropic.com/en/docs/claude-code/settings) — Where hooks are configured in `.claude/settings.json`.
+
+## Videos
+
+- [Claude Code Deep Dive](https://www.youtube.com/results?search_query=claude+code+hooks+automation) — Walkthroughs demonstrating hook-based automation.
+- [Git Hooks Explained](https://www.youtube.com/watch?v=egfuwOe8nXc) — Fireship. Conceptually similar lifecycle hooks in Git — helpful mental model.
+
+## Articles and Readings
+
+- [Anthropic Cookbook — Tool Use](https://github.com/anthropics/anthropic-cookbook/tree/main/tool_use) — Patterns for extending agent behavior, relevant to hook design.
+- [Git Hooks Documentation](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks) — Pro Git. Lifecycle hook patterns that inspired Claude Code hooks.
+- [Husky — Git Hooks Made Easy](https://typicode.github.io/husky/) — Popular tool for managing Git hooks, illustrates the hook automation pattern.
+
+## Books
+
+- **The Pragmatic Programmer** by Hunt & Thomas — Chapter on "Domain Languages" covers automation pipelines relevant to hook scripting. [pragprog.com](https://pragprog.com/titles/tpp20/the-pragmatic-programmer-20th-anniversary-edition/).
+
+## Tools and Frameworks
+
+- [jq](https://jqlang.github.io/jq/) — Lightweight JSON processor used in hook scripts to parse tool input/output.
+- [Prettier](https://prettier.io/) — Code formatter commonly invoked from PostToolUse hooks for auto-formatting.
+- [ESLint](https://eslint.org/) — Linter frequently wired into hooks for real-time code quality checks.
+- [ShellCheck](https://www.shellcheck.net/) — Static analysis for bash scripts — useful for validating your hook scripts.
+- [lefthook](https://github.com/evilmartians/lefthook) — Fast hook runner for Git, useful pattern reference for lifecycle automation.
+
+## Related Concepts
+
+- [Webhooks (MDN)](https://developer.mozilla.org/en-US/docs/Glossary/Webhook) — The broader pattern of event-driven callbacks that hooks implement.
+- [Observer Pattern (Refactoring Guru)](https://refactoring.guru/design-patterns/observer) — Design pattern behind lifecycle event systems.

package/modules/hooks/walkthrough.md

@@ -0,0 +1,105 @@
+# Claude Code Hooks — Walkthrough
+
+## Before We Begin
+
+<!-- hint:card type="concept" title="Automation runs in response to events" -->
+
+**Warm-up:** Think about automation you use today — Git hooks, CI pipelines, formatters that run on save. What do they have in common? What "events" trigger them, and what happens after?
+
+**Checkpoint:** The user should recognize that automation is often event-driven: something happens (a commit, a push, a file save), and a script runs. Hooks extend this pattern to the AI coding session.
+
+---
+
+## Step 1: What Are Hooks?
+
+Hooks are shell commands that Claude Code runs automatically when certain events occur.
+
+<!-- hint:diagram mermaid-type="flowchart" topic="Hook flow: event fires → script runs → continues" -->
+
+**Task:** Look at your project's `.claude/settings.json` (or the hooks docs). See if any hooks are already configured.
+
+**Question:** Why might you want a script to run *after* the agent uses a tool, rather than manually running it yourself?
+
+**Checkpoint:** The user should understand that hooks automate repetitive workflows — e.g., linting after every edit, so you never forget. They run transparently in the background of the session.
+
+---
+
+## Step 2: Lifecycle Events
+
+Claude Code fires hooks at three lifecycle points: PostToolUse, UserPromptSubmit, and Stop.
+
+**Task:** Review the table of events. For each event, name one concrete use case from your own workflow.
+
+**Question:** PostToolUse runs after *every* tool call — Edit, Write, Bash, etc. What's the trade-off? When might that be too frequent?
+
+**Checkpoint:** The user should see that PostToolUse is powerful but can be noisy — you might want to filter by tool name (e.g., only run on Edit/Write) or add a timeout to avoid slowdown.
+
+---
+
+## Step 3: Writing a PostToolUse Hook
+
+PostToolUse receives `TOOL_NAME`, `TOOL_INPUT`, and `TOOL_OUTPUT` as environment variables.
+
+<!-- hint:terminal -->
+
+**Task:** Write a minimal PostToolUse hook that logs the tool name to a file (e.g., `.local/hook-log.txt`) when the tool is Edit or Write. Configure it in `.claude/settings.json`.
+
+**Question:** How would you extract the file path from `TOOL_INPUT` inside a shell script? (Hint: it's JSON.)
+
+**Checkpoint:** The user should use `jq` or similar to parse `TOOL_INPUT` and get `file_path`. They should configure the hook with a timeout.
+
+---
+
+## Step 4: Writing a UserPromptSubmit Hook
+
+UserPromptSubmit fires when the user sends a message, before the agent responds.
+
+<!-- hint:card type="concept" title="UserPromptSubmit runs before the agent thinks" -->
+
+**Task:** Write a UserPromptSubmit hook that writes the first 100 characters of the user's prompt to a log file. Use the `USER_PROMPT` environment variable.
+
+**Question:** What could you use UserPromptSubmit for? Think beyond logging — validation, command detection, rate limiting.
+
+**Checkpoint:** The user should identify uses like: detecting `/teach` and routing to a specific handler; validating prompt length; blocking unsafe prompts.
+
+---
+
+## Step 5: Writing a Stop Hook
+
+Stop fires when the agent finishes a response. It receives `STOP_REASON` and `TOKEN_USAGE`.
+
+<!-- hint:terminal -->
+
+**Task:** Write a Stop hook that appends the session's token usage to a file. Parse `TOKEN_USAGE` (JSON) and log input/output counts.
+
+**Question:** Why run something at "Stop" rather than at "PostToolUse"? What kinds of things only make sense at the end of a turn?
+
+**Checkpoint:** The user should recognize that session-level metrics (duration, token usage, cleanup) only make sense when the turn is complete. PostToolUse would fire many times per turn; Stop fires once.
+
+---
+
+## Step 6: Testing Hooks
+
+Hooks block the agent while they run. Slow or failing hooks hurt the experience.
+
+<!-- hint:terminal -->
+
+**Task:** Run your PostToolUse hook script manually with fake env vars: `TOOL_NAME=Edit TOOL_INPUT='{"file_path":"test.txt"}' ./scripts/on-tool-use.sh`. Verify it behaves correctly.
+
+**Question:** What happens if your hook script exits with code 1? Should it? How does the agent interpret non-zero exit?
+
+**Checkpoint:** The user should test hooks in isolation before wiring them up. They should consider: hooks should fail gracefully — a lint failure shouldn't crash the session. Exit codes can signal the agent; document the contract.
+
+---
+
+## Step 7: Error Handling and Best Practices
+
+Hooks run synchronously. They can slow down or break the workflow if misused.
+
+<!-- hint:card type="concept" title="Keep hooks fast; fail gracefully" -->
+
+**Task:** Add a `timeout` to each hook in your config. Ensure your scripts handle missing or malformed env vars (e.g., empty `TOOL_INPUT`).
+
+**Question:** The content says "Log, don't print" — why? What happens to stdout when a hook runs?
+
+**Checkpoint:** The user should understand that stdout from hooks can be fed back to the agent, which may confuse it. Write to files instead. Use `timeout` to prevent runaway hooks.

package/modules/hooks/workshop.yaml

@@ -0,0 +1,64 @@
+scenarios:
+  - id: lint-hook
+    title: "Build a Lint Hook"
+    difficulty: beginner
+    xp: 25
+    setup: []
+    files:
+      - name: scripts/lint-hook.sh
+        content: |
+          #!/bin/bash
+          # TODO: Implement PostToolUse hook that checks for leftover TODO comments
+          exit 0
+        language: bash
+        readonly: false
+    task: "Write a PostToolUse hook that runs after Edit or Write and checks the modified file for leftover TODO comments. If any are found, append the file path and line numbers to .local/todo-report.txt. Configure the hook in .claude/settings.json with a 5000ms timeout."
+    validations:
+      - label: "Hook script exists and is executable"
+        check: output-contains
+        pattern: "lint-hook|todo-report|TODO"
+      - label: "Hook configured in settings"
+        check: output-contains
+        pattern: "PostToolUse|hooks|settings.json"
+      - label: "TODO detection implemented"
+        check: output-contains
+        pattern: "grep|TODO|todo"
+    hints:
+      - "Parse TOOL_INPUT with jq to get file_path. Only run when TOOL_NAME is Edit or Write."
+      - "Use grep -n 'TODO' to find lines. Append results to .local/todo-report.txt."
+      - "Ensure the script handles missing files and exits 0 to avoid breaking the session."
+    agent_prompts:
+      on_start: "What's the difference between a hook that runs on every tool and one that only runs on Edit/Write? Why might you want to filter?"
+      on_complete: "How would you extend this hook to also check for FIXME or XXX comments? What about excluding comments in test files?"
+
+  - id: session-tracker
+    title: "Build a Session Tracker"
+    difficulty: beginner
+    xp: 20
+    setup: []
+    files:
+      - name: scripts/session-tracker.sh
+        content: |
+          #!/bin/bash
+          # TODO: Implement Stop hook that logs session duration
+          exit 0
+        language: bash
+        readonly: false
+    task: "Write a Stop hook that logs the session end time and token usage to .local/session-log.json. Each entry should include: timestamp, STOP_REASON, and parsed input/output token counts from TOKEN_USAGE. Configure it in .claude/settings.json."
+    validations:
+      - label: "Stop hook script exists"
+        check: output-contains
+        pattern: "session-tracker|session-log|STOP_REASON|TOKEN_USAGE"
+      - label: "Hook configured for Stop event"
+        check: output-contains
+        pattern: "Stop|hooks"
+      - label: "JSON logging implemented"
+        check: output-contains
+        pattern: "jq|json|timestamp"
+    hints:
+      - "STOP_REASON and TOKEN_USAGE are in the environment. TOKEN_USAGE is JSON."
+      - "Use jq to parse TOKEN_USAGE and build a log entry. Append to .local/session-log.json as a new line (JSONL format)."
+      - "For timestamp: date -Iseconds or date +%Y-%m-%dT%H:%M:%S"
+    agent_prompts:
+      on_start: "Why does a session tracker belong in a Stop hook rather than PostToolUse? What would happen if you used PostToolUse?"
+      on_complete: "How could you extend this to also record session duration? What would you need to capture at the start of a session?"