Working Directory Support

March 12, 2026 ยท View on GitHub

CAO supports specifying working directories for agent handoff/delegation operations.

Configuration

Enable working directory parameter in MCP tools:

export CAO_ENABLE_WORKING_DIRECTORY=true

Behavior

  • When disabled (default): Working directory parameter is hidden from tools, agents start in supervisor's current directory
  • When enabled: Tools expose working_directory parameter, allowing explicit directory specification
  • Default directory: Current working directory (cwd) of the supervisor agent

Usage Example

With CAO_ENABLE_WORKING_DIRECTORY=true:

# Handoff to agent in specific package directory
result = await handoff(
    agent_profile="developer",
    message="Fix the bug in UserService.java",
    working_directory="/workspace/src/MyPackage"
)

# Assign task with specific working directory
result = await assign(
    agent_profile="reviewer",
    message="Review the changes in the authentication module",
    working_directory="/workspace/src/AuthModule"
)

Path Validation and Security

All working directory paths are canonicalized and validated before use. Paths are resolved via os.path.realpath to normalize symlinks and .. sequences.

Allowed directories

  • The user's home directory and any subdirectory (~/projects/foo)
  • External volumes and mount points (e.g., /Volumes/workplace/project)
  • Custom paths like /opt/projects, NFS mounts, corporate dev desktops
  • Any real directory that is not a blocked system path

Blocked (unsafe) directories

The following system directories are explicitly blocked:

/, /bin, /sbin, /usr/bin, /usr/sbin, /etc, /var, /tmp, /dev, /proc, /sys, /root, /boot, /lib, /lib64

On macOS, /private/etc, /private/var, and /private/tmp are also blocked (since /etc -> /private/etc, etc.).

Symlinks are resolved at validation time. A symlink pointing to a blocked system path (e.g., ~/escape -> /etc) is rejected after resolution.

Why Disabled by Default?

When the working_directory parameter is visible to agents, they may hallucinate or incorrectly infer directory paths instead of using the default (current working directory). Disabling by default prevents this behavior for users who don't need explicit directory control. If your workflow requires delegating tasks to specific directories, enable this feature and provide explicit paths in your agent instructions.