fix(agy): suppress tool use and file links in print-mode summaries

[mvance]

Overview

Supercedes #360 (which was closed because the maintainer environment lacked an authenticated agy session for live proof). Rebased onto current main (0.23.0).

Text-only agy CLI calls (allowTools: false) can leak the agent's work-log narration and local file:// links into the returned summary because --sandbox and the temporary cwd only isolate filesystem side effects, not printed stdout narration.

This change appends explicit prompt-level steering guidance ("do not use tools or create files, return only the final text response") to text-only prompts sent to agy --print.

Changes

• Append explicit best-effort guidance when allowTools is false to prompt before calling agy --print.
• Update docs/cli.md documenting that agy text-only prompt guidance is best-effort prompt steering.
• Extend tests/llm.cli.agy.test.ts to assert instruction presence when allowTools: false and absence when allowTools: true.

Verification & Live Smoke Proof

• Build & Test Suite: pnpm -s build and pnpm -s check pass completely (610 tests passed, 43 skipped).
• Live Smoke (agy 1.1.13):
  Command:

  printf "Chapter 1: The team decided to focus on user-visible outcomes and simplify interaction models.\nChapter 2: Automation scripts were updated to reduce friction and eliminate manual steps.\nChapter 3: Rigorous verification gates were added to prevent invalid deployments.\n" | pnpm -s summarize - --cli agy --no-cache --plain --metrics off --timeout 2m --prompt 'Please return a bulleted list of the key actionable takeaways from these chapter summaries.'

  Output:

  - Focus on user-visible outcomes and simplify interaction models.
  - Update automation scripts to eliminate manual steps and reduce friction.
  - Implement rigorous verification gates to prevent invalid deployments.
  via model cli/agy
  

  Output is clean: zero file:// links, zero work-log narration sections.

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed August 22, 2026, 10:08 AM ET / 14:08 UTC.

ClawSweeper review

What this changes

The PR appends no-tools and no-file-link guidance to text-only Antigravity CLI prompts, documents its best-effort nature, and tests both tool modes.

Merge readiness

⚠️ Ready for maintainer review - 2 items remain

Keep open for maintainer merge. Current main still sends the unmodified text-only prompt to Antigravity, while this PR adds the requested, explicitly best-effort steering and has focused tests plus a recorded live smoke result.

Priority: P2
Reviewed head: a75979ef5f81dc9b042e8038b01e490f09d740a8

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	A focused, documented mitigation with direct live output evidence and no actionable correctness finding.
Proof confidence	🐚 platinum hermit (4/6)	Sufficient (live_output): The PR body contains an after-fix live agy run that directly shows a clean returned summary; no contributor action is needed.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Verified	Sufficient (live_output): The PR body contains an after-fix live agy run that directly shows a clean returned summary; no contributor action is needed.
Evidence reviewed	6 items	Current-main behavior: Current main sends options.prompt directly as the --print argument, so it has no prompt-level instruction against tool narration or local file links. Scoped implementation: The PR appends the guidance only when allowTools is false, includes it in argv-limit accounting, and otherwise preserves the existing runner flow. Mode-boundary tests: Focused tests assert the instruction is present for text-only calls and absent when attachments allow tools; the oversize test also covers the added argv bytes.
Findings	None	None.
Security	None	None.

Live Verification

Command: pnpm -s summarize --help

Result: PASS (completed)

pnpm -s summarize --help
runner@runnervm76f27:/tmp/clawsweeper-live-proof-390-6asFhD/target$ pnpm -s summarize --help
$ pnpm dev:cli --help
$ node --import ./scripts/register-typescript.mjs src/cli.ts --help
pnpm -s summarize --help
Usage: summarize [options] [input]

Summarize web pages and YouTube links (uses direct provider API keys).

Arguments:
  input                             URL, local file path, or - for stdin (text or binary) to summarize

