Headless runs wait for MCP servers that allow rules and hooks depend on

What

MCP servers are add-ons that give Claude extra tools. In headless runs, meaning -p or the SDK with no interactive screen, Claude Code may start the first turn before every server has connected. It now works out which servers are required and waits for those.

• Required servers are collected from always-allow permission rules set by cliArg, flagSettings, session and command, and from servers used by mcp_tool hooks on events such as PreToolUse, PostToolUse, UserPromptSubmit and PermissionRequest.
• When loading is deferred, these requiredServerNames are not deferred. If any are still pending, Claude Code waits for them up to a separate time limit.
• At the first command the decision is recalculated, and servers that became required since startup cause a fresh wait.
• The wait records a reason, firstTurnHold, with values such as relay, host_wait, host_no_wait, single_shot, ccr_worker, coordinator, no_tool_search, explicit_mcp_config or lifted.
• The wait is timed under a new startup measure, mcp_prewait_ms, and also records pendingRequiredBefore and requiredWaitedMs.

The gates named tengu_headless_mcp_first_turn_join and tengu_headless_mcp_prewait are involved. Nothing has been read about either.

Why

If a script or SDK program relies on a particular MCP server from its first prompt, its first turn is less likely to start before that server's tools exist.