fusion/packages/cli/skill/fusion/references/engine-tools.md

Engine Session-Scoped Tools

These tools are not part of the user-invokable extension surface. They are injected by the engine at runtime for specific agent session types.

• Source files: packages/engine/src/agent-tools.ts, triage.ts, executor.ts, merger.ts, agent-heartbeat.ts
• Availability: only when the engine creates a session for the matching agent role
• Runtime contract: engine sessions now forward requested skill names (skillSelection.requestedSkillNames) into the generic runtime skills field so non-pi runtimes can still receive Fusion skill intent.
• Important: do not tell users to call these directly from the generic extension tool list

Shared runtime tools (agent-tools.ts)

Tool	Agent Types	Purpose	Parameters
fn_task_create	triage, executor, heartbeat	Create a follow-up task from within an agent run	description (string), dependencies? (string[]), priority? (low | normal | high | urgent)
fn_task_log	executor, heartbeat	Write significant task log entries	message (string), outcome? (string)
fn_task_document_write	triage, executor, heartbeat	Save/update a named task document revision	key (string), content (string), author? (string)
fn_task_document_read	triage, executor, heartbeat	Read one task document or list all	key? (string)
fn_memory_search	triage, executor, heartbeat	Search project memory plus per-agent layered memory snippets	query (string), limit? (number)
fn_memory_get	triage, executor, heartbeat	Read a bounded memory file window (including bounded per-agent layered paths)	path (string), startLine? (number), lineCount? (number)
fn_memory_append	executor, heartbeat (when writable backend enabled)	Append memory notes with explicit scope: scope="agent" for private operating context, scope="project" for workspace-wide durable knowledge	scope? (project | agent), layer (long-term | daily), content (string)
fn_web_fetch	executor, step-session, reviewer, merger, triage, heartbeat	Lightweight HTTP fetch with HTML→text extraction, timeout/size caps, and SSRF guard (no JS rendering)	url (string), prompt? (string), timeoutMs? (number), maxBytes? (number)
fn_research_run	triage, executor	Start a bounded research run (optionally wait for completion) and return structured findings metadata	query (string), wait_for_completion? (boolean), max_wait_ms? (number)
fn_research_list	triage, executor	List recent research runs with status/summary metadata	status? (pending | running | completed | failed | cancelled), limit? (number)
fn_research_get	triage, executor	Read one research run's structured findings/citations payload	id (string)
fn_research_cancel	triage, executor	Cancel an active research run via orchestrator cancellation path	id (string)
fn_read_evaluations	heartbeat	Read the current agent's rating summaries, recent comments, and reflections	none
fn_update_identity	heartbeat	Update the current agent's own soul, instructionsText, or memory fields	soul? (string), instructionsText? (string), memory? (string)
fn_reflect_on_performance	executor, heartbeat (when reflection service enabled)	Generate reflection insights from prior runs	focus_area? (string)
fn_list_agents	triage, executor, heartbeat	List agents (optionally filtered)	role? (string), state? (string), includeEphemeral? (boolean)
fn_delegate_task	triage, executor, heartbeat	Create and assign a new task to a specific agent	agent_id (string), description (string), dependencies? (string[]), override? (boolean)
fn_get_agent_config	executor, heartbeat	Read full config for a direct-report agent	agent_id (string)
fn_update_agent_config	executor, heartbeat	Update config fields for a direct-report, non-ephemeral agent	agent_id (string), optional: soul, instructions_text, instructions_path, heartbeat_procedure_path, heartbeat_interval_ms, heartbeat_timeout_ms, max_concurrent_runs, message_response_mode
fn_agent_create	executor, heartbeat	Create a non-ephemeral direct-report agent	name (string), role (string), optional: soul, instructions_text, instructions_path, reportsTo, heartbeat_interval_ms, heartbeat_timeout_ms, max_concurrent_runs, message_response_mode
fn_agent_delete	executor, heartbeat	Delete a non-ephemeral direct-report agent	agent_id (string), optional: force (boolean), reassign_to (string)
fn_send_message	executor, step-session, heartbeat	Send inbox messages to agents/users	to_id (string), content (string), type? (agent-to-agent | agent-to-user), reply_to_message_id? (string)
fn_read_messages	executor, step-session, heartbeat	Read inbox messages	unread_only? (boolean), limit? (number)
fn_post_room_message	heartbeat	Post a message to a chat room the agent is a member of	roomId (string), content (string), replyToMessageId? (string), mentions? (string[])

Triage-only runtime tools (triage.ts)

Tool	Purpose	Parameters
fn_task_list	List active tasks during specification (duplicate check, discovery)	none
fn_task_search	Keyword search tasks (including done/archived by default) for duplicate detection	query (string), limit? (number), includeDone? (boolean), includeArchived? (boolean)
fn_task_get	Fetch full task detail including PROMPT.md	id (string)
fn_review_spec	Spawn spec reviewer and return APPROVE/REVISE/RETHINK/UNAVAILABLE	none

Executor-only runtime tools (executor.ts)

Note: step-session execution (step-session-executor.ts) reuses executor coordination tools (fn_send_message, fn_read_messages, fn_list_agents, fn_delegate_task, task-document tools, and memory tools) so spawned/session-sliced execution keeps parity with main executor runs.

Tool	Purpose	Parameters
fn_task_update	Update a spec step status (pending/in-progress/done/skipped)	step (number), status (enum)
fn_task_add_dep	Add a dependency to current task (confirmation-gated)	task_id (string), confirm? (boolean)
fn_task_done	Mark task complete and optionally store summary	summary? (string)
fn_review_step	Spawn step plan/code reviewer	step (number), type (plan | code), step_name (string), baseline? (string)
fn_spawn_agent	Spawn child agent in separate worktree	name (string), role (enum), task (string)

Merger-only runtime tools (merger.ts)

Tool	Purpose	Parameters
fn_report_build_failure	Explicitly signal merge-time build verification failure	message (string)

Heartbeat-only runtime tools (agent-heartbeat.ts)

Tool	Purpose	Parameters
fn_heartbeat_done	Signal end of heartbeat run with optional summary	summary? (string)