Before changing this crate, discover and read the applicable Linked Specs in `specs/` and every wider `specs/` scope, then follow relevant links. Use the `linked-specs` skill when updating them and `linked-specs-review` when reviewing.
* CLI (or any other UI crate) MUST NOT special-case handling of tool-related UI. They should use general purpose mechanisms like `ToolUseState` to handle well even tools written by external developers that are not in this codebase. Any exceptions should be confirmed with the user, and notably documented as such.
* `tau-cli` should render harness-owned sub-agent activity from generic events: watches identify observed agents; complete `agent.stats_updated` runtime state defines the watched agent's current outer activity; and prompt/provider activity is only a pre-stats fallback. The CLI recursively projects that state through the live watch DAG for watched rows and the global side-agent count; it must not redefine navigation runtime state or model-visible watch notifications. Agent stats provide runtime/counters and provider response stats provide details. Do not treat merely live/non-suspended or merely watched idle leaves as running, and avoid reintroducing delegation-specific progress UI paths.
* Documented temporary exception: during composition, content-enabled prompt drafts represent a recognizable `:email auth google finish ...` buffer as exactly `:email auth google finish <redacted>`; after submission, command echo, histories, and editor context use that same fixed line. The current action schema has no sensitive-argument metadata, and the pasted Gmail loopback URL contains a one-time authorization code. Only the active editor, immediate routing stack, and exact owning action extension retain the raw line. Keep this exception narrow and prefer schema/protocol metadata when available.
* Command-mode and argument/subcommand completion descriptions must be meaningful user-facing help. Do not use generic labels such as `subcommand`, `command`, or `item` when the completion UI can explain the action.
* Before changing any behavior covered by documented `tau-cli` design decisions, read the applicable Linked Specs under `specs/`.
- Before introducing a new free-form payload kind, or reframing an existing one, in the shared generic user-role `ContentPart::Text` carrier, read [`GATE-new-generic-user-payload-envelopes`](../../specs/GATE-new-generic-user-payload-envelopes.md) and [`SPEC-exact-sentinel-prompt-envelopes`](../../specs/SPEC-exact-sentinel-prompt-envelopes.md); use the shared registry rather than a component-local provenance wrapper. Typed tool results and the system/developer prompt channel are outside that rule.