Merge pull request #83 from peg/staging

release: v0.4.6 — port fix, env var injection blocking, hook feedback on deny

Author: peg

CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.6] - 2026-02-21
+
+### Fixed
+- Stale port 18275 in `rampart hook --help` and `rampart setup` comment — both now correctly show port 9090 (matching `defaultServePort`)
+- `rampart preload` defaulted to port 19090 while `rampart serve` defaults to 9090 — they couldn't talk to each other at their defaults. Port now defaults to `defaultServePort` (9090). `RAMPART_URL` env var is also now respected and takes precedence over `--port`.
+
+### Added
+- **`block-env-var-injection` policy** in `standard.yaml` — hard-denies env var injection with no legitimate agent use: `LD_PRELOAD`, `DYLD_INSERT_LIBRARIES`, `LD_AUDIT`, `PYTHONSTARTUP`, `PYTHONHOME`, `DOTNET_STARTUP_HOOKS`, `BASH_ENV`, `_JAVA_OPTIONS`, `PERL5OPT`, `GIT_EXEC_PATH`. These were previously bypassing glob rules because env-var prefixes are stripped before command matching.
+- **`watch-env-var-override` policy** in `standard.yaml` — audits (but does not block) env var overrides that are common in legitimate dev workflows but are also injection vectors: `LD_LIBRARY_PATH`, `DYLD_LIBRARY_PATH`, `NODE_OPTIONS`, `NODE_PATH`, `PYTHONPATH`, `JAVA_OPTS`, `JVM_OPTS`, `JAVA_TOOL_OPTIONS`, `GIT_SSH_COMMAND`, `GIT_SSH`, `RUBYOPT`. Logged for audit trail; upgrade to `require_approval` in your `custom.yaml` if you want gating.
+- **PostToolUseFailure hook feedback** — when Rampart denies a `PreToolUse` event, the `PostToolUseFailure` handler now injects `additionalContext` telling Claude Code not to retry the blocked action. Prevents Claude from burning 3–5 turns on workarounds after a deny.
+
 ## [0.4.5] — 2026-02-21
 
 ### Added

cmd/rampart/cli/hook.go

@@ -53,6 +53,7 @@ type hookDecision struct {
 	HookEventName            string `json:"hookEventName"`
 	PermissionDecision       string `json:"permissionDecision,omitempty"`
 	PermissionDecisionReason string `json:"permissionDecisionReason,omitempty"`
+	AdditionalContext        string `json:"additionalContext,omitempty"`
 }
 
 // clineHookInput is the JSON sent by Cline on stdin for PreToolUse hooks.
