Understanding Pi-Web Tool Presets: NONE, DEFAULT, and FULL Explained

Pi-web tool presets are predefined tool configurations (NONE, DEFAULT, and FULL) that control which built-in tools are available to agents during a session.

The agegr/pi-web repository implements a strict tool preset system to manage agent capabilities. These pi-web tool presets define which filesystem and shell tools are automatically enabled when creating new sessions or loading existing ones. The system ensures agents operate with only the necessary permissions by enforcing these configurations on both the client and server sides.

What Are Pi-Web Tool Presets?

The Three Preset Constants

The preset definitions are exported as constant arrays in lib/tool-presets.ts at lines 9-11. Each constant represents a specific capability level:

• PRESET_NONE: An empty array ([]) providing no tool access.
• PRESET_DEFAULT: Contains read, bash, edit, and write for basic file and shell operations.
• PRESET_FULL: Includes all default tools plus grep, find, and ls for advanced filesystem searching and listing.

The preset system uses two primary helper functions also defined in lib/tool-presets.ts. The getToolNamesForPreset function (lines 30-34) returns the tool array for a given preset name, while getPresetFromTools (lines 15-27) performs the reverse lookup to classify an active tool list into one of the three categories.

How Pi-Web Tool Presets Are Applied

Session Creation with Tool Names

When a user initiates a new chat session, the application converts the selected preset into a concrete list of tool names. In hooks/useAgentSession.ts at line 546, the code calls getToolNamesForPreset(toolPreset) to generate the toolNames array. This array is then sent to the server via a POST request to /api/agent/new as part of the session initialization payload.

Detecting the Active Preset from Tool Lists

For existing sessions, the UI must determine which preset corresponds to the currently active tools. The application retrieves the agent's tool list via the get_tools method, then passes the array of ToolEntry objects to getPresetFromTools. This function, implemented at lines 15-27 in lib/tool-presets.ts, compares the active tools against the preset definitions and returns "none", "default", or "full". This logic is invoked in hooks/useAgentSession.ts at line 514 to synchronize the UI's preset selector with the actual session state.

Server-Side Tool Enforcement

The server-side agent validates all incoming tool calls against the toolNames array provided during session creation. Any tool invocation not present in the original preset is ignored, creating a security boundary that prevents accidental exposure of filesystem or shell capabilities beyond the intended scope.

Working with Tool Presets in Code

To retrieve the tool names for a specific preset, import the helper function from the presets library:

import { getToolNamesForPreset, type ToolPreset } from '@/lib/tool-presets';

const preset: ToolPreset = 'full';
const tools = getToolNamesForPreset(preset);
console.log(tools); // ["bash","read","edit","write","grep","find","ls"]

To determine which preset matches an active tool configuration:

import { getPresetFromTools, type ToolEntry } from '@/lib/tool-presets';

const activeTools: ToolEntry[] = [
  { name: 'read', description: 'Read a file', active: true },
  { name: 'bash', description: 'Run shell commands', active: true },
  { name: 'edit', description: 'Edit a file', active: true },
  { name: 'write', description: 'Write a file', active: true },
];

const preset = getPresetFromTools(activeTools);
console.log(preset); // "default"

When creating a session programmatically, pass the derived tool names to the API:

async function createSession(cwd: string, preset: 'none' | 'default' | 'full') {
  const toolNames = getToolNamesForPreset(preset);
  const res = await fetch('/api/agent/new', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      cwd,
      type: 'ensure_session',
      toolNames,
    }),
  });
  const { sessionId } = await res.json();
  return sessionId;
}

Summary

• Pi-web tool presets define three capability levels (NONE, DEFAULT, FULL) that control agent access to filesystem and shell tools.
• The constants PRESET_NONE, PRESET_DEFAULT, and PRESET_FULL are defined in lib/tool-presets.ts (lines 9-11) and contain specific arrays of tool names.
• The getToolNamesForPreset function converts preset names to tool arrays for session creation, used in hooks/useAgentSession.ts at line 546.
• The getPresetFromTools function classifies active tool lists back into preset categories (lines 15-27), enabling the UI to display the correct selection.
• Server-side enforcement ensures agents cannot invoke tools outside their assigned preset, maintaining security boundaries.

Frequently Asked Questions

What tools are included in each pi-web tool preset?

PRESET_NONE provides an empty tool set with no filesystem or shell access. PRESET_DEFAULT includes read, bash, edit, and write for basic file operations. PRESET_FULL extends the default set with grep, find, and ls for comprehensive filesystem searching and directory listing capabilities.

How does the pi-web UI detect which preset is currently active?

The UI calls getPresetFromTools from lib/tool-presets.ts (lines 15-27), passing in the array of active ToolEntry objects retrieved from the agent. This function compares the active tools against the preset definitions and returns the matching preset identifier ("none", "default", or "full"), which is used to update the preset selector in the interface.

Where are the pi-web tool preset constants defined?

The preset constants are defined as exported arrays in lib/tool-presets.ts at lines 9-11. PRESET_NONE is an empty array, PRESET_DEFAULT contains four tools, and PRESET_FULL contains seven tools. The file also exports the ToolPreset type and helper functions for converting between preset names and tool arrays.

Can I create a session with a custom tool combination outside the three presets?

While the API endpoint /api/agent/new accepts any array of toolNames, the getPresetFromTools function is designed to classify tool sets into only the three predefined categories. Custom combinations that do not exactly match NONE, DEFAULT, or FULL will not be recognized by the preset detection logic in hooks/useAgentSession.ts, though the server will still enforce the specific tool list provided during session creation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}