ツールシステム

TinyElf のツールシステムは、ToolRegistry がツールの登録と実行を管理し、TinyElfToolRegistryBuilder がセッション開始時に完全なツールセットを構築する役割を担います。各ツールは ITool インターフェースを実装しています。

ツール登録フロー

graph TB
    Builder["TinyElfToolRegistryBuilder<br/>buildToolRegistry()"] --> Reg["ToolRegistry"]

    Builder -->|"1. FileSystem"| FS["createFileSystemTools()<br/>Read, Write, Edit, ListDir, Glob, Grep"]
    Builder -->|"2. Shell"| Shell["ShellTool<br/>Bash"]
    Builder -->|"3. Web Search"| WS["setupWebSearch()<br/>WebSearch / NativeSearch"]
    Builder -->|"4. Web Fetch"| WF["createWebFetchTool()<br/>WebFetch + summarizer"]
    Builder -->|"5. Skills"| SK["SkillsTool + ReadSkillTool<br/>list_skills, read_skill"]
    Builder -->|"6. SkillHub"| SH["SkillHubSearchTool + InstallTool<br/>skillhub_search, skillhub_install"]
    Builder -->|"7. Sub-Agent"| SA["SpawnTool<br/>spawn_agent"]
    Builder -->|"8. Sub-Agent Query"| SAQ["SubagentListTool + StatusTool"]
    Builder -->|"9. Slash Command"| CMD["SlashCommandTool<br/>slash_command"]
    Builder -->|"10. MCP"| MCP["loadMcpTools() + loadDirectMcpTools()<br/>mcp__*"]
    Builder -->|"11. Session"| SS["SessionsSpawn/List/Send/History"]
    Builder -->|"12. Control"| Ctrl["NotifyTool + SessionsYieldTool"]

    FS --> Reg
    Shell --> Reg
    WS --> Reg
    WF --> Reg
    SK --> Reg
    SH --> Reg
    SA --> Reg
    SAQ --> Reg
    CMD --> Reg
    MCP --> Reg
    SS --> Reg
    Ctrl --> Reg

ITool インターフェース

interface ITool {
  readonly name: string;            // ユニークなツール名（function_calling 用）
  readonly description: string;     // LLM が読めるツールの説明
  readonly parameters: JsonSchema;  // JSON Schema パラメータ定義
  execute(params: Record<string, unknown>): Promise<string>;
}

ToolRegistry

class ToolRegistry {
  register(tool: ITool): void;
  registerAll(tools: ITool[]): void;
  unregister(name: string): boolean;
  get(name: string): ITool | undefined;
  has(name: string): boolean;
  getAll(): ITool[];
  getNames(): string[];
  getDefinitions(): ToolDefinition[];    // OpenAI function_calling 形式
  createFiltered(allowedNames: string[]): ToolRegistry;
  execute(toolCallId, toolName, params): Promise<ToolCallResult>;
}

実行フロー

ツールを検索 → 見つからない場合はエラーを返す（利用可能なツール一覧を表示）
パラメータの型変換 → LLM の一般的な型エラーを処理（string → number など）
必須パラメータのバリデーション → 欠落している場合はエラーを返す
tool.execute(params) を呼び出す
出力の切り捨て → maxChars（デフォルト 50KB）を超えた場合に切り捨て、(truncated) マークを付加
エラー出力にヒントを追記 → [Analyze the error above and try a different approach.]

ツールのフィルタリング

createFiltered() は、ホワイトリストに含まれるツールのみを持つ新しい ToolRegistry インスタンスを作成します。主な用途：

plan モードで読み取り専用ツールのみに制限
Agent 設定の allowedTools フィールド
Slash command の allowed-tools メタデータ

ツール一覧

FileSystem ツール

ツール	クラス	感度	パラメータ	説明
`Read`	`ReadFileTool`	安全	`path`, `offset?`, `limit?`	ファイル内容を読み取る（部分読み取りに対応）
`Write`	`WriteFileTool`	要注意	`path`, `content`	ファイルを書き込む（作成または上書き）
`Edit`	`EditFileTool`	要注意	`path`, `old_string`, `new_string`, `replace_all?`	文字列の精密な置換
`ListDir`	`ListDirTool`	安全	`path`	ディレクトリの内容を一覧表示
`Glob`	`GlobTool`	安全	`pattern`, `path?`	ファイル名のパターンマッチング
`Grep`	`GrepTool`	安全	`pattern`, `path?`, `include?`	ファイル内容の検索

