/cao-session-management

name: cao-session-management
description: Find available CAO (CLI Agent Orchestrator) agent profiles, and talk to the
  conductor and worker terminals of a running CAO session, including unblocking a stuck
  worker. Use when choosing a profile to launch, messaging or unblocking workers, or
  diagnosing a stuck session. For preflight, launching, session commands, statuses,
  delegation and safety, run `cao --skill` first.

CAO Session Management

Operating CAO

Run `cao --skill` for the CAO operating guide: preflight, launch, session commands, statuses, delegation, and safety. Run `cao <group> --help` for exact syntax.

Two rules apply to every launch from an agent:

• Use `--auto-approve`. It skips the confirmation prompt and leaves the profile's tool

policy unchanged; whether that policy is enforced depends on the provider (read the `Enforcement:` line launch prints). `--yolo` also skips the prompt but removes all tool restrictions, so the agent can run any command, including `aws`, `rm` and `curl`. Use `--yolo` only when the user asks for it.

• If a `cao` command cannot reach the server, check it with

`curl -sf http://localhost:9889/health`.

A reported status is inferred from the rendered terminal screen, so it can disagree with reality. Before reporting readiness, progress, or completion to a user, corroborate the status with an output read; see [cao-session-liveness](../cao-session-liveness/SKILL.md).

Discovering Available Profiles

Profiles are CAO-level entities, installed with `cao install` regardless of which CLI provider runs them. To find available profiles:

| Source | Command | |--------|---------| | All available profiles, with the source each one resolved from | `cao profile list` (no server needed), or `curl -sf http://localhost:9889/agents/profiles` | | Profiles matching a keyword | `cao profile find "<keywords>"` | | Custom/local profile files only | `ls ~/.aws/cli-agent-orchestrator/agent-store/` | | Profiles installed via `cao install <name>` | `ls ~/.aws/cli-agent-orchestrator/agent-context/` | | Profile installation and keyword discovery | see [Agent profile installation](../../docs/agent-profile.md#installation) and [profile discovery](../../docs/agent-profile.md#profile-discovery) | | Provider-native list (`kiro_cli` only) | `kiro-cli agent list`, useful because CAO mirrors profiles into `~/.kiro/agents/` |

`cao profile list` and the HTTP endpoint return the same list. Discovery scans the local store (`agent-store/`) first, then provider-specific directories (including `agent-context/`), then extra directories from settings, and the built-in packaged store last. The first match wins, so a local copy of a profile shadows the built-in one with the same name. Each entry has a `source` label showing where it came from.

A profile runs on its frontmatter `provider:` unless `--provider` overrides it; the default is `kiro_cli`. Run `cao install --help` for the provider IDs.

If unsure which profile to use, ask the user rather than guessing.

Worker Communication

Inside a session, the conductor talks to workers via two MCP tools, described below.

**Prefer communicating through the conductor** (`cao session send SESSION "msg"`) rather than directly to worker terminals. Bypassing the conductor leaves it without state on what was asked or answered, which causes confusion. Two exceptions: unblocking a stuck worker, and follow-up questions to a persistent async worker (see below).

**handoff** (blocking) — conductor sends task and waits for the worker to reach `COMPLETED` status, then reads the output. If it times out, the worker is still running — the conductor just stopped waiting.

**assign** (non-blocking) — conductor sends task and returns immediately. The worker is expected to call `send_message` back to the conductor's terminal ID when done. Each terminal only knows its own ID via `$CAO_TERMINAL_ID`.

By default the conductor uses sync (handoff). You can override this by explicitly asking it to use async or sync protocol when sending it a task.

Async workers (assign) stay alive after completing their task and can answer follow-up questions — useful for ongoing investigation where you want to keep querying the same worker. In this case, sending directly to the worker terminal is appropriate:

cao session send SESSION "<follow-up question>" --terminal <worker-terminal-id>

Kiro SOP Workflows

For SOP-driven work on the `kiro_cli` provider, send `/prompts` to discover the available SOPs, then the matched SOP name prefixed with `@` (for example `@my-sop-name`), then the task. Send each as a separate message, and wait for `completed` status between them.

Common Mistakes

**Wrong working directory** — agents won't find files, builds fail with confusing errors. Pass an absolute path in single quotes to `--working-directory`. A wrong path cannot be fixed without shutting down and relaunching; ask the user if the path is unclear.

**Launching with `--yolo` to avoid prompts** — `--auto-approve` already skips the confirmation prompt. `--yolo` additionally removes every tool restriction, which the task almost never needs.

**Stuck conductor** — conductor is waiting on a worker that stopped responding. Check the worker's status first, then decide: prompt it to continue and send results back, or ask it to resend if it already finished. Never re-delegate work that may still be running — it risks duplicate work.

cao session status SESSION --workers
cao session status SESSION --terminal <worker-terminal-id>
cao session send SESSION "continue your work, then send results to terminal <conductor-terminal-id>" --terminal <worker-terminal-id>

Get the conductor's terminal ID from `cao session status SESSION --json`.