| name | tensor-grep-prepare |
| description | Use when an agent needs one-call edit readiness before changing code — tg prepare returns primary target, confidence, callers/blast-radius floor, validation commands, and claim/evidence coordination hooks. Prefer over the multi-step orient→search→agent→route-test→callers→evidence→ledger loop for routine edits. Pair with tg install-dense once for semantic find quality. |
tensor-grep prepare (one-call edit readiness)
Verified against tg 1.110.14 — honesty note (2026-08-13): this stamp was bumped from 1.110.13
by the 2026-08-11 drift sweep (docs/audits/2026-08-11-skill-audit-findings.md item 6), but the
dogfood table below records no dated 1.110.14 row — its newest rows are 1.110.13, and the
~5s saddle / ~22s --out/--claim numbers this header previously presented as a LIVE 1.110.14 run
are byte-for-byte the 1.110.13 receipts. The 1.110.14 stamp therefore currently rests on the
1.110.13 receipt (prior 1.110.12 CUJ still representative); a future pass must either add a dated
1.110.14 dogfood row or keep citing 1.110.13, as this header now does.
Note: anonymous --claim agent_id_hint remains strong (“NOT attributable…” until
TG_LEDGER_AGENT_ID / TG_EVIDENCE_AGENT_ID is set).
When to use
| Need | Command |
|---|
| Single call before editing | tg prepare REPO/src "task" --json |
| Also submit advisory ledger claim | tg prepare REPO/src "task" --claim --json |
| Persist the capsule for evidence emit | tg prepare REPO/src "task" --out capsule.json --json |
| Whole-repo / large root | tg prepare REPO "task" --deadline 20 --json (expect partial) |
Prefer REPO/src. Default deadline is 60s (like agent cold path); pass --no-deadline only when intentional.
What you get
primary_target + confidence + ask_user_before_editingvalidation_commandsblast_radius_floor (callers_count, top_callers, trust summary)coordination.claim — args ready; submitted=true only with --claim; an anonymous claim
(neither TG_LEDGER_AGENT_ID nor TG_EVIDENCE_AGENT_ID set) additionally stamps
coordination.claim.agent_id_hint with the STRONG hint — "this claim is filed as 'anonymous'
and is NOT attributable to you. Set TG_LEDGER_AGENT_ID (or TG_EVIDENCE_AGENT_ID) to a stable
per-agent value so other agents can see WHO holds it." — plus the machine-branchable
agent_id_is_anonymous=true sibling, so the caller knows why agent_id reads anonymous.
(The earlier weak hint "set TG_LEDGER_AGENT_ID for a stable identity" is RETIRED — superseded
per the "Strengthened from" comment in src/tensor_grep/cli/prepare_service.py; grep
"Strengthened from" to re-verify. Do not re-quote the weak form.)coordination.evidence — argv/note to emit a receipt without guessing flags
Dogfood:
| Case | Result |
|---|
prepare … saddle (1.110.13) | PASS ~5s |
prepare … --out/--claim tg src (1.110.13) | PASS ~22s |
prepare … saddle (1.110.12) | PASS ~6.5s |
prepare … --out/--claim tg src (1.110.12) | PASS ~20s |
prepare … saddle (1.110.10) | PASS ~6s |
prepare … --out/--claim tg src (1.110.10) | PASS ~14s |
prepare … --out (1.101.31) | PASS ~8s — overall 0.9, callers_count=1, file ~8KB |
prepare … --claim (1.101.31) | PASS ~13s — anonymous + strong hint; env id clears hint |
prepare … --out (1.101.22) | PASS ~7s — overall 0.9, callers_count=1, file ~8KB |
prepare … --claim (1.101.22) | PASS ~9s — stronger anonymous agent_id_hint; env id clears hint |
prepare … --out (1.101.19) | PASS ~7s — overall 0.9, callers_count=1, file ~8KB |
prepare … --claim (1.101.19) | PASS ~8s — anonymous + hint; env id clears hint |
prepare … --out (1.101.17) | PASS ~7s — overall 0.9, callers_count=1, file ~8KB |
prepare … --claim (1.101.17) | PASS ~8s — anonymous + hint; TG_LEDGER_AGENT_ID clears hint |
prepare … --out (1.101.9) | PASS ~6s — overall 0.9, callers_count=1, file ~8KB |
prepare … --claim (1.101.9) | PASS ~8s — submitted=true + when anonymous |
--out FILE (v1.93.0, A12(d)) replaces the old manual-redirect workflow. Chain straight into
evidence emit, no separate save step:
tg prepare REPO/src "task" --out capsule.json --json
tg evidence emit REPO --capsule capsule.json --query "task" --json --agent-id "$AGENT_ID" --out receipt.json
Without --out, prepare still does not write the capsule file on its own — save stdout instead
(tg prepare ... --json > capsule.json), or use coordination.evidence.argv.
Ledger cross-ref: --claim's behavior is affected by the #706 PATH-canonicalization fix (see
tensor-grep-ledger) — a claim submitted here is now visible from tg ledger list at any subtree PATH
under the same repo, not just the exact PATH prepare was run against.
Hard stops
ask_user_before_editing.requiredpartial / partial_reason, scan_limit.possibly_truncated,
blast_radius_floor.possibly_incomplete, exit 2 — do not claim full coverage. (These are
prepare's REAL incompleteness signals — partial_reason="deadline" folds into the top-level
exit-2 honesty gate; a plain max_callers output cap stays exit 0. Note prepare emits NO
result_incomplete field: grep -c result_incomplete src/tensor_grep/cli/prepare_service.py
is 0, verified 2026-08-13 — an earlier revision of this hard stop listed it in error.)- Empty
blast_radius_floor with source=no_primary_symbol — narrow PATH or raise budget
Dense semantic companion
tg install-dense --json
tg find "intent" REPO/src --deadline 20 --json
Dogfood: install-dense PASS ~4s (uv-tool + potion-code-16M); post-install tg find no longer reports BM25-only rank_fallback_reason.
Related
tensor-grep, tensor-grep-ledger, tensor-grep-find-and-route, tensor-grep-enterprise-agent
