Merge pull request #62 from syou6162/subagent_stop

feat: SubagentStopフックのJSON出力対応

Author: syou6162

CLAUDE.md

@@ -521,6 +521,66 @@ Stop:
         decision: "block"
         reason: "Stopping Claude in this directory may lose work context"
 ```
+
+### SubagentStop JSON Output
+
+SubagentStop hooks support JSON output format for Claude Code integration. Actions can return structured output with decision control to block or allow subagent stopping:
+
+**Output Action** (type: `output`):
+```yaml
+SubagentStop:
+  - actions:
+      - type: output
+        message: "SubagentStop reason message"
+        decision: "block"  # optional: "block" only; omit to allow stop
+        reason: "Detailed reason for blocking"  # required when decision is "block"
+```
+
+**Command Action** (type: `command`):
+Commands must output JSON with the following structure:
+```json
+{
+  "continue": true,
+  "decision": "block",
+  "reason": "Detailed reason for blocking",
+  "stopReason": "Optional stop reason",
+  "suppressOutput": false,
+  "systemMessage": "Optional system message"
+}
+```
+
+Note: To allow the subagent stop, omit the `decision` field entirely.
+
+**Important**: SubagentStop uses the same decision control format as Stop hooks. It does NOT use `hookSpecificOutput`. All fields are at the top level.
+
+**Field Merging**:
+When multiple actions execute:
+- `continue`: Always `true` (cannot be changed for SubagentStop)
+- `decision`: Last value wins (early return on `"block"`)
+- `reason`: Reset when decision changes; concatenated with newline within same decision
+- `systemMessage`: Concatenated with newline separator
+- `stopReason` and `suppressOutput`: Last value wins
+
+**Exit Code Behavior**:
+SubagentStop hooks **always exit with code 0**. The `decision` field controls whether the subagent stopping is blocked:
+- `decision` field omitted: SubagentStop proceeds normally
+- `"block"`: SubagentStop is blocked (early return)
+
+Errors are logged to stderr as warnings, but cchook continues to output JSON and exits successfully. On errors, `decision` defaults to `"block"` for safety (fail-safe).
+
+**Example**:
+```yaml
+SubagentStop:
+  - conditions:
+      - type: cwd_contains
+        value: "/important-project"
+    actions:
+      - type: output
+        message: "Cannot stop subagent in important project directory"
+        decision: "block"
+        reason: "Stopping subagent in this directory may lose work context"
+```
+
 ### PostToolUse JSON Output
 
 PostToolUse hooks support JSON output format for Claude Code integration. Actions can return structured output with decision control and additional context:

README.md

@@ -627,18 +627,18 @@ All conditions return proper error messages for unknown condition types, ensurin
   - Print message
   - Default `exit_status`:
     - 0 for SessionStart, SessionEnd, UserPromptSubmit (non-blocking events)
-    - 2 for PostToolUse, SubagentStop, Notification, PreCompact
-  - Note: PreToolUse and Stop use JSON output (exit_status ignored)
+    - 2 for Notification, PreCompact
+  - Note: PreToolUse, Stop, PostToolUse, and SubagentStop use JSON output (exit_status ignored)
 
 ### Exit Status Control
 
-**JSON Output Events** (SessionStart, UserPromptSubmit, PreToolUse, Stop, PostToolUse):
+**JSON Output Events** (SessionStart, UserPromptSubmit, PreToolUse, Stop, SubagentStop, PostToolUse):
 - Always exit with code 0
 - Control behavior via JSON fields (`decision`, `permissionDecision`, etc.)
 - Errors logged to stderr as warnings
 - See CLAUDE.md for detailed JSON output format
 
-**Legacy Exit Code Events** (SubagentStop, Notification, PreCompact, SessionEnd):
+**Legacy Exit Code Events** (Notification, PreCompact, SessionEnd):
 - 0
   - Success, allow execution, output to stdout
 - 2

executor.go

@@ -201,18 +201,162 @@ func (e *ActionExecutor) ExecuteStopAction(action Action, input *StopInput, rawJ
 
 // ExecuteSubagentStopAction executes an action for the SubagentStop event.
 // Command failures result in exit status 2 to block the subagent stop operation.
-func (e *ActionExecutor) ExecuteSubagentStopAction(action Action, input *SubagentStopInput, rawJSON interface{}) error {
+func (e *ActionExecutor) ExecuteSubagentStopAction(action Action, input *SubagentStopInput, rawJSON interface{}) (*ActionOutput, error) {
 	switch action.Type {
 	case "command":
 		cmd := unifiedTemplateReplace(action.Command, rawJSON)
-		if err := e.runner.RunCommand(cmd, action.UseStdin, rawJSON); err != nil {
-			// SubagentStopでコマンドが失敗した場合はexit 2でサブエージェント停止をブロック
-			return NewExitError(2, fmt.Sprintf("Command failed: %v", err), true)
+		stdout, stderr, exitCode, err := e.runner.RunCommandWithOutput(cmd, action.UseStdin, rawJSON)
+
+		// Command failed with non-zero exit code
+		if exitCode != 0 {
+			errMsg := fmt.Sprintf("Command failed with exit code %d: %s", exitCode, stderr)
+			if strings.TrimSpace(stderr) == "" && err != nil {
+				errMsg = fmt.Sprintf("Command failed with exit code %d: %v", exitCode, err)
+			}
+			fmt.Fprintf(os.Stderr, "Warning: %s\n", errMsg)
+			return &ActionOutput{
+				Continue:      true,
+				Decision:      "block",
+				Reason:        errMsg,
+				SystemMessage: errMsg,
+			}, nil
 		}
+
+		// Empty stdout - Allow subagent stop (validation-type CLI tools: silence = OK)
+		if strings.TrimSpace(stdout) == "" {
+			return &ActionOutput{
+				Continue: true,
+				Decision: "", // Allow subagent stop
+			}, nil
+		}
+
+		// Parse JSON output (SubagentStopOutput has no hookSpecificOutput, same schema as Stop)
+		var cmdOutput SubagentStopOutput
+		if err := json.Unmarshal([]byte(stdout), &cmdOutput); err != nil {
+			errMsg := fmt.Sprintf("Command output is not valid JSON: %s", stdout)
+			fmt.Fprintf(os.Stderr, "Warning: %s\n", errMsg)
+			return &ActionOutput{
+				Continue:      true,
+				Decision:      "block",
+				Reason:        errMsg,
+				SystemMessage: errMsg,
+			}, nil
+		}
+
+		// Validate decision field (optional: "block" only, or field must be omitted entirely)
+		decision := cmdOutput.Decision
+		if decision != "" && decision != "block" {
+			errMsg := "Invalid decision value: must be 'block' or field must be omitted entirely"
+			fmt.Fprintf(os.Stderr, "Warning: %s\n", errMsg)
+			return &ActionOutput{
+				Continue:      true,
+				Decision:      "block",
+				Reason:        errMsg,
+				SystemMessage: errMsg,
+			}, nil
+		}
+
+		// Validate reason: required when decision is "block"
+		if decision == "block" && cmdOutput.Reason == "" {
+			errMsg := "Missing required field 'reason' when decision is 'block'"
+			fmt.Fprintf(os.Stderr, "Warning: %s\n", errMsg)
+			return &ActionOutput{
+				Continue:      true,
+				Decision:      "block",
+				Reason:        errMsg,
+				SystemMessage: errMsg,
+			}, nil
+		}
+
+		// Check for unsupported fields and log warnings to stderr
+		checkUnsupportedFieldsSubagentStop(stdout)
+
+		// Build ActionOutput from parsed JSON
+		return &ActionOutput{
+			Continue:       true,
+			Decision:       decision,
+			Reason:         cmdOutput.Reason,
+			StopReason:     cmdOutput.StopReason,
+			SuppressOutput: cmdOutput.SuppressOutput,
+			SystemMessage:  cmdOutput.SystemMessage,
+		}, nil
+
 	case "output":
-		return handleOutput(action.Message, action.ExitStatus, rawJSON)
+		processedMessage := unifiedTemplateReplace(action.Message, rawJSON)
+
+		// Empty message check → fail-safe (decision: block)
+		if strings.TrimSpace(processedMessage) == "" {
+			errMsg := "Empty message in SubagentStop action"
+			fmt.Fprintf(os.Stderr, "Warning: %s\n", errMsg)
+			return &ActionOutput{
+				Continue:      true,
+				Decision:      "block",
+				Reason:        errMsg,
+				SystemMessage: errMsg,
+			}, nil
+		}
+
+		// Warn if exit_status is set (deprecated for SubagentStop in JSON mode)
+		if action.ExitStatus != nil {
+			fmt.Fprintf(os.Stderr, "Warning: exit_status field is deprecated for SubagentStop hooks and will be ignored. Use 'decision' field instead.\n")
+		}
+
+		// Validate action.Decision if set
+		// Default to "" (allow subagent stop)
+		decision := ""
+		if action.Decision != nil {
+			if *action.Decision != "" && *action.Decision != "block" {
+				errMsg := "Invalid decision value in action config: must be 'block' or field must be omitted"
+				fmt.Fprintf(os.Stderr, "Warning: %s\n", errMsg)
+				return &ActionOutput{
+					Continue:      true,
+					Decision:      "block",
+					Reason:        processedMessage,
+					SystemMessage: errMsg,
+				}, nil
+			}
+			decision = *action.Decision
+		}
+
+		// Determine reason with template expansion
+		reason := processedMessage
+		if action.Reason != nil {
+			// Apply template expansion to reason
+			reasonValue := unifiedTemplateReplace(*action.Reason, rawJSON)
+			// Empty/whitespace reason with "block" decision should fallback to processedMessage
+			if strings.TrimSpace(reasonValue) == "" && decision == "block" {
+				reason = processedMessage
+			} else {
+				reason = reasonValue
+			}
+		}
+
+		// For allow (decision=""), clear reason (not applicable)
+		if decision == "" {
+			reason = ""
+		}
+
+		// Final validation: decision "block" requires non-empty reason
+		if decision == "block" && strings.TrimSpace(reason) == "" {
+			errMsg := "Empty reason when decision is 'block' (reason is required for block)"
+			fmt.Fprintf(os.Stderr, "Warning: %s\n", errMsg)
+			return &ActionOutput{
+				Continue:      true,
+				Decision:      "block",
+				Reason:        errMsg,
+				SystemMessage: errMsg,
+			}, nil
+		}
+
+		return &ActionOutput{
+			Continue:      true,
+			Decision:      decision,
+			Reason:        reason,
+			SystemMessage: processedMessage,
+		}, nil
 	}
-	return nil
+
+	return nil, nil
 }
 
 // ExecutePreCompactAction executes an action for the PreCompact event.
@@ -984,6 +1128,31 @@ func checkUnsupportedFieldsStop(stdout string) {
 	}
 }
 
+// checkUnsupportedFieldsSubagentStop checks for unsupported fields in SubagentStop hook output
+// SubagentStop uses the same schema as Stop (no hookSpecificOutput)
+func checkUnsupportedFieldsSubagentStop(stdout string) {
+	var data map[string]interface{}
+	if err := json.Unmarshal([]byte(stdout), &data); err != nil {
+		return
+	}
+
+	supportedFields := map[string]bool{
+		"continue":       true,
+		"decision":       true, // SubagentStop specific (top-level, same as Stop)
+		"reason":         true, // SubagentStop specific (top-level, same as Stop)
+		"stopReason":     true,
+		"suppressOutput": true,
+		"systemMessage":  true,
+		// Note: hookSpecificOutput is NOT supported for SubagentStop hooks
+	}
+
+	for field := range data {
+		if !supportedFields[field] {
+			fmt.Fprintf(os.Stderr, "Warning: Field '%s' is not supported for SubagentStop hooks\n", field)
+		}
+	}
+}
+
 // checkUnsupportedFieldsPostToolUse checks for unsupported fields in PostToolUse hook output
 func checkUnsupportedFieldsPostToolUse(stdout string) {
 	var data map[string]interface{}