devrites 3.0.7 → 3.1.0

package/engine/hooks.go

@@ -12,23 +12,24 @@ import (
 
 	"github.com/devrites/devrites/internal/gate"
 	"github.com/devrites/devrites/internal/harness"
+	"github.com/devrites/devrites/internal/lib"
 	"github.com/devrites/devrites/internal/orient"
+	drvreason "github.com/devrites/devrites/internal/reason"
 	"github.com/devrites/devrites/internal/state"
 )
 
-// hookOrient emits the SessionStart orientation for the active feature. It is
-// FAIL-OPEN and read-only: on a non-DevRites directory, an unreadable workspace,
-// or nothing to say, it stays silent and exits 0 so a session is never wedged.
-// The engine's inline shell guard handles a missing binary; this handles a
-// present binary run outside a workspace.
+// hookOrient emits SessionStart context for the active feature. It is read only
+// and returns silently when the workspace is missing, unreadable, or has nothing
+// to report. An inline shell guard handles a missing binary; this function
+// handles a present binary outside a workspace.
 func hookOrient(h harness.Harness, stdin io.Reader, stdout, stderr io.Writer) int {
-	// The SessionStart payload is drained but unused: orientation is a pure read
-	// of the workspace files, not a function of the harness's stdin.
+	// Orientation depends only on workspace files, so read and discard the
+	// SessionStart payload.
 	_, _ = io.Copy(io.Discard, stdin)
 
 	root, err := orient.ResolveRoot(os.Getenv("DEVRITES_ROOT"))
 	if err != nil {
-		return exitOK // not a DevRites workspace: silent no-op
+		return exitOK // Stay silent outside a DevRites workspace.
 	}
 	text, has, err := orient.Digest(root)
 	if err != nil {
@@ -36,8 +37,8 @@ func hookOrient(h harness.Harness, stdin io.Reader, stdout, stderr io.Writer) in
 		return exitOK
 	}
 	if !has {
-		// No active feature: on the first-ever such session, orient once with a
-		// repo-classified starting nudge instead of staying silent.
+		// On the first session without an active feature, print a starting hint
+		// based on the repository.
 		if text, has = orient.FirstRunDigest(root); !has {
 			return exitOK
 		}
@@ -51,40 +52,59 @@ func hookOrient(h harness.Harness, stdin io.Reader, stdout, stderr io.Writer) in
 	return exitOK
 }
 
-// hookStopGate refuses to end a turn at a provably inconsistent rest point. It
-// mirrors devrites-stop-gate.sh: OBSERVE by default, blocking only when
-// DEVRITES_STOP_GATE=enforce; loop-guarded by the harness's stop_hook_active so
-// it can never wedge the session; fully fail-open.
+// hookStopGate catches inconsistent state when a turn ends. It mirrors
+// devrites-stop-gate.sh, observes by default, and blocks only when
+// DEVRITES_STOP_GATE=enforce. stop_hook_active prevents a blocking loop, and
+// parsing or workspace errors do not block.
 func hookStopGate(h harness.Harness, stdin io.Reader, stdout, stderr io.Writer) int {
 	in := h.ParseStopInput(stdin)
+	if !in.StopHookActivePresent {
+		recordHookGuard(h, "stop-gate", drvreason.HookStopInputInvalid, lib.GuardUnavailable, lib.OutcomeUnavailable)
+		return exitOK // Invalid input does not block.
+	}
 	if in.StopHookActive {
-		return exitOK // already re-entered this stop cycle: let it stop
+		recordHookGuard(h, "stop-gate", drvreason.HookStopReentry, lib.GuardBypassed, lib.OutcomeBypassed)
+		return exitOK // A reentered Stop must finish.
 	}
 	root, err := orient.ResolveRoot(os.Getenv("DEVRITES_ROOT"))
 	if err != nil {
 		return exitOK
 	}
 	res, err := gate.StopGate(root)
-	if err != nil || !res.Blocked {
+	if err != nil {
+		recordHookGuard(h, "stop-gate", drvreason.HookStopWorkspaceUnavailable, lib.GuardUnavailable, lib.OutcomeUnavailable)
+		return exitOK
+	}
+	if res.ReasonID == "" {
+		recordHookGuard(h, "stop-gate", drvreason.HookStopWorkspaceUnavailable, lib.GuardUnavailable, lib.OutcomeUnavailable)
+		return exitOK
+	}
+	if !res.Blocked {
+		strength := lib.GuardObserved
+		if hookEnforce("DEVRITES_STOP_GATE") {
+			strength = lib.GuardEnforced
+		}
+		recordHookGuard(h, "stop-gate", res.ReasonID, strength, lib.OutcomePassed)
 		return exitOK
 	}
 	if !hookEnforce("DEVRITES_STOP_GATE") {
-		// Observe mode: never block. Record a would-block to the feature's
-		// append-only log (mirroring devrites-stop-gate.sh) so the invariant is
-		// visible without gating; the append is O_APPEND-atomic across the
-		// concurrent processes DevRites spawns.
+		// Observe mode records the finding without blocking. O_APPEND keeps each
+		// log entry intact when DevRites runs concurrent processes.
 		logPath := filepath.Join(resolveWorkspaceDir(root, res.Slug), ".stop-gate.log")
 		if err := state.AppendLog(logPath, "WOULD-BLOCK\t"+res.Reason); err != nil {
 			debugf(stderr, "stop-gate log: %v", err)
 		}
+		recordHookGuard(h, "stop-gate", res.ReasonID, lib.GuardObserved, lib.OutcomeObserved, res.EvidenceFiles...)
 		return exitOK
 	}
 	out, err := h.StopBlock(res.Reason)
 	if err != nil {
 		debugf(stderr, "stop-gate: %v", err)
+		recordHookGuard(h, "stop-gate", res.ReasonID, lib.GuardUnavailable, lib.OutcomeUnavailable, res.EvidenceFiles...)
 		return exitOK
 	}
 	fmt.Fprintln(stdout, out)
+	recordHookGuard(h, "stop-gate", res.ReasonID, lib.GuardEnforced, lib.OutcomeBlocked, res.EvidenceFiles...)
 	return exitOK
 }
 
@@ -107,16 +127,14 @@ var allowReadonlySubcommands = map[string]map[string]bool{
 	"reviewer-stats": {"report": true},
 }
 
-// hookAllow auto-approves the read-only devrites orientation/gate subcommands so
-// they stop triggering a permission prompt on every skill run. FAIL-OPEN: it only
-// ever EMITS an allow for a structurally exact command shape; on any doubt it
-// stays silent, leaving the normal permission flow untouched.
+// hookAllow approves exact read-only DevRites orientation and gate commands.
+// Any other command stays in the harness's normal permission flow.
 func hookAllow(h harness.Harness, stdin io.Reader, stdout, stderr io.Writer) int {
 	data, err := io.ReadAll(stdin)
 	if err != nil {
 		return exitOK
 	}
-	// Fast path: a command not mentioning devrites at all is never ours.
+	// Ignore commands that do not mention DevRites.
 	if !bytes.Contains(data, []byte("devrites")) {
 		return exitOK
 	}
@@ -133,6 +151,7 @@ func hookAllow(h harness.Harness, stdin io.Reader, stdout, stderr io.Writer) int
 		return exitOK
 	}
 	fmt.Fprintln(stdout, out)
+	recordHookGuard(h, "allow", drvreason.HookAllowApproved, lib.GuardEnforced, lib.OutcomeAllowed)
 	return exitOK
 }
 
@@ -215,77 +234,283 @@ func safeAllowArg(arg string) bool {
 // parity oracle green.
 const reviewerReadonlyDenyReason = "DevRites: reviewers are read-only. This Bash command can mutate or exfiltrate; inspect with Read/Grep/Glob and return findings: do not modify the tree or reach the network. (devrites-reviewer-readonly)"
 
-// reviewerMutateRe matches a Bash command that could mutate the tree or reach the
-// network: the deny-list ported verbatim from devrites-reviewer-readonly.sh. A
-// fresh-context reviewer reads untrusted source, so a silent write/exfil path is
-// a prompt-injection surface (standards/security.md). pack-scan-ignore: this is
-// the hook's own defensive deny-list, not a payload.
-//
-// The pattern is byte-identical to the bash `grep -E`. ONE deliberate divergence:
-// this matches against the WHOLE command, while the bash hook's
-// `read -r tool cmd agent_type` truncates the command at its first newline and so
-// only ever scans line 1. A reviewer running a multi-line Bash whose later lines
-// mutate (e.g. `cat x\nsed -i …`) slips past the bash hook but is denied here:
-// intentional hardening of a latent bash bug, not a parity regression. (RE2's
-// `[[:space:]]` already matches `\n`, so no `(?m)` flag is needed for the `-i$`
-// alternative to fire at an interior line break.)
-var reviewerMutateRe = regexp.MustCompile(`>>|[^0-9 ]>[^>&]|[[:space:]]-i([[:space:]]|$)|sed[[:space:]]+-i|\brm\b|\bmv\b|\btee\b|\btruncate\b|\bdd\b|chmod|chown|git[[:space:]]+(add|commit|push|reset|checkout|rm|mv|stash|tag|apply)|npm[[:space:]]+(install|i|publish|run)|pnpm[[:space:]]+(install|add)|yarn[[:space:]]+add|pip[[:space:]]+install|curl[[:space:]].*[[:space:]]-o\b|\bwget\b|\bscp\b|\bssh\b|\bnc\b`)
-
-// hookReviewerReadonly keeps the read-only reviewer subagents read-only: it denies
-// a Bash command that could mutate the tree or exfiltrate. It mirrors
-// devrites-reviewer-readonly.sh: OBSERVE by default (logs a would-block, allows),
-// blocking only when DEVRITES_REVIEWER_RO=enforce; fully fail-open.
+// reviewerMutateRe is the legacy observe-mode deny-list. Active DevRites leaves
+// use the fail-closed safe-command check below instead.
+var reviewerMutateRe = regexp.MustCompile(`(?im)>>|[^0-9 ]>[^>&]|[[:space:]]-i([[:space:]]|$)|sed[[:space:]]+-i|\b(rm|mv|cp|touch|mkdir|rmdir|tee|truncate|dd|chmod|chown|ln|unlink|install|patch)\b|git[[:space:]]+(add|commit|push|reset|checkout|restore|clean|rm|mv|stash|tag|apply|merge|rebase)|npm[[:space:]]+(install|i|ci|publish)|pnpm[[:space:]]+(install|add|publish)|yarn[[:space:]]+(add|install|publish)|pip[[:space:]]+install|go[[:space:]]+(get|install|generate)|cargo[[:space:]]+(add|install|publish)|\b(curl|wget|scp|ssh|nc|socat|telnet)\b`)
+
+var shellSegmentRe = regexp.MustCompile(`\|\||&&|[;|\n]`)
+
+type devritesAgentKind uint8
+
+const (
+	devritesAgentNone devritesAgentKind = iota
+	devritesAgentReadonly
+	devritesAgentWright
+	devritesAgentInvalid
+)
+
+// devritesAgent identifies the one write-capable leaf without copying the agent
+// roster. DEVRITES_AGENT_RUN supplies identity when a hook payload cannot carry
+// agent_type.
+func devritesAgent(payloadAgent string) devritesAgentKind {
+	payloadAgent = strings.TrimSpace(payloadAgent)
+	envAgent := strings.TrimSpace(os.Getenv("DEVRITES_ACTIVE_AGENT"))
+	declared := os.Getenv("DEVRITES_AGENT_RUN") == "1" || strings.HasPrefix(payloadAgent, "devrites-")
+	if !declared {
+		return devritesAgentNone
+	}
+	if payloadAgent != "" && envAgent != "" && payloadAgent != envAgent {
+		return devritesAgentInvalid
+	}
+	agent := payloadAgent
+	if agent == "" {
+		agent = envAgent
+	}
+	switch {
+	case agent == "devrites-slice-wright":
+		return devritesAgentWright
+	case strings.HasPrefix(agent, "devrites-") && len(agent) > len("devrites-"):
+		return devritesAgentReadonly
+	default:
+		return devritesAgentInvalid
+	}
+}
+
+func toolBaseName(tool string) string {
+	tool = strings.ToLower(strings.TrimSpace(tool))
+	for _, sep := range []string{"::", "__", "/", "."} {
+		if i := strings.LastIndex(tool, sep); i >= 0 {
+			tool = tool[i+len(sep):]
+		}
+	}
+	return strings.ReplaceAll(tool, "-", "_")
+}
+
+func isShellTool(tool string) bool {
+	switch toolBaseName(tool) {
+	case "bash", "shell", "sh", "exec_command", "run_command":
+		return true
+	}
+	return false
+}
+
+func isOpaqueExecutionTool(tool string) bool {
+	switch toolBaseName(tool) {
+	case "exec", "js", "python", "computer", "computer_use", "write_stdin", "run_code":
+		return true
+	}
+	return false
+}
+
+func isAgentDispatchTool(tool string) bool {
+	switch toolBaseName(tool) {
+	case "agent", "task", "spawn_agent", "delegate", "dispatch_agent", "create_agent":
+		return true
+	}
+	return false
+}
+
+// safeReadonlyShellCommand accepts common inspection and proof commands. A
+// read-only leaf can use Read or Grep, or ask the orchestrator to run anything
+// outside this conservative set.
+func safeReadonlyShellCommand(command string) bool {
+	command, writeTargets, opaqueRedirect := shellOutputRedirections(command)
+	if opaqueRedirect || len(writeTargets) != 0 ||
+		strings.Contains(command, "$(") || strings.ContainsRune(command, '`') ||
+		reviewerMutateRe.MatchString(command) {
+		return false
+	}
+	segments := shellSegmentRe.Split(command, -1)
+	if len(segments) == 0 {
+		return false
+	}
+	for _, segment := range segments {
+		if !safeReadonlyShellSegment(segment) {
+			return false
+		}
+	}
+	return true
+}
+
+func safeReadonlyShellSegment(segment string) bool {
+	fields := strings.Fields(strings.TrimSpace(segment))
+	for len(fields) > 0 && strings.Contains(fields[0], "=") && !strings.HasPrefix(fields[0], "=") {
+		fields = fields[1:]
+	}
+	for len(fields) > 0 {
+		switch filepath.Base(fields[0]) {
+		case "rtk", "timeout", "nice":
+			fields = fields[1:]
+			continue
+		case "command":
+			if len(fields) == 2 && fields[1] == "-v" {
+				return true
+			}
+			fields = fields[1:]
+			continue
+		case "env":
+			fields = fields[1:]
+			for len(fields) > 0 && (strings.HasPrefix(fields[0], "-") || strings.Contains(fields[0], "=")) {
+				fields = fields[1:]
+			}
+			continue
+		}
+		break
+	}
+	if len(fields) == 0 {
+		return false
+	}
+
+	base := strings.ToLower(filepath.Base(strings.Trim(fields[0], `"'`)))
+	args := fields[1:]
+	switch base {
+	case "true", "false", "pwd", "ls", "cat", "head", "tail", "less", "more",
+		"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":
+		return true
+	case "find":
+		return !hasAnyArg(args, "-delete", "-exec", "-execdir", "-ok", "-okdir", "-fprint", "-fprintf")
+	case "sed":
+		return !hasArgPrefix(args, "-i")
+	case "git":
+		return len(args) > 0 && hasAnyArg(args[:1], "diff", "status", "show", "log", "rev-parse", "ls-files", "grep", "blame")
+	case "go":
+		if len(args) == 0 || !hasAnyArg(args[:1], "test", "vet", "list", "version", "env") {
+			return false
+		}
+		return args[0] != "env" || !hasAnyArg(args[1:], "-w", "-u")
+	case "npm", "pnpm", "yarn":
+		return safePackageProof(args)
+	case "pytest", "rspec":
+		return true
+	case "python", "python3":
+		return len(args) >= 2 && args[0] == "-m" && hasAnyArg(args[1:2], "pytest", "unittest", "compileall")
+	case "cargo":
+		if len(args) == 0 {
+			return false
+		}
+		if hasAnyArg(args[:1], "test", "check", "clippy") {
+			return true
+		}
+		return args[0] == "fmt" && hasAnyArg(args[1:], "--check")
+	case "ruff":
+		return len(args) > 0 && args[0] == "check" && !hasAnyArg(args[1:], "--fix")
+	case "prettier":
+		return hasAnyArg(args, "--check", "--list-different")
+	case "eslint":
+		return !hasAnyArg(args, "--fix", "--fix-dry-run")
+	case "tsc":
+		return hasAnyArg(args, "--noEmit")
+	case "node":
+		return hasAnyArg(args, "--check", "--test", "--version", "-v")
+	case "bash", "sh", "zsh":
+		return len(args) > 0 && args[0] == "-n"
+	case "make":
+		return len(args) > 0 && hasAnyArg(args[:1], "test", "check", "lint", "vet")
+	case "devrites-engine":
+		return len(args) > 0 && safeAllowShape(args[0], args[1:])
+	}
+	return false
+}
+
+func safePackageProof(args []string) bool {
+	if len(args) == 0 {
+		return false
+	}
+	if args[0] == "test" {
+		return true
+	}
+	return len(args) > 1 && args[0] == "run" &&
+		hasAnyArg(args[1:2], "test", "lint", "check", "typecheck", "type-check")
+}
+
+func hasAnyArg(args []string, wants ...string) bool {
+	for _, arg := range args {
+		for _, want := range wants {
+			if arg == want {
+				return true
+			}
+		}
+	}
+	return false
+}
+
+func hasArgPrefix(args []string, prefix string) bool {
+	for _, arg := range args {
+		if strings.HasPrefix(arg, prefix) {
+			return true
+		}
+	}
+	return false
+}
+
+// hookReviewerReadonly keeps every DevRites leaf except slice-wright read only.
+// It always enforces declared DevRites runs. Undeclared runs keep the legacy
+// observe mode.
 func hookReviewerReadonly(h harness.Harness, stdin io.Reader, stdout, stderr io.Writer) int {
 	data, err := io.ReadAll(stdin)
 	if err != nil {
 		return exitOK
 	}
-	// Fast path: a payload with no tool call is not ours: mirrors the script's
-	// `case "$input" in *'"tool_name"'*`.
 	if !bytes.Contains(data, []byte(`"tool_name"`)) {
 		return exitOK
 	}
-	in := h.ParsePreToolInput(bytes.NewReader(data))
+	in := h.ParseGuardInput(bytes.NewReader(data))
+	kind := devritesAgent(in.AgentType)
 
-	// When the surface guarantees subagent identity, scope to devrites reviewers:
-	// the slice-wright is a sanctioned writer and the main thread / other agents
-	// are not our concern.
-	if os.Getenv("DEVRITES_REVIEWER_AGENT_REQUIRED") == "1" {
-		switch {
-		case in.AgentType == "" || in.AgentType == "devrites-slice-wright":
+	// Do not let a global hook interfere with the main thread or another
+	// product's agent when no DevRites run is declared.
+	if kind == devritesAgentNone && (in.AgentType != "" || os.Getenv("DEVRITES_REVIEWER_AGENT_REQUIRED") == "1") {
+		return exitOK
+	}
+	if kind == devritesAgentWright {
+		if !isAgentDispatchTool(in.ToolName) {
 			return exitOK
-		case !strings.HasPrefix(in.AgentType, "devrites-"):
+		}
+	} else {
+		active := kind != devritesAgentNone
+		unsafe := isEditTool(in.ToolName) || isOpaqueExecutionTool(in.ToolName) || isAgentDispatchTool(in.ToolName)
+		if isShellTool(in.ToolName) {
+			if in.Command == "" {
+				unsafe = active
+			} else if active {
+				unsafe = !safeReadonlyShellCommand(in.Command)
+			} else {
+				unsafe = reviewerMutateRe.MatchString(in.Command)
+			}
+		}
+		if !unsafe {
 			return exitOK
 		}
 	}
-	if in.ToolName != "Bash" || in.Command == "" {
-		return exitOK
-	}
-	if !reviewerMutateRe.MatchString(in.Command) {
-		return exitOK
-	}
 
-	if hookEnforce("DEVRITES_REVIEWER_RO") {
+	active := kind != devritesAgentNone
+	if active || hookEnforce("DEVRITES_REVIEWER_RO") {
 		out, err := h.PreToolDeny(reviewerReadonlyDenyReason)
 		if err != nil {
 			debugf(stderr, "reviewer-readonly: %v", err)
 			return exitOK
 		}
 		fmt.Fprintln(stdout, out)
+		recordHookGuard(h, "reviewer-readonly", drvreason.HookReviewerReadonlyDenied, lib.GuardEnforced, lib.OutcomeDenied)
 		return exitOK
 	}
 
-	// Observe mode: record the would-block to the active feature's append-only log,
-	// mirroring the stop-gate's log convention, then allow. The append is
-	// O_APPEND-atomic across the concurrent processes DevRites spawns.
 	if root, err := orient.ResolveRoot(os.Getenv("DEVRITES_ROOT")); err == nil {
 		if slug, _ := orient.ActiveSlug(root); slug != "" {
 			logPath := filepath.Join(resolveWorkspaceDir(root, slug), ".reviewer-ro.log")
-			if err := state.AppendLog(logPath, "WOULD-BLOCK\t"+head80(in.Command)); err != nil {
+			action := in.Command
+			if action == "" {
+				action = in.ToolName + "\t" + in.FilePath
+			}
+			if err := state.AppendLog(logPath, "WOULD-BLOCK\t"+head80(action)); err != nil {
 				debugf(stderr, "reviewer-readonly log: %v", err)
 			}
 		}
 	}
+	recordHookGuard(h, "reviewer-readonly", drvreason.HookReviewerReadonlyObserved, lib.GuardObserved, lib.OutcomeObserved)
 	return exitOK
 }
 
@@ -297,15 +522,13 @@ func hookReviewerReadonly(h harness.Harness, stdin io.Reader, stdout, stderr io.
 //go:embed subagent_orient_context.txt
 var subagentOrientContext string
 
-// hookSubagentOrient injects the DevRites discipline into every devrites-* subagent
-// at spawn: a spawned subagent starts in a fresh context and neither auto-loads the
-// rite-* framework nor discovers skills the way the main thread does. It mirrors
-// devrites-subagent-orient.sh: fire only for devrites-* agents, emit a fixed
-// context envelope, stay silent + fail-open otherwise.
+// hookSubagentOrient adds DevRites instructions when a devrites-* agent starts.
+// Spawned agents have fresh context and do not load the rite-* framework the
+// same way as the main thread. The output matches devrites-subagent-orient.sh.
 func hookSubagentOrient(h harness.Harness, stdin io.Reader, stdout, stderr io.Writer) int {
 	agentType := h.SubagentAgentType(stdin)
 	if !strings.HasPrefix(agentType, "devrites-") {
-		return exitOK // not a DevRites subagent (or no identity): silent no-op
+		return exitOK // Stay silent without a DevRites agent identity.
 	}
 	out, err := h.SubagentStartContext(strings.ReplaceAll(subagentOrientContext, "\r\n", "\n"))
 	if err != nil {
@@ -326,9 +549,7 @@ func head80(s string) string {
 	return s
 }
 
-// debugf writes an operational diagnostic only when DEVRITES_DEBUG is set, so a
-// fail-open hook can surface WHY it stayed silent without ever polluting normal
-// hook stdout/stderr.
+// debugf writes diagnostics only when DEVRITES_DEBUG is set.
 func debugf(stderr io.Writer, format string, args ...any) {
 	if os.Getenv("DEVRITES_DEBUG") != "" {
 		fmt.Fprintf(stderr, "devrites: "+format+"\n", args...)