The learning-agents plugin uses hooks to automatically track when LearningAgents are invoked during Claude Code sessions. The PostToolUse hook on the Agent tool creates session tracking files. The Stop hook checks for unprocessed sessions and suggests running the learning cycle.
The PostToolUse hook MUST fire after every use of the Agent tool. The hook matcher in hooks.json MUST be set to "Agent".
The post_task.sh hook MUST read JSON from stdin containing session_id, tool_input, and tool_response fields. If stdin is empty or not provided (terminal is interactive), the hook MUST output {} and exit 0.
The hook MUST extract session_id from the hook input JSON via .session_id. If session_id is missing or empty, the hook MUST output {} and exit 0.
The hook MUST extract the agent name from .tool_input.name in the hook input JSON. If the agent name is missing or empty, the hook MUST output {} and exit 0.
The hook MUST extract the agent ID from .tool_response.agentId (falling back to .tool_response.agent_id) in the hook input JSON. If the agent ID is missing or empty, the hook MUST output {} and exit 0.
The hook MUST check whether .deepwork/learning-agents/<agent-name>/ exists. If the directory does NOT exist, the Task was not for a LearningAgent and the hook MUST output {} and exit 0 without creating any files.
When a LearningAgent is detected, the hook MUST create the directory .deepwork/tmp/agent_sessions/<session_id>/<agent_id>/ (including all parent directories).
The hook MUST create a needs_learning_as_of_timestamp file in the session directory containing a single ISO 8601 UTC timestamp (format: YYYY-MM-DDTHH:MM:SSZ). This file serves as a flag indicating that the session transcript has not yet been processed for learnings.
The hook MUST create an agent_used file in the session directory containing the agent name (matching the folder name under .deepwork/learning-agents/). This links the session's agent ID back to the LearningAgent definition.
After creating session tracking files, the hook MUST output a JSON systemMessage containing the content of ${CLAUDE_PLUGIN_ROOT}/doc/learning_agent_post_task_reminder.md. If the reminder file does not exist, the hook MUST output {}.
The post-task reminder MUST instruct the user to:
- Resume the same task rather than starting a new one if they need more from the same agent
- Report issues via
/learning-agents report_issueor by resuming the conversation if the agent made a mistake
The Stop hook MUST fire at session end. The hook matcher in hooks.json MUST be set to an empty string ("") so it triggers for all stop events.
If .deepwork/tmp/agent_sessions does not exist, the stop hook MUST output {} and exit 0.
The stop hook MUST search for all needs_learning_as_of_timestamp files under .deepwork/tmp/agent_sessions/. If none are found, it MUST output {} and exit 0.
For each pending session found, the stop hook MUST read the corresponding agent_used file to determine which agent was used. It MUST deduplicate agent names before including them in the suggestion message.
When pending sessions exist, the stop hook MUST output a JSON systemMessage that:
- Lists the unique agent names that were used
- Suggests running
/learning-agents learnto process the transcripts
All session tracking files MUST be stored under .deepwork/tmp/agent_sessions/. The .deepwork/tmp/ directory is intended for transient working files and MAY be gitignored.
The needs_learning_as_of_timestamp file MUST be overwritten (not appended) each time the same agent is used in the same session. The timestamp reflects the most recent invocation.