feat: support append-mode ACP system prompts

readme-dev.md

@@ -152,6 +152,30 @@ v1 `modes` field (v2 removed the modes API in favor of config options), and fork
 get an `available_commands_update`, matching v1. There are no new environment/config knobs specific
 to v2; it reuses the runtime environment variables above.
 
+#### Client system prompts
+
+Both ACP versions advertise `systemPrompt: {}`: text-only `append` mode. Override and non-text
+content are rejected with `-32602` before a session is created or a fork is made.
+Text blocks are joined with a blank line and appended to the existing developer-instruction
+baseline: AIR `customInstructions` when supplied, otherwise configured Codex developer instructions.
+Codex's base instructions and workspace context remain intact. Requests without `systemPrompt`
+keep the legacy AIR behavior.
+
+New sessions use the instructions on their first turn. A changed prompt on an idle, persisted
+session detaches and reloads that thread under the same session ID. **The retained model context
+changes at the next compaction**, not immediately after resume; the adapter does not force a
+compaction. Forks with changed instructions have the same deferred behavior.
+
+Changed prompts are rejected while session work or background terminals are running, when a live
+session has no saved rollout yet, or when Codex cannot confirm a reload. Existing work is not
+cancelled. Retry after work finishes, or create a new session for immediate instructions.
+New prompts, steering, and config changes cannot race an instruction reload.
+
+Omitted/null prompts keep the instructions known to the currently open adapter session, including
+through app-server recovery and provider restarts. After closing a session or restarting the
+adapter, clients should resend their prompt on load/resume/fork; without it, Codex's retained
+context and configured defaults determine the instructions.
+
 #### AIR v2 client contract
 
 These are behaviors the AIR (JetBrains) ACP client relies on that aren't obvious from the wire

src/ClientSystemPrompt.ts

@@ -0,0 +1,42 @@
+import {RequestError, type SystemPrompt} from "@agentclientprotocol/sdk/unstable";
+import {airCustomInstructions} from "./AirExtension";
+
+/** Instructions to resend when a thread is reopened, including after an app-server restart. */
+export type SessionInstructions = {
+    text?: string;
+    airInstructions?: string;
+    developerInstructions: string;
+};
+
+export function clientSystemPromptText(value: unknown): string | undefined {
+    if (value == null) return undefined;
+    if (typeof value !== "object" || Array.isArray(value)
+        || !("mode" in value) || value.mode !== "append"
+        || !("content" in value) || !Array.isArray(value.content)) {
+        throw RequestError.invalidParams(undefined, "systemPrompt requires append mode and text content");
+    }
+    const blocks: string[] = [];
+    for (const block of value.content) {
+        if (block === null || typeof block !== "object" || block.type !== "text" || typeof block.text !== "string") {
+            throw RequestError.invalidParams(undefined, "systemPrompt content must contain only text blocks");
+        }
+        blocks.push(block.text);
+    }
+    return blocks.join("\n\n");
+}
+
+/** The text-only subset has the same wire shape on both ACP versions. */
+export function toV1SystemPrompt(value: unknown): SystemPrompt | null {
+    const text = clientSystemPromptText(value);
+    return text === undefined ? null : {mode: "append", content: [{type: "text", text}]};
+}
+
+export function changesSystemPrompt(
+    request: {systemPrompt?: unknown; _meta?: unknown},
+    previous: SessionInstructions | undefined,
+): boolean {
+    const text = clientSystemPromptText(request.systemPrompt);
+    const air = airCustomInstructions(request._meta);
+    return text !== undefined && (text !== previous?.text
+        || (air !== undefined && air !== previous?.airInstructions));
+}

src/CodexAcpClient.ts

@@ -68,11 +68,13 @@ import {forkSession as runForkSession} from "./SessionFork";
 import type {SessionMetadata, SessionMetadataWithThread} from "./SessionMetadata";
 import {
     isMissingRolloutError,
+    isThreadNotMaterializedError,
     isThreadActiveWriterError,
     isUnknownThreadError,
     threadActiveWriterRequestError,
 } from "./CodexThreadErrors";
 import {airCustomInstructions} from "./AirExtension";
+import {changesSystemPrompt, clientSystemPromptText, type SessionInstructions} from "./ClientSystemPrompt";
 import {
     GatewayListingError,
     type GatewayModelIds,
@@ -680,18 +682,24 @@ export class CodexAcpClient {
         }
     }
 
