Tools

Tools

Tool extensions are callable units the LLM can invoke: read a file, run a shell command, fetch a URL, edit a document, ask the user a clarifying question. Tools follow the ai-sdk tool() shape.

contractVersion: 1.0.0

---

Intent

Tools are the work plane. The LLM decides to call a tool; core (under state-machine and security-mode precedence) authorizes and executes it; the result flows back to the LLM.

Tools are extensions because the useful set is open-ended and user-specific. The default tool set is sourced from the agentool package and registered as bundled at boot — see Bundled Tools for the list. Third parties add their own at the global or project layer. Remote tools arrive through MCP and route into the same contract.

---

Contract shape

classDiagram
    class ToolContract {
        kind : "Tool"
        contractVersion : SemVer
        requiredCoreVersion : SemVerRange
        configSchema : JSONSchema
        loadedCardinality : unlimited
        activeCardinality : unlimited
        stateSlot : optional
        discoveryRules : DiscoveryRules
        reloadBehavior : between-turns
        name : string
        inputSchema : JSONSchema
        outputSchema : JSONSchema
        executor : local | remote
        gated : boolean
        deriveApprovalKey : (args) => string
    }

Loading

See Contract Pattern.

---

Tool identity

Tools use flat names — no origin prefix, no scope qualifier. Allowlist entries match on the flat name. Projects may shadow a bundled or global tool by declaring a tool with the same name.

Origin layer for each loaded tool is reported by Extension Discovery and surfaced via /tools and the audit/event stream — not persisted in the slim session manifest. /tools inspection is how a user or operator sees which implementation is bound to which name. Shadowing is an intentional tradeoff: simplicity for users, responsibility for the trust model.

The primary guards against malicious shadowing are:

1. First-run Project Trust prompt.
2. Hard-fail on validation errors in critical categories.
3. Audit trail of every tool invocation with its origin layer.

See Tool Approvals for how shadowing interacts with allowlists.

---

Executor variants

A tool's executor is one of:

Variant	Where it runs
local	In the host process.
remote	Proxied to an MCP server via the core MCP client. See MCP.

Remote tools are declared by the MCP client at registration time; extension authors do not write remote tool contracts by hand. Both variants appear in the same tool registry and are callable through the same contract.

---

Configuration schema

A tool contract's configSchema is tool-specific. Bundled tools' options are defined by agentool; see Bundled Tools. Every tool config schema, however, must accept at minimum:

Field	Meaning
enabled	Whether this tool is visible in the session.
timeoutMs	Default execution timeout. Tools may override per-call.

---

Input and output schemas

Schema	Purpose
inputSchema	Validated before execution. Malformed input fails the call with a typed error.
outputSchema	Declared so the LLM can be told what to expect. Core does not validate tool output against the schema; tools declare it for the model's benefit.

---

Approval model

Each tool controls its approval posture through two fields:

gated: boolean — whether the approval stack runs at all.

• true — every invocation runs through the SM → mode → guard chain.
• false — the tool executes without consulting the approval stack. Suitable for read-only, fully deterministic tools that carry no side-effects worth prompting for.

deriveApprovalKey(args): string — maps runtime arguments to a stable, human-readable cache key. The approval stack uses (toolName, deriveApprovalKey(args)) as the compound approval identity.

Security mode	Behaviour on a new key
ask	Prompt the user; approved keys cache for the session lifetime.
allowlist	Compare the key against allowlist patterns; prompt on miss.
yolo	Skip the gate entirely; no prompt, no cache lookup.

A key approved once is not re-prompted within the same session unless the session manifest is cleared. Project-scope approval caching is optional and must be explicitly enabled.

deriveApprovalKey contract:

• MUST be deterministic: equivalent args → identical key.
• MUST NOT include per-call noise (timestamps, random IDs, request counters).
• MUST NOT resolve secrets or make network calls.

Approval posture is entirely driven by gated + deriveApprovalKey (Q-8). See Tool Approvals for the full approval-stack sequence.

---

Lifecycle

Phase	Tool responsibilities
init	Validate config; prepare idempotent resources (subprocess pool, HTTP client).
activate	Register name and schemas with the tool registry.
deactivate	Drain in-flight invocations; refuse new calls.
dispose	Release resources. Idempotent.

A tool that needs to prompt during init (e.g., an OAuth-guarded remote tool) drives the Interaction Protocol. Tools never prompt outside the Interaction Protocol.

---

Cardinality

Loaded: unlimited. Any number of tools may load.

Active: unlimited. Every loaded tool is callable. The allowlist restricts only which proceed without prompt, not which exist.

---

State slot

Optional. Typical uses:

• Retry counters for idempotent tools.
• Cached expensive-to-recompute data (e.g., repository indexing state).
• Ratchet values for tools that must refuse certain sequences.

Tools that are stateless across turns and resumes declare stateSlot: none. See Extension State.

---

Discovery path

Tools live in a tools/ folder under each configuration scope layer:

Layer	Location
Bundled	Ships with the package.
Global	~/.stud/tools/…
Project	<cwd>/.stud/tools/…

Scope layering applies; later layers shadow earlier ones by name.

---

Ordering

Tools are an unordered category. Tools do not have an order of invocation — the LLM chooses which tool to call. There is no ordering manifest for tools.

---

Reload behavior

reloadBehavior: between-turns. A tool may be reloaded only when no turn is active. The in-flight guard in Extension Reloading holds reloads until the current turn completes or is cancelled.

---

Interaction with core

A tool reads and writes only through the Host API:

• Input validation and output emission.
• Cancellation tokens (host.cancel.tool) — a turn-level cancel aborts running tools.
• Audit events (ToolInvocationStarted, ToolInvocationSucceeded, ToolInvocationFailed).
• Interaction Protocol for tools that must prompt (e.g., Ask-User).
• Env Provider for credentials declared in their config schema — no bulk read.

A tool never reads another tool's state slot, another extension's config, or env values it did not declare.

---

Security notes

• A tool's gated flag and deriveApprovalKey implementation are load-bearing. Declaring gated: false on a tool with side-effects bypasses the approval stack entirely. The Project Trust prompt gates review of project-scoped tools precisely because of this risk.
• Tool input is untrusted. The LLM produces arguments; a tool that dispatches to a subprocess or URL must validate its own input, not trust the model.
• Tool output is untrusted context. A tool that returns the contents of a network fetch may carry injected LLM instructions. See LLM Context Isolation.
• Flat-name shadowing is a real risk. See Tool Approvals for the approval interaction, Project Trust for first-entry guarding, and /tools for post-hoc inspection.

---

Related pages

• Tool Approvals
• Security Modes
• State Machines — SM precedence on tool calls.
• Project Trust
• MCP
• Tool Call Cycle flow
• Parallel Tool Approvals flow
• Bundled tools: see Bundled Tools.

---

Changelog

1.0.0 — initial

• Tool contract as documented above. Local + remote executor variants. Flat-name identity with origin tracking surfaced via Extension Discovery and /tools (not persisted in the session manifest).
• Approval surface is gated: boolean + deriveApprovalKey(args): string. Approval is per (toolName, approvalKey). First use of a new key prompts in ask mode; approved keys cache for the session by default (project-scope optional). allowlist mode treats entries as approval-key patterns; yolo skips the gate.
• No validationSeverity field — failed tools are disabled (omitted from the loaded set); the session continues.