docs(cli): add hooks guide for event interception

[siewcapital]

Summary

• add a dedicated docs/cli/hooks.mdx guide for the CLI hooks system
• document config file locations for both .continue and .claude settings
• cover supported event types, matcher behavior, command/http handlers, and blocking semantics
• include sync vs async execution notes and command-hook environment variables
• add a "More CLI docs" section in quickstart linking to hooks/configuration/permissions pages

Why

The hooks feature introduced in #11029 is tier-1 functionality, but there was no end-to-end user documentation for setup and behavior.

Validation

• Verified docs links and markdown structure locally
• npm --prefix docs run build currently fails in this environment because mintlify is not installed (sh: mintlify: command not found)

Closes #11152

---

Summary by cubic

Adds a dedicated CLI Hooks guide and updates quickstart, tool permissions, and TUI docs (including the AskQuestion tool). This delivers end-to-end docs for the hooks system and meets the requirements of #11152.

• New Features
  • Added docs/cli/hooks.mdx: config file precedence (.claude/.continue), supported events, regex matchers, command/HTTP handlers, exit codes and blocking, sync vs async, env vars, disable-all, examples.
  • Updated quickstart with “More CLI docs” links (configuration, hooks, tool permissions).
  • Expanded tool-permissions: broader read-only defaults and full AskQuestion parameters and behavior.
  • Improved TUI docs: how AskQuestion prompts work and updated read-only tools list.

^{Written for commit f3967ac. Summary will update on new commits.}

[github-actions]

Thank you for your submission, we really appreciate it. Like many open-source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution. You can sign the CLA by just posting a Pull Request Comment same as the below format.

---

I have read the CLA Document and I hereby sign the CLA

---

_{You can retrigger this bot by commenting recheck in this Pull Request. Posted by the CLA Assistant Lite bot.}

[cubic-dev-ai]

2 issues found across 4 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="docs/cli/hooks.mdx">

<violation number="1" location="docs/cli/hooks.mdx:152">
P2: Docs overstate sync hook awaiting semantics; `SessionStart` is mode-dependent (non-blocking in interactive startup, awaited in headless mode).</violation>
</file>

<file name="docs/cli/tool-permissions.mdx">

<violation number="1" location="docs/cli/tool-permissions.mdx:31">
P2: Docs introduce ambiguous headless behavior for `AskQuestion`: it is documented as default `allow` and user-interactive, but headless docs only exclude `ask` tools and do not define what happens for this prompting tool.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

P2: Docs overstate sync hook awaiting semantics; SessionStart is mode-dependent (non-blocking in interactive startup, awaited in headless mode).

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At docs/cli/hooks.mdx, line 152:

<comment>Docs overstate sync hook awaiting semantics; `SessionStart` is mode-dependent (non-blocking in interactive startup, awaited in headless mode).</comment>

<file context>
@@ -0,0 +1,183 @@
+
+## 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.
</file context>

[cubic-dev-ai]

P2: Docs introduce ambiguous headless behavior for AskQuestion: it is documented as default allow and user-interactive, but headless docs only exclude ask tools and do not define what happens for this prompting tool.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At docs/cli/tool-permissions.mdx, line 31:

<comment>Docs introduce ambiguous headless behavior for `AskQuestion`: it is documented as default `allow` and user-interactive, but headless docs only exclude `ask` tools and do not define what happens for this prompting tool.</comment>

<file context>
@@ -12,7 +12,23 @@ Every tool has one of three permission levels:
+
+### Permission behavior
+
+`AskQuestion` is `allow` by default in normal, plan, and auto modes. It does not modify files or run commands.
 
 ## Overriding with flags
</file context>