RFD: Client-Provided System Prompt by wpfleger96 · Pull Request #1237 · agentclientprotocol/agent-client-protocol

wpfleger96 · 2026-05-18T16:37:25Z

Proposes a standard way for clients to provide system-level instructions at session creation, so agents can deliver them to the LLM's system prompt slot.

ACP is currently the only major agent protocol without a dedicated system prompt mechanism. MCP, OpenAI, and Anthropic's Messages API all have one. Every ACP implementation has independently implemented non-standard workarounds: _meta extensions, user-message injection, filesystem indirection. This RFD proposes a single interoperable solution:

A systemPrompt capability under sessionCapabilities, advertised at initialize, so clients have reliable feature detection before sending the field
An optional systemPrompt field on session/new, typed as ContentBlock[] for consistency with session/prompt, with text as the universal baseline
Two delivery modes via an optional systemPromptMode field: append (default and universal baseline) and override (double opt-in, gated behind an override sub-capability)
Session-scoped and immutable; restored on session/load/session/resume and inherited by session/fork

Motivated by Discussion #414.

alexhancock · 2026-05-19T15:28:17Z

I think it's good

One bit of feedback that comes to mind: if it is to remain a "SHOULD" for agents to thread it to the llm's system prompt slot, it may be good for the client to know if the agent is ignoring it.

Two solutions:

Consider making it a MUST for the agent to attempt to handle it
Make some kind of notification or value that comes back on the session/new response indicating to the client whether it is being used with the llm

Number 2 may also be needed for error cases where the system prompt couldn't be inserted into a facility for this on the llm side.

wpfleger96 · 2026-05-19T21:10:25Z

@alexhancock thanks for the feedback! I agree with both and just pushed an update with these changes:

upgrade from SHOULD to MUST for incorporating the system prompt. I couldn't find any real-world use cases where an ACP agent couldn't/wouldn't honor a system prompt so giving clients a stronger guarantee with MUST feels right here
add systemPromptStatus field on the session/new response: it returns accepted or rejected (with a reason) so clients know whether their system prompt addition was used or not. This covers the error cases you mentioned and if the client doesn't send a systemPrompt, the field is omitted from the response

aleclarson · 2026-05-21T20:42:13Z

2. Make some kind of notification or value that comes back on the session/new response indicating to the client whether it is being used with the llm

Number 2 may also be needed for error cases where the system prompt couldn't be inserted into a facility for this on the llm side.

add systemPromptStatus field on the session/new response: it returns accepted or rejected (with a reason) so clients know whether their system prompt addition was used or not. This covers the error cases you mentioned and if the client doesn't send a systemPrompt, the field is omitted from the response

It seems wrong to have the session created if the systemPrompt option can't be applied. Wouldn't it be better for the agent to respond with an error result instead?

wpfleger96 · 2026-05-21T21:53:01Z

Make some kind of notification or value that comes back on the session/new response indicating to the client whether it is being used with the llm
Number 2 may also be needed for error cases where the system prompt couldn't be inserted into a facility for this on the llm side.

add systemPromptStatus field on the session/new response: it returns accepted or rejected (with a reason) so clients know whether their system prompt addition was used or not. This covers the error cases you mentioned and if the client doesn't send a systemPrompt, the field is omitted from the response

It seems wrong to have the session created if the systemPrompt option can't be applied. Wouldn't it be better for the agent to respond with an error result instead?

@aleclarson good call, that's a much cleaner design. I just pushed an update that drops systemPromptStatus entirely so if the agent can't apply the system prompt, session/new returns a standard JSON-RPC error and the session isn't created. this avoids an ambiguous middle state where a session exists but without the client's intended instructions. let me know what you think!

wpfleger96 · 2026-06-11T20:38:16Z

We've built a working implementation of this RFD in block/sprout#981 — a Rust ACP agent (buzz-agent) that handles the proposed systemPrompt field in session/new.

Key implementation details:

Layering semantics: base_prompt.md is always the foundation for all agents — it is never removed or replaced. The client-provided systemPrompt (agent persona) layers on top of the base prompt. Hints are appended after that. The final prompt structure is: [base_prompt] + [systemPrompt persona] + [hints].
Empty string treated as absent (no-op)
Agent returns a JSON-RPC error if the combined prompt exceeds its internal size limit (512KB) — exercising the spec's "MUST return a standard JSON-RPC error" clause
No capability advertisement — feature detection via protocol version as proposed
Backward-compatible: agents that don't recognize the field ignore it per standard JSON-RPC

Copilot

Pull request overview

This PR adds a new RFD documenting a proposal to let clients provide system-level instructions at session creation time, so agents can place them into the LLM’s system prompt slot in a consistent, interoperable way.

Changes:

Introduces an RFD describing systemPrompt support for session/new, including capability advertisement and validation rules.
Specifies append vs. override delivery modes (with override gated behind a sub-capability).
Documents backward-compatibility and client/agent MUST-level behaviors, plus rationale and alternatives.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 1 comment.

