# Local-agent protocol guide
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
| 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` |
| Runner bridge, events and approvals | `turns.rs`, `turns/` |
| 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.
- 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.