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,19 @@ 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.
+
+## v1 Release Discipline
+
+- The workspace packages use one synchronized version. Root extras require the matching major
+  generation of adapter, helper, and transport packages.
+- Prefer an example's exported `acp_agent` target over its raw `agent` or `graph` when custom
+  `AdapterConfig` state must survive root CLI dispatch.
+- Run `make release RELEASE_TAG=vX.Y.Z` before a release tag. This includes compatibility,
+  documentation, coverage, artifact metadata, and clean-install smoke checks.
+- A release tag must exactly match every package `_version.py` and the corresponding
+  `CHANGELOG.md` heading.
+- Public v1 compatibility applies to top-level `__all__`, documented CLI behavior, and documented
+  configuration contracts. Do not promote private helpers into that contract accidentally.

.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/acpremote/SKILL.md

@@ -245,3 +245,13 @@ Common end-to-end references:
 - Do not blur ACP adaptation with ACP transport.
 - If the task is really about `acpkit run ...` or `acpkit serve ...`, pair this skill with
   `acpkit-sdk`.
+
+## Production Baseline
+
+- Bind to loopback unless an authenticated reverse proxy owns public TLS termination.
+- Require bearer authentication or an equivalent trusted edge for non-loopback exposure.
+- Bound metadata requests, WebSocket frames, stream buffers, command runtime, and command output.
+- Every connection setup failure, reconnect, cancellation, and shutdown path must close the ACP
+  connection, stream bridge, WebSocket, and child process it owns.
+- Use configured native `acp_agent` exports when exposing adapter-backed examples; serving a raw
+  framework target can discard custom adapter state.

.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
 
@@ -209,3 +210,14 @@ Stay in this skill when the main issue is:
 - Do not claim it supports generic Chat Completions if it does not.
 - Do not describe auth refresh logic that is not present in the package source.
 - If the task shifts into ACP adapter runtime behavior, move to `pydantic-acp`.
+
+## Production Baseline
+
+- Require explicit `instructions=` for Codex-backed Pydantic AI and LangChain factories.
+- Never log access tokens, refresh tokens, account ids, or the contents of `auth.json`.
+- Keep auth-file replacement atomic and private, and serialize sync and async refreshes that share
+  one auth store.
+- Preserve the enforced Responses settings, including disabled server-side storage and streaming
+  behavior.
+- Treat local Codex auth as machine-local user state; do not bake it into images, artifacts, CI
+  logs, or shared volumes.

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

.agents/skills/langchain-acp/SKILL.md

@@ -60,6 +60,27 @@ It does not own:
 - Codex auth handling
 - WebSocket transport
 
+## Current Framework Compatibility
+
+The package metadata and compatibility gate use these minimum versions:
+
+- `langchain>=1.3.11`
+- `langgraph>=1.2.7`
+- `deepagents>=0.6.12` through `langchain-acp[deepagents]`
+
+Treat the three packages as one resolved stack. Validate changes with `make check-langchain-stack`;
+that gate runs both runtime tests and `ty` against the exact baseline versions.
+
+Compatibility details:
+
+- LangChain 1.3 agent graphs remain the primary `create_agent(...)` path.
+- LangGraph 1.2 graph state, interrupts, and streamed events stay upstream-owned.
+- DeepAgents 0.6 uses newer state-channel internals; do not inspect them from the adapter.
+- Project DeepAgents' public `read_file`, `write_file`, `edit_file`, `ls`, `glob`, `grep`, and
+  `execute` calls through `DeepAgentsProjectionMap`.
+- Keep `write_todos` handling in `DeepAgentsCompatibilityBridge`; ACP-native `TaskPlan` remains the
+  preferred framework-neutral plan surface.
+
 ## Do Not Confuse With
 
 - `langchain-acp` vs `pydantic-acp`
@@ -280,3 +301,15 @@ Stay in this skill when the main issue is:
 - Do not reuse Pydantic-only host-policy language when the bug is really about graph or tool seams.
 - Do not claim a projection preset exists for an unstable tool family unless it is implemented.
 - If the task is really transport-only, move to `acpremote`.
+
+## Production Baseline
+
+- Use a persistent `SessionStore` when replay, resume, fork, model, mode, or plan state must survive
+  process restarts; do not share `FileSessionStore` across replicas.
+- Cancellation must interrupt the active graph task, including streams blocked before their next
+  chunk, without swallowing unrelated event-loop cancellation.
+- Projection maps must match the graph's real tool names, argument schemas, and result shapes.
+- Export a configured `acp_agent = create_acp_agent(...)` for CLI and remote hosting so graph
+  factories, providers, bridges, and projections are not replaced by defaults.
+- Run `make check-langchain-stack` after framework upgrades and validate real
+  `create_deep_agent(...)` construction rather than compatibility fakes alone.