Add Bash substitution rules (#26)

Author: jssblck

AGENTS.md

@@ -88,9 +88,11 @@ When Nudge has something to share, it responds in one of three ways:
 - **Passthrough**: Nothing to note. Carry on!
 - **Continue**: For UserPromptSubmit hooks, Nudge injects context as plain text
 - **Interrupt**: For PreToolUse hooks, Nudge blocks the operation and explains what to fix
+- **Substitute**: For deterministic PreToolUse Bash rules, Nudge rewrites the command and lets it proceed
 
 The response type is determined by the hook type:
-- `PreToolUse` rules always **interrupt** (block provider-supported Write/Edit/WebFetch/Bash operations)
+- `PreToolUse` block rules **interrupt** (block provider-supported Write/Edit/WebFetch/Bash operations)
+- `PreToolUse` substitute rules **allow with updated input** (Claude Code and Codex CLI Bash commands)
 - `UserPromptSubmit` rules always **continue** (inject guidance into the conversation)
 - `PermissionRequest` is parsed but always **passes through** until Nudge has a permission-specific rule surface
 - `Delete` is normalized but not yet matchable from YAML rules

CLAUDE.md

@@ -88,9 +88,11 @@ When Nudge has something to share, it responds in one of three ways:
 - **Passthrough**: Nothing to note. Carry on!
 - **Continue**: For UserPromptSubmit hooks, Nudge injects context as plain text
 - **Interrupt**: For PreToolUse hooks, Nudge blocks the operation and explains what to fix
+- **Substitute**: For deterministic PreToolUse Bash rules, Nudge rewrites the command and lets it proceed
 
 The response type is determined by the hook type:
-- `PreToolUse` rules always **interrupt** (block provider-supported Write/Edit/WebFetch/Bash operations)
+- `PreToolUse` block rules **interrupt** (block provider-supported Write/Edit/WebFetch/Bash operations)
+- `PreToolUse` substitute rules **allow with updated input** (Claude Code and Codex CLI Bash commands)
 - `UserPromptSubmit` rules always **continue** (inject guidance into the conversation)
 - `PermissionRequest` is parsed but always **passes through** until Nudge has a permission-specific rule surface
 - `Delete` is normalized but not yet matchable from YAML rules

README.md

@@ -22,6 +22,7 @@ Nudge uses agent hook systems to watch supported operations:
 When something matches a rule you've defined:
 
 - **Interrupt** (PreToolUse rules): Nudge catches the issue *before* it's written and explains what to fix
+- **Substitute** (PreToolUse Bash rules): Nudge rewrites simple deterministic commands, lets the tool proceed, and tells the model what changed
 - **Continue** (UserPromptSubmit rules): Nudge injects context into the conversation to guide the agent
 - **Passthrough**: No rules matched, everything proceeds normally
 
@@ -71,6 +72,24 @@ error: rule violation
 
 The pattern: **what's wrong** -> **how to fix** -> **retry**.
 
+For simple mechanical Bash command rewrites, use `action: substitute` with a regex `replace:` template instead of a blocking message:
+
+```yaml
+version: 1
+rules:
+  - name: use-yarn-add
+    action: substitute
+    on:
+      - hook: PreToolUse
+        tool: Bash
+        command:
+          - kind: Regex
+            pattern: "^npm install(?: (?P<args>.*))?$"
+            replace: "yarn add {{ $args }}"
+```
+
+Substitutions work for Claude Code and Codex CLI. Nudge returns the provider's full updated tool input with only `command` changed, and adds `hookSpecificOutput.additionalContext` so the model sees what was rewritten.
+
 For the full rule syntax and copy-pasteable examples, run `nudge claude docs` or `nudge codex docs`.
 
 ### Rule Writing Is Iterative
@@ -155,6 +174,8 @@ nudge check "**/*.rs"
 nudge check || exit 1
 ```
 
+`nudge check` only evaluates file-based block rules for `PreToolUse` Write/Edit matchers. It ignores `action: substitute` rules because substitutions rewrite live Bash hook payloads and need a provider to receive `updatedInput`.
+
 Example output when violations are found:
 
 ```
@@ -216,7 +237,7 @@ echo '{
   }
 }' | nudge codex hook
 
-# Exit 0 with JSON output = Interrupt (rule matched, operation blocked)
+# Exit 0 with JSON output = Interrupt or Substitute (rule matched)
 # Exit 0 with plain text = Continue (UserPromptSubmit context injected)
 # Exit 0 with no output = Passthrough (nothing to note)
 ```

docs/rfc/0002-claude-and-codex-hooks.md

@@ -91,6 +91,24 @@ Codex `PreToolUse` denial should be returned through the hook-specific shape:
 }
 ```
 
