feat(subagents): support custom working directories

Author: danielkov

docs/user/security-limits-and-troubleshooting.md

@@ -9,7 +9,7 @@ Kit is a coding agent runtime, not a security boundary. Treat the model, prompts
 The root does not confine processes:
 
 - `shell` starts the platform shell with the root as its current directory. The command can read or change anything allowed by the Kit process, including paths outside the root, the network, and inherited environment variables.
-- ACP subagents are child processes started directly from trusted local `command` and `args` profiles, with the same root as their current directory. They inherit normal child-process host access; selecting a harness is not isolation.
+- ACP subagents are child processes started directly from trusted local `command` and `args` profiles. Their current directory and ACP root are the optional `subagent.cwd`, or Kit's root when it is omitted. They inherit normal child-process host access; selecting a directory or harness is not isolation.
 - MCP stdio servers are local processes, while MCP HTTP servers and A2A agents are remote trust domains. Tool arguments, prompts, and returned data cross those boundaries.
 - `edit` resolves relative paths from Kit's working directory, but also accepts `..`, absolute paths, and paths through symlinks. It can change any filesystem path allowed by the Kit process.
 

docs/user/subagents-and-acp-harnesses.md

@@ -9,6 +9,7 @@ Use the object form of the hidden tools inside `compose`:
 ```text
 first = subagent({
   name: "Implementer",
+  cwd: "../parser-worktree",
   prompt: "Inspect the parser and identify the smallest risk."
 })
 second = prompt({
@@ -27,7 +28,7 @@ Each successful turn returns a session value with `id`, `name`, `output`, and `g
 
 Always pass the latest completed value back to `prompt` or `fork`. Reusing an older value fails with `stale subagent generation N; current generation is M`. This prevents two continuations from silently racing on one session. Calls on an individual ACP session are serialized, while separate forked sessions can be prompted concurrently.
 
-The optional `name` argument is preferred on `subagent` and `fork`; `prompt` has no naming input and preserves the session name. The optional `harness` and `model` arguments belong only on `subagent`. `harness` overrides the user's configured harness preference. `model` selects an exact model value ID advertised by that harness through its ACP session configuration, or a model alias configured for that harness. Omit either argument to retain the configured preference. `prompt` and `fork` retain the original session's harness and model. An explicit model fails before the first prompt if the harness does not advertise a selectable `model` option or rejects the value.
+The optional `name` argument is preferred on `subagent` and `fork`; `prompt` has no naming input and preserves the session name. The optional `harness`, `model`, and `cwd` arguments belong only on `subagent`. `harness` overrides the user's configured harness preference. `model` selects an exact model value ID advertised by that harness through its ACP session configuration, or a model alias configured for that harness. `cwd` selects the new subagent's working directory; relative paths resolve from Kit's working directory, and missing paths or non-directories fail before startup. Omit an argument to retain its configured default. `prompt` and `fork` retain the original session's harness, model, and working directory. An explicit model fails before the first prompt if the harness does not advertise a selectable `model` option or rejects the value.
 
 ## Inspect display names
 
@@ -78,7 +79,7 @@ Text-only turns omit `updates`. Capture is limited to 64 update objects and 64 K
 
 ## Choose the built-in `acp.kit` harness
 
-`acp.kit` is always available and is the default when `[subagent].harness` is not configured. By default Kit launches the installed `kit` executable as `kit acp`, whose default stdio protocol is ACP v1. A built-in child inherits Kit's working directory, provider, model, MCP configuration and credential storage, cancellation, and nesting depth. An explicit `subagent.model` selection overrides the inherited model for that ACP session. It does not start an A2A listener.
+`acp.kit` is always available and is the default when `[subagent].harness` is not configured. By default Kit launches the installed `kit` executable as `kit acp`, whose default stdio protocol is ACP v1. A built-in child uses `subagent.cwd` when provided and otherwise inherits Kit's working directory; it also inherits the provider, model, MCP configuration and credential storage, cancellation, and nesting depth. An explicit `subagent.model` selection overrides the inherited model for that ACP session. It does not start an A2A listener.
 
 You can override only the executable and base arguments while preserving built-in Kit behavior:
 
@@ -96,7 +97,7 @@ Built-in subagent transcripts are durable on disk, but their reusable parent-own
 
 ## Configure a generic ACP v1 harness
 
