Files & Workspace Tools

zo separates explicit file markers from workspace-wide tools. Choose the narrowest access that fits the task.

Permission overview

Input	Model access
`@file`	File content is included in the prompt
`!file`	The model may write that path but does not receive existing content
`@!file`	Existing content is included and the model may update that path
`--files read`	Dynamic list, find, search, and read tools across the workspace
`--files write`	Read tools plus create, replace, and edit tools across the workspace

--files read can still be combined with !file or @!file; writes then remain limited to those explicit paths.

File markers

# Read one or more files
zo @Cargo.toml 'Explain these dependencies'
zo '@src/*.rs Review this module'
 
# Create a specific file
zo 'Document this project in !ARCHITECTURE.md'
 
# Read and update a file
zo 'Add structured errors to @!src/main.rs'

zo expands *, ?, and bracket glob patterns itself, then sorts and deduplicates resolved paths. Input globs and output globs must match at least one existing file. A literal !new-file may create a file; @!file requires an existing file because its content is read first.

Markers start at a whitespace boundary and end at whitespace. Paths containing spaces cannot be represented by quoting the marker. Common trailing punctuation is removed when it is clearly sentence punctuation.

Referenced input must exist and contain valid UTF-8. Prompt text, STDIN, and referenced contents share the 1 MiB default turn limit.

Workspace tools

Read mode exposes bounded tools for listing a directory, finding paths, exact/regex content search, and ranged file reads:

zo --files read 'Find where API requests are constructed and explain the flow'
zo --chat --files read 'Help me explore this codebase'

Write mode additionally exposes full-file writes, exact single-match edits, and line-range replacement:

zo --files write 'Rename the parser type and update its tests'

Use --verbose to see compact tool calls or --debug to inspect full arguments before the initial request.

Write approval

Creating a new file does not ask again: the explicit marker or --files write already granted creation access.
Replacing or editing an existing file shows a focused colored diff and asks for approval.
--accept-writes or -y skips that approval.
--non-interactive denies an overwrite unless it was already accepted with --accept-writes.
Parent directories must exist; zo does not create them automatically.

Tool-aware responses still stream between tool calls.

Path security

Markers and file tools resolve relative to the current working directory. Absolute paths, .. traversal, and symlink escapes are rejected.

Dynamic tools and output operations block dotfiles and hidden directories unless --hidden is supplied. A directly referenced hidden input such as @.env is an explicit read and can be included without enabling hidden tool access; writing !.env or exploring hidden paths still requires --hidden.

Shell access is independent. --files read --shell does not make approved shell commands read-only.

Chat behavior

Markers are parsed on every chat turn. Newly granted output paths remain available for later turns in that session:

zo --chat --files read 'Help me improve this project'
> @src/main.rs Explain this entry point
> Update @!src/main.rs with the suggested error message
> Revisit that file and simplify the wording

Chat → · Shell Tools & Policies → · CLI Usage →