Fix #34: include permission fix hints in blocked command errors

src/automation/mod.rs

@@ -1004,10 +1004,13 @@ impl<'a> WorkflowExecutor<'a> {
                         let policy_decision =
                             evaluate_workflow_command_policy(policy_ctx, &rendered);
                         if !policy_decision.allowed {
-                            let message = format!(
+                            let mut message = format!(
                                 "command blocked by permissions policy: '{}'",
                                 policy_decision.command
                             );
+                            if let Some(rule) = policy_decision.suggested_rule.as_deref() {
+                                message.push_str(&format!(" (hint: add allow rule '{rule}')"));
+                            }
                             match fail_mode {
                                 WorkflowFailMode::Open => {
                                     step_results.push(StepResult {
@@ -1857,6 +1860,7 @@ fn evaluate_workflow_command_policy(
                 "step_index": ctx.step_index,
                 "command": decision.command,
                 "matched_rule": decision.matched_rule,
+                "suggested_rule": decision.suggested_rule,
             })),
         },
     );
@@ -3475,6 +3479,12 @@ mod tests {
                 .as_deref()
                 .is_some_and(|m| m.contains("blocked by permissions policy"))
         );
+        assert!(
+            result.step_results[0]
+                .message
+                .as_deref()
+                .is_some_and(|m| m.contains("hint: add allow rule"))
+        );
 
         let decisions = crate::state::load_policy_decisions(&dir).unwrap();
         assert!(decisions.iter().any(|d| {

src/cli/permissions.rs

@@ -29,6 +29,7 @@ struct PermissionCheckReport {
     allowed: bool,
     policy_configured: bool,
     matched_rule: Option<String>,
+    suggested_rule: Option<String>,
     reason: Option<String>,
 }
 
@@ -49,6 +50,7 @@ fn run_check(parts: &[String], as_json: bool) -> Result<()> {
         decision.allowed,
         decision.policy_configured,
         decision.matched_rule.as_deref(),
+        decision.suggested_rule.as_deref(),
         decision.reason.as_deref(),
     );
 
@@ -58,6 +60,7 @@ fn run_check(parts: &[String], as_json: bool) -> Result<()> {
             allowed: decision.allowed,
             policy_configured: decision.policy_configured,
             matched_rule: decision.matched_rule.clone(),
+            suggested_rule: decision.suggested_rule.clone(),
             reason: decision.reason.clone(),
         };
         println!("{}", serde_json::to_string_pretty(&report)?);
@@ -74,15 +77,22 @@ fn run_check(parts: &[String], as_json: bool) -> Result<()> {
         }
     } else if let Some(reason) = decision.reason.as_deref() {
         eprintln!("{reason}: '{}'", decision.command);
+        if let Some(rule) = decision.suggested_rule.as_deref() {
+            eprintln!("hint: add this allow rule: {rule}");
+        }
     }
 
     if decision.allowed {
         Ok(())
     } else {
-        Err(TuttiError::ConfigValidation(format!(
+        let mut message = format!(
             "command blocked by permissions policy: '{}'",
             decision.command
-        )))
+        );
+        if let Some(rule) = decision.suggested_rule.as_deref() {
+            message.push_str(&format!(" (hint: add allow rule '{rule}')"));
+        }
+        Err(TuttiError::ConfigValidation(message))
     }
 }
 
@@ -108,6 +118,7 @@ fn persist_permission_check_decision(
     allowed: bool,
     policy_configured: bool,
     matched_rule: Option<&str>,
+    suggested_rule: Option<&str>,
     reason: Option<&str>,
 ) {
     let Some(ctx) = workspace_ctx else {
@@ -137,7 +148,8 @@ fn persist_permission_check_decision(
             reason: reason.map(ToString::to_string),
             data: Some(json!({
                 "command": command,
-                "matched_rule": matched_rule
+                "matched_rule": matched_rule,
+                "suggested_rule": suggested_rule
             })),
         },
     );
@@ -191,7 +203,9 @@ fn collect_blocked_commands(
                     if !decision.allowed && seen_commands.insert(cmd.clone()) {
                         blocked.push(PermissionSuggestion {
                             command: cmd.clone(),
-                            suggested_rule: format!("{cmd} *"),
+                            suggested_rule: decision
+                                .suggested_rule
+                                .unwrap_or_else(|| format!("{cmd} *")),
                             reason: decision.reason,
                         });
                     }
@@ -436,6 +450,7 @@ mod tests {
             true,
             Some("git status"),
             None,
+            None,
         );
 
         let records = load_policy_decisions(&dir).unwrap();

src/permissions/mod.rs

@@ -34,6 +34,7 @@ pub struct CommandPolicyDecision {
     pub allowed: bool,
     pub policy_configured: bool,
     pub matched_rule: Option<String>,
+    pub suggested_rule: Option<String>,
     pub reason: Option<String>,
 }
 
@@ -48,6 +49,7 @@ pub fn evaluate_command_policy(
             allowed: true,
             policy_configured: false,
             matched_rule: None,
+            suggested_rule: None,
             reason: Some("policy not configured".to_string()),
         };
     };
@@ -58,19 +60,30 @@ pub fn evaluate_command_policy(
             allowed: true,
             policy_configured: true,
             matched_rule: Some(matched_rule.to_string()),
+            suggested_rule: None,
             reason: None,
         };
     }
 
     CommandPolicyDecision {
-        command: normalized,
+        command: normalized.clone(),
         allowed: false,
         policy_configured: true,
         matched_rule: None,
+        suggested_rule: suggested_wildcard_prefix_rule(&normalized),
         reason: Some("blocked by permissions policy".to_string()),
     }
 }
 
+fn suggested_wildcard_prefix_rule(command_line: &str) -> Option<String> {
+    let tokens: Vec<&str> = command_line.split_whitespace().collect();
+    if tokens.len() < 2 {
+        return None;
+    }
+
+    Some(format!("{} {} *", tokens[0], tokens[1]))
+}
+
 pub fn render_claude_settings(policy: &PermissionsConfig) -> Result<String> {
     let allow: Vec<String> = policy
         .allow
@@ -247,6 +260,16 @@ mod tests {
             decision.reason.as_deref(),
             Some("blocked by permissions policy")
         );
+        assert_eq!(decision.suggested_rule.as_deref(), Some("git stash *"));
+    }
+
+    #[test]
+    fn evaluate_command_policy_suggests_rule_from_first_two_tokens_only() {
+        let policy = PermissionsConfig {
+            allow: vec!["git status".to_string()],
+        };
+        let decision = evaluate_command_policy(Some(&policy), "cargo test --quiet --all");
+        assert_eq!(decision.suggested_rule.as_deref(), Some("cargo test *"));
     }
 
     #[test]