Client-Provided System Prompt

• Author(s): @wpfleger96
• Champion: @benbrandt

​

Elevator pitch

What are you proposing to change?

• A systemPrompt session capability, advertised by agents at initialize, so clients know before creating a session whether system prompt delivery is supported.
• An optional systemPrompt object on session/new with a mode and content. content is a ContentBlock[] for consistency with session/prompt, with text as the baseline. Clients re-send the object on the other session lifecycle requests, as they already do for cwd and mcpServers.
• Two modes: append (the baseline: client instructions are added to the agent’s own instructions) and override (client content replaces the agent’s built-in default instructions), the latter gated behind an override sub-capability.

​

Status quo

How do things work today and what problems does this cause? Why would we change things?

• claude-agent-acp added a _meta.systemPrompt extension (issue #90, PR #91). A string replaces the Claude Code preset and an object with append adds to it — the same two modes this RFD proposes. But the spec states implementations “MUST NOT make assumptions about values at these keys,” making _meta unsuitable for instruction delivery that agents are expected to act on. The implementation silently dropped excludeDynamicSections for months (issue #581), demonstrating the fragility of non-standard extensions.
• Buzz is a Nostr-based team collaboration and messaging platform where AI agents are first-class workspace members. Each managed agent has a persona (behavioral instructions, role definition, platform context) that the ACP harness needs to deliver as system-level instructions. Today, Buzz injects this as [System]\n{content} prepended to the user message on every turn — content that never reaches the LLM’s system slot. Buzz’s own Persona Pack Spec lists “true system prompt injection via ACP” as a planned feature, explicitly acknowledging the current approach is a workaround.
• Goose builds its system prompt internally via PromptManager and stores per-session overrides and additions, but the only way for an ACP client to set them is a Goose-specific extension method, _goose/unstable/session/system-prompt/set, with set (replace) and append modes. Goose has an open issue documenting the same gap in terms of its “recipe” system — recipes are Goose’s mechanism for injecting behavioral instructions into a session, and the issue notes “there is no recipe field on NewSessionRequest and no logic to load/apply a recipe to the new session’s agent.” Goose’s _goose/session/update_project method works around this by sending a project ID that the agent resolves to a file on disk — a Goose-specific indirection, not a protocol-level solution.
• Codex supports both modes through configuration — developer_instructions adds a developer message and model_instructions_file replaces its base instructions — but codex-acp exposes neither to ACP clients.

​

What we propose to do about it

What are you proposing to improve the situation?

​

Capability advertisement

{
  "jsonrpc": "2.0",
  "id": 0,
  "result": {
    "protocolVersion": 1,
    "agentCapabilities": {
      "sessionCapabilities": {
        "systemPrompt": {}
      }
    }
  }
}

​

Setting a system prompt

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "session/new",
  "params": {
    "cwd": "/home/user/project",
    "mcpServers": [],
    "systemPrompt": {
      "mode": "append",
      "content": [
        {
          "type": "text",
          "text": "You are a code review specialist. Focus on security vulnerabilities, performance issues, and adherence to the team's style guide. Be thorough but concise."
        }
      ]
    }
  }
}

​

Delivery modes: append and override

• "append": the client content is added to the agent’s own instructions rather than replacing them. Agents SHOULD give it system-level precedence — for example, in the model’s system prompt or developer instructions rather than in user-turn content — but where it is placed, in what order, and how it is formatted is implementation-defined. Every agent that advertises the capability MUST support append mode. Existing harnesses already behave this way: Goose adds appended text under an # Additional Instructions heading, Claude Code’s append adds text after its preset, and Codex delivers developer_instructions as a developer message alongside its base instructions.
• "override": the client content replaces the agent’s built-in default instructions. This mode only changes the instructions the agent itself authors: it does not change tool availability, MCP servers, permissions, or session configuration. Context the agent supplies from the workspace or environment — project instruction files such as AGENTS.md, environment details, skill listings — MAY still be included; every harness surveyed keeps some of it (see FAQ), and agents SHOULD document what they keep. Clients that use override take responsibility for any tool guidance or safety instructions the agent’s default prompt provided. This mode is opt-in on both sides: agents advertise it via the mode.override sub-capability, and clients MUST NOT request it unless advertised.

