Merge origin/main (Phase A of plugin migration)

Pulls in PR #172 plugin system and PR #193 opencode_cli so later
phases can build plugins instead of provider hooks.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: fanhongy

CHANGELOG.md

@@ -10,16 +10,51 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - **Persistent agent memory system** — Agents can now store and recall knowledge across sessions using `memory_store`, `memory_recall`, and `memory_forget` MCP tools. Memories are scoped to `global`, `project`, `session`, or `agent` and stored as wiki markdown files under `~/.aws/cli-agent-orchestrator/memory/`. CAO automatically injects relevant memories as `<cao-memory>` context at session start. Includes CLI commands (`cao memory list/show/delete/clear`), auto-save hooks for Claude Code (Stop + PreCompact) and Kiro CLI (AgentSpawn + UserPromptSubmit), tiered retention, and concurrent-write safety via file locking. See [docs/memory.md](docs/memory.md).
+- **OpenCode CLI provider** — Full integration with [OpenCode](https://opencode.ai), a terminal-based AI assistant whose native agent format (Markdown + YAML frontmatter) maps directly onto CAO profiles. Supports `cao install --provider opencode_cli`, all five terminal states (IDLE, PROCESSING, COMPLETED, WAITING_USER_ANSWER, ERROR), permission translation from CAO `allowedTools` to OpenCode `permission:` frontmatter, MCP server wiring via a CAO-owned `opencode.json`, and config isolation from the user's personal OpenCode setup. CAO's on-disk config directory for OpenCode is `~/.aws/opencode/` — users who installed an earlier pre-release build (which used `~/.aws/opencode_cli`) must re-run `cao install --provider opencode_cli` to populate the new location. The old directory can be removed with: `rm -rf ~/.aws/opencode_cli`. Provider docs: [`docs/opencode-cli.md`](docs/opencode-cli.md).
+
+## [2.1.0] - 2026-04-22
+
+### Added
+
+- **`cao session` command group + HTTP-based CLI refactor (#187)** — New `cao session list | status | send` commands for inspecting and driving running sessions from the CLI. `cao shutdown` and `cao launch` now go through the HTTP API instead of direct service calls, enabling a local CLI to drive a remote `cao-server`. `cao launch` also gains `--working-directory` and an optional trailing `message` argument for one-shot headless task execution. New `cao-session-management` skill documents the command group for LLM-driven operators.
+- **External plugins support (#172)** — Observer/hook plugins can now be installed via pip and auto-discovered through the `cao.plugins` entry point group. Plugins subclass `CaoPlugin` and register handlers with the `@hook` decorator. See [docs/plugins.md](docs/plugins.md).
+- **Skills system (#145, #154, #170)** — Native support for reusable agent skills installed to `~/.cao/skills/` via `cao skill add`. New `cao-provider` skill guides contributors through adding new CLI agent providers; `cao-supervisor-protocols` and `cao-worker-protocols` seeded via `cao init`. Managed-skills section added to README.
+- **Kiro CLI full TUI mode + `--legacy-ui` fallback (#138, #163)** — Support for Kiro CLI's new full-screen TUI alongside the legacy prompt; `--legacy-ui` flag preserved for compatibility.
+- **Agent-profile environment variable injection (#156)** — Agent profiles can declare `env` entries that are loaded into the agent process at launch, with secret-aware handling via `~/.cao/.env`.
+- **`allowedTools` universal tool restriction (#125, #144)** — Unified CAO tool-restriction vocabulary translated per-provider, replacing provider-specific allow/deny flags. Child agents honor explicit `allowedTools=["*"]` instead of silently inheriting parent restrictions.
+- **Web UI bundled in Python wheel (#169)** — Built Web UI assets now ship inside the wheel, so `uv tool install git+https://github.com/awslabs/cli-agent-orchestrator.git` gives you the dashboard with no extra build steps.
 
 ### Changed
 
-- **Launch prompt clarity + `--auto-approve`** — Redesign the `cao launch` confirmation prompt to show `Role` instead of `Blocked`, clearly distinguish `[Y]` / `[--auto-approve]` / `[--yolo]`, and add `--auto-approve` flag to skip the prompt without removing restrictions (for automated flows, scripts, and agent-to-agent launches)
+- **Launch prompt clarity + `--auto-approve` (#146)** — Redesigned the `cao launch` confirmation prompt to show `Role` instead of `Blocked`, clearly distinguish `[Y]` / `[--auto-approve]` / `[--yolo]`, and added `--auto-approve` flag to skip the prompt without removing restrictions (for automated flows, scripts, and agent-to-agent launches).
 
 ### Fixed
 
-- **Kiro CLI new TUI support** — Add fallback detection patterns for the new Kiro CLI TUI prompt format (`ask a question, or describe a task`), ensuring CAO works even if `--legacy-ui` is removed in a future version
-- **Agent profile exception handling (#137)** — Fix `load_agent_profile()` wrapping `FileNotFoundError` as `RuntimeError`, which caused `assign()` to fail for JSON-only agent profiles (AIM-installed kiro-cli agents). Callers now receive `FileNotFoundError` directly and handle it gracefully
-- **Missing providers in Web UI (#157)** — Add `gemini_cli`, `kimi_cli`, and `copilot_cli` to the `/agents/providers` endpoint and frontend fallback list so all 7 providers appear in the Web UI dropdown
+- **Terminal-service cleanup guard (#191)** — `_create_terminal` no longer kills sessions it didn't create during rollback: the cleanup path now tracks whether this call actually created the tmux session (`session_created` fact) instead of the `new_session` intent flag. Prevents collateral damage to pre-existing sessions when terminal creation fails partway through.
+- **Claude Code false-positive IDLE on shell prompt (#190)** — Initialize-time status check could return IDLE against the pre-existing zsh/bash `❯` prompt before Claude Code actually started. Added pre-launch pane snapshot + Claude-specific startup markers to confirm the CLI is actually running before accepting IDLE.
+- **Claude Code structural PROCESSING detection (#177)** — `get_status()` now uses structural detection for PROCESSING instead of relying on `❯` position, eliminating a race where the spinner and prompt interleaved mid-capture.
+- **Stale processing spinners no longer block Claude Code inbox delivery (#106)** — The inbox watchdog no longer gets stuck on lingering spinner output after a response completes, so messages to Claude Code workers are delivered reliably.
+- **Profile-level `model` honored at terminal creation (#189)** — Providers now pass `profile.model` through to the CLI at launch, so per-agent model selection works end-to-end.
+- **Kiro CLI 2.0 Credits-before-separator layout (#188)** — Status detection updated for the new Kiro TUI layout where the credits line appears before the separator.
+- **Kiro CLI position-aware "Kiro is working" check (#185)** — Stale scrollback could leave "Kiro is working" in the capture after completion and block handoffs with a false PROCESSING; detection is now position-aware to the latest interaction.
+- **Kiro CLI new TUI fallback patterns (#140)** — Added fallback detection patterns for the new Kiro CLI TUI prompt format (`ask a question, or describe a task`), ensuring CAO works even if `--legacy-ui` is removed in a future version.
+- **Agent profile exception handling (#140, resolves #137)** — `load_agent_profile()` no longer wraps `FileNotFoundError` as `RuntimeError`, which caused `assign()` to fail for JSON-only agent profiles (AIM-installed Kiro CLI agents). Callers now receive `FileNotFoundError` directly and handle it gracefully.
+- **Terminal-service graceful handling of missing agent profiles (#186)** — When an agent profile can't be found in the CAO store, `terminal_service` returns a clear error instead of tracebacking.
+- **Missing providers in Web UI (#158, resolves #157)** — Added `gemini_cli`, `kimi_cli`, and `copilot_cli` to the `/agents/providers` endpoint and frontend fallback list so all 7 providers appear in the Web UI dropdown.
+- **Web UI terminal scroll and paste reliability (#162)** — Fixes for scrollback drift and multi-line paste handling in the browser terminal.
+- **WAITING_USER_ANSWER false positives from stale scrollback (#142)** — Regex hardened so historical "confirm? [y/n]" lines in scrollback don't get re-detected as active prompts.
+- **Gemini skill catalog injection assertion in tests (#180)** — Test reads `GEMINI.md` rather than a hardcoded fixture so the catalog assertion tracks the live skill set.
+
+### Security
+
+- Bump authlib 1.6.9 → 1.6.11 (#178)
+- Bump python-multipart 0.0.22 → 0.0.26 (#175)
+- Bump cryptography 46.0.5 → 46.0.7 (#135, #165)
+- Bump fastmcp 2.14.5 → 3.2.0 (#139)
+- Bump pygments 2.19.2 → 2.20.0 (#136)
+- Bump vite 6.4.1 → 6.4.2 (#160)
+- Bump pytest (dev) 8.4.2 → 9.0.3 (#173)
+- Bump python-dotenv 1.1.1 → 1.2.2 (#194)
 
 ## [2.0.0] - 2026-03-28
 

README.md

@@ -104,6 +104,7 @@ Before using CAO, install at least one supported CLI agent tool:
 | **Gemini CLI** | [Provider docs](docs/gemini-cli.md) · [Installation](https://github.com/google-gemini/gemini-cli) | Google AI API key |
 | **Kimi CLI** | [Provider docs](docs/kimi-cli.md) · [Installation](https://platform.moonshot.cn/docs/kimi-cli) | Moonshot API key |
 | **GitHub Copilot CLI** | [Provider docs](docs/copilot-cli.md) · [Installation](https://github.com/features/copilot/cli) | GitHub auth |
+| **OpenCode CLI** *(experimental — single-agent only, [#203](https://github.com/awslabs/cli-agent-orchestrator/issues/203))* | [Provider docs](docs/opencode-cli.md) · [Installation](https://opencode.ai) | Per-model API key |
 | **Q CLI** | [Installation](https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/command-line.html) | AWS credentials |
 
 ## Quick Start
@@ -152,6 +153,7 @@ cao launch --agents code_supervisor --provider codex
 cao launch --agents code_supervisor --provider gemini_cli
 cao launch --agents code_supervisor --provider kimi_cli
 cao launch --agents code_supervisor --provider copilot_cli
+cao launch --agents code_supervisor --provider opencode_cli
 # Unrestricted access + skip confirmation (DANGEROUS)
 cao launch --agents code_supervisor --yolo
 ```
@@ -196,6 +198,41 @@ cao shutdown --session <session-name>
 
 ![Tmux Window Selector](./docs/assets/tmux_all_windows.png)
 
+
+## Session Management
+
+CAO provides CLI commands for managing sessions programmatically — useful for scripting, CI pipelines, or headless operation.
+
+### Commands
+
+| Command | Description |
+|---------|-------------|
+| `cao session list` | List active sessions |
+| `cao session status <name>` | Show conductor status and last output |
+| `cao session status <name> --workers` | Include worker terminal statuses |
+| `cao session send <name> "msg"` | Send message and wait for completion |
+| `cao session send <name> "msg" --async` | Fire-and-forget without waiting |
+| `cao session send <name> "msg" --timeout N` | Wait up to N seconds |
+| `cao shutdown --session <name>` | Shut down a session |
+
+### Headless Launch
+
+```bash
+cao launch --agents supervisor --headless --yolo \
+  --session-name my-task --working-directory '/path/to/project' "Your task here"
+```
+
+Add `--async` to send the message and return immediately without waiting for completion:
+
+```bash
+cao launch --agents supervisor --headless --async --yolo \
+  --session-name my-task --working-directory '/path/to/project' "Your task here"
+```
+
+> **Note:** Session names are automatically prefixed with `cao-`. Use the prefixed form (e.g., `cao-my-task`) when referencing sessions in commands like `cao session send` and `cao shutdown`.
+
+For full details, see the [Session Management skill](skills/cao-session-management/SKILL.md).
+
 ## Web UI
 
 CAO includes a web dashboard for managing agents, terminals, and flows from the browser.
@@ -569,6 +606,16 @@ When you add or remove a skill, all providers pick up the change automatically.
 
 For full details, see [docs/skills.md](docs/skills.md).
 
+## Plugins
+
+Plugins are observer-only extensions that react to server-side events inside `cao-server` — session and terminal lifecycle changes, and message delivery between agents. Typical uses include forwarding inter-agent messages to external chat (Discord, Slack), audit logging, and observability/metrics export.
+
+Plugins are standard Python packages discovered automatically via the `cao.plugins` entry-point group at server startup. Install a plugin into the same environment as `cao-server`, configure it, and restart the server — no registration step required.
+
+- **Installation, events, and troubleshooting:** [docs/plugins.md](docs/plugins.md)
+- **Ready-to-run example:** [examples/plugins/cao-discord/](examples/plugins/cao-discord/)
+- **Author your own plugin:** use the [cao-plugin skill](skills/cao-plugin/SKILL.md)
+
 ## Security
 
 The server is designed for **localhost-only use**. The WebSocket terminal endpoint (`/terminals/{id}/ws`) provides full PTY access and will reject connections from non-loopback addresses. Do not expose the server to untrusted networks without adding authentication.