[DOCS] Headless and Agent SDK docs omit session auto-title background request behavior

Status Fixed / completed

Maintainer reply ✓ Yes — bcherny

Activity 6 comments · opened Apr 16, 2026 · closed Aug 17, 2026

💡 Likely answer: A maintainer (bcherny, collaborator) responded on this thread — see the highlighted reply below.

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:

Headless / Agent SDK sessions may generate a session title/summary automatically for session metadata such as SDKSessionInfo.summary
This auto-title behavior can trigger a separate background Haiku-class request
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 and CLAUDE_CODE_DISABLE_TERMINAL_TITLE=1 suppress that non-essential title-generation request
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:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/headless | Primary page for claude -p / programmatic runs |
| https://code.claude.com/docs/en/agent-sdk/sessions | Session lifecycle, resume, and session metadata guidance |
| https://code.claude.com/docs/en/agent-sdk/typescript | SDKSessionInfo.summary and customTitle reference |
| https://code.claude.com/docs/en/agent-sdk/python | SDKSessionInfo.summary and custom_title reference |
| https://code.claude.com/docs/en/env-vars | Documents CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC and CLAUDE_CODE_DISABLE_TERMINAL_TITLE |

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

View original on GitHub ↗

5 Comments

coygeek · 4 months ago

Still relevant as of 2026-05-18. This documentation gap has not been addressed in the docs yet.

coygeek · 4 months ago

Verified against the latest docs; this still appears unresolved.

coygeek · 3 months ago

Verified against the latest docs; this still appears unresolved.

jbeda · 3 months ago

Empirically confirmed and quantified this via mitmproxy wire capture + local transcript comparison (write-up: https://github.com/stacklok/claude-plugins/issues/270), and it goes a bit beyond what's described here — filing this in case it's useful for scoping the doc fix (or points to a second bug):

This isn't limited to headless/SDK sessions. We reproduced it in a normal interactive terminal session (claude, no -p, no SDK) with a minimal single-prompt test (one WebFetch call). The hidden request still fires.

It's not just "an extra Haiku request." Wire capture shows two extra calls beyond the visible conversation:

A small Haiku call (~535 input tokens, its own ~1.5k-char system prompt) — matches the "extra Haiku request" description here.
A much larger claude-sonnet-5 call — full agent system prompt (28k+ chars), full tool list, and critically, it re-reads the entire accumulated prompt cache up to that point (in our test: ~56k cache-read tokens on a session whose total cache was only ~56k at that point — i.e. it reads everything). This call has no corresponding entry in the local session JSONL at all (or, if a custom title is already set via /rename, literally zero record of any kind) — Claude Code discards its message/usage data when persisting the transcript, which is why tools like /usage-vs-local-transcript reconciliation break.

CLAUDE_CODE_DISABLE_TERMINAL_TITLE=1 does suppress both, confirmed by direct /usage comparison (cache-read dropped from ~164k to ~107.5k in our isolated test, matching exactly what the visible conversation alone would cost). So the flag works as a full fix, at least for the interactive-terminal case — the gap here is purely that the docs (and apparently the underlying mental model in the changelog note) undersell where this fires and which model absorbs the larger part of the cost.

Happy to share the mitmproxy addon script if it'd help verify against current builds.

bcherny collaborator · 1 month ago

This is now documented: in Agent SDK and claude -p sessions, setting CLAUDE_CODE_DISABLE_TERMINAL_TITLE=1 also skips the background small-model request that generates the session title. See the variable's row at https://code.claude.com/docs/en/env-vars. Closing as documented.

🤖 Generated with Claude Code

Showing cached comments. Read the full discussion on GitHub ↗