docs(cli): add hooks guide for event interception

docs/cli/hooks.mdx

@@ -0,0 +1,183 @@
+---
+title: "Hooks"
+---
+
+Continue CLI supports Claude Code-compatible hooks so you can run custom logic before and after key events (tool calls, prompts, session lifecycle, and more).
+
+Hooks are configured in settings JSON files and run automatically when matching events fire.
+
+## Where to configure hooks
+
+`cn` loads hooks from the same paths as Claude Code, then merges them:
+
+1. `~/.claude/settings.json`
+2. `~/.continue/settings.json`
+3. `.claude/settings.json`
+4. `.continue/settings.json`
+5. `.claude/settings.local.json`
+6. `.continue/settings.local.json`
+
+Later files have higher precedence, but hooks from all files run.
+
+## Basic shape
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "^Bash$",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "echo 'About to run Bash tool'"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Event types
+
+Continue currently supports the following event names:
+
+- `PreToolUse`
+- `PostToolUse`
+- `PostToolUseFailure`
+- `PermissionRequest`
+- `UserPromptSubmit`
+- `SessionStart`
+- `SessionEnd`
+- `Stop`
+- `Notification`
+- `SubagentStart`
+- `SubagentStop`
+- `PreCompact`
+- `ConfigChange`
+- `TeammateIdle`
+- `TaskCompleted`
+- `WorktreeCreate`
+- `WorktreeRemove`
+
+## Matcher behavior
+
+Each event can define one or more matcher groups:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "^(Read|Glob)$",
+        "hooks": [{ "type": "command", "command": "echo read path" }]
+      },
+      {
+        "matcher": "^Bash$",
+        "hooks": [{ "type": "command", "command": "echo shell tool" }]
+      }
+    ]
+  }
+}
+```
+
+- `matcher` is a JavaScript regex string.
+- `"*"`, `""`, or omitted matcher means “match all”.
+- Invalid regexes are ignored (with a warning in logs).
+- Some events do not use matchers and always fire when configured.
+
+## Hook handler types
+
+### Command hooks
+
+Run a shell command and pass hook input JSON to stdin.
+
+```json
+{
+  "type": "command",
+  "command": "node .continue/hooks/pre-tool.js",
+  "timeout": 120,
+  "statusMessage": "Checking tool policy"
+}
+```
+
+Optional fields:
+
+- `async`: if `true`, runs in the background (fire-and-forget)
+- `timeout`: seconds before cancellation (default 600 for command hooks)
+- `statusMessage`: custom spinner message
+
+### HTTP hooks
+
+Send hook input as a JSON POST request.
+
+```json
+{
+  "type": "http",
+  "url": "https://example.com/hooks/pretool",
+  "headers": {
+    "Authorization": "Bearer ${HOOKS_TOKEN}"
+  },
+  "allowedEnvVars": ["HOOKS_TOKEN"],
+  "timeout": 30
+}
+```
+
+Notes:
+
+- Hook input is sent as request body.
+- Non-2xx responses are treated as non-blocking hook errors.
+- `headers` support env interpolation only for names listed in `allowedEnvVars`.
+
+### Prompt and Agent handlers
+
+You can include `prompt` and `agent` handler types in config for schema compatibility, but Continue CLI currently skips them.
+
+## Exit code and blocking semantics
+
+For **command hooks**:
+
+- Exit code `0`: success, continue execution
+- Exit code `2`: block the action (`stderr` becomes block reason)
+- Any other non-zero code: treated as hook failure, does not block by itself
+
+For **JSON hook output** (command or http):
+
+- `{"decision":"block","reason":"..."}` blocks the action
+- `hookSpecificOutput` can provide event-specific controls (for example `permissionDecision` in `PreToolUse`)
+
+## Sync vs async
+
+- Sync hooks are awaited and run in parallel with other sync hooks.
+- Command hooks with `"async": true` are started and not awaited.
+- Async hooks are useful for telemetry or background notifications where you do not want to delay the main action.
+
+## Environment variables for command hooks
+
+Command hooks receive:
+
+- `CONTINUE_PROJECT_DIR`
+- `CLAUDE_PROJECT_DIR`
+
+Both are set to the current project directory so shared hook scripts work across `cn` and Claude Code.
+
+## Disable all hooks
+
+To disable hooks globally for a config file:
+
+```json
+{
+  "disableAllHooks": true
+}
+```
+
+If any loaded settings file sets `disableAllHooks`, hooks are disabled.
+
+## Example use cases
+
+- Block dangerous tool calls (for example deny `Bash` commands matching `rm -rf`)
+- Add context before each user prompt (`UserPromptSubmit`)
+- Forward tool telemetry to internal observability services via HTTP hooks
+- Trigger notifications on session lifecycle events
+- Enforce org policies on permission requests

docs/cli/quickstart.mdx

@@ -86,3 +86,9 @@ If you don't want to use Continue, you can use an Anthropic API key directly. On
 | `--verbose` | Enable verbose logging |
 
 Run `cn --help` for the full list.
+
+## More CLI docs
+
+- **[Configuration](/cli/configuration)** — model/config resolution and runtime config flags.
+- **[Hooks](/cli/hooks)** — intercept CLI events with command/HTTP handlers.
+- **[Tool permissions](/cli/tool-permissions)** — tune permission behavior for tools.

docs/cli/tool-permissions.mdx

@@ -12,7 +12,23 @@ Every tool has one of three permission levels:
 
 ## Defaults
 
-Read-only tools (`Read`, `List`, `Search`, `Fetch`, `Diff`) default to `allow`. Write tools (`Edit`, `MultiEdit`, `Write`) and `Bash` default to `ask`. In [headless mode](/cli/headless-mode), `ask` tools are excluded since there's no one to approve them.
+Read-only tools (`Read`, `List`, `Search`, `Fetch`, `Diff`, `AskQuestion`, `Checklist`, `Status`, `CheckBackgroundJob`, `ReportFailure`, `UploadArtifact`) default to `allow`. Write tools (`Edit`, `MultiEdit`, `Write`) and `Bash` default to `ask`. In [headless mode](/cli/headless-mode), `ask` tools are excluded since there's no one to approve them.
+
+## AskQuestion tool
+
+`AskQuestion` is a built-in read-only tool that lets the agent pause and ask for clarification before continuing.
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `question` | `string` | Yes | The prompt shown to the user |
+| `options` | `string[]` | Yes | Suggested choices; use an empty array for free-form input |
+| `defaultAnswer` | `string` | No | Used when the user submits without typing a response |
+
+### Permission behavior
+
+`AskQuestion` is `allow` by default in normal, plan, and auto modes. It does not modify files or run commands.
 
 ## Overriding with flags
 

docs/cli/tui-mode.mdx

@@ -49,6 +49,17 @@ cn --resume
 
 This restores the full conversation history, so the agent remembers prior context.
 
+## Interactive questions in TUI mode
+
+The agent can use the `AskQuestion` tool to gather clarifications before it continues. You will see a quiz-style prompt directly in the terminal.
+
+- Use <kbd>↑</kbd>/<kbd>↓</kbd> to highlight an option
+- Press <kbd>Enter</kbd> to submit the highlighted option
+- Start typing to send a custom answer (even when options are shown)
+- If a default answer is provided, pressing <kbd>Enter</kbd> on an empty input submits that default
+
+This is useful when the agent needs decisions like scope, preferences, or environment details before making edits.
+
 ## Tool Permissions
 
 Tools that can modify your system (file writes, terminal commands) prompt for approval before executing. You get three options:
@@ -57,4 +68,4 @@ Tools that can modify your system (file writes, terminal commands) prompt for ap
 - **Continue + don't ask again** — approve and save a policy rule to `~/.continue/permissions.yaml`
 - **No** — reject the call and give the agent new instructions
 
-Read-only tools (`Read`, `List`, `Search`, `Fetch`) run automatically. See [tool permissions](/cli/tool-permissions) for the full policy system.
+Read-only tools (`Read`, `List`, `Search`, `Fetch`, `Diff`, `AskQuestion`) run automatically. See [tool permissions](/cli/tool-permissions) for the full policy system.