Tooling: design a structural code-region copy tool

[Hmbown]

Why

Agents waste tokens and introduce copy errors when they reproduce code by reading a region and then re-emitting it manually. CodeWhale already has file-edit tools and symbolic handles for large payloads; we should explore a precise tool that copies code regions by reference and lets the runtime perform the byte-level transfer.

Design goal

Prototype a copy_code-style primitive that can transfer exact source spans between files, buffers, or handles without forcing the model to restate the code body. The model should specify source, destination, range/anchor, and transformation intent; the tool should own exact bytes, validation, and diff reporting.

Questions to answer

• Is this a standalone tool, an apply_patch preflight mode, or a helper layered on the handle store?
• What source selectors are safe: file path + line range, AST item name, handle id + byte range, git ref + path?
• How do we prevent stale-line copies after edits: hashes, anchors, preview diffs, or mandatory preconditions?
• How should approvals describe the exact source/destination bytes without dumping large code into the prompt?
• Can the same design support examples, docs snippets, and test fixture cloning?

Acceptance criteria

• Produce a short design and one minimal implementation slice or prototype.
• Include tests for exact byte preservation, stale-source rejection, and diff preview.
• Keep behavior local and deterministic; no network or third-party dependency.
• Document when agents should use the tool instead of retyping code.