FileSystem ツールの特徴：

パスのサンドボックス：すべてのパスはワークスペースルートからの相対パスとして解決される
restrictToWorkspace 設定でワークスペース外へのアクセスを制御
Read は大きなファイル（128KB 超）を自動的に切り捨て、10MB 超は offset/limit が必要

Shell ツール

ツール	クラス	感度	パラメータ	説明
`Bash`	`ShellTool`	要注意	`command`	シェルコマンドを実行

Shell ツールのセキュリティ機能：

コマンドブラックリスト（重大な拒否パターン）：rm -rf /、format、mkfs、diskpart など
高リスクコマンドの警告：sudo、curl | sh、パーミッション変更
ワークスペース外パスの検出
出力制限：100KB
タイムアウト：デフォルト 2 分（execTimeout で変更可能）

Web ツール

ツール	クラス	感度	パラメータ	説明
`WebSearch`	`WebSearchServiceTool`	安全	`query`, `count?`	Web 検索
`WebFetch`	`WebFetchTool`	安全	`url`, `prompt?`, `raw?`	Web コンテンツの取得

WebFetch の特徴：

Readability を使用して記事本文を抽出
HTML → Markdown 変換（Turndown）
4KB 超のコンテンツはバックグラウンドモデルで自動要約
タイムアウト 30 秒、最大レスポンス 5MB

Web 検索の 3 段階フォールバック：

ネイティブ検索（Anthropic / OpenAI / Gemini / xAI 組み込み）
WebSearchService（Tavily / Jina / Searxng）
利用不可

サブエージェントツール

ツール	クラス	感度	パラメータ	説明
`spawn_agent`	`SpawnTool`	要注意	`prompt`, `agent?`, `model?`, `background?`, `maxIterations?`, `permissionMode?`, `tools?`	サブエージェントを起動
`subagent_list`	`SubagentListTool`	安全	なし	アクティブなサブエージェントを一覧表示
`subagent_status`	`SubagentStatusTool`	安全	`runId`	サブエージェントの状態を照会

セッションツール

ツール	クラス	感度	パラメータ	説明
`SessionsSpawn`	`SessionsSpawnTool`	要注意	`prompt`, `agentId?`, `title?`	新しいセッションを作成
`SessionsList`	`SessionsListTool`	安全	`limit?`, `offset?`	セッション一覧を表示
`SessionsSend`	`SessionsSendTool`	要注意	`sessionId`, `message`	セッションにメッセージを送信
`SessionsHistory`	`SessionsHistoryTool`	安全	`sessionId`, `limit?`	セッション履歴を表示
`SessionsYield`	`SessionsYieldTool`	安全	`message`	Agent ループを終了してメッセージを返す

Skills ツール

ツール	クラス	感度	パラメータ	説明
`list_skills`	`SkillsTool`	安全	なし	利用可能なすべての Skill を一覧表示
`read_skill`	`ReadSkillTool`	安全	`name`	Skill の内容を読み取る
`skillhub_search`	`SkillHubSearchTool`	安全	`query`	コミュニティ Skill を検索
`skillhub_install`	`SkillHubInstallTool`	安全	`skillId`	コミュニティ Skill をインストール

MCP ツール

ツール	クラス	感度	パラメータ	説明
`mcp__<server>__<tool>`	動的生成	要注意	MCP サーバーが定義	外部 MCP ツール

MCP ツールは 3 つのアプローチで読み込まれます：

ユーザー MCP（mcpServerIds）— 設定 → MCP で設定した stdio/http/sse サーバーに McpService 経由で接続
組み込み MCP（McpProviderRegistry で自動組み立て）— すべての組み込み MCP ハンドラーをプロセス内で動作させ、createSdkMcpServer で SDK ラップし、TinyElf が ITool として登録。CLI は中央の BuiltinMcpHttpServer HTTP ブリッジ経由でアクセス。各 Agent から見える MCP は Provider の isEligible(ctx) によって決定（Agent 設定の builtinMcpServers フィールドは cleanup-legacy-mcp（2026-05-19）で削除済み）
ダイレクト MCP（directMcpServers）— Agent 設定で宣言された stdio MCP（ローカル Python ツールを呼び出すようなユーザーシナリオ向け）

