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

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 through shim rendering to final prompt assembly.

Understanding Lever Storage in prompt-decomposition.json

Levers are persisted as structured configuration data within each run's prompt-decomposition.json file. According to the schema definition in 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 (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:

hpr levers render my-run-tag

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

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:

# 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

The system enforces shim existence through a pre-flight verification step in 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, drafting.md, critics.md, 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:

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

Command-Line Workflow for Lever Management

The 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, capturing register, inference depth, and domain guidance.
• The render_shims function in 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 (lines 498-506) enforces shim presence before run execution.
• CLI commands in 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 and validated by the schema in 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 (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.

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