ACP: support Preview client-provided systemPrompt append instructions per session #1457

ACP clients need to supply integration-specific instructions to Maple tasks without changing the host-wide Settings → Additional instructions or embedding behavioral instructions in ordinary user messages. Our Matrix integration is one example; this should work for any ACP client.

ACP has a defined Preview / unstable mechanism for this, not yet a stable protocol guarantee. Please implement that mechanism in Maple instead of inventing a Maple-specific extension or requiring a Matrix bridge workaround.

References:

• Client-Provided System Prompt RFD
• Move to Preview, merged upstream #2739
• Original schema implementation #2361

The upstream Rust feature is unstable_session_system_prompt. Track its current schema and semantics, since this remains Preview.

Requested initial scope

Support append mode. Keep Maple's built-in harness instructions and existing owner-configured additions, then apply client-provided text as a separate session-scoped addition at system/instruction level. Do not advertise override support; replacement of Maple's defaults is unnecessary for this use case.

For ACP v1, advertise agentCapabilities.sessionCapabilities.systemPrompt: {} only once supported. The client's session request then carries:

{
  "cwd": "/home/developer/project",
  "mcpServers": [],
  "systemPrompt": {
    "mode": "append",
    "content": [
      {
        "type": "text",
        "text": "You are participating in a team chat. Send messages only through the provided messaging tool."
      }
    ]
  }
}

Honor this on session/new and supported load/resume lifecycle methods according to the upstream contract. Document omission and changed-instruction behavior. No new fork capability is required. If v2 support is present, use its corresponding capability location.

Current implementation evidence

In released Maple 0.0.17 (c760e5b833c7724717deb54478b847bfc7fd0172), ACP new_session does not consume client system instructions and set_config_option supports model/thinking selection. Host settings already have harness_instructions / effective_harness_instructions(), but that is host-wide. Reuse prompt composition where appropriate without mutating shared settings or affecting other tasks.

Relevant source: apps/maple-agent/crates/maple-agent/src/acp/{handler,mod,session}.rs, apps/maple-agent/app/src/settings.rs, and the agent session construction path. Recheck current master before implementation.

Acceptance checks

• A client can discover support and create a task with appended text before the first model turn.
• Appended text reaches the model's instruction layer, retains Maple's defaults, and does not become a synthetic user turn.
• Two simultaneous sessions with different instructions remain isolated; desktop tasks and host settings are unchanged.
• Supported reconnect/load paths apply the documented semantics without repeatedly appending duplicates. Verify behavior after compaction as well.
• Unsupported modes/content and invalid requests produce explicit errors before a session is created or attached; never silently ignore supplied instructions.
• Existing clients that omit the field retain current behavior. Tool access and permissions are unaffected.

This issue requests Maple support first. Wiring the Matrix bridge to send the capability-gated field is separate follow-up work; no user-message fallback is requested here.