制御ツール

ツール	クラス	感度	パラメータ	説明
`Notify`	`NotifyTool`	安全	`title`, `body?`	デスクトップ通知を送信
`slash_command`	`SlashCommandTool`	安全	`command`, `args?`	Slash コマンドを実行

ツールの感度分類

private static readonly SAFE_TOOLS = new Set([
  'Read', 'ListDir', 'Glob', 'Grep',
  'WebSearch', 'WebFetch',
  'list_skills', 'read_skill',
  'Notify', 'SessionsYield', 'SessionsHistory',
]);

分類ルール：

SAFE_TOOLS セットに含まれる → 確認を求めない
acceptEdits モードでは、Write と Edit も確認を求めない
その他すべてのツール（MCP ツールを含む）→ 確認が必要

ツールの継承

サブエージェントは親 Agent から一部のツールを継承できます：

const inheritableToolNames = new Set([
  'list_skills', 'read_skill', 'slash_command'
]);
// + mcp__ で始まるすべての MCP ツール

主要ファイル

ファイル	パス	説明
ITool インターフェース	`tinyelf/tools/ToolInterface.ts`	ツールの基底インターフェース
ToolRegistry	`tinyelf/tools/ToolRegistry.ts`	ツールレジストリ
ToolRegistryBuilder	`tinyelf/TinyElfToolRegistryBuilder.ts`	ツールビルダー
FileSystemTools	`tinyelf/tools/FileSystemTools.ts`	FileSystem ツール群
ShellTool	`tinyelf/tools/ShellTool.ts`	Shell ツール
WebTools	`tinyelf/tools/WebTools.ts`	WebFetch
WebSearchServiceTool	`tinyelf/tools/WebSearchServiceTool.ts`	WebSearch
SpawnTool	`tinyelf/tools/SpawnTool.ts`	サブエージェントツール
SessionTools	`tinyelf/tools/SessionTools.ts`	セッション管理ツール群
SkillsTool	`tinyelf/tools/SkillsTool.ts`	Skills ツール
SkillHubTools	`tinyelf/tools/SkillHubTools.ts`	SkillHub ツール群
McpToolAdapter	`tinyelf/tools/McpToolAdapter.ts`	MCP ツールアダプター
NotifyTool	`tinyelf/tools/NotifyTool.ts`	通知ツール
YieldTool	`tinyelf/tools/YieldTool.ts`	ループ終了ツール
SubagentTools	`tinyelf/tools/SubagentTools.ts`	サブエージェント照会ツール群
SlashCommandTool	`tinyelf/tools/SlashCommandTool.ts`	Slash コマンド

すべてのパスは packages/desktop/app/main/services/agent-core/engine/ からの相対パスです。

拡張ポイント

新しいツールの追加：ITool インターフェースを実装 → TinyElfToolRegistryBuilder に登録
感度の変更：TinyElfAgentLoop.SAFE_TOOLS セットに追加または削除
カスタムツールの継承：inheritableToolNames セットを変更
MCP ツールの読み込み：McpToolAdapter で新しい MCP トランスポートに対応

モジュール	パス	関係
TinyElfAgentLoop	`tinyelf/TinyElfAgentLoop.ts`	ツール実行の呼び出し元
ExecutionFirewall	`platform/security/ExecutionFirewall.ts`	FileSystem ツールのパスチェック
McpService	`capabilities/tools/mcp-users/McpService.ts`	MCP ツールのソース
SkillsLoader	`tinyelf/skills/SkillsLoader.ts`	Skills ツールの依存
SubagentManager	`tinyelf/tools/SpawnTool.ts`	spawn_agent の依存

ツール登録フロー​

ITool インターフェース​

ToolRegistry​

実行フロー​

ツールのフィルタリング​

ツール一覧​

FileSystem ツール​

Shell ツール​

Web ツール​

サブエージェントツール​

セッションツール​

Skills ツール​

MCP ツール​

制御ツール​

ツールの感度分類​

ツールの継承​

主要ファイル​

拡張ポイント​

関連モジュール​