<!-- source: https://deepwiki.com/qhkm/zeptoclaw/5.4-agent-templates -->

# Agent Templates

- src/agent/budget.rs
- src/agent/tool_call_limit.rs
- src/cli/common.rs
- src/config/templates.rs
- src/lib.rs
- src/tools/mod.rs

Agent templates provide a mechanism to pre-configure agent behavior with custom system prompts, tool restrictions, and model overrides. Templates support both built-in presets (shipped with ZeptoClaw) and user-defined configurations stored in `~/.zeptoclaw/templates/*.json`.

For general configuration concepts, see [Configuration File Structure](/qhkm/zeptoclaw/5.1-configuration-file-structure). For runtime model switching per chat, see [Runtime Model Switching](/qhkm/zeptoclaw/10.4-runtime-model-switching).

## Template Structure

A template is defined by the `AgentTemplate` struct and consists of the following fields:

**Sources:** [src/config/templates.rs24-83](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/templates.rs#L24-L83)

## Template Resolution and Application

### Template Data Flow

The following diagram bridges the "Natural Language Space" (user commands and template names) to the "Code Entity Space" (internal structs and logic).

**Title: Template Resolution to Agent Execution**

```

```

**Sources:** [src/config/templates.rs18-83](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/templates.rs#L18-L83) [src/agent/budget.rs174-185](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/agent/budget.rs#L174-L185) [src/agent/tool_call_limit.rs9-15](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/agent/tool_call_limit.rs#L9-L15) [src/cli/common.rs84-111](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/common.rs#L84-L111) [src/config/templates.rs1-12](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/templates.rs#L1-L12)

## Built-in Templates

ZeptoClaw provides hardcoded templates defined in `src/config/templates.rs`. These can be overridden by user files of the same name.

- coder : An expert software engineering persona. Accesses all tools. Includes a specific workflow for bug fixing and testing, preferring edit_file over write_file and utilizing find / grep for discovery src/config/templates.rs 92-127
- researcher : A research assistant limited to information-gathering tools like web_search , web_fetch , memory_search , memory_get , and longterm_memory src/config/templates.rs 132-161

**Sources:** [src/config/templates.rs89-161](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/templates.rs#L89-L161)

## Tool and Shell Restrictions

Templates allow for fine-grained security and capability control:

### Tool Filtering

- allowed_tools : If set, the ToolRegistry is filtered to only include these tools src/config/templates.rs 47-50
- blocked_tools : Tools explicitly removed from the available set after allowlist filtering src/config/templates.rs 52-55

### Shell Security

The `shell_allowlist` field directly influences binary execution policy for tools that spawn external processes.

- None : Inherit default blocklist-only behavior src/config/templates.rs 66
- Some(vec![]) : Deny all shell commands (Strict mode + empty allowlist) src/config/templates.rs 67
- Some(vec!["git", "cargo"]) : Only allow the git and cargo binaries src/config/templates.rs 68

This policy is applied to `ShellTool`, `CustomTool`, and `BinaryPluginTool` [src/config/templates.rs69](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/templates.rs#L69-L69)

**Sources:** [src/config/templates.rs65-71](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/templates.rs#L65-L71)

## Resource Enforcement

Templates introduce two specific counters to prevent runaway costs or infinite tool loops:

### Token Budget

The `max_token_budget` is resolved via `resolve_token_budget`. If both a global limit and a template limit exist, the lower value is used [src/agent/budget.rs174-185](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/agent/budget.rs#L174-L185) The `TokenBudget` struct tracks `input_used` and `output_used` atomically using `AtomicU64` with `Relaxed` ordering [src/agent/budget.rs32-39](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/agent/budget.rs#L32-L39) [src/agent/budget.rs63-66](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/agent/budget.rs#L63-L66)

### Tool Call Limits

Unlike the per-turn `max_tool_iterations`, the `max_tool_calls` field sets a hard cap on the *total* number of tool executions across the entire agent run [src/config/templates.rs79-82](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/templates.rs#L79-L82) This is tracked by the `ToolCallLimitTracker` which is reset per message processing run [src/agent/tool_call_limit.rs9-15](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/agent/tool_call_limit.rs#L9-L15) [src/agent/tool_call_limit.rs65-67](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/agent/tool_call_limit.rs#L65-L67)

**Title: Resource Limit Enforcement in AgentLoop**

```

```

**Sources:** [src/agent/budget.rs63-66](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/agent/budget.rs#L63-L66) [src/agent/tool_call_limit.rs38-40](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/agent/tool_call_limit.rs#L38-L40) [src/agent/budget.rs102-107](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/agent/budget.rs#L102-L107) [src/agent/tool_call_limit.rs43-48](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/agent/tool_call_limit.rs#L43-L48)

## User-Defined Templates

User templates are stored as JSON files in `~/.zeptoclaw/templates/`. The `TemplateRegistry` loads these files during initialization [src/cli/common.rs84-91](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/common.rs#L84-L91)

### Example Template File

```

```

**Sources:** [src/config/templates.rs1-12](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/templates.rs#L1-L12) [src/cli/common.rs84-91](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/common.rs#L84-L91)

## Template vs. Runtime Overrides

The system follows a specific priority order for configuration:

1. Global Defaults : Defined in the configuration file under agents.defaults src/lib.rs 54
2. Template Overrides : Applied when a template is selected via the --template CLI flag or channel metadata src/cli/common.rs 196-200
3. Environment Variables : ZEPTOCLAW_* environment variables provide the final overlay for configuration values.
4. Active Hand : If a "hand" is active, it may provide further persona and tool context src/cli/common.rs 201-213

**Sources:** [src/lib.rs54](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/lib.rs#L54-L54) [src/cli/common.rs191-215](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/common.rs#L191-L215) [src/config/templates.rs18-22](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/config/templates.rs#L18-L22)
