[DOCS] Agent SDK user-input guide omits persistent localSettings Bash approval flow

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://code.claude.com/docs/en/agent-sdk/user-input

Section/Topic

"Handle tool approval requests" and "Respond to tool requests"

Current Documentation

The user-input guide currently says:

options (TS) / context (Python) | Additional context including optional suggestions (proposed PermissionUpdate entries to avoid re-prompting) and a cancellation signal.

And the response table immediately below says:

| Allow | PermissionResultAllow(updated_input=...) | { behavior: "allow", updatedInput } | | Deny | PermissionResultDeny(message=...) | { behavior: "deny", message } |

Meanwhile, the SDK references document the missing persistence details:

type PermissionResult = | { behavior: "allow"; updatedInput?: Record<string, unknown>; updatedPermissions?: PermissionUpdate[]; }

type PermissionUpdateDestination = | "userSettings" | "projectSettings" | "localSettings" // Gitignored local settings | "session"

And the hooks reference shows the concrete "Always allow" destination for permission suggestions:

permission_suggestions array contains the "always allow" options the user would normally see in the permission dialog. "permission_suggestions": [ { "type": "addRules", "rules": [{ "toolName": "Bash", "ruleContent": "rm -rf node_modules" }], "behavior": "allow", "destination": "localSettings" } ]

What's Wrong or Missing?

A. The guide understates what SDK hosts receive for Bash permission prompts

As of v2.1.128, SDK hosts can receive a persistent localSettings suggestion for Bash permission prompts, but the user-input guide describes suggestions only as a generic way to "avoid re-prompting." It does not explain that this suggestion can correspond to the UI's "Always allow" action and persist to .claude/settings.local.json.

B. The guide's allow-response examples omit the persistence path entirely

The page documents only updated_input / updatedInput in approval responses, even though the SDK types also support updated_permissions / updatedPermissions. That leaves SDK integrators without a clear documented path for honoring a user's persistent Bash approval choice.

Suggested Improvement

Update the user-input guide to explain that:

1. suggestions / permission_suggestions may include a persistent Bash approval entry with destination: "localSettings".
2. Surfacing that option to the user is equivalent to offering "Always allow."
3. Returning that entry via updatedPermissions / updated_permissions writes the rule to .claude/settings.local.json.

Add a short TypeScript and Python example after the current approval examples, for example:

TypeScript:

return {
behavior: "allow",
updatedInput: input,
updatedPermissions: options.suggestions
};

Python:

return PermissionResultAllow(
updated_input=input_data,
updated_permissions=context.get("suggestions")
)

If the exact Python context access pattern differs, the guide should still show the supported way to echo the persistent suggestion back so hosts can implement "Always allow" correctly for Bash prompts.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/agent-sdk/user-input | 35, 60, 206-225 | Mentions generic suggestions, but approval responses only show updatedInput |
| https://code.claude.com/docs/en/agent-sdk/typescript | 644, 671, 2258-2262 | Reference documents suggestions, updatedPermissions, and localSettings destination |
| https://code.claude.com/docs/en/hooks | 1244-1245, 1258-1264, 1314-1319, 1321 | Shows that permission suggestions map to "always allow" behavior and can target .claude/settings.local.json |
| https://platform.claude.com/docs/en/agent-sdk/user-input | 31, 56, 204-223 | Platform mirror has the same omission in the SDK host guidance |
| https://platform.claude.com/docs/en/agent-sdk/typescript | 1113-1117, 2088-2092 | Platform reference also documents permission_suggestions and localSettings |

Total scope: 5 pages affected

This gap appears after the v2.1.128 change that SDK hosts now receive a persistent localSettings suggestion for Bash permission prompts.