[DOCS] Agent SDK: document the Fable usage-credits consent dialog for SDK hosts

Open Beginner friendly
#110,914 0 comments 0 reactions 0 assignees View on GitHub

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

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

area:agent-sdk area:docs documentation enhancement
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 dialogExpiry deadline, Claude Code ends the turn without sending the request.

In non-interactive mode with the -p flag, 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:

  1. its dialogKind, the value a host lists in supportedDialogKinds to receive it;
  2. its payload fields, and what each one means;
  3. the result a host returns for "continue on Fable" and for "switch to the default model", and whether a dismissal is cancelled;
  4. 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 canUseTool and AskUserQuestion. Give its dialogKind, 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

Open in Codespaces

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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from anthropics/claude-code

All issues in anthropics/claude-code

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.