Suggested reading path

Architecture → Ticket flow → Conflict recovery → Token efficiency → Issues → Future providers. The publication chapter covers Pages preparation and a reviewed LinkedIn draft. All content is static; this site cannot launch agents or access live ACP data.

Architecture Mermaid source · Helper sequence Mermaid source

The helper sequence

1. Lead requests start_agent(role, task, helper?).
2. Engine checks caller, run phase, node, capacity, nesting, budget and attempts. A refusal produces no launch effect.
3. Server persists accepted state before executing launch effects.
4. Server prepares the recorded-tip worktree, trusted setup and scoped context.
5. Adapter launches with explicit role tools, model, effort and permission bridge.
6. Events return to the engine; state is persisted and reconciliation may schedule next work.

What reaches the first agent?

Ticket key/title, type, priority and description enter the prompt builder. The server adds selected context, stage profile, mapped skills, attachment references and a prior summary of the same ticket where applicable. It does not automatically send the entire repository, all comments or other tickets.

What starts the helpers?

The lead asks for implementation helpers. The engine authorizes them. The server creates worktrees and setup, and the provider adapter starts sessions. Initial planning roles, change reviewers and final stages can be scheduled automatically by engine rules. A helper block is a template; a running helper is one authorized instance.

Reviews, checks and completion

ACP seals editing work and follows configured change review/check routes. Checks blocks are optional on this baseline; legacy graphs retain their existing gates. A missing check gate is not a passing test result. Agent blocks can select model and effort; a profile narrows role tools rather than granting new authority.

Final stages inspect combined work. Later edits need fresh evidence, rather than assuming an earlier completed reviewer/tester covers a new candidate. Finish presents local merge or PR delivery. A run ending or a discard does not by itself establish accepted delivery.

A clean merge needs no resolver model call. For a conflict, ACP prepares a worktree with the merge in progress. The resolver edits content, reports its outcome/assessment, and the server seals and validates the candidate. Attempts are bounded across replacements: 1–3, default 2.

What is still limited?

• Targets are local refs; ACP does not fetch origin before resolution.
• Automatic triggers are supported view/refetch/local-merge paths, not a background timer.
• Adaptive routing is project policy; no conditional verification node exists in the graph.
• No automatic missing-test preparation route or independent assessor agent.
• Delegated conflict delivery opens/updates PRs; it does not automatically merge them on GitHub.

The issue: each new ticket can pay to learn the same code again

Imagine a large application with authentication, billing, notifications and shared libraries. Ticket A asks an agent to fix a login error. Before editing, it must locate the login route, follow the authentication service, understand shared validation and find the tests. Those reads are useful work: the agent needs evidence to make a correct change.

Ticket B later asks for another login change. It starts a separate run. ACP does not currently provide an automatic, project-wide memory of everything Ticket A discovered. The new lead and helpers may repeat searches and read the same route, service and tests. A reviewer may also inspect them independently. More tickets and more roles create more opportunities to repeat the same discovery.

This does not mean ACP automatically sends the entire repository to every agent. The model sees the context supplied to it and the results of tools it uses. An agent with an unclear brief may explore many folders or read large files; a focused agent may need only a few relevant modules. The risk is repeated broad exploration, not a guaranteed full-repository scan.

How repeated reads become model input

A file exists on disk without consuming model tokens. When an agent reads it through a tool, the returned text becomes input for a later model request. Search results, instructions, the task, relevant conversation history and the requested answer also contribute. Long tool results can remain in context for subsequent requests, subject to the provider and transport’s context management.

If another session reads that file again, its returned text can enter another model request. That is a new opportunity for input consumption even though the source file did not change. A matching provider prompt cache may reduce repeated processing or price, but an unchanged file alone does not guarantee a cache hit. Fresh sessions do not imply either zero reuse or fully shared memory.