-Generic external child harnesses remain ACP v1: they must speak newline-delimited JSON-RPC over stdio and support `initialize`, `session/new`, and `session/prompt`. `session/fork` and `session/close` are optional capabilities. Keep stdout protocol-only; the agent may log to stderr. Kit runs the executable directly from Kit's working directory and inherits the parent environment. It does not invoke a shell, so pipes, environment assignments, compound commands, and shell quoting in `command` or `args` do not work.
+Generic external child harnesses remain ACP v1: they must speak newline-delimited JSON-RPC over stdio and support `initialize`, `session/new`, and `session/prompt`. `session/fork` and `session/close` are optional capabilities. Keep stdout protocol-only; the agent may log to stderr. Kit runs the executable directly from the subagent's selected working directory, which defaults to Kit's working directory, and inherits the parent environment. It does not invoke a shell, so pipes, environment assignments, compound commands, and shell quoting in `command` or `args` do not work.
 
 Configure trusted argv profiles in `~/.kit/config.toml`:
 

fixtures/mock-acp.py

@@ -52,6 +52,8 @@ def log_request(request):
     entry = {"method": request.get("method")}
     if "sessionId" in params:
         entry["sessionId"] = params["sessionId"]
+    if request.get("method") in ("session/new", "session/fork"):
+        entry["cwd"] = params["cwd"]
     if request.get("method") == "session/prompt":
         entry["text"] = params["prompt"][0]["text"]
     with log_lock:
@@ -97,6 +99,8 @@ def prompt(request):
         time.sleep(0.01)
     if prompt_release is None:
         time.sleep(0.40)
+    if "MOCK_CWD" in text:
+        text = os.getcwd()
     if "MOCK_SELECTED_MODEL" in text:
         text = selected_models.get(session_id, model_ids[0])
     if "MOCK_STRUCTURED_OUTPUT" in text:

src/acp_child.rs

@@ -231,7 +231,7 @@ impl AcpHarnesses {
             command
         };
         // Every trusted profile is spawned directly (never through a shell)
-        // with Kit's working directory as cwd.
+        // with the configured subagent root as cwd.
         command.current_dir(&config.root);
         Ok(command)
     }
