plugins.md

Plugins

Plugins are the tools agents can call. Each plugin is a named collection of kernel functions. Add plugin names to an agent's Plugins list to make them available.

Plugins:
  - FileSystem
  - Shell
  - Git
  - Search

Plugin names are case-insensitive.

---

FileSystem

Read, write, and navigate the local filesystem.

Function	Parameters	Description
read_file	path, startLine (default 1), maxLines (optional)	Read a text file. Returns up to Security.ReadFileSizeLimit characters (default 20,000). Larger files are truncated with a notice. Rejects binary files.
grep_file	path, pattern, contextLines (default 2), maxMatches (default 30)	Case-insensitive text or regex search within a single file. Returns matching lines with surrounding context.
get_file_summary	path	Return a previously saved structural summary, or a character-count notice when no summary exists.
save_file_summary	path, summary	Persist a structural summary of a file so future agents can retrieve it cheaply via get_file_summary.
list_files	directory, pattern (default "*")	List files matching a glob pattern. Returns up to 500 results.
get_file_info	path	Returns metadata: type (file/directory), size, created/modified timestamps, and Unix permissions (on Unix systems).
stat_file	path	Return version, size, and last-modified for a file. Version is a monotonic counter incremented on every write_file call. Returns version=NOT_TRACKED when the file exists but was never written through write_file. Cheaper than read_file for conflict detection.
write_file	path, content, raw (default false), baseVersion (default 0)	Create or overwrite a file. Creates parent directories automatically. When baseVersion > 0, the write is rejected with VERSION_MISMATCH if the current stored version differs — use stat_file first to read the version and detect concurrent writes.
patch_file	path, oldText, newText	Replace an exact block of text in a file. Fails with a hint if oldText is not found verbatim.
delete_file	path	Delete a file if it exists.
set_permissions	path, mode	Set Unix file permissions (chmod). Accepts a 3- or 4-digit octal string such as "755" or "0644". No-op on Windows.
create_directory	path	Create a directory and all intermediate parent directories. Safe to call when the directory already exists.
delete_directory	path, recursive (default false)	Delete a directory. Set recursive=true to remove a non-empty directory and all its contents. Refuses to delete the sandbox root.
copy_file	source, destination, overwrite (default false)	Copy a file to a new location. Creates the destination directory if needed.
move_file	source, destination, overwrite (default false)	Move or rename a file or directory. Creates the destination parent directory if needed.
path_exists	path	Check whether a file or directory exists at the given path.
list_directory	directory, pattern (default "*")	List files and subdirectories in a single directory (non-recursive). Subdirectories are shown with a trailing /. Returns up to 500 entries.

Tip: When FileSystemSandboxPath is configured, all paths are resolved to canonical form and rejected if they fall outside the sandbox root. See Security.

---

Shell

Execute shell commands and scripts.

Function	Parameters	Description
shell_run	command, workingDirectory (optional), timeoutSeconds (default 60)	Run a shell command. Supports pipes, redirects, and chained commands. Captures stdout, stderr, and exit code.
shell_run_script	script, workingDirectory (optional), timeoutSeconds (default 120)	Write a multi-line script to a temp file and execute it. Useful for complex multi-command workflows.
shell_get_env	name	Return an environment variable value (empty string if not set).
shell_set_env	name, value	Set an environment variable for the current session. Inherited by all subsequent shell_run calls. Pass an empty string to clear a variable.
shell_which	program	Return the full path of a program (equivalent to which / where).
shell_get_working_directory	—	Return the effective working directory. Returns the sandbox root if a sandbox is configured.
shell_get_session_temp_dir	—	Return a session-scoped temporary directory. Created on first call; deleted automatically when the session ends.
shell_run_background	command, workingDirectory (optional)	Start a command without blocking and return a job ID. Use for long-running processes (dev servers, watchers, pipelines) where you need to continue working while the process runs.
shell_get_job_status	jobId	Check whether a background job is still running, has completed, or was killed. Includes a short tail of recent output.
shell_get_job_output	jobId	Return the full captured output of a background job so far (stdout + stderr combined, capped at 100 KB).
shell_kill_job	jobId	Terminate a running background job.

