# Fusion Extension Tools

All tools are registered via the Fusion extension. They are available in any agent session when Fusion is configured.

> Naming contract: all externally exposed Fusion extension tools are `fn_*` (for example `fn_task_create`). Engine runtime sessions also inject additional `fn_*` tools (for example `fn_review_step`, `fn_spawn_agent`, `fn_task_document_write`) that are separate from this extension surface and documented in `engine-tools.md`.

<!-- BEGIN: extension-tools (auto-generated by scripts/sync-fusion-skill-tools.mjs — do not edit by hand) -->

## Task Tools

### fn_task_create

Create a new task on the Fusion task board. The task enters the planning column where the AI planning agent will plan it into a full prompt with steps, file scope, and acceptance criteria.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `description` | string | ✓ | What needs to be done — be descriptive |
| `depends` | array | — | Task IDs this depends on (e.g. ['FN-001', 'FN-002']) |
| `agentId` | string | — | Agent ID to assign this task to (e.g. 'agent-abc123') |
| `priority` | string(enum) | — | Task priority (low, normal, high, urgent) |

### fn_task_update

Update fields on an existing task. Supports modifying the title, description, dependencies, assigned agent, and priority after task creation.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | ✓ | Task ID (e.g. FN-001) |
| `title` | string | — | New task title |
| `description` | string | — | New task description |
| `depends` | array | — | New dependency list — replaces existing dependencies (e.g. ['FN-001', 'FN-002']) |
| `agentId` | union | — | Agent ID to assign this task to, or null to clear (e.g. 'agent-abc123') |
| `nodeId` | union | — | Node ID override for this task, or null to clear |
| `priority` | string(enum) | — | Task priority (low, normal, high, urgent) |

### fn_task_list

List all tasks on the Fusion board, grouped by column.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `column` | string(enum) | — | Filter to a specific column |
| `limit` | number | — | Max tasks to show per column (default: 10) |

### fn_task_show

Show full details for a task including steps, progress, and log entries.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | ✓ | Task ID (e.g. FN-001) |

### fn_task_attach

Attach a file to a task. Supports images (png, jpg, gif, webp) and text files (txt, log, json, yaml, yml, toml, csv, xml).

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | ✓ | Task ID (e.g. FN-001) |
| `path` | string | ✓ | Path to the file to attach |

### fn_task_pause

Pause a task — stops all automated agent and scheduler interaction for this task.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | ✓ | Task ID (e.g. FN-001) |

### fn_task_unpause

Unpause a task — resumes automated agent and scheduler interaction.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | ✓ | Task ID (e.g. FN-001) |

### fn_task_retry

Retry a failed task — clears the error state. Non-review failures move to todo; in-review execution failures move to todo preserving progress; in-review merge failures stay in-place for auto-merge retry.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | ✓ | Task ID to retry (e.g. FN-001). Must be in 'failed' state. |

### fn_task_duplicate

Duplicate an existing task, creating a fresh copy in planning. Copies the title and description but resets all execution state. The AI planning agent will replan the new task.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | ✓ | Source task ID to duplicate (e.g. FN-001) |

### fn_task_refine

Request a refinement of a completed or in-review task. Creates a new follow-up task in planning that references the original task as a dependency. Use this when a done or in-review task needs additional work, improvements, or follow-up changes.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | ✓ | Task ID to refine (e.g. FN-001). Must be in 'done' or 'in-review' column. |
| `feedback` | string | ✓ | Description of what needs to be refined or improved |

### fn_task_archive

Archive a done task (move from done → archived). Archived tasks are preserved for historical reference but moved out of the main board view.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | ✓ | Task ID to archive (e.g. FN-001). Must be in 'done' column. |

### fn_task_unarchive

Unarchive an archived task (move from archived → done). Restores the task to the done column.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | ✓ | Task ID to unarchive (e.g. FN-001). Must be in 'archived' column. |

### fn_task_delete

Soft-delete a task from active Fusion board views. The task row and artifacts are preserved; optional allowResurrection marks the ID for intentional recreation.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | ✓ | Task ID to delete (e.g. FN-001) |
| `allowResurrection` | boolean | — | When true, mark this tombstone as explicitly reusable for future recreation. |

