aihook: rename stop to shell

Author: neongreen

aihook/AGENTS.md

@@ -36,7 +36,7 @@ go test ./aihook/...
 go build ./aihook
 
 # Run
-./aihook stop < script.sh
+./aihook shell < script.sh
 ```
 
 ### Code Structure

aihook/README.md

@@ -34,16 +34,19 @@ go build ./aihook
 
 ## Usage
 
-### Stop Hook
+### Shell Hook
 
-The `stop` subcommand validates shell scripts and ensures all `cd` commands are executed within subshells:
+The `shell` subcommand validates shell scripts and ensures all `cd` commands are executed within subshells:
 
 ```bash
 # Check a shell script from stdin
-echo 'cd /tmp' | aihook stop
+echo 'cd /tmp' | aihook shell
 
 # With Claude Code hook format output
-echo 'cd /tmp' | aihook stop --claude
+echo 'cd /tmp' | aihook shell --claude
+
+# Block execution when cd violations are found
+echo 'cd /tmp' | aihook shell --claude --block-on-cd
 ```
 
 ### Examples
@@ -58,10 +61,15 @@ cd /tmp && ls
 (cd /tmp && ls)
 ```
 
+### Flags
+
+- `--claude`: Output in JSON format compatible with Claude Code hooks
+- `--block-on-cd`: When set, returns exit code 2 for violations (blocks execution). Without this flag, violations are reported but execution is not blocked (exit code 0)
+
 ### Exit Codes
 
-- `0`: No violations found
-- `2`: Violations detected (cd commands outside subshells)
+- `0`: No violations found (or violations found but `--block-on-cd` not set)
+- `2`: Violations detected and `--block-on-cd` flag is set
 - `1`: Parse error or other failure
 
 ### Output Formats
@@ -97,7 +105,7 @@ To use `aihook` as a Claude Code PreToolUse hook that validates Bash commands, a
         "hooks": [
           {
             "type": "command",
-            "command": "aihook stop --claude"
+            "command": "aihook shell --claude --block-on-cd"
           }
         ]
       }
@@ -110,7 +118,8 @@ The hook will:
 - Match any Bash tool invocation (via the `"Bash"` matcher)
 - Receive the bash command script on stdin
 - Validate that all `cd` commands are in subshells
-- Return exit code 0 to allow, or exit code 2 to block with error message
+- With `--block-on-cd`: Return exit code 2 to block execution when violations are found
+- Without `--block-on-cd`: Report violations but allow execution (exit code 0)
 - Use `--claude` flag to output in the expected JSON format
 
 For more flexible matching, you can use regex patterns like `"Bash.*cd"` to only check Bash commands containing `cd`.

aihook/main.go

@@ -17,20 +17,22 @@ var rootCmd = &cobra.Command{
 	Long:  `aihook validates shell commands and code patterns for Claude Code hooks.`,
 }
 
-var stopCmd = &cobra.Command{
-	Use:   "stop",
-	Short: "Stop hook that validates shell commands",
-	Long:  `Stop hook that parses shell syntax and forbids 'cd' invocations outside subshells.`,
-	RunE:  runStop,
+var shellCmd = &cobra.Command{
+	Use:   "shell",
+	Short: "Shell hook that validates shell commands",
+	Long:  `Shell hook that parses shell syntax and forbids 'cd' invocations outside subshells.`,
+	RunE:  runShell,
 }
 
 var claudeFlag bool
+var blockOnCdFlag bool
 
 func init() {
-	rootCmd.AddCommand(stopCmd)
+	rootCmd.AddCommand(shellCmd)
 	rootCmd.AddCommand(version.NewVersionCommand("aihook"))
 
-	stopCmd.Flags().BoolVar(&claudeFlag, "claude", false, "Output in Claude Code hook format")
+	shellCmd.Flags().BoolVar(&claudeFlag, "claude", false, "Output in Claude Code hook format")
+	shellCmd.Flags().BoolVar(&blockOnCdFlag, "block-on-cd", false, "Block when cd commands are found outside subshells")
 }
 
 func main() {
@@ -40,7 +42,7 @@ func main() {
 	}
 }
 
-func runStop(cmd *cobra.Command, args []string) error {
+func runShell(cmd *cobra.Command, args []string) error {
 	v := validator.New()
 	violations, err := v.ValidateScript(os.Stdin)
 	if err != nil {
@@ -49,7 +51,10 @@ func runStop(cmd *cobra.Command, args []string) error {
 
 	if len(violations) > 0 {
 		msg := validator.FormatViolations(violations)
-		return formatOutput(msg, 2)
+		if blockOnCdFlag {
+			return formatOutput(msg, 2)
+		}
+		return formatOutput(msg, 0)
 	}
 
 	return formatOutput("No violations found", 0)