devrites 3.2.20 → 3.2.21

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 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.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.21`](https://github.com/ViktorsBaikers/DevRites/releases/tag/v3.2.21): 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
 		}
@@ -1105,7 +1105,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 +1118,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"
@@ -2142,9 +2144,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.21",
   "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",