Surface the large-tool-result jq/Read/grep pattern in workflow guidance

Context

On 2026-07-13, extracting several token-cap-exceeding get_pull_request_diff outputs per-file (python/jq + Read + grep on the saved tool-results/*.txt file) during four large PR reviews (#15127 / #15128 / #15129 / #15131) read as a "clever workaround" — enough that the operator asked whether a single context-shrinking subagent should be re-allowed. Analysis concluded it should not (a subagent is more total tokens — a fresh full-context agent — and for a review it launders the source through a summary, breaking verify-before-assert). The pattern used is the sanctioned one. The friction is that it looked like a workaround, because the sanctioned alternative to a subagent for a large saved tool-result is documented only in swarm-topology config rationale, not in any day-to-day workflow skill.

Operator-suggested owner: GPT family (Euclid or Emmy), given the Claude-family reviews-only conserve posture. Peers self-select; not hard-assigned.

The Problem

The §swarm_topology_anchor subagent prohibition names its alternative verbatim — "files / large saved tool-results via jq/Read/grep" (.claude/settings.template.json:68, AGENTS.md:155). But that lives in config/rule substrate an agent does not re-read mid-review. When a tool returns a >token-cap payload (e.g. get_pull_request_diff on a 3k-line PR, or a 222K query_raw_memories result), the harness message itself suggests a subagent. An agent without the config rationale front-of-mind can (a) reach for a forbidden subagent, or (b) perform the correct jq/Read/grep extraction but signal it as a hack — which invites recurring "should we re-allow subagents?" churn (this ticket's own origin). Verified gap: rg over .agents/skills/ finds the pattern in zero skill files; it exists only in the config rationale.

The Architectural Reality

• Saved-tool-result path: when an MCP result exceeds the token cap, the harness writes it to a tool-results/*.txt file (JSON {result: string}) and returns the path plus a subagent suggestion. The sanctioned Neo response is per-file extraction on the saved file (jq/python + Read + grep), NOT a subagent.
• Highest-traffic trigger surface: PR review — get_pull_request_diff routinely exceeds the cap on large PRs. .agents/skills/pr-review/references/pr-review-guide.md is the natural home for a compact trigger; a shared tooling reference is the alternative canonical home if the pattern should be skill-agnostic.
• Progressive Disclosure / Substrate Accretion: the fix must NOT fatten an always-loaded SKILL.md router. A compressed trigger line (Map) that cites the config rationale, OR a one-line entry in a conditionally-loaded references/ payload.

The Fix

Add a compact, discoverable pointer to the sanctioned large-saved-tool-result handling pattern in day-to-day workflow guidance:

• Primary: a one-line trigger in the pr-review guide's large-diff area — e.g. "When get_pull_request_diff (or any tool) exceeds the token cap and saves to a tool-results/*.txt file, extract per-file with jq/Read/grep on the saved file — the sanctioned alternative to a subagent (subagents are config-denied except the operator-permission hatch)."
• Optional: a shared tooling reference (e.g. under learn/agentos/tooling/) the pr-review line can point to, if the team prefers a skill-agnostic home.
• Cite, do not copy: reference the config rationale (.claude/settings.template.json / AGENTS.md §swarm_topology_anchor) as SSOT — no duplicated rule text (accretion discipline).

Decision Record impact

none (aligned-with the swarm-topology config rationale). This is a discoverability pointer to already-merged config/rule substrate. It does not amend the §swarm_topology_anchor core-override rule — that is operator-owned core-override substrate, out of scope here.

Acceptance Criteria

• A compact pointer to the large-saved-tool-result jq/Read/grep pattern exists in day-to-day workflow guidance (the pr-review guide and/or a shared tooling reference), discoverable during a review without reading the config.
• The pointer cites the swarm-topology config rationale as SSOT rather than duplicating the rule text (no net always-loaded bloat beyond a compressed trigger; Substrate Accretion Defense honored).
• The pointer names both the correct move (per-file jq/Read/grep on the saved file) and the anti-move (do not spawn a subagent; config-denied except the operator-permission hatch).
• rg over .agents/skills/ finds the pattern after the change (closing the verified gap).

Out of Scope

• Editing the §swarm_topology_anchor core-override rule itself (AGENTS.md / .claude/settings.template.json) — operator-owned; this ticket only adds a workflow-guidance POINTER to it.
• Re-allowing subagents (fan-out or single) — the rule stands; this ticket does not relax it.
• Any change to the token-cap threshold or the harness tool-result-saving mechanism.

Avoided Traps

• Duplicating the rule text into the skill — would bloat always-loaded substrate and create a second, drift-prone source of truth. The fix cites, not copies.
• Filing this as a rule change — the friction is discoverability, not the rule; the rule is correct (a subagent is more total tokens + a laundered review, per the origin analysis).

Related

• Origin: operator↔Grace dialogue 2026-07-13 (whether to re-allow a single context-shrinking subagent → rule stands, discoverability is the real gap).
• Substrate: .claude/settings.template.json (config rationale), AGENTS.md §swarm_topology_anchor (~line 155), .agents/skills/pr-review/references/pr-review-guide.md (candidate home).
• Sibling discipline: .agents/skills/create-skill/ (Progressive Disclosure — Map vs Atlas placement).

Sweep Record

Live latest-open sweep: checked latest 20 open issues 2026-07-13 ~15:37Z — no equivalent found. A2A in-flight claim sweep (list_messages all/25): no lane-claim on this scope. Keyword sweep: 3 tangential matches (#12456 AiConfig, #11909 wake-schema, D#9808 hybrid-RAG), none equivalent. Gap verified: pattern absent from .agents/skills/.

Origin Session ID: e4b46238-0b1d-440e-b15c-c95be925d07a

Retrieval Hint: query_raw_memories("large saved tool-result jq Read grep subagent alternative workflow guidance"); memory anchor big-diff-extraction-jq-read-grep-not-subagent.