Summary

• Problem: Claude Agent SDK's SDKResultSuccess declares is_error: boolean (not literal false). Stop_sequence terminations carry is_error: true + subtype: 'success' — the SDK's encoding of "non-default termination, but not a failure". The claude provider forwarded this to MessageChunk.isError verbatim, so three downstream consumers (dag-executor main, dag-executor loop, orchestrator-agent direct chat) misclassified clean terminations as node failures with the contradictory user-hostile error "Node '<X>' failed: SDK returned success" — even though the AI had completed correctly and written its output.
• Why it matters: Three reporters across v0.3.9 and v0.3.11 (latest 2026-05-13). Review-classify and synthesis pipelines, plus loop-back wrapper workflows, hard-fail and skip downstream trigger-rule joins (synthesize, self-fix, simplify, report). Users blocked unless they fork+patch+rebuild; archon's workflow schema does not expose stop_sequences and disabling output_format would break downstream when: conditions.
• What changed: Provider boundary normalises is_error: true + subtype: 'success' as a clean success — no isError propagation downstream; debug-level claude.result_success_stop_sequence log preserves observability. Defense-in-depth errorSubtype !== 'success' guards added to dag-executor.ts main path and loop branch so a future third-party IAgentProvider forwarding the SDK pair raw can't reintroduce the bug. Regression tests for provider, DAG main, DAG loop, and orchestrator direct chat; guard test ensures real error subtypes (error_max_turns) still propagate.
• What did NOT change (scope boundary): No change to MessageChunk type shape in packages/providers/src/types.ts (contract semantics tighten, type signature unchanged). No change to Codex turn.failed path (Bug A in the issue is already resolved by commit 4c6ddd99 + the current Codex turn.failed handler at codex/provider.ts:235-247). No change to orchestrator-agent.ts code (the provider-level fix covers direct chat transparently). No retry/auth-precheck behavioural improvements. No touch on related but separate bugs fix: interactive loop resume crashes with error_during_execution (stale session) #1208, bug(codex): retry loop reuses caller AbortSignal; crash on attempt N poisons attempt N+1 #1266.

UX Journey

Before

User                          Archon                                Claude SDK
────                          ──────                                ──────────
runs workflow with        ──▶  classify node executes
output_format: json_schema     SDK returns {is_error: true,
(implies stop_sequence)        subtype: 'success',
                               stop_reason: 'stop_sequence'}  ◀──── completes via stop sequence
                               provider forwards isError verbatim
                               dag-executor.ts:921 throws:
                                 "Node 'classify' failed:
                                  SDK returned success"
                               workflow exits with failure
                               trigger-rule joins skip
                               (synthesize/self-fix/simplify/report)
sees ❌ on a run whose  ◀──── output was written to disk;
classify output is valid       review pipeline produces nothing

After

User                          Archon                                Claude SDK
────                          ──────                                ──────────
runs workflow with        ──▶  classify node executes
output_format: json_schema     SDK returns {is_error: true,
                               subtype: 'success',
                               stop_reason: 'stop_sequence'}  ◀──── completes via stop sequence
                               [+] provider normalises:
                                   is_error + 'success' subtype
                                   ⇒ clean result, no isError
                                   [+] debug log: claude.result_success_stop_sequence
                               dag-executor.ts:921 guard:
                                   `isError && errorSubtype !== 'success'` ⇒ skip throw
                               node completes normally
                               trigger-rule joins fire
                               downstream nodes run on real output
sees ✅ classify output      ◀── review pipeline writes findings

Architecture Diagram

Before

@archon/providers
└── claude/provider.ts
    └── result handler: forwards SDK is_error verbatim
        ──▶ MessageChunk { isError: true, errorSubtype: 'success' }
                                            │
                                            ▼
@archon/workflows                @archon/core
├── dag-executor.ts              orchestrator-agent.ts
│   ├── main path:921             ├── handleStreamMode:1142
│   │   throws unconditionally    │   sends classifyAndFormatError("success")
│   │   on isError                │
│   └── loop branch:1947          └── handleBatchMode:1298
│       same throw                    same surface

After

