wait_for_text: expose risk_band_warned: bool in WaitForTextResult for clients that don't subscribe to log notifications #54

Type: enhancement · Tier: deferred · Tool: wait_for_text

Problem

When wait_for_text polls a pane near history-limit, it emits a one-shot ctx.warning() notification: "wait_for_text correctness is best-effort here. For deterministic synchronization use wait_for_channel." That warning routes through MCP client notifications. Some clients, stdio bridges, and programmatic callers do not surface those notifications to the agent or caller that receives the final tool result.

The current WaitForTextResult reports found, matched_lines, pane_id, and elapsed_seconds, but it does not include a structured indication that polling entered the history-limit risk band. The caller can therefore receive found=True or found=False without knowing that the answer was best-effort.

Proposed fix

Add a structured field to WaitForTextResult:

class WaitForTextResult(BaseModel):
    found: bool = ...
    matched_lines: list[str] = ...
    pane_id: str = ...
    elapsed_seconds: float = ...
    risk_band_warned: bool = Field(
        default=False,
        description=(
            "True if polling entered the history-limit trim-risk band "
            "at any point during the wait. Indicates wait_for_text's "
            "match result is best-effort; compose tmux wait-for -S "
            "with wait_for_channel for deterministic authored-command "
            "completion."
        ),
    )

The flag is already tracked inside wait_for_text as warned_risk_band, which gates the one-shot warning. Surface that value in the returned model.

Trade-offs

• This is an additive public response-model field. The project is still 0.1.x, but once shipped it should be treated as part of the tool contract.
• Tests should extend test_wait_for_text_warns_in_history_limit_risk_band and test_wait_for_text_warns_when_already_in_risk_band to assert result.risk_band_warned is True, and representative non-risk-band tests should assert the default is False.
• Docs and CHANGES should mention that the structured field mirrors the notification for clients that do not subscribe to or expose log messages.

Why this remains separate

• wait_for_text: two-call state/capture race within a single poll tick #50 covers a state/capture race inside wait_for_text.
• wait_for_text: optional include_baseline_row=True for in-place row writes #51 covers opt-in same-row matching.
• wait_for_text: adaptive backoff to reduce subprocess pressure on parallel waits #52 covers polling pressure and adaptive backoff.
• wait_for_content_change: surface pane death and respawn as ToolError for parity with wait_for_text #53 covers wait_for_content_change lifecycle parity.
• feat: capture_since — non-blocking, cursor-based delta capture for agentic flows #60 proposes a new non-blocking observation primitive.
• Observation-first architecture: eliminate agent lockout from blocking wait tools #61 is the umbrella architecture issue.

None of those surface the history-limit risk signal in WaitForTextResult, so this remains a small, independently testable issue.