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

> Learn how Hyperresearch enforces tool-locking for Patcher and Polish Auditor agents using YAML definitions and runtime masks. Restrict tools effectively.

- Repository: [Jordan Gibbs/hyperresearch](https://github.com/jordan-gibbs/hyperresearch)
- Tags: internals
- Published: 2026-09-13

---

**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`](https://github.com/jordan-gibbs/hyperresearch/blob/main/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`](https://github.com/jordan-gibbs/hyperresearch/blob/main/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:

```yaml
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:

```yaml
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

```python
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`](https://github.com/jordan-gibbs/hyperresearch/blob/main/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`](https://github.com/jordan-gibbs/hyperresearch/blob/main/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`](https://github.com/jordan-gibbs/hyperresearch/blob/main/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`](https://github.com/jordan-gibbs/hyperresearch/blob/main/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.