Implementation Plan: T5-P6-A4-WP1 ACP Session Contract Alignment Design Document#4124
Merged
Trecek merged 5 commits intoJun 27, 2026
Conversation
Create docs/design/acp-session-contract-alignment.md — the normative
reference for P6-A3-WP1 mapping the CodingAgentBackend lifecycle to
ACP session method semantics. Four sections cover:
1. Lifecycle Mapping — per-method table for all 23 protocol methods
of CodingAgentBackend across ClaudeCodeBackend and CodexBackend,
including Codex deviations (discard sites at lines 698-701, 821-823,
911, 1074-1075).
2. Recovery Ladder — full mapping of all 16 RetryReason enum values
to ACP session rungs (session/resume, session/load, session/new)
with routing callbacks and the contract-nudge mechanism
(_attempt_contract_nudge, _merge_token_usage).
3. Capabilities Translation — field-by-field categorization of all 41
BackendCapabilities fields into ACP-Mappable (17), autoskillit-Local
Extension (18), and Forward-Declared (6) buckets, validated against
_FORWARD_DECLARED in tests/arch/test_capability_consumption.py.
4. Codex Shim Deviations — seven deviation categories (approval-bypass,
developer_instructions, positional RESUME_SUBCOMMAND, no Channel B,
no PTY, inspector RuntimeError, noqa discard sites) with all eight
discard sites documented.
Update docs/design/README.md index to include the new document.
Refs #4053
…ming rule The filename had 4 kebab segments (acp, session, contract, alignment) which violates REQ-DOC-085 rule 4 (max 3 segments). Renamed to acp-session-contract.md and updated the docs/design/README.md index accordingly. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…ontract doc CLAUDE_CODE_CAPABILITIES sets inspector_capable=False (not True). The capability gate in ClaudeCodeBackend.build_inspector_cmd fires before the AssertionError stub, making both backends behave identically. Updates L53 lifecycle table, L83-86 grouping rationale, and Section 4.6 table+prose to reflect the correct value. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…able The # column did not appear in any other table in the document. Replaced "Sites 1–6 / Site 7 / Site 8" prose cross-references with line-range and method-name references to preserve navigability without the structural anomaly. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…ess noise) Section 3.4 documented how the final field categorization differed from a prior draft plan — derivation history that has no place in a normative reference doc. The authoritative claim (membership validated against _FORWARD_DECLARED) already appears in the Section 3.3 header. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Trecek
deleted the
t5-p6-a4-wp1-provide-authoritative-reference-aligning-autosk/4053
branch
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Create
docs/design/acp-session-contract.md— a four-section normative reference document mapping the autoskillitCodingAgentBackendlifecycle to ACP (Agent Communication Protocol) session method semantics. The document covers lifecycle mapping, recovery ladder, capabilities translation, and Codex shim deviations. No code files are modified. Thedocs/design/README.mdindex is updated to include the new document.Closes #4053
Implementation Plan
Plan file:
/home/talon/projects/autoskillit-runs/impl-20260627-031355-771942/.autoskillit/temp/make-plan/t5_p6_a4_wp1_acp_session_contract_alignment_plan_2026-06-27_031500.md🤖 Generated with Claude Code via AutoSkillit
Token Usage Summary
* Step used a non-Anthropic provider; caching behavior may differ.
Token Efficiency
Model Usage Breakdown