@@ -81,11 +82,12 @@ type clineHookOutput struct {
 
 // hookParseResult holds the parsed hook input including optional response data.
 type hookParseResult struct {
-	Tool     string
-	Params   map[string]any
-	Agent    string
-	Response string // non-empty for PostToolUse events
-	RunID    string // run ID derived from session_id (or env overrides)
+	Tool          string
+	Params        map[string]any
+	Agent         string
+	Response      string // non-empty for PostToolUse events
+	RunID         string // run ID derived from session_id (or env overrides)
+	HookEventName string // e.g. "PreToolUse", "PostToolUse", "PostToolUseFailure"
 }
 
 // gitContext holds the git repository context for the current working directory.
@@ -335,6 +337,22 @@ Cline setup: Use "rampart setup cline" to install hooks automatically.`,
 				return outputHookResult(cmd, format, hookOutcome, false, fmt.Sprintf("parse failure: %v", err), "")
 			}
 
+			// Short-circuit for PostToolUseFailure: the previous PreToolUse was denied by
+			// Rampart. Inject additionalContext telling Claude to stop retrying rather than
+			// burning 3-5 turns on workarounds.
+			if parsed.HookEventName == "PostToolUseFailure" {
+				msg := "This tool call failed or was blocked by a security policy. " +
+					"Do not attempt alternative approaches or workarounds — " +
+					"if an operation is restricted, report it to the user and stop."
+				out := hookOutput{
+					HookSpecificOutput: &hookDecision{
+						HookEventName:     "PostToolUseFailure",
+						AdditionalContext: msg,
+					},
+				}
+				return json.NewEncoder(cmd.OutOrStdout()).Encode(out)
+			}
+
 			// Build tool call for evaluation
 			call := engine.ToolCall{
 				ID:        audit.NewEventID(),
@@ -427,7 +445,7 @@ Cline setup: Use "rampart setup cline" to install hooks automatically.`,
 	cmd.Flags().StringVar(&mode, "mode", "enforce", "Mode: enforce | monitor | audit")
 	cmd.Flags().StringVar(&format, "format", "claude-code", "Input format: claude-code | cline")
 	cmd.Flags().StringVar(&auditDir, "audit-dir", "", "Directory for audit logs (default: ~/.rampart/audit)")
-	cmd.Flags().StringVar(&serveURL, "serve-url", "", "URL of rampart serve instance (default: auto-discover on localhost:18275, env: RAMPART_SERVE_URL)")
+	cmd.Flags().StringVar(&serveURL, "serve-url", "", "URL of rampart serve instance (default: auto-discover on localhost:9090, env: RAMPART_SERVE_URL)")
 	cmd.Flags().StringVar(&serveToken, "serve-token", "", "Auth token for rampart serve (env: RAMPART_TOKEN)")
 	cmd.Flags().MarkDeprecated("serve-token", "use RAMPART_TOKEN env var instead (--serve-token is visible in process list)")
 	cmd.Flags().StringVar(&configDir, "config-dir", "", "Directory of additional policy YAML files (default: ~/.rampart/policies/ if it exists)")
@@ -450,10 +468,11 @@ func parseClaudeCodeInput(reader interface{ Read([]byte) (int, error) }, logger
 	}
 
 	result := &hookParseResult{
-		Tool:   toolType,
-		Params: params,
-		Agent:  "claude-code",
-		RunID:  deriveRunID(input.SessionID),
+		Tool:          toolType,
+		Params:        params,
+		Agent:         "claude-code",
+		RunID:         deriveRunID(input.SessionID),
+		HookEventName: input.HookEventName,
 	}
 
 	// Extract response text from PostToolUse tool_response.

cmd/rampart/cli/hook_test.go

@@ -359,6 +359,79 @@ func TestOutputHookResult_ClaudeCode_Ask(t *testing.T) {
 	}
 }
 
