Customizing Per-Stage Policies in AutoResearchClaw's Co-Pilot Mode: A Complete Configuration Guide

Customize per-stage policies in AutoResearchClaw by configuring CoPilotConfig for global pause behavior and StagePolicy objects for granular human-in-the-loop controls at specific stages of the 23-step pipeline.

AutoResearchClaw's co-pilot mode enables precise human oversight across its 23-stage research pipeline through a two-layer policy system. By customizing per-stage policies in AutoResearchClaw's co-pilot mode, you can enforce approval gates at critical junctures, enable real-time collaboration during hypothesis generation, or stream execution logs while maintaining automatic execution elsewhere. This configuration relies on complementary mechanisms in researchclaw/config.py and researchclaw/hitl/config.py that determine when the system pauses and what interactive capabilities are exposed at each breakpoint.

Understanding the Two-Layer Policy System

The framework separates concerns into global co-pilot settings and per-stage HITL policies:

• Global settings (CoPilotConfig in researchclaw/config.py at line 792) define the overarching pause strategy—whether to stop at every stage, only at gate stages, or run fully automatic.
• Per-stage policies (StagePolicy in researchclaw/hitl/config.py at line 28) specify granular interaction parameters like requiring approval, enabling collaboration, or streaming output when a pause occurs.

The CoPilotController.should_pause method (line 34 in researchclaw/copilot/controller.py) evaluates the global flags to determine if a breakpoint triggers, while the HITLConfig.get_stage_policy method retrieves the specific UI behavior for that stage.

Configuring Global Co-Pilot Settings

The CoPilotConfig dataclass supports three mutually exclusive operational modes controlled via the mode field:

Mode	Behavior
zero-touch	Never pauses; runs the full pipeline automatically.
auto-pilot	Pauses only at predefined gate stages when pause_at_gates=True.
co-pilot	Pauses at gate stages, or at every stage if pause_at_every_stage=True.

The controller implements this logic in should_pause:

# researchclaw/copilot/controller.py – L34

def should_pause(self, stage_num: int, is_gate: bool) -> bool:
    if self.mode == ResearchMode.ZERO_TOUCH:
        return False
    if self.mode == ResearchMode.AUTO_PILOT:
        return is_gate and self.config.pause_at_gates
    # CO_PILOT mode

    if self.config.pause_at_every_stage:
        return True
    return is_gate

Configure these values in your rc.yaml file or programmatically via the CoPilotConfig constructor:

# rc.yaml – global co-pilot configuration

copilot:
  mode: co-pilot
  pause_at_gates: true
  pause_at_every_stage: false
  feedback_timeout_sec: 3600

Defining Per-Stage HITL Policies

When should_pause returns True, the Human-In-The-Loop subsystem consults a StagePolicy dataclass (defined at line 28 in researchclaw/hitl/config.py) to render the appropriate UI controls:

# researchclaw/hitl/config.py – L28-L48

@dataclass(frozen=True)
class StagePolicy:
    auto_execute: bool = True
    pause_before: bool = False
    pause_after: bool = False
    require_approval: bool = False
    stream_output: bool = False
    show_llm_calls: bool = False
    allow_edit_output: bool = False
    allow_inject_prompt: bool = False
    enable_collaboration: bool = False
    min_quality_score: float = 0.0

Default Co-Pilot Policies

The _default_policy_for_mode function (line 232 in researchclaw/hitl/config.py) generates baseline policies for the co-pilot intervention mode using predefined stage sets:

# researchclaw/hitl/config.py – L232-L240

if mode == InterventionMode.CO_PILOT:
    return StagePolicy(
        pause_after=stage_num in _COPILOT_PAUSE_AFTER_STAGES,
        require_approval=stage_num in _COPILOT_APPROVAL_STAGES,
        allow_edit_output=True,
        allow_inject_prompt=True,
        enable_collaboration=stage_num in _COPILOT_COLLABORATION_STAGES,
        stream_output=stage_num in _COPILOT_STREAM_STAGES,
    )

