Resource-operation card facts
Read, Grep, AST Grep, Find, and List Files share these display facts across Mission Control and negotiated tool cards. Identify results rows by exact labels, preserve null values, and never parse titles or private results to infer missing facts.
Values and operation
Missing evidence → value:null, never zero or inferred completeness. Counts are nonnegative decimal strings; flags are true/false strings. Zero stays "0". A missing row after detail reduction means omitted, not zero. detail.availability describes display retention, not scan completeness, resource availability or execution success. Card outcome remains authoritative.
First Results block contains Resource operation, with read, grep, search, outline, rewrite preview, find or list files; unavailable operation → null. Rewrite is read-only preview, never applied edit.
| Tool | Additional argument labels, in order |
|---|---|
| Read | None; ordered Resources rows retain selected target including selector. |
| Grep | Patterns, Scope, Mode, Limit, Offset, Context requested |
| AST Grep | Scope, Language, Pattern, Name filter, Symbol type filter, Items, View, Public members only, Limit |
| Find | Query, Scope, Kind, Limit, Offset |
| List Files | Directory, Include directories |
Only selected sanitized scalar arguments enter these rows; Patterns is a JSON-encoded string array, not arbitrary JSON. Missing argument/effective recorded value → null; do not invent defaults. Limits describe requested/effective limits, not totals.
Result labels
Next Results block has these exact ordered labels. Every label is emitted before ordinary bounded previews; rows still consume card/run/history limits.
| Tool | Labels, in order |
|---|---|
| Read | Requested resources, Result state, Succeeded resources, Failed resources, Omitted resources, Read complete, Results limited, Aggregate read limited |
| Grep | Matching lines returned, Result state, Total matching lines, Context lines returned, Output lines returned, Matching lines seen, Seen count exact, Files returned, Scan complete, Timed out, Results limited, Next offset, Has more, Context lines omitted, Read errors skipped, Walk errors, Walk entries omitted, File byte limit reached, Scan byte limit reached, File limit reached, Match limit reached, Per-file limit reached, Output byte limit reached, Raw lookahead reached |
| AST Grep | Search output lines returned, Result state, Scan complete, Outline entries returned, Timed out, Results limited, Partial scan, Output truncated, Files skipped, Workset limited |
| Find | Entries returned, Result state, Total matching entries, Matching entries seen, Seen count exact, Scan complete, Timed out, Results limited, Has more, Next offset, Entries scanned, Entry limit reached, Walk errors, Walk entries omitted |
| List Files | Files returned, Directories returned, Result state, Entries returned, Listing complete, Results limited |
Boolean labels: completeness, timeout, limiting/truncation flags, Seen count exact, Has more, Partial scan, Output truncated, Workset limited, Raw lookahead reached. Error/skipped/omitted labels are counts unless named a limiting flag. Context lines omitted counts excluded producer context records. Unsupported/malformed scalar types → null.
Count meanings:
- Read requested/succeeded/failed/omitted counts come from recorded aggregate facts.
Read completecomes from recorded aggregate completeness; selection or aggregate clipping can make it false. Failed resource is not omitted resource. - Grep matching lines are primary matching rows, distinct from context. Output lines include ranked file headers. Context returned derives from recorded output minus primary rows and, in ranked mode, returned file headers; absent required counts/mode → null. Full total requires explicitly exact seen count. Raw lookahead can report scan complete while exact seen count is false; scan complete alone never establishes full traversal/total.
- AST search/rewrite count is output lines, not AST nodes/matches; outline count is complete selected top-level entries, not members. Other operation's count remains null. Scan complete requires recorded partial/truncated/timeout flags all false; any true makes it false. Missing flags stay unknown.
- Find returned count is selected files/directories; seen count becomes total only when explicitly exact. Scan completeness differs from page completeness. Has-more/next-offset come from recorded continuation, never preview length.
- Listing counts cover returned eligible direct children, not unrestricted directory contents. Directories are zero when excluded by requested policy. Entries equals recorded files plus directories. Listing complete derives only from an explicit truncation flag. Failed listing never becomes empty listing.
Result state values: failed, incomplete, no matches, empty listing, no entries returned, results returned, complete, or null. Failure is observed execution failure; incomplete is observed partial/limited result. No matches/empty listing require complete scan and known zero total. Zero returned without that evidence is no entries returned. Positive returned count does not establish completeness. State row outcome is failure/partial/success for corresponding failed/incomplete/complete-or-known-empty states; otherwise unknown. Other fact rows have outcome unknown.
Read resources
Resources rows are ordered supplied targets, at most eight, including skill:// and explicit selectors. Availability is available for observed resource success, unavailable for failure/omission, otherwise unknown; this is historical evidence, not permission or current existence.
Following Results rows, for each one-based N:
| Exact label | Value |
|---|---|
Resource N outcome | success, failure, omitted, or null; corresponding row outcome success/failure/partial/unknown. |
Resource N supplied source lines | Recorded selected source-line count, or null. Hash anchors contribute only their count, never payload. Aggregate clipping or missing multi-read aggregate-retention flag → null; never use whole-source totals. Non-anchor reads use retained line count only when explicitly untruncated. |
Resource N retained output lines | .lines() of recorded sanitized retained resource output, including formatting; absent text → null, empty text → zero. Not a whole-source count. |
Resource N completeness | complete, partial, omitted, unavailable, or null. Selected range can be partial relative to source. |
Resource N reason | Bounded sanitized supplied error, read output byte limit reached, read scan byte limit reached, requested selection complete; source not fully read, or fallback selected read limited; otherwise null. |
Read blocks expose no source contents or hash-anchor payload by default. Reasons are display explanations, not enum routing or permission evidence.
Persistence, privacy and bounds
Required tool-result append stores selected version-1 resource_display alongside result, including nested Code Mode calls. It does not change serialized ToolResult, provider output/context or tool execution. Only fixed labels, scalar counts/flags and bounded Read locations/reasons are persisted. No raw argument/result/metadata endpoint, current-filesystem reconstruction or replay.
Report ≤12 KiB escaped JSON; ≤8 resources, each location/reason ≤512 UTF-8 bytes. Optional reasons then resource detail can be excluded to fit, with size-limit omission. Ordinary schema-1 bounds still apply. Null facts use missing-source live/not-recorded saved omissions. Core reduction may exclude operation/count/resource blocks with explicit omissions; outcome/effects/protection and Bash execution safety retain existing core rules.
Exact reopen prefers validated persisted report. Missing legacy report selects only facts already present in recorded call/result; absent facts remain null. Malformed present report clears selected facts rather than reconstructing them, and suppresses contradictory legacy metadata claims. Saved records are never rewritten.
Live retention measures actual cards against 8 MiB, not hypothetical future identities. Admission can release already-delivered optional detail from older cards; subsequent replacement/final drain reports those omissions. Existing initial/terminal delivery reservations, card count and critical-delivery bounds remain unchanged.
Backend observations and executable provenance: #875 report. Ma-gi #37 owns frontend keyboard/clipboard/input/errors and width acceptance separately.