Documentation
¶
Overview ¶
Package toolset is the built-in agent_toolset_20260401: the six tools the platform executes for the model — bash, read, write, edit, glob, grep — run inside the session's sandbox.
Two halves. Tools turns an agent's toolset entry into the definitions the model is handed (name, description, input schema); Runner.Run executes one call of a named tool against a sandbox. Nothing here talks to the event log or the work queue: what a tool call means for the session is the executor's, and this package only knows how to run one.
The reference implementation of these six is anthropic-sdk-go's tools/agenttoolset, which runs them on the host and therefore has to confine the file tools to a workdir and warn that bash cannot be confined at all. Here the container IS the confinement, and bash runs in it like everything else, so the file tools resolve relative paths against the workdir and otherwise let a path be a path: a model that wants /etc can read it with bash regardless, and a lexical check that bash ignores is theatre, not a boundary.
Divergences from that reference, all deliberate:
- No workdir confinement (above). Absolute paths and absolute glob patterns are accepted.
- grep shells out to GNU grep inside the sandbox (PCRE where the image's grep has it, POSIX ERE otherwise) rather than preferring ripgrep and falling back to a Go walker. One implementation, one behaviour, and no dependence on what the image happens to ship beyond the /bin/bash the sandbox already requires.
- The tools carry no state between calls except bash's, which is the shell package's snapshot; there is no per-runner session object to close.
Index ¶
Constants ¶
const ( // MaxOutputBytes caps what a tool call returns to the model. The sandbox // caps a command's output an order of magnitude higher (that cap is a // memory guard on the executor); this one is the model's context budget, // and it is the tool result that goes on the event log forever. MaxOutputBytes = 100 << 10 // DefaultTimeout bounds a tool call the model did not time itself, and // MaxTimeout bounds the one it did. A model-chosen timeout is a lease the // executor has to keep alive, so it cannot be unbounded. DefaultTimeout = 2 * time.Minute MaxTimeout = 10 * time.Minute )
const DefaultAgentToolsetPolicy = domain.PolicyAlwaysAllow
DefaultAgentToolsetPolicy is the permission policy a built-in tool resolves to when its agent_toolset entry sets none. The plan states the reference resolves the agent toolset to always_allow; the wire types carry no resolved default to corroborate that, so this is the plan's value, not a recorded one — flip this one constant once a real managed-agents endpoint can be recorded.
Variables ¶
This section is empty.
Functions ¶
func Policies ¶
func Policies(raw json.RawMessage) (map[string]domain.PermissionPolicyType, error)
Policies resolves the permission policy of every built-in tool an agent_toolset_20260401 entry enables, keyed by tool name. It mirrors Tools' enable resolution, so disabled tools are absent; the brain reads it to stamp evaluated_permission on each tool_use and to decide whether a turn's calls suspend for human confirmation.
func Tools ¶
func Tools(raw json.RawMessage) ([]json.RawMessage, error)
Tools returns the model-facing definitions of the built-in tools an agent_toolset_20260401 entry enables, in the wire's order.
func Validate ¶
func Validate(raw json.RawMessage) error
Validate checks that an agent_toolset_20260401 entry resolves — its enable flags and the permission policies of its enabled tools are well-formed. It is the create-time counterpart to Tools/Policies: an entry that fails here would otherwise be stored on the agent and wedge every turn when the brain resolves it, so the API validates at agent creation to make a malformed toolset a 400 instead.
Types ¶
type Result ¶
Result is one tool call as the model sees it. IsError marks a tool-level failure — a missing file, a bad regex, a nonzero exit — which the model reads and can recover from. A backend fault (the sandbox is gone, the daemon is unreachable) is never a Result: it comes back from Run as an error, and what happens to the tool call then is the executor's decision, not the model's.
type Runner ¶
type Runner struct {
Sandbox sandbox.Sandbox
// Session scopes the bash shell's state in the container.
Session domain.ID
// Workdir is where relative tool paths resolve. Empty means the sandbox's
// own default, which is where its Exec already runs.
Workdir string
}
Runner executes built-in tool calls inside one session's sandbox.
Source Files