feat(worktree): merge-back flow + opt-in orchestrate child worktrees (#121 tracks 2+3)

crates/core/src/settings.rs

@@ -323,6 +323,10 @@ pub struct OrchestrateSettings {
  pub child_models: Vec<OrchestrateChildModel>,
  #[serde(default)]
  pub child_approval: ChildApprovalMode,
+ /// Give dispatched children dedicated Git worktrees when their resolved cwd
+ /// is itself a repository root. Dispatch-level `worktree` overrides this.
+ #[serde(default)]
+ pub child_worktrees: bool,
  /// Archive completed children automatically once their terminal result has
  /// been delivered to the parent. Per-dispatch `archive_on_complete`
  /// overrides this; failed children always stay visible for retries.
@@ -393,6 +397,7 @@ impl Default for OrchestrateSettings {
  },
  ],
  child_approval: ChildApprovalMode::default(),
+ child_worktrees: false,
  archive_on_complete: true,
  }
  }
@@ -1171,6 +1176,23 @@ mod tests {
  }
  }
 
+ #[test]
+ fn orchestrate_child_worktrees_default_false_and_round_trip() {
+ let legacy: OrchestrateSettings = serde_json::from_str("{}").unwrap();
+ assert!(!legacy.child_worktrees);
+
+ let settings = OrchestrateSettings {
+ child_worktrees: true,
+ ..Default::default()
+ };
+ let json = serde_json::to_string(&settings).unwrap();
+ assert!(json.contains(r#""child_worktrees":true"#));
+ assert_eq!(
+ serde_json::from_str::<OrchestrateSettings>(&json).unwrap(),
+ settings
+ );
+ }
+
  #[test]
  fn orchestrate_child_legacy_default_effort_alias_parses() {
  let settings: OrchestrateSettings = serde_json::from_str(

crates/orchestrate-mcp/src/lib.rs

@@ -16,6 +16,7 @@ pub enum OrchestrateOp {
  title: String,
  brief: String,
  cwd: Option<String>,
+ worktree: Option<bool>,
  archive_on_complete: Option<bool>,
  result_max_chars: Option<u32>,
  },

crates/orchestrate-mcp/src/tools.rs

@@ -28,6 +28,11 @@ struct DispatchParams {
  #[serde(default)]
  cwd: Option<String>,
  #[serde(default)]
+ #[schemars(
+ description = "Override Settings → Orchestrate child-worktree isolation for this dispatch. When true and cwd resolves to a Git repository root, the child runs on branch tcode/<thread-id> in a dedicated worktree. The response includes its path and branch. Non-Git cwd or creation failure falls back to cwd and reports a warning."
+ )]
+ worktree: Option<bool>,
+ #[serde(default)]
  #[schemars(
  description = "Override the auto-archive policy for this child. By default (per Settings → Orchestrate) a completed child is archived once its terminal result reaches you; failed children always stay visible. Set false to keep a completed child in the sidebar; send to an archived child unarchives it."
  )]
@@ -82,7 +87,7 @@ impl OrchestrateTools {
  }
 
  #[tool(
- description = "Dispatch a brief to a new child tcode thread and return its thread id. profile is the provider-profile id from the fleet table, required when the entry names one. access is one of read_only (review/investigation: read-only actions run without prompts; anything that mutates pauses for user approval), workspace_write (edits auto-approved inside the workspace), or full (default; no approval prompts). Completed children are auto-archived after their result is delivered unless archive_on_complete: false; failed children stay visible for retries."
+ description = "Dispatch a brief to a new child tcode thread and return its thread id. profile is the provider-profile id from the fleet table, required when the entry names one. access is one of read_only (review/investigation: read-only actions run without prompts; anything that mutates pauses for user approval), workspace_write (edits auto-approved inside the workspace), or full (default; no approval prompts). worktree optionally isolates the child in tcode/<thread-id> and overrides the Orchestrate setting; the response identifies the path and branch or explains fallback. Completed children are auto-archived after their result is delivered unless archive_on_complete: false; failed children stay visible for retries."
  )]
  async fn dispatch(
  &self,
@@ -99,6 +104,7 @@ impl OrchestrateTools {
  title: p.title,
  brief: p.brief,
  cwd: p.cwd,
+ worktree: p.worktree,
  archive_on_complete: p.archive_on_complete,
  result_max_chars: p.result_max_chars,
  })

crates/protocol/src/command.rs

@@ -40,6 +40,7 @@ pub enum SettingsPatch {
  AutoArchiveKeepCount(usize),
  AutoArchiveNoticeShown(bool),
  Orchestrate(OrchestrateSettings),
+ OrchestrateChildWorktrees(bool),
  ComputerUse(ComputerUseSettings),
  Browser(BrowserSettings),
  TitleGeneration(TitleGenerationSettings),
@@ -196,6 +197,9 @@ pub enum Command {
  session_id: String,
  remove_worktree: bool,
  },
+ MergeWorktree {
+ session_id: String,
+ },
  DeleteProject {
  project_id: String,
  },

crates/protocol/src/event.rs

@@ -252,6 +252,17 @@ pub struct GitActionRequest {
  pub feature_branch: Option<String>,
 }
 
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum MergeWorktreeFailure {
+ Missing,
+ DirtyWorktree,
+ DestinationDetached,
+ DirtyDestination,
+ DivergedConflict,
+ Git,
+}
+
 #[non_exhaustive]
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(tag = "type", content = "content", rename_all = "snake_case")]
@@ -354,4 +365,10 @@ pub enum RuntimeNotice {
  skipped: Vec<String>,
  limit_reached: bool,
  },
+ WorktreeMergedFastForward,
+ WorktreeMergedCommit,
+ WorktreeMergeFailed {
+ reason: MergeWorktreeFailure,
+ detail: Option<String>,
+ },
 }

crates/protocol/src/lib.rs

@@ -12,10 +12,10 @@ mod wire;
 pub use command::{Command, CommandResponse, SettingsPatch, ThreadExportFormat};
 pub use event::{
  AcpMarketplaceItem, EventEnvelope, GitActionRequest, GitStatusStatus, IndexSnapshot,
- ProviderVersionStatus, ProvidersStatus, QueuedMessageStatus, RuntimeEffect, RuntimeError,
-RuntimeNotice, RuntimeNotification, RuntimeOperationId, RuntimeToast, ServerEvent,
- SessionEventRecord, SessionStatus, TcodeUpdateStatus, TerminalContextStatus,
- TerminalSplitStatus, TerminalStatus, Topic,
+MergeWorktreeFailure, ProviderVersionStatus, ProvidersStatus, QueuedMessageStatus,
+RuntimeEffect, RuntimeError, RuntimeNotice, RuntimeNotification, RuntimeOperationId,
+RuntimeToast, ServerEvent, SessionEventRecord, SessionStatus, TcodeUpdateStatus,
+TerminalContextStatus, TerminalSplitStatus, TerminalStatus, Topic,
 };
 pub use query::{
  ExternalThread, GitDiffResult, GitDiffScope, GitFileText, PathEntry, Query, QueryResponse,

crates/protocol/src/tests.rs

@@ -227,6 +227,11 @@ fn round_trips_top_level_wire_types() {
  });
 }
 
