Agent Access and Approval Tiers

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• AGENTS.md
• src/index.ts
• src/routing.ts
• src/tools/morph-edit.ts
• src/tools/warpgrep.ts
• test/morph.test.ts

Introduction

In the oh-my-pi-plugin-morph extension, Agent Access and Approval Tiers define how AI agents interact with Morph-backed tools and the host filesystem. Access is managed through a combination of tool registration, environment-based feature flags, and explicit agent manifest allowlists. The system ensures that agents only utilize tools they are authorized to use, categorized by the level of risk or impact their operations have on the codebase.

Approval tiers are specifically assigned to tools to dictate the permissions required for execution. These tiers range from read (for information gathering) to write (for modifying existing files or creating new ones). This structure allows for a clear separation between read-only agents and those capable of performing destructive or constructive operations within a session.

Sources: README.md:129-136, src/tools/morph-edit.ts:91, src/tools/warpgrep.ts:86

Tool Approval Tiers

Each Morph tool is registered with a specific approval level. This metadata is used by the host oh-my-pi environment to enforce security boundaries.

Write Tier

The Write tier is reserved for tools that can mutate the workspace.

• fast_edit: This tool allows for large-scale, scattered, or complex refactors of existing files. Because it results in filesystem changes, it requires the highest level of trust.

Read Tier

The Read tier is applied to tools that retrieve information without altering the workspace state.

• codebase_warpsearch: Performs agentic natural-language search over the local workspace.
• github_warpsearch: Conducts grounded source search for public GitHub repositories.
• fastcompact: Condenses specific files or artifacts into shorter text digests.

Sources: README.md:68-103, src/tools/morph-edit.ts:91, src/tools/warpgrep.ts:86, src/tools/warpgrep.ts:167

Summary of Tiers and Tools

Tool Name	Approval Tier	Description
fast_edit	write	AI-driven merging for scattered/large edits.
codebase_warpsearch	read	Local workspace natural-language search.
github_warpsearch	read	Remote public GitHub repository search.
fastcompact	read	Digest/summary of specific files or artifacts.

Sources: README.md:68-103, test/morph.test.ts:881-884

Agent Manifest Access

While the plugin registers tools to the session, individual agents must explicitly include these tools in their own manifest allowlist. This provides a secondary layer of control beyond the tool's approval tier.

• Write-Capable Agents: Recommended to allow fast_edit, codebase_warpsearch, github_warpsearch, and fastcompact.
• Read-Only Agents: Recommended to restrict access to codebase_warpsearch and github_warpsearch only.

Sources: README.md:133-136, CHANGELOG.md:46-47

Agent Registration Flow

The following diagram illustrates how the plugin registers tools and how agents access them based on their configuration and approval levels.

This diagram shows the logical flow from plugin initialization through to tool execution, highlighting the gates provided by manifest allowlists and approval tiers.
Sources: src/index.ts:15-20, README.md:133-136

Runtime Access Guidance

The extension provides runtime notes and routing hints to agents based on the availability of the MORPH_API_KEY. If the key is missing, tools remain registered but return setup guidance and direct the agent toward native equivalents.

// src/routing.ts:28-32
if (notes.length > 0 && !MORPH_API_KEY) {
    notes.push("Currently unavailable until MORPH_API_KEY is configured.");
}

return appendRuntimeNotes("", notes).trim();

Routing Policy Logic

The before_agent_start hook appends a tool-selection policy that varies based on the configuration state:

1. Configured Key: The system-prompt instructs the agent to "Favor Morph-backed tools over their native equivalents" for suitable tasks.
2. Missing Key: The system-prompt explicitly states that Morph tools are unavailable and directs the agent to use native edit, write, or search.

Sources: src/routing.ts:38-50, src/index.ts:22-31, AGENTS.md:11-15

Security and Verification

Access is further protected by verification gates during tool execution. For example, fast_edit performs strict filepath resolution to prevent path traversal, ensuring that write access is confined to the authorized workspace root.

This sequence diagram demonstrates the security checks performed by the fast_edit tool before granting filesystem write access.
Sources: src/tools/morph-edit.ts:104-123, test/morph.test.ts:251-274

Conclusion

The Agent Access and Approval Tiers system in the Morph plugin provides a granular security model. By combining tool-level approval metadata (read/write), agent-specific manifests, environment-based feature toggles, and runtime routing hints, the project ensures that agents operate within safe and expected boundaries while prioritizing the most efficient tools available for a given task.

Sources: README.md:129-136, src/routing.ts:74-78