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

> Master pi-web tool presets NONE, DEFAULT, and FULL. Understand how these configurations control agent tool availability and enhance your sessions.

- Repository: [Alex Yang/pi-web](https://github.com/agegr/pi-web)
- Tags: deep-dive
- Published: 2026-07-24

---

**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`](https://github.com/agegr/pi-web/blob/main/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`](https://github.com/agegr/pi-web/blob/main/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`](https://github.com/agegr/pi-web/blob/main/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`](https://github.com/agegr/pi-web/blob/main/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`](https://github.com/agegr/pi-web/blob/main/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:

```typescript
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:

```typescript
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:

```typescript
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`](https://github.com/agegr/pi-web/blob/main/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`](https://github.com/agegr/pi-web/blob/main/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`](https://github.com/agegr/pi-web/blob/main/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`](https://github.com/agegr/pi-web/blob/main/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`](https://github.com/agegr/pi-web/blob/main/hooks/useAgentSession.ts), though the server will still enforce the specific tool list provided during session creation.