P7: Bounded, High-Signal Responses

Definition

CLI tools MUST provide mechanisms to control output volume. Agent context windows are finite and expensive — a tool that dumps 10,000 lines of unfiltered output wastes tokens and may exceed the context limit entirely, breaking the conversation that invoked it.

Why Agents Need It

Every token of CLI output an agent consumes has a cost — both monetary (API tokens) and cognitive (context window capacity). Unbounded output forces the agent to either truncate (losing potentially important data) or consume the full response (wasting context on noise). Bounded output with --quiet, --verbose, and --limit flags gives the agent precise control over how much data arrives, keeping responses high-signal and inside budget.

Requirements

MUST:

• A --quiet flag suppresses non-essential output: progress indicators, informational messages, decorative formatting. When --quiet is set, only requested data and errors appear. Implementations typically route diagnostics through a macro that short-circuits when quiet is on:

  macro_rules! diag {
      ($cfg:expr, $($arg:tt)*) => {
          if !$cfg.quiet { eprintln!($($arg)*); }
      }
  }

• List operations clamp to a sensible default maximum. A list without --limit does not return more than a configurable ceiling (e.g., 100 items). If more items exist, the output indicates truncation — "truncated": true in JSON, a stderr note in text mode.

SHOULD:

• A --verbose flag (or -v / -vv) escalates diagnostic detail when agents need to debug failures.
• A --limit or --max-results flag lets callers request exactly the number of items they want.
• A --timeout flag bounds execution time. An agent waiting indefinitely on a hung network call cannot proceed.

MAY:

• Cursor-based pagination flags (--after, --before) for efficient traversal of large result sets.
• Automatic verbosity reduction in non-TTY contexts (the same behavior --quiet explicitly requests).

Evidence

• --quiet flag with a falsey-value parser and env-var binding.
• A diagnostic macro (or equivalent gate) that short-circuits when quiet is true.
• --limit or --max-results on every list / search command.
• Pagination clamping logic (e.g., min(requested, MAX_RESULTS)).
• --timeout flag with a sensible default.
• --verbose flag for diagnostic escalation.
• A suppress_diag() method that returns true when quiet is set or when the output format is JSON / JSONL.

Anti-Patterns

• List commands that return all results with no default limit — an agent listing 50,000 items floods its context window.
• No --quiet flag — agents consuming JSON output still receive interleaved diagnostic text on stderr.
• --verbose as the only output control. If there is no way to reduce output, bounded responses do not exist.
• Progress bars or spinners that write to stderr in non-TTY contexts, adding noise to agent logs.
• No --timeout on network operations. A stalled request blocks the agent indefinitely.

Measured by check IDs p7-quiet, p7-limit, p7-timeout. Run agentnative check --principle 7 . against your CLI to see each.