…ppend/override modes Addresses maintainer review: an optional field without a capability is a de facto breaking change (old agents may silently ignore or reject unknown params, and protocolVersion is major-only so it cannot signal additive features). Adds a systemPrompt capability under sessionCapabilities, switches the field type to ContentBlock[] with a text-only baseline, and specs both append (default, universal baseline) and override (sub-capability-gated) delivery modes since shipping harnesses already support both. Co-authored-by: Will Pfleger <wpfleger@block.xyz> Signed-off-by: Will Pfleger <wpfleger@block.xyz>

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

+title: "Client-Provided System Prompt"
+---
+
+Author(s): [@wpfleger96](https://github.com/wpfleger96) (Block — contributor to [Buzz](https://github.com/block/buzz) and [Goose](https://github.com/aaif-goose/goose))


wpfleger96 marked this pull request as ready for review May 18, 2026 16:44

wpfleger96 requested a review from a team as a code owner May 18, 2026 16:44

wpfleger96 force-pushed the rfd/client-system-prompt branch from b93753b to 68a1067 Compare May 18, 2026 19:14

andymac4182 reviewed May 18, 2026

View reviewed changes

Comment thread docs/rfds/client-system-prompt.mdx Outdated

wpfleger96 force-pushed the rfd/client-system-prompt branch from 68a1067 to 3cf1268 Compare May 19, 2026 00:12

wpfleger96 force-pushed the rfd/client-system-prompt branch from 3cf1268 to 4e4a566 Compare May 19, 2026 20:58

wpfleger96 force-pushed the rfd/client-system-prompt branch from 4e4a566 to 2331a57 Compare May 19, 2026 21:12

wpfleger96 force-pushed the rfd/client-system-prompt branch from 2331a57 to cb74b20 Compare May 21, 2026 21:50

wpfleger96 mentioned this pull request Jun 11, 2026

feat(acp): implement systemPrompt with protocol version gating block/buzz#981

Merged

This was referenced Jun 23, 2026

feat: add optional systemPrompt field to session/new #1494

Closed

feat(acp): incorporate client systemPrompt into new sessions aaif-goose/goose#9971

Closed

feat(buzz-acp): route goose systemPrompt via ACP+ _meta extension block/buzz#1290

Closed

kennethsinder mentioned this pull request Jul 3, 2026

Track reminder and ambient-context injection proposals across ACP, A2A, and MCP burin-labs/harn#1829

Open

benbrandt requested changes Jul 21, 2026

View reviewed changes

docs: add RFD for client-provided system prompt

0b902f1

Copilot AI review requested due to automatic review settings July 22, 2026 18:31

wpfleger96 force-pushed the rfd/client-system-prompt branch from cb74b20 to 526537e Compare July 22, 2026 18:31

Copilot started reviewing on behalf of wpfleger96 July 22, 2026 18:31 View session

Copilot AI reviewed Jul 22, 2026

View reviewed changes

Comment thread docs/rfds/client-system-prompt.mdx Outdated

Comment thread docs/rfds/client-system-prompt.mdx

Copilot AI review requested due to automatic review settings July 22, 2026 18:40

wpfleger96 force-pushed the rfd/client-system-prompt branch from 526537e to c2189e4 Compare July 22, 2026 18:40

Copilot started reviewing on behalf of wpfleger96 July 22, 2026 18:41 View session

Copilot AI reviewed Jul 22, 2026

View reviewed changes

Comment thread docs/rfds/client-system-prompt.mdx

Copilot AI review requested due to automatic review settings July 22, 2026 18:55

wpfleger96 force-pushed the rfd/client-system-prompt branch from c2189e4 to 4969bbb Compare July 22, 2026 18:55

Copilot started reviewing on behalf of wpfleger96 July 22, 2026 18:56 View session

Copilot AI reviewed Jul 22, 2026

View reviewed changes

Comment thread docs/rfds/client-system-prompt.mdx

title: "Client-Provided System Prompt"

---

Author(s): [@wpfleger96](https://github.com/wpfleger96) (Block — contributor to [Buzz](https://github.com/block/buzz) and [Goose](https://github.com/aaif-goose/goose))

This was referenced Aug 1, 2026

[spec] Cursor 接入 P1：lizi MCP 桥、commands / skills palette、usage 点亮与上游跟踪 gardenZzz/cindy#4

Open

T5 向 Cursor 请求 ACP system prompt 注入面 gardenZzz/cindy#51

Open

Uh oh!

Conversation

wpfleger96 commented May 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

alexhancock commented May 19, 2026

Uh oh!

wpfleger96 commented May 19, 2026

Uh oh!

aleclarson commented May 21, 2026

Uh oh!

wpfleger96 commented May 21, 2026

Uh oh!

wpfleger96 commented Jun 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

wpfleger96 commented May 18, 2026 •

edited

Loading

wpfleger96 commented Jun 11, 2026 •

edited

Loading