claude-code - 💡(How to fix) Fix [DOCS] Headless and Agent SDK docs omit session auto-title background request behavior [1 participants]

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/headless

Section/Topic

Programmatic sessions / Agent SDK session metadata and title generation

Current Documentation

The programmatic-session docs describe headless and SDK usage, but they do not explain that headless/SDK sessions can auto-generate a session title/summary with a background model request:

The Agent SDK gives you the same tools, agent loop, and context management that power Claude Code. It's available as a CLI for scripts and CI/CD, or as Python and TypeScript packages for full programmatic control.

This page covers using the Agent SDK via the CLI (claude -p).

The SDK references expose a generated session summary field but do not explain when or how it is produced:

summary | string | Display title: custom title, auto-generated summary, or first prompt

summary | str | Display title: custom title, auto-generated summary, or first prompt

The environment variable reference documents the disable flags separately, but not their interaction with headless/SDK session auto-titling:

CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC | Equivalent of setting DISABLE_AUTOUPDATER, DISABLE_FEEDBACK_COMMAND, DISABLE_ERROR_REPORTING, and DISABLE_TELEMETRY

CLAUDE_CODE_DISABLE_TERMINAL_TITLE | Set to 1 to disable automatic terminal title updates based on conversation context

What's Wrong or Missing?

Changelog v2.1.110 says:

Fixed headless/SDK session auto-title firing an extra Haiku request when CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC or CLAUDE_CODE_DISABLE_TERMINAL_TITLE is set

That exposes user-visible behavior that the docs do not currently explain:

A. Headless and SDK docs never say that programmatic sessions may auto-generate a session title/summary

The current pages mention summary as an "auto-generated summary," but they do not explain that this may require a separate background Haiku request in headless/SDK usage.

B. The disable flags are not documented as controls for this background request

Users who set CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 specifically to avoid extra non-essential requests, or CLAUDE_CODE_DISABLE_TERMINAL_TITLE=1 to suppress title generation, are not told that these settings affect session auto-title generation in headless/SDK runs.

C. Cost and traffic expectations are unclear for automation users

For scripts, CI, and SDK apps, an extra model request matters for cost predictability, traffic minimization, and debugging. The docs should state when this request happens and what summary/title behavior users should expect when it is disabled.

Suggested Improvement

Add a short note to the programmatic-session docs and SDK session docs explaining that:

1. Headless / Agent SDK sessions may generate a session title/summary automatically for session metadata such as SDKSessionInfo.summary
2. This auto-title behavior can trigger a separate background Haiku-class request
3. CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 and CLAUDE_CODE_DISABLE_TERMINAL_TITLE=1 suppress that non-essential title-generation request
4. When auto-title generation is disabled or unavailable, session listings fall back to the existing documented alternatives (customTitle / custom_title or the first prompt)

Suggested placement:

• Run Claude Code programmatically near session metadata / JSON output
• Work with sessions near listSessions() / list_sessions() guidance
• Environment variables entries for both disable flags, with cross-links back to headless/SDK session docs

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 5 pages affected

Source: Changelog v2.1.110

Exact changelog entry:

Fixed headless/SDK session auto-title firing an extra Haiku request when CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC or CLAUDE_CODE_DISABLE_TERMINAL_TITLE is set