+// TestPostToolUseFailure_ShortCircuit verifies that a PostToolUseFailure hook event
+// produces an additionalContext response without policy evaluation.
+func TestPostToolUseFailure_ShortCircuit(t *testing.T) {
+	t.Run("parseClaudeCodeInput extracts HookEventName", func(t *testing.T) {
+		input := map[string]any{
+			"hook_event_name": "PostToolUseFailure",
+			"tool_name":       "Bash",
+			"tool_input":      map[string]any{"command": "rm -rf /"},
+			"session_id":      "sess-abc",
+		}
+		data, _ := json.Marshal(input)
+		result, err := parseClaudeCodeInput(strings.NewReader(string(data)), testLogger())
+		if err != nil {
+			t.Fatalf("parseClaudeCodeInput error: %v", err)
+		}
+		if result.HookEventName != "PostToolUseFailure" {
+			t.Fatalf("HookEventName = %q, want PostToolUseFailure", result.HookEventName)
+		}
+		if result.Tool != "exec" {
+			t.Fatalf("Tool = %q, want exec", result.Tool)
+		}
+	})
+
+	t.Run("PostToolUseFailure output contains additionalContext", func(t *testing.T) {
+		// Simulate what the hook RunE short-circuit produces.
+		cmd := &cobra.Command{}
+		out := &bytes.Buffer{}
+		cmd.SetOut(out)
+
+		msg := "This tool call was blocked by a Rampart policy rule. " +
+			"This is a deliberate security constraint — do not attempt " +
+			"alternative approaches or workarounds. " +
+			"Tell the user the operation was blocked by policy and stop."
+		hookOut := hookOutput{
+			HookSpecificOutput: &hookDecision{
+				HookEventName:     "PostToolUseFailure",
+				AdditionalContext: msg,
+			},
+		}
+		if err := json.NewEncoder(cmd.OutOrStdout()).Encode(hookOut); err != nil {
+			t.Fatalf("encode hookOutput: %v", err)
+		}
+
+		var got hookOutput
+		if err := json.Unmarshal(out.Bytes(), &got); err != nil {
+			t.Fatalf("unmarshal output: %v", err)
+		}
+		if got.HookSpecificOutput == nil {
+			t.Fatal("expected non-nil hookSpecificOutput")
+		}
+		if got.HookSpecificOutput.HookEventName != "PostToolUseFailure" {
+			t.Fatalf("hookEventName = %q, want PostToolUseFailure", got.HookSpecificOutput.HookEventName)
+		}
+		if got.HookSpecificOutput.AdditionalContext == "" {
+			t.Fatal("additionalContext must not be empty")
+		}
+		if !strings.Contains(got.HookSpecificOutput.AdditionalContext, "blocked by a Rampart policy rule") {
+			t.Fatalf("additionalContext = %q, want to contain 'blocked by a Rampart policy rule'", got.HookSpecificOutput.AdditionalContext)
+		}
+		if !strings.Contains(got.HookSpecificOutput.AdditionalContext, "do not attempt") {
+			t.Fatalf("additionalContext = %q, should contain 'do not attempt'", got.HookSpecificOutput.AdditionalContext)
+		}
+		// Ensure no PermissionDecision field — this is not a PreToolUse response
+		if got.HookSpecificOutput.PermissionDecision != "" {
+			t.Fatalf("PermissionDecision should be empty for PostToolUseFailure, got %q", got.HookSpecificOutput.PermissionDecision)
+		}
+		// Ensure top-level decision is empty (PostToolUseFailure uses hookSpecificOutput)
+		if got.Decision != "" {
+			t.Fatalf("top-level Decision should be empty, got %q", got.Decision)
+		}
+	})
+}
+
 func TestMapClaudeCodeTool(t *testing.T) {
 	tests := []struct {
 		input string

cmd/rampart/cli/preload.go

@@ -57,6 +57,9 @@ func newPreloadCmd(_ *rootOptions) *cobra.Command {
 			}
 
 			baseURL := fmt.Sprintf("http://127.0.0.1:%d", port)
+			if envURL := strings.TrimSpace(os.Getenv("RAMPART_URL")); envURL != "" {
+				baseURL = strings.TrimRight(envURL, "/")
+			}
 			if !isPreloadRuntimeReady(cmd.Context(), baseURL) {
 				fmt.Fprintf(cmd.ErrOrStderr(), "preload: warning: rampart serve is not reachable at %s/healthz; continuing\n", baseURL)
 			}
@@ -107,7 +110,7 @@ func newPreloadCmd(_ *rootOptions) *cobra.Command {
 		},
 	}
 
-	cmd.Flags().IntVar(&port, "port", 19090, "Port for rampart serve")
+	cmd.Flags().IntVar(&port, "port", defaultServePort, "Port for rampart serve (default matches 'rampart serve' default)")
 	cmd.Flags().StringVar(&token, "token", "", "Auth token (or set RAMPART_TOKEN)")
 	cmd.Flags().StringVar(&mode, "mode", "enforce", "Mode: enforce | monitor | disabled")
 	cmd.Flags().BoolVar(&failOpen, "fail-open", true, "Whether to fail open")

cmd/rampart/cli/setup.go

@@ -97,7 +97,7 @@ Use --remove to uninstall the Rampart hooks from Claude Code settings.`,
 				return nil
 			}
 
-			// Build the hook config — no --serve-url needed, hook auto-discovers on localhost:18275.
+			// Build the hook config — no --serve-url needed, hook auto-discovers on localhost:9090.
 			// Use absolute path so the hook works regardless of Claude Code's PATH.
 			// The hook reads RAMPART_TOKEN from ~/.rampart/token automatically, so
 			// settings.json never needs to contain credentials.
@@ -126,14 +126,21 @@ Use --remove to uninstall the Rampart hooks from Claude Code settings.`,
 				"matcher": "Write|Edit",
 				"hooks":   []any{rampartHook},
 			}
+			// PostToolUseFailure: fires when Claude Code denies a tool after PreToolUse.
+			// Matcher ".*" catches all tools so Rampart can inject additionalContext
+			// telling Claude to stop retrying instead of burning turns on workarounds.
+			postToolUseFailureMatcher := map[string]any{
+				"matcher": ".*",
+				"hooks":   []any{rampartHook},
+			}
 
 			// Get or create hooks section
 			hooks, ok := settings["hooks"].(map[string]any)
 			if !ok {
 				hooks = make(map[string]any)
 			}
 