{
  "cwd": "/home/user/project",
  "mcpServers": [],
  "systemPrompt": {
    "mode": "override",
    "content": [{ "type": "text", "text": "..." }]
  }
}

"sessionCapabilities": {
  "systemPrompt": {
    "mode": {
      "override": {}
    }
  }
}

​

Session lifecycle

• Clients SHOULD send the same systemPrompt on these requests that they used when the session was created. Agents that rebuild their prompt from request parameters depend on it.
• When a lifecycle request omits systemPrompt, the resulting prompt is implementation-defined: the agent MAY keep using a prompt it stored with the session, or fall back to its default. Existing harnesses already persist the prompt in different ways (see FAQ), so this RFD requires agents neither to store it nor to discard a stored one.
• When a lifecycle request supplies a systemPrompt that differs from the one the session was using, the agent SHOULD apply it. An agent MAY defer the change until it next rebuilds its prompt (for example, after compaction) when applying it immediately would discard prompt caches or preserved reasoning.

​

Errors

​

Design choices

• Capability-gated opt-in. Without a capability, an “optional” field is a de facto breaking change: existing agents would silently ignore it, and the requirements below would retroactively put every existing agent in violation. The capability lets agents opt in and then be held to the behavior, and gives clients reliable feature detection — protocolVersion cannot serve that role since it only tracks major versions.
• A systemPrompt object with mode and content. Keeping the mode next to the content means there is no mode without a prompt to rule out, and leaves room for prompt-scoped _meta (see FAQ).
• Content as ContentBlock[]. Consistent with session/prompt and the rest of the protocol’s content model. Text is the required baseline; richer types are future sub-capabilities (see FAQ for why they are excluded from the initial version).
• Both modes, append as baseline. Append is what Claude Code, Codex, and Goose already support and is the mode every advertising agent must support. Override has real demand (Claude Code, Codex, and Goose ship it) but changes the safety posture — so it is double opt-in: agent advertises, client explicitly requests.
• Re-sent on lifecycle requests. This follows the pattern for cwd, mcpServers, and additionalDirectories, while leaving room for harnesses that already persist the prompt (see FAQ).

​

Shiny future

How will things will play out once this feature exists?

​

Implementation details and plan

Tell me more about your implementation. What is your detailed implementation plan?

​

Schema changes

interface SessionCapabilities {
  // ...existing capabilities
  systemPrompt?: SessionSystemPromptCapabilities | null; // omitted/null = unsupported, {} = supported
}

interface SessionSystemPromptCapabilities {
  mode?: SessionSystemPromptModeCapabilities | null; // omitted/null = append only
  _meta?: { [key: string]: unknown } | null;
}

interface SessionSystemPromptModeCapabilities {
  override?: SessionSystemPromptOverrideCapabilities | null; // omitted/null = unsupported, {} = override supported
  _meta?: { [key: string]: unknown } | null;
}

interface SessionSystemPromptOverrideCapabilities {
  _meta?: { [key: string]: unknown } | null;
}

interface SystemPrompt {
  mode: SystemPromptMode;
  content: ContentBlock[];
  _meta?: { [key: string]: unknown } | null;
}

type SystemPromptMode = "append" | "override";

interface NewSessionRequest {
  // ...existing fields
  systemPrompt?: SystemPrompt | null; // omitted and null are equivalent: no client prompt supplied
}

// The same optional field is added to LoadSessionRequest (v1 only),
// ResumeSessionRequest, and ForkSessionRequest.

​

ACP v1 and v2

​

Agent behavior

• MUST accept ContentBlock::Text content
• MUST support append mode, and MUST support override mode if they advertise the mode.override sub-capability
• MUST apply a systemPrompt supplied on session/new in the requested mode, or return an error as described above

​

Client behavior

