Fundamental Tools (Grida binding)
This document binds the locked fundamental-tool RFC
(../agent/tools.md) to Grida's host surfaces.
The RFC names the shapes every conforming implementation MUST
honor; this page records the identifiers, backends, and shipped
deviations as Grida currently implements them.
For canvas-specific tools (scene-graph search, specialized inserts,
canvas exec / lint / format, resource lookup), see
tools-canvas.md. For image-generation tools,
see tools-image.md.
Naming map (RFC → Grida)
The RFC locks 13 ids (read, write, edit, glob, grep,
bash, todo, task, question, web_search, web_fetch,
skill, tool_search). Grida currently ships a _file / _files
suffix on the fs tools and splits command execution into a start and
an interaction tool. The divergence is recorded here, not endorsed — a future
RFC item should reconcile (see Adding a new fundamental
tool).
| RFC id | Grida id | Notes |
|---|---|---|
read | read_file | Same shape; Grida's name is more specific. |
write | write_file | Same full-file upsert shape; creates or overwrites. |
edit | edit_file | Same current-content replacement shape; Grida adds a strict ambiguity rule on multi-match. |
glob | list_files | Grida binding uses a path-scoped directory-listing shape; VFS hosts should provide it, real-fs hosts may omit it when command/search tools are stronger. |
grep | grep_files | Same shape; literal substring search (regex is not shipped). |
bash | exec_command, write_stdin | A command may outlive one call: the first starts it and waits briefly; the second reads, types into, or interrupts it. |
todo | todo_write | Same shape; replace-all semantics. |
task | not yet shipped | Subagent spawn surfaced behind editor flows; expose as task once stable. |
question | question | Shipped. Pauses the run on a human (client-resolved survey card); interactive hosts (desktop, serve daemon) answer it, headless hosts return a fixed refusal. |
web_search | not yet shipped | Host-bound provider; out of scope for the first cut. |
web_fetch | not yet shipped | As above. |
skill | not yet shipped | Discovery layer pending. |
tool_search | tool_search (proposed) | Two-level (literal + semantic) proposed below; not yet implemented. |
Backends
Grida's filesystem tools are storage-agnostic by signature. The same
read_file({ path }) call works against any backend; what differs is
the adapter under the fs, not the schema the model sees.
| Backend category | Where | Use case |
|---|---|---|
| In-process storage | application memory | Tests, scratch documents, ad-hoc agent runs. |
| Browser storage | browser origin | Web environment (per agent/environments / web). |
| Host-scoped storage | local host filesystem | Opened Desktop/agent workspaces under the host's containment policy. |
| Remote storage | service boundary | Multi-tenant cloud product surfaces. |
A path can be bound to live state (an editor, a doc model) or pure in-memory storage (notes, scratch). Both shapes share the API.
Per-tool deviations and Grida extensions
Items where Grida's binding deviates from or extends the RFC shape.
read_file
Returns the file's current text content. Read is how the agent understands an
existing file and obtains exact edit context; it is not an authorization event.
The tool exposes no session-local freshness token to the model. Grida bounds
model-readable and model-mutable text files at 1 MiB of UTF-8; larger files
return too_large. A storage read failure returns io_error, never
not_found, so the agent cannot mistake an inaccessible existing file for a
safe path to recreate.
edit_file
Match-and-replace edit. The default write path — cheap, safe, must locate the change.
Each invocation loads current content and finds old_string. Where the storage
layer supports an optimistic publication precondition, a detected concurrent
change produces stale without clobbering the newer bytes. This narrows the
validation-to-publication gap; it is not a claim of cross-process atomicity. A
prior read_file is useful but not required: content from a successful
write_file is already valid edit context, including after a pause or resumed
run.
Matching: literal substring first, then a whitespace-normalized
fallback. Ambiguous matches reject unless replace_all: true. The
strategy is conservative on purpose: it tolerates whitespace drift, not semantic
or broadly fuzzy matches.
write_file
Full-file upsert. It creates a missing path or replaces all content at an
existing path. The model-facing shape has no version argument: choosing this
tool is the explicit intent to perform a last-writer-wins wholesale write.
Targeted changes belong in edit_file.
Success means the full write has completed before the result returns.
Content above the shared 1 MiB text bound is rejected with too_large, so every
successful write can still be read and edited after a resumed run.
list_files
Grida adopts a path-scoped directory-listing shape for the RFC's filesystem-discovery primitive. Despite the current Grida id, this tool is not a whole-workspace inventory.
list_files({
path?: string, // defaults to "/"
offset?: number,
limit?: number,
}) -> {
path: string,
folders: string[],
files: string[],
truncated: boolean,
next_offset?: number,
}
Contract:
pathis rooted in the agent workspace or virtual filesystem. It must not be a general host-absolute path.- The result lists only the direct children of
path, grouped into folders and files. - The result is sorted, paginated, and explicit about truncation.
list_filesdiscovers names only. It does not return file content or provide textual edit context.- For filename-pattern search, use a separate glob / find-path tool rather than overloading this directory-listing result.
Implementation guidance:
- VFS / OPFS / memory backends: provide
list_files. A virtual filesystem may not have a shell,find,tree, orrg, so the structured directory-listing tool is the portable way for the agent to discover reachable paths. - Real filesystem backends: treat this tool as optional. A
shell-capable real-fs agent often gets better behavior from explicit
commands (
rg --files,find,ls,tree) because those tools follow mature ignore rules, stream large output, and make scope visible in the command. A flat "all known files" tool can degrade agent quality by confusing the model into trusting an incomplete or stale index as ground truth. - Do not hide truncation. If a backend is indexed, capped, or ignore-filtered, the tool result must say so in-band.
grep_files
Literal substring search across every known file. Returns one entry
per matching line with a 1-indexed line number and the full line
text. Mirrors grep -n -F (case-sensitive, fixed-string by default;
pass case_sensitive: false for -i). A result may provide enough
text for a unique edit, but the agent should read the file when it
needs broader context.
Roadmap:
- Level 1 (shipped): literal substring search. Cheap, deterministic, works offline.
- Level 2 (future): semantic / RAG search. Higher cost; will ship as a separate tool name (e.g.
semantic_search) so the model picks the cost tier explicitly.
todo_write
Plan and track work. Pass the complete list of todos every call — the prior list is replaced wholesale.
{
"todos": [
{
"content": "Add a star",
"activeForm": "Adding a star",
"status": "in_progress"
}
]
}
- Exactly one
in_progressat a time. Enforced socially by the prompt; the visible list makes drift obvious. - No batched updates. The model should update as it works.
- Replace-all. No per-item ops; the whole list is the input.
Use it when the work is non-trivial (multiple edits, exploration, anything you'd break into steps). Skip it for one-shot edits.
exec_command and write_stdin
Grida's binding of the RFC's bash, split in two because a command can
outlive the call that started it: a development server, a watcher, a long
build, or an interactive program.
exec_command({
cmd: string, // command line, run as `<shell> -c cmd`
workdir?: string, // absolute; defaults to the selected directory's root
tty?: boolean, // pseudo-terminal; otherwise pipes with stdin closed
yield_time_ms?: number, // wait before returning; default 10000, 250–30000
max_output_tokens?: number, // output budget; default 10000, host-capped
// plus the host's approval fields where grants are scoped per directory
})
write_stdin({
session_id: number, // from an earlier result
chars?: string, // empty polls; "\u0003" interrupts
yield_time_ms?: number, // writes: default 250, at most 30000; polls: 5000–300000
max_output_tokens?: number,
})
Both return text:
Wall time: 1.2345 seconds
Process exited with code 0 (or: Process running with session ID 3)
Original token count: 12 (only when the output was shortened)
Output:
<output>
The contract:
- The shell is named, not chosen by the model. It is the user's own
POSIX shell when that is a known one at an absolute path, otherwise
/bin/sh, and never a login or interactive shell. The call carries no environment, stdin, or shell selection. - A call waits for its whole yield. It returns at the end of its wait or when the command ends, never at the first output, so one call sees everything that arrived in that time.
- A command that ends within its wait has no session. Its exit is reported once and nothing is retained.
- A still-running command belongs to the conversation, not to the call or the turn. Ending, cancelling or pausing a turn, waiting for an approval, and resuming elsewhere leave it running; a later turn reaches it by its session ID. An explicit stop, revocation of its directory, deleting the conversation, eviction, and host shutdown end it, and the host's own exit ends it too.
- Session IDs are per conversation, increasing, and never reused. The end of a session is reported once; after that its ID is unknown.
- Pipes accept only an interrupt. A terminal session receives the characters as typed, including the interrupt character.
- Output keeps its start and end. Over budget, the middle is replaced with a counted truncation marker; bytes the host could not retain are counted where they were dropped. An end by signal or stop is reported as such, never as an exit code.
- Approval belongs to the start. Input to an approved session needs no approval of its own and reaches only the conversation's own sessions. A pre-execution policy check therefore sees the command line, not later input; a policy that must see every command refuses interactive shells.
- Recovery is honest. A start or input whose result the host cannot account for after an interruption is uncertain; an empty poll may be repeated.
- Bounded. A conversation keeps a bounded number of sessions. Starting another evicts the least recently used one, never one of the most recently used or one in use, ended ones first; if none qualifies, the start is refused.
Security expectation: command execution must run under a real sandbox boundary. Every command runs under execution confinement with its own authority set; see execution authority.
view_image (Grida extension)
Grida's binding of the RFC visual perception
contract — the visual twin of read_file. read_file returns text and
stays text-only; view_image returns a raster image the model sees as
pixels.
view_image({ path }) →
| { ok: true, mime, width?, height?, bytes, data /* base64 */ }
| { ok: false, reason: "not_found" | "unsupported_type" | "too_large", message }
Binding facts as Grida currently ships them:
- v1 = raster bitmaps (
png/jpeg/webp/gif), identified by magic bytes (never the extension). Rendering non-bitmap sources (svg / text / code → pixels) is the planned next step under this same tool name; the contract is shaped to absorb it without a rename. - Result-to-image lowering uses Strategy 1 (
vision / lowering): the tool result carries the base64 payload and the tool declares a model-output lowering to a media block, so the perception reproduces from the persisted result on every rebuild — no bespoke replay path. - Retention. A stale
view_imageresult drops its payload (lowering degrades to a naming descriptor); the bytes stay durable and the model re-views by calling the tool again. Pasted inline images are NOT auto-evicted (no re-view reference) — seevision / retention. - Capability. Needs only
fs.readover the path — the same read scope asread_file;view_imagejoins the registry only when the host wires a byte source. Grida's workspace agent passes its filesystem (it exposes a raw-bytes read), so the tool sees workspace images by path. - Known v1 gap. A binary image is not yet surfaced by
list_files(the text-hydrate skips it), so the agent perceives images the user names by path; autonomous discovery is a tracked follow-up.
It lives alongside the other fundamentals (the perception module is a
sibling of the fs tools, not part of tools-image.md, which is image
generation — a different verb).
tool_search (proposed)
As the toolkit grows — fs + todos + canvas (15+) + future env tools
- user-installed MCP servers — the model can't reasonably hold every tool's full schema in its working context. The RFC names a two-level (literal + semantic) discovery shape; Grida's binding will mirror it.
| Level | Search type | Cost | When |
|---|---|---|---|
| Level 1 | Text / token match | Zero | Default. Substring + ranked keyword match on tool name + description. |
| Level 2 | Semantic / embedding | Cheap, non-zero | Optional fallback when text match is empty. |
The model picks the level via a hint (mode: "literal" | "semantic"),
default literal. Level 2 is invoked only on miss, keeping the
typical path zero-cost.
tool_search({
query: "send slack message", // free-text intent
// or
select: ["read_file", "edit_file"], // exact tool names
max_results?: 5,
})
→ {
tools: [
{ name: "slack_post_message", description: "...", schema: {...} },
...
]
}
Status: proposed. The four shipped fundamentals plus the canvas tools are enough that we haven't felt the pinch. When the form-builder agent surface or the first MCP integration lands, this becomes the next thing to ship.
What lives where
crates/grida-agent/src/file_tools.rs— filesystem fundamentals (source)tool_search— not yet created; see proposal above- Document-specific tools belong to their editor implementations. See
tools-canvas.mdfor the canvas capability catalog.
Adding a new fundamental tool
Bar: would every agent want this, regardless of env? If yes, it's fundamental. Examples that pass the bar: filesystem, planning, tool discovery, time/clock, env metadata. Examples that fail: anything canvas-specific, anything network-bound (those are MCP or per-env).
Process:
- Confirm the RFC carries the shape — if not, propose it to
../agent/tools.mdfirst. - Implement it in the native agent (
crates/grida-agent) with its own module, tool schema, and pure-logic tests. - Add a row to the naming map above and a per-tool section below it.
- If it's vfs-only (only needed because we lack command execution), mark it so — the host can then drop it when command execution is available.
See also
- Agent RFC / Tools — the locked-set contract this page binds.
- Agent RFC / Visual perception — the read/view split
view_imagebinds. - Agent RFC / Environments — which capabilities each environment exposes.
- Canvas Tools — canvas-only tool surface.
- Image Tools — image-generation tool surface.