pydantic-acp

# pydantic-acp Skill Use this skill when the task is primarily about the `pydantic-acp` adapter package. This is the richest ACP adapter in the repo and the clearest expression of the project rule: > expose ACP state only when the underlying runtime can actually honor it. In this package that rule affects: - model selection - mode switching - config options - prompt capability advertisement - ACP-native plans - approval flows - host-backed files and terminal access - tool projection - hook visibility - external hook event projection - custom slash commands - custom ACP extension methods and notifications - authentication method advertisement and execution - typed, capability-gated choice elicitation - session replay ## Start Here If you only need the shortest high-signal path: 1. read `Quick Routing` 2. open the [adapter config module](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/config.py) and the [package entrypoint](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/__init__.py) for public-surface questions 3. open the [runtime adapter](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/runtime/adapter.py) for lifecycle and dispatch questions 4. then branch into approvals, projections, host, plans, slash commands, or prompt capabilities ## Quick Routing | If the task is about... | Use this skill? | Open first | | --- | --- | --- | | `run_acp(agent=...)` or `create_acp_agent(...)` | Yes | [package entrypoint](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/__init__.py), [adapter config module](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/config.py), [runtime adapter](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/runtime/adapter.py) | | approvals, permission presentation, or remembered policy | Yes | [approvals module](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/approvals.py), [approval store module](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/approval_store.py), [permission presentation module](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/permission_presentation.py), [prompt-execution runtime](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/runtime/_prompt_execution.py) | | plans or plan generation | Yes | [prepare-tools bridge](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/bridges/prepare_tools.py), [native plan runtime](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/runtime/_native_plan_runtime.py), [models module](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/models.py) | | filesystem / terminal ownership | Yes | [host context module](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/host/context.py), [filesystem host backend](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/host/filesystem.py), [terminal host backend](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/host/terminal.py), [host policy module](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/host/policy.py) | | hook visibility or external hook projection | Yes | [hooks bridge](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/bridges/hooks.py), [external hooks bridge](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/bridges/external_hooks.py), [hook-introspection runtime](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/runtime/hook_introspection.py), [hook projection module](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/hook_projection.py) | | slash commands / model / mode surface | Yes | [custom slash command module](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/slash.py), [slash-commands runtime](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/runtime/slash_commands.py), [adapter-prompt runtime](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/runtime/_adapter_prompt.py), [providers module](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/providers.py) | | prompt capabilities or multimodal input flags | Yes | [prompt capabilities module](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/prompt_capabilities.py), [adapter config module](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/config.py), [prompt/resources docs](https://github.com/vcoderun/acpkit/blob/main/docs/pydantic-acp/prompt-resources.md) | | private ACP methods, notifications, or authentication | Yes | [extensions module](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/extensions.py), [runtime adapter](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/runtime/adapter.py), [extensions/auth guide](https://github.com/vcoderun/acpkit/blob/main/docs/pydantic-acp/extensions-and-authentication.md) | | typed user choices or low-level ACP elicitation | Yes | [elicitation module](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/elicitation.py), [session-state module](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/session/state.py), [elicitation guide](https://github.com/vcoderun/acpkit/blob/main/docs/pydantic-acp/elicitation.md) | | filesystem search/list projection or tool classification | Yes | [projection module](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/projection.py), [host backends docs](https://github.com/vcoderun/acpkit/blob/main/docs/host-backends.md), [projection cookbook](https://github.com/vcoderun/acpkit/blob/main/docs/projection-cookbook.md) | | Codex auth refresh or `auth.json` | No, pair with `codex-auth-helper` | [Codex helper package](https://github.com/vcoderun/acpkit/tree/main/packages/helpers/codex-auth-helper) | | remote hosting or WebSocket transport | No, pair with `acpremote` | [remote transport package](https://github.com/vcoderun/acpkit/tree/main/packages/transports/acpremote) | ## Package Boundary `pydantic-acp` is the adapter layer for `pydantic_ai.Agent`. It owns: - truthful ACP capability advertisement for a Pydantic runtime - session-scoped model, mode, and config state - ACP-native plan state and plan updates - approval lifecycle and remembered approval policies - hook introspection and hook projection - external hook event buffering - custom slash command discovery and handling - typed extension routing and authentication strategies - host-backed filesystem and terminal ownership - tool projection maps - session store semantics and transcript replay It does not own: - Codex auth file parsing or token refresh - WebSocket transport - root CLI target loading ## Do Not Confuse With - `pydantic-acp` vs `codex-auth-helper` the helper builds a Codex-backed model; this package exposes the Pydantic runtime through ACP - `pydantic-acp` vs `acpremote` this package adapts a Pydantic runtime; `acpremote` only transports ACP - `pydantic-acp` vs `acpkit-sdk` this package owns adapter semantics; `acpkit` owns CLI target loading and dispatch ## Primary References Package references: - [Raw skill](https://raw.githubusercontent.com/vcoderun/acpkit/main/.agents/skills/pydantic-acp/SKILL.md) - [Raw overview docs](https://raw.githubusercontent.com/vcoderun/acpkit/main/docs/pydantic-acp.md) - [Raw host backends docs](https://raw.githubusercontent.com/vcoderun/acpkit/main/docs/host-backends.md) - [Raw projection cookbook](https://raw.githubusercontent.com/vcoderun/acpkit/main/docs/projection-cookbook.md) - [Raw runtime controls docs](https://raw.githubusercontent.com/vcoderun/acpkit/main/docs/pydantic-acp/runtime-controls.md) - [Raw plans, thinking, and approvals docs](https://raw.githubusercontent.com/vcoderun/acpkit/main/docs/pydantic-acp/plans-thinking-approvals.md) - [Raw prompt/resources docs](https://raw.githubusercontent.com/vcoderun/acpkit/main/docs/pydantic-acp/prompt-resources.md) - [Raw extensions/authentication docs](https://raw.githubusercontent.com/vcoderun/acpkit/main/docs/pydantic-acp/extensions-and-authentication.md) - [Raw API docs](https://raw.githubusercontent.com/vcoderun/acpkit/main/docs/api/pydantic_acp.md) - [Rendered overview](https://vcoderun.github.io/acpkit/pydantic-acp/) - [Source tree](https://github.com/vcoderun/acpkit/tree/main/packages/adapters/pydantic-acp) Cross-skill references: - [Root package skill](https://raw.githubusercontent.com/vcoderun/acpkit/main/.agents/skills/acpkit-sdk/SKILL.md) - [Codex helper skill](https://raw.githubusercontent.com/vcoderun/acpkit/main/.agents/skills/codex-auth-helper/SKILL.md) - [Remote transport skill](https://raw.githubusercontent.com/vcoderun/acpkit/main/.agents/skills/acpremote/SKILL.md) ## Public Surface High-value public seams: - `run_acp(agent=...)` - `create_acp_agent(...)` - `create_acp_model(...)` - `AcpProvider` - `AcpModel` - `AcpHostBridge` - `AdapterConfig(...)` - `MemorySessionStore` - `FileSessionStore` - `AdapterPromptCapabilities` - `ExtensionRouter` - `ContextualExtensionRouter` - `ExtensionContext` - `AuthenticationProvider` - `AuthenticationMethod` - `ElicitationChoice` - `ChoiceElicitationFallback` - `ChoiceElicitationResult` - `ElicitationUnsupportedError` - `InvalidElicitationFallbackError` - `NativeApprovalBridge` - `PermissionToolCallBuilder` - `ApprovalPolicyStore` - `PrepareToolsBridge` - `PrepareToolsMode` - `PrepareOutputToolsBridge` - `PrepareOutputToolsMode` - `SessionMcpBridge` - `ThinkingBridge` - `HookBridge` - `SlashCommandProvider` - `StaticSlashCommandProvider` - `ExternalHookEventBridge` - `ProjectionAwareToolClassifier` - `ClientHostContext` - `CompatibilityManifest` - `BlackBoxHarness` Package entrypoint: - [Package entrypoint](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/__init__.py) ## Current Pydantic AI Compatibility `pydantic-acp` supports `pydantic-ai-slim>=2.9.0,<=2.36.0`. Do not restore Pydantic AI V1 or pre-2.9.0 compatibility, or widen the upper bound without running the runtime and type-check matrix: ```bash make check-pydantic-ai-matrix ``` When working on this surface, remember: - Pydantic AI V2 defaults `Agent` dependency and output generics to `object`; use `deps_type=type(None)` when tools or hooks explicitly use `RunContext[None]` or `Hooks[None]` - `PrepareToolsBridge` owns function-tool preparation and mode-specific plan tool visibility - `PrepareOutputToolsBridge` owns structured-output tool preparation and session metadata for output-tool modes - `HookBridge` covers output-tool preparation, output validation, output processing, and deferred tool-call observation - prompt runtime passes ACP session identity through Pydantic AI `conversation_id` and run `metadata` - `run_stream_events()` is consumed as an async context manager throughout the supported range; 2.4.0 starts the run lazily on first event iteration - keep the direct async-iterable fallback only for tests and compatibility fakes - `OpenAICompactionBridge` must not pass deprecated `instructions=` into upstream `OpenAICompaction` - Harness filesystem, shell, and CodeMode bridges are regression-tested against `pydantic-ai-harness[code-mode]==0.22.0` through its public imports; do not duplicate unrelated Harness capabilities such as Memory or Guardrails in ACP Kit. - Harness 0.22.0 requires Pydantic AI 2.28.0 or newer; keep Harness capability tests on the locked development version and use the core adapter matrix for the full supported range. ## Module Guide | Subsystem | Key files | Use them for | | --- | --- | --- |