@@ -306,7 +306,7 @@ struct LaunchContext {
 impl LaunchContext {
     fn error(&self, phase: &str, error: impl std::fmt::Display) -> String {
         format!(
-            "ACP harness {phase}: {error} (harness={:?}, source={}, cwd=Kit working directory)",
+            "ACP harness {phase}: {error} (harness={:?}, source={}, cwd=configured working directory)",
             self.harness, self.source
         )
     }
@@ -364,6 +364,22 @@ pub(crate) struct ChildConfig {
 }
 
 impl ChildConfig {
+    pub(crate) fn with_root(mut self, root: PathBuf) -> Self {
+        let previous_root = self.root.clone();
+        if let Some(path) = &mut self.mcp_config
+            && path.is_relative()
+        {
+            *path = previous_root.join(&*path);
+        }
+        if let CredentialStorage::Filesystem(path) = &mut self.credential_storage
+            && path.is_relative()
+        {
+            *path = previous_root.join(&*path);
+        }
+        self.root = root;
+        self
+    }
+
     pub(crate) fn with_parent_context(mut self, id: String, name: String) -> Self {
         self.parent_id = Some(id);
         self.parent_name = Some(name);
@@ -1362,7 +1378,7 @@ mod tests {
         let error = context.error("handshake timeout", "no response within 30 seconds");
         assert!(error.contains("harness=\"acp.safe-name\""));
         assert!(error.contains("source=configured ACP profile"));
-        assert!(error.contains("cwd=Kit working directory"));
+        assert!(error.contains("cwd=configured working directory"));
         assert!(!error.contains("secret-command-name"));
         assert!(!error.contains("secret-argument"));
         assert!(!error.contains("/private/runtime/root"));
@@ -1427,7 +1443,10 @@ mod tests {
         assert!(error.contains("protocol handshake failure"), "{error}");
         assert!(error.contains("harness=\"acp.broken\""), "{error}");
         assert!(error.contains("source=configured ACP profile"), "{error}");
-        assert!(error.contains("cwd=Kit working directory"), "{error}");
+        assert!(
+            error.contains("cwd=configured working directory"),
+            "{error}"
+        );
         assert!(
             error.contains("the child did not complete the ACP handshake"),
             "{error}"
@@ -1487,7 +1506,10 @@ mod tests {
         assert!(error.contains("17"), "{error}");
         assert!(error.contains("harness=\"acp.exits\""), "{error}");
         assert!(error.contains("source=configured ACP profile"), "{error}");
-        assert!(error.contains("cwd=Kit working directory"), "{error}");
+        assert!(
+            error.contains("cwd=configured working directory"),
+            "{error}"
+        );
         assert!(!error.contains("python3"), "{error}");
         assert!(!error.contains("raise SystemExit"), "{error}");
         assert!(!error.contains(root.path().to_string_lossy().as_ref()));
@@ -1679,7 +1701,10 @@ mod tests {
             assert!(error.contains("spawn failure"), "{error}");
             assert!(error.contains("harness=\"acp.broken\""), "{error}");
             assert!(error.contains("source=configured ACP profile"), "{error}");
-            assert!(error.contains("cwd=Kit working directory"), "{error}");
+            assert!(
+                error.contains("cwd=configured working directory"),
+                "{error}"
+            );
             assert!(!error.contains("kit-test-acp-executable-that-does-not-exist"));
             assert!(!error.contains(root.path().to_string_lossy().as_ref()));
         }

src/tools/subagent.rs

@@ -1,5 +1,6 @@
 use std::{
     collections::{HashMap, HashSet},
+    path::PathBuf,
     sync::{Arc, Mutex},
 };
 
@@ -122,6 +123,7 @@ struct State {
     harness: String,
     model: Option<String>,
     kit: bool,
+    root: PathBuf,
     child: Option<ChildSession>,
     forking: Option<String>,
     permit: Option<OwnedSemaphorePermit>,
@@ -231,6 +233,7 @@ struct CreateOptions {
     name: Option<String>,
     harness: Option<String>,
     model: Option<String>,
+    cwd: Option<PathBuf>,
 }
 
 struct ForkSuccess {
@@ -248,6 +251,7 @@ struct ForkOperation {
     harness: String,
     model: Option<String>,
     kit: bool,
+    root: PathBuf,
     generation: u64,
     depth: usize,
     cancellation: TurnCancellation,
@@ -295,6 +299,30 @@ impl Subagents {
         self.config.harnesses.references()
     }
 
+    fn resolve_root(&self, cwd: Option<PathBuf>) -> Result<PathBuf, ChildError> {
+        let Some(cwd) = cwd else {
+            return Ok(self.config.root.clone());
+        };
+        let path = if cwd.is_absolute() {
+            cwd
+        } else {
+            self.config.root.join(cwd)
+        };
+        let root = path.canonicalize().map_err(|error| {
+            ChildError::Failed(format!(
+                "could not open subagent working directory {}: {error}",
+                path.display()
+            ))
+        })?;
+        if !root.is_dir() {
+            return Err(ChildError::Failed(format!(
+                "subagent working directory is not a directory: {}",
+                root.display()
+            )));
+        }
+        Ok(root)
+    }
+
     async fn create(
         &self,
         prompt: String,
@@ -310,7 +338,9 @@ impl Subagents {
             name,
             harness,
             model,
+            cwd,
         } = options;
+        let root = self.resolve_root(cwd)?;
         let harness = harness.unwrap_or_else(|| self.config.default_harness.clone());
         if !self.config.harnesses.contains(&harness) {
             return Err(ChildError::Failed(format!(
@@ -341,6 +371,7 @@ impl Subagents {
                 harness: harness.clone(),
                 model: model.clone(),
                 kit,
+                root: root.clone(),
                 child: None,
                 forking: None,
                 permit: Some(permit),
@@ -350,6 +381,7 @@ impl Subagents {
         let child_config = self
             .config
             .clone()
+            .with_root(root)
             .with_parent_context(id.clone(), state.lock().await.name.clone());
         {
             let locked = state.lock().await;
@@ -557,6 +589,7 @@ impl Subagents {
             harness: source.harness.clone(),
             model: source.model.clone(),
             kit: source.kit,
+            root: source.root.clone(),
             generation,
             depth,
             cancellation,
@@ -610,6 +643,7 @@ impl Subagents {
             harness,
             model,
             kit,
+            root,
             generation,
             depth,
             cancellation,
@@ -640,6 +674,7 @@ impl Subagents {
                 harness: harness.clone(),
                 model: model.clone(),
                 kit,
+                root: root.clone(),
                 child: None,
                 forking: None,
                 permit: None,
@@ -652,11 +687,11 @@ impl Subagents {
         }
 
         if !native_fork {
-            let root = self.config.root.clone();
+            let transcript_root = root.clone();
             let source_id = source_id.clone();
             let branch_id = id.clone();
             let cloned = tokio::task::spawn_blocking(move || {
-                session::clone_completed(&root, &source_id, &branch_id)
+                session::clone_completed(&transcript_root, &source_id, &branch_id)
             })
             .await
             .map_err(|error| ChildError::Failed(format!("transcript clone task failed: {error}")))
@@ -674,6 +709,7 @@ impl Subagents {
         let child_config = self
             .config
             .clone()
+            .with_root(root)
             .with_parent_context(id.clone(), branch_name);
         let child_result = if native_fork {
             source_child.fork(model.as_deref(), &cancellation).await
@@ -1269,7 +1305,7 @@ fn call_id_schema() -> serde_json::Value {
 impl SubagentTool {
     pub fn new(manager: Subagents, depth: usize) -> Self {
         let harnesses = manager.harness_references();
-        Self { manager, depth, spec: ToolSpec::new(ToolName::new("subagent"), "Start a parent-owned configured ACP harness, preferably assign a concise role-oriented display name, prompt it, and return its reusable session value. Omit `harness` and `model` unless the user or active workflow explicitly supplies the exact override or a configured alias. Never choose an override based on your own model, provider, publisher, familiarity, cost, or perceived quality; advertised choices indicate availability, not preference.", json!({"type":"object","properties":{"prompt":{"type":"string"},"name":display_name_schema(),"harness":{"type":"string","enum":harnesses,"description":"Override the user's configured harness preference with this value. Default to omitting it."},"model":{"type":"string","minLength":1,"description":"Exact ACP model selection ID or configured alias explicitly requested by the user or active workflow. Applies only to this new session; default to omitting it."},"output_schema":{"oneOf":[{"type":"object"},{"type":"boolean"}]}},"required":["prompt"],"additionalProperties":false})).with_output_schema(value_schema()).with_annotations(ToolAnnotations::new()) }
+        Self { manager, depth, spec: ToolSpec::new(ToolName::new("subagent"), "Start a parent-owned configured ACP harness, preferably assign a concise role-oriented display name, prompt it, and return its reusable session value. Omit `harness` and `model` unless the user or active workflow explicitly supplies the exact override or a configured alias. Never choose an override based on your own model, provider, publisher, familiarity, cost, or perceived quality; advertised choices indicate availability, not preference.", json!({"type":"object","properties":{"prompt":{"type":"string"},"name":display_name_schema(),"harness":{"type":"string","enum":harnesses,"description":"Override the user's configured harness preference with this value. Default to omitting it."},"model":{"type":"string","minLength":1,"description":"Exact ACP model selection ID or configured alias explicitly requested by the user or active workflow. Applies only to this new session; default to omitting it."},"cwd":{"type":"string","minLength":1,"description":"Working directory for the new subagent. Relative paths resolve from Kit's working directory."},"output_schema":{"oneOf":[{"type":"object"},{"type":"boolean"}]}},"required":["prompt"],"additionalProperties":false})).with_output_schema(value_schema()).with_annotations(ToolAnnotations::new()) }
     }
 }
 impl PromptTool {
@@ -1331,6 +1367,7 @@ struct Input {
     name: Option<String>,
     harness: Option<String>,
     model: Option<String>,
+    cwd: Option<PathBuf>,
     #[serde(default, deserialize_with = "deserialize_output_schema")]
     output_schema: Option<Value>,
 }
@@ -1467,6 +1504,7 @@ impl Tool for SubagentTool {
                         name: input.name,
                         harness: input.harness,
                         model: input.model,
+                        cwd: input.cwd,
                     },
                     self.depth,
                     cancellation(context),