Harness tools¶
tools.Harness builds one curated toolset for an agent that works in a directory: read and search files, change them, run code, fetch URLs, and keep notes in a scratch workspace. Every tool is confined to one root, and anything that changes files or runs code asks for approval first.
import (
"github.com/urmzd/saige/agent"
"github.com/urmzd/saige/tools"
)
a, err := agent.New(cfg, agent.WithHarnessTools(tools.HarnessOptions{
Root: "/path/to/project",
Groups: tools.AllGroups(), // default: tools.ReadOnly()
}))
if err != nil {
return err
}
An agent has no tools unless you add them. WithHarnessTools is the one-call way; tools.Harness returns the same toolset when you want to handle errors or inspect it first.
Tools¶
| Tool | Group | Capability | Approval | Description |
|---|---|---|---|---|
read_file |
read |
read | no | Numbered lines, one page at a time (offset, limit) |
list_dir |
read |
read | no | Entries of one directory: directories first, file sizes, symlink targets |
glob |
read |
read | no | Paths matching *, ?, [...], and ** |
grep |
read |
read | no | RE2 search with an optional glob filter and ignore_case |
write_file |
write |
write | yes | Create or overwrite a file, atomically |
edit_file |
write |
write | yes | Replace an exact, unique string, or every occurrence |
execute_code |
exec |
write or destructive | yes | Run shell, python, or go code behind a sandbox |
fetch_url |
web |
read | no | Fetch an http or https URL as text |
scratch_write, scratch_read, scratch_search |
always | write, read, read | no | The run's scratch workspace, separate from the root |
The file tools come from tools/fs, execute_code and the sandboxes from tools/exec, and fetch_url from tools/fetch. The scratch tools are agent/workspace tools.
execute_code¶
| Argument | Description |
|---|---|
language |
One of the languages the sandbox has: shell always, python when python3 or python is present, go when go is present. The schema lists only those. |
code |
The program. It reaches the interpreter through a quoted heredoc, so the shell expands nothing in it. |
cwd |
Working directory inside the root |
timeout_seconds |
Per-call limit, capped by MaxTimeout |
Python reads the program from standard input. Go code must be a main package that imports only the standard library; it is built in a private directory with its own module and GOTOOLCHAIN=local, then run in cwd.
The command policy (exec.Policy.Commands) checks shell code, and checks the interpreter or compiler for the other languages. Programs in exec.DefaultDeny, such as sudo, are refused.
Safety defaults¶
| Default | Detail |
|---|---|
| Read-only | Without Groups, only the read group is enabled. |
| Root confinement | ../ traversal, absolute paths outside the root, and symlinks that leave it are refused by every file tool and by cwd. The file tools work through an os.Root, which checks each path when it is used, so a symlink swapped in between calls cannot lead out. |
| Approval | write_file, edit_file, and execute_code carry a human_approval marker. There is no option to remove it. |
| No network for code | Network defaults to exec.NetworkDeny. On the subprocess sandbox that needs sandbox-exec (macOS) or unshare (Linux); without them, building the exec group fails with exec.ErrNetworkIsolationUnavailable rather than running code with the network open. |
| Clean environment | Code runs with only PATH, HOME, USER, LANG, LC_ALL, TERM, TMPDIR, and TZ from the parent. API keys in your environment do not reach it. |
| Time limits | 2 minutes per call by default, 10 at most. Set Timeout and MaxTimeout. |
| Private addresses | fetch_url refuses loopback, private, link-local, and cloud metadata addresses, checked after DNS on every connection. |
| Output limits | A built sandbox keeps up to 1 MiB of stdout and stderr each (MaxOutputBytes). |
| Spill | Any result over 16 KiB is stored in the workspace and replaced by a 2 KiB preview naming its saige-artifact:// URI. The model pages through the rest with scratch_read. Tune with Spill, or turn it off with NoSpill. |
Capability classes and grants¶
Each tool declares a capability class, which gates and the approval policy judge. execute_code takes its class from the sandbox:
| Sandbox | Network | Class | What an approval grant can do |
|---|---|---|---|
docker |
denied | write | A tool or session grant covers later calls |
subprocess |
any | destructive | Nothing: every call is asked about |
| any | allowed | destructive | Nothing: every call is asked about |
A subprocess can change files anywhere the user can, so it is never write-class. A Docker container mounts only the root, so its effects stay in the workspace. See approval policy and grants.
Sandboxes¶
SandboxKind |
Isolation |
|---|---|
subprocess (default) |
A child process in its own process group, killed as a group on exit, timeout, or cancel. Network denied by the platform wrapper. |
docker |
A fresh container per call: the root mounted read-write at /workspace, a read-only image filesystem with a private /tmp, all capabilities dropped, no-new-privileges, 1 GiB of memory, 256 processes, no network, and the caller's uid and gid. The container is removed on timeout or cancel. |
The Docker image defaults to python:3.13-slim (DockerImage changes it). Pull it before the first run, because a pull counts against the call's time limit. Building the Docker sandbox fails clearly when Docker cannot be used:
exec.ErrDockerUnavailable: thedockerCLI is missing or its daemon does not answer.exec.ErrMountNotShared: the Docker host cannot see the root. VM-based hosts often share only the home directory, so a workspace elsewhere would appear empty inside the container. Use a root inside a shared directory.
Pass your own exec.Sandbox in Sandbox to use another backend. Report Isolation{Filesystem: true} only when commands cannot change files outside the working directory and private temporary space.
Options¶
| Field | Default | Meaning |
|---|---|---|
Root |
required | Directory every tool is confined to |
Groups |
ReadOnly() |
Any of GroupRead, GroupWrite, GroupExec, GroupWeb; AllGroups() for all |
Sandbox |
built | An exec.Sandbox for execute_code |
SandboxKind |
subprocess |
subprocess or docker, when Sandbox is nil |
DockerImage |
python:3.13-slim |
Image for the Docker sandbox |
Network |
deny |
deny or allow for execute_code |
Policy |
exec.DefaultPolicy() |
Command, environment, and time policy |
Timeout, MaxTimeout |
2m, 10m | Default and maximum per-call limit |
Languages |
detected | Limit the languages offered |
MaxOutputBytes |
1 MiB | Output kept by a built sandbox, per stream |
Workspace |
in memory | Store for spilled results and scratch artifacts |
Spill |
16 KiB, 2 KiB preview | workspace.SpillOptions |
NoSpill |
false | Return large results whole |
FS, Fetch |
none | Extra fs.Option and fetch.Option values |
The toolset's workspace becomes the agent's workspace unless agent.WithWorkspace sets one. Spilled results and the scratch tools always use the workspace attached to the call, so a sub-agent gets a read-only view.
Examples¶
Library: read and run code, with grants¶
set, err := tools.Harness(ctx, tools.HarnessOptions{
Root: dir,
Groups: []tools.Group{tools.GroupRead, tools.GroupWrite, tools.GroupExec},
SandboxKind: tools.SandboxDocker,
})
if err != nil {
return err // for example exec.ErrDockerUnavailable
}
a, err := agent.New(cfg, agent.WithToolset(set), agent.WithApprovalPolicy(agent.ApprovalPolicy{}))
if err != nil {
return err
}
stream := a.Invoke(ctx, []types.Message{types.UserMsg(types.Text("Which test fails, and why?"))})
for d := range stream.Deltas() {
if m, ok := d.(types.MarkerDelta); ok {
// Ask the user. Approving with a session grant stops further
// questions about write-class calls in this conversation.
stream.ResolveMarkerErr(m.ToolCallID, agent.Resolution{
Approved: true, Approver: "user:ada",
Grant: &types.GrantRequest{Scope: types.GrantSession},
})
}
}
agent.WithHarnessTools(opts) does the same in one option. When the toolset cannot be built, every run of that agent fails with the error.
Disclose tools on demand¶
A large toolset costs context on every turn. Pin the core read tools and let the model find the rest with tool_search:
deferred := selector.NewDeferredTools(set.Core()...) // read_file, list_dir, grep, scratch_read
a, err := agent.New(cfg,
agent.WithToolset(set),
agent.WithToolPolicy(deferred),
agent.WithTools(deferred.Tool()),
)
if err != nil {
return err
}
Discovery is disclosure, not permission: a discovered tool still passes through gates and approvals.
CLI¶
saige agent run - take --tools:
| Value | Tools |
|---|---|
none |
No built-in tools. The default for ad hoc runs. |
readonly |
read_file, list_dir, glob, grep, and the scratch tools. |
harness |
Every group |
| a group list | For example read,exec |
saige agent run - --tools readonly "Summarize this repository"
saige agent run - --tools harness --workspace ./repo --approve allow "Run the tests"
saige agent run - --tools read,exec --sandbox docker --approve allow "Run the tests"
saige agent run - --tools harness --approve allow "Run the tests and summarize failures"
--workspace sets the root (default .), --sandbox picks subprocess or docker, and --exec-network sets deny or allow. agent run cannot prompt, so --approve decides: deny by default, or allow for explicitly authorized execution.