feat: support system prompt append

[Shuryne]

Summary

• advertise a versioned system prompt append extension during ACP initialization
• validate client-provided append metadata and map it to Codex developer instructions without replacing base instructions
• apply explicit append metadata across new, resume, load, and fork lifecycle paths while omitting absent values
• document the extension and add a real-Codex test-runner option

Validation

• npm run typecheck
• npm run build
• 20 targeted system-prompt, initialization, and fork tests passed
• 495 additional tests passed and 26 were skipped when excluding the existing MCP config integration file
• real Codex rollout verified the appended text is emitted in a separate developer-role message alongside the existing base, skills, and permission instructions

Local environment note

The repository-pinned Codex 0.148 platform executable was not runnable on this macOS host, so real-Codex verification used the installed Codex 0.151 binary. Under that substitution, three existing MCP config merge tests exited during app-server initialization; all other tests passed, and this change does not touch MCP configuration.

[Copilot]

Pull request overview

Adds a provider-neutral “system prompt append” capability to ACP session lifecycle flows, validating client metadata and mapping the appended text onto Codex developerInstructions so the base/system prompt remains unchanged.

Changes:

• Introduces a versioned _meta.systemPrompt capability advertisement during ACP initialize.
• Parses/validates _meta.systemPrompt.append and applies it to threadStart, threadResume (resume/load), and threadFork while omitting absent/blank values.
• Documents the extension and adds a CLI option to exercise it in the real-Codex test runner script.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/SystemPrompt.ts	Adds the extension capability constants and the _meta.systemPrompt.append parser/validator.
src/SessionFork.ts	Passes validated append text through to threadFork as developerInstructions.
src/CodexAcpServer.ts	Advertises the capability in initialize and validates metadata early on session lifecycle routes.
src/CodexAcpClient.ts	Applies validated append text to Codex thread start/resume calls via developerInstructions.
src/tests/CodexACPAgent/system-prompt.test.ts	Adds coverage for parsing/validation and propagation to Codex calls across lifecycle routes.
src/tests/CodexACPAgent/initialize.test.ts	Asserts the new capability is included in the initialize response _meta.
README.md	Documents the new extension at the top-level feature list.
docs/system-prompt-extension.md	Adds detailed extension documentation and usage examples.
.claude/skills/run-codex/scripts/run-codex-test.ts	Adds --system-prompt-append flag and wires it into session creation for real-Codex runs.

Suppressed comments (1)

.claude/skills/run-codex/scripts/run-codex-test.ts:165

• The systemPromptAppend && {...} spread includes _meta for whitespace-only values, but the server treats blank/whitespace append text as unspecified. Using a trim-based condition avoids sending a no-op _meta payload while still preserving the original (untrimmed) text when present.

            ...(systemPromptAppend && {
                _meta: {systemPrompt: {append: systemPromptAppend}},
            }),

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[salman1993]

it'd be great to allow overriding or appending to the codex system prompt. claude-agent-acp allows this now: agentclientprotocol/claude-agent-acp#91 @nikita-ashihmin

[salman1993]

🤖 automated review:

• Support replacement via baseInstructions, alongside append via developerInstructions.
• Define load/resume/fork behavior, noting that Codex ignores overrides when resuming a running thread.
• Avoid silently replacing existing developer_instructions.
• Add a real-Codex behavior test for both modes.

The V2 API already supports both fields, so these should be incremental changes. see comments in this issue - #215