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

> Master customizing per stage policies in AutoResearchClaw's co-pilot mode. Configure CoPilotConfig and StagePolicy for granular human-in-the-loop controls and optimize your 23-step pipeline. Get the complete guide.

- Repository: [AIMING Lab/AutoResearchClaw](https://github.com/aiming-lab/AutoResearchClaw)
- Tags: how-to-guide
- Published: 2026-05-28

---

**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`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/researchclaw/config.py) and [`researchclaw/hitl/config.py`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/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`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/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`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/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`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/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`:

```python

# 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`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/rc.yaml) file or programmatically via the `CoPilotConfig` constructor:

```yaml

# 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`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/researchclaw/hitl/config.py)) to render the appropriate UI controls:

```python

# 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`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/researchclaw/hitl/config.py)) generates baseline policies for the `co-pilot` intervention mode using predefined stage sets:

```python

# 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:

```yaml

# 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:

```yaml

# 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`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/researchclaw/config.py#L792), 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`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/researchclaw/hitl/config.py#L28), 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`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/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`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/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`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/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`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/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`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/researchclaw/hitl/presets.py) (line 12), which provides the `copilot_preset` convenience configuration.