# Applying Levers to Subagent Prompts in Hyperresearch: A Technical Deep Dive

> Learn how Hyperresearch applies levers to subagent prompts by rendering runtime instructions into static shim files. Discover how the orchestrator enforces consistent behavior across your research pipeline.

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

---

**Hyperresearch applies levers to subagent prompts by first rendering run-time posture instructions into static role-specific shim files, which the orchestrator then injects verbatim into each subagent's spawn prompt to enforce consistent behavior across the research pipeline.**

In Jordan Gibbs' Hyperresearch framework, **levers** function as the central configuration mechanism for controlling subagent posture without modifying individual agent logic. Rather than passing dynamic parameters directly to each subagent at spawn time, the system implements a decoupled three-stage pipeline that ensures every subagent inherits identical run-level settings. This article traces the technical implementation from lever definition in [`prompt-decomposition.json`](https://github.com/jordan-gibbs/hyperresearch/blob/main/prompt-decomposition.json) through shim rendering to final prompt assembly.

## Understanding Lever Storage in [`prompt-decomposition.json`](https://github.com/jordan-gibbs/hyperresearch/blob/main/prompt-decomposition.json)

**Levers** are persisted as structured configuration data within each run's [`prompt-decomposition.json`](https://github.com/jordan-gibbs/hyperresearch/blob/main/prompt-decomposition.json) file. According to the schema definition in [`src/hyperresearch/core/levers.py`](https://github.com/jordan-gibbs/hyperresearch/blob/main/src/hyperresearch/core/levers.py) (lines 3-12), the `"levers"` block captures three critical posture parameters: the selected **register** (stylistic tone), the **inference depth** (processing thoroughness), and optional **domain notes** (specialized context). This JSON structure serves as the single source of truth for run-level behavior, decoupling researcher intent from subagent implementation details.

## Rendering Levers to Role-Specific Shim Files

