The Task plugin provides 2 official hooks for session-level event handling. Internal lifecycle events (task start/completion/iteration) are handled through the Agent's internal logic and do not use the hooks system.
Available Hooks
SessionStart
Trigger: on session start/resume. Purpose: initialize environment variables/load configuration/set up resources.
{"SessionStart": [{"hooks": [{"type": "command", "command": "echo 'export ...' >> \"$CLAUDE_ENV_FILE\"", "async": true}]}]}
SessionEnd
Trigger: on session end. Environment variables:SESSION_ID. Purpose: clean up temporary files/archive logs/generate reports.
Log:.claude/logs/task-hooks-{session_id}.jsonl
Migration notes (v0.0.184)
Removed 6 hooks not officially supported (TaskStart/IterationStart/IterationEnd/TaskComplete/TaskFailed/CheckpointSave). Alternatives:
| Original Hook | New Solution |
|---|---|
| TaskStart | Loop skill output[MindFlow] 任务启动 |
| IterationStart/End | Loop skill iteration log |
| TaskComplete | Finalizer generates report |
| TaskFailed | Adjuster records failure |
| IterationEnd (metrics) | Observability skill |
| CheckpointSave | Checkpoint skill log |
Hook Development Guide
- Input: environment variables (SESSION_ID, etc.) + stdin JSON
- Output: stdout log | stderr error | exit 0=success, 2=block, other=non-blocking
- Best practices: execute in <1 second | async:true | robust error handling | idempotent | default timeout 600s
Troubleshooting
Not triggered: check that the hook name is in the official list/plugin.json configuration/script is executable/path is correct. Failure: check syntax/environment variables/stderr/timeout/permissions.