Consider four sessions: the lead, two helpers and a reviewer. In the illustrative comparison below, discovery uses 15,000 tokens per session, or 60,000 across four. If focused context reduces discovery to 5,000 per session, that becomes 20,000. With 30,000 other tokens unchanged, the example moves from 90,000 to 50,000. These are assumptions to explain the mechanism, not measured ACP savings or a dollar bill.

Why a small ticket can still be expensive

Changing three lines may require understanding callers, permissions, data contracts and tests across several packages. Codebase size increases the search space; change size does not reliably predict discovery cost. Adding helpers can shorten elapsed time while increasing total reading, handoff, review and rework. Worktrees isolate edits; they do not automatically share what each agent learned.

The waste to reduce is avoidable rediscovery or irrelevant input. Re-reading current source to validate an assumption, checking a changed dependency and independently reviewing a security-sensitive edit can be necessary. Optimizing by forbidding those reads could save input while increasing incorrect changes and later repairs.

Proposed fix: give each role a focused starting point, then verify it

These are proposed improvements, not an implemented project-memory service. Start with a small, source-backed project map: module responsibilities, entry points, important dependencies, invariants and where trusted tests are defined. Reuse that map across tickets only while its references remain valid. Do not generate a full repository summary separately for every helper.

For the login example, a ticket brief should name the relevant route, authentication service, shared validator and tests, explain the requested behavior, and identify what is still uncertain. The lead hands a helper the findings and source references it already has. The helper verifies those references in its own checkout and expands its search whenever the task requires it.

Keep shared essentials small and tailor additional context to the role. A documentation helper does not automatically need the billing implementation. A reviewer still receives the current diff, acceptance criteria and relevant checks, and retains enough independence to find mistakes rather than merely accepting the implementer’s account.

Key reusable source facts to the project and source snapshot; use file content hashes and invalidate affected entries after changes. Concurrent tickets can be based on different commits, so a correct map for Ticket A may already be stale for Ticket B. Source facts remain data, never permission grants. New persistent knowledge needs an explicit trust and retention design; do not store conversations or tool output as memory.

Measure net benefit per correctly accepted ticket: model input/output and cache categories, discovery overhead where reliably attributable, preparation and refresh work, retries, reviews, latency and regressions. Do not claim a saving if maintaining the map or fixing missed context costs more than the reading it avoided.

What ACP already does, and what remains proposed

Implemented: bounded initial context of up to 10 files / 32 KiB, assembled once per run and passed to its agents; same-ticket summaries; helper-session continuation for rework when available; structured outcomes and attempt limits; role/node model and effort settings. These mechanisms help within the current design, but do not establish a cross-ticket memory or a provider cache hit.

Proposed: a reusable project map with freshness checks, task-specific retrieval and structured source handoffs, plus evaluation of their net benefit. The existing 32 KiB bound is a byte limit on initial context, not a total token cap or a limit on later file reads. The issue cards below pair each additional risk with its proposed control.

24 risks to understand before adding infrastructure

Historical fixes are labeled. Other mechanisms identify potential waste, not measured frequency or savings.

Our opinion: reuse verified knowledge across isolated sessions.

Start with maintained docs and local file/symbol search. Do not add a mandatory research agent or external vector service before measuring net benefit. One permanent project conversation can accumulate irrelevant history, stale assumptions and mixed permissions.

Keep source facts separate from authority; invalidate affected knowledge and dependents after changes. Do not persist conversations, tool I/O or hidden reasoning as project memory.

Actual budget semantics

Budget tokens = uncached input + cache creation + output. Cache reads are tracked separately and excluded from the cap. Default: 500,000 per agent, configurable and soft. Three agents reaching that allowance account for 1,500,000 before possible overshoot—not an observed bill. Follow-up allowance resets per question.

Initial shared context allows 10 files / 32 KiB. That does not cap later tool reads or history, and reading context once per run does not prove a provider cache hit.

Measure quality and the entire attempt

Track acceptance evidence, regressions/reopenings, owner interruptions, latency, reported usage coverage and retries. Include map maintenance, retrieval, reviews and repairs. Test compute time is separate from LLM tokens. Exact discovery-token attribution is not established; do not invent it from timestamps.

