Auto-inject rigor profile into sub-agents via SubagentStart hook

[11PJ11]

Problem

The rigor profile is currently injected manually — each wave command file must explicitly read .nwave/des-config.json and pass model=rigor_agent_model to the Task tool. If a command file doesn't follow the instructions, or an agent is dispatched non-standardly, rigor is silently ignored.

Solution

Use the SubagentStart hook with additionalContext to automatically inject the active rigor profile into every sub-agent's context at spawn time.

{
  "hooks": {
    "SubagentStart": [{
      "hooks": [{
        "type": "command",
        "command": "PYTHONPATH=$HOME/.claude/lib/python python3 -m des.adapters.drivers.hooks.claude_code_hook_adapter subagent-start"
      }]
    }]
  }
}

The hook reads .nwave/des-config.json and returns:

{
  "additionalContext": "Active rigor profile: thorough. agent_model: opus, reviewer_model: sonnet, tdd_phases: 5-phase, review_enabled: true, double_review: true, mutation_enabled: false."
}

Benefits

• Zero dependency on command file instructions
• Applied universally to all sub-agents without exceptions
• Rigor profile becomes a first-class session-wide concern
• Command files can be simplified (no need to manually read config)

---

This issue was created by Claude (Opus 4.6), the AI assistant powering this project's development workflow.

[11PJ11]

Thank you @11PJ11 — three solid suggestions in a row, we appreciate the engagement.

We've investigated this extensively. The SubagentStart hook type in Claude Code has a documented reliability issue — our testing shows a ~42% failure rate (tracked upstream in anthropics/claude-code#27755, #27423, #27153).

Our SubagentStart hook code is correct, but Claude Code intermittently fails to fire the event. Until the upstream fix lands, we can't reliably inject rigor profiles this way.

Current workaround: Agent definitions include imperative skill-loading instructions that read the rigor profile directly.

Status: Blocked on upstream Claude Code fix. We're monitoring the linked issues and will implement auto-injection once SubagentStart reliability improves.

— nwave.ai

[JiwaniZakir]

The core problem is that rigor injection relies on convention rather than enforcement — any agent dispatch path that doesn't explicitly follow the "read config → pass model param" pattern silently falls through with no rigor applied. The SubagentStart hook approach is the right architectural fix here since it moves the injection out of the call-site layer and into the runtime layer, making it impossible to bypass accidentally. Worth noting that additionalContext is injected as natural language context rather than a structured system prompt override, so sub-agents will parse/interpret it rather than having it enforced at the API level — this should still be reliable for well-prompted agents, but it's a softer guarantee than a direct model parameter. The relevant enforcement gap lives in whatever dispatch abstraction currently wraps the Task tool calls, likely in the wave command execution layer.

[11PJ11]

@JiwaniZakir Thanks for the thoughtful analysis — you've nailed the key architectural tension here. You're right that additionalContext is a softer guarantee than a direct API-level enforcement, and that the real gap is in the dispatch layer.

The good news is that the next major version of nWave introduces a new engine architecture that resolves this at the source — rigor profiles will be enforced structurally at the dispatch level rather than relying on convention or hook injection. This makes the SubagentStart workaround unnecessary altogether.

We'll update this issue when the new version ships. Thanks again for the detailed feedback!

[JiwaniZakir]

The skill-scoped hook approach @DevOpsCraftsman linked is worth prototyping — if the hook only activates when the nWave skill is loaded, it sidesteps the reliability concerns with globally registered SubagentStart hooks and keeps the injection contained to intentional nWave sessions. The tradeoff is that agents spawned outside the skill context still won't inherit the rigor profile, but that's arguably the correct behavior anyway. Worth testing whether additionalContext from a skill-scoped hook persists reliably into nested sub-agents, since that's where the 42% failure rate was observed in the global case.