pydantic-acp

name	pydantic-acp
description	Use for `pydantic-acp` tasks: exposing `pydantic_ai.Agent` through ACP, adapter config/runtime ownership, prompt capabilities, slash commands, approvals, plans, hooks, projections, host-backed tools, and Pydantic-specific examples.

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
• session replay

Start Here

If you only need the shortest high-signal path:

1. read Quick Routing
2. open the adapter config module and the package entrypoint for public-surface questions
3. open the runtime adapter 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, adapter config module, runtime adapter
approvals, permission presentation, or remembered policy	Yes	approvals module, approval store module, permission presentation module, prompt-execution runtime
plans or plan generation	Yes	prepare-tools bridge, native plan runtime, models module
filesystem / terminal ownership	Yes	host context module, filesystem host backend, terminal host backend, host policy module
hook visibility or external hook projection	Yes	hooks bridge, external hooks bridge, hook-introspection runtime, hook projection module
slash commands / model / mode surface	Yes	custom slash command module, slash-commands runtime, adapter-prompt runtime, providers module
prompt capabilities or multimodal input flags	Yes	prompt capabilities module, adapter config module, prompt/resources docs
filesystem search/list projection or tool classification	Yes	projection module, host backends docs, projection cookbook
Codex auth refresh or auth.json	No, pair with codex-auth-helper	Codex helper package
remote hosting or WebSocket transport	No, pair with acpremote	remote transport package

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
• 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
• Raw overview docs
• Raw host backends docs
• Raw projection cookbook
• Raw runtime controls docs
• Raw plans, thinking, and approvals docs
• Raw prompt/resources docs
• Raw API docs
• Rendered overview
• Source tree

Cross-skill references:

• Root package skill
• Codex helper skill
• Remote transport skill

Public Surface

High-value public seams:

• run_acp(agent=...)
• create_acp_agent(...)
• create_acp_model(...)
• AcpProvider
• AcpModel
• AcpHostBridge
• AdapterConfig(...)
• MemorySessionStore
• FileSessionStore
• AdapterPromptCapabilities
• NativeApprovalBridge
• PermissionToolCallBuilder
• ApprovalPolicyStore
• PrepareToolsBridge
• PrepareToolsMode
• PrepareOutputToolsBridge
• PrepareOutputToolsMode
• SessionMcpBridge
• ThinkingBridge
• HookBridge
• SlashCommandProvider
• StaticSlashCommandProvider
• ExternalHookEventBridge
• ProjectionAwareToolClassifier
• ClientHostContext
• CompatibilityManifest
• BlackBoxHarness

Package entrypoint:

• Package entrypoint

Current Pydantic AI Compatibility

pydantic-acp supports pydantic-ai-slim>=2.0.0,<=2.9.1. Do not restore Pydantic AI V1 compatibility or widen the upper bound without running the runtime and type-check matrix:

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.7.0 through its public imports; do not duplicate unrelated Harness capabilities such as Memory or Guardrails in ACP Kit.

Module Guide

Subsystem	Key files	Use them for
public surface and construction	package entrypoint, adapter config module, prompt capabilities module, agent source module, agent type definitions, models module, providers module	public API shape, construction seams, prompt capability flags, provider contracts
approvals	approvals module, approval store module, permission presentation module, prompt-execution runtime, prompt runtime	deferred approvals, remembered policy, permission cards, projection-aware approval context
bridges	base bridge module, capability-support bridge, external hooks bridge, history-processor bridge, hooks bridge, MCP bridge, prepare-tools bridge, thinking bridge	optional capability wiring, external event projection, and extension seams
projection	projection module, projection helper module, projection text helpers, projection risk helpers, hook projection module	ACP-visible transcript cards and rendering
host ownership	host context module, filesystem host backend, terminal host backend, host policy module, path policy helpers, command policy helpers	path safety, command safety, client-backed host behavior
runtime core	runtime adapter, runtime server, bridge manager, hook-introspection runtime, session surface module, slash-commands runtime	adapter lifecycle, runtime update emission, slash command behavior
runtime helpers	adapter-mixins runtime helpers, adapter-prompt runtime helpers, agent-state runtime helpers, native plan runtime, prompt-model runtime, session-lifecycle runtime, session-model runtime, session runtime helpers, session-surface runtime helpers	narrower runtime bugs that need subsystem-level edits
session storage	session-state module, session-store module	persisted sessions, replay, load/fork/resume/close/list
ACP testing helpers	testing fakes, testing harness	testing the ACP boundary itself

