--- 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 --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 ""` | | Custom/local profile files only | `ls ~/.aws/cli-agent-orchestrator/agent-store/` | | Profiles installed via `cao install ` | `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: ```bash cao session send SESSION "" --terminal ``` ## 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. ```bash cao session status SESSION --workers cao session status SESSION --terminal cao session send SESSION "continue your work, then send results to terminal " --terminal ``` Get the conductor's terminal ID from `cao session status SESSION --json`.