devrites 3.2.8 → 3.2.10

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.10](https://github.com/ViktorsBaikers/DevRites/compare/v3.2.9...v3.2.10) (2026-07-26)
+
+### Fixed
+
+* **devrites:** allow external dispatch scratch ([fdaac3f](https://github.com/ViktorsBaikers/DevRites/commit/fdaac3f9aaf19af897c6d3d70ce01fc046a60d3e))
+
+## [3.2.9](https://github.com/ViktorsBaikers/DevRites/compare/v3.2.8...v3.2.9) (2026-07-26)
+
+### Fixed
+
+* **devrites:** unblock retained reconcile checks ([c1093b0](https://github.com/ViktorsBaikers/DevRites/commit/c1093b00c3e32ba3cc22e0b9a2da548618ead621))
+
 ## [3.2.8](https://github.com/ViktorsBaikers/DevRites/compare/v3.2.7...v3.2.8) (2026-07-26)
 
 ### 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.8`](https://github.com/ViktorsBaikers/DevRites/releases/tag/v3.2.8): see [`CHANGELOG.md`](CHANGELOG.md) for release notes.
+**Status:** [`v3.2.10`](https://github.com/ViktorsBaikers/DevRites/releases/tag/v3.2.10): see [`CHANGELOG.md`](CHANGELOG.md) for release notes.
 
 ## Quick start
 

package/docs/orchestration.md

@@ -69,6 +69,16 @@ Each dispatch follows the retained-baseline sequence:
 5. After proof and decision checks pass, `reconcile close` retires the private
    window; only then does the root write canonical records.
 
+An ordinary `reconcile check` may revalidate an existing retained window
+without a fresh current-turn wright receipt; it does not retire or widen that
+window. `reconcile close` still requires the confirmed, awaited wright result
+bound to the active snapshot. While the window is armed, the root guard permits
+inspectable writes only under `.devrites` or at an absolute scratch path outside
+the project; source-tree writes, relative escapes, and opaque execution remain
+blocked. The standalone A1 hook and wright-scope hook share this classification;
+Codex `cmd` and Claude `command` payloads may create a literal external packet
+with a patch, heredoc, or copy and may hash it without gaining source authority.
+
 The canonical-state fingerprint excludes root-owned operational records:
 `timeline.jsonl`, feature `events.jsonl`, a valid `recovery-attempts.jsonl`,
 the redwatch sentinel, automatic handoff snapshots, and hidden hook observation

package/engine/hooks.go

@@ -377,7 +377,7 @@ func safeReadonlyShellSegment(segment string) bool {
 		"grep", "rg", "wc", "sort", "uniq", "cut", "tr", "stat", "file",
 		"readlink", "realpath", "basename", "dirname", "cmp", "diff", "jq", "yq",
 		"tree", "du", "df", "printenv", "which", "date", "uname", "id", "whoami",
-		"ps", "echo", "printf", "test", "[", "cd":
+		"ps", "echo", "printf", "test", "[", "cd", "sha256sum", "shasum":
 		return true
 	case "find":
 		return !hasAnyArg(args, "-delete", "-exec", "-execdir", "-ok", "-okdir", "-fprint", "-fprintf")

package/engine/hooks_agent_dispatch.go

@@ -33,7 +33,7 @@ var (
 	devritesAgentPathRe = regexp.MustCompile(`\.codex/agents/(devrites-[a-z0-9-]+)\.toml`)
 	devritesAgentNameRe = regexp.MustCompile(`^devrites-[a-z0-9-]+$`)
 	skillInvocationRe   = regexp.MustCompile(`(?i)(?:^|[^a-z0-9_./-])(?:\$|/)([a-z][a-z0-9-]*)\b`)
-	reconcileTerminalRe = regexp.MustCompile(`(?m)(?:^|[;&|]\s*)(?:rtk\s+)?(?:[A-Za-z0-9_./-]+/)?devrites-engine\s+reconcile\s+(?:check|close)\b`)
+	reconcileCloseRe    = regexp.MustCompile(`(?m)(?:^|[;&|]\s*)(?:rtk\s+)?(?:[A-Za-z0-9_./-]+/)?devrites-engine\s+reconcile\s+close\b`)
 )
 
 type agentDispatchHookInput struct {
@@ -1163,7 +1163,7 @@ func hookAgentDispatchPreTool(h harness.Harness, root string, in agentDispatchHo
 		return exitOK
 	}
 
-	if isShellTool(in.ToolName) && reconcileTerminalRe.MatchString(in.ToolInput.Command) {
+	if isShellTool(in.ToolName) && reconcileCloseRe.MatchString(in.ToolInput.Command) {
 		windowID := currentReconcileWindowID()
 		if windowID == "" {
 			return exitOK
@@ -1177,7 +1177,7 @@ func hookAgentDispatchPreTool(h harness.Harness, root string, in agentDispatchHo
 			}
 			attempts = append(attempts, durable...)
 			if !roleSatisfied("devrites-slice-wright", windowID, attempts) {
-				return preToolDeny(h, "DevRites reconcile check/close requires a confirmed, awaited devrites-slice-wright result bound to the active reconcile snapshot.", stdout, stderr)
+				return preToolDeny(h, "DevRites reconcile close requires a confirmed, awaited devrites-slice-wright result bound to the active reconcile snapshot.", stdout, stderr)
 			}
 			for _, attempt := range durable {
 				if attempt.Role != "devrites-slice-wright" || attempt.WindowID != windowID ||

package/engine/hooks_workspace.go

@@ -325,6 +325,8 @@ func redwatchSafe(cmd string) string {
 // node regex the shell guards use.
 var patchPathRe = regexp.MustCompile(`(?m)^\*\*\* (?:(?:Add|Update|Delete) File|Move to): (.+)$`)
 
+var shellHeredocStartRe = regexp.MustCompile(`<<(-?)[ \t]*(?:'([A-Za-z_][A-Za-z0-9_]*)'|"([A-Za-z_][A-Za-z0-9_]*)"|([A-Za-z_][A-Za-z0-9_]*))`)
+
 // isEditTool reports whether a tool can write source. toolBaseName also handles
 // host-qualified names such as functions.apply_patch and MCP symbol editors.
 func isEditTool(tool string) bool {
@@ -346,6 +348,39 @@ func patchPaths(command string) []string {
 	return paths
 }
 
+func stripShellHeredocBodies(command string) (string, bool) {
+	lines := strings.Split(strings.ReplaceAll(command, "\r\n", "\n"), "\n")
+	out := make([]string, 0, len(lines))
+	for i := 0; i < len(lines); i++ {
+		line := lines[i]
+		out = append(out, line)
+		for _, match := range shellHeredocStartRe.FindAllStringSubmatch(line, -1) {
+			delimiter := match[2]
+			if delimiter == "" {
+				delimiter = match[3]
+			}
+			if delimiter == "" {
+				return "", false
+			}
+			found := false
+			for i++; i < len(lines); i++ {
+				candidate := lines[i]
+				if match[1] == "-" {
+					candidate = strings.TrimLeft(candidate, "\t")
+				}
+				if candidate == delimiter {
+					found = true
+					break
+				}
+			}
+			if !found {
+				return "", false
+			}
+		}
+	}
+	return strings.Join(out, "\n"), true
+}
+
 // shellOutputRedirections removes harmless fd redirects and returns every file
 // target of >, >>, or >|. Dynamic targets are opaque and therefore unsafe.
 func shellOutputRedirections(command string) (sanitized string, paths []string, opaque bool) {
@@ -471,44 +506,13 @@ func hookA1Guard(h harness.Harness, stdin io.Reader, stdout, stderr io.Writer) i
 	}
 
 	in := h.ParseGuardInput(bytes.NewReader(data))
-	if !isEditTool(in.ToolName) {
-		return exitOK
-	}
 	// The wright may edit. Claude sends agent_id; Codex sends agent_type.
 	if in.AgentID != "" || in.AgentType != "" {
 		return exitOK
 	}
-
-	projectDir := filepath.Dir(root)
-	target := ""
-	if in.ToolName == "apply_patch" {
-		sourcePatch := false
-		for _, p := range patchPaths(in.Command) {
-			abs := p
-			if !filepath.IsAbs(abs) {
-				abs = filepath.Join(projectDir, abs)
-			}
-			if !underDevrites(abs, root) {
-				sourcePatch = true
-				break
-			}
-		}
-		if !sourcePatch {
-			return exitOK
-		}
-		target = "apply_patch"
-	} else {
-		if in.FilePath == "" {
-			return exitOK
-		}
-		abs := in.FilePath
-		if !filepath.IsAbs(abs) {
-			abs = filepath.Join(projectDir, abs)
-		}
-		if underDevrites(abs, root) {
-			return exitOK // orchestrator editing its own .devrites bookkeeping
-		}
-		target = abs
+	handled, violation, target := classifyRootBuildWindowOperation(root, data, in)
+	if !handled || !violation {
+		return exitOK
 	}
 
 	mode := os.Getenv("DEVRITES_A1_HOOK")
@@ -842,7 +846,11 @@ func uniqueStrings(values []string) []string {
 }
 
 func wrightShellWritePaths(command string) ([]string, bool) {
-	if strings.TrimSpace(command) == "" || wrightForbiddenShellRe.MatchString(command) {
+	patches := patchPaths(command)
+	var ok bool
+	command, ok = stripShellHeredocBodies(command)
+	if !ok || strings.TrimSpace(command) == "" || strings.Contains(command, "$(") ||
+		strings.ContainsRune(command, '`') || wrightForbiddenShellRe.MatchString(command) {
 		return nil, true
 	}
 	sanitized, paths, opaque := shellOutputRedirections(command)
@@ -850,7 +858,6 @@ func wrightShellWritePaths(command string) ([]string, bool) {
 		return nil, true
 	}
 
-	patches := patchPaths(command)
 	if strings.Contains(command, "apply_patch") {
 		if len(patches) == 0 {
 			return nil, true
@@ -896,6 +903,15 @@ func wrightShellWritePaths(command string) ([]string, bool) {
 			found = nonFlagArgs(args)
 		case "rm", "unlink", "touch", "mkdir", "rmdir", "truncate":
 			found = nonFlagArgs(args)
+		case "cp":
+			if hasAnyArg(args, "-t", "--target-directory") || hasArgPrefix(args, "--target-directory=") {
+				return nil, true
+			}
+			operands := nonFlagArgs(args)
+			if len(operands) < 2 {
+				return nil, true
+			}
+			found = operands[len(operands)-1:]
 		default:
 			return nil, true
 		}
@@ -1014,36 +1030,50 @@ func guardRootBuildWindow(h harness.Harness, data []byte, in harness.GuardInput,
 		return exitOK, false
 	}
 
-	if isAgentDispatchTool(in.ToolName) {
-		return exitOK, true
+	handled, violation, _ := classifyRootBuildWindowOperation(root, data, in)
+	if violation {
+		return denyWright(h, stdout, stderr, a1DenyReason, drvreason.HookA1Denied), true
 	}
+	return exitOK, handled
+}
 
-	projectDir := filepath.Dir(root)
+func classifyRootBuildWindowOperation(root string, data []byte, in harness.GuardInput) (handled, violation bool, target string) {
+	if isAgentDispatchTool(in.ToolName) {
+		return true, false, ""
+	}
 	if isOpaqueExecutionTool(in.ToolName) {
-		return denyWright(h, stdout, stderr, a1DenyReason, drvreason.HookA1Denied), true
+		return true, true, in.ToolName
 	}
+
+	projectDir := filepath.Dir(root)
 	targets, suspicious := rootMutationTargets(data, in)
 	for _, target := range targets {
+		absoluteTarget := filepath.IsAbs(target)
 		abs := target
-		if !filepath.IsAbs(abs) {
+		if !absoluteTarget {
 			abs = filepath.Join(projectDir, abs)
 		}
 		abs = filepath.Clean(abs)
 		resolved, err := resolveRootMutationTarget(abs)
 		if err != nil {
-			return denyWright(h, stdout, stderr, a1DenyReason, drvreason.HookA1Denied), true
+			return true, true, target
 		}
-		if !underDevrites(resolved, root) {
-			return denyWright(h, stdout, stderr, a1DenyReason, drvreason.HookA1Denied), true
+		insideProject := pathWithin(resolved, projectDir)
+		if (insideProject && !underDevrites(resolved, root)) ||
+			(!insideProject && !absoluteTarget) {
+			return true, true, target
 		}
 	}
 	if suspicious {
-		return denyWright(h, stdout, stderr, a1DenyReason, drvreason.HookA1Denied), true
+		return true, true, in.ToolName
 	}
 	if len(targets) > 0 {
-		return exitOK, true
+		return true, false, strings.Join(targets, ",")
+	}
+	if isShellTool(in.ToolName) && safeReadonlyShellCommand(in.Command) {
+		return true, false, ""
 	}
-	return exitOK, false
+	return false, false, ""
 }
 
 func resolveRootMutationTarget(filename string) (string, error) {
@@ -1071,7 +1101,8 @@ func rootMutationTargets(data []byte, in harness.GuardInput) ([]string, bool) {
 		if len(targets) > 0 {
 			return targets, false
 		}
-		return nil, opaque && (reviewerMutateRe.MatchString(in.Command) || opaqueInterpreterRe.MatchString(in.Command))
+		_, completeHeredoc := stripShellHeredocBodies(in.Command)
+		return nil, opaque && (!completeHeredoc || reviewerMutateRe.MatchString(in.Command) || opaqueInterpreterRe.MatchString(in.Command))
 	default:
 		return nil, false
 	}

package/engine/internal/harness/harness.go

@@ -214,6 +214,7 @@ func (h Harness) ParseGuardInput(r io.Reader) GuardInput {
 		ToolName  string `json:"tool_name"`
 		ToolInput struct {
 			Command  string `json:"command"`
+			Cmd      string `json:"cmd"`
 			FilePath string `json:"file_path"`
 			Path     string `json:"path"`
 		} `json:"tool_input"`
@@ -237,7 +238,7 @@ func (h Harness) ParseGuardInput(r io.Reader) GuardInput {
 	}
 	return GuardInput{
 		ToolName:     raw.ToolName,
-		Command:      raw.ToolInput.Command,
+		Command:      firstNonEmpty(raw.ToolInput.Command, raw.ToolInput.Cmd),
 		FilePath:     firstNonEmpty(raw.ToolInput.FilePath, raw.ToolInput.Path),
 		SessionID:    raw.SessionID,
 		AgentType:    raw.AgentType,

package/engine/internal/harness/harness_test.go

@@ -113,6 +113,10 @@ func TestHarnessParsersFailOpenAndFallbacks(t *testing.T) {
 	if guard.ToolName != "Edit" || guard.FilePath != "src/app.go" || guard.AgentID != "a1" || guard.ToolResponse != `{"ok":true}` {
 		t.Fatalf("ParseGuardInput = %#v", guard)
 	}
+	guard = Codex.ParseGuardInput(strings.NewReader(`{"tool_name":"functions.exec_command","tool_input":{"cmd":"sha256sum /tmp/agent-packet.yaml"}}`))
+	if guard.ToolName != "functions.exec_command" || guard.Command != "sha256sum /tmp/agent-packet.yaml" {
+		t.Fatalf("ParseGuardInput Codex cmd = %#v", guard)
+	}
 
 	if got := Codex.SubagentAgentType(strings.NewReader(`{"agentType":"executor"}`)); got != "executor" {
 		t.Fatalf("SubagentAgentType fallback = %q, want executor", got)

package/engine/tests/hook_test.go

@@ -583,6 +583,13 @@ func TestHookWrightScopeRequiresSpawnedCodexWorkerForSourceWrites(t *testing.T)
 	runGuard(`{"tool_name":"spawn_agent","tool_input":{"agent_type":"worker"}}`, false)
 	runGuard(`{"tool_name":"spawn_agent","tool_input":{"agent_type":"explorer"}}`, false)
 	runGuard(`{"tool_name":"Write","tool_input":{"file_path":".devrites/features/auth-tokens/state.md"}}`, false)
+	scratch := t.TempDir()
+	packet := filepath.Join(scratch, "agent-packet.yaml")
+	runGuard(hookPayload(t, map[string]any{
+		"tool_name":  "Write",
+		"tool_input": map[string]any{"file_path": packet},
+	}), false)
+	runGuard(`{"tool_name":"Write","tool_input":{"file_path":"../outside.txt"}}`, true)
 	runGuard(`{"tool_name":"Write","tool_input":{"file_path":"src/app.go"}}`, true)
 	runGuard(`{"tool_name":"Bash","tool_input":{"command":"printf x > src/app.go"}}`, true)
 	runGuard(`{"tool_name":"js","tool_input":{"code":"writeFile()"}}`, true)
@@ -644,6 +651,59 @@ func TestHookA1GuardIgnoresLegacyInlineMarker(t *testing.T) {
 	}
 }
 
+func TestHookA1GuardAllowsExternalDispatchScratchOnly(t *testing.T) {
+	root := newWorkspace(t)
+	writeActive(t, root, "auth-tokens")
+	workspace := filepath.Join(root, "features", "auth-tokens")
+	if err := os.WriteFile(filepath.Join(workspace, ".reconcile-base"), []byte("snapshot\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	scratch := t.TempDir()
+	packet := filepath.Join(scratch, "agent-packet.yaml")
+	env := []string{"DEVRITES_A1_HOOK=enforce"}
+	patch := func(tool, path string, freeform bool) string {
+		body := "*** Begin Patch\n*** Add File: " + path + "\n+x\n*** End Patch\n"
+		if freeform {
+			return hookPayload(t, map[string]any{"tool_name": tool, "tool_input": body})
+		}
+		return hookPayload(t, map[string]any{"tool_name": tool, "tool_input": map[string]any{"patch": body}})
+	}
+	shell := func(command string) string {
+		return hookPayload(t, map[string]any{
+			"tool_name":  "functions.exec_command",
+			"tool_input": map[string]any{"cmd": command},
+		})
+	}
+
+	runGuard := func(input string, deny bool) {
+		t.Helper()
+		out, errOut, code := runDevritesIO(t, root, input, env,
+			"hook", "a1-guard", "--harness=codex")
+		if code != 0 {
+			t.Fatalf("exit=%d out=%q stderr=%q", code, out, errOut)
+		}
+		if deny {
+			if decision, _ := parsePermissionDecision(t, out); decision != "deny" {
+				t.Fatalf("expected deny, got %q", out)
+			}
+		} else if strings.TrimSpace(out) != "" {
+			t.Fatalf("expected allow, got %q", out)
+		}
+	}
+
+	runGuard(patch("apply_patch", packet, false), false)
+	runGuard(patch("functions.apply_patch", packet, true), false)
+	runGuard(shell("cat <<'EOF' > "+packet+"\npacket_version: agent-packet/v1\nEOF"), false)
+	runGuard(shell("sha256sum "+packet), false)
+	runGuard(shell("cp "+packet+" "+filepath.Join(scratch, "agent-packet.copy.yaml")), false)
+	runGuard(patch("apply_patch", "src/app.go", false), true)
+	runGuard(patch("functions.apply_patch", "src/app.go", true), true)
+	runGuard(shell("cat <<'EOF' > src/app.go\npackage src\nEOF"), true)
+	runGuard(shell("cat <<'EOF' > "+packet+"\nunterminated"), true)
+	runGuard(shell("cat <<EOF > "+packet+"\n$(cp "+packet+" src/app.go)\nEOF"), true)
+	runGuard(shell("cp "+packet+" src/app.go"), true)
+}
+
 func TestHookWrightScopeFailsClosedWhenWorkspaceResolutionFails(t *testing.T) {
 	root := newWorkspace(t)
 	if err := os.Remove(filepath.Join(root, "ACTIVE")); err != nil && !os.IsNotExist(err) {
@@ -1695,7 +1755,7 @@ func TestCodexAgentDispatchRejectsIncompleteDurableV2(t *testing.T) {
 	}
 }
 
-func TestCodexAgentDispatchGatesReconcileOnBoundWrightResult(t *testing.T) {
+func TestCodexAgentDispatchGatesReconcileCloseOnBoundWrightResult(t *testing.T) {
 	root := newWorkspace(t)
 	writeActive(t, root, "auth-tokens")
 	workspace := filepath.Join(root, "features", "auth-tokens")
@@ -1714,14 +1774,26 @@ func TestCodexAgentDispatchGatesReconcileOnBoundWrightResult(t *testing.T) {
 		"prompt":          "$rite-build",
 	}), nil, "hook", "agent-dispatch", "--harness=codex")
 
-	reconcile := hookPayload(t, map[string]any{
+	check := hookPayload(t, map[string]any{
+		"hook_event_name": "PreToolUse",
+		"session_id":      sessionID,
+		"turn_id":         turnID,
+		"tool_name":       "Bash",
+		"tool_input":      map[string]any{"command": "rtk devrites-engine reconcile check"},
+	})
+	if out, stderr, code := runDevritesIO(t, root, check, nil,
+		"hook", "agent-dispatch", "--harness=codex"); code != 0 || strings.TrimSpace(out) != "" {
+		t.Fatalf("ordinary reconcile check exit=%d out=%s stderr=%s", code, out, stderr)
+	}
+
+	closeWindow := hookPayload(t, map[string]any{
 		"hook_event_name": "PreToolUse",
 		"session_id":      sessionID,
 		"turn_id":         turnID,
 		"tool_name":       "Bash",
 		"tool_input":      map[string]any{"command": "rtk devrites-engine reconcile close"},
 	})
-	out, _, _ := runDevritesIO(t, root, reconcile, nil,
+	out, _, _ := runDevritesIO(t, root, closeWindow, nil,
 		"hook", "agent-dispatch", "--harness=codex")
 	if decision, reason := parsePermissionDecision(t, out); decision != "deny" ||
 		!strings.Contains(reason, "confirmed") {
@@ -1774,7 +1846,7 @@ func TestCodexAgentDispatchGatesReconcileOnBoundWrightResult(t *testing.T) {
 		}
 	}
 
-	if out, stderr, code := runDevritesIO(t, root, reconcile, nil,
+	if out, stderr, code := runDevritesIO(t, root, closeWindow, nil,
 		"hook", "agent-dispatch", "--harness=codex"); code != 0 || strings.TrimSpace(out) != "" {
 		t.Fatalf("completed wright reconcile exit=%d out=%s stderr=%s", code, out, stderr)
 	}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devrites",
-  "version": "3.2.8",
+  "version": "3.2.10",
   "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",