These sets (e.g., _COPILOT_APPROVAL_STAGES, _COPILOT_COLLABORATION_STAGES) encode the canonical behavior where critical stages like hypothesis generation (stage 8) require approval and collaborative editing by default.

Overriding Individual Stages

Override defaults by specifying stage numbers under stage_policies in your configuration file. The HITLConfig.get_stage_policy method merges these user-defined values with the baseline defaults:

# rc.yaml – per-stage policy overrides

hitl:
  enabled: true
  mode: co-pilot
  stage_policies:
    8:                           # HYPOTHESIS_GEN stage

      require_approval: true
      enable_collaboration: true
      pause_after: false         # Skip automatic post-stage pause

    12:                          # EXPERIMENT_RUN stage

      stream_output: true        # Show live execution logs

      allow_edit_output: false

Complete Configuration Example

Combine global settings with per-stage overrides to implement a workflow that pauses only at gates globally, but enforces strict approval and collaboration at stage 8 while streaming experiment output at stage 12:

# rc.yaml – full co-pilot implementation

copilot:
  mode: co-pilot
  pause_at_gates: true
  pause_at_every_stage: false
  feedback_timeout_sec: 3600
  allow_branching: true
  max_branches: 5

hitl:
  enabled: true
  mode: co-pilot
  stage_policies:
    8:
      require_approval: true
      enable_collaboration: true
      pause_after: false
    12:
      stream_output: true
      allow_edit_output: false

When the pipeline reaches stage 8, the UI enforces human sign-off and opens a collaboration session before proceeding. At stage 12, the interface streams real-time logs without permitting output modification.

Summary

• Global control resides in CoPilotConfig (researchclaw/config.py, where you set the mode (co-pilot, auto-pilot, or zero-touch) and pause preferences.
• Granular interaction is governed by StagePolicy objects (researchclaw/hitl/config.py, which define approval requirements, collaboration settings, and output streaming per stage.
• Default behaviors for co-pilot mode are generated by _default_policy_for_mode (L232) using canonical stage sets like _COPILOT_APPROVAL_STAGES.
• Customization occurs via the stage_policies dictionary in rc.yaml, where specific stage numbers map to policy overrides that merge with defaults at runtime.

Frequently Asked Questions

What is the difference between co-pilot mode and auto-pilot mode in AutoResearchClaw?

Auto-pilot mode pauses execution only at predefined gate stages, allowing hands-off operation between checkpoints. Co-pilot mode offers finer control, capable of pausing at every stage (when pause_at_every_stage=True) or combining gate pauses with specific per-stage policies that enable collaboration, approval dialogs, and real-time editing. According to the source code in researchclaw/copilot/controller.py, the mode determines the return value of should_pause based on the is_gate parameter and configuration flags.

How do I require human approval only at specific research stages?

Set require_approval: true within the stage_policies configuration for the specific stage numbers requiring oversight. For example, configuring stage 8 with require_approval: true forces the UI to present an approval dialog during the hypothesis generation phase while allowing other stages to execute automatically. This overrides the default behavior defined in _default_policy_for_mode without modifying the global pause strategy.

Can I enable real-time collaboration for some stages but not others?

Yes. Set enable_collaboration: true only for the stages needing multi-user editing capabilities in your stage_policies configuration. The default co-pilot policy enables collaboration only for stages listed in _COPILOT_COLLABORATION_STAGES, but you can extend or restrict this by explicitly setting the flag for specific stage numbers in your rc.yaml file.

Where are the default stage sets (like _COPILOT_APPROVAL_STAGES) defined?

These canonical stage groupings are defined as module-level constants in researchclaw/hitl/config.py (near line 232) and referenced by the _default_policy_for_mode function. While the specific line numbers for these set definitions are not explicitly detailed in the configuration module, they are utilized alongside the preset configurations available in researchclaw/hitl/presets.py (line 12), which provides the copilot_preset convenience configuration.

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