Feature Request: Provider-Agnostic Worktree-Based Workflows

Overview

Add first-class support for Git worktree-based workflows in CAO, enabling supervisors to launch and coordinate worker agents in isolated Git worktrees. The CAO server should manage worktree creation and registration, and the integration should work across all supported CLI providers (Kiro CLI, Claude Code, Codex, Q CLI) without relying on any provider-native worktree mechanism.

User Stories

• As a supervisor agent, I want to launch worker agents in isolated Git worktrees so that parallel feature development does not cause branch conflicts or file-system race conditions.
• As a CAO user, I want to pass --enable-worktrees (and optionally --worktree-path) to cao launch so that every downstream handoff or assign call automatically provisions a worktree for the spawned worker.
• As a CAO user, I want to specify a custom root directory for worktrees so that I can control where worktrees are stored, independent of any provider-specific default paths (e.g. .claude/worktrees).
• As a worker agent, I want my working_directory to be set to the root of my dedicated worktree so that all file operations and tool calls are naturally scoped to my branch.
• As a CAO user, I want a cao worktrees clean command so that I can explicitly remove worktrees that are no longer needed, with full visibility and control over what gets deleted.

Acceptance Criteria

• cao launch accepts --enable-worktrees (boolean flag) and --worktree-path <path> (optional, defaults to <repo-root>/.cao/worktrees) CLI options.
• When --enable-worktrees is set, the CAO server creates a new Git worktree for each worker spawned via handoff or assign MCP tools, branching off the current HEAD.
• The worktree path passed to the spawned worker's working_directory is the newly created worktree root.
• The supervisor can optionally pass worktree: true (or equivalent) as part of the handoff/assign payload to request a worktree even without the global flag.
• Worktree base path is configurable: users can provide an absolute path; relative paths are resolved against the current repository root.
• The feature works correctly for all registered providers (Kiro CLI, Claude Code, Codex, Q CLI) without requiring any provider-specific flag or worktree support.
• A new cao worktrees clean command removes worktrees managed by CAO (optionally all, or scoped by session/terminal ID), running git worktree remove --force for each.
• A new worktree_service.py module encapsulates all Git worktree operations (create, list, remove), making it easy to unit test independently of the rest of CAO.
• Unit test coverage for the new service and any modifications to existing modules is ≥ 60%.
• Documentation is updated in docs/ to describe the worktree workflow and the new CLI flags.

Proposed Solution

• Introduce a worktree service in the CAO server responsible for creating and removing Git worktrees via standard git worktree commands.
• Extend cao launch with --enable-worktrees and an optional --worktree-path flag. When enabled, the server automatically provisions a dedicated worktree for each worker spawned via handoff or assign, and sets it as the worker's working directory.
• Extend the handoff and assign MCP tools with an optional use_worktree field, allowing a supervisor to request a worktree on a per-call basis even without the global launch flag.
• Add a cao worktrees clean CLI command that lets users explicitly remove worktrees managed by CAO, with options to scope by session, terminal, or clean all at once.
• Update documentation to describe the worktree workflow, new flags, and an example multi-agent flow.

Additional Context

Is your feature request related to a problem? Please describe.

Currently, when a supervisor spawns multiple workers via handoff or assign, all workers share the same Git branch and working directory. Running parallel agents that each commit distinct changes leads to merge conflicts, overwritten files, and race conditions that are difficult to debug. The only provider-level workaround today is the Claude Code --worktree flag, but that flag stores worktrees in a hard-coded .claude/worktrees path with no ability to customize the location, and it is entirely provider-specific, offering no consistent solution for users of Kiro CLI, Codex, or Q CLI.

Describe alternatives you've considered

• Provider-native worktree support (e.g., claude --worktree): Claude Code CLI exposes a --worktree flag, but it unconditionally stores worktrees under .claude/worktrees and does not support specifying a custom root. More critically, this approach is provider-specific — it cannot serve users running Kiro CLI, Codex, or Q CLI without duplicating logic in every provider integration. Accepting this limitation would cement a dependency on Claude Code's opinionated directory structure and prevent a consistent multi-provider worktree experience.
• Requiring users to manually create worktrees before launching agents: This places undue operational burden on users and breaks the automated orchestration model that CAO is designed around, as worktree paths would need to be tracked and passed manually to each spawned worker.