### fn_task_plan

Create a task via AI-guided planning mode — interactive conversation to refine your idea into a well-specified task.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `description` | string | — | Initial plan description (optional) — the AI will ask clarifying questions if not provided |
| `baseBranch` | string | — | Optional base branch for the task created from this planning session |

## GitHub Tools

### fn_task_import_github

Import GitHub issues as Fusion tasks. Fetches open issues from a repository and creates tasks in the planning column. Each task includes the issue title and body with a link to the source issue.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `ownerRepo` | string | ✓ | Repository in owner/repo format (e.g., 'dustinbyrne/fusion') |
| `limit` | number | — | Max issues to import (default: 30, max: 100) |
| `labels` | array | — | Label names to filter by |

### fn_task_import_github_issue

Import a specific GitHub issue as a Fusion task. Fetches the issue by number and creates a single task in the planning column with the issue title and body.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `owner` | string | ✓ | Repository owner (e.g., 'dustinbyrne') |
| `repo` | string | ✓ | Repository name (e.g., 'fusion') |
| `issueNumber` | number | ✓ | GitHub issue number to import |

### fn_task_browse_github_issues

List open GitHub issues from a repository to browse before importing. Returns issue numbers, titles, and URLs for selection. Use with fn_task_import_github_issue to import specific issues by number.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `owner` | string | ✓ | Repository owner (e.g., 'dustinbyrne') |
| `repo` | string | ✓ | Repository name (e.g., 'fusion') |
| `limit` | number | — | Max issues to show (default: 30, max: 100) |
| `labels` | array | — | Label names to filter by |

## Mission Tools

### fn_mission_create

Create a new mission — a high-level objective that can span multiple milestones. Missions contain milestones that break down work into phases.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `title` | string | ✓ | Mission title — brief but descriptive |
| `description` | string | — | Detailed mission objectives and context |
| `autoAdvance` | boolean | — | Automatically activate the next pending slice when the current slice completes |
| `baseBranch` | string | — | Optional integration base branch for tasks triaged from this mission |

### fn_mission_list

List all missions with their current status.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `includeDrafts` | boolean | — | Include in-flight mission interview drafts (default: true) |

### fn_mission_show

Show mission details with full hierarchy: milestones → slices → features.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | ✓ | Mission ID (e.g., M-001) |

### fn_mission_delete

Delete a mission and all its milestones, slices, and features. Cannot be undone.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | ✓ | Mission ID to delete (e.g., M-001) |

### fn_milestone_add

Add a milestone to a mission. Milestones represent phases of work.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `missionId` | string | ✓ | Parent mission ID (e.g., M-001) |
| `title` | string | ✓ | Milestone title |
| `description` | string | — | Milestone description |

### fn_slice_add

Add a slice to a milestone. Slices are work units that can be activated for implementation.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `milestoneId` | string | ✓ | Parent milestone ID (e.g., MS-001) |
| `title` | string | ✓ | Slice title |
| `description` | string | — | Slice description |

### fn_feature_add

Add a feature to a slice. Features are deliverables that can be linked to tasks.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `sliceId` | string | ✓ | Parent slice ID (e.g., SL-001) |
| `title` | string | ✓ | Feature title |
| `description` | string | — | Feature description |
| `acceptanceCriteria` | string | — | Acceptance criteria for completing the feature |

### fn_slice_activate

Activate a pending slice for implementation. Sets status to 'active' and enables task linking for its features.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | ✓ | Slice ID to activate (e.g., SL-001) |

### fn_feature_link_task

Link a feature to a fn task for implementation. Updates the feature status to 'triaged' and associates it with the task.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `featureId` | string | ✓ | Feature ID to link (e.g., F-001) |
| `taskId` | string | ✓ | Task ID to link to (e.g., FN-001) |

### fn_feature_update

Update an existing feature's title, description, or acceptance criteria. Partial patches leave untouched fields intact.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | ✓ | Feature ID to update (e.g., F-001) |
| `title` | string | — | Updated feature title |
| `description` | string | — | Updated feature description |
| `acceptanceCriteria` | string | — | Updated acceptance criteria for completing the feature |

### fn_milestone_update

