Tool Subsystem Overview

The Tool Subsystem is the core execution engine of the plugsuits agent, providing the interface between the LLM and the local environment. It implements a suite of callable tools for file exploration, deterministic modification, shell execution, and task planning. The system is designed to favor dedicated, safe tools for file operations over generic shell commands to ensure deterministic behavior and stale-safety through a hashline-aware engine.

Sources: packages/cea/src/tools/AGENTS.md:7-10, README.md:15-20

Subsystem Architecture

The subsystem is organized into functional categories, each residing in a dedicated directory within packages/cea/src/tools/. A central registry serves as the single source of truth for all exported tool keys.

Directory Structure

• explore/: Tools for reading and searching files (e.g., read_file, glob_files, grep_files).
• modify/: Tools for mutating the filesystem (e.g., edit_file, write_file, delete_file).
• execute/: Tools for system-level operations (e.g., shell_execute, shell_interact).
• planning/: Tools for state management and workflow orchestration (e.g., load_skill, todo_write).

Sources: packages/cea/src/tools/AGENTS.md:12-20, packages/cea/src/AGENTS.md:10-20

Tool Execution Flow

The following diagram illustrates the lifecycle of a tool call within the subsystem, from the agent's intent to the rendered result.

The registry maps stable public tool keys to concrete executors, ensuring model-tool contracts remain consistent even if underlying implementations change.
Sources: packages/cea/src/tools/AGENTS.md:22-30, packages/cea/src/interaction/tool-renderers.ts:1010-1022

Core Tool Categories

1. Exploration Tools

Exploration tools are the primary means for the agent to gather context. The system strictly enforces a "read before write" principle.

Sources: packages/cea/src/context/system-prompt.ts:36-40, packages/cea/src/interaction/tool-renderers.ts:390-410

2. Modification Tools

Modification tools implement surgical, deterministic file updates. A "hashline-first" approach is used, where edits are anchored to specific lines verified by a unique hash (LINE#HASH) to prevent applying changes to stale file versions.

3. Execution and Planning

Execution tools are reserved for operations that truly require a shell, such as builds, tests, or Git workflows. Planning tools allow the agent to manage its own state across multiple turns.

• shell_execute: Handles timeouts, background processes, and non-interactive wrapping.
• todo_write: Persists task status (pending, in_progress, completed, cancelled) to session-specific JSON and Markdown files.
• load_skill: Resolves local or bundled skill content to extend agent capabilities.

Sources: packages/cea/src/tools/AGENTS.md:24-28, packages/cea/src/tools/planning/todo-write.ts:133-145

Operational Guidelines and Anti-Patterns

The subsystem enforces specific principles to ensure agent efficiency and safety.

Principles of Interaction

1. Parallel Execution: Independent tools (like reading multiple files) should be called in a single response for efficiency gains.
2. Sequential Execution: Dependent operations (write then test) must be ordered correctly.
3. Path Integrity: Agents must preserve the path format provided in tasks (absolute vs relative).

Sources: packages/cea/src/context/system-prompt.ts:46-75

Anti-Patterns to Avoid

• Generic Shell Usage: Using cat, sed, grep, or find via shell_execute when dedicated tools exist.
• Blind Edits: Modifying files without prior inspection via exploration tools.
• Bypassing Safety: Ignoring expected_file_hash during edit flows.

Sources: packages/cea/src/tools/AGENTS.md:37-45, packages/cea/src/tools/modify/AGENTS.md:28-32

Tool Output Rendering

Every tool has a corresponding renderer in the interaction/ module that converts raw tool results into human-readable views for the TUI or structured JSONL for headless mode.

// Example: Mapping executors to renderers
export const createToolRenderers = (): ToolRendererMap => ({
  read_file: renderReadFile,
  glob_files: renderGlob,
  grep_files: renderGrep,
  shell_execute: renderShellExecute,
  write_file: renderWriteFile,
  edit_file: renderEditFile,
  todo_write: renderTodoWrite,
});

Sources: packages/cea/src/interaction/tool-renderers.ts:1010-1022

The Tool Subsystem provides a robust, safety-oriented framework that allows the agent to interact with complex codebases while minimizing the risk of non-deterministic errors or environment corruption.