Thesis

For broad refactors, DeepSeek's cheap cached input suggests per-file resident sub-agents: each child gets a stable prefix containing the repo skeleton plus one target file, then receives small instructions over time. This is different from the removed swarm surface because the win is persistent cached locality, not arbitrary fan-out volume.

Current behavior

• crates/tui/src/core/engine.rs:833 registers ordinary agent_spawn tools for Agent/Yolo modes.
• crates/tui/src/core/engine.rs:837 builds sub-agent runtimes from the current client/model/tool context, but without a per-file resident prompt contract.
• docs/TOOL_SURFACE.md notes agent_spawn as bounded full sub-agent loops and says the legacy agent_swarm surface was removed.
• Open issue v0.8.9 agents: summarize sub-agent output before folding it into the parent's context #511 already tracks summarizing child results before parent reinsertion; this proposal is about child prompt residency and cache locality, not transcript folding.

Proposed change

Introduce a cache-aware sub-agent spawn variant or prompt profile that binds a child to one file or module. The parent supplies a deterministic repo skeleton, target file contents, and refactor objective. Subsequent agent_send_input messages should preserve that prefix and only append narrow deltas. Keep the existing agent_spawn lifecycle and caps; do not resurrect agent_swarm or /swarm.

Open questions / risks

• Resident agents can hold stale file contents after parent/other child edits; need invalidation or refresh messages.
• Parent/child write conflicts need explicit ownership or side-worktree isolation.
• Concurrency can hit output and tool-latency ceilings even when input is cached.
• Must not duplicate v0.8.9 agents: summarize sub-agent output before folding it into the parent's context #511's result-summary work; this is about child-context construction.

Acceptance signals

• A test proves resident file-agent prompt assembly is byte-stable across follow-up inputs when the file is unchanged.
• A refactor smoke over 3 files shows each child reports cache-hit-heavy input after its first turn.
• File ownership conflicts are detected and surfaced before applying overlapping edits.
• Existing agent_spawn, agent_wait, agent_result, and cancellation behavior remains compatible.