• Clients MUST NOT include systemPrompt in any request unless the agent advertised the systemPrompt capability
• Clients MUST NOT use "mode": "override" unless the agent advertised the mode.override sub-capability
• Clients MUST NOT include content block types other than text unless a future sub-capability allows them
• Clients SHOULD re-send the session’s systemPrompt on session/load, session/resume, and session/fork

​

Security considerations

​

Backward compatibility

• Existing clients that don’t send systemPrompt see no difference.
• Existing agents never receive the field, because they don’t advertise the capability and clients gate on it. The unknown-param hazard — an old agent may silently ignore the field (no error, no incorporation) or, if it validates strictly, reject the request — is closed by construction, matching the approach taken by additionalDirectories.
• Capability detection follows the established rule from initialization: all capabilities omitted in the initialize response are treated as unsupported, and introducing a new capability is not a breaking change.

​

Frequently asked questions

What questions have arisen over the course of authoring this document or during subsequent discussions?

​

Why ContentBlock[] and not string?

​

Why is text the only baseline content type?

• resource_link is a pointer, not content. The agent would have to fetch and resolve the URI to text before session creation, with unspecified failure and lifecycle semantics (missing or oversized resources, snapshot-once vs. re-read, unreachable URIs). In a user prompt the agent can address a link with its own tools mid-turn; at session creation there is no turn to do it in.
• image / audio have no known use case. Model system slots are typically text-only (Anthropic’s system accepts text blocks only, and OpenAI’s instructions is a plain string), so an agent would have to deliver media elsewhere, such as a developer or user message at the start of the conversation, the way Claude Code delivers CLAUDE.md. The append rules allow that, but no client needs it yet.
• resource (embedded content) is the borderline case — inline delivery, can carry text mime-types — and is the plausible first future sub-capability if a real use case emerges. It’s excluded from the baseline because it adds URI/mime handling with no known consumer.

​

Why a systemPrompt object instead of a separate mode field?

​

What does override replace in existing harnesses?

​

Why re-send the prompt on load, resume, and fork instead of having the agent restore it?

​

How does this interact with session config options and modes?

​

Why include both append and override in the first version?

​

What alternative approaches did you consider, and why did you settle on this one?

• systemPrompt on session/prompt (per-turn): Would allow mid-session updates, matching how most LLM APIs send system content per-request. But it introduces ambiguous semantics when systemPrompt is omitted on a turn (inherit last value? revert to default?) and moves system prompt delivery from a one-time configuration to a repeated per-turn concern. For the common case — set instructions once at session start — session/new is simpler and sufficient.
• Dedicated session/set_system_prompt method: Changing the prompt of a live session is a separate feature; Goose already ships one as _goose/unstable/session/system-prompt/set. This RFD covers session creation and the lifecycle requests, and a dedicated method can be added later without conflicting with it.
• Standardize _meta.systemPrompt: Violates _meta design intent (see Status quo).
• CWD file conventions (e.g., placing instruction files in the session cwd): Agent-specific, not portable, and relies on the agent voluntarily reading the file. Not a protocol-level solution.
• Environment variables or CLI flags: Pre-session only, not portable across agent implementations, can’t be session-specific without restarting the agent.

​

Revision history

• 2026-05-18: Initial draft
• 2026-05-19: Upgraded to MUST with response acknowledgment per PR review feedback
• 2026-05-21: Replaced the response acknowledgment (systemPromptStatus) with a JSON-RPC error when the agent cannot apply the prompt
• 2026-07-21: Capability-gated opt-in under sessionCapabilities, type changed to ContentBlock[] with text-only baseline, explicit append/override delivery modes with override sub-capability, invalid-combination and load/resume/fork semantics — per maintainer review
• 2026-10-09: Moved to Draft. Replaced the bare array and systemPromptMode with a systemPrompt object, grouped the override capability under mode, accepted it on load/resume/fork with re-send semantics based on a survey of existing agents, covered ACP v1 and v2, defined what override replaces, and relaxed requirements that agents could not observe or implement