How Hyperresearch Enforces Tool-Locking for Patcher and Polish Auditor Agents

Hyperresearch enforces tool-locking by restricting the patcher (Layer 6) and polish auditor (Layer 7) to only the Read and Edit tools through declarative YAML agent definitions in src/hyperresearch/core/hooks.py and runtime tool-capability masks that reject any disallowed tool requests.

The jordan-gibbs/hyperresearch repository implements a strict capability-based security model for its multi-layer research pipeline. Hyperresearch's tool-locking mechanism ensures that sensitive editing agents cannot perform destructive regeneration operations, maintaining content integrity through surgical edits only.

Declarative Agent Definitions in hooks.py

The foundation of Hyperresearch's tool-locking strategy lies in static YAML definitions that explicitly declare permitted capabilities. These definitions act as the single source of truth for what tools each agent may invoke.

Patcher Agent Configuration

In src/hyperresearch/core/hooks.py, the patcher agent is defined with a hardcoded tools: Read, Edit stanza that prevents access to write or execution capabilities. The definition appears at lines 1320‑1335:

PATCHER_AGENT = """\
---
name: hyperresearch-patcher
description: >
  Use this agent in Layer 6 of the hyperresearch deep research pipeline.
  Tool-locked: Read + Edit ONLY. Cannot Write. Cannot regenerate.
model: << p.models.patcher >>
tools: Read, Edit
color: orange
---
"""

This YAML block explicitly limits the agent to Read and Edit tools, prohibiting Write, Bash, or other potentially hazardous operations.

Polish Auditor Agent Configuration

Similarly, the polish auditor (Layer 7) carries an identical tool restriction at lines 1495‑1505 in the same file:

POLISH_AUDITOR_AGENT = """\
---
name: hyperresearch-polish-auditor
description: >
  Layer 7 – polish auditor. Read + Edit ONLY.
tools: Read, Edit
---
"""

Both agents share the exact same tool-locking contract, ensuring consistency across the final editing stages of the pipeline.

Runtime Enforcement Mechanism

Hyperresearch translates these static declarations into runtime restrictions through a tool-capability mask applied during agent spawning. When the orchestrator initializes either agent, it parses the tools: field and constructs a sandboxed environment that filters available capabilities.

The enforcement flow operates as follows:

1. Parse Phase – The orchestrator extracts the allowed tool set from the agent's YAML definition
2. Mask Construction – A capability mask is built containing only the declared tools (Read, Edit)
3. Sandbox Application – The mask restricts the agent's execution context
4. Validation – Any attempt to invoke disallowed tools triggers an immediate error

def spawn_agent(agent_yaml):
    allowed_tools = parse_tools(agent_yaml)               # → {"Read", "Edit"}

    sandbox = ToolSandbox(allowed=allowed_tools)         # restricts available tools

    return sandbox.run(agent_yaml)                       # any disallowed tool → error

This runtime layer ensures that even if an agent's logic attempts to request a prohibited tool like Write or Bash, the underlying infrastructure blocks the invocation before execution.

The No-Regeneration Invariant

The tool-locking mechanism upholds a critical architectural guarantee documented directly in src/hyperresearch/core/hooks.py at lines 1320‑1322:

"The tool lock enforces the no‑regeneration invariant; the revisor makes surgical edits, not rewrites."

By restricting the patcher and polish auditor to Read and Edit operations exclusively, Hyperresearch prevents these agents from:

• Generating entirely new content sections
• Overwriting existing content with regenerated text
• Executing shell commands that could modify the filesystem outside the editing context

This invariant ensures that refinement operations remain surgical—modifying specific text ranges rather than wholesale replacement—preserving the semantic consistency of research outputs throughout Layer 6 and Layer 7 processing.

Summary

• Declarative restrictions in src/hyperresearch/core/hooks.py define the [Read, Edit] tool set for both the patcher (lines 1320‑1335) and polish auditor (lines 1495‑1505)
• Runtime capability masks translate YAML declarations into enforced sandbox restrictions during agent spawning
• Error-on-violation behavior ensures that any request for disallowed tools (Write, Bash, etc.) fails immediately rather than executing
• No-regeneration invariant guarantees that editing agents perform surgical modifications only, never full rewrites

Frequently Asked Questions

What specific tools are the patcher and polish auditor allowed to use?

According to the source code in src/hyperresearch/core/hooks.py, both agents are restricted exclusively to the Read and Edit tools. The YAML definitions for both PATCHER_AGENT and POLISH_AUDITOR_AGENT explicitly declare tools: Read, Edit, preventing access to Write, Bash, or other potentially destructive capabilities.

Where in the codebase is the tool-locking defined?

The tool-locking definitions reside in src/hyperresearch/core/hooks.py. The patcher configuration appears at lines 1320‑1335, while the polish auditor configuration is located at lines 1495‑1505. These YAML strings serve as the authoritative source for runtime enforcement.

How does Hyperresearch prevent agents from bypassing tool restrictions?

Hyperresearch implements runtime capability masks that parse the tools: field from agent definitions and construct restricted sandboxes. When an agent attempts to invoke a tool, the sandbox validates the request against the allowed set. Any attempt to use a tool not listed in the original YAML definition results in an immediate execution error, making bypass impossible through standard operation.

Why does Hyperresearch restrict these specific agents to Read and Edit only?

The restriction upholds the no-regeneration invariant critical to Hyperresearch's research pipeline. By limiting the patcher and polish auditor to surgical edits rather than allowing Write operations or shell execution, the system ensures that content refinement modifies existing text precisely without introducing wholesale regenerated sections that could drift from the original research context.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}