+#[test]
+fn orchestrate_child_worktrees_patch_round_trips() {
+ round_trip(&SettingsPatch::OrchestrateChildWorktrees(true));
+}
+
 fn assert_command_crosses_ndjson(id: u64, command: Command) {
  match &command {
  Command::ApplyPendingRelaunch => {}
@@ -275,6 +280,7 @@ fn assert_command_crosses_ndjson(id: u64, command: Command) {
  Command::AutoArchiveSweep { .. } => {}
  Command::RenameSession { .. } => {}
  Command::ForkThread { .. } => {}
+ Command::MergeWorktree { .. } => {}
  Command::DeleteSession { .. } => {}
  Command::DeleteProject { .. } => {}
  Command::MarkSessionUnread { .. } => {}

crates/runtime/src/app/mod.rs

@@ -48,20 +48,22 @@ use tcode_core::ui::{
 };
 use tcode_protocol::ThreadExportFormat;
 use tcode_protocol::{
- AcpMarketplaceItem, EventEnvelope, ExternalThread, GitStatusStatus, IndexSnapshot, PathEntry,
- ProviderVersionStatus as ProtocolProviderVersionStatus, ProvidersStatus, QueuedMessageStatus,
- RecentDir, ServerEvent, SessionEventRecord, SessionStatus, TcodeUpdateStatus,
- TerminalContextStatus, TerminalSplitStatus, TerminalStatus, Topic,
+ AcpMarketplaceItem, EventEnvelope, ExternalThread, GitStatusStatus, IndexSnapshot,
+ MergeWorktreeFailure, PathEntry, ProviderVersionStatus as ProtocolProviderVersionStatus,
+ ProvidersStatus, QueuedMessageStatus, RecentDir, ServerEvent, SessionEventRecord,
+ SessionStatus, TcodeUpdateStatus, TerminalContextStatus, TerminalSplitStatus, TerminalStatus,
+ Topic,
 };
 use tcode_services::acp_registry::{
  Registry, RegistryAgent, cached, install, load, platform_key, resolve_recipe, uninstall,
  visible_agents,
 };
 use tcode_services::export;
 use tcode_services::git::{
- CheckoutError, checkout_if_clean, cleanup_orphaned_worktrees, commit_diff_context,
- create_git_worktree, list_git_branches, perform_action, read_git_branch, read_status,
- remove_git_worktree, run_claude_headless, worktree_path_for,
+ CheckoutError, MergeWorktreeError, MergeWorktreeOutcome, checkout_if_clean,
+ cleanup_orphaned_worktrees, commit_diff_context, create_git_worktree, list_git_branches,
+ merge_worktree_back, perform_action, read_git_branch, read_status, remove_git_worktree,
+ run_claude_headless, run_git, worktree_path_for,
 };
 use tcode_services::import::{
  ExternalImportUpdate, ExternalRoots, ImportOutcome, existing_external_ids, import_thread,

crates/runtime/src/app/orchestrate.rs

@@ -252,6 +252,15 @@ impl AppState {
  result_max_chars,
  );
  meta.title = title;
+ self.install_child_session(meta, brief, cx)
+ }
+
+ fn install_child_session(
+ &mut self,
+ meta: SessionMeta,
+ brief: String,
+ cx: &mut HostCx,
+ ) -> Result<String, String> {
  self.enqueue_store_write(
  StoreWrite::UpsertMeta {
  meta: Box::new(meta.clone()),
@@ -307,6 +316,7 @@ impl AppState {
  title,
  brief,
  cwd,
+ worktree,
  archive_on_complete,
  result_max_chars,
  } => {
@@ -335,7 +345,8 @@ impl AppState {
  };
  let archive_on_complete =
  archive_on_complete.unwrap_or(self.settings.orchestrate.archive_on_complete);
- let Some(cwd) = cwd else {
+ let isolate = worktree.unwrap_or(self.settings.orchestrate.child_worktrees);
+ if cwd.is_none() && !isolate {
  let result = self
  .create_child_session(
  &parent_id,
@@ -354,17 +365,32 @@ impl AppState {
  .map(|id| serde_json::json!({ "thread_id": id }));
  let _ = reply.try_send(result);
  return;
- };
- let Some(parent_cwd) = self.find_meta(&parent_id).map(|meta| meta.cwd) else {
+ }
+ let Some(parent) = self.find_meta(&parent_id) else {
  let _ = reply.try_send(Err("unknown parent session".to_string()));
  return;
  };
- let path = PathBuf::from(cwd);
- let path = if path.is_absolute() {
+ let path = PathBuf::from(cwd.unwrap_or_default());
+ let path = if path.as_os_str().is_empty() {
+ parent.cwd.clone()
+ } else if path.is_absolute() {
  path
  } else {
-parent_cwd.join(path)
+parent.cwd.join(path)
  };
+ let mut meta = build_child_meta(
+ &parent,
+ provider,
+ Some(model),
+ effort,
+ profile_id,
+ approval_mode,
+ path.clone(),
+ archive_on_complete,
+ result_max_chars,
+ );
+ meta.title = title;
+ let child_id = meta.id.clone();
  let host_cx = cx.clone();
  HostCx::spawn_detached(cx, async move {
  let resolved_cwd = host_cx
@@ -375,30 +401,39 @@ impl AppState {
  if !canonical.is_dir() {
  return Err(format!("invalid cwd: {}", canonical.display()));
  }
- Ok(canonical)
+ if isolate {
+ Ok(resolve_child_worktree(canonical, &child_id))
+ } else {
+ Ok((canonical, None, None))
+ }
  })
  .await;
  let result = match resolved_cwd {
- Ok(cwd) => host_cx
+ Ok((cwd, worktree, warning)) => host_cx
  .enqueue_and_wait(move |state, cx| {
- state.create_child_session(
- &parent_id,
- provider,
- Some(model),
- effort,
- profile_id,
- approval_mode,
- title,
- Some(cwd),
- brief,
- archive_on_complete,
- result_max_chars,
- cx,
- )
+ meta.cwd = cwd;
+ meta.worktree = worktree;
+ let worktree_info = meta.worktree.clone();
+ state
+ .install_child_session(meta, brief, cx)
+ .map(|id| (id, worktree_info, warning))
  })
  .await
  .unwrap_or_else(|_| Err("application closed".to_string()))
- .map(|id| serde_json::json!({ "thread_id": id })),
+ .map(|(id, worktree, warning)| {
+ let mut response = serde_json::json!({ "thread_id": id });
+ if let Some(worktree) = worktree {
+ response["worktree_path"] = serde_json::json!(
+ worktree_path_for(&id).display().to_string()
+ );
+ response["worktree_branch"] =
+ serde_json::json!(worktree.branch);
+ }
+ if let Some(warning) = warning {
+ response["warning"] = serde_json::json!(warning);
+ }
+ response
+ }),
  Err(err) => Err(err),
  };
  let _ = reply.try_send(result);
@@ -1211,6 +1246,55 @@ pub(super) fn provider_name(provider: ProviderKind) -> &'static str {
  }
 }
 
+fn resolve_child_worktree(
+ cwd: PathBuf,
+ child_id: &str,
+) -> (PathBuf, Option<WorktreeInfo>, Option<String>) {
+ let repo_root = run_git(&cwd, &["rev-parse", "--show-toplevel"])
+ .ok()
+ .map(|root| PathBuf::from(root.trim()))
+ .and_then(|root| root.canonicalize().ok());
+ if repo_root.as_ref() != Some(&cwd) {
+ let warning = format!(
+ "worktree isolation unavailable: {} is not a Git repository root; using the plain cwd",
+ cwd.display()
+ );
+ log::warn!("orchestrate dispatch: {warning}");
+ return (cwd, None, Some(warning));
+ }
+
+ let base = run_git(&cwd, &["symbolic-ref", "--quiet", "--short", "HEAD"])
+ .or_else(|_| run_git(&cwd, &["rev-parse", "HEAD"]))
+ .map(|base| base.trim().to_string());
+ let base = match base {
+ Ok(base) => base,
+ Err(error) => {
+ let warning = format!(
+ "worktree isolation unavailable: could not resolve the base revision ({error}); using the plain cwd"
+ );
+ log::warn!("orchestrate dispatch: {warning}");
+ return (cwd, None, Some(warning));
+ }
+ };
+ let path = worktree_path_for(child_id);
+ let requested_branch = format!("tcode/{child_id}");
+ match create_git_worktree(&cwd, &path, &requested_branch, &base) {
+ Ok(created) => {
+ let info = WorktreeInfo {
+ root_project_path: cwd,
+ base,
+ branch: created.branch,
+ };
+ (created.path, Some(info), None)
+ }
+ Err(error) => {
+ let warning = format!("worktree isolation failed ({error}); using the plain cwd");
+ log::warn!("orchestrate dispatch: {warning}");
+ (cwd, None, Some(warning))
+ }
+ }
+}
+
 #[allow(clippy::too_many_arguments)] // mirrors the MCP dispatch schema
 pub(super) fn build_child_meta(
  parent: &SessionMeta,

crates/core/src/settings.rs

@@ -323,6 +323,10 @@ pub struct OrchestrateSettings {
  pub child_models: Vec<OrchestrateChildModel>,
  #[serde(default)]
  pub child_approval: ChildApprovalMode,
+ /// Give dispatched children dedicated Git worktrees when their resolved cwd
+ /// is itself a repository root. Dispatch-level `worktree` overrides this.
+ #[serde(default)]
+ pub child_worktrees: bool,
  /// Archive completed children automatically once their terminal result has
  /// been delivered to the parent. Per-dispatch `archive_on_complete`
  /// overrides this; failed children always stay visible for retries.
@@ -393,6 +397,7 @@ impl Default for OrchestrateSettings {
  },
  ],
  child_approval: ChildApprovalMode::default(),
+ child_worktrees: false,
  archive_on_complete: true,
  }
  }
@@ -1171,6 +1176,23 @@ mod tests {
  }
  }
 
+ #[test]
+ fn orchestrate_child_worktrees_default_false_and_round_trip() {
+ let legacy: OrchestrateSettings = serde_json::from_str("{}").unwrap();
+ assert!(!legacy.child_worktrees);
+
+ let settings = OrchestrateSettings {
+ child_worktrees: true,
+ ..Default::default()
+ };
+ let json = serde_json::to_string(&settings).unwrap();
+ assert!(json.contains(r#""child_worktrees":true"#));
+ assert_eq!(
+ serde_json::from_str::<OrchestrateSettings>(&json).unwrap(),
+ settings
+ );
+ }
+
  #[test]
  fn orchestrate_child_legacy_default_effort_alias_parses() {
  let settings: OrchestrateSettings = serde_json::from_str(

crates/orchestrate-mcp/src/lib.rs

@@ -16,6 +16,7 @@ pub enum OrchestrateOp {
  title: String,
  brief: String,
  cwd: Option<String>,
+ worktree: Option<bool>,
  archive_on_complete: Option<bool>,
  result_max_chars: Option<u32>,
  },

crates/orchestrate-mcp/src/tools.rs

@@ -28,6 +28,11 @@ struct DispatchParams {
  #[serde(default)]
  cwd: Option<String>,
  #[serde(default)]
+ #[schemars(
+ description = "Override Settings → Orchestrate child-worktree isolation for this dispatch. When true and cwd resolves to a Git repository root, the child runs on branch tcode/<thread-id> in a dedicated worktree. The response includes its path and branch. Non-Git cwd or creation failure falls back to cwd and reports a warning."
+ )]
+ worktree: Option<bool>,
+ #[serde(default)]
  #[schemars(
  description = "Override the auto-archive policy for this child. By default (per Settings → Orchestrate) a completed child is archived once its terminal result reaches you; failed children always stay visible. Set false to keep a completed child in the sidebar; send to an archived child unarchives it."
  )]
@@ -82,7 +87,7 @@ impl OrchestrateTools {
  }
 
  #[tool(
- description = "Dispatch a brief to a new child tcode thread and return its thread id. profile is the provider-profile id from the fleet table, required when the entry names one. access is one of read_only (review/investigation: read-only actions run without prompts; anything that mutates pauses for user approval), workspace_write (edits auto-approved inside the workspace), or full (default; no approval prompts). Completed children are auto-archived after their result is delivered unless archive_on_complete: false; failed children stay visible for retries."
+ description = "Dispatch a brief to a new child tcode thread and return its thread id. profile is the provider-profile id from the fleet table, required when the entry names one. access is one of read_only (review/investigation: read-only actions run without prompts; anything that mutates pauses for user approval), workspace_write (edits auto-approved inside the workspace), or full (default; no approval prompts). worktree optionally isolates the child in tcode/<thread-id> and overrides the Orchestrate setting; the response identifies the path and branch or explains fallback. Completed children are auto-archived after their result is delivered unless archive_on_complete: false; failed children stay visible for retries."
  )]
  async fn dispatch(
  &self,
@@ -99,6 +104,7 @@ impl OrchestrateTools {
  title: p.title,
  brief: p.brief,
  cwd: p.cwd,
+ worktree: p.worktree,
  archive_on_complete: p.archive_on_complete,
  result_max_chars: p.result_max_chars,
  })

crates/protocol/src/command.rs

@@ -40,6 +40,7 @@ pub enum SettingsPatch {
  AutoArchiveKeepCount(usize),
  AutoArchiveNoticeShown(bool),
  Orchestrate(OrchestrateSettings),
+ OrchestrateChildWorktrees(bool),
  ComputerUse(ComputerUseSettings),
  Browser(BrowserSettings),
  TitleGeneration(TitleGenerationSettings),
@@ -196,6 +197,9 @@ pub enum Command {
  session_id: String,
  remove_worktree: bool,
  },
+ MergeWorktree {
+ session_id: String,
+ },
  DeleteProject {
  project_id: String,
  },

crates/protocol/src/event.rs

@@ -252,6 +252,17 @@ pub struct GitActionRequest {
  pub feature_branch: Option<String>,
 }
 
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum MergeWorktreeFailure {
+ Missing,
+ DirtyWorktree,
+ DestinationDetached,
+ DirtyDestination,
+ DivergedConflict,
+ Git,
+}
+
 #[non_exhaustive]
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(tag = "type", content = "content", rename_all = "snake_case")]
@@ -354,4 +365,10 @@ pub enum RuntimeNotice {
  skipped: Vec<String>,
  limit_reached: bool,
  },
+ WorktreeMergedFastForward,
+ WorktreeMergedCommit,
+ WorktreeMergeFailed {
+ reason: MergeWorktreeFailure,
+ detail: Option<String>,
+ },
 }

crates/protocol/src/lib.rs

@@ -12,10 +12,10 @@ mod wire;
 pub use command::{Command, CommandResponse, SettingsPatch, ThreadExportFormat};
 pub use event::{
  AcpMarketplaceItem, EventEnvelope, GitActionRequest, GitStatusStatus, IndexSnapshot,
- ProviderVersionStatus, ProvidersStatus, QueuedMessageStatus, RuntimeEffect, RuntimeError,
-RuntimeNotice, RuntimeNotification, RuntimeOperationId, RuntimeToast, ServerEvent,
- SessionEventRecord, SessionStatus, TcodeUpdateStatus, TerminalContextStatus,
- TerminalSplitStatus, TerminalStatus, Topic,
+MergeWorktreeFailure, ProviderVersionStatus, ProvidersStatus, QueuedMessageStatus,
+RuntimeEffect, RuntimeError, RuntimeNotice, RuntimeNotification, RuntimeOperationId,
+RuntimeToast, ServerEvent, SessionEventRecord, SessionStatus, TcodeUpdateStatus,
+TerminalContextStatus, TerminalSplitStatus, TerminalStatus, Topic,
 };
 pub use query::{
  ExternalThread, GitDiffResult, GitDiffScope, GitFileText, PathEntry, Query, QueryResponse,

crates/protocol/src/tests.rs

@@ -227,6 +227,11 @@ fn round_trips_top_level_wire_types() {
  });
 }
 
+#[test]
+fn orchestrate_child_worktrees_patch_round_trips() {
+ round_trip(&SettingsPatch::OrchestrateChildWorktrees(true));
+}
+
 fn assert_command_crosses_ndjson(id: u64, command: Command) {
  match &command {
  Command::ApplyPendingRelaunch => {}
@@ -275,6 +280,7 @@ fn assert_command_crosses_ndjson(id: u64, command: Command) {
  Command::AutoArchiveSweep { .. } => {}
  Command::RenameSession { .. } => {}
  Command::ForkThread { .. } => {}
+ Command::MergeWorktree { .. } => {}
  Command::DeleteSession { .. } => {}
  Command::DeleteProject { .. } => {}
  Command::MarkSessionUnread { .. } => {}

crates/runtime/src/app/mod.rs

@@ -48,20 +48,22 @@ use tcode_core::ui::{
 };
 use tcode_protocol::ThreadExportFormat;
 use tcode_protocol::{
- AcpMarketplaceItem, EventEnvelope, ExternalThread, GitStatusStatus, IndexSnapshot, PathEntry,
- ProviderVersionStatus as ProtocolProviderVersionStatus, ProvidersStatus, QueuedMessageStatus,
- RecentDir, ServerEvent, SessionEventRecord, SessionStatus, TcodeUpdateStatus,
- TerminalContextStatus, TerminalSplitStatus, TerminalStatus, Topic,
+ AcpMarketplaceItem, EventEnvelope, ExternalThread, GitStatusStatus, IndexSnapshot,
+ MergeWorktreeFailure, PathEntry, ProviderVersionStatus as ProtocolProviderVersionStatus,
+ ProvidersStatus, QueuedMessageStatus, RecentDir, ServerEvent, SessionEventRecord,
+ SessionStatus, TcodeUpdateStatus, TerminalContextStatus, TerminalSplitStatus, TerminalStatus,
+ Topic,
 };
 use tcode_services::acp_registry::{
  Registry, RegistryAgent, cached, install, load, platform_key, resolve_recipe, uninstall,
  visible_agents,
 };
 use tcode_services::export;
 use tcode_services::git::{
- CheckoutError, checkout_if_clean, cleanup_orphaned_worktrees, commit_diff_context,
- create_git_worktree, list_git_branches, perform_action, read_git_branch, read_status,
- remove_git_worktree, run_claude_headless, worktree_path_for,
+ CheckoutError, MergeWorktreeError, MergeWorktreeOutcome, checkout_if_clean,
+ cleanup_orphaned_worktrees, commit_diff_context, create_git_worktree, list_git_branches,
+ merge_worktree_back, perform_action, read_git_branch, read_status, remove_git_worktree,
+ run_claude_headless, run_git, worktree_path_for,
 };
 use tcode_services::import::{
  ExternalImportUpdate, ExternalRoots, ImportOutcome, existing_external_ids, import_thread,

crates/runtime/src/app/orchestrate.rs

@@ -252,6 +252,15 @@ impl AppState {
  result_max_chars,
  );
  meta.title = title;
+ self.install_child_session(meta, brief, cx)
+ }
+
+ fn install_child_session(
+ &mut self,
+ meta: SessionMeta,
+ brief: String,
+ cx: &mut HostCx,
+ ) -> Result<String, String> {
  self.enqueue_store_write(
  StoreWrite::UpsertMeta {
  meta: Box::new(meta.clone()),
@@ -307,6 +316,7 @@ impl AppState {
  title,
  brief,
  cwd,
+ worktree,
  archive_on_complete,
  result_max_chars,
  } => {
@@ -335,7 +345,8 @@ impl AppState {
  };
  let archive_on_complete =
  archive_on_complete.unwrap_or(self.settings.orchestrate.archive_on_complete);
- let Some(cwd) = cwd else {
+ let isolate = worktree.unwrap_or(self.settings.orchestrate.child_worktrees);
+ if cwd.is_none() && !isolate {
  let result = self
  .create_child_session(
  &parent_id,
@@ -354,17 +365,32 @@ impl AppState {
  .map(|id| serde_json::json!({ "thread_id": id }));
  let _ = reply.try_send(result);
  return;
- };
- let Some(parent_cwd) = self.find_meta(&parent_id).map(|meta| meta.cwd) else {
+ }
+ let Some(parent) = self.find_meta(&parent_id) else {
  let _ = reply.try_send(Err("unknown parent session".to_string()));
  return;
  };
- let path = PathBuf::from(cwd);
- let path = if path.is_absolute() {
+ let path = PathBuf::from(cwd.unwrap_or_default());
+ let path = if path.as_os_str().is_empty() {
+ parent.cwd.clone()
+ } else if path.is_absolute() {
  path
  } else {
-parent_cwd.join(path)
+parent.cwd.join(path)
  };
+ let mut meta = build_child_meta(
+ &parent,
+ provider,
+ Some(model),
+ effort,
+ profile_id,
+ approval_mode,
+ path.clone(),
+ archive_on_complete,
+ result_max_chars,
+ );
+ meta.title = title;
+ let child_id = meta.id.clone();
  let host_cx = cx.clone();
  HostCx::spawn_detached(cx, async move {
  let resolved_cwd = host_cx
@@ -375,30 +401,39 @@ impl AppState {
  if !canonical.is_dir() {
  return Err(format!("invalid cwd: {}", canonical.display()));
  }
- Ok(canonical)
+ if isolate {
+ Ok(resolve_child_worktree(canonical, &child_id))
+ } else {
+ Ok((canonical, None, None))
+ }
  })
  .await;
  let result = match resolved_cwd {
- Ok(cwd) => host_cx
+ Ok((cwd, worktree, warning)) => host_cx
  .enqueue_and_wait(move |state, cx| {
- state.create_child_session(
- &parent_id,
- provider,
- Some(model),
- effort,
- profile_id,
- approval_mode,
- title,
- Some(cwd),
- brief,
- archive_on_complete,
- result_max_chars,
- cx,
- )
+ meta.cwd = cwd;
+ meta.worktree = worktree;
+ let worktree_info = meta.worktree.clone();
+ state
+ .install_child_session(meta, brief, cx)
+ .map(|id| (id, worktree_info, warning))
  })
  .await
  .unwrap_or_else(|_| Err("application closed".to_string()))
- .map(|id| serde_json::json!({ "thread_id": id })),
+ .map(|(id, worktree, warning)| {
+ let mut response = serde_json::json!({ "thread_id": id });
+ if let Some(worktree) = worktree {
+ response["worktree_path"] = serde_json::json!(
+ worktree_path_for(&id).display().to_string()
+ );
+ response["worktree_branch"] =
+ serde_json::json!(worktree.branch);
+ }
+ if let Some(warning) = warning {
+ response["warning"] = serde_json::json!(warning);
+ }
+ response
+ }),
  Err(err) => Err(err),
  };
  let _ = reply.try_send(result);
@@ -1211,6 +1246,55 @@ pub(super) fn provider_name(provider: ProviderKind) -> &'static str {
  }
 }
 
+fn resolve_child_worktree(
+ cwd: PathBuf,
+ child_id: &str,
+) -> (PathBuf, Option<WorktreeInfo>, Option<String>) {
+ let repo_root = run_git(&cwd, &["rev-parse", "--show-toplevel"])
+ .ok()
+ .map(|root| PathBuf::from(root.trim()))
+ .and_then(|root| root.canonicalize().ok());
+ if repo_root.as_ref() != Some(&cwd) {
+ let warning = format!(
+ "worktree isolation unavailable: {} is not a Git repository root; using the plain cwd",
+ cwd.display()
+ );
+ log::warn!("orchestrate dispatch: {warning}");
+ return (cwd, None, Some(warning));
+ }
+
+ let base = run_git(&cwd, &["symbolic-ref", "--quiet", "--short", "HEAD"])
+ .or_else(|_| run_git(&cwd, &["rev-parse", "HEAD"]))
+ .map(|base| base.trim().to_string());
+ let base = match base {
+ Ok(base) => base,
+ Err(error) => {
+ let warning = format!(
+ "worktree isolation unavailable: could not resolve the base revision ({error}); using the plain cwd"
+ );
+ log::warn!("orchestrate dispatch: {warning}");
+ return (cwd, None, Some(warning));
+ }
+ };
+ let path = worktree_path_for(child_id);
+ let requested_branch = format!("tcode/{child_id}");
+ match create_git_worktree(&cwd, &path, &requested_branch, &base) {
+ Ok(created) => {
+ let info = WorktreeInfo {
+ root_project_path: cwd,
+ base,
+ branch: created.branch,
+ };
+ (created.path, Some(info), None)
+ }
+ Err(error) => {
+ let warning = format!("worktree isolation failed ({error}); using the plain cwd");
+ log::warn!("orchestrate dispatch: {warning}");
+ (cwd, None, Some(warning))
+ }
+ }
+}
+
 #[allow(clippy::too_many_arguments)] // mirrors the MCP dispatch schema
 pub(super) fn build_child_meta(
  parent: &SessionMeta,

crates/core/src/settings.rs

@@ -323,6 +323,10 @@ pub struct OrchestrateSettings {
  pub child_models: Vec<OrchestrateChildModel>,
  #[serde(default)]
  pub child_approval: ChildApprovalMode,
+ /// Give dispatched children dedicated Git worktrees when their resolved cwd
+ /// is itself a repository root. Dispatch-level `worktree` overrides this.
+ #[serde(default)]
+ pub child_worktrees: bool,
  /// Archive completed children automatically once their terminal result has
  /// been delivered to the parent. Per-dispatch `archive_on_complete`
  /// overrides this; failed children always stay visible for retries.
@@ -393,6 +397,7 @@ impl Default for OrchestrateSettings {
  },
  ],
  child_approval: ChildApprovalMode::default(),
+ child_worktrees: false,
  archive_on_complete: true,
  }
  }
@@ -1171,6 +1176,23 @@ mod tests {
  }
  }
 
+ #[test]
+ fn orchestrate_child_worktrees_default_false_and_round_trip() {
+ let legacy: OrchestrateSettings = serde_json::from_str("{}").unwrap();
+ assert!(!legacy.child_worktrees);
+
+ let settings = OrchestrateSettings {
+ child_worktrees: true,
+ ..Default::default()
+ };
+ let json = serde_json::to_string(&settings).unwrap();
+ assert!(json.contains(r#""child_worktrees":true"#));
+ assert_eq!(
+ serde_json::from_str::<OrchestrateSettings>(&json).unwrap(),
+ settings
+ );
+ }
+
  #[test]
  fn orchestrate_child_legacy_default_effort_alias_parses() {
  let settings: OrchestrateSettings = serde_json::from_str(

crates/orchestrate-mcp/src/lib.rs

@@ -16,6 +16,7 @@ pub enum OrchestrateOp {
  title: String,
  brief: String,
  cwd: Option<String>,
+ worktree: Option<bool>,
  archive_on_complete: Option<bool>,
  result_max_chars: Option<u32>,
  },

crates/orchestrate-mcp/src/tools.rs

@@ -28,6 +28,11 @@ struct DispatchParams {
  #[serde(default)]
  cwd: Option<String>,
  #[serde(default)]
+ #[schemars(
+ description = "Override Settings → Orchestrate child-worktree isolation for this dispatch. When true and cwd resolves to a Git repository root, the child runs on branch tcode/<thread-id> in a dedicated worktree. The response includes its path and branch. Non-Git cwd or creation failure falls back to cwd and reports a warning."
+ )]
+ worktree: Option<bool>,
+ #[serde(default)]
  #[schemars(
  description = "Override the auto-archive policy for this child. By default (per Settings → Orchestrate) a completed child is archived once its terminal result reaches you; failed children always stay visible. Set false to keep a completed child in the sidebar; send to an archived child unarchives it."
  )]
@@ -82,7 +87,7 @@ impl OrchestrateTools {
  }
 
  #[tool(
- description = "Dispatch a brief to a new child tcode thread and return its thread id. profile is the provider-profile id from the fleet table, required when the entry names one. access is one of read_only (review/investigation: read-only actions run without prompts; anything that mutates pauses for user approval), workspace_write (edits auto-approved inside the workspace), or full (default; no approval prompts). Completed children are auto-archived after their result is delivered unless archive_on_complete: false; failed children stay visible for retries."
+ description = "Dispatch a brief to a new child tcode thread and return its thread id. profile is the provider-profile id from the fleet table, required when the entry names one. access is one of read_only (review/investigation: read-only actions run without prompts; anything that mutates pauses for user approval), workspace_write (edits auto-approved inside the workspace), or full (default; no approval prompts). worktree optionally isolates the child in tcode/<thread-id> and overrides the Orchestrate setting; the response identifies the path and branch or explains fallback. Completed children are auto-archived after their result is delivered unless archive_on_complete: false; failed children stay visible for retries."
  )]
  async fn dispatch(
  &self,
@@ -99,6 +104,7 @@ impl OrchestrateTools {
  title: p.title,
  brief: p.brief,
  cwd: p.cwd,
+ worktree: p.worktree,
  archive_on_complete: p.archive_on_complete,
  result_max_chars: p.result_max_chars,
  })

crates/protocol/src/command.rs

@@ -40,6 +40,7 @@ pub enum SettingsPatch {
  AutoArchiveKeepCount(usize),
  AutoArchiveNoticeShown(bool),
  Orchestrate(OrchestrateSettings),
+ OrchestrateChildWorktrees(bool),
  ComputerUse(ComputerUseSettings),
  Browser(BrowserSettings),
  TitleGeneration(TitleGenerationSettings),
@@ -196,6 +197,9 @@ pub enum Command {
  session_id: String,
  remove_worktree: bool,
  },
+ MergeWorktree {
+ session_id: String,
+ },
  DeleteProject {
  project_id: String,
  },

crates/protocol/src/event.rs

@@ -252,6 +252,17 @@ pub struct GitActionRequest {
  pub feature_branch: Option<String>,
 }
 
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum MergeWorktreeFailure {
+ Missing,
+ DirtyWorktree,
+ DestinationDetached,
+ DirtyDestination,
+ DivergedConflict,
+ Git,
+}
+
 #[non_exhaustive]
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(tag = "type", content = "content", rename_all = "snake_case")]
@@ -354,4 +365,10 @@ pub enum RuntimeNotice {
  skipped: Vec<String>,
  limit_reached: bool,
  },
+ WorktreeMergedFastForward,
+ WorktreeMergedCommit,
+ WorktreeMergeFailed {
+ reason: MergeWorktreeFailure,
+ detail: Option<String>,
+ },
 }

crates/protocol/src/lib.rs

@@ -12,10 +12,10 @@ mod wire;
 pub use command::{Command, CommandResponse, SettingsPatch, ThreadExportFormat};
 pub use event::{
  AcpMarketplaceItem, EventEnvelope, GitActionRequest, GitStatusStatus, IndexSnapshot,
- ProviderVersionStatus, ProvidersStatus, QueuedMessageStatus, RuntimeEffect, RuntimeError,
-RuntimeNotice, RuntimeNotification, RuntimeOperationId, RuntimeToast, ServerEvent,
- SessionEventRecord, SessionStatus, TcodeUpdateStatus, TerminalContextStatus,
- TerminalSplitStatus, TerminalStatus, Topic,
+MergeWorktreeFailure, ProviderVersionStatus, ProvidersStatus, QueuedMessageStatus,
+RuntimeEffect, RuntimeError, RuntimeNotice, RuntimeNotification, RuntimeOperationId,
+RuntimeToast, ServerEvent, SessionEventRecord, SessionStatus, TcodeUpdateStatus,
+TerminalContextStatus, TerminalSplitStatus, TerminalStatus, Topic,
 };
 pub use query::{
  ExternalThread, GitDiffResult, GitDiffScope, GitFileText, PathEntry, Query, QueryResponse,

crates/protocol/src/tests.rs

@@ -227,6 +227,11 @@ fn round_trips_top_level_wire_types() {
  });
 }
 
+#[test]
+fn orchestrate_child_worktrees_patch_round_trips() {
+ round_trip(&SettingsPatch::OrchestrateChildWorktrees(true));
+}
+
 fn assert_command_crosses_ndjson(id: u64, command: Command) {
  match &command {
  Command::ApplyPendingRelaunch => {}
@@ -275,6 +280,7 @@ fn assert_command_crosses_ndjson(id: u64, command: Command) {
  Command::AutoArchiveSweep { .. } => {}
  Command::RenameSession { .. } => {}
  Command::ForkThread { .. } => {}
+ Command::MergeWorktree { .. } => {}
  Command::DeleteSession { .. } => {}
  Command::DeleteProject { .. } => {}
  Command::MarkSessionUnread { .. } => {}

crates/runtime/src/app/mod.rs

@@ -48,20 +48,22 @@ use tcode_core::ui::{
 };
 use tcode_protocol::ThreadExportFormat;
 use tcode_protocol::{
- AcpMarketplaceItem, EventEnvelope, ExternalThread, GitStatusStatus, IndexSnapshot, PathEntry,
- ProviderVersionStatus as ProtocolProviderVersionStatus, ProvidersStatus, QueuedMessageStatus,
- RecentDir, ServerEvent, SessionEventRecord, SessionStatus, TcodeUpdateStatus,
- TerminalContextStatus, TerminalSplitStatus, TerminalStatus, Topic,
+ AcpMarketplaceItem, EventEnvelope, ExternalThread, GitStatusStatus, IndexSnapshot,
+ MergeWorktreeFailure, PathEntry, ProviderVersionStatus as ProtocolProviderVersionStatus,
+ ProvidersStatus, QueuedMessageStatus, RecentDir, ServerEvent, SessionEventRecord,
+ SessionStatus, TcodeUpdateStatus, TerminalContextStatus, TerminalSplitStatus, TerminalStatus,
+ Topic,
 };
 use tcode_services::acp_registry::{
  Registry, RegistryAgent, cached, install, load, platform_key, resolve_recipe, uninstall,
  visible_agents,
 };
 use tcode_services::export;
 use tcode_services::git::{
- CheckoutError, checkout_if_clean, cleanup_orphaned_worktrees, commit_diff_context,
- create_git_worktree, list_git_branches, perform_action, read_git_branch, read_status,
- remove_git_worktree, run_claude_headless, worktree_path_for,
+ CheckoutError, MergeWorktreeError, MergeWorktreeOutcome, checkout_if_clean,
+ cleanup_orphaned_worktrees, commit_diff_context, create_git_worktree, list_git_branches,
+ merge_worktree_back, perform_action, read_git_branch, read_status, remove_git_worktree,
+ run_claude_headless, run_git, worktree_path_for,
 };
 use tcode_services::import::{
  ExternalImportUpdate, ExternalRoots, ImportOutcome, existing_external_ids, import_thread,

crates/runtime/src/app/orchestrate.rs

@@ -252,6 +252,15 @@ impl AppState {
  result_max_chars,
  );
  meta.title = title;
+ self.install_child_session(meta, brief, cx)
+ }
+
+ fn install_child_session(
+ &mut self,
+ meta: SessionMeta,
+ brief: String,
+ cx: &mut HostCx,
+ ) -> Result<String, String> {
  self.enqueue_store_write(
  StoreWrite::UpsertMeta {
  meta: Box::new(meta.clone()),
@@ -307,6 +316,7 @@ impl AppState {
  title,
  brief,
  cwd,
+ worktree,
  archive_on_complete,
  result_max_chars,
  } => {
@@ -335,7 +345,8 @@ impl AppState {
  };
  let archive_on_complete =
  archive_on_complete.unwrap_or(self.settings.orchestrate.archive_on_complete);
- let Some(cwd) = cwd else {
+ let isolate = worktree.unwrap_or(self.settings.orchestrate.child_worktrees);
+ if cwd.is_none() && !isolate {
  let result = self
  .create_child_session(
  &parent_id,
@@ -354,17 +365,32 @@ impl AppState {
  .map(|id| serde_json::json!({ "thread_id": id }));
  let _ = reply.try_send(result);
  return;
- };
- let Some(parent_cwd) = self.find_meta(&parent_id).map(|meta| meta.cwd) else {
+ }
+ let Some(parent) = self.find_meta(&parent_id) else {
  let _ = reply.try_send(Err("unknown parent session".to_string()));
  return;
  };
- let path = PathBuf::from(cwd);
- let path = if path.is_absolute() {
+ let path = PathBuf::from(cwd.unwrap_or_default());
+ let path = if path.as_os_str().is_empty() {
+ parent.cwd.clone()
+ } else if path.is_absolute() {
  path
  } else {
-parent_cwd.join(path)
+parent.cwd.join(path)
  };
+ let mut meta = build_child_meta(
+ &parent,
+ provider,
+ Some(model),
+ effort,
+ profile_id,
+ approval_mode,
+ path.clone(),
+ archive_on_complete,
+ result_max_chars,
+ );
+ meta.title = title;
+ let child_id = meta.id.clone();
  let host_cx = cx.clone();
  HostCx::spawn_detached(cx, async move {
  let resolved_cwd = host_cx
@@ -375,30 +401,39 @@ impl AppState {
  if !canonical.is_dir() {
  return Err(format!("invalid cwd: {}", canonical.display()));
  }
- Ok(canonical)
+ if isolate {
+ Ok(resolve_child_worktree(canonical, &child_id))
+ } else {
+ Ok((canonical, None, None))
+ }
  })
  .await;
  let result = match resolved_cwd {
- Ok(cwd) => host_cx
+ Ok((cwd, worktree, warning)) => host_cx
  .enqueue_and_wait(move |state, cx| {
- state.create_child_session(
- &parent_id,
- provider,
- Some(model),
- effort,
- profile_id,
- approval_mode,
- title,
- Some(cwd),
- brief,
- archive_on_complete,
- result_max_chars,
- cx,
- )
+ meta.cwd = cwd;
+ meta.worktree = worktree;
+ let worktree_info = meta.worktree.clone();
+ state
+ .install_child_session(meta, brief, cx)
+ .map(|id| (id, worktree_info, warning))
  })
  .await
  .unwrap_or_else(|_| Err("application closed".to_string()))
- .map(|id| serde_json::json!({ "thread_id": id })),
+ .map(|(id, worktree, warning)| {
+ let mut response = serde_json::json!({ "thread_id": id });
+ if let Some(worktree) = worktree {
+ response["worktree_path"] = serde_json::json!(
+ worktree_path_for(&id).display().to_string()
+ );
+ response["worktree_branch"] =
+ serde_json::json!(worktree.branch);
+ }
+ if let Some(warning) = warning {
+ response["warning"] = serde_json::json!(warning);
+ }
+ response
+ }),
  Err(err) => Err(err),
  };
  let _ = reply.try_send(result);
@@ -1211,6 +1246,55 @@ pub(super) fn provider_name(provider: ProviderKind) -> &'static str {
  }
 }
 
+fn resolve_child_worktree(
+ cwd: PathBuf,
+ child_id: &str,
+) -> (PathBuf, Option<WorktreeInfo>, Option<String>) {
+ let repo_root = run_git(&cwd, &["rev-parse", "--show-toplevel"])
+ .ok()
+ .map(|root| PathBuf::from(root.trim()))
+ .and_then(|root| root.canonicalize().ok());
+ if repo_root.as_ref() != Some(&cwd) {
+ let warning = format!(
+ "worktree isolation unavailable: {} is not a Git repository root; using the plain cwd",
+ cwd.display()
+ );
+ log::warn!("orchestrate dispatch: {warning}");
+ return (cwd, None, Some(warning));
+ }
+
+ let base = run_git(&cwd, &["symbolic-ref", "--quiet", "--short", "HEAD"])
+ .or_else(|_| run_git(&cwd, &["rev-parse", "HEAD"]))
+ .map(|base| base.trim().to_string());
+ let base = match base {
+ Ok(base) => base,
+ Err(error) => {
+ let warning = format!(
+ "worktree isolation unavailable: could not resolve the base revision ({error}); using the plain cwd"
+ );
+ log::warn!("orchestrate dispatch: {warning}");
+ return (cwd, None, Some(warning));
+ }
+ };
+ let path = worktree_path_for(child_id);
+ let requested_branch = format!("tcode/{child_id}");
+ match create_git_worktree(&cwd, &path, &requested_branch, &base) {
+ Ok(created) => {
+ let info = WorktreeInfo {
+ root_project_path: cwd,
+ base,
+ branch: created.branch,
+ };
+ (created.path, Some(info), None)
+ }
+ Err(error) => {
+ let warning = format!("worktree isolation failed ({error}); using the plain cwd");
+ log::warn!("orchestrate dispatch: {warning}");
+ (cwd, None, Some(warning))
+ }
+ }
+}
+
 #[allow(clippy::too_many_arguments)] // mirrors the MCP dispatch schema
 pub(super) fn build_child_meta(
  parent: &SessionMeta,

crates/core/src/settings.rs

@@ -323,6 +323,10 @@ pub struct OrchestrateSettings {
  pub child_models: Vec<OrchestrateChildModel>,
  #[serde(default)]
  pub child_approval: ChildApprovalMode,
+ /// Give dispatched children dedicated Git worktrees when their resolved cwd
+ /// is itself a repository root. Dispatch-level `worktree` overrides this.
+ #[serde(default)]
+ pub child_worktrees: bool,
  /// Archive completed children automatically once their terminal result has
  /// been delivered to the parent. Per-dispatch `archive_on_complete`
  /// overrides this; failed children always stay visible for retries.
@@ -393,6 +397,7 @@ impl Default for OrchestrateSettings {
  },
  ],
  child_approval: ChildApprovalMode::default(),
+ child_worktrees: false,
  archive_on_complete: true,
  }
  }
@@ -1171,6 +1176,23 @@ mod tests {
  }
  }
 
+ #[test]
+ fn orchestrate_child_worktrees_default_false_and_round_trip() {
+ let legacy: OrchestrateSettings = serde_json::from_str("{}").unwrap();
+ assert!(!legacy.child_worktrees);
+
+ let settings = OrchestrateSettings {
+ child_worktrees: true,
+ ..Default::default()
+ };
+ let json = serde_json::to_string(&settings).unwrap();
+ assert!(json.contains(r#""child_worktrees":true"#));
+ assert_eq!(
+ serde_json::from_str::<OrchestrateSettings>(&json).unwrap(),
+ settings
+ );
+ }
+
  #[test]
  fn orchestrate_child_legacy_default_effort_alias_parses() {
  let settings: OrchestrateSettings = serde_json::from_str(

crates/orchestrate-mcp/src/lib.rs

@@ -16,6 +16,7 @@ pub enum OrchestrateOp {
  title: String,
  brief: String,
  cwd: Option<String>,
+ worktree: Option<bool>,
  archive_on_complete: Option<bool>,
  result_max_chars: Option<u32>,
  },

crates/orchestrate-mcp/src/tools.rs

@@ -28,6 +28,11 @@ struct DispatchParams {
  #[serde(default)]
  cwd: Option<String>,
  #[serde(default)]
+ #[schemars(
+ description = "Override Settings → Orchestrate child-worktree isolation for this dispatch. When true and cwd resolves to a Git repository root, the child runs on branch tcode/<thread-id> in a dedicated worktree. The response includes its path and branch. Non-Git cwd or creation failure falls back to cwd and reports a warning."
+ )]
+ worktree: Option<bool>,
+ #[serde(default)]
  #[schemars(
  description = "Override the auto-archive policy for this child. By default (per Settings → Orchestrate) a completed child is archived once its terminal result reaches you; failed children always stay visible. Set false to keep a completed child in the sidebar; send to an archived child unarchives it."
  )]
@@ -82,7 +87,7 @@ impl OrchestrateTools {
  }
 
  #[tool(
- description = "Dispatch a brief to a new child tcode thread and return its thread id. profile is the provider-profile id from the fleet table, required when the entry names one. access is one of read_only (review/investigation: read-only actions run without prompts; anything that mutates pauses for user approval), workspace_write (edits auto-approved inside the workspace), or full (default; no approval prompts). Completed children are auto-archived after their result is delivered unless archive_on_complete: false; failed children stay visible for retries."
+ description = "Dispatch a brief to a new child tcode thread and return its thread id. profile is the provider-profile id from the fleet table, required when the entry names one. access is one of read_only (review/investigation: read-only actions run without prompts; anything that mutates pauses for user approval), workspace_write (edits auto-approved inside the workspace), or full (default; no approval prompts). worktree optionally isolates the child in tcode/<thread-id> and overrides the Orchestrate setting; the response identifies the path and branch or explains fallback. Completed children are auto-archived after their result is delivered unless archive_on_complete: false; failed children stay visible for retries."
  )]
  async fn dispatch(
  &self,
@@ -99,6 +104,7 @@ impl OrchestrateTools {
  title: p.title,
  brief: p.brief,
  cwd: p.cwd,
+ worktree: p.worktree,
  archive_on_complete: p.archive_on_complete,
  result_max_chars: p.result_max_chars,
  })

crates/protocol/src/command.rs

@@ -40,6 +40,7 @@ pub enum SettingsPatch {
  AutoArchiveKeepCount(usize),
  AutoArchiveNoticeShown(bool),
  Orchestrate(OrchestrateSettings),
+ OrchestrateChildWorktrees(bool),
  ComputerUse(ComputerUseSettings),
  Browser(BrowserSettings),
  TitleGeneration(TitleGenerationSettings),
@@ -196,6 +197,9 @@ pub enum Command {
  session_id: String,
  remove_worktree: bool,
  },
+ MergeWorktree {
+ session_id: String,
+ },
  DeleteProject {
  project_id: String,
  },

crates/protocol/src/event.rs

@@ -252,6 +252,17 @@ pub struct GitActionRequest {
  pub feature_branch: Option<String>,
 }
 
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum MergeWorktreeFailure {
+ Missing,
+ DirtyWorktree,
+ DestinationDetached,
+ DirtyDestination,
+ DivergedConflict,
+ Git,
+}
+
 #[non_exhaustive]
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(tag = "type", content = "content", rename_all = "snake_case")]
@@ -354,4 +365,10 @@ pub enum RuntimeNotice {
  skipped: Vec<String>,
  limit_reached: bool,
  },
+ WorktreeMergedFastForward,
+ WorktreeMergedCommit,
+ WorktreeMergeFailed {
+ reason: MergeWorktreeFailure,
+ detail: Option<String>,
+ },
 }

crates/protocol/src/lib.rs

@@ -12,10 +12,10 @@ mod wire;
 pub use command::{Command, CommandResponse, SettingsPatch, ThreadExportFormat};
 pub use event::{
  AcpMarketplaceItem, EventEnvelope, GitActionRequest, GitStatusStatus, IndexSnapshot,
- ProviderVersionStatus, ProvidersStatus, QueuedMessageStatus, RuntimeEffect, RuntimeError,
-RuntimeNotice, RuntimeNotification, RuntimeOperationId, RuntimeToast, ServerEvent,
- SessionEventRecord, SessionStatus, TcodeUpdateStatus, TerminalContextStatus,
- TerminalSplitStatus, TerminalStatus, Topic,
+MergeWorktreeFailure, ProviderVersionStatus, ProvidersStatus, QueuedMessageStatus,
+RuntimeEffect, RuntimeError, RuntimeNotice, RuntimeNotification, RuntimeOperationId,
+RuntimeToast, ServerEvent, SessionEventRecord, SessionStatus, TcodeUpdateStatus,
+TerminalContextStatus, TerminalSplitStatus, TerminalStatus, Topic,
 };
 pub use query::{
  ExternalThread, GitDiffResult, GitDiffScope, GitFileText, PathEntry, Query, QueryResponse,

crates/protocol/src/tests.rs

@@ -227,6 +227,11 @@ fn round_trips_top_level_wire_types() {
  });
 }
 
+#[test]
+fn orchestrate_child_worktrees_patch_round_trips() {
+ round_trip(&SettingsPatch::OrchestrateChildWorktrees(true));
+}
+
 fn assert_command_crosses_ndjson(id: u64, command: Command) {
  match &command {
  Command::ApplyPendingRelaunch => {}
@@ -275,6 +280,7 @@ fn assert_command_crosses_ndjson(id: u64, command: Command) {
  Command::AutoArchiveSweep { .. } => {}
  Command::RenameSession { .. } => {}
  Command::ForkThread { .. } => {}
+ Command::MergeWorktree { .. } => {}
  Command::DeleteSession { .. } => {}
  Command::DeleteProject { .. } => {}
  Command::MarkSessionUnread { .. } => {}

crates/runtime/src/app/mod.rs

@@ -48,20 +48,22 @@ use tcode_core::ui::{
 };
 use tcode_protocol::ThreadExportFormat;
 use tcode_protocol::{
- AcpMarketplaceItem, EventEnvelope, ExternalThread, GitStatusStatus, IndexSnapshot, PathEntry,
- ProviderVersionStatus as ProtocolProviderVersionStatus, ProvidersStatus, QueuedMessageStatus,
- RecentDir, ServerEvent, SessionEventRecord, SessionStatus, TcodeUpdateStatus,
- TerminalContextStatus, TerminalSplitStatus, TerminalStatus, Topic,
+ AcpMarketplaceItem, EventEnvelope, ExternalThread, GitStatusStatus, IndexSnapshot,
+ MergeWorktreeFailure, PathEntry, ProviderVersionStatus as ProtocolProviderVersionStatus,
+ ProvidersStatus, QueuedMessageStatus, RecentDir, ServerEvent, SessionEventRecord,
+ SessionStatus, TcodeUpdateStatus, TerminalContextStatus, TerminalSplitStatus, TerminalStatus,
+ Topic,
 };
 use tcode_services::acp_registry::{
  Registry, RegistryAgent, cached, install, load, platform_key, resolve_recipe, uninstall,
  visible_agents,
 };
 use tcode_services::export;
 use tcode_services::git::{
- CheckoutError, checkout_if_clean, cleanup_orphaned_worktrees, commit_diff_context,
- create_git_worktree, list_git_branches, perform_action, read_git_branch, read_status,
- remove_git_worktree, run_claude_headless, worktree_path_for,
+ CheckoutError, MergeWorktreeError, MergeWorktreeOutcome, checkout_if_clean,
+ cleanup_orphaned_worktrees, commit_diff_context, create_git_worktree, list_git_branches,
+ merge_worktree_back, perform_action, read_git_branch, read_status, remove_git_worktree,
+ run_claude_headless, run_git, worktree_path_for,
 };
 use tcode_services::import::{
  ExternalImportUpdate, ExternalRoots, ImportOutcome, existing_external_ids, import_thread,

crates/runtime/src/app/orchestrate.rs

@@ -252,6 +252,15 @@ impl AppState {
  result_max_chars,
  );
  meta.title = title;
+ self.install_child_session(meta, brief, cx)
+ }
+
+ fn install_child_session(
+ &mut self,
+ meta: SessionMeta,
+ brief: String,
+ cx: &mut HostCx,
+ ) -> Result<String, String> {
  self.enqueue_store_write(
  StoreWrite::UpsertMeta {
  meta: Box::new(meta.clone()),
@@ -307,6 +316,7 @@ impl AppState {
  title,
  brief,
  cwd,
+ worktree,
  archive_on_complete,
  result_max_chars,
  } => {
@@ -335,7 +345,8 @@ impl AppState {
  };
  let archive_on_complete =
  archive_on_complete.unwrap_or(self.settings.orchestrate.archive_on_complete);
- let Some(cwd) = cwd else {
+ let isolate = worktree.unwrap_or(self.settings.orchestrate.child_worktrees);
+ if cwd.is_none() && !isolate {
  let result = self
  .create_child_session(
  &parent_id,
@@ -354,17 +365,32 @@ impl AppState {
  .map(|id| serde_json::json!({ "thread_id": id }));
  let _ = reply.try_send(result);
  return;
- };
- let Some(parent_cwd) = self.find_meta(&parent_id).map(|meta| meta.cwd) else {
+ }
+ let Some(parent) = self.find_meta(&parent_id) else {
  let _ = reply.try_send(Err("unknown parent session".to_string()));
  return;
  };
- let path = PathBuf::from(cwd);
- let path = if path.is_absolute() {
+ let path = PathBuf::from(cwd.unwrap_or_default());
+ let path = if path.as_os_str().is_empty() {
+ parent.cwd.clone()
+ } else if path.is_absolute() {
  path
  } else {
-parent_cwd.join(path)
+parent.cwd.join(path)
  };
+ let mut meta = build_child_meta(
+ &parent,
+ provider,
+ Some(model),
+ effort,
+ profile_id,
+ approval_mode,
+ path.clone(),
+ archive_on_complete,
+ result_max_chars,
+ );
+ meta.title = title;
+ let child_id = meta.id.clone();
  let host_cx = cx.clone();
  HostCx::spawn_detached(cx, async move {
  let resolved_cwd = host_cx
@@ -375,30 +401,39 @@ impl AppState {
  if !canonical.is_dir() {
  return Err(format!("invalid cwd: {}", canonical.display()));
  }
- Ok(canonical)
+ if isolate {
+ Ok(resolve_child_worktree(canonical, &child_id))
+ } else {
+ Ok((canonical, None, None))
+ }
  })
  .await;
  let result = match resolved_cwd {
- Ok(cwd) => host_cx
+ Ok((cwd, worktree, warning)) => host_cx
  .enqueue_and_wait(move |state, cx| {
- state.create_child_session(
- &parent_id,
- provider,
- Some(model),
- effort,
- profile_id,
- approval_mode,
- title,
- Some(cwd),
- brief,
- archive_on_complete,
- result_max_chars,
- cx,
- )
+ meta.cwd = cwd;
+ meta.worktree = worktree;
+ let worktree_info = meta.worktree.clone();
+ state
+ .install_child_session(meta, brief, cx)
+ .map(|id| (id, worktree_info, warning))
  })
  .await
  .unwrap_or_else(|_| Err("application closed".to_string()))
- .map(|id| serde_json::json!({ "thread_id": id })),
+ .map(|(id, worktree, warning)| {
+ let mut response = serde_json::json!({ "thread_id": id });
+ if let Some(worktree) = worktree {
+ response["worktree_path"] = serde_json::json!(
+ worktree_path_for(&id).display().to_string()
+ );
+ response["worktree_branch"] =
+ serde_json::json!(worktree.branch);
+ }
+ if let Some(warning) = warning {
+ response["warning"] = serde_json::json!(warning);
+ }
+ response
+ }),
  Err(err) => Err(err),
  };
  let _ = reply.try_send(result);
@@ -1211,6 +1246,55 @@ pub(super) fn provider_name(provider: ProviderKind) -> &'static str {
  }
 }
 
+fn resolve_child_worktree(
+ cwd: PathBuf,
+ child_id: &str,
+) -> (PathBuf, Option<WorktreeInfo>, Option<String>) {
+ let repo_root = run_git(&cwd, &["rev-parse", "--show-toplevel"])
+ .ok()
+ .map(|root| PathBuf::from(root.trim()))
+ .and_then(|root| root.canonicalize().ok());
+ if repo_root.as_ref() != Some(&cwd) {
+ let warning = format!(
+ "worktree isolation unavailable: {} is not a Git repository root; using the plain cwd",
+ cwd.display()
+ );
+ log::warn!("orchestrate dispatch: {warning}");
+ return (cwd, None, Some(warning));
+ }
+
+ let base = run_git(&cwd, &["symbolic-ref", "--quiet", "--short", "HEAD"])
+ .or_else(|_| run_git(&cwd, &["rev-parse", "HEAD"]))
+ .map(|base| base.trim().to_string());
+ let base = match base {
+ Ok(base) => base,
+ Err(error) => {
+ let warning = format!(
+ "worktree isolation unavailable: could not resolve the base revision ({error}); using the plain cwd"
+ );
+ log::warn!("orchestrate dispatch: {warning}");
+ return (cwd, None, Some(warning));
+ }
+ };
+ let path = worktree_path_for(child_id);
+ let requested_branch = format!("tcode/{child_id}");
+ match create_git_worktree(&cwd, &path, &requested_branch, &base) {
+ Ok(created) => {
+ let info = WorktreeInfo {
+ root_project_path: cwd,
+ base,
+ branch: created.branch,
+ };
+ (created.path, Some(info), None)
+ }
+ Err(error) => {
+ let warning = format!("worktree isolation failed ({error}); using the plain cwd");
+ log::warn!("orchestrate dispatch: {warning}");
+ (cwd, None, Some(warning))
+ }
+ }
+}
+
 #[allow(clippy::too_many_arguments)] // mirrors the MCP dispatch schema
 pub(super) fn build_child_meta(
  parent: &SessionMeta,

crates/core/src/settings.rs

@@ -323,6 +323,10 @@ pub struct OrchestrateSettings {
  pub child_models: Vec<OrchestrateChildModel>,
  #[serde(default)]
  pub child_approval: ChildApprovalMode,
+ /// Give dispatched children dedicated Git worktrees when their resolved cwd
+ /// is itself a repository root. Dispatch-level `worktree` overrides this.
+ #[serde(default)]
+ pub child_worktrees: bool,
  /// Archive completed children automatically once their terminal result has
  /// been delivered to the parent. Per-dispatch `archive_on_complete`
  /// overrides this; failed children always stay visible for retries.
@@ -393,6 +397,7 @@ impl Default for OrchestrateSettings {
  },
  ],
  child_approval: ChildApprovalMode::default(),
+ child_worktrees: false,
  archive_on_complete: true,
  }
  }
@@ -1171,6 +1176,23 @@ mod tests {
  }
  }
 
+ #[test]
+ fn orchestrate_child_worktrees_default_false_and_round_trip() {
+ let legacy: OrchestrateSettings = serde_json::from_str("{}").unwrap();
+ assert!(!legacy.child_worktrees);
+
+ let settings = OrchestrateSettings {
+ child_worktrees: true,
+ ..Default::default()
+ };
+ let json = serde_json::to_string(&settings).unwrap();
+ assert!(json.contains(r#""child_worktrees":true"#));
+ assert_eq!(
+ serde_json::from_str::<OrchestrateSettings>(&json).unwrap(),
+ settings
+ );
+ }
+
  #[test]
  fn orchestrate_child_legacy_default_effort_alias_parses() {
  let settings: OrchestrateSettings = serde_json::from_str(

crates/orchestrate-mcp/src/lib.rs

@@ -16,6 +16,7 @@ pub enum OrchestrateOp {
  title: String,
  brief: String,
  cwd: Option<String>,
+ worktree: Option<bool>,
  archive_on_complete: Option<bool>,
  result_max_chars: Option<u32>,
  },

crates/orchestrate-mcp/src/tools.rs

@@ -28,6 +28,11 @@ struct DispatchParams {
  #[serde(default)]
  cwd: Option<String>,
  #[serde(default)]
+ #[schemars(
+ description = "Override Settings → Orchestrate child-worktree isolation for this dispatch. When true and cwd resolves to a Git repository root, the child runs on branch tcode/<thread-id> in a dedicated worktree. The response includes its path and branch. Non-Git cwd or creation failure falls back to cwd and reports a warning."
+ )]
+ worktree: Option<bool>,
+ #[serde(default)]
  #[schemars(
  description = "Override the auto-archive policy for this child. By default (per Settings → Orchestrate) a completed child is archived once its terminal result reaches you; failed children always stay visible. Set false to keep a completed child in the sidebar; send to an archived child unarchives it."
  )]
@@ -82,7 +87,7 @@ impl OrchestrateTools {
  }
 
  #[tool(
- description = "Dispatch a brief to a new child tcode thread and return its thread id. profile is the provider-profile id from the fleet table, required when the entry names one. access is one of read_only (review/investigation: read-only actions run without prompts; anything that mutates pauses for user approval), workspace_write (edits auto-approved inside the workspace), or full (default; no approval prompts). Completed children are auto-archived after their result is delivered unless archive_on_complete: false; failed children stay visible for retries."
+ description = "Dispatch a brief to a new child tcode thread and return its thread id. profile is the provider-profile id from the fleet table, required when the entry names one. access is one of read_only (review/investigation: read-only actions run without prompts; anything that mutates pauses for user approval), workspace_write (edits auto-approved inside the workspace), or full (default; no approval prompts). worktree optionally isolates the child in tcode/<thread-id> and overrides the Orchestrate setting; the response identifies the path and branch or explains fallback. Completed children are auto-archived after their result is delivered unless archive_on_complete: false; failed children stay visible for retries."
  )]
  async fn dispatch(
  &self,
@@ -99,6 +104,7 @@ impl OrchestrateTools {
  title: p.title,
  brief: p.brief,
  cwd: p.cwd,
+ worktree: p.worktree,
  archive_on_complete: p.archive_on_complete,
  result_max_chars: p.result_max_chars,
  })

crates/protocol/src/command.rs

@@ -40,6 +40,7 @@ pub enum SettingsPatch {
  AutoArchiveKeepCount(usize),
  AutoArchiveNoticeShown(bool),
  Orchestrate(OrchestrateSettings),
+ OrchestrateChildWorktrees(bool),
  ComputerUse(ComputerUseSettings),
  Browser(BrowserSettings),
  TitleGeneration(TitleGenerationSettings),
@@ -196,6 +197,9 @@ pub enum Command {
  session_id: String,
  remove_worktree: bool,
  },
+ MergeWorktree {
+ session_id: String,
+ },
  DeleteProject {
  project_id: String,
  },

crates/protocol/src/event.rs

@@ -252,6 +252,17 @@ pub struct GitActionRequest {
  pub feature_branch: Option<String>,
 }
 
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum MergeWorktreeFailure {
+ Missing,
+ DirtyWorktree,
+ DestinationDetached,
+ DirtyDestination,
+ DivergedConflict,
+ Git,
+}
+
 #[non_exhaustive]
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(tag = "type", content = "content", rename_all = "snake_case")]
@@ -354,4 +365,10 @@ pub enum RuntimeNotice {
  skipped: Vec<String>,
  limit_reached: bool,
  },
+ WorktreeMergedFastForward,
+ WorktreeMergedCommit,
+ WorktreeMergeFailed {
+ reason: MergeWorktreeFailure,
+ detail: Option<String>,
+ },
 }

crates/protocol/src/lib.rs

@@ -12,10 +12,10 @@ mod wire;
 pub use command::{Command, CommandResponse, SettingsPatch, ThreadExportFormat};
 pub use event::{
  AcpMarketplaceItem, EventEnvelope, GitActionRequest, GitStatusStatus, IndexSnapshot,
- ProviderVersionStatus, ProvidersStatus, QueuedMessageStatus, RuntimeEffect, RuntimeError,
-RuntimeNotice, RuntimeNotification, RuntimeOperationId, RuntimeToast, ServerEvent,
- SessionEventRecord, SessionStatus, TcodeUpdateStatus, TerminalContextStatus,
- TerminalSplitStatus, TerminalStatus, Topic,
+MergeWorktreeFailure, ProviderVersionStatus, ProvidersStatus, QueuedMessageStatus,
+RuntimeEffect, RuntimeError, RuntimeNotice, RuntimeNotification, RuntimeOperationId,
+RuntimeToast, ServerEvent, SessionEventRecord, SessionStatus, TcodeUpdateStatus,
+TerminalContextStatus, TerminalSplitStatus, TerminalStatus, Topic,
 };
 pub use query::{
  ExternalThread, GitDiffResult, GitDiffScope, GitFileText, PathEntry, Query, QueryResponse,

crates/protocol/src/tests.rs

@@ -227,6 +227,11 @@ fn round_trips_top_level_wire_types() {
  });
 }
 
+#[test]
+fn orchestrate_child_worktrees_patch_round_trips() {
+ round_trip(&SettingsPatch::OrchestrateChildWorktrees(true));
+}
+
 fn assert_command_crosses_ndjson(id: u64, command: Command) {
  match &command {
  Command::ApplyPendingRelaunch => {}
@@ -275,6 +280,7 @@ fn assert_command_crosses_ndjson(id: u64, command: Command) {
  Command::AutoArchiveSweep { .. } => {}
  Command::RenameSession { .. } => {}
  Command::ForkThread { .. } => {}
+ Command::MergeWorktree { .. } => {}
  Command::DeleteSession { .. } => {}
  Command::DeleteProject { .. } => {}
  Command::MarkSessionUnread { .. } => {}

crates/runtime/src/app/mod.rs

@@ -48,20 +48,22 @@ use tcode_core::ui::{
 };
 use tcode_protocol::ThreadExportFormat;
 use tcode_protocol::{
- AcpMarketplaceItem, EventEnvelope, ExternalThread, GitStatusStatus, IndexSnapshot, PathEntry,
- ProviderVersionStatus as ProtocolProviderVersionStatus, ProvidersStatus, QueuedMessageStatus,
- RecentDir, ServerEvent, SessionEventRecord, SessionStatus, TcodeUpdateStatus,
- TerminalContextStatus, TerminalSplitStatus, TerminalStatus, Topic,
+ AcpMarketplaceItem, EventEnvelope, ExternalThread, GitStatusStatus, IndexSnapshot,
+ MergeWorktreeFailure, PathEntry, ProviderVersionStatus as ProtocolProviderVersionStatus,
+ ProvidersStatus, QueuedMessageStatus, RecentDir, ServerEvent, SessionEventRecord,
+ SessionStatus, TcodeUpdateStatus, TerminalContextStatus, TerminalSplitStatus, TerminalStatus,
+ Topic,
 };
 use tcode_services::acp_registry::{
  Registry, RegistryAgent, cached, install, load, platform_key, resolve_recipe, uninstall,
  visible_agents,
 };
 use tcode_services::export;
 use tcode_services::git::{
- CheckoutError, checkout_if_clean, cleanup_orphaned_worktrees, commit_diff_context,
- create_git_worktree, list_git_branches, perform_action, read_git_branch, read_status,
- remove_git_worktree, run_claude_headless, worktree_path_for,
+ CheckoutError, MergeWorktreeError, MergeWorktreeOutcome, checkout_if_clean,
+ cleanup_orphaned_worktrees, commit_diff_context, create_git_worktree, list_git_branches,
+ merge_worktree_back, perform_action, read_git_branch, read_status, remove_git_worktree,
+ run_claude_headless, run_git, worktree_path_for,
 };
 use tcode_services::import::{
  ExternalImportUpdate, ExternalRoots, ImportOutcome, existing_external_ids, import_thread,

crates/runtime/src/app/orchestrate.rs

@@ -252,6 +252,15 @@ impl AppState {
  result_max_chars,
  );
  meta.title = title;
+ self.install_child_session(meta, brief, cx)
+ }
+
+ fn install_child_session(
+ &mut self,
+ meta: SessionMeta,
+ brief: String,
+ cx: &mut HostCx,
+ ) -> Result<String, String> {
  self.enqueue_store_write(
  StoreWrite::UpsertMeta {
  meta: Box::new(meta.clone()),
@@ -307,6 +316,7 @@ impl AppState {
  title,
  brief,
  cwd,
+ worktree,
  archive_on_complete,
  result_max_chars,
  } => {
@@ -335,7 +345,8 @@ impl AppState {
  };
  let archive_on_complete =
  archive_on_complete.unwrap_or(self.settings.orchestrate.archive_on_complete);
- let Some(cwd) = cwd else {
+ let isolate = worktree.unwrap_or(self.settings.orchestrate.child_worktrees);
+ if cwd.is_none() && !isolate {
  let result = self
  .create_child_session(
  &parent_id,
@@ -354,17 +365,32 @@ impl AppState {
  .map(|id| serde_json::json!({ "thread_id": id }));
  let _ = reply.try_send(result);
  return;
- };
- let Some(parent_cwd) = self.find_meta(&parent_id).map(|meta| meta.cwd) else {
+ }
+ let Some(parent) = self.find_meta(&parent_id) else {
  let _ = reply.try_send(Err("unknown parent session".to_string()));
  return;
  };
- let path = PathBuf::from(cwd);
- let path = if path.is_absolute() {
+ let path = PathBuf::from(cwd.unwrap_or_default());
+ let path = if path.as_os_str().is_empty() {
+ parent.cwd.clone()
+ } else if path.is_absolute() {
  path
  } else {
-parent_cwd.join(path)
+parent.cwd.join(path)
  };
+ let mut meta = build_child_meta(
+ &parent,
+ provider,
+ Some(model),
+ effort,
+ profile_id,
+ approval_mode,
+ path.clone(),
+ archive_on_complete,
+ result_max_chars,
+ );
+ meta.title = title;
+ let child_id = meta.id.clone();
  let host_cx = cx.clone();
  HostCx::spawn_detached(cx, async move {
  let resolved_cwd = host_cx
@@ -375,30 +401,39 @@ impl AppState {
  if !canonical.is_dir() {
  return Err(format!("invalid cwd: {}", canonical.display()));
  }
- Ok(canonical)
+ if isolate {
+ Ok(resolve_child_worktree(canonical, &child_id))
+ } else {
+ Ok((canonical, None, None))
+ }
  })
  .await;
  let result = match resolved_cwd {
- Ok(cwd) => host_cx
+ Ok((cwd, worktree, warning)) => host_cx
  .enqueue_and_wait(move |state, cx| {
- state.create_child_session(
- &parent_id,
- provider,
- Some(model),
- effort,
- profile_id,
- approval_mode,
- title,
- Some(cwd),
- brief,
- archive_on_complete,
- result_max_chars,
- cx,
- )
+ meta.cwd = cwd;
+ meta.worktree = worktree;
+ let worktree_info = meta.worktree.clone();
+ state
+ .install_child_session(meta, brief, cx)
+ .map(|id| (id, worktree_info, warning))
  })
  .await
  .unwrap_or_else(|_| Err("application closed".to_string()))
- .map(|id| serde_json::json!({ "thread_id": id })),
+ .map(|(id, worktree, warning)| {
+ let mut response = serde_json::json!({ "thread_id": id });
+ if let Some(worktree) = worktree {
+ response["worktree_path"] = serde_json::json!(
+ worktree_path_for(&id).display().to_string()
+ );
+ response["worktree_branch"] =
+ serde_json::json!(worktree.branch);
+ }
+ if let Some(warning) = warning {
+ response["warning"] = serde_json::json!(warning);
+ }
+ response
+ }),
  Err(err) => Err(err),
  };
  let _ = reply.try_send(result);
@@ -1211,6 +1246,55 @@ pub(super) fn provider_name(provider: ProviderKind) -> &'static str {
  }
 }
 
+fn resolve_child_worktree(
+ cwd: PathBuf,
+ child_id: &str,
+) -> (PathBuf, Option<WorktreeInfo>, Option<String>) {
+ let repo_root = run_git(&cwd, &["rev-parse", "--show-toplevel"])
+ .ok()
+ .map(|root| PathBuf::from(root.trim()))
+ .and_then(|root| root.canonicalize().ok());
+ if repo_root.as_ref() != Some(&cwd) {
+ let warning = format!(
+ "worktree isolation unavailable: {} is not a Git repository root; using the plain cwd",
+ cwd.display()
+ );
+ log::warn!("orchestrate dispatch: {warning}");
+ return (cwd, None, Some(warning));
+ }
+
+ let base = run_git(&cwd, &["symbolic-ref", "--quiet", "--short", "HEAD"])
+ .or_else(|_| run_git(&cwd, &["rev-parse", "HEAD"]))
+ .map(|base| base.trim().to_string());
+ let base = match base {
+ Ok(base) => base,
+ Err(error) => {
+ let warning = format!(
+ "worktree isolation unavailable: could not resolve the base revision ({error}); using the plain cwd"
+ );
+ log::warn!("orchestrate dispatch: {warning}");
+ return (cwd, None, Some(warning));
+ }
+ };
+ let path = worktree_path_for(child_id);
+ let requested_branch = format!("tcode/{child_id}");
+ match create_git_worktree(&cwd, &path, &requested_branch, &base) {
+ Ok(created) => {
+ let info = WorktreeInfo {
+ root_project_path: cwd,
+ base,
+ branch: created.branch,
+ };
+ (created.path, Some(info), None)
+ }
+ Err(error) => {
+ let warning = format!("worktree isolation failed ({error}); using the plain cwd");
+ log::warn!("orchestrate dispatch: {warning}");
+ (cwd, None, Some(warning))
+ }
+ }
+}
+
 #[allow(clippy::too_many_arguments)] // mirrors the MCP dispatch schema
 pub(super) fn build_child_meta(
  parent: &SessionMeta,

crates/core/src/settings.rs

@@ -323,6 +323,10 @@ pub struct OrchestrateSettings {
  pub child_models: Vec<OrchestrateChildModel>,
  #[serde(default)]
  pub child_approval: ChildApprovalMode,
+ /// Give dispatched children dedicated Git worktrees when their resolved cwd
+ /// is itself a repository root. Dispatch-level `worktree` overrides this.
+ #[serde(default)]
+ pub child_worktrees: bool,
  /// Archive completed children automatically once their terminal result has
  /// been delivered to the parent. Per-dispatch `archive_on_complete`
  /// overrides this; failed children always stay visible for retries.
@@ -393,6 +397,7 @@ impl Default for OrchestrateSettings {
  },
  ],
  child_approval: ChildApprovalMode::default(),
+ child_worktrees: false,
  archive_on_complete: true,
  }
  }
@@ -1171,6 +1176,23 @@ mod tests {
  }
  }
 
+ #[test]
+ fn orchestrate_child_worktrees_default_false_and_round_trip() {
+ let legacy: OrchestrateSettings = serde_json::from_str("{}").unwrap();
+ assert!(!legacy.child_worktrees);
+
+ let settings = OrchestrateSettings {
+ child_worktrees: true,
+ ..Default::default()
+ };
+ let json = serde_json::to_string(&settings).unwrap();
+ assert!(json.contains(r#""child_worktrees":true"#));
+ assert_eq!(
+ serde_json::from_str::<OrchestrateSettings>(&json).unwrap(),
+ settings
+ );
+ }
+
  #[test]
  fn orchestrate_child_legacy_default_effort_alias_parses() {
  let settings: OrchestrateSettings = serde_json::from_str(

crates/orchestrate-mcp/src/lib.rs

@@ -16,6 +16,7 @@ pub enum OrchestrateOp {
  title: String,
  brief: String,
  cwd: Option<String>,
+ worktree: Option<bool>,
  archive_on_complete: Option<bool>,
  result_max_chars: Option<u32>,
  },

crates/orchestrate-mcp/src/tools.rs

@@ -28,6 +28,11 @@ struct DispatchParams {
  #[serde(default)]
  cwd: Option<String>,
  #[serde(default)]
+ #[schemars(
+ description = "Override Settings → Orchestrate child-worktree isolation for this dispatch. When true and cwd resolves to a Git repository root, the child runs on branch tcode/<thread-id> in a dedicated worktree. The response includes its path and branch. Non-Git cwd or creation failure falls back to cwd and reports a warning."
+ )]
+ worktree: Option<bool>,
+ #[serde(default)]
  #[schemars(
  description = "Override the auto-archive policy for this child. By default (per Settings → Orchestrate) a completed child is archived once its terminal result reaches you; failed children always stay visible. Set false to keep a completed child in the sidebar; send to an archived child unarchives it."
  )]
@@ -82,7 +87,7 @@ impl OrchestrateTools {
  }
 
  #[tool(
- description = "Dispatch a brief to a new child tcode thread and return its thread id. profile is the provider-profile id from the fleet table, required when the entry names one. access is one of read_only (review/investigation: read-only actions run without prompts; anything that mutates pauses for user approval), workspace_write (edits auto-approved inside the workspace), or full (default; no approval prompts). Completed children are auto-archived after their result is delivered unless archive_on_complete: false; failed children stay visible for retries."
+ description = "Dispatch a brief to a new child tcode thread and return its thread id. profile is the provider-profile id from the fleet table, required when the entry names one. access is one of read_only (review/investigation: read-only actions run without prompts; anything that mutates pauses for user approval), workspace_write (edits auto-approved inside the workspace), or full (default; no approval prompts). worktree optionally isolates the child in tcode/<thread-id> and overrides the Orchestrate setting; the response identifies the path and branch or explains fallback. Completed children are auto-archived after their result is delivered unless archive_on_complete: false; failed children stay visible for retries."
  )]
  async fn dispatch(
  &self,
@@ -99,6 +104,7 @@ impl OrchestrateTools {
  title: p.title,
  brief: p.brief,
  cwd: p.cwd,
+ worktree: p.worktree,
  archive_on_complete: p.archive_on_complete,
  result_max_chars: p.result_max_chars,
  })

crates/protocol/src/command.rs

@@ -40,6 +40,7 @@ pub enum SettingsPatch {
  AutoArchiveKeepCount(usize),
  AutoArchiveNoticeShown(bool),
  Orchestrate(OrchestrateSettings),
+ OrchestrateChildWorktrees(bool),
  ComputerUse(ComputerUseSettings),
  Browser(BrowserSettings),
  TitleGeneration(TitleGenerationSettings),
@@ -196,6 +197,9 @@ pub enum Command {
  session_id: String,
  remove_worktree: bool,
  },
+ MergeWorktree {
+ session_id: String,
+ },
  DeleteProject {
  project_id: String,
  },

crates/protocol/src/event.rs

@@ -252,6 +252,17 @@ pub struct GitActionRequest {
  pub feature_branch: Option<String>,
 }
 
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum MergeWorktreeFailure {
+ Missing,
+ DirtyWorktree,
+ DestinationDetached,
+ DirtyDestination,
+ DivergedConflict,
+ Git,
+}
+
 #[non_exhaustive]
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(tag = "type", content = "content", rename_all = "snake_case")]
@@ -354,4 +365,10 @@ pub enum RuntimeNotice {
  skipped: Vec<String>,
  limit_reached: bool,
  },
+ WorktreeMergedFastForward,
+ WorktreeMergedCommit,
+ WorktreeMergeFailed {
+ reason: MergeWorktreeFailure,
+ detail: Option<String>,
+ },
 }

crates/protocol/src/lib.rs

@@ -12,10 +12,10 @@ mod wire;
 pub use command::{Command, CommandResponse, SettingsPatch, ThreadExportFormat};
 pub use event::{
  AcpMarketplaceItem, EventEnvelope, GitActionRequest, GitStatusStatus, IndexSnapshot,
- ProviderVersionStatus, ProvidersStatus, QueuedMessageStatus, RuntimeEffect, RuntimeError,
-RuntimeNotice, RuntimeNotification, RuntimeOperationId, RuntimeToast, ServerEvent,
- SessionEventRecord, SessionStatus, TcodeUpdateStatus, TerminalContextStatus,
- TerminalSplitStatus, TerminalStatus, Topic,
+MergeWorktreeFailure, ProviderVersionStatus, ProvidersStatus, QueuedMessageStatus,
+RuntimeEffect, RuntimeError, RuntimeNotice, RuntimeNotification, RuntimeOperationId,
+RuntimeToast, ServerEvent, SessionEventRecord, SessionStatus, TcodeUpdateStatus,
+TerminalContextStatus, TerminalSplitStatus, TerminalStatus, Topic,
 };
 pub use query::{
  ExternalThread, GitDiffResult, GitDiffScope, GitFileText, PathEntry, Query, QueryResponse,

crates/protocol/src/tests.rs

@@ -227,6 +227,11 @@ fn round_trips_top_level_wire_types() {
  });
 }
 
+#[test]
+fn orchestrate_child_worktrees_patch_round_trips() {
+ round_trip(&SettingsPatch::OrchestrateChildWorktrees(true));
+}
+
 fn assert_command_crosses_ndjson(id: u64, command: Command) {
  match &command {
  Command::ApplyPendingRelaunch => {}
@@ -275,6 +280,7 @@ fn assert_command_crosses_ndjson(id: u64, command: Command) {
  Command::AutoArchiveSweep { .. } => {}
  Command::RenameSession { .. } => {}
  Command::ForkThread { .. } => {}
+ Command::MergeWorktree { .. } => {}
  Command::DeleteSession { .. } => {}
  Command::DeleteProject { .. } => {}
  Command::MarkSessionUnread { .. } => {}

crates/runtime/src/app/mod.rs

@@ -48,20 +48,22 @@ use tcode_core::ui::{
 };
 use tcode_protocol::ThreadExportFormat;
 use tcode_protocol::{
- AcpMarketplaceItem, EventEnvelope, ExternalThread, GitStatusStatus, IndexSnapshot, PathEntry,
- ProviderVersionStatus as ProtocolProviderVersionStatus, ProvidersStatus, QueuedMessageStatus,
- RecentDir, ServerEvent, SessionEventRecord, SessionStatus, TcodeUpdateStatus,
- TerminalContextStatus, TerminalSplitStatus, TerminalStatus, Topic,
+ AcpMarketplaceItem, EventEnvelope, ExternalThread, GitStatusStatus, IndexSnapshot,
+ MergeWorktreeFailure, PathEntry, ProviderVersionStatus as ProtocolProviderVersionStatus,
+ ProvidersStatus, QueuedMessageStatus, RecentDir, ServerEvent, SessionEventRecord,
+ SessionStatus, TcodeUpdateStatus, TerminalContextStatus, TerminalSplitStatus, TerminalStatus,
+ Topic,
 };
 use tcode_services::acp_registry::{
  Registry, RegistryAgent, cached, install, load, platform_key, resolve_recipe, uninstall,
  visible_agents,
 };
 use tcode_services::export;
 use tcode_services::git::{
- CheckoutError, checkout_if_clean, cleanup_orphaned_worktrees, commit_diff_context,
- create_git_worktree, list_git_branches, perform_action, read_git_branch, read_status,
- remove_git_worktree, run_claude_headless, worktree_path_for,
+ CheckoutError, MergeWorktreeError, MergeWorktreeOutcome, checkout_if_clean,
+ cleanup_orphaned_worktrees, commit_diff_context, create_git_worktree, list_git_branches,
+ merge_worktree_back, perform_action, read_git_branch, read_status, remove_git_worktree,
+ run_claude_headless, run_git, worktree_path_for,
 };
 use tcode_services::import::{
  ExternalImportUpdate, ExternalRoots, ImportOutcome, existing_external_ids, import_thread,

crates/runtime/src/app/orchestrate.rs

@@ -252,6 +252,15 @@ impl AppState {
  result_max_chars,
  );
  meta.title = title;
+ self.install_child_session(meta, brief, cx)
+ }
+
+ fn install_child_session(
+ &mut self,
+ meta: SessionMeta,
+ brief: String,
+ cx: &mut HostCx,
+ ) -> Result<String, String> {
  self.enqueue_store_write(
  StoreWrite::UpsertMeta {
  meta: Box::new(meta.clone()),
@@ -307,6 +316,7 @@ impl AppState {
  title,
  brief,
  cwd,
+ worktree,
  archive_on_complete,
  result_max_chars,
  } => {
@@ -335,7 +345,8 @@ impl AppState {
  };
  let archive_on_complete =
  archive_on_complete.unwrap_or(self.settings.orchestrate.archive_on_complete);
- let Some(cwd) = cwd else {
+ let isolate = worktree.unwrap_or(self.settings.orchestrate.child_worktrees);
+ if cwd.is_none() && !isolate {
  let result = self
  .create_child_session(
  &parent_id,
@@ -354,17 +365,32 @@ impl AppState {
  .map(|id| serde_json::json!({ "thread_id": id }));
  let _ = reply.try_send(result);
  return;
- };
- let Some(parent_cwd) = self.find_meta(&parent_id).map(|meta| meta.cwd) else {
+ }
+ let Some(parent) = self.find_meta(&parent_id) else {
  let _ = reply.try_send(Err("unknown parent session".to_string()));
  return;
  };
- let path = PathBuf::from(cwd);
- let path = if path.is_absolute() {
+ let path = PathBuf::from(cwd.unwrap_or_default());
+ let path = if path.as_os_str().is_empty() {
+ parent.cwd.clone()
+ } else if path.is_absolute() {
  path
  } else {
-parent_cwd.join(path)
+parent.cwd.join(path)
  };
+ let mut meta = build_child_meta(
+ &parent,
+ provider,
+ Some(model),
+ effort,
+ profile_id,
+ approval_mode,
+ path.clone(),
+ archive_on_complete,
+ result_max_chars,
+ );
+ meta.title = title;
+ let child_id = meta.id.clone();
  let host_cx = cx.clone();
  HostCx::spawn_detached(cx, async move {
  let resolved_cwd = host_cx
@@ -375,30 +401,39 @@ impl AppState {
  if !canonical.is_dir() {
  return Err(format!("invalid cwd: {}", canonical.display()));
  }
- Ok(canonical)
+ if isolate {
+ Ok(resolve_child_worktree(canonical, &child_id))
+ } else {
+ Ok((canonical, None, None))
+ }
  })
  .await;
  let result = match resolved_cwd {
- Ok(cwd) => host_cx
+ Ok((cwd, worktree, warning)) => host_cx
  .enqueue_and_wait(move |state, cx| {
- state.create_child_session(
- &parent_id,
- provider,
- Some(model),
- effort,
- profile_id,
- approval_mode,
- title,
- Some(cwd),
- brief,
- archive_on_complete,
- result_max_chars,
- cx,
- )
+ meta.cwd = cwd;
+ meta.worktree = worktree;
+ let worktree_info = meta.worktree.clone();
+ state
+ .install_child_session(meta, brief, cx)
+ .map(|id| (id, worktree_info, warning))
  })
  .await
  .unwrap_or_else(|_| Err("application closed".to_string()))
- .map(|id| serde_json::json!({ "thread_id": id })),
+ .map(|(id, worktree, warning)| {
+ let mut response = serde_json::json!({ "thread_id": id });
+ if let Some(worktree) = worktree {
+ response["worktree_path"] = serde_json::json!(
+ worktree_path_for(&id).display().to_string()
+ );
+ response["worktree_branch"] =
+ serde_json::json!(worktree.branch);
+ }
+ if let Some(warning) = warning {
+ response["warning"] = serde_json::json!(warning);
+ }
+ response
+ }),
  Err(err) => Err(err),
  };
  let _ = reply.try_send(result);
@@ -1211,6 +1246,55 @@ pub(super) fn provider_name(provider: ProviderKind) -> &'static str {
  }
 }
 
+fn resolve_child_worktree(
+ cwd: PathBuf,
+ child_id: &str,
+) -> (PathBuf, Option<WorktreeInfo>, Option<String>) {
+ let repo_root = run_git(&cwd, &["rev-parse", "--show-toplevel"])
+ .ok()
+ .map(|root| PathBuf::from(root.trim()))
+ .and_then(|root| root.canonicalize().ok());
+ if repo_root.as_ref() != Some(&cwd) {
+ let warning = format!(
+ "worktree isolation unavailable: {} is not a Git repository root; using the plain cwd",
+ cwd.display()
+ );
+ log::warn!("orchestrate dispatch: {warning}");
+ return (cwd, None, Some(warning));
+ }
+
+ let base = run_git(&cwd, &["symbolic-ref", "--quiet", "--short", "HEAD"])
+ .or_else(|_| run_git(&cwd, &["rev-parse", "HEAD"]))
+ .map(|base| base.trim().to_string());
+ let base = match base {
+ Ok(base) => base,
+ Err(error) => {
+ let warning = format!(
+ "worktree isolation unavailable: could not resolve the base revision ({error}); using the plain cwd"
+ );
+ log::warn!("orchestrate dispatch: {warning}");
+ return (cwd, None, Some(warning));
+ }
+ };
+ let path = worktree_path_for(child_id);
+ let requested_branch = format!("tcode/{child_id}");
+ match create_git_worktree(&cwd, &path, &requested_branch, &base) {
+ Ok(created) => {
+ let info = WorktreeInfo {
+ root_project_path: cwd,
+ base,
+ branch: created.branch,
+ };
+ (created.path, Some(info), None)
+ }
+ Err(error) => {
+ let warning = format!("worktree isolation failed ({error}); using the plain cwd");
+ log::warn!("orchestrate dispatch: {warning}");
+ (cwd, None, Some(warning))
+ }
+ }
+}
+
 #[allow(clippy::too_many_arguments)] // mirrors the MCP dispatch schema
 pub(super) fn build_child_meta(
  parent: &SessionMeta,

crates/core/src/settings.rs

@@ -323,6 +323,10 @@ pub struct OrchestrateSettings {
  pub child_models: Vec<OrchestrateChildModel>,
  #[serde(default)]
  pub child_approval: ChildApprovalMode,
+ /// Give dispatched children dedicated Git worktrees when their resolved cwd
+ /// is itself a repository root. Dispatch-level `worktree` overrides this.
+ #[serde(default)]
+ pub child_worktrees: bool,
  /// Archive completed children automatically once their terminal result has
  /// been delivered to the parent. Per-dispatch `archive_on_complete`
  /// overrides this; failed children always stay visible for retries.
@@ -393,6 +397,7 @@ impl Default for OrchestrateSettings {
  },
  ],
  child_approval: ChildApprovalMode::default(),
+ child_worktrees: false,
  archive_on_complete: true,
  }
  }
@@ -1171,6 +1176,23 @@ mod tests {
  }
  }
 
+ #[test]
+ fn orchestrate_child_worktrees_default_false_and_round_trip() {
+ let legacy: OrchestrateSettings = serde_json::from_str("{}").unwrap();
+ assert!(!legacy.child_worktrees);
+
+ let settings = OrchestrateSettings {
+ child_worktrees: true,
+ ..Default::default()
+ };
+ let json = serde_json::to_string(&settings).unwrap();
+ assert!(json.contains(r#""child_worktrees":true"#));
+ assert_eq!(
+ serde_json::from_str::<OrchestrateSettings>(&json).unwrap(),
+ settings
+ );
+ }
+
  #[test]
  fn orchestrate_child_legacy_default_effort_alias_parses() {
  let settings: OrchestrateSettings = serde_json::from_str(

crates/orchestrate-mcp/src/lib.rs

@@ -16,6 +16,7 @@ pub enum OrchestrateOp {
  title: String,
  brief: String,
  cwd: Option<String>,
+ worktree: Option<bool>,
  archive_on_complete: Option<bool>,
  result_max_chars: Option<u32>,
  },

crates/orchestrate-mcp/src/tools.rs

@@ -28,6 +28,11 @@ struct DispatchParams {
  #[serde(default)]
  cwd: Option<String>,
  #[serde(default)]
+ #[schemars(
+ description = "Override Settings → Orchestrate child-worktree isolation for this dispatch. When true and cwd resolves to a Git repository root, the child runs on branch tcode/<thread-id> in a dedicated worktree. The response includes its path and branch. Non-Git cwd or creation failure falls back to cwd and reports a warning."
+ )]
+ worktree: Option<bool>,
+ #[serde(default)]
  #[schemars(
  description = "Override the auto-archive policy for this child. By default (per Settings → Orchestrate) a completed child is archived once its terminal result reaches you; failed children always stay visible. Set false to keep a completed child in the sidebar; send to an archived child unarchives it."
  )]
@@ -82,7 +87,7 @@ impl OrchestrateTools {
  }
 
  #[tool(
- description = "Dispatch a brief to a new child tcode thread and return its thread id. profile is the provider-profile id from the fleet table, required when the entry names one. access is one of read_only (review/investigation: read-only actions run without prompts; anything that mutates pauses for user approval), workspace_write (edits auto-approved inside the workspace), or full (default; no approval prompts). Completed children are auto-archived after their result is delivered unless archive_on_complete: false; failed children stay visible for retries."
+ description = "Dispatch a brief to a new child tcode thread and return its thread id. profile is the provider-profile id from the fleet table, required when the entry names one. access is one of read_only (review/investigation: read-only actions run without prompts; anything that mutates pauses for user approval), workspace_write (edits auto-approved inside the workspace), or full (default; no approval prompts). worktree optionally isolates the child in tcode/<thread-id> and overrides the Orchestrate setting; the response identifies the path and branch or explains fallback. Completed children are auto-archived after their result is delivered unless archive_on_complete: false; failed children stay visible for retries."
  )]
  async fn dispatch(
  &self,
@@ -99,6 +104,7 @@ impl OrchestrateTools {
  title: p.title,
  brief: p.brief,
  cwd: p.cwd,
+ worktree: p.worktree,
  archive_on_complete: p.archive_on_complete,
  result_max_chars: p.result_max_chars,
  })

crates/protocol/src/command.rs

@@ -40,6 +40,7 @@ pub enum SettingsPatch {
  AutoArchiveKeepCount(usize),
  AutoArchiveNoticeShown(bool),
  Orchestrate(OrchestrateSettings),
+ OrchestrateChildWorktrees(bool),
  ComputerUse(ComputerUseSettings),
  Browser(BrowserSettings),
  TitleGeneration(TitleGenerationSettings),
@@ -196,6 +197,9 @@ pub enum Command {
  session_id: String,
  remove_worktree: bool,
  },
+ MergeWorktree {
+ session_id: String,
+ },
  DeleteProject {
  project_id: String,
  },

crates/protocol/src/event.rs

@@ -252,6 +252,17 @@ pub struct GitActionRequest {
  pub feature_branch: Option<String>,
 }
 
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum MergeWorktreeFailure {
+ Missing,
+ DirtyWorktree,
+ DestinationDetached,
+ DirtyDestination,
+ DivergedConflict,
+ Git,
+}
+
 #[non_exhaustive]
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(tag = "type", content = "content", rename_all = "snake_case")]
@@ -354,4 +365,10 @@ pub enum RuntimeNotice {
  skipped: Vec<String>,
  limit_reached: bool,
  },
+ WorktreeMergedFastForward,
+ WorktreeMergedCommit,
+ WorktreeMergeFailed {
+ reason: MergeWorktreeFailure,
+ detail: Option<String>,
+ },
 }

crates/protocol/src/lib.rs

@@ -12,10 +12,10 @@ mod wire;
 pub use command::{Command, CommandResponse, SettingsPatch, ThreadExportFormat};
 pub use event::{
  AcpMarketplaceItem, EventEnvelope, GitActionRequest, GitStatusStatus, IndexSnapshot,
- ProviderVersionStatus, ProvidersStatus, QueuedMessageStatus, RuntimeEffect, RuntimeError,
-RuntimeNotice, RuntimeNotification, RuntimeOperationId, RuntimeToast, ServerEvent,
- SessionEventRecord, SessionStatus, TcodeUpdateStatus, TerminalContextStatus,
- TerminalSplitStatus, TerminalStatus, Topic,
+MergeWorktreeFailure, ProviderVersionStatus, ProvidersStatus, QueuedMessageStatus,
+RuntimeEffect, RuntimeError, RuntimeNotice, RuntimeNotification, RuntimeOperationId,
+RuntimeToast, ServerEvent, SessionEventRecord, SessionStatus, TcodeUpdateStatus,
+TerminalContextStatus, TerminalSplitStatus, TerminalStatus, Topic,
 };
 pub use query::{
  ExternalThread, GitDiffResult, GitDiffScope, GitFileText, PathEntry, Query, QueryResponse,

crates/protocol/src/tests.rs

@@ -227,6 +227,11 @@ fn round_trips_top_level_wire_types() {
  });
 }
 
+#[test]
+fn orchestrate_child_worktrees_patch_round_trips() {
+ round_trip(&SettingsPatch::OrchestrateChildWorktrees(true));
+}
+
 fn assert_command_crosses_ndjson(id: u64, command: Command) {
  match &command {
  Command::ApplyPendingRelaunch => {}
@@ -275,6 +280,7 @@ fn assert_command_crosses_ndjson(id: u64, command: Command) {
  Command::AutoArchiveSweep { .. } => {}
  Command::RenameSession { .. } => {}
  Command::ForkThread { .. } => {}
+ Command::MergeWorktree { .. } => {}
  Command::DeleteSession { .. } => {}
  Command::DeleteProject { .. } => {}
  Command::MarkSessionUnread { .. } => {}

crates/runtime/src/app/mod.rs

@@ -48,20 +48,22 @@ use tcode_core::ui::{
 };
 use tcode_protocol::ThreadExportFormat;
 use tcode_protocol::{
- AcpMarketplaceItem, EventEnvelope, ExternalThread, GitStatusStatus, IndexSnapshot, PathEntry,
- ProviderVersionStatus as ProtocolProviderVersionStatus, ProvidersStatus, QueuedMessageStatus,
- RecentDir, ServerEvent, SessionEventRecord, SessionStatus, TcodeUpdateStatus,
- TerminalContextStatus, TerminalSplitStatus, TerminalStatus, Topic,
+ AcpMarketplaceItem, EventEnvelope, ExternalThread, GitStatusStatus, IndexSnapshot,
+ MergeWorktreeFailure, PathEntry, ProviderVersionStatus as ProtocolProviderVersionStatus,
+ ProvidersStatus, QueuedMessageStatus, RecentDir, ServerEvent, SessionEventRecord,
+ SessionStatus, TcodeUpdateStatus, TerminalContextStatus, TerminalSplitStatus, TerminalStatus,
+ Topic,
 };
 use tcode_services::acp_registry::{
  Registry, RegistryAgent, cached, install, load, platform_key, resolve_recipe, uninstall,
  visible_agents,
 };
 use tcode_services::export;
 use tcode_services::git::{
- CheckoutError, checkout_if_clean, cleanup_orphaned_worktrees, commit_diff_context,
- create_git_worktree, list_git_branches, perform_action, read_git_branch, read_status,
- remove_git_worktree, run_claude_headless, worktree_path_for,
+ CheckoutError, MergeWorktreeError, MergeWorktreeOutcome, checkout_if_clean,
+ cleanup_orphaned_worktrees, commit_diff_context, create_git_worktree, list_git_branches,
+ merge_worktree_back, perform_action, read_git_branch, read_status, remove_git_worktree,
+ run_claude_headless, run_git, worktree_path_for,
 };
 use tcode_services::import::{
  ExternalImportUpdate, ExternalRoots, ImportOutcome, existing_external_ids, import_thread,

crates/runtime/src/app/orchestrate.rs

@@ -252,6 +252,15 @@ impl AppState {
  result_max_chars,
  );
  meta.title = title;
+ self.install_child_session(meta, brief, cx)
+ }
+
+ fn install_child_session(
+ &mut self,
+ meta: SessionMeta,
+ brief: String,
+ cx: &mut HostCx,
+ ) -> Result<String, String> {
  self.enqueue_store_write(
  StoreWrite::UpsertMeta {
  meta: Box::new(meta.clone()),
@@ -307,6 +316,7 @@ impl AppState {
  title,
  brief,
  cwd,
+ worktree,
  archive_on_complete,
  result_max_chars,
  } => {
@@ -335,7 +345,8 @@ impl AppState {
  };
  let archive_on_complete =
  archive_on_complete.unwrap_or(self.settings.orchestrate.archive_on_complete);
- let Some(cwd) = cwd else {
+ let isolate = worktree.unwrap_or(self.settings.orchestrate.child_worktrees);
+ if cwd.is_none() && !isolate {
  let result = self
  .create_child_session(
  &parent_id,
@@ -354,17 +365,32 @@ impl AppState {
  .map(|id| serde_json::json!({ "thread_id": id }));
  let _ = reply.try_send(result);
  return;
- };
- let Some(parent_cwd) = self.find_meta(&parent_id).map(|meta| meta.cwd) else {
+ }
+ let Some(parent) = self.find_meta(&parent_id) else {
  let _ = reply.try_send(Err("unknown parent session".to_string()));
  return;
  };
- let path = PathBuf::from(cwd);
- let path = if path.is_absolute() {
+ let path = PathBuf::from(cwd.unwrap_or_default());
+ let path = if path.as_os_str().is_empty() {
+ parent.cwd.clone()
+ } else if path.is_absolute() {
  path
  } else {
-parent_cwd.join(path)
+parent.cwd.join(path)
  };
+ let mut meta = build_child_meta(
+ &parent,
+ provider,
+ Some(model),
+ effort,
+ profile_id,
+ approval_mode,
+ path.clone(),
+ archive_on_complete,
+ result_max_chars,
+ );
+ meta.title = title;
+ let child_id = meta.id.clone();
  let host_cx = cx.clone();
  HostCx::spawn_detached(cx, async move {
  let resolved_cwd = host_cx
@@ -375,30 +401,39 @@ impl AppState {
  if !canonical.is_dir() {
  return Err(format!("invalid cwd: {}", canonical.display()));
  }
- Ok(canonical)
+ if isolate {
+ Ok(resolve_child_worktree(canonical, &child_id))
+ } else {
+ Ok((canonical, None, None))
+ }
  })
  .await;
  let result = match resolved_cwd {
- Ok(cwd) => host_cx
+ Ok((cwd, worktree, warning)) => host_cx
  .enqueue_and_wait(move |state, cx| {
- state.create_child_session(
- &parent_id,
- provider,
- Some(model),
- effort,
- profile_id,
- approval_mode,
- title,
- Some(cwd),
- brief,
- archive_on_complete,
- result_max_chars,
- cx,
- )
+ meta.cwd = cwd;
+ meta.worktree = worktree;
+ let worktree_info = meta.worktree.clone();
+ state
+ .install_child_session(meta, brief, cx)
+ .map(|id| (id, worktree_info, warning))
  })
  .await
  .unwrap_or_else(|_| Err("application closed".to_string()))
- .map(|id| serde_json::json!({ "thread_id": id })),
+ .map(|(id, worktree, warning)| {
+ let mut response = serde_json::json!({ "thread_id": id });
+ if let Some(worktree) = worktree {
+ response["worktree_path"] = serde_json::json!(
+ worktree_path_for(&id).display().to_string()
+ );
+ response["worktree_branch"] =
+ serde_json::json!(worktree.branch);
+ }
+ if let Some(warning) = warning {
+ response["warning"] = serde_json::json!(warning);
+ }
+ response
+ }),
  Err(err) => Err(err),
  };
  let _ = reply.try_send(result);
@@ -1211,6 +1246,55 @@ pub(super) fn provider_name(provider: ProviderKind) -> &'static str {
  }
 }
 
+fn resolve_child_worktree(
+ cwd: PathBuf,
+ child_id: &str,
+) -> (PathBuf, Option<WorktreeInfo>, Option<String>) {
+ let repo_root = run_git(&cwd, &["rev-parse", "--show-toplevel"])
+ .ok()
+ .map(|root| PathBuf::from(root.trim()))
+ .and_then(|root| root.canonicalize().ok());
+ if repo_root.as_ref() != Some(&cwd) {
+ let warning = format!(
+ "worktree isolation unavailable: {} is not a Git repository root; using the plain cwd",
+ cwd.display()
+ );
+ log::warn!("orchestrate dispatch: {warning}");
+ return (cwd, None, Some(warning));
+ }
+
+ let base = run_git(&cwd, &["symbolic-ref", "--quiet", "--short", "HEAD"])
+ .or_else(|_| run_git(&cwd, &["rev-parse", "HEAD"]))
+ .map(|base| base.trim().to_string());
+ let base = match base {
+ Ok(base) => base,
+ Err(error) => {
+ let warning = format!(
+ "worktree isolation unavailable: could not resolve the base revision ({error}); using the plain cwd"
+ );
+ log::warn!("orchestrate dispatch: {warning}");
+ return (cwd, None, Some(warning));
+ }
+ };
+ let path = worktree_path_for(child_id);
+ let requested_branch = format!("tcode/{child_id}");
+ match create_git_worktree(&cwd, &path, &requested_branch, &base) {
+ Ok(created) => {
+ let info = WorktreeInfo {
+ root_project_path: cwd,
+ base,
+ branch: created.branch,
+ };
+ (created.path, Some(info), None)
+ }
+ Err(error) => {
+ let warning = format!("worktree isolation failed ({error}); using the plain cwd");
+ log::warn!("orchestrate dispatch: {warning}");
+ (cwd, None, Some(warning))
+ }
+ }
+}
+
 #[allow(clippy::too_many_arguments)] // mirrors the MCP dispatch schema
 pub(super) fn build_child_meta(
  parent: &SessionMeta,

crates/core/src/settings.rs

@@ -323,6 +323,10 @@ pub struct OrchestrateSettings {
  pub child_models: Vec<OrchestrateChildModel>,
  #[serde(default)]
  pub child_approval: ChildApprovalMode,
+ /// Give dispatched children dedicated Git worktrees when their resolved cwd
+ /// is itself a repository root. Dispatch-level `worktree` overrides this.
+ #[serde(default)]
+ pub child_worktrees: bool,
  /// Archive completed children automatically once their terminal result has
  /// been delivered to the parent. Per-dispatch `archive_on_complete`
  /// overrides this; failed children always stay visible for retries.
@@ -393,6 +397,7 @@ impl Default for OrchestrateSettings {
  },
  ],
  child_approval: ChildApprovalMode::default(),
+ child_worktrees: false,
  archive_on_complete: true,
  }
  }
@@ -1171,6 +1176,23 @@ mod tests {
  }
  }
 
+ #[test]
+ fn orchestrate_child_worktrees_default_false_and_round_trip() {
+ let legacy: OrchestrateSettings = serde_json::from_str("{}").unwrap();
+ assert!(!legacy.child_worktrees);
+
+ let settings = OrchestrateSettings {
+ child_worktrees: true,
+ ..Default::default()
+ };
+ let json = serde_json::to_string(&settings).unwrap();
+ assert!(json.contains(r#""child_worktrees":true"#));
+ assert_eq!(
+ serde_json::from_str::<OrchestrateSettings>(&json).unwrap(),
+ settings
+ );
+ }
+
  #[test]
  fn orchestrate_child_legacy_default_effort_alias_parses() {
  let settings: OrchestrateSettings = serde_json::from_str(

crates/orchestrate-mcp/src/lib.rs

@@ -16,6 +16,7 @@ pub enum OrchestrateOp {
  title: String,
  brief: String,
  cwd: Option<String>,
+ worktree: Option<bool>,
  archive_on_complete: Option<bool>,
  result_max_chars: Option<u32>,
  },

crates/orchestrate-mcp/src/tools.rs

@@ -28,6 +28,11 @@ struct DispatchParams {
  #[serde(default)]
  cwd: Option<String>,
  #[serde(default)]
+ #[schemars(
+ description = "Override Settings → Orchestrate child-worktree isolation for this dispatch. When true and cwd resolves to a Git repository root, the child runs on branch tcode/<thread-id> in a dedicated worktree. The response includes its path and branch. Non-Git cwd or creation failure falls back to cwd and reports a warning."
+ )]
+ worktree: Option<bool>,
+ #[serde(default)]
  #[schemars(
  description = "Override the auto-archive policy for this child. By default (per Settings → Orchestrate) a completed child is archived once its terminal result reaches you; failed children always stay visible. Set false to keep a completed child in the sidebar; send to an archived child unarchives it."
  )]
@@ -82,7 +87,7 @@ impl OrchestrateTools {
  }
 
  #[tool(
- description = "Dispatch a brief to a new child tcode thread and return its thread id. profile is the provider-profile id from the fleet table, required when the entry names one. access is one of read_only (review/investigation: read-only actions run without prompts; anything that mutates pauses for user approval), workspace_write (edits auto-approved inside the workspace), or full (default; no approval prompts). Completed children are auto-archived after their result is delivered unless archive_on_complete: false; failed children stay visible for retries."
+ description = "Dispatch a brief to a new child tcode thread and return its thread id. profile is the provider-profile id from the fleet table, required when the entry names one. access is one of read_only (review/investigation: read-only actions run without prompts; anything that mutates pauses for user approval), workspace_write (edits auto-approved inside the workspace), or full (default; no approval prompts). worktree optionally isolates the child in tcode/<thread-id> and overrides the Orchestrate setting; the response identifies the path and branch or explains fallback. Completed children are auto-archived after their result is delivered unless archive_on_complete: false; failed children stay visible for retries."
  )]
  async fn dispatch(
  &self,
@@ -99,6 +104,7 @@ impl OrchestrateTools {
  title: p.title,
  brief: p.brief,
  cwd: p.cwd,
+ worktree: p.worktree,
  archive_on_complete: p.archive_on_complete,
  result_max_chars: p.result_max_chars,
  })

crates/protocol/src/command.rs

@@ -40,6 +40,7 @@ pub enum SettingsPatch {
  AutoArchiveKeepCount(usize),
  AutoArchiveNoticeShown(bool),
  Orchestrate(OrchestrateSettings),
+ OrchestrateChildWorktrees(bool),
  ComputerUse(ComputerUseSettings),
  Browser(BrowserSettings),
  TitleGeneration(TitleGenerationSettings),
@@ -196,6 +197,9 @@ pub enum Command {
  session_id: String,
  remove_worktree: bool,
  },
+ MergeWorktree {
+ session_id: String,
+ },
  DeleteProject {
  project_id: String,
  },

crates/protocol/src/event.rs

@@ -252,6 +252,17 @@ pub struct GitActionRequest {
  pub feature_branch: Option<String>,
 }
 
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum MergeWorktreeFailure {
+ Missing,
+ DirtyWorktree,
+ DestinationDetached,
+ DirtyDestination,
+ DivergedConflict,
+ Git,
+}
+
 #[non_exhaustive]
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(tag = "type", content = "content", rename_all = "snake_case")]
@@ -354,4 +365,10 @@ pub enum RuntimeNotice {
  skipped: Vec<String>,
  limit_reached: bool,
  },
+ WorktreeMergedFastForward,
+ WorktreeMergedCommit,
+ WorktreeMergeFailed {
+ reason: MergeWorktreeFailure,
+ detail: Option<String>,
+ },
 }

crates/protocol/src/lib.rs

@@ -12,10 +12,10 @@ mod wire;
 pub use command::{Command, CommandResponse, SettingsPatch, ThreadExportFormat};
 pub use event::{
  AcpMarketplaceItem, EventEnvelope, GitActionRequest, GitStatusStatus, IndexSnapshot,
- ProviderVersionStatus, ProvidersStatus, QueuedMessageStatus, RuntimeEffect, RuntimeError,
-RuntimeNotice, RuntimeNotification, RuntimeOperationId, RuntimeToast, ServerEvent,
- SessionEventRecord, SessionStatus, TcodeUpdateStatus, TerminalContextStatus,
- TerminalSplitStatus, TerminalStatus, Topic,
+MergeWorktreeFailure, ProviderVersionStatus, ProvidersStatus, QueuedMessageStatus,
+RuntimeEffect, RuntimeError, RuntimeNotice, RuntimeNotification, RuntimeOperationId,
+RuntimeToast, ServerEvent, SessionEventRecord, SessionStatus, TcodeUpdateStatus,
+TerminalContextStatus, TerminalSplitStatus, TerminalStatus, Topic,
 };
 pub use query::{
  ExternalThread, GitDiffResult, GitDiffScope, GitFileText, PathEntry, Query, QueryResponse,

crates/protocol/src/tests.rs

@@ -227,6 +227,11 @@ fn round_trips_top_level_wire_types() {
  });
 }
 
+#[test]
+fn orchestrate_child_worktrees_patch_round_trips() {
+ round_trip(&SettingsPatch::OrchestrateChildWorktrees(true));
+}
+
 fn assert_command_crosses_ndjson(id: u64, command: Command) {
  match &command {
  Command::ApplyPendingRelaunch => {}
@@ -275,6 +280,7 @@ fn assert_command_crosses_ndjson(id: u64, command: Command) {
  Command::AutoArchiveSweep { .. } => {}
  Command::RenameSession { .. } => {}
  Command::ForkThread { .. } => {}
+ Command::MergeWorktree { .. } => {}
  Command::DeleteSession { .. } => {}
  Command::DeleteProject { .. } => {}
  Command::MarkSessionUnread { .. } => {}

crates/runtime/src/app/mod.rs

@@ -48,20 +48,22 @@ use tcode_core::ui::{
 };
 use tcode_protocol::ThreadExportFormat;
 use tcode_protocol::{
- AcpMarketplaceItem, EventEnvelope, ExternalThread, GitStatusStatus, IndexSnapshot, PathEntry,
- ProviderVersionStatus as ProtocolProviderVersionStatus, ProvidersStatus, QueuedMessageStatus,
- RecentDir, ServerEvent, SessionEventRecord, SessionStatus, TcodeUpdateStatus,
- TerminalContextStatus, TerminalSplitStatus, TerminalStatus, Topic,
+ AcpMarketplaceItem, EventEnvelope, ExternalThread, GitStatusStatus, IndexSnapshot,
+ MergeWorktreeFailure, PathEntry, ProviderVersionStatus as ProtocolProviderVersionStatus,
+ ProvidersStatus, QueuedMessageStatus, RecentDir, ServerEvent, SessionEventRecord,
+ SessionStatus, TcodeUpdateStatus, TerminalContextStatus, TerminalSplitStatus, TerminalStatus,
+ Topic,
 };
 use tcode_services::acp_registry::{
  Registry, RegistryAgent, cached, install, load, platform_key, resolve_recipe, uninstall,
  visible_agents,
 };
 use tcode_services::export;
 use tcode_services::git::{
- CheckoutError, checkout_if_clean, cleanup_orphaned_worktrees, commit_diff_context,
- create_git_worktree, list_git_branches, perform_action, read_git_branch, read_status,
- remove_git_worktree, run_claude_headless, worktree_path_for,
+ CheckoutError, MergeWorktreeError, MergeWorktreeOutcome, checkout_if_clean,
+ cleanup_orphaned_worktrees, commit_diff_context, create_git_worktree, list_git_branches,
+ merge_worktree_back, perform_action, read_git_branch, read_status, remove_git_worktree,
+ run_claude_headless, run_git, worktree_path_for,
 };
 use tcode_services::import::{
  ExternalImportUpdate, ExternalRoots, ImportOutcome, existing_external_ids, import_thread,

crates/runtime/src/app/orchestrate.rs

@@ -252,6 +252,15 @@ impl AppState {
  result_max_chars,
  );
  meta.title = title;
+ self.install_child_session(meta, brief, cx)
+ }
+
+ fn install_child_session(
+ &mut self,
+ meta: SessionMeta,
+ brief: String,
+ cx: &mut HostCx,
+ ) -> Result<String, String> {
  self.enqueue_store_write(
  StoreWrite::UpsertMeta {
  meta: Box::new(meta.clone()),
@@ -307,6 +316,7 @@ impl AppState {
  title,
  brief,
  cwd,
+ worktree,
  archive_on_complete,
  result_max_chars,
  } => {
@@ -335,7 +345,8 @@ impl AppState {
  };
  let archive_on_complete =
  archive_on_complete.unwrap_or(self.settings.orchestrate.archive_on_complete);
- let Some(cwd) = cwd else {
+ let isolate = worktree.unwrap_or(self.settings.orchestrate.child_worktrees);
+ if cwd.is_none() && !isolate {
  let result = self
  .create_child_session(
  &parent_id,
@@ -354,17 +365,32 @@ impl AppState {
  .map(|id| serde_json::json!({ "thread_id": id }));
  let _ = reply.try_send(result);
  return;
- };
- let Some(parent_cwd) = self.find_meta(&parent_id).map(|meta| meta.cwd) else {
+ }
+ let Some(parent) = self.find_meta(&parent_id) else {
  let _ = reply.try_send(Err("unknown parent session".to_string()));
  return;
  };
- let path = PathBuf::from(cwd);
- let path = if path.is_absolute() {
+ let path = PathBuf::from(cwd.unwrap_or_default());
+ let path = if path.as_os_str().is_empty() {
+ parent.cwd.clone()
+ } else if path.is_absolute() {
  path
  } else {
-parent_cwd.join(path)
+parent.cwd.join(path)
  };
+ let mut meta = build_child_meta(
+ &parent,
+ provider,
+ Some(model),
+ effort,
+ profile_id,
+ approval_mode,
+ path.clone(),
+ archive_on_complete,
+ result_max_chars,
+ );
+ meta.title = title;
+ let child_id = meta.id.clone();
  let host_cx = cx.clone();
  HostCx::spawn_detached(cx, async move {
  let resolved_cwd = host_cx
@@ -375,30 +401,39 @@ impl AppState {
  if !canonical.is_dir() {
  return Err(format!("invalid cwd: {}", canonical.display()));
  }
- Ok(canonical)
+ if isolate {
+ Ok(resolve_child_worktree(canonical, &child_id))
+ } else {
+ Ok((canonical, None, None))
+ }
  })
  .await;
  let result = match resolved_cwd {
- Ok(cwd) => host_cx
+ Ok((cwd, worktree, warning)) => host_cx
  .enqueue_and_wait(move |state, cx| {
- state.create_child_session(
- &parent_id,
- provider,
- Some(model),
- effort,
- profile_id,
- approval_mode,
- title,
- Some(cwd),
- brief,
- archive_on_complete,
- result_max_chars,
- cx,
- )
+ meta.cwd = cwd;
+ meta.worktree = worktree;
+ let worktree_info = meta.worktree.clone();
+ state
+ .install_child_session(meta, brief, cx)
+ .map(|id| (id, worktree_info, warning))
  })
  .await
  .unwrap_or_else(|_| Err("application closed".to_string()))
- .map(|id| serde_json::json!({ "thread_id": id })),
+ .map(|(id, worktree, warning)| {
+ let mut response = serde_json::json!({ "thread_id": id });
+ if let Some(worktree) = worktree {
+ response["worktree_path"] = serde_json::json!(
+ worktree_path_for(&id).display().to_string()
+ );
+ response["worktree_branch"] =
+ serde_json::json!(worktree.branch);
+ }
+ if let Some(warning) = warning {
+ response["warning"] = serde_json::json!(warning);
+ }
+ response
+ }),
  Err(err) => Err(err),
  };
  let _ = reply.try_send(result);
@@ -1211,6 +1246,55 @@ pub(super) fn provider_name(provider: ProviderKind) -> &'static str {
  }
 }
 
+fn resolve_child_worktree(
+ cwd: PathBuf,
+ child_id: &str,
+) -> (PathBuf, Option<WorktreeInfo>, Option<String>) {
+ let repo_root = run_git(&cwd, &["rev-parse", "--show-toplevel"])
+ .ok()
+ .map(|root| PathBuf::from(root.trim()))
+ .and_then(|root| root.canonicalize().ok());
+ if repo_root.as_ref() != Some(&cwd) {
+ let warning = format!(
+ "worktree isolation unavailable: {} is not a Git repository root; using the plain cwd",
+ cwd.display()
+ );
+ log::warn!("orchestrate dispatch: {warning}");
+ return (cwd, None, Some(warning));
+ }
+
+ let base = run_git(&cwd, &["symbolic-ref", "--quiet", "--short", "HEAD"])
+ .or_else(|_| run_git(&cwd, &["rev-parse", "HEAD"]))
+ .map(|base| base.trim().to_string());
+ let base = match base {
+ Ok(base) => base,
+ Err(error) => {
+ let warning = format!(
+ "worktree isolation unavailable: could not resolve the base revision ({error}); using the plain cwd"
+ );
+ log::warn!("orchestrate dispatch: {warning}");
+ return (cwd, None, Some(warning));
+ }
+ };
+ let path = worktree_path_for(child_id);
+ let requested_branch = format!("tcode/{child_id}");
+ match create_git_worktree(&cwd, &path, &requested_branch, &base) {
+ Ok(created) => {
+ let info = WorktreeInfo {
+ root_project_path: cwd,
+ base,
+ branch: created.branch,
+ };
+ (created.path, Some(info), None)
+ }
+ Err(error) => {
+ let warning = format!("worktree isolation failed ({error}); using the plain cwd");
+ log::warn!("orchestrate dispatch: {warning}");
+ (cwd, None, Some(warning))
+ }
+ }
+}
+
 #[allow(clippy::too_many_arguments)] // mirrors the MCP dispatch schema
 pub(super) fn build_child_meta(
  parent: &SessionMeta,