# Local-agent model/selection handoff
Protocol `magi-code.local-agent`, version **1**; package **0.96.3** at pinned source, not a claim of a new crates.io release. Require `model.catalog` and `selection.set`; original nine-capability clients remain compatible. Exact schemas, null/unknown/default meanings, scopes, effects, limits and errors: [protocol](local-agent-protocol.md#providermodel-catalog-and-deliberate-selection).
## Frozen implementation and observations
Selection implementation: [`50c9fc8081842fb5131c039346feda3154fe13a9`](https://github.com/magimetal/magi-code/commit/50c9fc8081842fb5131c039346feda3154fe13a9). Observed debug executable SHA-256: `acd231a0a56d4893bb341da198f09d14c3ce529ea50c217ce21544c0a01d5a65`. macOS; independent disposable Node consumers, shell `cat` bridges for real Unix pipes. Node's native socketpair endpoints are unsupported.
Consumers used isolated temporary `MC_HOME`, canonical synthetic cwd, synthetic saved sessions and validated synthetic cache metadata. No frontend credential/config reading, credential copying, automated tests or retained correctness suite. Consumers recorded actual frames without assertions. Wrappers carry provenance and ordered `frames`; `child` labels distinguish connections. Send only client `frame` plus LF, never wrapper. Captures are real process responses, not invented wire examples. Local metadata fixtures do not claim a live catalog refresh.
| Capture | Observed outcome |
| --- | --- |
| [Catalog / selection / reopen](https://github.com/magimetal/magi-code/blob/main/docs/features/local-agent-traces/model-selection.json) | Paged stable admitted choices; supported, unsupported, unknown and missing-auth cases; saved low restored; unknown provider/model, invalid/unsupported effort, extraneous fields, stale revisions and wrong session rejected without changing selection/revision; deliberate high persisted, status agrees, same-child and new-child exact reopen restore high; fresh catalog invalidates previous cursor. No turn submitted. |
| [Cache / save faults / limits](https://github.com/magimetal/magi-code/blob/main/docs/features/local-agent-traces/model-selection-faults.json) | Startup catalog → busy; actual cache mutation → stale cursor and mutation rejection; restoring old file cannot revive stale snapshot; fresh catalog recovers. Read-only synthetic history → persistence_failed with old requested/effective selection and revision intact. 2,049 cached models → catalog_limit, no partial result; concurrent status precedes error; connection recovers. No turn submitted. |
| [Effort semantics / concurrency](https://github.com/magimetal/magi-code/blob/main/docs/features/local-agent-traces/model-selection-effort.json) | Explicit reset selects unsupported effort controls → null/not-applicable; keep selects unknown controls → null/unavailable; explicit high supported and acknowledged. Null effort/value, config patch and unsupported max rejected. Concurrent catalog/selection → busy without queued change. Changed effort metadata between acknowledgement and deliberate turn → failed/not_started stale_selection, no input.persisted, no provider generation; requested high retained, effective default exposed after cleanup. |
| [Harmless live provider](https://github.com/magimetal/magi-code/blob/main/docs/features/local-agent-traces/model-selection-live.json) | Lazy isolated session deliberately changes from synthetic provider to available claude-subscription/claude-sonnet-4-6 with explicit default/reset. Preferences durable before input; response/status agree. Only explicit turn.start submits “Reply exactly OK. Do not call any tools.” Actual official Claude subscription returns “OK.”, reconciles reply, finishes completed/durable. Admission-time selection/catalog requests return busy; no tool activities or deferred changes. |
Final discovery accounting review additionally counts directory iterations (including repeated names) and conservatively charges failed-read budgets, in [`4497b37329a115bb20883dc6c5c03b610138a970`](https://github.com/magimetal/magi-code/commit/4497b37329a115bb20883dc6c5c03b610138a970). Selection code is unchanged from frozen implementation above. Supplementary [discovery safety capture](https://github.com/magimetal/magi-code/blob/main/docs/features/local-agent-traces/session-discovery-safety.json), executable SHA-256 `fc88c4985520f05315004606cad04c902555d0daecb6836d5cd87cd58948ded4`, observes deletion after enumeration, stale recovery, FIFO/symlink rejection, legacy exact-open notice, 4,097 synthetic directory names → discovery_limit with responsive status, and concurrent shutdown → operation_cancelled without a turn.
## Verification and user-state boundary
Formatting, locked check/build, strict all-target/all-feature Clippy and diff checks passed. Additional source review covered shared cache/model/effort admission, strict nested fields, credential-safe projections, resource ownership, stale protection, durable-before-config replacement and admitted-settings reasoning metadata. Compilation does not establish runtime correctness; process observations above supply separate evidence. No automated tests added or run.
Normal magi-code global/project provider/model/thinking settings were never modified; no configuration restoration needed. Temporary cache/permission fault changes restored in consumers' cleanup. Two harmless live observations ran during implementation; only final frozen-source turn published. Official Claude CLI used its existing authentication through backend, without credential payloads/copying or login UI. Native CLI may update its own authentication/usage/conversation metadata; no claim of rolling those effects back or restoring provider-side usage. Temporary backend sessions remain separate from normal history. No remote catalog refresh or frontend provider/tool execution.
## Independent client flow
1. Initialize requiring both capabilities plus status/session attachment/shutdown. Keep existing nullable provider/model fields; decode optional selection object without inferred defaults.
2. Request cache-only catalog; follow opaque revision/cursor until complete. Notices distinguish unavailable/unsafe cached data; a limit error is not a complete partial catalog. Display sanitized names or exact admitted identifiers.
3. Attach exact saved session, then obtain status and its current selection revision. Catalog revision is separate from selection/history revisions. Preserve frontend draft locally.
4. Submit exact provider/model, attached session ID and both revisions. Omit effort or keep to preserve requested value; explicit default resets; set requires permitted explicit level. Busy/invalid/unavailable/unsupported/stale errors preserve previous selection, never queue or cancel a turn.
5. Use successful authoritative selection/status and durable acknowledgement. Selection is session-only; history revision changes after preferences append. Reopen restores saved selection subject to current backend admission. Submit a prompt only through deliberate turn.start; no automatic replay after errors/uncertain admission.
6. Stale catalog → fresh catalog and status. Stale selection/session → reconcile attachment/status explicitly. Persistence failure → exact reopen to resolve uncertain storage outcome, never automatic mutation/prompt retry.
## Limits and exclusions
No claim of Linux/Windows/native frontend validation, exhaustive filesystem fault timing or remote-default knowledge. Status is last completed backend observation; availability is local readiness, not remote proof. Cooperative scan deadlines cannot interrupt kernel filesystem stalls or existing bounded Claude auth-status inspection; protocol loop and shutdown remain independent, with existing 2-second cleanup wait. No catalog refresh capability shipped; deliberate remote refresh remains normal Mission Control settings. Ma-gi controls/drafts/auth UI remain outside backend scope.