Options:
  --youtube ‹mode›                  YouTube transcript source: auto, web, no-auto (skip auto-generated captions), yt-dlp, apify (default: "auto")
  --transcriber ‹name›              Local transcription stage: auto (default), whisper, parakeet, canary; Groq still runs first when keyed (choices: "auto",
                                    "whisper", "parakeet", "canary")
  --diarize [provider]              Add speaker labels to YouTube or direct audio/video: auto (ElevenLabs then OpenAI), elevenlabs, openai. (choices: "auto",
                                    "elevenlabs", "openai", preset: "auto")
  --identify-speakers               Resolve diarization labels to real names using timestamp anchors and OpenAI context.
  --no-identify-speakers            Keep generic diarization labels even when speaker identification is configured.
  --speaker-profile ‹name›          Speaker profile from ~/.summarize/config.json (implies --identify-speakers).
  --speaker-at ‹timestamp=name›     Identify the speaker active at a timestamp; repeat for multiple speakers. (default: [])
  --remember-speakers               Persist resolved mappings and anchors under the selected speaker profile. (default: false)
  --video-mode ‹mode›               Video handling: auto (prefer video understanding if supported), transcript, understand. (choices: "auto", "transcript",
                                    "understand", default: "auto")
  --embedded-video ‹mode›           Embedded YouTube handling: auto, off, prefer transcript, or combine article+transcript. (choices: "auto", "off", "prefer",
                                    "both", default: "auto")
  --slides [value]                  Extract slides for YouTube/direct video URLs or local video files and render them inline inside the summary narrative (when
                                    supported). Combine with --extract to interleave slides in the full transcript.
  --no-slides                       Disable configured slide extraction for this run.
  --slides-debug                    Show slide image paths instead of rendering inline images. (default: false)
  --slides-ocr                      Run OCR on extracted slides (requires tesseract). (default: false)
  --no-slides-ocr                   Disable configured slide OCR for this run.
  --slides-dir ‹dir›                Base output dir for slides (default: ./slides). (default: "slides")
  --slides-scene-threshold ‹value›  Scene detection threshold for slide changes (0.1-1.0). (default: "0.3")
  --slides-max ‹count›              Maximum slides to extract (default: 6). (default: "6")
  --slides-min-duration ‹seconds›   Minimum seconds between slides (default: 2). (default: "2")
  --timestamps                      Include timestamps in transcripts when available. (default: false)
  --firecrawl ‹mode›                Firecrawl usage: off, auto (fallback), always (try Firecrawl first). (default: "auto")
  --format ‹format›                 Website/file content format: md|text. For websites: controls the extraction format. For files: controls whether we try to
                                    preprocess to Markdown for model compatibility. (default: text; default in --extract mode for URLs: md)
  --preprocess ‹mode›               Preprocess inputs for model compatibility: off, auto (fallback), always. (choices: "off", "auto", "always", default: "auto")
  --markdown-mode ‹mode›            Markdown conversion: off, auto, llm (force LLM), readability. For websites: converts 
… output truncated …

Assertions:

• PASS expect_output: Summarize web pages and YouTube links

How this fits together

Summarize routes extracted text and user prompts through a selected CLI model provider, then returns that provider's stdout as the summary. The Antigravity runner builds the agy --print command, where this change affects text-only prompts before the CLI receives them.

flowchart LR
A[Extracted text and user prompt] --> B[Model executor]
B --> C{Text-only call?}
C -->|Yes| D[Antigravity prompt preparation]
C -->|Attachment| E[Attachment working directory]
D --> F[Antigravity print command]
E --> F
F --> G[Returned summary text]

Loading

Before merge

• Resolve merge risk (P1) - Prompt steering cannot enforce behavior if a future Antigravity model disregards the instruction; the PR documents this limitation rather than presenting it as a security boundary.
• Complete next step (P2) - No repair lane is needed: the patch has no discrete finding, so the remaining action is a normal maintainer merge decision.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Diff scope	3 files; source +7/-3, tests +54/-3, docs +1/-1	The implementation is narrowly limited to the Antigravity runner, its contract tests, and its user-facing limitation note.
Recorded validation	4 completed checks, including 24-shard tests	The supplied PR context reports all required checks passing in addition to the live smoke proof.

