Description
The aidlc-stop.ts hook fires a blocking error ("The AIDLC workflow has a pending step") when the conductor has legitimately dispatched a background subagent via the Agent() tool and is waiting for its completion notification. The conductor CANNOT report the stage result until the subagent returns — but the stop hook doesn't recognize this in-flight async state.
This creates a confusing UX: the user sees a blocking error telling them to "run next" or "park", but neither action is appropriate — the conductor is correctly waiting for work to complete.
Steps to Reproduce
- Start an AI-DLC workflow on Claude Code
- Reach a
mode: subagent stage (e.g., reverse-engineering or code-generation) OR any stage where the conductor dispatches Agent() with run_in_background: true
- The conductor launches the background agent and outputs "waiting for completion"
- Before the background agent returns, the stop hook fires
- Observe: blocking error "The AIDLC workflow has a pending step (a run-stage directive for X). You haven't finished the forwarding loop yet."
Expected Behavior
The stop hook should recognize that a background agent is in-flight and NOT block. Possible approaches:
- Check for a
.aidlc-agent-inflight marker file (set by conductor before Agent dispatch, cleared on notification)
- Simply suppress the hook when the conductor's last output mentions "waiting for" or "background agent"
- Add a timeout: only fire if the pending step has been idle for >5 minutes with no background work
Actual Behavior
The stop hook fires immediately, producing a confusing error that tells the user to report or park — neither of which is valid while a subagent is running. The conductor correctly continues waiting anyway (the hook is blocking-advisory, not truly blocking execution), but the error message clutters the UX and confuses users.
AI-DLC Version
v2 (alpha)
Release / Commit
Latest (installed via .claude/ workspace shell, July 2026)
AI-DLC Phase
Not phase-specific — happens on any stage that dispatches a background Agent().
Observed specifically during:
- Stage 2.1 Reverse Engineering (subagent mode, aidlc-developer-agent)
- Stage 2.3 Requirements Analysis (inline mode but with background Agent for artifact generation)
Platform / IDE
Claude Code
AI Model
global.anthropic.claude-opus-4-6-v1[1m] (Opus 4.6, 1M context)
Environment
- OS: macOS Sequoia (Darwin 25.5.0)
- Shell: zsh
- Terminal: Warp
- Claude Code: latest
Additional Context
The stop hook at .claude/hooks/aidlc-stop.ts checks aidlc-state.md for an in-progress stage and fires if it finds one. It has no awareness of whether the conductor is actively waiting for a subagent or is genuinely idle/stuck.
The hook's guard condition needs to include: "AND no background agent is in-flight" — which requires either a marker file protocol or a query to the Claude Code task system.
Description
The
aidlc-stop.tshook fires a blocking error ("The AIDLC workflow has a pending step") when the conductor has legitimately dispatched a background subagent via theAgent()tool and is waiting for its completion notification. The conductor CANNOT report the stage result until the subagent returns — but the stop hook doesn't recognize this in-flight async state.This creates a confusing UX: the user sees a blocking error telling them to "run next" or "park", but neither action is appropriate — the conductor is correctly waiting for work to complete.
Steps to Reproduce
mode: subagentstage (e.g.,reverse-engineeringorcode-generation) OR any stage where the conductor dispatchesAgent()withrun_in_background: trueExpected Behavior
The stop hook should recognize that a background agent is in-flight and NOT block. Possible approaches:
.aidlc-agent-inflightmarker file (set by conductor before Agent dispatch, cleared on notification)Actual Behavior
The stop hook fires immediately, producing a confusing error that tells the user to
reportorpark— neither of which is valid while a subagent is running. The conductor correctly continues waiting anyway (the hook is blocking-advisory, not truly blocking execution), but the error message clutters the UX and confuses users.AI-DLC Version
v2 (alpha)
Release / Commit
Latest (installed via
.claude/workspace shell, July 2026)AI-DLC Phase
Not phase-specific — happens on any stage that dispatches a background Agent().
Observed specifically during:
Platform / IDE
Claude Code
AI Model
global.anthropic.claude-opus-4-6-v1[1m] (Opus 4.6, 1M context)
Environment
Additional Context
The stop hook at
.claude/hooks/aidlc-stop.tschecksaidlc-state.mdfor an in-progress stage and fires if it finds one. It has no awareness of whether the conductor is actively waiting for a subagent or is genuinely idle/stuck.The hook's guard condition needs to include: "AND no background agent is in-flight" — which requires either a marker file protocol or a query to the Claude Code task system.