[FEATURE] Let a hook read the session's task list, through its input or a documented file format

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

A hook cannot read the session's task list, the one TaskCreate and TaskUpdate keep, through anything documented.

• PostToolBatch input carries the batch's tool_calls and nothing about the tasks.
• TaskCreated and TaskCompleted input carry only the one task the event is about (task_id, task_subject, task_description).
• The only mention of ~/.claude/tasks/ I found in the docs is one line in the Task list section of the interactive mode page, saying CLAUDE_CODE_TASK_LIST_ID names a directory there. No page describes what is in that directory.

So a hook that needs the list reads Claude Code's own files. On 2.1.291 (macOS) a session's list is the folder ~/.claude/tasks/<session id>/, holding one <id>.json per task with the fields id, subject, description, activeForm, status, blocks and blockedBy, beside a .lock file. Nothing promises that folder, those file names or those fields, so any release can break such a hook.

Proposed Solution

Either of these would do:

1. Put the task list in hook input, for example a tasks array of { id, subject, status } on PostToolBatch, TaskCreated and TaskCompleted.
2. Document the task files as a stable format: which folder holds a session's list, the file names, and the fields with their possible values.

The first is simpler for a hook author, since the hook then never has to work out which folder belongs to its session.

Alternative Solutions

• Read the files as described above, which works today and breaks silently the day the format changes.
• Rebuild the list inside the hook from TaskCreated, TaskCompleted and the TaskUpdate calls seen in PostToolBatch. That keeps a second copy of the list in the hook, which can drift from the real one after any event the hook misses (not tested).

Priority

Low - Nice to have

Feature Category

Developer tools/SDK

Use Case Example

A PostToolBatch hook reminds the session of its open work. After any batch that created or updated a task, it adds one sentence to the context: how many tasks are open, how many of those are in progress, and which open task is the oldest. Without it, in a long session the oldest task can sit untouched for hours while newer requests go ahead.

To do that, the hook reads every task file in the session's folder and counts them by status. It checks the fields it reads and reports loudly when they stop matching, but that only catches a change after it ships.

Additional Context

• Related: #88129 asks for external programs to write to the same task store. This request is only about reading it.

Written by Claude Opus 5.5 in Claude Code, at a user's request.