Root-cause cluster

Relationship: canonical
Canonical: #390
Summary: This rebased PR is the active implementation candidate for the same Antigravity output-contamination problem previously attempted in a closed PR.

Members:

• superseded: fix(agy): suppress tool use and file links in print-mode summaries #360 - The PR body identifies it as the earlier closed attempt for the same fix; this branch supplies the current rebased implementation and live proof.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Merge-risk options

Maintainer options:

1. Decide the mitigation before merge
   Merge the scoped guidance with its explicit best-effort documentation, while retaining the existing sandbox, temporary working directory, and argv-limit protections.
2. Pause or close
   Do not merge this PR until maintainers decide whether the risk is worth taking.

Technical review

Best possible solution:

Merge the scoped guidance with its explicit best-effort documentation, while retaining the existing sandbox, temporary working directory, and argv-limit protections.

Do we have a high-confidence way to reproduce the issue?

No independent current-main live reproduction was run; current main's raw agy --print prompt path and the reported real incident make the source path clear, but model narration is nondeterministic.

Is this the best way to solve the issue?

Yes. With no hard no-tools flag established for agy --print, scoped final prompt guidance is the narrowest available mitigation, and the documentation correctly avoids overstating it as enforcement.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against c78ac23b2fc8.

Labels

Label justifications:

• P2: This fixes contaminated output for an optional CLI provider without evidence of wider runtime or data-loss impact.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (live_output): The PR body contains an after-fix live agy run that directly shows a clean returned summary; no contributor action is needed.
• proof: sufficient: Contributor real behavior proof is sufficient. The PR body contains an after-fix live agy run that directly shows a clean returned summary; no contributor action is needed.

Evidence

What I checked:

• Current-main behavior: Current main sends options.prompt directly as the --print argument, so it has no prompt-level instruction against tool narration or local file links. (src/llm/cli-runners/plain.ts:99, c78ac23b2fc8)
• Scoped implementation: The PR appends the guidance only when allowTools is false, includes it in argv-limit accounting, and otherwise preserves the existing runner flow. (src/llm/cli-runners/plain.ts:83, a75979ef5f81)
• Mode-boundary tests: Focused tests assert the instruction is present for text-only calls and absent when attachments allow tools; the oversize test also covers the added argv bytes. (tests/llm.cli.agy.test.ts:296, a75979ef5f81)
• Documented capability boundary: The updated CLI documentation accurately states that this is prompt steering rather than a hard capability boundary. (docs/cli.md:178, a75979ef5f81)
• Real behavior proof: The PR body records an after-fix agy 1.1.13 smoke run whose returned summary contains only the requested bullets and model footer, with no file links or work-log narration. (a75979ef5f81)
• Feature history: History shows Antigravity support was introduced in commit 821e766 and the CLI runners were later refactored in commit a50fb6e, with substantial subsequent work by Peter Steinberger on these paths. (src/llm/cli-runners/plain.ts:69, 821e76613ded)

Likely related people:

• steipete: Feature history shows repeated ownership of the CLI runner and provider-adapter surface, including the adapter split that contains the current Antigravity runner. (role: recent CLI-runner contributor; confidence: high; commits: a50fb6e89b23, a75979ef5f81; files: src/llm/cli-runners/plain.ts, src/llm/cli.ts)
• Mykhailo: Introduced the repository's Antigravity CLI provider in the feature history. (role: Antigravity provider introducer; confidence: medium; commits: 821e76613ded; files: src/llm/cli-runners/plain.ts, tests/llm.cli.agy.test.ts)

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Workflow

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

History

Review history (2 earlier review cycles)

• reviewed 2026-08-17T17:26:39.019Z sha a75979e :: needs maintainer review before merge. :: none
• reviewed 2026-08-21T21:09:17.974Z sha a75979e :: needs maintainer review before merge. :: none