Breaking change: --headless --stdio removed without deprecation, breaks copilot-sdk and all downstream integrations

[darthmolen]

Describe the bug

The Copilot CLI removed support for --headless --stdio flags (the programmatic interface used by @github/copilot-sdk) without any deprecation period or migration path. The CLI now exits with code 1 when these flags are passed.

This is a silent breaking change — the CLI auto-updates itself, so every copilot-sdk user who runs their application discovers it's broken at runtime. There was no deprecation warning, no migration guide, and no changelog entry announcing the removal.

Impact

• Every version of @github/copilot-sdk (0.1.0 through 0.1.26-preview.0) is broken. The SDK internally spawns copilot --headless --stdio — there is no way to override this.
• Every downstream application using the SDK is broken: VS Code extensions, CLI wrappers, custom integrations.
• The only workaround is pinning the CLI binary to v0.0.403 and passing --no-auto-update, which defeats the purpose of having an SDK.
• The SDK team closed the ACP support request as "wontfix" (Feature Request: Support ACP (Agent Client Protocol) Compatible CLIs copilot-sdk#377), stating the SDK is specifically for the Copilot CLI. But the Copilot CLI broke the Copilot SDK.

Reproduction

# Install latest CLI (auto-updates to v0.0.410+)
copilot --version  # v0.0.410 or later

# This is what copilot-sdk does internally:
copilot --headless --stdio --log-level error
# Result: exits code 1, "Connection is closed."

# The replacement (ACP) works, but the SDK doesn't use it:
copilot --acp --stdio
# Result: works, accepts NDJSON JSON-RPC

Affected version

v0.0.410+ (verified on v0.0.413, v0.0.394)

Expected behavior

Either:

1. Keep --headless --stdio working alongside --acp --stdio (backward compatibility)
2. Deprecation period: CLI warns "headless mode deprecated, use --acp --stdio" for N versions before removing
3. Coordinate with SDK team: Update copilot-sdk to use --acp --stdio before removing --headless

Additional context

• Proven via diagnostic harness: the CLI rejects --headless and exits code 1, while --acp --stdio works correctly with full JSON-RPC round-trips (initialize, session/new, session/prompt, streaming, cancel, permissions).
• The ACP protocol works well — the issue is purely the unannounced removal of the old interface.
• Related: Feature Request: Support ACP (Agent Client Protocol) Compatible CLIs copilot-sdk#377 (closed wontfix), Docs need to show a minimum CLI version required copilot-sdk#137 (no minimum CLI version docs)

[darthmolen]

Update: Correcting our findings

After deeper investigation, several claims in this issue are incorrect. We're correcting the record:

What we got wrong:

• --headless --stdio was not removed. We tested CLI versions 0.0.403 through 0.0.414 — the flag is accepted on all of them. The "exits code 1" error we observed was likely caused by the runtime version delegation (see below), not flag removal.
• The original reproduction (copilot --headless --stdio → "Connection is closed") was misleading. The flag is accepted; the failure had a different root cause.

What's actually happening:
The Copilot CLI binary is a thin launcher that downloads newer versions to ~/.copilot/pkg/universal/ and delegates execution at runtime. Without --no-auto-update, a binary installed as v0.0.403 will silently run as v0.0.410 (or whatever the latest downloaded version is). The @github/copilot-sdk prior to v0.1.23 did not pass --no-auto-update, so integrators experienced unexpected version drift.

The SDK team fixed this in PR github/copilot-sdk#392 (Feb 6), shipping in SDK v0.1.23+. Integrators on older SDK versions can work around it by passing cliArgs: ['--no-auto-update'] to CopilotClient.

What remains valid:

• The auto-update behavior is disruptive for SDK integrators who don't know about --no-auto-update
• There's no documentation of this launcher/delegation behavior
• The --no-auto-update flag isn't mentioned in the SDK docs

We apologize for the inaccurate original report. The remaining concern (undocumented auto-update delegation) is better tracked as a documentation request.

We're happy to close this issue if the team prefers.