ACP Kit V1 Stable Release

.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.

.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,80 @@ 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
+- `PrepareOutputToolsBridge` is the separate seam for structured-output tool preparation in
+  current Pydantic AI
+- `HookBridge` covers output-tool preparation, output validation, output processing, and
+  deferred tool-call observation
 - `/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 +225,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.

.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
 

.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",
 )

.agents/skills/codex-auth-helper/examples/codex_responses_agent.py

@@ -9,11 +9,14 @@
 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",
 )