-    async resumeSession(request: WithAcpMcpServers<acp.ResumeSessionRequest>, onSubscribed?: () => void): Promise<SessionMetadata> {
+    async resumeSession(
+        request: WithAcpMcpServers<acp.ResumeSessionRequest>,
+        onSubscribed?: () => void,
+        previousInstructions?: SessionInstructions,
+    ): Promise<SessionMetadata> {
+        const instructions = await this.resolveSessionInstructions(request, previousInstructions);
         const additionalDirectories = readAdditionalDirectories(request.cwd, request.additionalDirectories, request._meta);
         await this.refreshSkills(request.cwd, additionalDirectories);
 
         const sessionConfig = await this.createSessionConfig(request.cwd, additionalDirectories, request.mcpServers ?? []);
-        const response = await this.resumeThread({
+        const response = await this.resumeThreadWithInstructions({
             excludeTurns: true,
             config: sessionConfig.config,
             cwd: request.cwd,
             modelProvider: await this.getResumeModelProvider(),
             threadId: request.sessionId,
-        });
+            ...(instructions?.text !== undefined ? {developerInstructions: instructions.developerInstructions} : {}),
+        }, request, previousInstructions);
         onSubscribed?.();
         const codexModels = await this.fetchAvailableModels();
         const currentModelId = this.createModelId(codexModels, response.model, response.reasoningEffort).toString();
@@ -706,14 +714,17 @@ export class CodexAcpClient {
             currentServiceTier: response.serviceTier as ServiceTier ?? null,
             additionalDirectories,
             skippedMcpServers: sessionConfig.skippedMcpServers,
+            ...(instructions ? {instructions} : {}),
         }
     }
 
     async forkSession(
         request: WithAcpMcpServers<acp.ForkSessionRequest>,
         releaseFailedFork: (threadId: string) => Promise<void> = threadId => this.closeSession(threadId),
         forkCreated: (threadId: string) => void = () => {},
+        previousInstructions?: SessionInstructions,
     ): Promise<SessionMetadata> {
+        const instructions = await this.resolveSessionInstructions(request, previousInstructions);
         const additionalDirectories = readAdditionalDirectories(request.cwd, request.additionalDirectories, request._meta);
         return await runForkSession(request, additionalDirectories, {
             codexClient: this.codexClient,
@@ -727,21 +738,27 @@ export class CodexAcpClient {
             getCollaborationMode: sessionId => this.getCollaborationMode(sessionId),
             releaseFailedFork,
             forkCreated,
-        });
+        }, instructions);
     }
 
