<!-- source: https://deepwiki.com/qhkm/zeptoclaw/6.3-agent-mode-policies -->

# Agent Mode Policies

- src/audit.rs
- src/kernel/gate.rs
- src/safety/chain_alert.rs
- src/safety/mod.rs
- src/security/shell.rs
- src/tools/approval.rs

This page documents ZeptoClaw's **agent mode system**, which provides category-based autonomy controls for tool execution. Agent modes define coarse-grained access policies that determine whether a tool category requires approval, is blocked, or is allowed without intervention.

For general security architecture and defense-in-depth layers, see [6.1 Security Architecture](https://github.com/qhkm/zeptoclaw/blob/2c743d31/6.1 Security Architecture) For fine-grained tool-specific approval gates and policy configuration, see [6.2 SafetyLayer Components](https://github.com/qhkm/zeptoclaw/blob/2c743d31/6.2 SafetyLayer Components) For shell-specific security controls, see [6.4 Shell Security](https://github.com/qhkm/zeptoclaw/blob/2c743d31/6.4 Shell Security)

## Overview

Agent modes define the trust level of an agent session by mapping tool categories to permissions. This enforcement happens in the agent loop **before** the approval gate and safety scans [src/kernel/gate.rs9-10](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/kernel/gate.rs#L9-L10)

The mode is resolved from the `ApprovalConfig` and enforced by a `ModePolicy` that determines the `CategoryPermission`.

**Sources:** [src/kernel/gate.rs1-11](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/kernel/gate.rs#L1-L11) [src/tools/approval.rs49-85](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/approval.rs#L49-L85)

## Tool Categories and Actions

Every tool invocation is classified by the `audit_specific_action` function to map tool names to security-sensitive actions [src/kernel/gate.rs34-41](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/kernel/gate.rs#L34-L41) This classification informs the `record_tool_execution_audit` and determines which audit category is triggered [src/kernel/gate.rs43-47](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/kernel/gate.rs#L43-L47)

**Sources:** [src/kernel/gate.rs34-47](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/kernel/gate.rs#L34-L47) [src/audit.rs75-86](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/audit.rs#L75-L86)

## Mode Policy Matrix

The system evaluates a tool against the active mode to return a permission level.

### Observer Mode

Designed for read-only access.

- Allowed : Read-only tools (e.g., filesystem_read , longterm_memory ).
- Blocked : Side-effect tools like shell or write_file .

### Assistant Mode (Default)

The standard interactive mode defined in `ApprovalPolicyConfig::RequireForDangerous` [src/tools/approval.rs83](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/approval.rs#L83-L83)

- Allowed : Standard read/write tools that aren't marked as dangerous.
- Requires Approval : Tools listed in dangerous_tools (defaults to ["shell", "write_file", "edit_file", "google"] ) src/tools/approval.rs 118-120 src/tools/approval.rs 132

### Autonomous Mode

Unrestricted access for trusted automation.

- Allowed : All tool categories, corresponding to ApprovalPolicy::AlwaysRequire src/tools/approval.rs 58 or custom configurations where enabled is false src/tools/approval.rs 109

**Sources:** [src/tools/approval.rs49-85](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/approval.rs#L49-L85) [src/tools/approval.rs102-136](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/approval.rs#L102-L136)

## Configuration

Agent mode and approval behavior are configured via the `ApprovalConfig` struct [src/tools/approval.rs102-104](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/approval.rs#L102-L104) typically found in `config.json`.

```

```

The `ApprovalGate` [src/tools/approval.rs202](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/approval.rs#L202-L202) uses this configuration to determine if a specific tool name requires a user prompt via `requires_approval(name)` [src/tools/approval.rs38-39](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/approval.rs#L38-L39)

**Sources:** [src/tools/approval.rs102-136](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/approval.rs#L102-L136)

## Runtime Enforcement Flow

The following diagram illustrates how the kernel's `execute_tool` function [src/kernel/gate.rs131](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/kernel/gate.rs#L131-L131) acts as the primary gatekeeper, integrating safety scans, taint tracking, and audit logging.

### Policy Enforcement Pipeline

```

```

**Sources:** [src/kernel/gate.rs131-175](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/kernel/gate.rs#L131-L175) [src/tools/approval.rs145-184](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/approval.rs#L145-L184) [src/kernel/gate.rs65-117](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/kernel/gate.rs#L65-L117)

## Tool Category Mapping

The mapping between user-facing modes and the underlying code entities is managed by the `ApprovalGate` and the core `execute_tool` logic.

### Code Entity Association

```

```

**Sources:** [src/tools/approval.rs54-63](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/approval.rs#L54-L63) [src/tools/approval.rs202-210](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/approval.rs#L202-L210) [src/kernel/gate.rs131-135](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/kernel/gate.rs#L131-L135)

## Approval Gates

While agent modes provide high-level enforcement, the `ApprovalGate` [src/tools/approval.rs202](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/approval.rs#L202-L202) handles fine-grained, tool-specific confirmation.

### Approval Policies

The `ApprovalPolicy` enum [src/tools/approval.rs54-63](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/approval.rs#L54-L63) defines how the gate behaves:

- AlwaysAllow : Bypasses all approvals src/tools/approval.rs 56
- AlwaysRequire : Forces approval for every tool invocation src/tools/approval.rs 58
- RequireForTools(Vec<String>) : Gates specific tools by name src/tools/approval.rs 60
- RequireForDangerous : Gates tools listed in dangerous_tools (default) src/tools/approval.rs 62

### Interaction with Agent Mode

If a tool is deemed to require approval, an `ApprovalRequest` is generated [src/tools/approval.rs145](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/approval.rs#L145-L145) The `ApprovalConfig` allows setting an `auto_approve_timeout_secs` [src/tools/approval.rs123](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/approval.rs#L123-L123) If this is non-zero, the request will automatically proceed after the timeout via `is_auto_approved()` [src/tools/approval.rs178-183](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/approval.rs#L178-L183)

**Sources:** [src/tools/approval.rs102-196](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/approval.rs#L102-L196) [src/tools/approval.rs202-234](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/approval.rs#L202-L234)

## Implementation Details

### Kernel Integration

The kernel's `execute_tool` function [src/kernel/gate.rs131](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/kernel/gate.rs#L131-L131) is the final choke point. It enforces `SafetyLayer` and `TaintEngine` policies [src/kernel/gate.rs148-168](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/kernel/gate.rs#L148-L168)

1. Safety Scan (Input) : scan_tool_input checks for injections or policy violations in arguments src/kernel/gate.rs 149 It uses specialized logic for write_file and edit_file to ignore shell_injection rules in file bodies src/kernel/gate.rs 23 src/kernel/gate.rs 75-117
2. Taint Check : Blocks sensitive sinks if they contain data from untrusted sources src/kernel/gate.rs 157-168
3. Execution : Runs the tool via the ToolRegistry src/kernel/gate.rs 171
4. Safety Scan (Output) : Prevents data leaks in the result using safety_layer.scan src/kernel/gate.rs 181-190
5. Audit Logging : Every tool execution, whether successful or blocked, is recorded in the immutable audit chain src/kernel/gate.rs 150 src/kernel/gate.rs 160 src/kernel/gate.rs 174

### Tool Chain Alerting

The `ChainTracker` [src/safety/chain_alert.rs30](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/safety/chain_alert.rs#L30-L30) provides a secondary layer of security by detecting suspicious tool call sequences, such as `filesystem_write` followed by `shell_execute` [src/safety/chain_alert.rs12-16](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/safety/chain_alert.rs#L12-L16) This system is non-blocking but emits `AuditCategory::ToolChainAlert` warnings and logs audit events [src/safety/chain_alert.rs74-80](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/safety/chain_alert.rs#L74-L80)

**Sources:** [src/kernel/gate.rs131-195](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/kernel/gate.rs#L131-L195) [src/safety/chain_alert.rs1-35](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/safety/chain_alert.rs#L1-L35) [src/audit.rs14-35](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/audit.rs#L14-L35)