-			// Get or create PreToolUse array
+			// Get or create PreToolUse array (dedup existing rampart entries)
 			var preToolUse []any
 			if existing, ok := hooks["PreToolUse"].([]any); ok {
 				// Filter out any existing rampart hooks
@@ -148,7 +155,22 @@ Use --remove to uninstall the Rampart hooks from Claude Code settings.`,
 			}
 			preToolUse = append(preToolUse, bashMatcher, readMatcher, writeMatcher)
 
+			// Get or create PostToolUseFailure array (dedup existing rampart entries)
+			var postToolUseFailure []any
+			if existing, ok := hooks["PostToolUseFailure"].([]any); ok {
+				for _, h := range existing {
+					if m, ok := h.(map[string]any); ok {
+						if hasRampartInMatcher(m) {
+							continue
+						}
+					}
+					postToolUseFailure = append(postToolUseFailure, h)
+				}
+			}
+			postToolUseFailure = append(postToolUseFailure, postToolUseFailureMatcher)
+
 			hooks["PreToolUse"] = preToolUse
+			hooks["PostToolUseFailure"] = postToolUseFailure
 			settings["hooks"] = hooks
 
 			// Ensure directory exists
@@ -231,35 +253,51 @@ func removeClaudeCodeHooks(cmd *cobra.Command) error {
 		return nil
 	}
 
-	preToolUse, ok := hooks["PreToolUse"].([]any)
-	if !ok {
-		fmt.Fprintln(cmd.OutOrStdout(), "No PreToolUse hooks found. Nothing to remove.")
-		return nil
+	var removedCount int
+
+	// Remove from PreToolUse
+	if preToolUse, ok := hooks["PreToolUse"].([]any); ok {
+		var kept []any
+		for _, h := range preToolUse {
+			if m, ok := h.(map[string]any); ok && hasRampartInMatcher(m) {
+				removedCount++
+				matcher, _ := m["matcher"].(string)
+				fmt.Fprintf(cmd.OutOrStdout(), "  Removed PreToolUse hook: matcher=%s\n", matcher)
+				continue
+			}
+			kept = append(kept, h)
+		}
+		if len(kept) == 0 {
+			delete(hooks, "PreToolUse")
+		} else {
+			hooks["PreToolUse"] = kept
+		}
 	}
 
-	var kept []any
-	var removedCount int
-	for _, h := range preToolUse {
-		if m, ok := h.(map[string]any); ok && hasRampartInMatcher(m) {
-			removedCount++
-			matcher, _ := m["matcher"].(string)
-			fmt.Fprintf(cmd.OutOrStdout(), "  Removed hook: matcher=%s\n", matcher)
-			continue
+	// Remove from PostToolUseFailure
+	if postToolUseFailure, ok := hooks["PostToolUseFailure"].([]any); ok {
+		var kept []any
+		for _, h := range postToolUseFailure {
+			if m, ok := h.(map[string]any); ok && hasRampartInMatcher(m) {
+				removedCount++
+				matcher, _ := m["matcher"].(string)
+				fmt.Fprintf(cmd.OutOrStdout(), "  Removed PostToolUseFailure hook: matcher=%s\n", matcher)
+				continue
+			}
+			kept = append(kept, h)
+		}
+		if len(kept) == 0 {
+			delete(hooks, "PostToolUseFailure")
+		} else {
+			hooks["PostToolUseFailure"] = kept
 		}
-		kept = append(kept, h)
 	}
 
 	if removedCount == 0 {
 		fmt.Fprintln(cmd.OutOrStdout(), "No Rampart hooks found in Claude Code settings. Nothing to remove.")
 		return nil
 	}
 
-	// Clean up empty structures
-	if len(kept) == 0 {
-		delete(hooks, "PreToolUse")
-	} else {
-		hooks["PreToolUse"] = kept
-	}
 	if len(hooks) == 0 {
 		delete(settings, "hooks")
 	} else {
@@ -735,11 +773,32 @@ func hasRampartHook(settings claudeSettings) bool {
 	if !ok {
 		return false
 	}
+
+	// Check PreToolUse
 	preToolUse, ok := hooks["PreToolUse"].([]any)
 	if !ok {
 		return false
 	}
+	hasPreToolUse := false
 	for _, h := range preToolUse {
+		if m, ok := h.(map[string]any); ok {
+			if hasRampartInMatcher(m) {
+				hasPreToolUse = true
+				break
+			}
+		}
+	}
+	if !hasPreToolUse {
+		return false
+	}
+
+	// Also require PostToolUseFailure to be registered; if it's missing,
+	// return false so setup re-runs and adds it (dedup handles PreToolUse).
+	postToolUseFailure, ok := hooks["PostToolUseFailure"].([]any)
+	if !ok {
+		return false
+	}
+	for _, h := range postToolUseFailure {
 		if m, ok := h.(map[string]any); ok {
 			if hasRampartInMatcher(m) {
 				return true