+Codex `PreToolUse` substitution should use `permissionDecision: "allow"` with
+`updatedInput`, and should include `hookSpecificOutput.additionalContext` when
+Nudge needs the model to know what was rewritten:
+
+```json
+{
+  "systemMessage": "Nudge substituted `npm install foo` -> `yarn add foo`.",
+  "hookSpecificOutput": {
+    "hookEventName": "PreToolUse",
+    "permissionDecision": "allow",
+    "updatedInput": {
+      "command": "yarn add foo"
+    },
+    "additionalContext": "Nudge rewrote the Bash command from `npm install foo` to `yarn add foo` before execution."
+  }
+}
+```
+
 Important compatibility detail: Codex documents `continue`, `stopReason`, and
 `suppressOutput` as unsupported for `PreToolUse`. Returning those fields on
 `PreToolUse` makes the hook run fail and Codex continues the tool call. Nudge's
@@ -408,7 +426,8 @@ pub fn evaluate_hook(hook: &NudgeHook, rules: &[Rule]) -> Evaluation;
 
 The existing behavior remains:
 
-- `PreToolUse` matches produce a blocking denial.
+- `PreToolUse` block matches produce a blocking denial.
+- `PreToolUse` Bash substitute matches produce an allow response with updated input.
 - `UserPromptSubmit` matches produce context on stdout.
 - `PermissionRequest` always passes through in this update.
 - No matches produce no output and exit 0.
