Skip to content

SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.

Agent chat: the system note reaches agents beyond the Claude adapter (#9811) (#9818)

MarkusRe776dfc9c1818
diff --git a/crates/ui-egui/src/agent_chat/acp.rs b/crates/ui-egui/src/agent_chat/acp.rs
index fe4d8e7ec1..2f5e4d49fa 100644
--- a/crates/ui-egui/src/agent_chat/acp.rs
+++ b/crates/ui-egui/src/agent_chat/acp.rs
@@ -211,7 +211,8 @@ pub fn wsl_path(path: &std::path::Path) -> std::path::PathBuf {
}
}
-/// What every session is told about where it is. Agents that don't read `_meta` ignore it.
+/// What every session is told about where it is. An agent with no route for it in
+/// [`session_new_params`] doesn't get it.
pub const SYSTEM_NOTE: &str = "You are running inside SolidCraft, a parametric 3D CAD application, as the user's assistant. \
The open design is reachable through the `solidcraft-app` MCP server: use its tools (list_commands, batch, execute, inspect_design, \
measure, screenshot, set_parameter, undo, skill_reference) to read and change the design the user is looking at, and verify with \
@@ -226,19 +227,44 @@ Keep answers short.";
pub const CLAUDE_DISALLOWED_TOOLS: &[&str] =
&["Bash", "BashOutput", "KillShell", "Read", "Write", "Edit", "MultiEdit", "NotebookEdit", "Glob", "Grep", "WebFetch", "WebSearch", "Task"];
-pub fn session_new_params(cwd: &std::path::Path, bridge: Option<&McpBridge>) -> Value {
+/// The `session/new` parameters. `init` is the agent's `initialize` reply: agents read the system
+/// note from different places (#9811), and the standard field may only go to an agent offering it.
+pub fn session_new_params(cwd: &std::path::Path, bridge: Option<&McpBridge>, init: &Value) -> Value {
let servers: Vec<Value> = bridge.map(McpBridge::to_json).into_iter().collect();
- json!({
+ let mut meta = json!({
+ // The Claude adapter's own key, for its versions without the standard field.
+ "systemPrompt": {"append": SYSTEM_NOTE},
+ // Hosts may opt a session out of "bypass permissions" (the Claude adapter reads it):
+ // every tool call the agent asks about reaches the panel.
+ // Its own shell and file tools are off: the agent works through SolidCraft's tools.
+ "claudeCode": {"options": {"allowDangerouslySkipPermissions": false, "disallowedTools": CLAUDE_DISALLOWED_TOOLS}},
+ });
+ if takes_antigravity_note(init)
+ && let Some(meta) = meta.as_object_mut()
+ {
+ meta.insert("antigravity".into(), json!({"systemPrompt": {"append": SYSTEM_NOTE}}));
+ }
+ let mut params = json!({
"cwd": cwd.to_string_lossy(),
"mcpServers": servers,
- "_meta": {
- "systemPrompt": {"append": SYSTEM_NOTE},
- // Hosts may opt a session out of "bypass permissions" (the Claude adapter reads it):
- // every tool call the agent asks about reaches the panel.
- // Its own shell and file tools are off: the agent works through SolidCraft's tools.
- "claudeCode": {"options": {"allowDangerouslySkipPermissions": false, "disallowedTools": CLAUDE_DISALLOWED_TOOLS}},
- },
- })
+ "_meta": meta,
+ });
+ if takes_standard_note(init)
+ && let Some(params) = params.as_object_mut()
+ {
+ params.insert("systemPrompt".into(), json!({"mode": "append", "content": [{"type": "text", "text": SYSTEM_NOTE}]}));
+ }
+ params
+}
+
+/// The agent offers ACP's `systemPrompt` field on its sessions.
+fn takes_standard_note(init: &Value) -> bool {
+ init.pointer("/agentCapabilities/sessionCapabilities/systemPrompt").is_some_and(|offer| !offer.is_null())
+}
+
+/// Antigravity offers its own key under `_meta` and doesn't read the Claude adapter's.
+fn takes_antigravity_note(init: &Value) -> bool {
+ init.pointer("/agentCapabilities/_meta/antigravity/systemPrompt/append").and_then(Value::as_bool).unwrap_or(false)
}
pub fn prompt_params(session: &str, parts: &[super::backend::PromptPart]) -> Value {
@@ -679,14 +705,47 @@ mod tests {
#[test]
fn the_session_gets_the_bridged_mcp_server_without_a_token_or_any_path() {
let b = McpBridge { cli: "/opt/solidcraft/solidcraft-cli".into(), port: 41234 };
- let p = session_new_params(std::path::Path::new("/home/u/designs"), Some(&b));
+ let p = session_new_params(std::path::Path::new("/home/u/designs"), Some(&b), &json!({}));
let s = &p["mcpServers"][0];
assert_eq!(s["name"], BRIDGE_NAME);
assert_eq!(s["args"], json!(["mcp", "--connect", "127.0.0.1:41234"]));
let text = p.to_string();
assert!(!text.contains("allow-any-path") && !text.contains("TOKEN") && !text.contains("token"), "{text}");
assert!(p["_meta"]["claudeCode"]["options"]["disallowedTools"].as_array().is_some_and(|t| t.iter().any(|x| x == "Bash")));
- assert_eq!(session_new_params(std::path::Path::new("/tmp"), None)["mcpServers"], json!([]));
+ assert_eq!(session_new_params(std::path::Path::new("/tmp"), None, &json!({}))["mcpServers"], json!([]));
+ }
+
+ /// #9811: the note goes by the routes an agent's `initialize` reply offers, and the standard
+ /// field never goes to an agent that doesn't offer it, as the protocol asks.
+ #[test]
+ fn the_system_note_takes_every_route_the_agent_offers() {
+ let params = |init: Value| session_new_params(std::path::Path::new("/tmp"), None, &init);
+ let standard = json!({"mode": "append", "content": [{"type": "text", "text": SYSTEM_NOTE}]});
+
+ let offers_standard = params(json!({"agentCapabilities": {"sessionCapabilities": {"systemPrompt": {}}}}));
+ assert_eq!(offers_standard["systemPrompt"], standard);
+ assert!(offers_standard["_meta"].get("antigravity").is_none());
+
+ let offers_antigravity = params(json!({"agentCapabilities": {"_meta": {"antigravity": {"systemPrompt": {"append": true}}}}}));
+ assert_eq!(offers_antigravity["_meta"]["antigravity"]["systemPrompt"]["append"], SYSTEM_NOTE);
+ assert!(offers_antigravity.get("systemPrompt").is_none());
+
+ for none in [
+ json!({}),
+ json!({"agentCapabilities": {"sessionCapabilities": {"systemPrompt": null}}}),
+ json!({"agentCapabilities": {"_meta": {"antigravity": {"systemPrompt": {"append": false}}}}}),
+ ] {
+ let p = params(none);
+ assert!(p.get("systemPrompt").is_none(), "{p}");
+ assert!(p["_meta"].get("antigravity").is_none(), "{p}");
+ }
+
+ // Every session keeps the key older Claude adapters read, and the tools they turn off.
+ for init in [json!({}), json!({"agentCapabilities": {"sessionCapabilities": {"systemPrompt": {}}}})] {
+ let p = params(init);
+ assert_eq!(p["_meta"]["systemPrompt"]["append"], SYSTEM_NOTE);
+ assert!(p["_meta"]["claudeCode"]["options"]["disallowedTools"].is_array());
+ }
}
/// #5546: an agent started through `wsl.exe` gets the session's paths as WSL shows them.
@@ -709,7 +768,7 @@ mod tests {
assert_eq!(wsl(r"\\server\share\x"), r"\\server\share\x");
let b = McpBridge { cli: r"C:\Program Files\SolidCraft\solidcraft-cli.exe".into(), port: 41234 };
- let p = session_new_params(&wsl_path(std::path::Path::new(r"C:\Users\u\work")), Some(&b.in_wsl()));
+ let p = session_new_params(&wsl_path(std::path::Path::new(r"C:\Users\u\work")), Some(&b.in_wsl()), &json!({}));
assert_eq!(p["cwd"], "/mnt/c/Users/u/work");
assert_eq!(p["mcpServers"][0]["command"], "/mnt/c/Program Files/SolidCraft/solidcraft-cli.exe");
assert_eq!(p["mcpServers"][0]["args"], json!(["mcp", "--connect", "127.0.0.1:41234"]));
diff --git a/crates/ui-egui/src/agent_chat/acp_client.rs b/crates/ui-egui/src/agent_chat/acp_client.rs
index 3f0e1eb348..c9695e9ccf 100644
--- a/crates/ui-egui/src/agent_chat/acp_client.rs
+++ b/crates/ui-egui/src/agent_chat/acp_client.rs
@@ -29,6 +29,8 @@ pub struct AcpBackend {
proc: AgentProcess,
cwd: std::path::PathBuf,
bridge: Option<acp::McpBridge>,
+ /// The agent's `initialize` reply: which routes the system note can take into a session.
+ init: Value,
next_id: u64,
pending: HashMap<u64, Pending>,
session: Option<String>,
@@ -56,6 +58,7 @@ impl AcpBackend {
proc,
cwd,
bridge,
+ init: Value::Null,
next_id: 0,
pending: HashMap::new(),
session: None,
@@ -82,7 +85,7 @@ impl AcpBackend {
fn new_session(&mut self) {
self.config_pending = None;
self.pending.retain(|_, request| *request != Pending::SetConfig);
- let params = acp::session_new_params(&self.cwd, self.bridge.as_ref());
+ let params = acp::session_new_params(&self.cwd, self.bridge.as_ref(), &self.init);
self.request(Pending::SessionNew, "session/new", params);
}
@@ -96,6 +99,7 @@ impl AcpBackend {
self.images = acp::takes_images(&v);
self.documents = acp::takes_documents(&v);
self.auth = acp::auth_methods(&v);
+ self.init = v;
self.new_session();
}
(Pending::SessionNew, Ok(v)) => match v.get("sessionId").and_then(Value::as_str) {
@@ -317,7 +321,7 @@ pub fn test_agent(argv: &[String], cwd: &std::path::Path) -> Result<String, Test
let init = wait_for(&p, 1);
let session_cwd = if acp::runs_in_wsl(argv) { acp::wsl_path(cwd) } else { cwd.to_path_buf() };
let result = init.and_then(|v| {
- p.send(&acp::request(2, "session/new", acp::session_new_params(&session_cwd, None)));
+ p.send(&acp::request(2, "session/new", acp::session_new_params(&session_cwd, None, &v)));
wait_for(&p, 2).map(|_| {
let who = acp::agent_info(&v);
crate::i18n::format("ui.ai_test_acp_ok", &[("agent", if who.is_empty() { "?" } else { &who })])
diff --git a/crates/ui-egui/src/agent_chat/tests.rs b/crates/ui-egui/src/agent_chat/tests.rs
index 82c670999b..a7bf716938 100644
--- a/crates/ui-egui/src/agent_chat/tests.rs
+++ b/crates/ui-egui/src/agent_chat/tests.rs
@@ -1148,6 +1148,56 @@ done
let _ = std::fs::remove_dir_all(&dir);
}
+/// #9811: an agent that offers the standard `systemPrompt` field gets the note in it, on the first
+/// session and on the one New chat opens.
+#[cfg(unix)]
+#[test]
+fn an_acp_agent_offering_the_standard_field_gets_the_system_note_in_every_session() {
+ let dir = std::env::temp_dir().join(format!("sc-agent-chat-note-{}", std::process::id()));
+ std::fs::create_dir_all(&dir).unwrap();
+ let log = dir.join("received.log");
+ let script = r#"
+log="$1"; n=0
+while IFS= read -r line; do
+ printf '%s\n' "$line" >> "$log"
+ id=$(printf '%s' "$line" | sed -n 's/.*"id":\([0-9][0-9]*\).*/\1/p')
+ case "$line" in
+ *'"method":"initialize"'*) printf '{"jsonrpc":"2.0","id":%s,"result":{"agentCapabilities":{"sessionCapabilities":{"systemPrompt":{}}},"agentInfo":{"name":"fake","version":"1"}}}\n' "$id" ;;
+ *'"method":"session/new"'*) n=$((n+1)); printf '{"jsonrpc":"2.0","id":%s,"result":{"sessionId":"s%s"}}\n' "$id" "$n" ;;
+ esac
+done
+"#;
+ let argv = vec!["sh".to_string(), "-c".to_string(), script.to_string(), "fake-agent".to_string(), log.to_string_lossy().into_owned()];
+ let start = backend::StartContext { cwd: dir.clone(), bridge: None, tools: None, wake: Box::new(|| {}) };
+ let mut app = SolveApp::new(solidcraft_engine::Session::default(), crate::Services::default());
+ app.agent_chat.backend = Some(Box::new(acp_client::AcpBackend::start(&argv, start).unwrap()));
+ app.agent_chat.state = Some(State::Starting);
+ let ctx = crate::fonts::test_context();
+ let until = |app: &mut SolveApp, done: &dyn Fn(&SolveApp) -> bool| {
+ let t = std::time::Instant::now();
+ while !done(app) {
+ assert!(t.elapsed() < std::time::Duration::from_secs(20), "timed out");
+ poll(app, &ctx);
+ std::thread::sleep(std::time::Duration::from_millis(10));
+ }
+ };
+ until(&mut app, &|a| a.agent_chat.state() == State::Ready);
+ new_chat(&mut app);
+ until(&mut app, &|a| a.agent_chat.state() == State::Ready);
+ let sessions: Vec<Value> = std::fs::read_to_string(&log)
+ .unwrap()
+ .lines()
+ .filter_map(|l| serde_json::from_str::<Value>(l).ok())
+ .filter(|v| v["method"] == "session/new")
+ .collect();
+ assert_eq!(sessions.len(), 2);
+ for session in &sessions {
+ assert_eq!(session.pointer("/params/systemPrompt/content/0/text").and_then(Value::as_str), Some(acp::SYSTEM_NOTE));
+ }
+ disconnect(&mut app);
+ let _ = std::fs::remove_dir_all(&dir);
+}
+
fn models_reply(current: &str) -> Event {
let m = |id: &str| acp::ModelInfo { id: id.into(), name: id.to_uppercase(), description: String::new() };
Event::Models { current: current.into(), available: vec![m("fast"), m("smart")] }
diff --git a/docs/design/in-app-agent-chat.md b/docs/design/in-app-agent-chat.md
index 938b5aabdd..5e0f037b69 100644
--- a/docs/design/in-app-agent-chat.md
+++ b/docs/design/in-app-agent-chat.md
@@ -26,7 +26,7 @@ What the prototype uses:
| Direction | Message | Use |
|---|---|---|
| → agent | `initialize {protocolVersion: 1, clientCapabilities, clientInfo}` | We declare no file system and no terminal (`fs.readTextFile/writeTextFile: false`, `terminal: false`), and terminal login (`auth.terminal: true`, plus the older `_meta["terminal-auth"]`). The reply carries `agentInfo` and `authMethods`. |
-| → agent | `session/new {cwd, mcpServers}` | `mcpServers` holds one stdio server: `solidcraft-cli mcp --connect 127.0.0.1:PORT`. `cwd` is the open design's folder (else SolidCraft's own `agent` folder). |
+| → agent | `session/new {cwd, mcpServers}` | `mcpServers` holds one stdio server: `solidcraft-cli mcp --connect 127.0.0.1:PORT`. `cwd` is the open design's folder (else SolidCraft's own `agent` folder). The system note goes in the standard `systemPrompt` field when the agent offers `sessionCapabilities.systemPrompt`, in `_meta.antigravity.systemPrompt.append` when Antigravity offers that, and always in `_meta.systemPrompt.append` for the Claude adapter. An agent with none of these doesn't get it. |
| → agent | `session/set_config_option {sessionId, configId, value}` | Set an advertised select option, including a model, reasoning effort or mode. The complete returned `configOptions` snapshot confirms the state; rejection leaves the previous confirmed snapshot intact. |
| → agent | `session/prompt {sessionId, prompt: [content]}` | One text block. The reply comes at the end of the turn with `stopReason` (`end_turn`, `cancelled`, `refusal`, …). |
| → agent | `session/cancel {sessionId}` (notification) | Cancel button. Open permission prompts are answered `cancelled` first, as the spec asks. |