devrites 3.2.20 → 3.2.22

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to DevRites are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and DevRites adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Releases are generated automatically by [semantic-release](https://semantic-release.gitbook.io/) from Conventional Commits on `main`.
 
+## [3.2.22](https://github.com/ViktorsBaikers/DevRites/compare/v3.2.21...v3.2.22) (2026-07-28)
+
+### Fixed
+
+* **devrites:** prevent receipt-only agent spawns ([4cf4c19](https://github.com/ViktorsBaikers/DevRites/commit/4cf4c19cf8671b8fdd497b8875c50bd50faf85d9))
+
+## [3.2.21](https://github.com/ViktorsBaikers/DevRites/compare/v3.2.20...v3.2.21) (2026-07-28)
+
+### Fixed
+
+* **devrites:** bound Codex dispatch stop retries ([4ef9d5b](https://github.com/ViktorsBaikers/DevRites/commit/4ef9d5baf3ca74b1d494f535e8820447e9c37129))
+
 ## [3.2.20](https://github.com/ViktorsBaikers/DevRites/compare/v3.2.19...v3.2.20) (2026-07-28)
 
 ### Fixed

package/README.md

@@ -25,7 +25,7 @@ final commit, push, and tag, and it requires a typed `GO` confirmation.
 Unattended runs may create local WIP checkpoint commits along the way, but only
 Ship collapses and pushes them.
 
-**Status:** [`v3.2.20`](https://github.com/ViktorsBaikers/DevRites/releases/tag/v3.2.20): see [`CHANGELOG.md`](CHANGELOG.md) for release notes.
+**Status:** [`v3.2.22`](https://github.com/ViktorsBaikers/DevRites/releases/tag/v3.2.22): see [`CHANGELOG.md`](CHANGELOG.md) for release notes.
 
 ## Quick start
 

package/engine/hookpolicy.go

@@ -49,6 +49,7 @@ var hookRegistry = map[string]hookDefinition{
 
 	// Standard hooks add the default gates, guards, sentinels, and caches.
 	"a1-guard":          {tier: tierStandard, canBlock: true},
+	"agent-dispatch":    {tier: tierStandard, canBlock: true},
 	"git-guard":         {tier: tierStandard, canBlock: true},
 	"stop-gate":         {tier: tierStandard, canBlock: true},
 	"reviewer-readonly": {tier: tierStandard, canBlock: true},

package/engine/hookpolicy_test.go

@@ -81,6 +81,12 @@ func TestBlockingHookExitAudit(t *testing.T) {
 			bound:     "one block before the host re-enters with stop_hook_active=true",
 			killPath:  "DEVRITES_DISABLED_HOOKS=stop-gate or DEVRITES_HOOK_PROFILE=minimal",
 		},
+		"agent-dispatch": {
+			reentry:   "explicit stop_hook_active=true terminates the re-entered Stop with the same failure",
+			malformed: "missing or malformed event, session, or turn identity fails open",
+			bound:     "one block before the host re-enters with stop_hook_active=true",
+			killPath:  "DEVRITES_DISABLED_HOOKS=agent-dispatch or DEVRITES_HOOK_PROFILE=minimal",
+		},
 		"reviewer-readonly": {
 			reentry:   "not applicable: each PreToolUse decision applies to one tool request",
 			malformed: "missing or malformed tool identity fails open",

package/engine/hooks_agent_dispatch.go

@@ -527,7 +527,7 @@ func durableCodexV2DispatchAttempts(
 		}
 		if !devritesAgentNameRe.MatchString(role) || role == agentDispatchSkillGuard {
 			if strings.TrimSpace(spawn.Result) != "" {
-				return nil, fmt.Errorf("codex V2 completed a default or non-DevRites child during a DevRites skill turn; %s", conditionalDispatchInstruction())
+				return nil, fmt.Errorf("codex V2 completed a default or non-DevRites child during a DevRites skill turn; this turn is tainted and cannot be repaired by another dispatch. Do not use the child result or advance workflow state. End this turn, then retry the skill in a fresh turn; %s", conditionalDispatchInstruction())
 			}
 			continue
 		}
@@ -853,6 +853,10 @@ func conditionalDispatchInstruction() string {
 	return "CONDITIONAL DISPATCH RULE — If this skill reaches a child-agent step, call spawn_agent with the exact named agent_type=devrites-<role> specified by the skill, a unique task_name, and fork_turns=\"none\". GPT-5.6 V2 may omit agent_type from the visible tool schema; send agent_type anyway and never use a default child. Wait for the returned child and use its non-empty result."
 }
 
+func preDispatchStopInstruction() string {
+	return "PRE-DISPATCH STOP RULE — If a deterministic prerequisite forces STOP before any spawn attempt, do not spawn only to satisfy this receipt. Run exactly one successful standalone devrites-engine dispatch-waive <reason> before replying. Use only the matching observed predicate: no-active-workspace, wrong-phase, readiness-failed, no-eligible-work, or human-gate-before-dispatch. The successful PostToolUse receipt is required; never waive after a spawn attempt."
+}
+
 func incompleteDispatchReason(armed map[string]struct{}, attempts []*agentDispatchAttempt) string {
 	roles := make([]string, 0, len(armed))
 	for role := range armed {
@@ -871,7 +875,11 @@ func incompleteDispatchReason(armed map[string]struct{}, attempts []*agentDispat
 	if role == agentDispatchMetadataRole {
 		return "DevRites could not determine this skill's required agents because its installed required-agent-roles contract is invalid. Reinstall or repair the DevRites skill pack before continuing."
 	}
-	return fmt.Sprintf("DevRites dispatch for %s is not complete. %s", role, dispatchInstruction(role))
+	reason := fmt.Sprintf("DevRites dispatch for %s is not complete. %s", role, dispatchInstruction(role))
+	if len(attempts) == 0 {
+		reason += " " + preDispatchStopInstruction()
+	}
+	return reason
 }
 
 func preToolDeny(h harness.Harness, reason string, stdout, stderr io.Writer) int {
@@ -1022,8 +1030,9 @@ func hookAgentDispatch(h harness.Harness, stdin io.Reader, stdout, stderr io.Wri
 			}
 			fmt.Fprintf(
 				stdout,
-				"MANDATORY DISPATCH THIS TURN — At the skill's dispatch step, execute every required child before finishing or claiming completion; a success phrase is not evidence.\n%s",
+				"MANDATORY DISPATCH THIS TURN — At the skill's dispatch step, execute every required child before finishing or claiming completion; a success phrase is not evidence.\n%s\n%s",
 				strings.Join(instructions, "\n"),
+				preDispatchStopInstruction(),
 			)
 		}
 		if skillInvoked {
@@ -1105,7 +1114,11 @@ func hookAgentDispatch(h harness.Harness, stdin io.Reader, stdout, stderr io.Wri
 	case "Stop":
 		events, err := readAgentDispatchEvents(root, in.SessionID)
 		if err != nil {
-			return stopDispatchBlock(h, "DevRites could not verify the required agent dispatch: "+err.Error(), stdout, stderr)
+			reason := "DevRites could not verify the required agent dispatch: " + err.Error()
+			if in.StopHookActive {
+				return stopDispatchFailure(reason, stdout, stderr)
+			}
+			return stopDispatchBlock(h, reason, stdout, stderr)
 		}
 		armed, attempts := dispatchTurnState(events, in.TurnID)
 		_, guarded := armed[agentDispatchSkillGuard]
@@ -1114,7 +1127,11 @@ func hookAgentDispatch(h harness.Harness, stdin io.Reader, stdout, stderr io.Wri
 				root, in.SessionID, in.TurnID, armed,
 			)
 			if durableErr != nil {
-				return stopDispatchBlock(h, "DevRites could not verify the Codex V2 agent dispatch: "+durableErr.Error(), stdout, stderr)
+				reason := "DevRites could not verify the Codex V2 agent dispatch: " + durableErr.Error()
+				if in.StopHookActive {
+					return stopDispatchFailure(reason, stdout, stderr)
+				}
+				return stopDispatchBlock(h, reason, stdout, stderr)
 			}
 			attempts = append(attempts, durable...)
 		}

package/engine/tests/hook_test.go

@@ -6,6 +6,8 @@ package main_test
 
 import (
 	"bytes"
+	"crypto/sha256"
+	"encoding/hex"
 	"encoding/json"
 	"fmt"
 	"os"
@@ -1439,6 +1441,12 @@ func TestCodexAgentDispatchPromptGivesExactNamedCallBeforeCompletion(t *testing.
 		".codex/agents/" + role + ".toml",
 		"send agent_type anyway",
 		"Wait for the returned child",
+		"PRE-DISPATCH STOP RULE",
+		"do not spawn only to satisfy this receipt",
+		"devrites-engine dispatch-waive <reason>",
+		"readiness-failed",
+		"human-gate-before-dispatch",
+		"never waive after a spawn attempt",
 	} {
 		if !strings.Contains(out, want) {
 			t.Fatalf("initial dispatch guidance omitted %q:\n%s", want, out)
@@ -1690,7 +1698,9 @@ func TestCodexAgentDispatchBlocksFalseWaitAndStop(t *testing.T) {
 	if stopDecision.Decision != "block" ||
 		!strings.Contains(stopDecision.Reason, "spawn_agent") ||
 		!strings.Contains(stopDecision.Reason, "visible tool schema") ||
-		!strings.Contains(stopDecision.Reason, "send agent_type anyway") {
+		!strings.Contains(stopDecision.Reason, "send agent_type anyway") ||
+		!strings.Contains(stopDecision.Reason, "do not spawn only to satisfy this receipt") ||
+		!strings.Contains(stopDecision.Reason, "dispatch-waive <reason>") {
 		t.Fatalf("false completion not blocked: %#v", stopDecision)
 	}
 
@@ -1743,7 +1753,7 @@ func TestCodexAgentDispatchRequiresSuccessfulReasonBoundWaiver(t *testing.T) {
 		t.Fatalf("chained waiver was not denied: %s", out)
 	}
 
-	command := "devrites-engine dispatch-waive wrong-phase"
+	command := "devrites-engine dispatch-waive readiness-failed"
 	pre := hookPayload(t, map[string]any{
 		"hook_event_name": "PreToolUse",
 		"session_id":      sessionID,
@@ -1773,7 +1783,7 @@ func TestCodexAgentDispatchRequiresSuccessfulReasonBoundWaiver(t *testing.T) {
 		"turn_id":         turnID,
 		"tool_name":       "functions.exec_command",
 		"tool_input":      map[string]any{"cmd": command},
-		"tool_response":   "dispatch-waive: accepted wrong-phase",
+		"tool_response":   "dispatch-waive: accepted readiness-failed",
 	})
 	if out, stderr, code := runDevritesIO(t, root, post, nil,
 		"hook", "agent-dispatch", "--harness=codex"); code != 0 || strings.TrimSpace(out) != "" {
@@ -1885,6 +1895,7 @@ func TestCodexAgentDispatchConfirmsGenericRoleAndResult(t *testing.T) {
 	}
 	var blocked struct {
 		Decision string `json:"decision"`
+		Reason   string `json:"reason"`
 	}
 	if err := json.Unmarshal([]byte(strings.TrimSpace(out)), &blocked); err != nil {
 		t.Fatalf("invalid unawaited Stop response: %v\n%s", err, out)
@@ -1892,6 +1903,9 @@ func TestCodexAgentDispatchConfirmsGenericRoleAndResult(t *testing.T) {
 	if blocked.Decision != "block" {
 		t.Fatalf("unawaited child result passed Stop: %s", out)
 	}
+	if strings.Contains(blocked.Reason, "dispatch-waive") {
+		t.Fatalf("unavailable post-spawn waiver was suggested: %s", out)
+	}
 
 	wait := hookPayload(t, map[string]any{
 		"hook_event_name": "PreToolUse",
@@ -2142,9 +2156,98 @@ func TestCodexAgentDispatchRejectsConditionalDurableV2DefaultChild(t *testing.T)
 	}
 	if decision.Decision != "block" ||
 		!strings.Contains(decision.Reason, "default or non-DevRites child") ||
+		!strings.Contains(decision.Reason, "cannot be repaired by another dispatch") ||
+		!strings.Contains(decision.Reason, "retry the skill in a fresh turn") ||
 		!strings.Contains(decision.Reason, "never use a default child") {
 		t.Fatalf("conditional V2 default child passed: %#v", decision)
 	}
+
+	stop = hookPayload(t, map[string]any{
+		"hook_event_name":  "Stop",
+		"session_id":       sessionID,
+		"turn_id":          turnID,
+		"stop_hook_active": true,
+	})
+	out, stderr, code = runDevritesIO(t, root, stop,
+		[]string{"CODEX_HOME=" + codeHome},
+		"hook", "agent-dispatch", "--harness=codex")
+	if code != 0 {
+		t.Fatalf("conditional default reentry exit=%d stderr=%s", code, stderr)
+	}
+	var terminal struct {
+		Continue   bool   `json:"continue"`
+		StopReason string `json:"stopReason"`
+	}
+	if err := json.Unmarshal([]byte(strings.TrimSpace(out)), &terminal); err != nil {
+		t.Fatalf("invalid conditional default reentry response: %v\n%s", err, out)
+	}
+	if terminal.Continue ||
+		!strings.Contains(terminal.StopReason, "default or non-DevRites child") ||
+		!strings.Contains(terminal.StopReason, "retry the skill in a fresh turn") {
+		t.Fatalf("conditional V2 default child reentry did not stop: %#v", terminal)
+	}
+}
+
+func TestCodexAgentDispatchTerminatesCorruptStateReentry(t *testing.T) {
+	root := newWorkspace(t)
+	sessionID, turnID := "session-corrupt-state", "turn-corrupt-state"
+
+	runDevritesIO(t, root, hookPayload(t, map[string]any{
+		"hook_event_name": "UserPromptSubmit",
+		"session_id":      sessionID,
+		"turn_id":         turnID,
+		"prompt":          "$rite-status",
+	}), nil, "hook", "agent-dispatch", "--harness=codex")
+
+	resolvedRoot, err := filepath.EvalSymlinks(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	rootSum := sha256.Sum256([]byte(filepath.Clean(resolvedRoot)))
+	sessionSum := sha256.Sum256([]byte(sessionID))
+	statePath := filepath.Join(
+		os.TempDir(),
+		"devrites-agent-dispatch-v1",
+		hex.EncodeToString(rootSum[:]),
+		hex.EncodeToString(sessionSum[:])+".jsonl",
+	)
+	if err := os.MkdirAll(filepath.Dir(statePath), 0o700); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(statePath, []byte("not-json\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+
+	stop := func(active bool) string {
+		out, stderr, code := runDevritesIO(t, root, hookPayload(t, map[string]any{
+			"hook_event_name":  "Stop",
+			"session_id":       sessionID,
+			"turn_id":          turnID,
+			"stop_hook_active": active,
+		}), nil, "hook", "agent-dispatch", "--harness=codex")
+		if code != 0 {
+			t.Fatalf("corrupt state stop active=%t exit=%d stderr=%s", active, code, stderr)
+		}
+		return out
+	}
+
+	var blocked struct {
+		Decision string `json:"decision"`
+	}
+	if out := stop(false); json.Unmarshal([]byte(strings.TrimSpace(out)), &blocked) != nil ||
+		blocked.Decision != "block" {
+		t.Fatalf("corrupt state first Stop did not block: %s", out)
+	}
+
+	var terminal struct {
+		Continue   bool   `json:"continue"`
+		StopReason string `json:"stopReason"`
+	}
+	if out := stop(true); json.Unmarshal([]byte(strings.TrimSpace(out)), &terminal) != nil ||
+		terminal.Continue ||
+		!strings.Contains(terminal.StopReason, "invalid agent dispatch state") {
+		t.Fatalf("corrupt state reentry did not stop: %s", out)
+	}
 }
 
 func TestCodexAgentDispatchRejectsIncompleteDurableV2(t *testing.T) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devrites",
-  "version": "3.2.20",
+  "version": "3.2.22",
   "description": "DevRites: a disciplined senior-engineer workflow pack for Claude Code and Codex",
   "license": "SEE LICENSE IN LICENSE",
   "homepage": "https://github.com/ViktorsBaikers/DevRites#readme",