> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getpioneer.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools System

> Built-in tools, dynamic tool bundles, routing, output policies, and retry classification.

`crates/tools` is the runtime layer that turns model tool calls into real actions. The agent loop asks it to build a tool runtime for a turn, then routes each provider tool call through that runtime.

Tool execution is protected by the turn permission and sandboxing system. Each turn carries an effective permission profile and a `TurnExecutionSecuritySnapshot`. The tools runtime evaluates side-effecting actions before execution, checks the relevant filesystem, network, and process policy, and then either executes, rejects, or opens a client approval request.

The tools layer is where model output becomes a side effect. Reading a file, running a command, calling an MCP server, applying a patch, and using computer control all execute on the gateway host.

<Note>
  A remote gateway means the tool runs on the remote host; a local gateway means it runs on the local host. Within that host, Pioneer applies turn permission profiles, resource policies, scoped approval grants, and the selected native or provider sandbox backend.
</Note>

## Why this layer exists

Tools need a common runtime because Pioneer has several capability sources: built-ins, MCP servers, skills, and task orchestration. The model should not need to know which subsystem owns a tool. It should see a clean tool name, JSON schema, and result.

At the same time, Pioneer needs consistent behavior after execution: timeline events, model-visible output, storage output, recovery evidence, retries, and diagnostics. If every subsystem returned raw text directly to the model, context windows would explode and recovery would be unreliable.

## Runtime pieces

| Piece                | Responsibility                                                                                                   |
| -------------------- | ---------------------------------------------------------------------------------------------------------------- |
| Tool registry        | Stores tool specs and handlers by name.                                                                          |
| Tool router          | Selects the handler for a raw tool call and controls which tools are visible to the model.                       |
| Tool runtime         | Executes calls, emits tool events, applies output projection, and returns model-visible results.                 |
| Extension bundles    | Add dynamic tools from MCP, skills, and tasks to the same runtime as built-ins.                                  |
| Permission evaluator | Classifies each tool action and applies the turn's effective permission policy.                                  |
| Approval broker      | Opens user approval requests for actions whose policy behavior is `ask`.                                         |
| Output policy        | Separates what the model sees from what the timeline, storage, and recovery systems retain.                      |
| Retry classifier     | Classifies tool failures as recoverable, fatal, partial, or successful so the agent can decide whether to retry. |

## Permission evaluation

Every tool invocation receives a `PermissionEvaluationContext` containing the workspace, thread, turn, and `TurnPermissionProfileSnapshot`, plus the turn's `TurnExecutionSecuritySnapshot`. Before execution, the orchestrator extracts a `PermissionIntent`, classifies the action kind, and evaluates it against the profile's `ToolPermissionPolicySnapshot`.

Supported action kinds are:

| Action kind            | Typical source                                                           |
| ---------------------- | ------------------------------------------------------------------------ |
| `file_read`            | `read_file`, directory listing, grep-style reads, artifact reads.        |
| `file_write`           | `apply_patch`, generated output registration, file mutation tools.       |
| `shell_command`        | `exec_command` and active shell sessions.                                |
| `network`              | Web fetch/search/download and network-capable tool handlers.             |
| `mcp_read`             | MCP tools classified as read-only.                                       |
| `mcp_write_or_unknown` | MCP tools that mutate state or cannot be safely classified as read-only. |
| `dynamic_skill_tool`   | Skill-provided dynamic tools.                                            |
| `computer_use`         | Native desktop automation and screenshot-driven interaction.             |
| `task_subagent`        | Task creation, attached subagents, and delegated agent work.             |
| `internal` / `unknown` | Runtime-internal or unclassified actions.                                |

Policy evaluation returns one of three behaviors:

| Behavior | Runtime result                                                                                                                                                           |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `allow`  | Emit a permission audit event and execute the tool.                                                                                                                      |
| `ask`    | Emit an approval-request audit event, open `turn/permission/request/opened`, wait for `turn/permission/request/respond`, then execute or reject based on the resolution. |
| `deny`   | Emit a denied audit event and reject the tool call before side effects.                                                                                                  |

Approval requests include a normalized request key and scope hash. If the user chooses `allow_for_turn`, the tools runtime caches that request key for the rest of the turn so matching actions can proceed without repeated prompts. `allow_once` applies only to the current request.

The tools layer emits permission audit events for profile decisions, approval requests, approval resolutions, cached approvals, and denied actions. The gateway persists those events through the same durable turn-event path as ordinary tool lifecycle events.

## Sandbox and resource policy

Permission approval is not the only gate. The orchestrator and handlers also enforce the execution security snapshot:

| Resource         | Enforcement path                                                                                                                                        |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Filesystem       | `FilePolicyChecker` verifies reads and writes against resolved sandbox roots, access mode, canonical paths, missing write parents, and symlink escapes. |
| Network          | `NetworkPolicyChecker` verifies HTTP/HTTPS access against enabled, disabled, or restricted network policy before search, fetch, or download.            |
| Process          | `build_process_spawn_plan` checks shell policy, command risk, cwd access, environment filtering, and timeout caps before a shell command spawns.        |
| Native sandbox   | Shell execution prepares the selected backend (`nono` on Linux/macOS or Windows restricted token) when the snapshot requires it.                        |
| Provider sandbox | CLI-backed runtimes report provider-native sandbox and approval capabilities through the same backend capability snapshot.                              |

Scoped approvals can extend a restricted snapshot for the current invocation or the rest of the turn. For example, approving a specific download can add both the network grant and destination write grant needed for that operation without switching the whole turn to full access.

## Built-in tools

The core built-ins are intentionally small and always eligible for agent turns when tool calling is available:

* `exec_command`
* `write_stdin`
* `read_file`
* `list_dir`
* `grep_files`
* `apply_patch`
* `web_search`
* `web_fetch`
* `download_url`
* `read_skill`
* `request_tools`

Large domain tools are registered in the same router but hidden until turn preflight or an explicit `request_tools` call makes them visible.

| Domain         | Tools                                                                                                                                            |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `memory`       | `memory_search`, `memory_list`, `memory_get`, `memory_remember`, `memory_forget`                                                                 |
| `task`         | `task_create`, `task_wait`, `task_cancel`, `task_update`, `task_detach`, `task_list`, `task_get`, `task_reschedule`, `task_pause`, `task_resume` |
| `artifact`     | `artifact_prepare`, `artifact_register`                                                                                                          |
| `computer_use` | `computer_use`                                                                                                                                   |

Artifact tools are lazy-domain tools. `artifact_prepare` gives the model a safe turn-scoped staging path for a user-visible output file. `artifact_register` imports a completed regular file into the workspace artifact store and binds it to the current turn. Tool authors should not invent filesystem scanning or tool-specific discovery paths; all agent-created user results use this explicit registration contract.

Shell execution uses unified sessions. `exec_command` can start a process and return either final output or a session id. `write_stdin` can continue an existing session. Active sessions are bounded and buffered so long-running commands do not grow memory without limit.

Filesystem tools are intentionally direct: read files, list directories, search with grep-style behavior, and apply patches. Manual patch edits in Pioneer are routed through the patch tool path rather than ad hoc file rewriting. These handlers call the file policy checker before opening paths when a turn security snapshot is present.

Web tools are optional at runtime and controlled by gateway configuration. They can search, fetch, and download with limits. They call the network policy checker before network access; downloads also call the file policy checker before creating the destination file.

Computer use uses native automation/screenshot dependencies where available. It is part of the same tool router, not a special client-side channel, but the `computer_use` schema is hidden until preflight or `request_tools` reveals the `computer_use` domain.

## Lazy visibility

The router stores all specs for a turn, but the model only receives the currently visible subset.

Turn preflight is the first visibility selector. It receives a compact `PreflightToolIndex`: `coreTools` plus concrete hidden-domain `candidateTools` with name, domain, short summary, and mutation flag. It does not receive full JSON schemas. The preflight output `tools.visibleTools` must be exact tool names from `candidateTools`, never domain names.

`request_tools` is the in-turn expansion path. Its schema accepts:

```json theme={null}
{
  "domains": ["task", "artifact"],
  "reason": "Need to delegate work and register generated files."
}
```

`domains` is an enum: `memory`, `task`, `artifact`, or `computer_use`. The handler expands each requested domain to every registered and available tool in that domain, reports already-visible and unavailable tools, and returns a compact result without embedding hidden schemas. The agent loop applies the result before the next provider round and keeps visibility monotonic for the rest of the turn.

## Dynamic tools

Dynamic tools are exposed through `ToolExtensionBundle`.

MCP tools are created from live MCP server catalogs. Pioneer maps a server tool into a callable tool descriptor, then calls back into `McpService` when the model invokes it.

Skill tools are declared by installed skills and validated by the skills runtime. They can represent shell, HTTP, or function-proxy style tools depending on the skill declaration and policy.

Task tools are injected when task orchestration is available. They let an agent create attached tasks, wait for them, cancel them, detach them, and observe terminal child task results.

Dynamic tools do not bypass the router. They use the same runtime and output projection path, and emit the same tool events as built-in tools. The agent loop can therefore handle shell commands, MCP calls, and skill functions through one execution contract.

Dynamic extension tools that are not in the built-in domain map are independent of preflight domain selection and `request_tools`. If an MCP server or skill contributes a turn-specific tool, including through an explicit composer capability, the final visibility pass keeps it available as a dynamic extension when it is registered and has a handler.

Visibility is not authorization. A tool may be visible to the model and still require approval when called. The permission evaluator is the last policy gate before execution.

## Output projection

A tool call produces more than one view of output. The model-visible view may be shorter or structured differently from the timeline view. Storage may keep full output, a summary, metadata only, or nothing depending on policy. Recovery evidence can include exit status, error class, retry hints, excerpts, and fingerprints.

This matters because a large shell output or MCP response should not automatically flood the LLM context window. Tool authors should define output policies deliberately.

## Retry and recovery

Tool failures are normalized into `ToolOutcome` with status and error class. Recoverable errors can trigger another provider round with a retry instruction. Fatal errors are surfaced to the model or fail the turn depending on context.

The agent does not blindly retry forever. Retry decisions are constrained by per-episode and per-tool budgets, and the tool loop itself has a separate round/call budget.

## What not to put here

Provider-specific tool-call parsing belongs in [Provider System](/architecture/providers). The tools crate should receive normalized tool calls.

Prompt prose about when to use tools belongs in [Prompt And Context](/architecture/prompt). The tools crate should define capabilities and execution behavior, not assistant personality.

MCP server lifecycle belongs in [MCP Architecture](/architecture/mcp). Skills installation and trust policy belong in [Skills Architecture](/architecture/skills). The tools layer only receives their already-materialized tool descriptors and handlers.

## Related pages

* [Agent Loop](/architecture/agent-loop) explains when tools are exposed and called.
* [Permission System](/architecture/permissions) explains turn permission modes, security snapshots, sandbox/resource policy, approval requests, and audit events.
* [MCP Architecture](/architecture/mcp) explains MCP-backed dynamic tools.
* [Skills Architecture](/architecture/skills) explains skill-backed dynamic tools.
* [Tasks And Subagents](/architecture/tasks) explains task orchestration tools.
* [CLI Runtime Architecture](/architecture/cli-runtime) explains why CLI-backed agent runtimes are not ordinary tools or providers.