Merge pull request #63 from syou6162/session_end_json

feat: SessionEnd JSON出力対応

Author: syou6162

CLAUDE.md

@@ -654,6 +654,66 @@ PostToolUse:
         reason: "Sensitive file modified - verify .gitignore configuration"
 ```
 
+### SessionEnd JSON Output
+
+SessionEnd hooks support JSON output format for Claude Code integration. Actions can return structured output for session cleanup:
+
+**Output Action** (type: `output`):
+```yaml
+SessionEnd:
+  - actions:
+      - type: output
+        message: "Session cleanup message"
+```
+
+**Command Action** (type: `command`):
+Commands must output JSON with the following structure:
+```json
+{
+  "continue": true,
+  "stopReason": "Optional stop reason",
+  "suppressOutput": false,
+  "systemMessage": "Optional system message"
+}
+```
+
+**Important**: SessionEnd uses **Common JSON Fields only**. Unlike other events, it has no `decision`, `reason`, or `hookSpecificOutput` fields. SessionEnd is a cleanup-only hook and **cannot block** session termination.
+
+**Field Merging**:
+When multiple actions execute:
+- `continue`: Always `true` (session end cannot be blocked)
+- `systemMessage`: Concatenated with newline separator
+- `stopReason` and `suppressOutput`: Last value wins
+
+**Exit Code Behavior**:
+SessionEnd hooks **always exit with code 0**. The `continue` field is always `true` because session termination cannot be blocked.
+
+Errors are logged to stderr as warnings, but cchook continues to output JSON and exits successfully. This ensures cleanup actions complete even on errors.
+
+**Message Mapping**:
+Output action `message` field is mapped to `systemMessage` (shown to user, not to Claude). This maintains backward compatibility with the old stdout-based implementation.
+
+**Condition Types**:
+SessionEnd supports the `reason_is` condition to match session end reasons:
+- `"clear"`: User cleared the session
+- `"logout"`: User logged out
+- `"prompt_input_exit"`: User exited via prompt input
+- `"other"`: Other reasons
+
+**Example**:
+```yaml
+SessionEnd:
+  - conditions:
+      - type: reason_is
+        value: "clear"
+    actions:
+      - type: output
+        message: "Session cleared - workspace cleanup complete"
+  - actions:
+      - type: command
+        command: "cleanup-session.sh"  # Returns JSON with systemMessage
+```
+
 ## Common Workflows
 
 ### Adding a New Hook Type

README.md

@@ -626,19 +626,19 @@ All conditions return proper error messages for unknown condition types, ensurin
 - `output`
   - Print message
   - Default `exit_status`:
-    - 0 for SessionStart, SessionEnd, UserPromptSubmit (non-blocking events)
+    - 0 for SessionStart, UserPromptSubmit (non-blocking events)
     - 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, SubagentStop, PostToolUse):
+**JSON Output Events** (SessionStart, UserPromptSubmit, PreToolUse, Stop, SubagentStop, PostToolUse, SessionEnd):
 - 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** (Notification, PreCompact, SessionEnd):
+**Legacy Exit Code Events** (Notification, PreCompact):
 - 0
   - Success, allow execution, output to stdout
 - 2

actions_test.go

@@ -288,76 +288,6 @@ func TestNewExitError(t *testing.T) {
 	}
 }
 
-func TestExecuteSessionEndAction_WithExitError(t *testing.T) {
-	action := Action{
-		Type:       "output",
-		Message:    "SessionEnd error message",
-		ExitStatus: intPtr(2),
-	}
-
-	executor := NewActionExecutor(nil)
-	err := executor.ExecuteSessionEndAction(action, &SessionEndInput{}, map[string]interface{}{})
-
-	if err == nil {
-		t.Fatal("Expected ExitError, got nil")
-	}
-
-	exitErr, ok := err.(*ExitError)
-	if !ok {
-		t.Fatalf("Expected *ExitError, got %T", err)
-	}
-
-	if exitErr.Code != 2 {
-		t.Errorf("Expected exit code 2, got %d", exitErr.Code)
-	}
-
-	if !exitErr.Stderr {
-		t.Error("Expected stderr output")
-	}
-}
-
-func TestExecuteSessionEndAction_OutputWithDefaultExitStatus(t *testing.T) {
-	tests := []struct {
-		name       string
-		exitStatus *int
-		wantErr    bool
-	}{
-		{
-			name:       "nil ExitStatus should print without error",
-			exitStatus: nil,
-			wantErr:    false,
-		},
-		{
-			name:       "ExitStatus 0 should print without error",
-			exitStatus: intPtr(0),
-			wantErr:    false,
-		},
-	}
-
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			action := Action{
-				Type:       "output",
-				Message:    "SessionEnd message",
-				ExitStatus: tt.exitStatus,
-			}
-
-			executor := NewActionExecutor(nil)
-			err := executor.ExecuteSessionEndAction(action, &SessionEndInput{}, map[string]interface{}{})
-
-			if tt.wantErr {
-				if err == nil {
-					t.Error("Expected error, got nil")
-				}
-			} else {
-				if err != nil {
-					t.Errorf("Expected no error, got %v", err)
-				}
-			}
-		})
-	}
-}
-
 func TestExecuteNotificationAction_CommandWithStubRunner(t *testing.T) {
 	tests := []struct {
 		name      string

executor.go

@@ -1007,25 +1007,85 @@ func (e *ActionExecutor) ExecutePostToolUseAction(action Action, input *PostTool
 	return nil, nil
 }
 
-// ExecuteSessionEndAction executes an action for the SessionEnd event.
-// Errors are logged but do not block session end.
-func (e *ActionExecutor) ExecuteSessionEndAction(action Action, input *SessionEndInput, rawJSON interface{}) error {
+// ExecuteSessionEndAction executes an action for the SessionEnd event and returns ActionOutput.
+// SessionEnd always returns continue=true (fail-safe: session end cannot be blocked).
+// Errors are reported via systemMessage field, not by blocking execution.
+func (e *ActionExecutor) ExecuteSessionEndAction(action Action, input *SessionEndInput, 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 {
-			return err
+		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,
+				SystemMessage: errMsg,
+			}, nil
 		}
+
+		// Empty stdout - Allow session end (validation-type CLI tools: silence = OK)
+		if strings.TrimSpace(stdout) == "" {
+			return &ActionOutput{
+				Continue: true,
+			}, nil
+		}
+
+		// Parse JSON output (SessionEndOutput has Common JSON Fields only)
+		var cmdOutput SessionEndOutput
+		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,
+				SystemMessage: errMsg,
+			}, nil
+		}
+
+		// Check for unsupported fields and log warnings to stderr
+		checkUnsupportedFieldsSessionEnd(stdout)
+
+		// Build ActionOutput from parsed JSON
+		return &ActionOutput{
+			Continue:       true,
+			StopReason:     cmdOutput.StopReason,
+			SuppressOutput: cmdOutput.SuppressOutput,
+			SystemMessage:  cmdOutput.SystemMessage,
+		}, nil
+
 	case "output":
-		// SessionEndはブロッキング不要なので、exitStatusが指定されていない場合は通常出力
 		processedMessage := unifiedTemplateReplace(action.Message, rawJSON)
-		if action.ExitStatus != nil && *action.ExitStatus != 0 {
-			stderr := *action.ExitStatus == 2
-			return NewExitError(*action.ExitStatus, processedMessage, stderr)
+
+		// Emit warning if exit_status is set (backward compatibility - no longer used)
+		if action.ExitStatus != nil {
+			fmt.Fprintf(os.Stderr, "Warning: exit_status field is ignored in SessionEnd output actions (JSON output does not use exit codes)\n")
 		}
-		fmt.Println(processedMessage)
+
+		// Empty message is an error (fail-safe)
+		if strings.TrimSpace(processedMessage) == "" {
+			errMsg := "Empty message in SessionEnd action"
+			fmt.Fprintf(os.Stderr, "Warning: %s\n", errMsg)
+			return &ActionOutput{
+				Continue:      true,
+				SystemMessage: errMsg,
+			}, nil
+		}
+
+		// Output action: message maps to systemMessage
+		return &ActionOutput{
+			Continue:      true,
+			SystemMessage: processedMessage,
+		}, nil
 	}
-	return nil
+
+	return &ActionOutput{
+		Continue: true,
+	}, nil
 }
 
 // checkUnsupportedFieldsSessionStart checks for unsupported fields in SessionStart JSON output
@@ -1153,6 +1213,29 @@ func checkUnsupportedFieldsSubagentStop(stdout string) {
 	}
 }
 
+// checkUnsupportedFieldsSessionEnd checks for unsupported fields in SessionEnd hook output
+// SessionEnd uses Common JSON Fields only (no decision/reason/hookSpecificOutput)
+func checkUnsupportedFieldsSessionEnd(stdout string) {
+	var data map[string]interface{}
+	if err := json.Unmarshal([]byte(stdout), &data); err != nil {
+		return
+	}
+
+	supportedFields := map[string]bool{
+		"continue":       true,
+		"stopReason":     true,
+		"suppressOutput": true,
+		"systemMessage":  true,
+		// Note: decision, reason, hookSpecificOutput are NOT supported for SessionEnd hooks
+	}
+
+	for field := range data {
+		if !supportedFields[field] {
+			fmt.Fprintf(os.Stderr, "Warning: Field '%s' is not supported for SessionEnd hooks\n", field)
+		}
+	}
+}
+
 // checkUnsupportedFieldsPostToolUse checks for unsupported fields in PostToolUse hook output
 func checkUnsupportedFieldsPostToolUse(stdout string) {
 	var data map[string]interface{}