Define reliable opaque-handle data use without reintroducing language-specific rewriting

## Problem

The #1293 simplification intentionally made completed local tool restoration one exact known-handle substitution operation. That remains a valuable design constraint. However, the agent cannot inspect a handle's value and therefore cannot reliably choose value-dependent quoting or serialization. Retrying the same opaque value is not a complete compatibility strategy.

The September 8 retest confirms ordinary synthetic-key command → native file write → readback → reuse on live Codex, Pi, and (after user re-login) Claude, and on OpenCode with a read retry. Deterministic actual-client tests also pass. These successful cases must not be generalized to arbitrary value contents or every destination format.

This public issue tracks the data-use contract and maintainable design. Security-sensitive reproduction details are handled privately under CONTRIBUTING.md; this issue intentionally contains no execution payload or exploit instructions.

## Preserve

- Same opaque handles and detector engines; this is not a secret-detection/CredSweeper issue.
- One authoritative recovery implementation and provider-boundary protection.
- Local tools retain their existing authority; no new destination/tool/time capability policy.
- No client-specific escaping tables, shell-dialect guessing, or general shell/JS/SQL rewriting layer.
- Normal tools and ordinary-key workflows remain usable without a new manual ceremony.

## Design questions

1. Distinguish a string used as data from a string subsequently parsed as code or a document. JSON tool-argument encoding protects the outer transport, not an embedded JSON file or script.
2. Prefer a small, shared data-binding primitive at an owned execution boundary, rather than extending detection or recovery. Evaluate existing direct argv/stdin mechanisms first. Specify how shell-only and native file-edit tools access it without exposing values to the model.
3. Do not advertise a nested `pentect exec` workaround until native gateway restoration, wrapper handling, session access, and all four real clients are tested: a handle may otherwise be restored before the intended late-binding boundary.
4. Raw-file content means exact replacement bytes. Producing a valid JSON/TOML/dotenv document is a separate encoding operation. If offering structured serialization, require explicit format/operation semantics and use standard encoders; do not guess from arbitrary content or silently reformat files/patches.
5. Unsupported combinations need a precise, value-free explanation and a verified recovery path, not blind retries or automatic compatibility bypass. Define the coverage before changing default behavior.

## Proposed sequence (design proposal, not yet implemented)

1. Retain the independent edge diagnostic and define an executable value/consumer contract. Record confirmed vs untested cases separately.
2. Prove one end-to-end data-binding path for command arguments and raw file data, including the actual native-client boundary and approval behavior. Keep #1444's independent JSON-output recovery correction separate.
3. Consolidate client mapping into thin adapters to shared semantics; introduce no syntax-dependent secret transformation into the recovery store.
4. Add explicitly scoped structured file serialization only where needed. Evaluate each additional consumer by a reusable contract, not a special-case tool-name heuristic.
5. Update documentation and agent instructions together, then roll out with cross-platform and live-client regression evidence.

## Acceptance criteria

- [ ] Data usage never requires the agent to know secret characters, reconstruct plaintext, or choose a different quote based on hidden contents.
- [ ] Fresh-session tests cover quotes, backslashes, whitespace, Unicode, LF/CRLF, leading/trailing newlines, empty values where representable, repeated handles, and unresolved references. Explicitly reject unsupported byte representations such as NUL in argv rather than silently altering them.
- [ ] Independent verification at the real consumer asserts exact value bytes; structured documents additionally parse and preserve unrelated content according to the declared operation.
- [ ] No-op inputs remain unchanged; restoration is owned once, with no repeated expansion of recovered text or transport-layer double restoration.
- [ ] Gateway, hook, streaming completion, and native-file paths follow the same contract. Partial/retried calls produce no premature side effects.
- [ ] Codex, Claude, OpenCode, and Pi use their actual command/native-file tools; record strict success, retry, provider-auth blockage, and unsupported cases distinctly.
- [ ] Linux/macOS/Windows tests declare their actual shell; cancellation, session expiry and tmux re-entry are covered for any new runtime helper.
- [ ] Provider-facing requests/results and diagnostics are independently checked using synthetic fixtures; no blanket claim of leakage absence from file roundtrips alone.
- [ ] No capability-policy redesign or per-client language parser is required to close this issue.

Related: #1293, #1443, #1444, #349. This is a follow-up to a deliberate simplification, not an instruction to restore the old rewriting architecture.

Start with CONTRIBUTING.md and the independent edge diagnostic, then evaluate the existing direct argv/stdin mechanisms at the native gateway boundary. Map the gateway, hook, streaming-completion, and native-file paths before testing the four named clients. Done means a documented value/consumer contract, exact-byte verification, explicit unsupported cases, and regression evidence across the stated platforms and client outcomes.

Written by the indexing model from the issue text.