[benbrandt]

Summary

• Advertise and implement standard, unstable systemPrompt support on ACP v1 and v2 session lifecycle requests. Support text-only append mode; reject override, custom modes, and non-text content before lifecycle side effects.
• Preserve AIR's existing instruction baseline. Append standard client text after AIR customInstructions when present, otherwise after configured Codex developer instructions. Leave Codex base instructions and workspace context intact. Requests without standard prompts retain legacy AIR behavior.
• Carry known instruction state through new/resume/load/fork and through provider restarts/app-server recovery. Omitted/null prompts preserve known instructions while the adapter session remains open; clients should resend after closing/restarting the adapter.
• For changed prompts on an idle, persisted thread, detach/reload under the same ID. Verify an actual unload instead of acknowledging an override Codex silently ignored. Check persisted history (a planned rollout path alone is not proof), block racing inputs/config changes, and restore delivery after rejected/failed changes.
• Do not interrupt foreground work or background terminals, force compaction, restart the global app-server, rewrite history, or repurpose collaboration-mode instructions. Standard subagent support remains separate; the AIR subagent contract is unchanged.

Timing and limits

New sessions apply the prompt on their first turn. Changed prompts on existing sessions and forks become model-visible at the next compaction. Reload updates configuration but retained history still contains the previous developer message until context is rebuilt. This is the deferral allowed by the ACP system-prompt specification, similar to the Claude adapter's documented behavior.

Changed prompts on busy sessions, sessions with background terminals, or live sessions without a saved rollout are explicitly rejected with -32602; finish the work and retry, or create a new session for immediate instructions. A runtime that keeps the existing thread loaded also produces an error rather than false success. Busy-session changes are not automatically queued in this package.

Validation

• npm run typecheck — passed, including examples.
• npm test — 1,859 passed, 36 skipped; includes 38 system-prompt wire tests across v1/v2, concurrency guards, runtime refusal, restoration after failure, empty-content clearing, and provider-restart preservation.
• npm run build — passed.
• npm run test:integration — 7 passed against real Codex app-server with a local mock model. New v1/v2 tests inspect actual developer messages for new, changed resume, fork, full-history replay, and compaction, preserving AIR and configured baselines and keeping rejected unused sessions usable.
• npm run codex-test live-model legacy smoke — passed.
• Additional live-model ACP smoke: standard system prompt specified system-prompt-live-ok, user prompt was Greet me., and the model returned exactly the system-prompt marker with end_turn.
• git diff --check — passed.
• Verified all 33 AIR scenario snapshot changes add only the systemPrompt capability. The pinned compatibility baselines are unchanged; their allowed feature-delta rule accounts for the new advertisement.

The full live-model E2E suite was not run. Specification checked at agent-client-protocol@4034a8cbc99bc48fd4579f70a3407b07907e0eb6; backend behavior verified on Codex 0.160.1.

Follow-up observed during testing

The existing /compact command can answer on compaction-item completion shortly before Codex releases the underlying turn. The new integration fixture waits for the separate runtime turn completion before issuing the next probe. Changing that command's completion semantics is outside this package.