## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - A native driver must declare its supported behavior before the
coordinator can select it.
> - ACP-compatible agents do not all expose the same event families.
> - A loose config could also select an unqualified model, permission
policy, or executable field.
> - This pull request defines the ACPX descriptor, capability matrix,
and strict configuration parser.
> - The benefit is one reviewable admission contract before any ACPX
runtime is wired.
## Linked Issues or Issue Description
**Agent or provider**
Qualified Pi, Claude, and Codex ACP servers through the internal ACPX
driver.
**Why this adapter is useful**
The runner needs a truthful capability descriptor and a closed
configuration boundary before it can create an ACPX session. The
boundary must reject arbitrary commands and unqualified models.
**How the agent is invoked**
A later pull request will implement the private runtime behind this
descriptor. This pull request does not launch a process, add a
dependency, register an adapter, or make ACPX selectable.
**Additional context**
This pull request is stacked on #12389. Pi reports plan events as
unsupported. Claude and Codex report structured plan support.
## What Changed
- Add the ACPX driver descriptor and native runtime-context capability
declaration.
- Add an agent-specific typed event capability matrix.
- Add strict config validation for agent, exact qualified model, and
permission mode.
- Default the permission mode to `approve-all` when the field is absent.
- Reject non-object config, unknown fields, unqualified models, and
unsupported permission values.
- Add table-driven tests for all qualified agents and failure cases.
## Verification
- Runner TypeScript typecheck — passed.
- Runner TypeScript tests — passed, including 8 new driver-profile
assertions.
- `pnpm -r typecheck` — passed for all applicable workspaces.
- `pnpm build` — passed, including runner binary, server, UI, and
workspace packages.
- Prettier and `git diff --check` — passed.
- The diff contains 2 files and does not change `pnpm-lock.yaml`, a
workflow, a dependency, a public export, server selection, or UI
behavior.
## Risks
The main risk is advertising a capability that a qualified ACP server
cannot supply. The matrix is explicit per agent, and tests cover the one
current difference. Config validation rejects unknown fields so a caller
cannot smuggle an executable or an unsupported runtime setting into this
boundary.
## Model Used
OpenAI Codex with GPT-5 and repository tool use.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either linked an existing public item or described the
issue in this PR
- [x] I have not referenced internal or instance-local Paperclip issues
or links
- [x] My branch name describes the change and contains no internal task
identifier
- [x] I have run the affected tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have documented the compatibility and admission boundary
- [ ] All applicable GitHub Actions are green
- [ ] Greptile is 5/5 with every actionable comment resolved
- [x] I will address all review findings before requesting merge
da6124adf2