feat(output): add --suppress-reads flag

[hayatosc]

close #134

This pull request introduces a new --suppress-reads flag to the CLI, allowing users to suppress the output of raw file contents from read operations in both human-readable and JSON output formats. This is particularly useful for privacy or security-sensitive scenarios, or to reduce noise in agent-to-agent pipelines. The flag is documented across CLI help, documentation, and skill reference files, and is implemented with careful handling in both output formatting and CLI flag resolution.

Key changes:

Feature: Suppress Read Output

• Added a --suppress-reads global CLI flag that replaces raw file contents with [read output suppressed] in both text and json output formats, while leaving quiet mode unchanged. This is reflected in CLI flag parsing, documentation, and the help output.

• Implemented suppression logic in the output formatters:

  • For JSON output, read responses and read-like tool outputs are sanitized to replace file contents with the suppression marker.
  • For text output, similar suppression is performed when rendering tool outputs.

CLI and Core Integration

• Updated CLI core logic to propagate the suppressReads flag through output policy resolution and formatter creation, ensuring consistent behavior across prompt and exec commands.

• Extended the GlobalFlags and output policy types to include the new suppressReads option, ensuring type safety and future extensibility.

Documentation

• Thoroughly documented the new flag in docs/CLI.md, README.md, and skills/acpx/SKILL.md, including usage examples and behavioral details.

[dutifulbob]

Triage result

Human attention: ⚠️ Required
Recommendation: 🏁 escalate to a human
Human decision needed: ready for human landing decision

Quick read

This PR looks right-shaped and safe to continue. It adds an opt-in --suppress-reads flag so acpx can keep streaming tool activity while masking raw file-read bodies in text and json output.

Targeted feature validation passed. Stored Codex review evidence has no blocking P0/P1 findings. CI was initially approval-blocked, was approved, reran, and is now green. Initial and final conflict checks are both clean.

Intent

Add a CLI option so acpx can keep streaming normal tool activity while redacting file-read contents from text and JSON output.

Why

Today acpx forces a bad tradeoff for agent-to-agent workflows: text and json include full READ payloads, which can flood downstream context or expose sensitive content, while quiet removes the tool execution details the caller still needs. This PR addresses that directly with an opt-in flag rather than inventing a broader new output mode.

Codex review

Stored GitHub Codex review data for the current head was empty.

Stored local Codex review completed successfully and reported only non-blocking P2 findings:

• raw-agent token scanning may not skip --suppress-reads
• text output may suppress read-tool failure diagnostics
• JSON suppression may over-normalize some tool-update payload shapes

No blocking P0/P1 findings remain from the stored review evidence.

CI/CD

Targeted feature validation passed with:

• pnpm run build:test
• node --test dist-test/test/cli.test.js dist-test/test/integration.test.js dist-test/test/output.test.js dist-test/test/read-output-suppression.test.js

GitHub Actions status:

• CI was initially action_required
• workflow approval was attempted and succeeded
• the rerun completed green across Docs, Typecheck, Test, Format, Lint, Conformance Smoke, and Build

Conflict status:

• initial conflict check: clean against origin/main
• final conflict check: clean against origin/main

Recommendation

Ready for human landing decision. The PR is solving the right problem, validation passed, CI is green, and no merge conflicts were detected. Human review should focus on whether the remaining non-blocking P2 concerns are acceptable for merge now or should be deferred to follow-up work.