Update an existing milestone's title, description, or acceptance criteria (the structured pass/fail bar, distinct from verification's free-form how-to-confirm notes). Partial patches leave untouched fields intact.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | ✓ | Milestone ID to update (e.g., MS-001) |
| `title` | string | — | Updated milestone title |
| `description` | string | — | Updated milestone description |
| `acceptanceCriteria` | string | — | Updated acceptance criteria for completing the milestone |

## Goal Tools

### fn_goal_list

List goals by status with active-goal warning details.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `status` | union | — | Filter by goal status (default: active) |

### fn_goal_create

Create a new project goal.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `title` | string | ✓ | Goal title — brief but descriptive |
| `description` | string | — | Long-form goal description (free-text markdown) |

### fn_goal_archive

Archive a goal by ID.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | ✓ | Goal ID (G-…) to archive |

### fn_goal_show

Show full details for a single goal by ID.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | ✓ | Goal ID (G-…) |

## Agent Tools

### fn_agent_stop

Stop a running agent — pauses its execution. Transitions the agent from running/active to paused state.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | ✓ | Agent ID to stop (e.g., agent-abc123) |

### fn_agent_start

Start a stopped agent — resumes its execution. Transitions the agent from paused to active state.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | ✓ | Agent ID to start (e.g., agent-abc123) |

### fn_agent_create

Create a new non-ephemeral agent.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | ✓ | Agent name |
| `role` | union | ✓ | Agent role/capability |
| `soul` | string | — | Agent personality/identity text |
| `instructions_text` | string | — | Inline custom instructions |
| `instructions_path` | string | — | Path to instructions markdown |
| `reportsTo` | string | — | Manager agent ID |
| `heartbeat_interval_ms` | number | — |  |
| `heartbeat_timeout_ms` | number | — |  |
| `max_concurrent_runs` | number | — |  |
| `message_response_mode` | union | — |  |

### fn_agent_delete

Delete a non-ephemeral agent.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `agent_id` | string | ✓ | Agent ID to delete |
| `force` | boolean | — | Force delete when holding checkout |
| `reassign_to` | string | — | Optional replacement agent for assigned tasks |

### fn_list_agents

List all available agents in the system. Shows each agent's name, role, state, personality (soul), and current assignment. Use this to discover which agents exist and what they specialize in before delegating work.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `role` | string | — | Filter by agent role/capability (e.g., 'executor', 'reviewer', 'qa') |
| `state` | string | — | Filter by agent state (e.g., 'idle', 'active', 'running') |
| `includeEphemeral` | boolean | — | Include ephemeral/runtime agents (default: false) |

### fn_delegate_task

