[DOCS] Agent SDK: document the Fable usage-credits consent dialog for SDK hosts
Nobody has claimed this yet.
Assessment
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Newbie friendliness
- 66/100
- Issue type
- Documentation
- Clarity
- Clearly specified
- Activity status
- Active
- Tech stack
- typescript
- Domain
- developer-experience, documentation
Research direction
Start with the Agent SDK declarations for request_user_dialog, supportedDialogKinds, UserDialogRequest, and UserDialogResult, then read the two documentation pages named in the issue. Document this dialog's kind, payload, outcomes, version stability, and the warning for hosts that do not handle it. Done when a host developer can identify the request and return the correct response from the published documentation.
Written by the indexing model from the issue text.
Description
Documentation Type
Missing documentation (feature not documented)
Documentation Location
https://code.claude.com/docs/en/agent-sdk/user-input and https://code.claude.com/docs/en/model-config#fable-and-usage-credits
Section/Topic
Fable usage-credits consent in Agent SDK hosts
Current Documentation
"Model configuration › Fable and usage credits" describes how the prompt behaves:
In interactive sessions, Claude Code can show a Fable usage-credits consent prompt. You can continue on Fable using usage credits or switch to your default model.
In a session another application hosts through the Agent SDK, whether the prompt appears is up to that application. If it appears and nobody answers before the same
dialogExpirydeadline, Claude Code ends the turn without sending the request.
In non-interactive mode with the
-pflag, and in an Agent SDK application that doesn't show the prompt, Claude Code never asks for consent. When a Fable request there would bill to usage credits, Claude Code bills it without asking.
"Handle approvals and user input" covers canUseTool and AskUserQuestion, but not this prompt.
What's Wrong or Missing?
What a host needs in order to show the prompt isn't documented.
The published SDK type declarations (@anthropic-ai/claude-agent-sdk 0.3.327) define the general envelope: request_user_dialog, the supportedDialogKinds option, UserDialogRequest with a dialogKind and a payload whose "shape is defined per dialogKind", and UserDialogResult (completed with a result, or cancelled).
For this prompt, nothing public gives:
- its
dialogKind, the value a host lists insupportedDialogKindsto receive it; - its
payloadfields, and what each one means; - the
resulta host returns for "continue on Fable" and for "switch to the default model", and whether a dismissal iscancelled; - whether this kind's payload and result stay stable across Claude Code versions. The types say new kinds may be added without a protocol bump, but not how a change to an existing kind is signalled.
Suggested Improvement
- Add the usage-credits consent dialog to "Handle approvals and user input", beside
canUseToolandAskUserQuestion. Give itsdialogKind, its payload fields, its results and their effects, with a short example of a request and its answer. - Add a clear warning on that page: an SDK host that doesn't list this dialog lets Fable requests bill to usage credits without asking the user. Hosts built for other people should handle it.
- Say whether an existing dialog kind's payload and result are stable, or how a change to them is signalled.
Impact
High - Prevents users from using a feature
Additional Context
We host Claude Code sessions headless through the Agent SDK's stream-json protocol (Claude Code 2.1.311). Our host won't answer the consent question on anyone's behalf: until this dialog is documented, it offers only stopping the turn or switching to the default model.
Related: #104015, where the same consent can't be given from Claude Code on the web.
- Dominant language
- TypeScript
- Stars
- 156k
- Forks
- 25k
- Avg merge
- 12h 27m
- Merged PRs (30d)
- 4
Getting set up
Starts the project's dev container in your browser, under your own GitHub account.
- No Dockerfile or Docker Compose file
- No pull request template
- No contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from anthropics/claude-code
-
area:tui bug has repro platform:linux regression
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
anthropics/claude-code#110876 ·
-
area:desktop area:ui bug platform:macos
Difficulty 2/5 1-3 hours Newbie friendliness 61/100
anthropics/claude-code#110835 ·
-
area:ui bug platform:vscode platform:windows
Difficulty 2/5 1-3 hours Newbie friendliness 64/100
anthropics/claude-code#110675 ·
-
area:hooks area:plugins area:skills enhancement
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
anthropics/claude-code#110517 ·
-
area:installation enhancement platform:windows
Difficulty 1/5 Under an hour Newbie friendliness 84/100
anthropics/claude-code#110491 ·
All issues in anthropics/claude-code
Similar issues
-
bot:ai-assisted component:platform-js status:untriaged
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
midnightntwrk/platform-js#69 ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
Picolab/pico-engine#668 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
Maintainers usually reply within 1 day
-
ai-driven-qa bug claude Cosmetic
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
Maintainers usually reply within 1 day
-
needs verification
Difficulty 2/5 1-3 hours Newbie friendliness 64/100
Maintainers usually reply within 13 days