<!-- Generated by generate-agent-docs; preserve verified project-specific guidance when regenerating. -->
# Local-agent protocol guide
Parent: [source guide](../AGENTS.md).
Owns pipe transport, admitted startup, session attachment and streamed turns. Normative wire contract: `../../docs/features/local-agent-protocol.md`; facade and DTOs: `../local_agent.rs`.
## Where to look
| Task | Owner |
| --- | --- |
| Envelope, capabilities and admission | `../local_agent.rs` |
| Nonblocking reads/writes and teardown | `transport.rs` |
| Shared startup and retained runtime | `startup.rs`, `../runtime_context.rs` |
| Create/open/history snapshots | `sessions.rs`; neutral presentation: `../sessions/chat.rs` |
| Read-only workspace session discovery | `discovery.rs`, `discovery/incremental.rs`; safe durable inventory: `../sessions/discovery.rs` |
| Cached model options / explicit refresh / session-only selection | `catalog.rs`, `selection.rs`; validation and refresh: `../model_catalog/{cache,refresh}.rs` |
| Runner bridge, events and approvals | `turns.rs`, `turns/` |
| Negotiated schema-1 display / live identities / saved selection | `tool_cards.rs`, `turns/cards.rs`, `tool_cards/history.rs` |
| Startup client-tool registration and replies | `../tools/client.rs`, `../tools/client/broker.rs`; contract: `../../docs/features/local-agent-client-tools.md` |
| Durable usage | `../sessions/usage_recorder.rs` |
## Local contracts
- Wire DTOs stay independent of internal display/session enums. Stdout contains protocol bytes only; transport failure omits stderr diagnostics so blocked stderr cannot delay exit.
- Capability preflight precedes configuration/auth/startup effects. Advertise implemented operations only. Keep one admitted discovery/settings snapshot per child; external settings changes require restart.
- Startup/session/turn work stays off the protocol loop and uses the existing full runner. No frontend provider/tool fallback, auth UI, daemon or additional execution path.
- Keep one nonblocking ordered writer, bounded queues and absolute output deadlines that partial writes cannot reset. Continue reading while workers or output stall; cleanup waits are separate from output draining.
- Request IDs are child-lifetime unique; never replay uncertain accepted requests. Admission, required-input acknowledgement, authoritative message reconciliation and durable terminal recording are separate milestones.
- Create is lazy; exact open never falls back to newest/new session. Preserve recorded cwd and delegated task ceilings. Writer/active leases outlive asynchronous work and MCP cleanup.
- History is bounded presentation, not provider replay or raw JSONL. Reconcile final/chunk text before redaction/chunking; accept reasoning summaries only with explicit provider provenance. File changes invalidate revision-scoped snapshots/pages.
- Discovery never owns writers, repairs sidecars, prunes or switches attachment. `session.list` retains full bounded scans; explicitly negotiated `session.discover` holds constant-memory iterators/readers, yields provisional pages and validates inventory incrementally before completeness. Require all recorded cwds for eligibility; one mismatch proves exclusion. Mutation/error invalidation remains sticky; exact open stays authoritative.
- Catalog reads remain cache-only; bound reads, model counts, labels, provider status and pages. Negotiate `model.catalog.status`, `model.refresh`, `operation.cancel` explicitly, with extension limits separate from unchanged `session.list` limits. Refresh one provider through shared auth/discovery/enrichment and atomic validated cache writes; never alter enabled IDs or preferences. Invalidate catalog guards on every admitted refresh; retain previous cache on remote failure and check cancellation before writes. Selection requires exact attachment plus selection/catalog revisions, normal admission and full effort validation; durable owned preferences append precedes config replacement. Never persist global/project selection or replay input. Keep/default/set effort objects reject extraneous fields.
- Best-effort deltas may drop; authoritative content must reconcile or fail visibly. Accepted content and critical-event waits remain bounded. Preserve shared usage recording rather than relying on event delivery.
- Approvals are run-scoped, first-reply-wins, expire and default deny. They cannot bypass global MCP startup approvals. Cancellation never promises rollback.
- `client.tools` is a startup-only exception to backend-owned execution, not a built-in/MCP fallback. Preflight the immutable registry before startup; keep call/cancel delivery critical and independent of cards. Result acceptance is not durable history.
- Task reports bind validated original indices and scoped identities to declared parents. Pending final telemetry consumes the same retained-byte budget; never derive totals from previews or mark live delivery durable.
- `tool.cards` explicitly negotiates both live and saved projections. Only requests negotiating it gain its capability, descriptor, events and first-part activity field. Retain selected wire facts rather than raw detail and reserve initial/terminal cores. Preserve precise outcomes, partial effects and public decisions; unresolved drain outcomes stay unknown. Keep snapshots critical; never bypass admission or silently drop authoritative facts. Saved cards use exact event attachments, bounded incremental selection and escaped whole-entry budgets before freezing revisions.