feat: update usage recommendations across multiple workflow commands to require user confirmation and improve clarity

2026-02-13 02:41:50 +08:00 · 2026-02-01 22:04:26 +08:00
parent 5fb910610a
commit 7dcc0a1c05
70 changed files with 4420 additions and 1108 deletions
--- a/.claude/docs/HOOKS_OFFICIAL_GUIDE.md
+++ b/.claude/docs/HOOKS_OFFICIAL_GUIDE.md
@@ -0,0 +1,124 @@
+# Claude Code Hooks - Official Guide
+
+> Complete official documentation from https://code.claude.com/docs/en/hooks-guide
+
+## Automate workflows with hooks
+
+Run shell commands automatically when Claude Code edits files, finishes tasks, or needs input. Format code, send notifications, validate commands, and enforce project rules.
+
+### Hook lifecycle
+
+Hooks fire at specific points during a Claude Code session. The official hook events are:
+
+| Event                | When it fires                                        |
+| :------------------- | :--------------------------------------------------- |
+| `SessionStart`       | When a session begins or resumes                     |
+| `UserPromptSubmit`   | When you submit a prompt, before Claude processes it |
+| `PreToolUse`         | Before a tool call executes. Can block it            |
+| `PermissionRequest`  | When a permission dialog appears                     |
+| `PostToolUse`        | After a tool call succeeds                           |
+| `PostToolUseFailure` | After a tool call fails                              |
+| `Notification`       | When Claude Code sends a notification                |
+| `SubagentStart`      | When a subagent is spawned                           |
+| `SubagentStop`       | When a subagent finishes                             |
+| `Stop`               | When Claude finishes responding                      |
+| `PreCompact`         | Before context compaction                            |
+| `SessionEnd`         | When a session terminates                            |
+
+### Hook handler types
+
+There are three types of hook handlers:
+
+1. **Command hooks** (`type: "command"`): Run a shell command
+2. **Prompt hooks** (`type: "prompt"`): Use Claude model for single-turn evaluation
+3. **Agent hooks** (`type: "agent"`): Spawn subagent with tool access
+
+### Configuration structure
+
+```json
+{
+  "hooks": {
+    "EventName": [
+      {
+        "matcher": "ToolName|AnotherTool",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash /path/to/script.sh",
+            "timeout": 600,
+            "async": false
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### Hook input (stdin)
+
+Common fields for all events:
+- `session_id`: Current session ID
+- `transcript_path`: Path to conversation JSON
+- `cwd`: Current working directory
+- `permission_mode`: Current permission mode
+- `hook_event_name`: Name of the event that fired
+
+Event-specific fields depend on the event type.
+
+### Hook output (exit codes and stdout)
+
+- **Exit 0**: Success. Parse stdout for JSON decision
+- **Exit 2**: Blocking error. stderr text becomes Claude's feedback
+- **Any other code**: Non-blocking error
+
+### Tool matchers
+
+Available for: `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`
+
+Tool names:
+- Built-in: `Bash`, `Edit`, `Write`, `Read`, `Glob`, `Grep`, `Task`, `WebFetch`, `WebSearch`
+- MCP tools: `mcp__<server>__<tool>` (e.g., `mcp__github__search_repositories`)
+
+### Event matchers
+
+Different events match on different fields:
+- `SessionStart`: `startup`, `resume`, `clear`, `compact`
+- `SessionEnd`: `clear`, `logout`, `prompt_input_exit`, `bypass_permissions_disabled`, `other`
+- `Notification`: `permission_prompt`, `idle_prompt`, `auth_success`, `elicitation_dialog`
+- `SubagentStart`/`SubagentStop`: agent type (e.g., `Bash`, `Explore`, `Plan`)
+- `PreCompact`: `manual`, `auto`
+
+### Hook configuration locations
+
+| Location | Scope |
+|----------|-------|
+| `~/.claude/settings.json` | All your projects |
+| `.claude/settings.json` | Single project |
+| `.claude/settings.local.json` | Single project (gitignored) |
+| Plugin `hooks/hooks.json` | When plugin enabled |
+| Skill/Agent frontmatter | While component active |
+
+### Best practices
+
+✅ **DO:**
+- Use command hooks for deterministic actions
+- Use prompt hooks for judgment-based decisions
+- Use agent hooks when verification requires file inspection
+- Quote all shell variables: `"$VAR"`
+- Use absolute paths with `$CLAUDE_PROJECT_DIR`
+- Set appropriate timeouts
+- Use async hooks for long-running operations
+- Keep hooks fast (< 10 seconds by default)
+
+❌ **DON'T:**
+- Trust input data blindly
+- Use relative paths
+- Put sensitive data in hook output
+- Create infinite loops in Stop hooks
+- Run blocking operations without async
+
+---
+
+See https://code.claude.com/docs/en/hooks-guide for complete guide
+See https://code.claude.com/docs/en/hooks for reference documentation