## Purpose This is the umbrella epic for all work that makes the **Duo CLI extensible** — the extension points, contribution formats, distribution mechanisms, and governance that let users, teams, and third parties customise and extend the CLI without changes to the CLI codebase itself. Today, extensibility work is spread across several efforts (plugins, marketplace, skills, hooks, MCP) with no single place to see the whole surface, its invariants, or its gaps. This epic tracks that work as one theme so we can keep the extension mechanisms coherent. ## What "extensibility" covers The extension surfaces of the Duo CLI, current and planned: | Surface | Mechanism | Status | |---|---|---| | **Plugins** | `plugin.json` manifests; on-disk contributions read by the CLI | In progress — &21319 | | **Plugin marketplaces** | Third-party marketplaces (git repos / local dirs), compatible with the existing community plugin ecosystem | In progress — &22497 | | **Agent Skills** | `SKILL.md` folders discovered at workspace/user level; distributable via plugins | Shipped (workspace), expanding — &20675 | | **Slash commands** | Plugin-contributed `commands/*.md` | Part of plugin marketplace work | | **MCP servers** | User/project `mcp.json`; plugin-contributed `.mcp.json` | Shipped, plugin distribution in progress | | **Hooks** | `lib_hooks` — user-configured external commands on lifecycle events | Partial (`SessionStart` only) | | **Host status reporters** | Report agent lifecycle state (working/idle/blocked/error) to host environments (terminal multiplexers such as Herdr, workmux) via built-in adapters first, then declarative plugin contributions | Proposed — POC issue TBD | ## Guiding invariants These are the properties every extension mechanism should preserve; proposals that break one should be flagged at design time: 1. **Declarative over code execution** — plugins contribute files (manifests, markdown, JSON configs) that the CLI parses; no third-party JS runs inside the CLI process. 2. **Consent and transparency** — anything that runs external commands (hooks, MCP servers, status reporters) requires explicit user approval, with the exact commands shown at enable time (mirroring the MCP approval flow). 3. **Hardened execution** — filtered child environments (no token leakage), spawn via args arrays (never through a shell), timeouts with process-group kill, path containment via the plugin store sandboxing. 4. **Ecosystem compatibility** — where a community convention exists (plugin/marketplace on-disk layout, Agent Skills spec), we follow it so existing artifacts work unmodified. 5. **Enterprise governance path** — mechanisms should be distributable/restrictable at instance or namespace level, not only per-user (see &21319). ## Child / related work - &21319 — Support Duo Agent Platform plugins to customise agents and flows - &22497 — Plugin marketplace client implementation (already a child of &21319, so tracked here as a grandchild) - &20675 — DAP: Add Agentic Skills - Host agent-status reporting extension point (Herdr / workmux POC) — issue/epic TBD - Lifecycle hooks completion (`lib_hooks` events beyond `SessionStart`) — issue TBD ## Out of scope - AI Catalog items (custom agents/flows) — server-side catalog work is owned by ~"group::ai catalog"; this epic covers only how the CLI consumes/installs such artifacts. - IDE extension APIs — this epic is CLI-focused; shared mechanisms (e.g. plugins in editor extensions) are tracked in their parent epics.