Tools overview

Tools

Tools are the only path from model intent to system effect. Carina normalizes tool calls so policy, audit, and UIEvery tool call is a capability check + audit event before Zig executes. treat them uniformly.

Toolchain layout

• 📁bin/
  • 📄carina-scan
  • 📄carina-grep
  • 📄carina-diff
  • 📄carina-patch-native
  • 📄carina-run
  • 📄carina-pty

📂Filesystem

list · read · search · patch — always workspace-scoped.

⌘Shell

run via risk-classified CommandExec + allowlists.

Built-in agent tools

See the full action table in Agents overview. Families:

• Filesystem: list, read, search, patch
• Shell: run (risk-classified CommandExec)
• Memory: governed long-term entries
• Code intelligence: search / symbols / map / def / refs / impact
• MCP: external servers via governed manager
• Orchestration: spawn, workflow, best_of_n
• Human: ask_user

Zig native toolchain

Binary	Role
carina-scan	Workspace file tree
carina-grep	Structured search
carina-diff	Structured diff
carina-patch-native	Apply / verify / rollback / dry-run
carina-run	Command execution with timeout / env allowlist
carina-pty	Interactive terminal sessions

These emit machine-readable JSON and never bypass kernel policy.

Code intelligence

Tool	Result
code.search	Ranked keyword and semantic matches
code.symbols / code.def / code.refs	Definitions, references, and precision provenance
code.impact	Governed transitive dependents
code.map	A token-bounded projection of the workspace symbol graph

Large workspaces do not block the agent on a first-use full scan. Carina builds one resumable graph per workspace in bounded background batches. While it is building, code.map returns explicit progress and the best available partial projection; a metadata-only overview is used until the first semantic batch is ready. Completed graphs are reused across daemon restarts when the persisted source fingerprint still matches the workspace.

Index coverage: complete; graph: 6434 indexed files, 44120 symbols, 228788 edges, 82687 chunks;
projection: 37/5689 files and 37/44120 symbols (pagerank-domain-diverse, about 1017 tokens).

The finite projection is not presented as an exhaustive dump. PageRank provides global relevance; selection covers top-level domains and ranked files before repeating a file. Each retained symbol carries a global rank plus incoming and outgoing edge counts. Ingestion, status, and map reads all remain gated by the session’s CodeIndex and FileRead policy.

Safety rules

1. Every tool has a capability requirement
2. Arguments are validated before execution
3. Outcomes (success, denial, error) are audit events
4. Plugins and tools carry manifests; undeclared capability use → PolicyViolation

Source of truth

• Agent tool table + Zig native bins (carina-scan, carina-grep, carina-patch-native, …)
• Capability requirements: Policy · protocol/capabilities/
• Related: MCP · Agents · CLI reference

Next

• MCP — external tools still policy-gated
• Audit — every tool outcome is an event