Historical gaps that are now mitigated

Seven concrete mechanisms still worth reviewing

Recommended priorities

1. Make degraded context visible and validate source facts against the actual checkout.
2. Bound message backlogs and expose delivery status without inventing read receipts.
3. Scope aggregate run/project/follow-up admission limits separately from current accounting.
4. Measure progress after the retry fixes; improve change-inspection coverage and evidence freshness.
5. Reconcile ADR/status wording with the merged implementation in a separate governance change.

ACP owns intent and authority. Adapters own transport.

Keep logical task identity, workflow policy, context selection, retry limits and evidence in ACP. Translate them to each provider’s supported API or process. Do not pass a Claude session identifier to Codex or imply conversation/cache reuse across providers.

Sequence the work

1. Stabilize the current provider and establish quality-aware baselines.
2. Evaluate focused context and incremental local references with freshness checks.
3. At Phase 6, test adapter capabilities and conformance before enabling real runs.
4. Evaluate model/effort routing and richer retrieval only when evidence justifies them.

Current model precedence is node → profile → project → provider default. Effort is a separate workflow setting; support depends on the chosen provider/model. No new adapter, model recommendation service or future-phase feature is implemented in this documentation package.

Baseline and governance

dev / df9cf44f713e11c62add3786e6026aaee8022495, reviewed 27 Oct 2026. Package version 0.3.1. The snapshot includes conflict-recovery code, while ADR-0030 remains marked proposed and CR rows remain review. Maintainers should reconcile that wording separately.

Where to inspect

Primary external references

• Anthropic prompt caching — matching prefixes and usage evidence.
• Official OpenAI prompt caching — API behavior; not proof of a future Codex transport control.
• Context engineering — focused retrieval; ACP’s proposed layers are our design.
• GitHub Pages workflows and site visibility.

Limits of this review

No private provider transcript scan, production token study or comprehensive security audit was performed. Historical figures were transcribed from supplied screenshots; examples are hypothetical. Exact prices, model capacity and provider availability are deliberately not pinned.

The site makes no ACP API calls, uses no analytics, remote assets or browser storage, and contains no live inventory or credentials. Citations load only when clicked. Repository code links may require access to the private source; this guide does not require it.

Who does what?

How ticket details reach an agent

1. The owner creates a ticket and starts a run. The server supplies the ticket brief and configured project context to the run.
2. The workflow determines the available roles and routes. A planning role proposes work where configured, and the required approval must be satisfied before implementation proceeds.
3. The lead receives its role instructions and ticket context. It can request a helper with a role and task through start_agent.
4. The engine checks the caller, run phase, workflow node, capacity, nesting, budget and attempt limits. An invalid request is refused.
5. For an accepted request, the server records the transition, prepares a worktree from the recorded ticket tip, runs trusted setup, assembles the helper brief and context, and invokes the provider adapter.
6. The adapter starts the SDK query. Agent lifecycle and usage events return to the server and engine; a completed helper reports its outcome for the lead and configured review flow.

The engine can also schedule agents

Depending on the configured workflow, the engine can schedule planning, change reviewers and final stages as their conditions become ready. Conflict resolution uses a separate server-managed operation and resolver helper.

One command, four stages

Persisting state before an effect prevents an unrecorded launch when that database commit fails. It does not make SQLite, Git, the agent process and GitHub one atomic transaction; failures and restarts require reconciliation.

What the safeguards check

• A helper cannot start before the required planning or branch conditions are met.
• Configured capacity, nesting, budget and attempt limits apply to agent requests.
• Reviewers are read-only; helper branch-management commands are denied.
• Conflict candidate promotion checks the pinned candidate, target and policy. Delivery requires its own owner action or explicit project delegation.

These descriptions are based on the guide’s pinned development snapshot. See Architecture & authority for the diagram and Ticket & workflow for configurable routes.