acpkit 0.9.0__tar.gz → 0.9.2__tar.gz

{acpkit-0.9.0 → acpkit-0.9.2}/.agents/skills/acpkit-sdk/SKILL.md

@@ -67,6 +67,7 @@ What it owns:
 What it does not own:
 
 - Pydantic plan/approval/projection details
+- Pydantic prompt capability, custom slash command, and external hook event details
 - LangChain graph/provider/projection details
 - WebSocket transport behavior
 - Codex auth parsing
@@ -258,7 +259,7 @@ Remote pairing examples:
 Switch to a narrower skill when:
 
 - the bug is clearly inside adapter runtime behavior
-- the task is about approvals, plans, projections, or host policy
+- the task is about approvals, plans, prompt capabilities, custom slash commands, projections, external hook events, or host policy
 - the task is about transport or remote ownership rather than CLI or dispatch
 - the task is about Codex auth refresh or `auth.json`
 
@@ -275,5 +276,6 @@ Stay in this skill when:
 - Do not describe `acpremote` as an adapter.
 - Do not describe `codex-auth-helper` as part of target resolution.
 - Do not document a root CLI feature that is not present in the [CLI module](https://github.com/vcoderun/acpkit/blob/main/src/acpkit/cli.py).
-- When the question is about adapter truthfulness, plans, approvals, projections, host ownership,
-  or provider behavior, move to the narrower package skill.
+- When the question is about adapter truthfulness, plans, approvals, prompt capabilities, custom
+  slash commands, projections, external hook events, host ownership, or provider behavior, move to
+  the narrower package skill.

{acpkit-0.9.0 → acpkit-0.9.2}/.agents/skills/acpkit-sdk/resources/intro.md

@@ -2,9 +2,9 @@
 
 ACP Kit is the adapter toolkit and monorepo for turning an existing agent surface into a truthful ACP server boundary.
 
-Today the stable production focus is `pydantic-acp`: exposing `pydantic_ai.Agent` through ACP while keeping models, modes, plans, approvals, MCP metadata, host tools, and session state aligned with what the underlying runtime can actually support.
-
-Additional adapters such as `langchain-acp` and `dspy-acp` are planned after `pydantic-acp` reaches 1.0 stability.
+Today the repo ships production-grade adapters for both `pydantic-acp` and `langchain-acp`.
+`pydantic-acp` remains the richest reference implementation for ACP-native models, modes, plans,
+approvals, MCP metadata, host tools, projection, and session state.
 
 This intro is intentionally short. The canonical deep references should come from the published docs set, not from a second parallel skill-specific spec.
 
@@ -21,7 +21,8 @@ The central contract is:
 
 > expose ACP state only when the underlying runtime can actually honor it.
 
-That rule drives model selection, mode switching, slash commands, native plan state, approval flow, MCP metadata, and host-backed tooling.
+That rule drives model selection, mode switching, slash commands, prompt capabilities, native plan
+state, approval flow, MCP metadata, external hook events, projection, and host-backed tooling.
 
 ## Start With The Real Docs
 
@@ -32,13 +33,14 @@ Use these published docs pages as the primary references:
 | Product overview and package map | [ACP Kit Overview](https://vcoderun.github.io/acpkit/) |
 | Construction seams and adapter overview | [Pydantic ACP Overview](https://vcoderun.github.io/acpkit/pydantic-acp/) |
 | Runtime config and session ownership | [AdapterConfig](https://vcoderun.github.io/acpkit/pydantic-acp/adapter-config/) |
-| Models, modes, slash commands, thinking | [Models, Modes, and Slash Commands](https://vcoderun.github.io/acpkit/pydantic-acp/runtime-controls/) |
-| Plans, approvals, and cancellation | [Plans, Thinking, and Approvals](https://vcoderun.github.io/acpkit/pydantic-acp/plans-thinking-approvals/) |
+| Models, modes, custom slash commands, thinking | [Models, Modes, and Slash Commands](https://vcoderun.github.io/acpkit/pydantic-acp/runtime-controls/) |
+| Plans, approvals, permission presentation, and cancellation | [Plans, Thinking, and Approvals](https://vcoderun.github.io/acpkit/pydantic-acp/plans-thinking-approvals/) |
 | Host-owned state patterns | [Providers](https://vcoderun.github.io/acpkit/providers/) |
-| ACP-visible extension seams | [Bridges](https://vcoderun.github.io/acpkit/bridges/) |
-| Host-backed tools and projections | [Host Backends and Projections](https://vcoderun.github.io/acpkit/host-backends/) |
+| ACP-visible extension seams and external hook events | [Bridges](https://vcoderun.github.io/acpkit/bridges/) |
+| Host-backed tools, search/list projection, and classification | [Host Backends and Projections](https://vcoderun.github.io/acpkit/host-backends/) |
 | Maintained example ladder | [Examples Overview](https://vcoderun.github.io/acpkit/examples/) |
-| Production showcase | [Workspace Agent](https://vcoderun.github.io/acpkit/examples/workspace-agent/) |
+| Pydantic production showcase | [Finance Agent](https://vcoderun.github.io/acpkit/examples/finance/) |
+| LangChain production showcase | [LangChain Workspace Graph](https://vcoderun.github.io/acpkit/examples/langchain-workspace/) |
 | API surface | [pydantic_acp API](https://vcoderun.github.io/acpkit/api/pydantic_acp/) |
 
 ## Construction Seams To Reach For
@@ -61,19 +63,76 @@ Use these seams intentionally:
 - `FileSessionStore` is the hardened local durable store: atomic replace writes, local locking, malformed-session tolerance, and stale temp cleanup; it is not a distributed multi-writer backend
 - slash mode commands are dynamic; `ask`, `plan`, and `agent` are examples, not built-in global names
 - mode ids must not collide with reserved slash command names like `model`, `thinking`, `tools`, `hooks`, or `mcp-servers`
+- custom slash commands come from `SlashCommandProvider` or `StaticSlashCommandProvider`, and
+  must not collide with built-in commands or mode names
+- `AdapterConfig.prompt_capabilities` controls what prompt input families are advertised; do not
+  advertise image, audio, or embedded context unless the runtime can honor them
 - only one `PrepareToolsMode(..., plan_mode=True)` is allowed
 - `plan_tools=True` is how a non-plan execution mode keeps plan progress tools visible
 - `/thinking` only exists when `ThinkingBridge()` is configured
 - native ACP plan state and `PlanProvider` are separate ownership paths
+- permission card rendering is `NativeApprovalBridge.tool_call_builder`, not an `AdapterConfig`
+  field
+- `ApprovalBridge` stays compatible with the legacy no-`projection_map` signature; use
+  `ProjectionAwareApprovalBridge` only when the bridge explicitly accepts projected context
+- remembered approval policy is live runtime state owned by `ApprovalPolicyStore`, while
+  `ApprovalStateProvider` is metadata-only
 - `HookBridge(hide_all=True)` suppresses hook listing output, not the underlying hook capability itself
+- `ExternalHookEventBridge` is for integrations that already own lifecycle events and want them
+  buffered into ACP updates
 - custom `run_event_stream` hooks and wrappers must return an async iterable, not a coroutine
 - `HostAccessPolicy` is the native typed guardrail surface for host-backed file and terminal access
+- `FileSystemProjectionMap` search/list tree rendering is opt-in and based only on tool output;
+  it must not read the filesystem
+- `ProjectionAwareToolClassifier` classifies only configured projection tool names and delegates
+  unknown tools to the base classifier
 - `BlackBoxHarness` is the reusable black-box ACP boundary test helper for downstream integrations
 - projection helper primitives handle diff previews, truncation, command summaries, and guardrail-aware caution text without each integration rebuilding that shaping logic
 - the compatibility manifest schema gives integrations one typed, reviewable declaration of which ACP surfaces are implemented, partial, intentionally not used, or planned
 
 ## New Native Surfaces
 
+### PromptCapabilities, SlashCommandProvider, And StaticSlashCommandProvider
+
+Reach for `AdapterConfig.prompt_capabilities` when the runtime's prompt input support differs from
+the defaults. Use `SlashCommandProvider` or `StaticSlashCommandProvider` when a product integration
+needs commands beyond the built-in model, mode, config, thinking, tools, hooks, and MCP surfaces.
+
+Custom command handlers can return transcript updates, text, or a handled/fallthrough decision. The
+default result refreshes the session surface so visible commands and related state stay synchronized.
+
+Read next:
+
+- https://vcoderun.github.io/acpkit/pydantic-acp/runtime-controls/
+- https://vcoderun.github.io/acpkit/pydantic-acp/adapter-config/
+
+### ApprovalPolicyStore And PermissionToolCallBuilder
+
+Reach for `ApprovalPolicyStore` when remembered approval policy needs to live somewhere other than
+session metadata. Reach for `PermissionToolCallBuilder` when native approvals should render custom
+permission cards while keeping the ACP approval lifecycle unchanged.
+
+Keep the builder on `NativeApprovalBridge.tool_call_builder`. If a custom approval bridge needs
+projected file or command context, implement `ProjectionAwareApprovalBridge` rather than widening the
+legacy `ApprovalBridge` protocol.
+
+Read next:
+
+- https://vcoderun.github.io/acpkit/pydantic-acp/plans-thinking-approvals/
+- https://vcoderun.github.io/acpkit/providers/
+
+### ExternalHookEventBridge And ProjectionAwareToolClassifier
+
+Reach for `ExternalHookEventBridge` when hook-like lifecycle events come from an external runtime and
+should appear through the normal buffered bridge update path. Reach for
+`ProjectionAwareToolClassifier` when configured projection maps should also drive ACP tool-kind
+classification for reads, writes, bash, and search tools.
+
+Read next:
+
+- https://vcoderun.github.io/acpkit/bridges/
+- https://vcoderun.github.io/acpkit/host-backends/
+
 ### HostAccessPolicy
 
 Reach for `HostAccessPolicy` when an integration needs one reusable, typed place to evaluate file and command risk.
@@ -162,10 +221,13 @@ Read next:
 
 ## Reference Files In This Skill
 
-These skill-local references are only routing aids back into the docs:
+These skill-local references are only routing aids back into the docs and source tree:
 
-- `references/package-surface.md`
-- `references/runtime-capabilities.md`
-- `references/docs-examples-map.md`
+- `SKILL.md`
+- `resources/intro.md`
+- `examples/README.md`
+- `scripts/list_examples.py`
+- `scripts/list_public_exports.py`
 
-Use them to find the right docs page quickly, not as independent source-of-truth specs.
+Use them to find the right docs page or package surface quickly, not as independent source-of-truth
+specs.

{acpkit-0.9.0 → acpkit-0.9.2}/.agents/skills/codex-auth-helper/SKILL.md

@@ -155,7 +155,7 @@ This helper is usually upstream of the adapter, not a replacement for it.
 
 ### Build a Codex-backed `pydantic-ai` model
 
-Use `create_codex_responses_model(...)`.
+Use `create_codex_responses_model(...)` and pass explicit `instructions=...`.
 
 ### Build a lower-level client first
 
@@ -164,7 +164,8 @@ Use `create_codex_async_openai(...)` when you need the transport/client object e
 ### Build a LangChain model
 
 Use `create_codex_chat_openai(...)` when the upstream runtime is LangChain or LangGraph and you
-want the Responses API path instead of hand-wiring `langchain-openai`.
+want the Responses API path instead of hand-wiring `langchain-openai`. Pass explicit
+`instructions=...` here too.
 
 ### Debug refresh behavior
 

{acpkit-0.9.0 → acpkit-0.9.2}/.agents/skills/codex-auth-helper/examples/codex_chat_openai_graph.py

@@ -19,7 +19,13 @@ def describe_codex_surface() -> str:
 
 
 graph = create_agent(
-    model=create_codex_chat_openai(MODEL_NAME),
+    model=create_codex_chat_openai(
+        MODEL_NAME,
+        instructions=(
+            "You are a helpful coding assistant. "
+            "Explain concrete workspace observations and use tools when helpful."
+        ),
+    ),
     tools=[describe_codex_surface],
     name="codex-chat-openai-graph",
 )

{acpkit-0.9.0 → acpkit-0.9.2}/.agents/skills/codex-auth-helper/examples/codex_responses_agent.py

@@ -9,11 +9,14 @@ from pydantic_ai import Agent
 MODEL_NAME = os.getenv("CODEX_MODEL", "gpt-5.4")
 
 agent = Agent(
-    create_codex_responses_model(MODEL_NAME),
-    name="codex-responses-agent",
-    instructions=(
-        "You are a concise coding assistant. Ask for clarification when the task is underspecified."
+    create_codex_responses_model(
+        MODEL_NAME,
+        instructions=(
+            "You are a concise coding assistant. "
+            "Ask for clarification when the task is underspecified."
+        ),
     ),
+    name="codex-responses-agent",
 )
 
 

{acpkit-0.9.0 → acpkit-0.9.2}/.agents/skills/pydantic-acp/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: "pydantic-acp"
-description: "Use for `pydantic-acp` tasks: exposing `pydantic_ai.Agent` through ACP, adapter config/runtime ownership, approvals, plans, hooks, projections, host-backed tools, and Pydantic-specific examples."
+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
@@ -16,11 +16,14 @@ 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
@@ -30,18 +33,20 @@ 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, or plans
+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 or remembered policy | Yes | [approvals module](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/approvals.py), [prompt-execution runtime](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/runtime/_prompt_execution.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 hook projection | Yes | [hooks bridge](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/bridges/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 | [slash-commands runtime](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/runtime/slash_commands.py), [providers module](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/providers.py), [models module](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/models.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) |
+| 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) |
 
@@ -56,6 +61,8 @@ It owns:
 - 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
@@ -83,7 +90,10 @@ Package references:
 - [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 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)
 
@@ -102,7 +112,14 @@ High-value public seams:
 - `AdapterConfig(...)`
 - `MemorySessionStore`
 - `FileSessionStore`
+- `AdapterPromptCapabilities`
 - `NativeApprovalBridge`
+- `PermissionToolCallBuilder`
+- `ApprovalPolicyStore`
+- `SlashCommandProvider`
+- `StaticSlashCommandProvider`
+- `ExternalHookEventBridge`
+- `ProjectionAwareToolClassifier`
 - `ClientHostContext`
 - `CompatibilityManifest`
 - `BlackBoxHarness`
@@ -115,9 +132,9 @@ Package entrypoint:
 
 | Subsystem | Key files | Use them for |
 | --- | --- | --- |
-| public surface and construction | [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), [agent source module](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/agent_source.py), [agent type definitions](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/agent_types.py), [models module](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/models.py), [providers module](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/providers.py) | public API shape, construction seams, provider contracts |
-| approvals | [approvals module](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/approvals.py), [prompt-execution runtime](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/runtime/_prompt_execution.py), [prompt runtime](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/runtime/_prompt_runtime.py) | deferred approvals, remembered policy, permission flow |
-| bridges | [base bridge module](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/bridges/base.py), [capability-support bridge](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/bridges/capability_support.py), [history-processor bridge](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/bridges/history_processor.py), [hooks bridge](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/bridges/hooks.py), [MCP bridge](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/bridges/mcp.py), [prepare-tools bridge](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/bridges/prepare_tools.py), [thinking bridge](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/bridges/thinking.py) | optional capability wiring and extension seams |
+| public surface and construction | [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), [prompt capabilities module](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/prompt_capabilities.py), [agent source module](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/agent_source.py), [agent type definitions](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/agent_types.py), [models module](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/models.py), [providers module](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/providers.py) | public API shape, construction seams, prompt capability flags, provider contracts |
+| approvals | [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), [prompt runtime](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/runtime/_prompt_runtime.py) | deferred approvals, remembered policy, permission cards, projection-aware approval context |
+| bridges | [base bridge module](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/bridges/base.py), [capability-support bridge](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/bridges/capability_support.py), [external hooks bridge](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/bridges/external_hooks.py), [history-processor bridge](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/bridges/history_processor.py), [hooks bridge](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/bridges/hooks.py), [MCP bridge](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/bridges/mcp.py), [prepare-tools bridge](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/bridges/prepare_tools.py), [thinking bridge](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/bridges/thinking.py) | optional capability wiring, external event projection, and extension seams |
 | projection | [projection module](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/projection.py), [projection helper module](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/projection_helpers.py), [projection text helpers](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/_projection_text.py), [projection risk helpers](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/_projection_risk.py), [hook projection module](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/hook_projection.py) | ACP-visible transcript cards and rendering |
 | host ownership | [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), [path policy helpers](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/host/_policy_paths.py), [command policy helpers](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/host/_policy_commands.py) | path safety, command safety, client-backed host behavior |
 | runtime core | [runtime adapter](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/runtime/adapter.py), [runtime server](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/runtime/server.py), [bridge manager](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/runtime/bridge_manager.py), [hook-introspection runtime](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/runtime/hook_introspection.py), [session surface module](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/runtime/session_surface.py), [slash-commands runtime](https://github.com/vcoderun/acpkit/blob/main/packages/adapters/pydantic-acp/src/pydantic_acp/runtime/slash_commands.py) | adapter lifecycle, runtime update emission, slash command behavior |
@@ -174,6 +191,7 @@ It supports:
 - config options
 - ACP-native plans
 - tool-based or structured plan generation
+- custom slash command providers
 - session replay and fork/resume/load/close/list lifecycle
 - slash command discovery and rendering
 
@@ -196,6 +214,7 @@ High-value bridges include:
 - `McpCapabilityBridge`
 - `ToolsetBridge`
 - `PrefixToolsBridge`
+- `ExternalHookEventBridge`
 - `OpenAICompactionBridge`
 - `AnthropicCompactionBridge`
 
@@ -206,11 +225,14 @@ High-value projection families include:
 - `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.
 
@@ -238,6 +260,7 @@ Use this skill when the task is about:
 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
@@ -330,4 +353,11 @@ Stay in this skill when the main issue is:
 - 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`.

{acpkit-0.9.0 → acpkit-0.9.2}/.github/workflows/ci.yml

@@ -44,7 +44,7 @@ jobs:
       - name: Run Tests
         run: make tests
 
-      - name: Build Root, Adapter, And Helper Projects
+      - name: Build Root, Adapter, Helper, And Transport Projects
         shell: bash
         run: |
           project_dirs() {
@@ -54,6 +54,9 @@ jobs:
             if [ -d packages/adapters ]; then
               find packages/adapters -type f -name pyproject.toml -exec dirname {} \; | sort -u
             fi
+            if [ -d packages/transports ]; then
+              find packages/transports -type f -name pyproject.toml -exec dirname {} \; | sort -u
+            fi
             printf '.\n'
           }
 

{acpkit-0.9.0 → acpkit-0.9.2}/.github/workflows/docs.yml

@@ -2,7 +2,7 @@ name: Docs
 
 on:
   push:
-    branches: [ "main" ]
+    branches: ["main", "acpkit_v1"]
   workflow_dispatch:
 
 permissions:

{acpkit-0.9.0 → acpkit-0.9.2}/.github/workflows/publish.yml

@@ -38,7 +38,7 @@ jobs:
           uv sync --all-extras
           make prod
 
-      - name: Build And Publish Root, Adapter, And Helper Projects
+      - name: Build And Publish Root, Adapter, Helper, And Transport Projects
         shell: bash
         run: |
           project_dirs() {
@@ -48,6 +48,9 @@ jobs:
             if [ -d packages/adapters ]; then
               find packages/adapters -type f -name pyproject.toml -exec dirname {} \; | sort -u
             fi
+            if [ -d packages/transports ]; then
+              find packages/transports -type f -name pyproject.toml -exec dirname {} \; | sort -u
+            fi
             printf '.\n'
           }
 

{acpkit-0.9.0 → acpkit-0.9.2}/.gitignore

@@ -96,3 +96,6 @@ scripts/check_releases.py
 connect*.py
 expose*.py
 CHANGELOG
+/.acprouter-state
+/.deepagents-graph
+/.workspace-graph

acpkit-0.9.2/COVERAGE

@@ -0,0 +1,2 @@
+Line coverage: 100.00% (8145 / 8145)
+Branch coverage: 100.00% (2702 / 2702)

{acpkit-0.9.0 → acpkit-0.9.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: acpkit
-Version: 0.9.0
+Version: 0.9.2
 Summary: ACP Kit provides a common adapter for Agent Frameworks.
 Project-URL: Homepage, https://vcoderun.github.io/acpkit/
 Project-URL: Issues, https://github.com/vcoderun/acpkit/issues

acpkit-0.9.2/VERSION

@@ -0,0 +1 @@
+0.9.2

{acpkit-0.9.0 → acpkit-0.9.2}/docs/api/pydantic_acp.md

@@ -16,6 +16,8 @@ This page documents the public surface re-exported by `pydantic_acp`.
 
 ::: pydantic_acp.AdapterModel
 
+::: pydantic_acp.AdapterPromptCapabilities
+
 ::: pydantic_acp.AcpSessionContext
 
 ::: pydantic_acp.JsonValue
@@ -58,6 +60,14 @@ This page documents the public surface re-exported by `pydantic_acp`.
 
 ::: pydantic_acp.ApprovalStateProvider
 
+::: pydantic_acp.ApprovalPolicy
+
+::: pydantic_acp.ApprovalPolicyStore
+
+::: pydantic_acp.SessionMetadataApprovalPolicyStore
+
+::: pydantic_acp.PermissionOptionSet
+
 ## Bridge Classes
 
 ::: pydantic_acp.CapabilityBridge
@@ -72,6 +82,10 @@ This page documents the public surface re-exported by `pydantic_acp`.
 
 ::: pydantic_acp.HookBridge
 
+::: pydantic_acp.ExternalHookEventBridge
+
+::: pydantic_acp.EventEmissionMode
+
 ::: pydantic_acp.HistoryProcessorBridge
 
 ::: pydantic_acp.ThreadExecutorBridge
@@ -118,6 +132,36 @@ This page documents the public surface re-exported by `pydantic_acp`.
 
 ::: pydantic_acp.CompositeProjectionMap
 
+::: pydantic_acp.ProjectionAwareToolClassifier
+
+## Approval Presentation
+
+::: pydantic_acp.PermissionRequestContext
+
+::: pydantic_acp.PermissionToolCallBuilder
+
+::: pydantic_acp.DefaultPermissionToolCallBuilder
+
+::: pydantic_acp.NativeApprovalBridge
+
+::: pydantic_acp.ProjectionAwareApprovalBridge
+
+::: pydantic_acp.supports_projection_aware_approval_bridge
+
+## Slash Commands
+
+::: pydantic_acp.SlashCommandRequest
+
+::: pydantic_acp.SlashCommandResult
+
+::: pydantic_acp.SlashCommandProvider
+
+::: pydantic_acp.StaticSlashCommand
+
+::: pydantic_acp.StaticSlashCommandProvider
+
+::: pydantic_acp.SlashCommandHandler
+
 ## Projection Helpers
 
 ::: pydantic_acp.truncate_text

{acpkit-0.9.0 → acpkit-0.9.2}/docs/bridges.md

@@ -37,6 +37,29 @@ Use plain `CapabilityBridge` when you only need to:
 
 Use `BufferedCapabilityBridge` when the bridge also needs to emit ACP transcript updates over time.
 
+## External Hook Events
+
+Use `ExternalHookEventBridge` when an integration already knows about lifecycle events and wants to project them into ACP without installing Pydantic AI hooks or writing directly to the ACP client.
+
+```python
+from pydantic_acp import ExternalHookEventBridge, HookEvent
+
+bridge = ExternalHookEventBridge()
+bridge.record_event(
+    session,
+    HookEvent(
+        event_id="before_run",
+        hook_name="before_run",
+        tool_name=None,
+        tool_filters=(),
+        raw_output="completed",
+        status="completed",
+    ),
+)
+```
+
+The bridge buffers updates and the adapter drains them through the normal bridge manager. Its session metadata appears under `external_hooks` by default and includes emission mode, pending event count, hidden event ids, and projection title prefix.
+
 ### Override Matrix
 
 | Method | Override it when | Return value |
@@ -106,8 +129,6 @@ ACP Kit models those callable shapes locally and passes them through the public
 
 That means:
 
-- bridge extension code should import history-processor aliases from
-  `pydantic_acp`, not from `pydantic_ai._history_processor`
 - the adapter is no longer directly coupled to upstream private
   history-processor imports
 

{acpkit-0.9.0 → acpkit-0.9.2}/docs/examples/deepagents.md

@@ -8,6 +8,7 @@ This example is the maintained DeepAgents-facing showcase for `langchain-acp`.
 
 It demonstrates:
 
+- a Codex-backed `ChatOpenAI` model created through `codex-auth-helper`
 - wiring a DeepAgents graph through `langchain-acp`
 - `DeepAgentsCompatibilityBridge`
 - `DeepAgentsProjectionMap`
@@ -30,6 +31,12 @@ Run it:
 uv run python -m examples.langchain.deepagents_graph
 ```
 
+Required local state:
+
+```text
+~/.codex/auth.json
+```
+
 If you want the module-level compiled graph directly, the example exports `graph` when `deepagents` is installed:
 
 ```bash

{acpkit-0.9.0 → acpkit-0.9.2}/docs/examples/langchain-codex.md

@@ -10,6 +10,15 @@ This example demonstrates the helper-to-adapter path for LangChain:
 - `langchain.agents.create_agent(...)` owns the graph
 - `langchain-acp` exposes that graph through ACP
 
+The model factory call must pass `instructions=` explicitly:
+
+```python
+model = create_codex_chat_openai(
+    "gpt-5.4",
+    instructions="You are a helpful coding assistant.",
+)
+```
+
 Run it:
 
 ```bash
@@ -22,6 +31,12 @@ Required local state:
 ~/.codex/auth.json
 ```
 
+Override the default model when needed:
+
+```bash
+CODEX_MODEL=gpt-5.4-mini uv run python -m examples.langchain.codex_graph
+```
+
 If you have not logged in yet:
 
 ```bash