-    async loadSession(request: WithAcpMcpServers<acp.LoadSessionRequest>, onSubscribed?: () => void): Promise<SessionMetadataWithThread> {
+    async loadSession(
+        request: WithAcpMcpServers<acp.LoadSessionRequest>,
+        onSubscribed?: () => void,
+        previousInstructions?: SessionInstructions,
+    ): Promise<SessionMetadataWithThread> {
+        const instructions = await this.resolveSessionInstructions(request, previousInstructions);
         const additionalDirectories = readAdditionalDirectories(request.cwd, request.additionalDirectories, request._meta);
         await this.refreshSkills(request.cwd, additionalDirectories);
 
         const sessionConfig = await this.createSessionConfig(request.cwd, additionalDirectories, request.mcpServers ?? []);
-        const response = await this.resumeThread({
+        const response = await this.resumeThreadWithInstructions({
             excludeTurns: true,
             config: sessionConfig.config,
             cwd: request.cwd,
             modelProvider: await this.getResumeModelProvider(),
             threadId: request.sessionId,
-        });
+            ...(instructions?.text !== undefined ? {developerInstructions: instructions.developerInstructions} : {}),
+        }, request, previousInstructions);
         onSubscribed?.();
         // Resume cursors bound durable history; later turns arrive through live events.
         // A null paginated cursor means there was no durable history at resume time.
@@ -779,6 +796,7 @@ export class CodexAcpClient {
             history,
             additionalDirectories,
             skippedMcpServers: sessionConfig.skippedMcpServers,
+            ...(instructions ? {instructions} : {}),
         };
     }
 
@@ -809,8 +827,9 @@ export class CodexAcpClient {
     }
 
     async newSession(request: WithAcpMcpServers<acp.NewSessionRequest>): Promise<SessionMetadata> {
+        const instructions = await this.resolveSessionInstructions(request, undefined, true);
         const additionalDirectories = readAdditionalDirectories(request.cwd, request.additionalDirectories, request._meta);
-        const developerInstructions = airCustomInstructions(request._meta);
+        const developerInstructions = instructions?.developerInstructions;
         await this.refreshSkills(request.cwd, additionalDirectories);
 
         const sessionConfig = await this.createSessionConfig(request.cwd, additionalDirectories, request.mcpServers ?? []);
@@ -835,9 +854,97 @@ export class CodexAcpClient {
             currentServiceTier: response.serviceTier as ServiceTier ?? null,
             additionalDirectories,
             skippedMcpServers: sessionConfig.skippedMcpServers,
+            ...(instructions ? {instructions} : {}),
+        };
+    }
+
+    private async resolveSessionInstructions(
+        request: {cwd: string; systemPrompt?: unknown; _meta?: unknown},
+        previous?: SessionInstructions,
+        creating = false,
+    ): Promise<SessionInstructions | undefined> {
+        const text = clientSystemPromptText(request.systemPrompt);
+        if (text === undefined) {
+            if (!creating) return previous;
+            const airInstructions = airCustomInstructions(request._meta);
+            return airInstructions === undefined ? undefined : {airInstructions, developerInstructions: airInstructions};
+        }
+        if (!changesSystemPrompt(request, previous)) return previous;
+        // AIR already replaces configured developer instructions. Append to that same baseline.
+        const airInstructions = airCustomInstructions(request._meta) ?? previous?.airInstructions;
+        const baseline = airInstructions ?? this.config["developer_instructions"]
+            ?? (await this.codexClient.configRead({cwd: request.cwd, includeLayers: false}))?.config?.developer_instructions
+            ?? "";
+        if (typeof baseline !== "string") {
+            throw acp.RequestError.invalidParams(undefined, "Configured developer instructions must be text");
+        }
+        return {
+            text,
+            ...(airInstructions !== undefined ? {airInstructions} : {}),
+            developerInstructions: [baseline, text].filter(part => part.length > 0).join("\n\n"),
         };
     }
 
+    private async resumeThreadWithInstructions(
+        params: ThreadResumeParams,
+        request: {sessionId: string; systemPrompt?: unknown; _meta?: unknown},
+        previous?: SessionInstructions,
+    ): Promise<ResumedThread> {
+        if (!changesSystemPrompt(request, previous)) return this.resumeThread(params);
+        const {thread} = await this.codexClient.threadRead({threadId: request.sessionId});
+        if (thread.status.type === "notLoaded") return this.resumeThread(params);
+        if (thread.status.type !== "idle" || thread.path === null) {
+            throw acp.RequestError.invalidParams(
+                undefined,
+                "Changing systemPrompt requires an idle, persisted session; finish the turn or create a new session",
+            );
+        }
+        const terminals = await this.codexClient.threadBackgroundTerminalsList({threadId: request.sessionId, limit: 1});
+        if (terminals.data.length > 0) {
+            throw RequestError.invalidParams(undefined, "Cannot change systemPrompt while background terminals are running");
+        }
+        // A start response contains a planned rollout path even before the file exists.
+        try {
+            await this.codexClient.threadTurnsList({threadId: request.sessionId, limit: 1, itemsView: "notLoaded"});
+        } catch (error) {
+            if (!isMissingRolloutError(error) && !isThreadNotMaterializedError(error)) throw error;
+            throw RequestError.invalidParams(undefined, "Changing systemPrompt requires a persisted session; create a new session instead");
+        }
+        // Subscribed threads ignore resume overrides. Idle, detached threads can be rebuilt.
+        // Retained developer messages are replaced at the next compaction.
+        let unloaded = false;
+        let detached = false;
+        let resumed = false;
+        const release = this.codexClient.onClientTransportEvent(event => {
+            if (event.eventType === "notification" && event.method === "thread/status/changed"
+                && event.params.threadId === request.sessionId && event.params.status.type === "notLoaded") {
+                unloaded = true;
+            }
+        });
+        try {
+            await this.codexClient.threadUnsubscribe({threadId: request.sessionId});
+            detached = true;
+            const response = await this.resumeThread(params);
+            resumed = true;
+            if (!unloaded) {
+                throw RequestError.invalidParams(
+                    undefined,
+                    "Codex kept the existing thread loaded; systemPrompt could not be changed. Retry when idle",
+                );
+            }
+            return response;
+        } catch (error) {
+            if (detached && !resumed) {
+                await this.resumeThread({threadId: request.sessionId, excludeTurns: true}).catch(restoreError => {
+                    logger.error(`Failed to restore session ${request.sessionId} after an instruction update`, restoreError);
+                });
+            }
+            throw error;
+        } finally {
+            release();
+        }
+    }
+
     async closeSession(sessionId: string): Promise<void> {
         try {
             await this.codexClient.threadUnsubscribe({threadId: sessionId});