Browse documentation

Technical documentation / Reference

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.

ToolAdditional argument labels, in order
ReadNone; ordered Resources rows retain selected target including selector.
GrepPatterns, Scope, Mode, Limit, Offset, Context requested
AST GrepScope, Language, Pattern, Name filter, Symbol type filter, Items, View, Public members only, Limit
FindQuery, Scope, Kind, Limit, Offset
List FilesDirectory, 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.

ToolLabels, in order
ReadRequested resources, Result state, Succeeded resources, Failed resources, Omitted resources, Read complete, Results limited, Aggregate read limited
GrepMatching 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 GrepSearch output lines returned, Result state, Scan complete, Outline entries returned, Timed out, Results limited, Partial scan, Output truncated, Files skipped, Workset limited
FindEntries 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 FilesFiles 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:

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 labelValue
Resource N outcomesuccess, failure, omitted, or null; corresponding row outcome success/failure/partial/unknown.
Resource N supplied source linesRecorded 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 completenesscomplete, partial, omitted, unavailable, or null. Selected range can be partial relative to source.
Resource N reasonBounded 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.

Edit this page on GitHub ↗