@@ -425,6 +444,11 @@ Define an abstract outcome:
 pub enum HookOutcome {
     Passthrough,
     DenyPreToolUse { message: String },
+    UpdatePreToolUse {
+        system_message: String,
+        additional_context: String,
+        updated_input: Value,
+    },
     AddContext { context: String },
 }
 ```
@@ -460,6 +484,12 @@ Codex `DenyPreToolUse`:
 Do not include `continue`, `stopReason`, or `suppressOutput` on `PreToolUse`.
 This is the key wire-format fix for Codex.
 
+For `UpdatePreToolUse`, render `permissionDecision: "allow"` with a full
+`updatedInput` object. Preserve every original tool input field and replace
+only the rewritten field. Put the model-visible explanation in
+`hookSpecificOutput.additionalContext`; use `systemMessage` only as an
+audit/user-visible note.
+
 For `UserPromptSubmit`, prefer plain stdout for both agents. It is simple and
 documented by both hook systems as model-visible context.
 

packages/nudge/src/agent/claude.rs

@@ -23,6 +23,7 @@ pub fn parse_hook(raw: Value) -> Result<Vec<NudgeHook>> {
 
     match event {
         "PreToolUse" => Ok(vec![NudgeHook::PreToolUse(PreToolUse {
+            tool_input: raw.get("tool_input").cloned().unwrap_or(Value::Null),
             tool: tool_use(&raw)?,
             context,
         })]),
@@ -111,6 +112,8 @@ fn path_field(value: &Value, field: &str) -> Result<PathBuf> {
 mod tests {
     use serde_json::json;
 
+    use pretty_assertions::assert_eq as pretty_assert_eq;
+
     use crate::hook::{NudgeHook, ToolUse};
 
     use super::parse_hook;
@@ -154,13 +157,17 @@ mod tests {
             "hook_event_name": "PreToolUse",
             "cwd": "/tmp",
             "tool_name": "Bash",
-            "tool_input": { "command": "cargo test" }
+            "tool_input": { "command": "cargo test", "timeout": 120 }
         }))
         .expect("parse hook");
 
         assert!(
             matches!(hooks.as_slice(), [NudgeHook::PreToolUse(payload)] if matches!(payload.tool, ToolUse::Bash(_)))
         );
+        let [NudgeHook::PreToolUse(payload)] = hooks.as_slice() else {
+            panic!("expected PreToolUse");
+        };
+        pretty_assert_eq!(payload.tool_input["timeout"], 120);
     }
 
     #[test]

packages/nudge/src/agent/codex.rs

@@ -37,6 +37,7 @@ pub fn parse_hook(raw: Value) -> Result<Vec<NudgeHook>> {
 
 fn pretooluse(raw: Value, context: HookContext) -> Vec<NudgeHook> {
     let tool = tool_use(&raw);
+    let tool_input = raw.get("tool_input").cloned().unwrap_or(Value::Null);
     match tool {
         ToolUse::Other { tool_name, input } if tool_name == "apply_patch" => {
             let command = input
@@ -49,6 +50,7 @@ fn pretooluse(raw: Value, context: HookContext) -> Vec<NudgeHook> {
                     .map(|tool| {
                         NudgeHook::PreToolUse(PreToolUse {
                             context: context.clone(),
+                            tool_input: tool_input.clone(),
                             tool,
                         })
                     })
@@ -59,7 +61,11 @@ fn pretooluse(raw: Value, context: HookContext) -> Vec<NudgeHook> {
                 }
             }
         }
-        tool => vec![NudgeHook::PreToolUse(PreToolUse { context, tool })],
+        tool => vec![NudgeHook::PreToolUse(PreToolUse {
+            context,
+            tool_input,
+            tool,
+        })],
     }
 }
 

packages/nudge/src/cmd/check.rs

@@ -13,7 +13,7 @@ use color_eyre::eyre::{Context, Result};
 use glob::Pattern;
 use ignore::WalkBuilder;
 
-use nudge::rules::{self, ContentMatcher, GlobMatcher, Hook, PreToolUseMatcher, Rule};
+use nudge::rules::{self, ContentMatcher, GlobMatcher, Hook, PreToolUseMatcher, Rule, RuleAction};
 
 #[derive(Args, Clone, Debug)]
 pub struct Config {
@@ -93,19 +93,27 @@ fn collect_file_rules(rules_by_source: &[(PathBuf, Vec<Rule>)]) -> (Vec<FileRule
 }
 
 fn file_rules_for_rule(rule: &Rule) -> impl Iterator<Item = FileRule<'_>> {
-    rule.on.iter().filter_map(move |hook| match hook {
-        Hook::PreToolUse(PreToolUseMatcher::Write(matcher)) => Some(FileRule {
-            pattern: &matcher.file,
-            matchers: ContentMatcherSet::Write(&matcher.content),
-            rule,
-        }),
-        Hook::PreToolUse(PreToolUseMatcher::Edit(matcher)) => Some(FileRule {
-            pattern: &matcher.file,
-            matchers: ContentMatcherSet::Edit(&matcher.new_content),
-            rule,
-        }),
-        _ => None,
-    })
+    if rule.action != RuleAction::Block {
+        return Vec::new().into_iter();
+    }
+
+    rule.on
+        .iter()
+        .filter_map(move |hook| match hook {
+            Hook::PreToolUse(PreToolUseMatcher::Write(matcher)) => Some(FileRule {
+                pattern: &matcher.file,
+                matchers: ContentMatcherSet::Write(&matcher.content),
+                rule,
+            }),
+            Hook::PreToolUse(PreToolUseMatcher::Edit(matcher)) => Some(FileRule {
+                pattern: &matcher.file,
+                matchers: ContentMatcherSet::Edit(&matcher.new_content),
+                rule,
+            }),
+            _ => None,
+        })
+        .collect::<Vec<_>>()
+        .into_iter()
 }
 
 fn check_files(files: &[PathBuf], file_rules: &[FileRule<'_>]) -> (Vec<Issue>, usize) {
@@ -164,7 +172,7 @@ fn rule_issues(file: &Path, content: &str, file_rule: &FileRule<'_>) -> Vec<Issu
         .flat_map(|matcher| matcher.matches_with_context(content))
         .map(|m| {
             let line = byte_offset_to_line(content, m.span.start);
-            let message = nudge::template::interpolate(&file_rule.rule.message, &m.captures);
+            let message = nudge::template::interpolate(file_rule.rule.message(), &m.captures);
 
             Issue {
                 file: file.to_path_buf(),

packages/nudge/src/cmd/claude/docs.rs

@@ -45,7 +45,8 @@ const DOCS: &str = cstr!("\
   <yellow>rules:</yellow>
     <yellow>- name: rule-identifier</yellow>
       <yellow>description: \"Human-readable description\"</yellow>  <dim># Optional</dim>
-      <yellow>message: \"Your message shown at each match\"</yellow>
+      <yellow>action: block</yellow>                         <dim># block (default) or substitute</dim>
+      <yellow>message: \"Your message shown at each match\"</yellow> <dim># Required for useful block rules</dim>
 
       <yellow>on:</yellow>                           <dim># List of matchers (any match triggers the rule)</dim>
         <yellow>- hook: PreToolUse</yellow>          <dim># PreToolUse or UserPromptSubmit</dim>
@@ -54,6 +55,7 @@ const DOCS: &str = cstr!("\
           <yellow>content:</yellow>                   <dim># Patterns to match (Write tool)</dim>
             <yellow>- kind: Regex</yellow>
               <yellow>pattern: \"your-regex\"</yellow>
+              <yellow>replace: \"optional\"</yellow>      <dim># Template for substitute action</dim>
               <yellow>suggestion: \"optional\"</yellow>   <dim># Template for suggested fix</dim>
 
         <yellow>- hook: PreToolUse</yellow>          <dim># Same rule can match multiple scenarios</dim>
@@ -67,8 +69,8 @@ const DOCS: &str = cstr!("\
 <bold>Hook Types</bold>
 
   <green>PreToolUse</green>        Triggers before provider-supported Write/Edit/WebFetch/Bash
-                    operations. Always <cyan>interrupts</cyan> (blocks the operation until
-                    the issue is fixed).
+                    operations. Block rules <cyan>interrupt</cyan>; Bash substitute rules
+                    rewrite the command and allow it to proceed.
 
   <green>UserPromptSubmit</green>  Triggers when user submits a prompt. Always <cyan>continues</cyan>
                     (injects context into the conversation).
@@ -144,6 +146,35 @@ const DOCS: &str = cstr!("\
 
   Each match gets its own suggestion with its specific captures.
 
+<bold>Substitution Rules</bold>
+
+  Use <cyan>action: substitute</cyan> for deterministic Bash command rewrites. Substitute rules
+  do not need a message. They match the current Bash command, apply Regex <cyan>replace:</cyan>
+  templates in rule order, return the provider's full updated tool input, and add
+  <cyan>hookSpecificOutput.additionalContext</cyan> so the model sees what changed.
+
+  <white>Basic Syntax:</white>
+    <yellow>- name: use-yarn-add</yellow>
+      <yellow>description: Use yarn add instead of npm install</yellow>
+      <yellow>action: substitute</yellow>
+      <yellow>on:</yellow>
+        <yellow>- hook: PreToolUse</yellow>
+          <yellow>tool: Bash</yellow>
+          <yellow>command:</yellow>
+            <yellow>- kind: Regex</yellow>
+              <yellow>pattern: \"^npm install(?: (?P<<args>>.*))?$\"</yellow>
+              <yellow>replace: \"yarn add {{ $args }}\"</yellow>
+
+  <dim>For input</dim> <green>npm install lodash</green><dim>, Nudge runs</dim> <green>yarn add lodash</green><dim>.</dim>
+
+  <dim>Substitutions currently apply to Bash commands for Claude Code and Codex CLI.</dim>
+  <dim>Write/Edit substitutions are intentionally not exposed because Codex apply_patch</dim>
+  <dim>normalization would need a lossless patch rewrite.</dim>
+
+  <dim>CI note: nudge check ignores substitute rules. Check mode scans repository</dim>
+  <dim>files against file-based block rules; substitutions need a live Bash hook</dim>
+  <dim>payload and a provider that can receive updatedInput.</dim>
+
 <bold>How Messages Are Displayed</bold>
 
   When a rule matches, Nudge displays a <cyan>code snippet</cyan> with your message shown
@@ -395,6 +426,21 @@ const DOCS: &str = cstr!("\
                 <yellow>- kind: Regex</yellow>
                   <yellow>pattern: \"^main$\"</yellow>
 
+  <cyan>Substitute npm install with yarn add (Bash)</cyan>
+
+    <dim># Mechanical command rewrites can proceed without a retry loop.</dim>
+
+    <yellow>- name: use-yarn-add</yellow>
+      <yellow>description: Use yarn add instead of npm install</yellow>
+      <yellow>action: substitute</yellow>
+      <yellow>on:</yellow>
+        <yellow>- hook: PreToolUse</yellow>
+          <yellow>tool: Bash</yellow>
+          <yellow>command:</yellow>
+            <yellow>- kind: Regex</yellow>
+              <yellow>pattern: \"^npm install(?: (?P<<args>>.*))?$\"</yellow>
+              <yellow>replace: \"yarn add {{ $args }}\"</yellow>
+
   <cyan>Block dangerous commands (Bash)</cyan>
 
     <dim># Prevent accidentally running dangerous commands like rm -rf /</dim>

packages/nudge/src/cmd/test.rs

@@ -67,6 +67,17 @@ pub fn main(config: Config) -> Result<()> {
             println!("Matched content:");
             println!("{message}");
         }
+        HookOutcome::UpdatePreToolUse {
+            system_message,
+            additional_context,
+            updated_input,
+        } => {
+            println!("Result: Substitute");
+            println!();
+            println!("{system_message}");
+            println!("{additional_context}");
+            println!("{}", serde_json::to_string_pretty(&updated_input)?);
+        }
         HookOutcome::AddContext { context } => {
             println!("Result: Continue");
             println!();

packages/nudge/src/hook.rs

@@ -57,6 +57,13 @@ pub struct PreToolUse {
     /// Shared hook context.
     pub context: HookContext,
 
+    /// Original provider tool input.
+    ///
+    /// Nudge evaluates normalized tool shapes, but provider rewrite responses
+    /// must return the complete tool input object with only the intended fields
+    /// changed.
+    pub tool_input: Value,
+
     /// Normalized tool input.
     pub tool: ToolUse,
 }