12.6. App Control Tool Reference¶

This page is the per-tool reference for the application-control tools the host exposes to plugins that opt into tool calling. For how a plugin opts in and renders the loop, read the Tool Calling section of the Plugin Authoring Guide first. This page assumes you have.

These tools share one Rust tool category, AppControl, and one property: every one goes through an existing internal service (the inference pool, the model manager, the download manager, the statistics manager, Hugging Face search, or squad storage) rather than any new or platform-specific code path. They observe and operate the running application.

The catalog¶

Every tool below is category AppControl. "Approval" is required when the tool's definition sets requires_approval: true (mutating tools), and none for read-only tools. All backend tools are desktop-only (see Desktop-only); navigate_to_page runs in the WebView.

Tool	Approval	Purpose
`list_models`	none	List models known to this application: downloaded local models and their loaded state, with recommendation-grade metadata and a device-fit label.
`get_inference_status`	none	Live status of the local inference server pool: which models are loaded, their serving aliases, ports, and health.
`list_downloads`	none	List active and recently finished model downloads with progress.
`get_token_usage_stats`	none	Token usage and request statistics: totals, a per-day breakdown, and per-model usage.
`search_huggingface_models`	none	Search Hugging Face for downloadable models and report whether each fits this machine's memory and accelerator. Network-requiring.
`list_squads`	none	List existing squads with their name, description, agent count, and status.
`list_squad_templates`	none	List installed squad templates, both built-in and user-created.
`load_model`	required	Load a downloaded local model into the inference server. Starts loading and returns immediately.
`unload_model`	required	Unload a currently loaded model from the inference server.
`download_model`	required	Download a model file from Hugging Face into the local model store. Starts the download and returns immediately. Network-requiring.
`create_squad`	required	Create a new squad, preferring a `templateId` from `list_squad_templates` so it starts with a proven agent lineup.
`navigate_to_page`	none	Navigate the application to a top-level page through the host router. A frontend tool: it executes in the WebView, not the backend.

A plugin advertises a tool only when the tool's name is in its manifest tools allowlist. The bundled Companion Chat plugin allowlists all twelve.

Approval and prompt-injection posture¶

The four mutating tools (load_model, unload_model, download_model, create_squad) carry requires_approval: true. The SDK never runs one without an explicit per-call user approval, and denies by default when the plugin supplies no approval callback. This is the primary defense against indirect prompt injection: a companion that injects Memory Bank content into its system prompt is injecting text an attacker may have influenced, so a state-changing action must never auto-execute. See Deny-by-default approval.

The read-only tools are auto-approvable and run without a prompt, but their activity is still surfaced through the onToolCallStart / onToolResult callbacks.

Initiate-and-poll for long-running actions¶

load_model and download_model do not block the tool result until the operation finishes. They validate the request, start the operation in the background, and return immediately. This keeps a tool turn fast and avoids model or HTTP timeouts on a multi-minute download. The model observes progress by polling the read-only status tools:

get_inference_status reflects a model transitioning to loaded.
list_downloads reports download progress and completion.

The bundled companion's system prompt encodes this behavior so the model reports that the action started and then polls, rather than waiting.

Local-first model recommendation¶

There is no dedicated "recommend a model" tool. Recommendation is an emergent behavior the model performs over grounded, fit-annotated candidates from two tools:

list_models carries a device-fit label for each already-downloaded model.
search_huggingface_models covers not-yet-downloaded models, each annotated with whether it fits this machine's memory and accelerator.

The companion's system prompt encodes a local-first ordering: check downloaded models first with list_models, recommend a suitable one whose fit is not "too large", and only call search_huggingface_models when nothing local fits. A proposed Hugging Face model must be downloaded before it can be loaded, and the model is told to say so.

Offline and air-gapped deployments¶

Two tools require network access: search_huggingface_models and download_model. An air-gapped enterprise deployment is supported without a separate mode. The enterprise tool policy can deny those two tools individually, and because the advertised tool set is the intersection of the manifest allowlist, the host catalog, and the enterprise policy (recomputed every turn), a deployment that denies them leaves the plugin advertising only the local tools. Recommendation and loading then operate entirely on already-downloaded models, and no download is ever proposed or attempted. On a plain network failure, a network-requiring tool fails with a descriptive tool error rather than hanging. No plugin code change is needed for either case.

Enterprise tool policy¶

Every tool executes through the host's built-in execute path, which runs the enterprise tool-policy gate on every call (Tauri, REST, and registry-fallback paths alike). A tool an administrator has denied is filtered out of the advertised set, and even a model that names it anyway receives a structured policy-denied result instead of execution. Plugin-initiated calls inherit this automatically because they ride the same execute path; no plugin-side policy logic exists or is needed.

Desktop-only¶

Every backend AppControl tool needs a Tauri application handle or process-global application state (the inference pool, download manager, statistics manager, or squad storage), so all of them are desktop-only. They are listed in the host's single headless-capability gate, which sets available_in_headless: false. The SDK loop reads that flag from the live catalog, so in a headless or browser context these tools are simply never advertised to the model, and the turn degrades to plain chat if nothing else is available. navigate_to_page is a frontend tool that executes in the WebView and is likewise marked non-headless. Making the backend tools headless-capable would require plumbing pool and download state into the REST execute path and is out of scope here.