Agent Routing and System Hints

Relevant source files

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

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

The Agent Routing and System Hints system manages how the oh-my-pi-plugin-morph extension guides AI agents toward the most efficient tool for a given task. It establishes a "routing contract" that prefers Morph-backed tools—such as fast_edit and codebase_warpsearch—over native alternatives while ensuring that agents remain functional when credentials (like MORPH_API_KEY) are missing.

This system injects high-level behavioral policies into the agent's system prompt during the before_agent_start lifecycle event and appends specific "runtime notes" to tool descriptions. These hints help agents decide between using specialized Morph tools (optimized for large files or natural language search) and local native tools (optimized for trivial edits or exact string matches).

Sources: README.md:120-125, AGENTS.md:11-15, src/routing.ts:50-55

Routing Architecture

The routing logic is driven by environment configuration and the presence of API credentials. When the plugin initializes, it registers a hook for the before_agent_start event to provide the agent with a "System Routing Hint".

Routing Hint Lifecycle

The following diagram illustrates how the system determines which hint to provide the agent based on the runtime environment.

The system ensures that the routing guidance leads with a "Morph-first" preference when configured, but maintains a "native floor" for simple operations.
Sources: src/routing.ts:50-93, src/index.ts:24-33, test/morph.test.ts:745-755

Routing Logic and Contracts

The system operates under several strict routing contracts to ensure the agent uses the most cost-effective and performant tool for the job.

• Credential Dependency: If MORPH_API_KEY is absent, the system explicitly tells the agent that Morph tools are unavailable and routes them to native edit, write, and search tools.
• The Native Floor: Even when Morph is enabled, guidance suggests using native edit for trivial single-line or exact-string replacements, and native write for creating entirely new files.
• WarpGrep vs. Grep: Agents are instructed to prefer codebase_warpsearch for natural-language, exploratory questions (e.g., "Find the auth flow"), while using native grep for exact symbol or string lookups.

Sources: AGENTS.md:11-20, src/routing.ts:66-75, README.md:120-125

Key Routing Hints by Tool

Tool ID	Guidance Policy	Native Fallback Recommendation
fast_edit	Use for large files, scattered changes, or whitespace-sensitive edits.	Native edit for trivial single-line changes; write for new files.
codebase_warpsearch	Use for exploratory, natural-language workspace queries.	Native search/grep for exact symbol or string lookups.
github_warpsearch	Use for public GitHub source questions/internals.	Web search or standard doc fetching.
fastcompact	Use to condense specific files or artifacts before full reading.	None (specific to focused text reduction).

Sources: src/routing.ts:66-93, README.md:120-125

Runtime Tool Notes

Beyond the high-level system prompt hint, the system uses buildToolNote and withToolNote functions to append context-specific information to the descriptions of individual tools. This provides just-in-time guidance when the agent is inspecting its toolset.

Note Generation Logic

1. Contextual Awareness: Notes are added for specific behaviors (e.g., "Relative paths resolve from the active session directory" for fast_edit).
2. Availability Status: If the MORPH_API_KEY is missing, a specific note is appended stating the tool is "Currently unavailable until MORPH_API_KEY is configured."
3. Workspace Redirects: For tools like github_warpsearch, a note may redirect the agent to codebase_warpsearch if they are searching the local workspace.

Sources: src/routing.ts:16-48, src/tools/warpgrep.ts:133-135, test/morph.test.ts:718-725

Implementation Example: withToolNote

// src/routing.ts:45-48
export function withToolNote(description: string, toolID: string): string {
  const note = buildToolNote(toolID);
  return note ? `${description}\n\n${note}` : description;
}

Sources: src/routing.ts:45-48

Configuration Flags

The visibility and presence of these hints are controlled via environment variables in src/config.ts, integrated within the plugin factory in src/index.ts.

Variable	Default	Impact on Routing
MORPH_ROUTING_HINT	true	If false, the before_agent_start hook is not registered.
MORPH_EDIT	true	If false, fast_edit hints are removed from the system prompt.
MORPH_WARPGREP	true	Controls advertising of codebase_warpsearch in hints.
MORPH_WARPGREP_GITHUB	true	Controls advertising of github_warpsearch in hints.

Sources: README.md:43-52, src/index.ts:19-25, test/morph.test.ts:1010-1040

Summary

The Agent Routing and System Hints system provides a governance layer that ensures agents efficiently utilize the Morph platform's capabilities. By balancing "Morph-first" preferences with a "native floor," the system prevents unnecessary remote API calls for trivial tasks while leveraging advanced LLM-backed search and editing for complex operations. This logic is strictly enforced through dynamic system prompt injection and real-time tool description updates based on the current environment state.

Sources: README.md:120-125, AGENTS.md:11-20