Support client system prompt replacement and append

[salman1993]

Why

ACP clients cannot currently replace or append to Pi's system prompt when they create a session. Clients must use process wrappers or put standing instructions into user messages, which does not provide the same behavior.

What

Accept _meta.systemPrompt on session/new: a nonempty string replaces Pi's base prompt, and { "append": "..." } appends instructions. Advertise both modes and persistence through agentCapabilities._meta.piAcp.systemPrompt.

How

Validate the request before starting Pi. Pass literal prompt text through private files to Pi's existing CLI flags, then save the mode and text with the session record. Reapply that snapshot on automatic restoration and session/load, including after an adapter restart. Remove temporary files when the subprocess exits and saved prompts when sessions are deleted.

Omitting the extension preserves existing behavior. This change does not add skill or argument forwarding.

references

• Add support for appending or overriding the system prompt agentclientprotocol/claude-agent-acp#91
• fix: Forward full systemPrompt preset options from _meta agentclientprotocol/claude-agent-acp#591
• how buzz integrated changes from claude-agent-acp: feat(acp): deliver system prompt via _meta.systemPrompt for claude-agent-acp block/buzz#4395

Risk

The saved prompt lives in the adapter's session map, separately from Pi's transcript; restoration depends on retaining that map. Pi still adds its normal context, and explicit append supersedes automatic APPEND_SYSTEM.md discovery. Live checks ran on macOS; Windows process execution was not tested.

Testing

• PI_ACP_TEST_REAL_PI=1 node --import tsx --test test/component/pi-rpc-system-prompt.test.ts passed against Pi 0.84.4. Its RPC HTML export contained the custom prompt exactly once, and only append retained Pi's native coding preamble. No model calls were made.
• Exercised the built adapter over JSON-RPC stdio with isolated HOME and Pi settings. Created replacement session A and append session B, seeded synthetic transcripts, and inspected exports through session/prompt. Automatic restoration of A, explicit loading of B, and restoration after a full adapter restart all preserved the correct prompt without cross-session leakage. No model calls were made.

Generated with Codex

[salman1993]

where & how is the system prompt saved on session/new and how is it used when session is resumed for session/prompt method?

It’s saved in ~/.pi/pi-acp/session-map.json, keyed by session ID. There are two copies with different lifetimes: durable JSON for restoration, and a temporary file for the running Pi subprocess.

On session/new:

1. _meta.systemPrompt is normalized into { mode: "replace" | "append", text: "…" }.
2. The adapter writes the text into a private temporary file and starts Pi with --system-prompt <file> or --append-system-prompt <file>.
3. Once Pi returns its session ID and transcript path, SessionManager.create() saves a record like:

{
  "version": 1,
  "sessions": {
    "<session-id>": {
      "sessionId": "<session-id>",
      "cwd": "/workspace",
      "sessionFile": "/path/to/pi-session.jsonl",
      "systemPrompt": {
        "mode": "replace",
        "text": "Your complete instructions"
      },
      "updatedAt": "..."
    }
  }
}

On session/prompt:

• Session is already active: reuse its Pi subprocess, which already has the system prompt.
• Session needs restoration: read the saved record, recreate the temporary prompt file, and start Pi with both the transcript and prompt:

pi --mode rpc --no-themes \
  --session /path/to/pi-session.jsonl \
  --system-prompt /temporary/directory/prompt.md

Append mode uses --append-system-prompt instead.

The temporary file is removed when Pi exits; the saved JSON survives adapter restart. Deleting the session removes its saved prompt.

One limitation in the current implementation: missing or corrupt session-map data falls back to Pi transcript discovery, which cannot recover the custom prompt. So restoration depends on retaining that JSON record.