Create a new task and assign it to a specific agent for execution. The task goes to 'todo' and will be picked up by the target agent on their next heartbeat cycle. Use fn_list_agents first to find available agents and their capabilities.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `agent_id` | string | ✓ | The agent ID to delegate work to |
| `description` | string | ✓ | What needs to be done |
| `dependencies` | array | — | Task IDs this new task depends on (e.g. [\"KB-001\"] |
| `override` | boolean | — | Set true to bypass executor-role assignment policy |

### fn_agent_show

Show detailed information about a single agent, including their role, state, position in the org hierarchy (reports-to, direct reports), skills, and current assignment.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | ✓ | Agent ID or resolvable name |

### fn_agent_org_chart

Show the organizational tree of agents, displaying the role hierarchy. Optionally filter to a subtree rooted at a specific agent.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `root_agent_id` | string | — | If provided, show only the subtree rooted at this agent |
| `include_ephemeral` | boolean | — | Include ephemeral/runtime agents (default: false) |

## Skills Tools

### fn_skills_search

Search the skills.sh directory for agent skills. Returns matching skills with names, sources (owner/repo), install counts, and install commands. Use fn_skills_install to install a selected skill.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | ✓ | Search query — framework name, technology, or capability (e.g., 'react', 'firebase', 'testing', 'docker') |
| `limit` | number | — | Max results to return (default: 10, max: 50) |

### fn_skills_install

Install an agent skill from skills.sh into the current project. Downloads skill files into the project's skill directories (.fusion/skills/, legacy .pi/skills/, .agents/skills/). The skill becomes available to AI agents in subsequent sessions.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `source` | string | ✓ | GitHub source in owner/repo format (e.g., 'firebase/agent-skills') |
| `skill` | string | — | Specific skill name to install (e.g., 'firebase-basics'). Omit to install all skills from the source. |

## Insight Tools

### fn_insight_list

List persisted project insights with optional category/status filters.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `category` | string(enum) | — | Filter by insight category |
| `status` | string(enum) | — | Filter by insight status |
| `runId` | string | — | Filter to insights linked to a specific run ID |
| `limit` | number | — | Max insights to return |
| `offset` | number | — | Number of rows to skip |

### fn_insight_show

Show a single persisted insight by ID.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | ✓ | Insight ID (e.g. INS-XXXXX) |

### fn_insight_run_list

List recent insight-generation runs with optional status/trigger filters.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `status` | string(enum) | — | Filter by run status |
| `trigger` | string(enum) | — | Filter by run trigger |
| `limit` | number | — | Max runs to return |
| `offset` | number | — | Number of runs to skip |

### fn_insight_run_show

Show a single insight-generation run by ID.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | ✓ | Insight run ID (e.g. INSR-XXXXX) |

## Other Tools

### fn_web_fetch

Lightweight URL fetch (no JS rendering). Use agent-browser skill for JS-heavy pages. URL to fetch (http/https) Optional extraction hint for downstream summarization Timeout in milliseconds (default: 30000) Max bytes to return (default: 512000)

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `url` | string | ✓ | URL to fetch (http/https) |
| `prompt` | string | — | Optional extraction hint for downstream summarization |
| `timeoutMs` | number | — | Timeout in milliseconds (default: 30000) |
| `maxBytes` | number | — | Max bytes to return (default: 512000) |

### fn_secret_get

Read a secret by key using per-secret access policy.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `key` | string | ✓ | Secret key |
| `scope` | union | — | Optional scope |

### fn_research_run

Cited-research pipeline: create a bounded search/fetch/synthesis run (not an autonomous experiment loop) and optionally wait for completion.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | ✓ | Research query or question |
| `wait_for_completion` | boolean | — | Wait for the run to complete before returning (default: false) |
| `max_wait_ms` | number | — | Max wait time when wait_for_completion=true (default: 90000, capped by settings) |

### fn_research_list

Cited-research pipeline: list recent search/fetch/synthesis runs (not experiment-loop sessions).

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `status` | string(enum) | — | Filter by run status |
| `limit` | number | — | Max runs to return (default: 10) |

### fn_research_get

Cited-research pipeline: get one run with structured findings and citations (not experiment-loop state).

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | ✓ | Research run ID |

### fn_research_cancel

Cited-research pipeline: cancel an in-flight run; terminal runs return INVALID_TRANSITION (does not control experiment loops).

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | ✓ | Research run ID |

### fn_research_retry

Cited-research pipeline: retry a failed run when lifecycle marks it retryable (not an autonomous experiment loop retry).

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | ✓ | Research run ID |

### fn_experiment_finalize

Group kept experiment runs into reviewable branches and finalize the session. Use dryRun=true to preview the plan without touching git.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `sessionId` | string | ✓ | Experiment session ID |
| `integrationBranch` | string | — | Integration branch to compute merge-base against (default: main) |
| `dryRun` | boolean | — | Preview plan only; do not create branches |
| `planOverride` | unknown | — | Optional plan override payload |
| `summary` | string | — | Optional finalize summary |

<!-- END: extension-tools -->

## Goal retrieval contract notes

### Goal-show response contract

- **Success:** returns `details.goal` as the complete goal JSON object (`id`, `title`, optional `description`, `status`, `createdAt`, `updatedAt`) and `content[0].text` with those same human-readable fields.
- **Not found:** returns `isError: true` with `details.code: "GOAL_NOT_FOUND"` and `details.goalId` set to the requested id.

## Dashboard Command

### /fn

Start or stop the Fusion dashboard from within an agent session.

| Command | Description |
|---------|-------------|
| `/fn` | Start dashboard on port 4040 |
| `/fn 8080` | Start on custom port |
| `/fn stop` | Stop dashboard |
| `/fn status` | Check if running |
