Handle approvals and user input changedagent-sdk/user-input
Nearest release: v2.1.280, published an hour after upstream edited the page. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Upstream edited this page at 22 Sep 2026 14:15 UTC, give or take a minute or two: the time comes from Anthropic’s own sitemap rather than from a commit. This site recorded the change at 22 Sep 2026 14:37 UTC.
Upstream edited
Recorded here
Lines+7added
Lines−7removed
From line
60
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits16to this page, all time
The whole hunk
from line 60, old and new numbered
/
from line 60
6060
6161| Argument | Description |
6262| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
63| `toolName` | The name of the tool Claude wants to use (e.g., `"Bash"`, `"Write"`, `"Edit"`) |
63| `toolName` | The name of the tool Claude wants to use (for example, `"Bash"`, `"Write"`, `"Edit"`) |
6464| `input` | The parameters Claude is passing to the tool. Contents vary by tool. |
6565| `options` (TS) / `context` (Python) | Additional context including optional `suggestions` (proposed `PermissionUpdate` entries to avoid re-prompting) and a cancellation signal. In TypeScript, `signal` is an `AbortSignal`; in Python, the signal field is reserved for future use. See [`ToolPermissionContext`](/docs/en/agent-sdk/python#toolpermissioncontext) for Python. |
6666
from line 214
214214Beyond allowing or denying, you can modify the tool's input or provide context that helps Claude adjust its approach:
215215
216216* **Approve**: let the tool execute as Claude requested
217* **Approve with changes**: modify the input before execution (e.g., sanitize paths, add constraints)
217* **Approve with changes**: modify the input before execution (for example, sanitize paths, add constraints)
218218* **Approve and remember**: echo a suggested permission rule back so matching calls skip the prompt next time
219219* **Reject**: block the tool and tell Claude why
220220* **Suggest alternative**: block but guide Claude toward what the user wants instead
from line 500
500500 <Step title="Return answers to Claude">
501501 Build the `answers` object as a record where each key is the `question` text and each value is the selected option's `label`:
502502
503 | From the question object | Use as |
504 | ------------------------------------------------------------ | ------ |
505 | `question` field (e.g., `"How should I format the output?"`) | Key |
506 | Selected option's `label` field (e.g., `"Summary"`) | Value |
503 | From the question object | Use as |
504 | ------------------------------------------------------------------- | ------ |
505 | `question` field (for example, `"How should I format the output?"`) | Key |
506 | Selected option's `label` field (for example, `"Summary"`) | Value |
507507
508508 For multi-select questions, pass an array of labels or join them with `", "`. If you [support free-text input](#support-free-text-input), use the user's custom text as the value.
509509
from line 647
647647
6486481. **Route the request**: The `canUseTool` callback checks if the tool name is `"AskUserQuestion"` and routes to a dedicated handler
6496492. **Display questions**: The handler loops through the `questions` array and prints each question with numbered options
6503. **Collect input**: The user can enter a number to select an option, or type free text directly (e.g., "jquery", "i don't know")
6503. **Collect input**: The user can enter a number to select an option, or type free text directly (for example, "jquery", "i don't know")
6516514. **Map answers**: The code checks if input is numeric (uses the option's label) or free text (uses the text directly)
6526525. **Return to Claude**: The response includes both the original `questions` array and the `answers` mapping
653653
No line in this hunk matches that.