@archon/providers
└── claude/provider.ts
    [~] result handler: normalises is_error + subtype: 'success'
        ──▶ MessageChunk { /* no isError when subtype === 'success' */ }
            [+] debug log: claude.result_success_stop_sequence
                                            │
                                            ▼
@archon/workflows                @archon/core
├── dag-executor.ts              orchestrator-agent.ts
│   ├── main path:921             ├── handleStreamMode:1142
│   │   [~] && errorSubtype       │   transparently fixed (chunk clean)
│   │       !== 'success'         │
│   └── loop branch:1947          └── handleBatchMode:1298
│       [~] same carve-out            transparently fixed (chunk clean)

Connection inventory:

Label Snapshot

• Risk: risk: low
• Size: size: S
• Scope: workflows, core (tests)
• Module: providers:claude, workflows:executor, core:orchestrator (test)

Change Metadata

• Change type: bug
• Primary scope: multi (providers + workflows + core tests)

Linked Issue

• Closes bug(workflow): two silent-failure paths in DAG executor — Codex turn.failed exits stream, Claude success-with-stop-sequence thrown as failure #1425
• Related: fix: interactive loop resume crashes with error_during_execution (stale session) #1208 (parent fix this regression rode on top of), bug(codex): retry loop reuses caller AbortSignal; crash on attempt N poisons attempt N+1 #1266 (separate Codex AbortSignal bug — not addressed), feat(workflows): add execution-evidence contract with terminal-success gate #1601 (broader evidence-contract PR — orthogonal)
• Depends on: none
• Supersedes: none

Validation Evidence (required)

bun run validate   # ✅ exit 0

All six gates green on first invocation (after one prettier auto-format pass on the new provider test):

• check:bundled — bundled-defaults.generated.ts is up to date (36 commands, 20 workflows)
• check:bundled-skill — bundled-skill.ts is up to date (21 files)
• type-check — all 10 packages exit 0
• lint — 0 errors, 0 warnings
• format:check — all files Prettier-clean
• test — all per-package suites pass; new tests:
  • @archon/providers claude/provider.test.ts: +1 test (success-via-stop-sequence) → 26 → 27 in sendQuery decomposition behaviors
  • @archon/workflows dag-executor.test.ts: +2 tests (DAG main + loop branch) → 218 in the test file
  • @archon/core orchestrator-agent.test.ts: +1 test (direct chat contract) → 116 → 117

Skipped commands: none.

Security Impact (required)

• New permissions/capabilities? No — only changes the conditional emission of an existing field on an existing chunk type, and a log level for one event.
• New external network calls? No.
• Secrets/tokens handling changed? No.
• File system access scope changed? No.
• Risk and mitigation: n/a.

Compatibility / Migration

• Backward compatible? Yes — workflows that previously failed with "SDK returned success" will now complete cleanly. No workflow YAML changes required. Workflows that produced real errors (e.g. error_max_turns, error_during_execution, error_max_budget_usd) continue to fail loudly; the guard is subtype-scoped to 'success' only.
• Config/env changes? No.
• Database migration needed? No.
• Upgrade steps: none.

Human Verification (required)

• Verified scenarios:
  • bun run validate exits 0 on a clean checkout of this branch (after one prettier auto-format on the new test).
  • Individual per-package test runs: provider 74 pass, workflows dag-executor 218 pass, core orchestrator-agent 117 pass.
  • SDK type signature personally inspected at @anthropic-ai/claude-agent-sdk@0.2.121/sdk.d.ts:3117-3158 — SDKResultSuccess.is_error: boolean (not literal false), confirming the bug mechanism described in the investigation artifact.
  • Provider's else if (resultMsg.is_error === true && resultMsg.subtype === 'success') branch verified to fire on the new test case (asserted via not.toHaveBeenCalledWith(..., 'claude.result_is_error')).