Construction Seams

run_acp(agent=...)

Use this when the caller already has one agent instance and wants the narrowest path to a running ACP server.

create_acp_agent(...)

Use this when the ACP-compatible agent object is needed before it is run.

Common reasons:

• combine with acpremote
• embed into another runner
• test the ACP object directly

agent_factory=

Use this when ACP session state should influence agent construction but full custom source control is unnecessary.

Typical cases:

• model-aware variants
• workspace-root binding
• mode-aware tools or instructions

agent_source=

Use this when the caller needs total control over agent materialization.

Typical cases:

• precise host-context injection
• complex dependency wiring
• custom source behavior that outgrows a factory callback

Plans, Modes, Models, and Slash Commands

pydantic-acp is the repo's most complete ACP-native session surface.

It supports:

• model selection
• mode switching
• config options
• ACP-native plans
• Tool Plans or Structured Plans plan generation
• custom slash command providers
• session replay and fork/resume/load/close/list lifecycle
• slash command discovery and rendering

This package should be the reference answer whenever the question is:

• "can ACP expose model switching truthfully?"
• "where do slash commands come from?"
• "how does plan state survive reload?"

Bridges and Projections

High-value bridges include:

• PrepareToolsBridge
• PrepareOutputToolsBridge
• ThinkingBridge
• HookBridge
• ThreadExecutorBridge
• SetToolMetadataBridge
• IncludeToolReturnSchemasBridge
• WebSearchBridge
• WebFetchBridge
• ImageGenerationBridge
• McpCapabilityBridge
• SessionMcpBridge
• ToolsetBridge
• PrefixToolsBridge
• ExternalHookEventBridge
• OpenAICompactionBridge
• AnthropicCompactionBridge

High-value projection families include:

• FileSystemProjectionMap
• WebToolProjectionMap
• BuiltinToolProjectionMap
• HookProjectionMap
• CompositeProjectionMap
• ProjectionAwareToolClassifier

Important rule:

• bridges affect runtime behavior and metadata
• projection maps affect ACP-visible transcript rendering
• FileSystemProjectionMap search/list tree rendering is opt-in and never reads the filesystem
• ProjectionAwareToolClassifier classifies only configured tool names and delegates unknown tools

Split those concerns before editing.

Host Ownership

This package has the repo's strongest host-side ownership model.

Relevant public ideas:

• ClientHostContext
• filesystem backend
• terminal backend
• HostAccessPolicy

Use this skill when the task is about:

• safe writes
• command warnings
• diff projection before approval
• path normalization
• client-owned host resources

Prompt and Model Ownership

This package also owns the more subtle Pydantic-specific surfaces:

• prompt-to-input conversion
• prompt capability advertisement through AdapterPromptCapabilities
• prompt-model override providers
• media-aware model routing
• transcript-to-history rebuilding
• model restore paths during replay/load

When the question involves image/audio/resources plus model selection, this package is usually the correct home.

Common Workflows

Minimal Pydantic ACP server

from pydantic_ai import Agent
from pydantic_acp import run_acp

agent = Agent('openai:gpt-5')
run_acp(agent=agent)

ACP object first, run later

Use create_acp_agent(...) when another runner or transport layer should own startup.

ACP-backed Pydantic AI provider

Use create_acp_model(acp_agent=...) when the runtime you have is already an ACP agent and the host application needs to consume it through normal Pydantic AI v2 model APIs.

from pydantic_ai import Agent
from pydantic_acp import create_acp_model

model = create_acp_model(acp_agent=remote_acp_agent, cwd="/workspace")
agent = Agent(model)

create_acp_model(...) leaves ACP model selection to the wrapped ACP agent's session default. Pass model_name=... only when that ACP agent exposes a selectable "model" session/set_config_option option. Do not use this as a replacement for create_acp_agent(...); it is the inverse bridge.

Use create_acp_model(acp_command=...) for local child processes that already speak ACP JSON-RPC over stdin/stdout, such as external ACP agent servers:

from pydantic_ai import Agent
from pydantic_acp import create_acp_model

model = create_acp_model(
    acp_command=("npx", "@zed-industries/codex-acp"),
    cwd="/workspace",
)
agent = Agent(model)

