From bcdb44c5d317c08683d84c4a5518ac7d8547a516 Mon Sep 17 00:00:00 2001 From: Dragon <52599892+DragonnZhang@users.noreply.github.com> Date: Tue, 7 Jul 2026 06:18:49 +0800 Subject: [PATCH] docs(hooks): document PreToolUse permissionDecision 'ask' behavior (#6411) Co-authored-by: Claude --- docs/users/features/hooks.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/users/features/hooks.md b/docs/users/features/hooks.md index 3c78115a72..8709b22d10 100644 --- a/docs/users/features/hooks.md +++ b/docs/users/features/hooks.md @@ -396,6 +396,12 @@ Hook output supports three categories of fields: - `hookSpecificOutput.updatedInput`: modified tool input parameters to use instead of original - `hookSpecificOutput.additionalContext`: additional context information +The `permissionDecision` value controls whether the tool runs: + +- `"allow"` — run the tool without the usual approval prompt. +- `"deny"` — block the tool; it does not execute and an error is returned to the model. +- `"ask"` — pause and ask the user to confirm the tool call in the TUI before it runs. Confirming runs the tool once; declining cancels it. In contexts that cannot prompt for confirmation — headless (`--prompt`) runs and background subagents — `"ask"` falls back to `"deny"`. + **Note**: While standard hook output fields like `decision` and `reason` are technically supported by the underlying class, the official interface expects the `hookSpecificOutput` with `permissionDecision` and `permissionDecisionReason`. **Example Output**: