Skip to content

Commit 4f715d8

Browse files
committed
docs: SessionEnd JSON出力のドキュメント追加
CLAUDE.mdにSessionEnd JSON Outputセクションを追加。 README.mdでSessionEndをJSON Output Eventsに移動、Legacy Exit Code Eventsから削除。 Common JSON Fieldsのみ使用、decision/reason/hookSpecificOutputなし。 cleanup専用フック、セッション終了をブロック不可、常にexit 0。
1 parent 6320ac5 commit 4f715d8

File tree

2 files changed

+63
-3
lines changed

2 files changed

+63
-3
lines changed

CLAUDE.md

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -654,6 +654,66 @@ PostToolUse:
654654
reason: "Sensitive file modified - verify .gitignore configuration"
655655
```
656656

657+
### SessionEnd JSON Output
658+
659+
SessionEnd hooks support JSON output format for Claude Code integration. Actions can return structured output for session cleanup:
660+
661+
**Output Action** (type: `output`):
662+
```yaml
663+
SessionEnd:
664+
- actions:
665+
- type: output
666+
message: "Session cleanup message"
667+
```
668+
669+
**Command Action** (type: `command`):
670+
Commands must output JSON with the following structure:
671+
```json
672+
{
673+
"continue": true,
674+
"stopReason": "Optional stop reason",
675+
"suppressOutput": false,
676+
"systemMessage": "Optional system message"
677+
}
678+
```
679+
680+
**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.
681+
682+
**Field Merging**:
683+
When multiple actions execute:
684+
- `continue`: Always `true` (session end cannot be blocked)
685+
- `systemMessage`: Concatenated with newline separator
686+
- `stopReason` and `suppressOutput`: Last value wins
687+
688+
**Exit Code Behavior**:
689+
SessionEnd hooks **always exit with code 0**. The `continue` field is always `true` because session termination cannot be blocked.
690+
691+
Errors are logged to stderr as warnings, but cchook continues to output JSON and exits successfully. This ensures cleanup actions complete even on errors.
692+
693+
**Message Mapping**:
694+
Output action `message` field is mapped to `systemMessage` (shown to user, not to Claude). This maintains backward compatibility with the old stdout-based implementation.
695+
696+
**Condition Types**:
697+
SessionEnd supports the `reason_is` condition to match session end reasons:
698+
- `"clear"`: User cleared the session
699+
- `"logout"`: User logged out
700+
- `"prompt_input_exit"`: User exited via prompt input
701+
- `"other"`: Other reasons
702+
703+
**Example**:
704+
```yaml
705+
SessionEnd:
706+
- conditions:
707+
- type: reason_is
708+
value: "clear"
709+
actions:
710+
- type: output
711+
message: "Session cleared - workspace cleanup complete"
712+
- actions:
713+
- type: command
714+
command: "cleanup-session.sh" # Returns JSON with systemMessage
715+
```
716+
657717
## Common Workflows
658718

659719
### Adding a New Hook Type

README.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -626,19 +626,19 @@ All conditions return proper error messages for unknown condition types, ensurin
626626
- `output`
627627
- Print message
628628
- Default `exit_status`:
629-
- 0 for SessionStart, SessionEnd, UserPromptSubmit (non-blocking events)
629+
- 0 for SessionStart, UserPromptSubmit (non-blocking events)
630630
- 2 for Notification, PreCompact
631631
- Note: PreToolUse, Stop, PostToolUse, and SubagentStop use JSON output (exit_status ignored)
632632

633633
### Exit Status Control
634634

635-
**JSON Output Events** (SessionStart, UserPromptSubmit, PreToolUse, Stop, SubagentStop, PostToolUse):
635+
**JSON Output Events** (SessionStart, UserPromptSubmit, PreToolUse, Stop, SubagentStop, PostToolUse, SessionEnd):
636636
- Always exit with code 0
637637
- Control behavior via JSON fields (`decision`, `permissionDecision`, etc.)
638638
- Errors logged to stderr as warnings
639639
- See CLAUDE.md for detailed JSON output format
640640

641-
**Legacy Exit Code Events** (Notification, PreCompact, SessionEnd):
641+
**Legacy Exit Code Events** (Notification, PreCompact):
642642
- 0
643643
- Success, allow execution, output to stdout
644644
- 2

0 commit comments

Comments
 (0)