The transformation from abstract configuration to concrete prompt text occurs through the `render_shims` function implemented in [`src/hyperresearch/core/levers.py`](https://github.com/jordan-gibbs/hyperresearch/blob/main/src/hyperresearch/core/levers.py) (lines 90-104). This function bridges the gap between declarative lever settings and the imperative prompt engineering required by different subagent types.

### The `render_shims` Function Implementation

When invoked, `render_shims` reads the lever configuration and generates four distinct markdown files, each tailored to a specific pipeline role:

- **research.md**: For fetcher and depth-investigator agents
- **drafting.md**: For content generation agents
- **critics.md**: For review and evaluation agents  
- **polish.md**: For final refinement agents

Each shim file is composed by concatenating a standardized header with optional domain notes and an inference-depth instruction block specific to that role's responsibilities. The output is written to `research/runs/<tag>/shims/`, creating static assets that cache the run's posture for repeated use.

To generate these files via the CLI:

```bash
hpr levers render my-run-tag

```

Or to update a lever and regenerate the shims in a single operation:

```bash
hpr levers set my-run-tag inference_depth=deep --rerender

```

## Injecting Shim Content into Subagent Prompts

Once rendered, the shim files function as immutable prompt prefixes that standardize subagent behavior across the entire pipeline.

### Orchestrator Prompt Assembly

When spawning a subagent—whether initializing a **fetcher**, **depth-investigator**, or **critic**—the orchestrator locates the appropriate shim file for that agent's role and inserts its contents verbatim at the beginning of the prompt. As illustrated by the internal pipeline logic, this insertion ensures the subagent receives the complete posture context without requiring runtime computation:

```python

# Pseudocode representing orchestrator behavior in Hyperresearch

shim_text = (vault.run_dir(tag) / "shims" / f"{role}.md").read_text()
prompt = f"{shim_text}\n\n{subagent_specific_instructions}"
spawn_subagent(prompt)

```

This verbatim injection guarantees that parameters defined in the levers—such as demanding "deep" inference or specifying technical domain constraints—propagate identically to every subagent participating in the run.

### Verification in [`core/runs.py`](https://github.com/jordan-gibbs/hyperresearch/blob/main/core/runs.py)

The system enforces shim existence through a pre-flight verification step in [`src/hyperresearch/core/runs.py`](https://github.com/jordan-gibbs/hyperresearch/blob/main/src/hyperresearch/core/runs.py) (lines 498-506). Before allowing a run to proceed, the orchestrator confirms that all four required shim files ([`research.md`](https://github.com/jordan-gibbs/hyperresearch/blob/main/research.md), [`drafting.md`](https://github.com/jordan-gibbs/hyperresearch/blob/main/drafting.md), [`critics.md`](https://github.com/jordan-gibbs/hyperresearch/blob/main/critics.md), [`polish.md`](https://github.com/jordan-gibbs/hyperresearch/blob/main/polish.md)) exist in `research/runs/<tag>/shims/`. This verification acts as a contractual gate, preventing execution if levers have not been rendered for the current run configuration.

You can inspect a generated shim manually to verify its contents:

```bash
cat research/runs/my-run-tag/shims/research.md

```

## Command-Line Workflow for Lever Management

The [`src/hyperresearch/cli/levers_cmd.py`](https://github.com/jordan-gibbs/hyperresearch/blob/main/src/hyperresearch/cli/levers_cmd.py) module exposes intuitive commands for managing the lever-to-shim pipeline:

1. **Initialize or refresh shims**: `hpr levers render <tag>`
2. **Update specific parameters**: `hpr levers set <tag> register=academic --rerender`
3. **Inspect outputs**: Direct file examination of `research/runs/<tag>/shims/*.md`

This workflow ensures that **applying levers to subagent prompts** remains an explicit, version-controlled operation rather than a hidden runtime side effect.

## Summary

- **Levers** are stored as structured JSON in [`prompt-decomposition.json`](https://github.com/jordan-gibbs/hyperresearch/blob/main/prompt-decomposition.json), capturing register, inference depth, and domain guidance.
- The `render_shims` function in [`src/hyperresearch/core/levers.py`](https://github.com/jordan-gibbs/hyperresearch/blob/main/src/hyperresearch/core/levers.py) (lines 90-104) generates four role-specific markdown files under `research/runs/<tag>/shims/`.
- The orchestrator injects these shim files verbatim into subagent spawn prompts, ensuring consistent posture inheritance.
- Verification logic in [`src/hyperresearch/core/runs.py`](https://github.com/jordan-gibbs/hyperresearch/blob/main/src/hyperresearch/core/runs.py) (lines 498-506) enforces shim presence before run execution.
- CLI commands in [`src/hyperresearch/cli/levers_cmd.py`](https://github.com/jordan-gibbs/hyperresearch/blob/main/src/hyperresearch/cli/levers_cmd.py) provide explicit control over the rendering pipeline.

## Frequently Asked Questions

### What parameters can be configured via levers?

Levers control three primary posture dimensions: the **register** (stylistic tone such as academic or conversational), **inference depth** (processing thoroughness ranging from shallow to deep), and optional **domain notes** (specialized contextual guidance). These are defined in the `"levers"` block of [`prompt-decomposition.json`](https://github.com/jordan-gibbs/hyperresearch/blob/main/prompt-decomposition.json) and validated by the schema in [`core/levers.py`](https://github.com/jordan-gibbs/hyperresearch/blob/main/core/levers.py).

### How does the orchestrator ensure consistent posture across subagents?

The orchestrator achieves consistency by loading static shim files from `research/runs/<tag>/shims/` and pasting their contents verbatim into every subagent's initial prompt. Because all agents of a given role receive identical shim text derived from the same lever configuration, they share the exact same posture constraints without requiring individual parameter passing.

### What happens if shim files are missing at runtime?

The verification routine in [`src/hyperresearch/core/runs.py`](https://github.com/jordan-gibbs/hyperresearch/blob/main/src/hyperresearch/core/runs.py) (lines 498-506) checks for the presence of all four required shim files before allowing a run to continue. If any shim is missing, the orchestrator halts execution and requires the user to run `hpr levers render <tag>` to generate the missing files, enforcing the architectural contract that levers must be explicitly rendered.

### Can I manually edit generated shim files?

While technically possible, manual editing of files in `research/runs/<tag>/shims/` is not recommended because the `render_shims` function will overwrite these files whenever `hpr levers render` or `hpr levers set --rerender` is executed. To make persistent changes, modify the source lever configuration and re-render the shims through the CLI.