• Edge cases checked:
  • Real error subtype (error_max_turns) still propagates isError: true and fires the claude.result_is_error error log — guarded by the existing test at provider.test.ts:1223 which continues to pass.
  • Codex provider's turn.failed path (codex/provider.ts:235-247) audited — emits errorSubtype: 'codex_turn_failed', never 'success'. Unaffected.
  • Pi provider's event-bridge.ts:160,164,173 audited — emits 'missing_assistant_message' or last.stopReason ∈ {'error','aborted'}, never 'success'. Unaffected.
  • Empty-output guard at dag-executor.ts:1126 audited — still triggers if any node produces zero output AND no structured output. Defence-in-depth for Bug A (issue bug(workflow): two silent-failure paths in DAG executor — Codex turn.failed exits stream, Claude success-with-stop-sequence thrown as failure #1425) remains intact.
• What was not verified:
  • End-to-end live run against archon-fix-github-issue on a real Claude output_format: json_schema node. The unit tests synthesise the exact (is_error, subtype, stop_reason) triple the SDK emits in this case, so behavioural coverage is equivalent.
  • Behaviour on Claude Agent SDK versions older than 0.2.121. The SDKResultSuccess.is_error: boolean type signature has been stable across the 0.2.x line (verified in 0.2.74 and 0.2.89 lockfile entries).

Side Effects / Blast Radius (required)

• Affected subsystems:
  • @archon/providers — Claude provider only. Codex/Pi unaffected.
  • @archon/workflows — DAG executor's main and loop branches only.
  • @archon/core — orchestrator direct chat transparently fixed; no code change to orchestrator-agent.ts.
• Potential unintended effects:
  • Stop_sequence-terminated runs that previously failed loudly with "SDK returned success" will now complete. This is the intended behaviour, but operators who monitored those failures as alerts will see them disappear. Logs preserve a debug-level claude.result_success_stop_sequence event for ops dashboards.
  • The claude.result_is_error error-level log no longer fires for subtype === 'success'. The new debug event is a clean replacement.
• Guardrails / monitoring for early detection:
  • claude.result_success_stop_sequence log (debug) shows where the new code path fires.
  • claude.result_is_error log (error) continues to fire for genuine error subtypes — alert on this if a real regression slips through.
  • Type-check + lint + format catch any author misuse of the guard pattern at change time.

Rollback Plan (required)

• Fast rollback path: git revert <merge-commit-sha> && git push origin dev — single commit, additive only. Reverting restores the pre-PR throw behaviour on stop_sequence terminations (re-introducing bug(workflow): two silent-failure paths in DAG executor — Codex turn.failed exits stream, Claude success-with-stop-sequence thrown as failure #1425's bug for affected users).
• Feature flags / config toggles: None. The fix is unconditional and non-configurable — there's no scenario in which surfacing subtype === 'success' as a failure is correct.
• Observable failure symptoms post-merge:
  • If a user reports a workflow that completes when it should fail: check claude.result_is_error logs — should fire for real errors.
  • If a user reports the original bug(workflow): two silent-failure paths in DAG executor — Codex turn.failed exits stream, Claude success-with-stop-sequence thrown as failure #1425 symptom returning: check the new && msg.errorSubtype !== 'success' guards in dag-executor.ts lines ~915 and ~1940 are still present; check claude/provider.ts:807-826 isRealError derivation is intact.

Risks and Mitigations

• Risk: The provider's success normalisation hides a future SDK regression where subtype: 'success' actually does indicate a failure.
  • Mitigation: Very unlikely given the SDK's explicit discriminated union (SDKResultMessage = SDKResultSuccess | SDKResultError) and the error_* subtype enum. If the SDK ever changes semantics, the executor's defense-in-depth guard would still emit a less-confusing error (the node would complete rather than throw with a contradictory message). The guard scope is subtype-equality on the string literal 'success', not a broader pattern.
• Risk: A third-party IAgentProvider implementation copies the SDK pattern and starts emitting isError: true, errorSubtype: 'success'.
  • Mitigation: Defense-in-depth guards at dag-executor.ts:915 and :1940 already cover this — the executor will not throw on such a chunk regardless of which provider emitted it.

Investigation artifact: .claude/PRPs/issues/issue-1425.md (local-only, gitignored per repo policy)

Summary by CodeRabbit

• Bug Fixes

  • Claude stop-sequence terminations that indicate clean completion are no longer misclassified as errors; sessions persist and no false error messages are shown.

• Tests

  • Added regression tests across provider, orchestrator, and workflow layers to prevent reintroduction of the misclassification and ensure workflows complete correctly.