The shell used is /bin/bash on Unix and cmd on Windows. The shell binary is located from common system paths at startup.

sudo protection: sudo is always blocked. Any command or script containing sudo (including after pipes, &&, ;, or newlines) is rejected before execution. The denial message instructs the agent to use non-privileged alternatives (pip install --user, pipx, virtualenvs) or, if elevated access is truly required, to tell the user what to run so they can do it themselves.

Shell command approval in --hitl mode: When fuseraft run --hitl is active, every shell_run and shell_run_script call pauses and shows the command for approval before executing. See CLI Reference — Shell command approval.

Security note: When FileSystemSandboxPath is set, the workingDirectory argument is hard-denied if it falls outside the sandbox. The command and script arguments are scanned for absolute paths escaping the sandbox; system binary prefixes (/usr/, /bin/, /opt/, /nix/, etc.) are exempted. Shell scanning is heuristic — for strict containment use CodeExecution (Docker) instead.

---

Git

Read and write a Git repository.

Read operations

Function	Parameters	Description
git_status	repoPath (default ".")	Show working-tree status: staged, unstaged, and untracked files.
git_diff	repoPath, staged (default false), maxLines (default 200)	Show a unified diff. Pass staged: true for the index diff.
git_log	repoPath, count (default 10), ref (optional)	Show recent commit history with hashes, authors, and messages.
git_show	commitRef, repoPath, maxLines (default 300)	Show the content and diff of a specific commit.
git_branch_list	repoPath, includeRemotes (default false)	List branches.
git_stash_list	repoPath	List all stashed changesets.

Write operations

Function	Parameters	Description
git_add	paths, repoPath	Stage files. Pass "." to stage everything.
git_commit	message, repoPath, stageAll (default false)	Commit staged changes.
git_checkout	target, repoPath, createBranch (default false)	Switch to a branch or restore files.
git_create_branch	branchName, repoPath	Create a new branch from HEAD.
git_init	directory (optional)	Initialize a new repository.
git_push	remote (optional), branch (optional), setUpstream (default false), repoPath	Push local commits to a remote. Omit remote and branch to push the current tracking branch. 120 s timeout.
git_pull	remote (optional), branch (optional), repoPath	Fetch and integrate changes from a remote. 120 s timeout.
git_stash	message (optional), repoPath	Save the current working-tree changes to the stash.
git_stash_pop	repoPath	Apply the most recent stash entry and remove it from the stash list.
git_reset	mode (default "mixed"), ref (default "HEAD"), repoPath	Reset HEAD. soft: moves HEAD only. mixed: unstages changes. hard: discards all uncommitted changes — use with caution.

---

Http

Make HTTP requests to external APIs.

Function	Parameters	Description
http_get	url, headers (JSON, optional), timeoutSeconds (default 30), profile (optional)	GET request. Returns response body as text.
http_post	url, body, contentType (default "application/json"), headers, timeoutSeconds, profile	POST request with body.
http_put	url, body, contentType (default "application/json"), headers, timeoutSeconds, profile	PUT request.
http_patch	url, body, contentType (default "application/json"), headers, timeoutSeconds, profile	PATCH request. Useful for partial updates (e.g. closing a ticket).
http_delete	url, headers, timeoutSeconds (default 30), profile	DELETE request.
http_head	url, headers, timeoutSeconds (default 30), profile	HEAD request. Returns response headers only, no body.

API profiles (profile parameter)

All HTTP functions accept an optional profile parameter. When provided, the plugin looks up that name in the ApiProfiles config section and applies:

• Base URL — if url is a relative path (no http:///https:// scheme), it is prepended with the profile's BaseUrl. Absolute URLs are used as-is.
• Default headers — merged with any per-call headers. Per-call headers win on conflicts.
• Timeout — the profile's TimeoutSeconds is used when the caller does not supply an explicit timeout (i.e. when timeoutSeconds equals the default of 30).

# .fuseraft/config/orchestration.yaml snippet
ApiProfiles:
  snow:
    BaseUrl: "https://mycompany.service-now.com/api/now"
    TimeoutSeconds: 60
    DefaultHeaders:
      Authorization: "Bearer ${SNOW_API_TOKEN}"
      Accept: "application/json"

# Agent can now call:
http_get(url="/table/incident", profile="snow")
# → GET https://mycompany.service-now.com/api/now/table/incident
#   Authorization: Bearer <value of $SNOW_API_TOKEN>

Header values in DefaultHeaders support ${ENV_VAR} token expansion — the token is replaced with the environment variable's value at startup. See Configuration → ApiProfiles for the full reference.

Security note: When HttpAllowedHosts is non-empty, only listed hostnames are permitted. The allowlist is enforced after profile resolution — a profile that resolves to an unlisted host is still denied. Private and loopback addresses (127.x, 10.x, 172.16–31.x, 192.168.x, 169.254.x, IPv6 loopback/link-local) are always blocked regardless of the allowlist.

---

Json

Parse, transform, and query JSON data.

Function	Parameters	Description
json_format	json	Pretty-print a JSON string with indentation.
json_minify	json	Strip whitespace to produce compact output.
json_get	json, path	Get a nested value using dot-separated path notation, e.g. "data.results.0.title".
json_keys	json	Return top-level keys of an object, or the length of an array.
json_search	json, keyName	Find all keys matching a search term (case-insensitive, deep search).
json_merge	baseJson, patchJson	Shallow-merge two JSON objects. Patch fields overwrite base fields.
json_to_text	json, depth (default 0)	Convert JSON to a human-readable summary suitable for feeding into a model prompt.
json_validate	json	Check whether a string is well-formed JSON.

---

Search

Search the filesystem by name or content.

Function	Parameters	Description
search_files	pattern, directory (default "."), maxResults (default 100)	Find files by wildcard/glob pattern.
search_content	query, directory (default "."), filePattern (default "*"), maxResults (default 100), caseSensitive (default false)	Search file contents by regex or plain text (like grep).
search_symbol	symbol, directory (default "."), extension (default ""), maxResults (default 50)	Find symbol definitions (class, function, interface, variable, etc.) using language-agnostic patterns. Results are automatically recorded as SymbolDefinition nodes in the evidence graph when EvidenceStore is configured.
search_callers	symbol, directory (default "."), extension (default ""), maxResults (default 100)	Find call sites and usages of a symbol: invocations, constructor calls, type annotations, and inheritance declarations. Excludes definition lines so results contain only references. Results are automatically recorded as SymbolReference nodes in the evidence graph when EvidenceStore is configured; TargetFile is resolved from any existing SymbolDefinition nodes for the same symbol.

---

Probe

Structured hypothesis testing and assertion utilities. Useful for Tester agents that need to verify behavior with evidence.

Function	Parameters	Description
probe_code	language, code, directory (default "."), timeoutSeconds (default 30)	Execute a code snippet and return stdout/stderr/exit code. Supported languages: bash, python, javascript, go, csharp, powershell, kiwi.
probe_assert_output	command, expected, matchType (default "contains"), directory, timeoutSeconds	Run a command and assert its output. matchType: contains, equals, regex, exitcode. Returns PASS or FAIL with evidence.
probe_compare_outputs	commandA, commandB, directory, timeoutSeconds	Run two commands and return their outputs side-by-side for comparison.
probe_run_hypothesis	hypothesis, command, expectedObservation, setupCommand (optional), directory, timeoutSeconds	Given/When/Then structured test.

---

CodeExecution

Sandboxed code execution via Docker containers. Each run gets a fresh, isolated container with no network access and capped resources.

Requirements: Docker CLI and daemon must be running. Check with the check_docker function.

Function	Parameters	Description
code_execution_check_docker	—	Verify Docker is available and the daemon is reachable.
code_execution_sandbox_run	language, code, timeoutSeconds (default 30)	Run code in a fresh Docker container. Supported languages: python, node, bash, go, rust.
code_execution_repl_start	language	Start a REPL session (Python or Node). Returns a session ID.
code_execution_repl_exec	sessionId, code, timeoutSeconds	Execute code in an active REPL session. Variables and functions persist between calls.
code_execution_repl_reset	sessionId	Clear accumulated code in a REPL session (session stays open).
code_execution_repl_stop	sessionId	Remove the REPL session and all accumulated state.

Container resource limits: --network none, --memory 256m, --cpus 0.5

Docker images used:

Language	Image
Python	python:3.12-slim
Node	node:20-slim
Bash	bash:5.2
Go	golang:1.23-alpine
Rust	rust:1-slim

---

Scratchpad

Persistent per-agent key-value store that survives across sessions. Each agent that includes "Scratchpad" in its Plugins list gets an isolated JSON file at ~/.fuseraft/scratchpad/{AgentName}.json. A global scope (~/.fuseraft/scratchpad/global.json) is shared by all agents in the orchestration.

Files are stored outside the project directory so notes persist regardless of which project or config file is used.

Typical usage pattern:

At the start of a resumed session:  scratchpad_read_all()
When you make a key decision:       scratchpad_write("auth_decision", "Use JWT tokens", tags="auth")
When you want to find past notes:   scratchpad_search("auth")
Before ending the session:          scratchpad_write("session_summary", "Completed task X, left Y for next time")

Function	Parameters	Description
scratchpad_write	key, value, tags (optional), scope (default "agent")	Store or update an entry. Tags are comma-separated keywords.
scratchpad_read	key, scope (default "agent")	Retrieve a single entry by key.
scratchpad_read_all	scope (default "agent")	Read all entries — call this at session start to restore context.
scratchpad_search	query, scope (default "agent")	Case-insensitive substring search across keys, values, and tags.
scratchpad_delete	key, scope (default "agent")	Remove an entry.

Scope values:

Scope	File	Visibility
agent (default)	~/.fuseraft/scratchpad/{AgentName}.json	Private to this agent
global	~/.fuseraft/scratchpad/global.json	Shared by all agents

Note: Unlike other plugins, "Scratchpad" is not shared between agents — each agent gets its own instance backed by its own file. This is handled automatically; no extra configuration is needed.

---

Chatroom

Shared append-only message log for agent-to-agent coordination. All agents that include "Chatroom" in their Plugins list share the same JSONL file, but each agent sends under its own name.

Function	Parameters	Description
chatroom_send	recipient, message	Append a message to the log. recipient can be a specific agent name or "All" to broadcast.
chatroom_read	count (default 20)	Read the most recent count messages from the log.

Typical usage:

After completing a task:    chatroom_send("Tester", "Files are written and build passes.")
At the start of your turn:  chatroom_read()
Broadcasting a blocker:     chatroom_send("All", "Blocked on missing dependency — need shell access.")

Note: Like "Scratchpad", "Chatroom" is instantiated per-agent (so each instance knows the sender's name), but all instances write to the same file so messages are visible across the team.

---

Changes

Read-only view of the session change log written automatically by the orchestrator's ChangeTracker. Records which files were written, which commands ran, and which git commits were made — turn by turn — so downstream agents (Tester, Reviewer) know exactly what happened without having to infer it from the chat history.

Availability: Only registered when ChangeTracking is present in the orchestration config. See Configuration.

Function	Parameters	Description
changes_read	—	Return the full session change log: every agent turn that wrote files, ran commands, or made git commits.
changes_read_latest	count (default 1)	Return the count most-recent change entries. Use this before deciding what to test or review.

Typical usage:

Tester, before writing tests:   changes_read_latest()
Reviewer, at session start:     changes_read()

Each entry shows the agent name, turn index, timestamp, files written/deleted, commands run (with pass/fail status), and git commits.

---

Session

Gives REPL agents first-class access to their own session metadata, saved-session history, and diagnostic log files. Always available in the REPL when tools are enabled; not applicable to fuseraft run orchestrations.

Function	Parameters	Description
repl_session_current	—	Return the current session's ID, model, start time, working directory, snapshot path, and log file locations.
repl_session_list	—	List all saved REPL sessions newest-first. The active session is marked with ◄ current.
repl_session_read_event_log	targetSessionId (optional), maxLines (default 50)	Read entries from repl_events.jsonl filtered to a session. Defaults to the current session.
repl_session_read_log	logName (default "repl_events"), maxLines (default 100)	Read the tail of a named diagnostic log. Valid names: repl_events, events, provider_errors, app.

Session context in system prompt: The current session ID, start time, snapshot path, and event log path are injected into the system prompt automatically — the agent always knows its session without needing to call a tool first.

Typical usage:

# Find my session ID and log locations
repl_session_current()

# Compare this session with past ones
repl_session_list()

# Debug what happened in the last 20 events
repl_session_read_event_log(maxLines=20)

# Check for provider errors
repl_session_read_log(logName="provider_errors")

---

Compaction

Lets an agent request a history compaction flush on demand — the same path as the automatic turn-count and token-budget triggers, using whatever compaction mode is configured.

Availability: Only effective when Compaction is present in the orchestration config. Calling compact_conversation without a configured compactor is a no-op.

Plugins:
  - Compaction

# In agent instructions:
When your context is growing large and you need to free up space, call compact_conversation().

Function	Parameters	Description
compact_conversation	—	Compact conversation history using the configured compaction mode.

How it works: The tool returns immediately. The runner detects the call at the end of the turn and triggers ApplyCompactionAsync before the next stream starts — identical to the automatic threshold trigger.

---

Handoff

Provides a single handoff tool for deterministic, type-safe routing. Agents call handoff(route_keyword: "...") instead of emitting a keyword in free text. The tool-call argument is parsed by the model's function-calling infrastructure — far more reliable than expecting an exact string on its own line in an open-ended prose response.

When handoff is called, fuseraft terminates the agent's tool loop immediately so no further tools can be called in the same turn. This guarantees the handoff is always the last action the agent takes.

Plugins:
  - Handoff

# In agent instructions:
When your work is complete, call handoff(route_keyword: "HANDOFF TO TESTER").

Function	Parameters	Description
handoff	route_keyword	Signal completion and hand off to the next step. Provide the exact keyword defined in your instructions (e.g. "HANDOFF TO TESTER", "APPROVED"). Must be the last tool call in your response.

How it interacts with keyword routing: The keyword strategy checks for a handoff tool call first. If found, the route_keyword argument is used directly as the routing signal — text scanning is skipped entirely. Text-based keywords are still supported as a fallback for configs that do not include the Handoff plugin.

---

SubAgent

Exposes two lightweight sub-agent tools that keep the caller's context window clean. Instead of reading many files directly, the parent agent delegates work to a focused loop that returns only a distilled result.

Both tools share the same tool set, timeout (8 minutes), and cancellation behaviour — the parent agent's cancellation token is linked so interrupts propagate immediately. The sub-agent's current working directory is automatically injected into its system prompt so it never wastes a tool call discovering it.

Default tool set (read-only): read_file, list_files, grep_file, get_file_summary, get_file_info, search_files, search_content, search_symbol, shell_run, shell_get_env, shell_which, git_status, git_diff, git_log, git_show, git_branch_list, git_stash_list. The sub-agent is instructed never to implement, edit, delete, commit, or push anything.

Plugins:
  - SubAgent

Tool	Parameters	Description
sub_agent_explore	query, format	Multi-hop exploration. Returns a prose summary (≤600 words) or a bulleted file list depending on format. Up to 20 iterations by default.
sub_agent_locate	target	Single-target lookup. Finds where a symbol, type, method, interface, or file is defined. Returns path:line — description. Capped at 5 iterations and 512 output tokens — much cheaper than explore for targeted lookups.

format values for sub_agent_explore:

Value	Output
"prose" (default)	Narrative summary, ≤600 words
"file_list"	Markdown bullet list of relevant file paths, each with a one-line role description

Tool selection inside the sub-agent loop (enforced by system prompt):

search_symbol → search_files → search_content → get_file_summary → grep_file → read_file → shell_run

The model is instructed to prefer earlier options when they suffice, reserving read_file for when a summary is insufficient and shell_run only for verifying a specific hypothesis (build, test) — not for browsing.

Typical usage:

# Broad question — use explore
sub_agent_explore("Which files in src/Parsing/ handle string interpolation and how do they interact?")

# Need a list of paths — use file_list format
sub_agent_explore("What files does AgentFactory depend on?", format="file_list")

# Single target — use locate (5 iterations, much cheaper)
sub_agent_locate("IOrchestrationHook")
sub_agent_locate("AgentFactory.Create")
sub_agent_locate("EventEmitter.cs")

Sub-agent model override (SubAgentModel)

By default the sub-agent inherits the parent agent's model. Set SubAgentModel to run it on a cheaper model for cost control:

Agents:
  - Name: Developer
    Model: claude-opus-4-7
    Plugins:
      - FileSystem
      - Shell
      - SubAgent
    SubAgentModel: claude-haiku-4-5-20251001   # exploration on a cheaper model

Any model alias or provider model ID accepted by the Models config section can be used here.

Sub-agent iteration cap (SubAgentMaxToolCalls)

Controls the maximum number of tool-call iterations inside the sub_agent_explore loop. sub_agent_locate always uses a hard cap of 5.

Agents:
  - Name: Archaeologist
    Plugins:
      - SubAgent
    SubAgentMaxToolCalls: 30   # allow deeper exploration for this agent

0 (default) uses the built-in default of 20.

Custom sub-agent plugin list (SubAgentPlugins)

To give the sub-agent a different set of plugins from the default, list them under SubAgentPlugins. Capability filters from Capabilities apply to sub-agent plugins the same way they apply to the parent. Unknown plugin names raise an error at session startup (they are not silently ignored).

Agents:
  - Name: Developer
    Plugins:
      - FileSystem
      - Shell
      - SubAgent
    SubAgentPlugins:
      - FileSystem
      - Search
      - Git
    Capabilities:
      Git: [read]

Note: SubAgent is instantiated per-agent by AgentFactory. The stub registered in PluginRegistry is only used by fuseraft plugins for enumeration.

---

Document

Read rich document formats as plain text. All operations are read-only. Sandbox rules apply when FileSystemSandboxPath is configured.

Function	Parameters	Description
document_extract_text	path	Extract full plain text from a PDF, DOCX, PPTX, or XLSX file. Returns a format/size header followed by the extracted text.
document_get_info	path	Return format metadata (page/sheet count, file size, extracted character count) without returning the full text. Cheaper than extract_text for planning.
document_list_sheets	path	List sheet names in an Excel file (.xlsx only).
document_get_sheet	path, sheetName, maxRows (default 0 = all)	Extract one sheet from an Excel file as a pipe-delimited text table.

Supported formats: .pdf, .docx, .pptx, .xlsx

Context store integration: When you run fuseraft context add on a supported document, the text is automatically extracted and stored as a .txt file at import time. Agents can then access it via read_file without needing the Document plugin. Use Document when you need on-demand extraction inside a session (e.g. processing documents found during a task, or working with individual Excel sheets).

---

Skills

Exposes installed skills as callable tools in the REPL. Only present when at least one skill is found at startup — see Skills for how discovery works.

Unlike other plugins, Skills is not listed in an agent's Plugins config. It is registered automatically by the REPL based on what is installed on the filesystem.

Function	Parameters	Description
load_skill	name	Load the full SKILL.md body for a skill by slug. The model calls this when the catalog entry indicates the skill is relevant to the current task.
run_skill_script	skill, script, args (optional)	Run a script bundled with a skill. script is the filename inside the skill directory (e.g. transform.py). args is a space-separated argument string. Supported extensions: .sh, .py, .js.

---

MCP plugins

In addition to the built-in plugins above, tools from any connected MCP server are available as plugins. The plugin name is the Name field from McpServers config.

McpServers:
  - Name: MyTools
    Transport: stdio
    Command: npx
    Args:
      - "-y"
      - my-mcp-server
Agents:
  - Name: Developer
    Plugins:
      - FileSystem
      - Shell
      - MyTools

See MCP Integration for full detail.