Do not pass arbitrary CLI commands here; the process must be an ACP server. Each command-backed model owns one child ACP process and should be reused for repeated subagent calls.

Use AcpProvider(acp_agent=...) directly only when provider ownership, host delegation, or lower level lifecycle control matters.

Session-aware construction

Use agent_factory= when session state should change the built agent.

Codex-backed Pydantic model plus ACP

Use codex-auth-helper to construct the model, then expose through pydantic-acp.

Remote-hosted Pydantic ACP

Adapt with pydantic-acp, then expose with acpremote.

Public Examples

Maintained public examples:

• Pydantic public examples
• Finance agent example
• Travel agent example
• Harness agent example
• Session MCP agent example

Use finance_agent.py for:

• ACP-native plans
• approvals
• projected file diffs
• workspace/file ownership

Use travel_agent.py for:

• hook projection
• prompt-model overrides
• media prompt behavior

Use mock_harness_agent.py for:

• pydantic-ai-harness filesystem and shell capability bridges
• optional CodeMode capability wiring through --codemode
• bounded workspace behavior under agent_demos/harness-agent/

Use session_mcp_agent.py for:

• client-owned session/new.mcpServers
• SessionMcpBridge converting session payloads into Pydantic AI MCPToolset capabilities
• env/header values kept available for connection while metadata exposes only names

Skill-local example index:

• Skill-local example index

Cross-package Codex-backed example:

• Codex-backed agent example

Handoff Rules

Pair or switch to:

• codex-auth-helper when a local Codex login is being turned into a Pydantic AI model
• acpkit-sdk when this adapter is being reached through acpkit run ... or acpkit serve ...
• acpremote when the adapted agent is then exposed remotely over WebSocket

Stay in this skill when the main issue is:

• ACP runtime truthfulness
• provider state
• plan/approval behavior
• host policy
• projection
• session lifecycle

Guardrails

ACP 0.11 Protocol Rules

• Depend on agent-client-protocol==0.11.0; do not reintroduce ModelInfo or wire-level session/set_model calls.

• Model selection travels through session/set_config_option with config_id="model". AcpProvider.model() leaves the remote default intact; an explicit provider model requires the remote agent to expose that select option.

• Preserve additional_directories in every lifecycle method. They extend the session scope for host-backed file and terminal operations, but never bypass a configured workspace_root.

• Use AcpSessionContext.create_elicitation(...) only with an exact ElicitationFormSessionMode, ElicitationFormRequestMode, ElicitationUrlSessionMode, or ElicitationUrlRequestMode that the client advertised.

• Keep full AgentPlanUpdate as the compatibility baseline. Use AdapterConfig(plan_update_mode="content") only when the client advertises plan; the runtime must fall back to full updates otherwise.

• Accept and persist AcpMcpServer session payloads, but do not advertise ACP MCP transport capability until the SDK exposes a public router.

• Do not describe pydantic-acp as transport.

• Do not promise ACP state the active pydantic_ai.Agent cannot honor.

• Do not route LangChain or DeepAgents questions through this skill.

• Do not answer Codex auth refresh questions from here unless the adapter integration itself is the point.

• Do not add permission_tool_call_builder to AdapterConfig; permission rendering belongs on NativeApprovalBridge.tool_call_builder.

• Keep ApprovalBridge compatible with the legacy no-projection_map signature. Use ProjectionAwareApprovalBridge only for bridges that explicitly accept projected context.

• Do not make custom slash commands collide with built-in commands or mode names.

• Treat ExternalHookEventBridge.metadata_key=None as the way to suppress bridge metadata publication.

• If the task is really about remote transport, move to acpremote.

Production Baseline

• Use FileSessionStore only for a single process. Multi-replica deployments need an application-owned SessionStore with explicit concurrency semantics.
• Keep filesystem, shell, and code-mode capabilities scoped to the smallest workspace and deny secrets, VCS metadata, interactive commands, and unbounded output.
• Approval-required tools must remain approval-required after mode-specific PrepareToolsBridge filtering.
• Export a configured acp_agent = create_acp_agent(...) when root CLI or remote hosting must preserve custom bridges, projections, providers, and persistence.
• Maintained examples write generated workspaces and local sessions under agent_demos/; do not reintroduce per-example hidden directories as default runtime output.
• Validate supported Pydantic AI versions with make check-pydantic-ai-matrix; dependency resolution alone is not compatibility evidence.