Hook for phase boundary recap reminders

[acreeger]

Summary

Add a hook that fires when iloom agents complete, reminding the orchestrator to capture any decisions, insights, risks, or assumptions from that phase that weren't already logged.

Motivation

The prompts (#347) tell Claude to log things proactively as they happen. But Claude may forget during long phases. The hook provides a "backstop" - a reminder at each phase boundary to capture anything that was missed.

The hook reminder can be specific about what to look for, making it easy for the orchestrator to distill the key points from the agent's output.

Proposed Implementation

Hook Trigger

Fire when an agent task completes, filtered to iloom agents:

• Agent name contains "iloom" (e.g., iloom-issue-enhancer, iloom-issue-analyzer, etc.)

Reminder Content

Inject a reminder to the orchestrator like:

The {agent-name} phase just completed. Before continuing, review the agent's output and use the Recap MCP to capture any:
- **Decisions** made during this phase
- **Insights** discovered about the codebase or problem
- **Risks** identified that could affect the solution
- **Assumptions** made about requirements or approach

Only log things not already captured. Keep entries concise.

Configuration

Make this optional in settings:

{
  "recap": {
    "phaseReminders": true  // default: true
  }
}

Alternative: Periodic Reminder

Consider also a periodic reminder (every N minutes or N tool calls) if no recap entry has been added recently. This is lower priority than phase boundary reminders.

Acceptance Criteria

• Hook fires when iloom agents complete
• Reminder text is injected to orchestrator
• Reminder is specific about what to capture
• Can be disabled via settings
• Works with all iloom agents (enhancer, analyzer, planner, implementer, etc.)

Related

• Loom Recap MCP Server #346 - Loom Recap MCP Server (provides the tools)
• Update prompts to use Loom Recap MCP #347 - Prompt updates (proactive capture)
• iloom-vscode#43 - POC Loom Context Panel (displays the data)

[acreeger]

Complexity Assessment

Classification: SIMPLE

Metrics:

• Estimated files affected: 4
• Estimated lines of code: 180
• Breaking changes: No
• Database migrations: No
• Cross-cutting changes: No
• File architecture quality: Good - all target files are well-structured
• Overall risk level: Low

Reasoning: This feature adds an optional hook configuration to remind orchestrators to capture recap entries at phase boundaries. The implementation involves minor additions to existing settings schema and hook configuration, with no breaking changes or cross-cutting concerns. All target files are well-maintained and straightforward to modify.

[acreeger]

Combined Analysis & Plan - Issue #348

Executive Summary

Add a SubagentStop hook that fires when iloom agents complete, reminding the orchestrator to capture recap entries (decisions, insights, risks, assumptions). The hook reads the transcript to identify the agent name, checks if recap.phaseReminders is enabled in settings, and outputs plain text that gets added to Claude's context as a non-blocking reminder.

Questions and Key Decisions (if applicable)

Question	Answer
How to identify iloom agents from SubagentStop?	Parse the hook input - the subagent_type field contains the agent name directly
How to inject reminder text to orchestrator?	Output plain text to stdout (non-JSON) - Claude Code adds this as context to the conversation without blocking
Where to read settings from?	Read .iloom/settings.json from cwd provided in hook input
How to prevent infinite loops?	Check stop_hook_active flag - if true, skip the reminder

Implementation Overview

High-Level Execution Phases

1. Schema Update: Add recap.phaseReminders to SettingsManager.ts Zod schemas
2. Hook Enhancement: Modify iloom-hook.js to handle SubagentStop for iloom agents with settings check
3. Tests: Add unit tests for hook logic and schema validation
4. Documentation: Update README.md with new configuration option

Quick Stats

• 3 files to modify
• 0 new files to create
• 0 files to delete
• Dependencies: None

---

Complete Analysis & Implementation Details (click to expand)

Research Findings

Problem Space

• Problem: Claude may forget to capture recap entries during long phases; hook provides a backstop reminder at phase boundaries
• Architectural context: Hooks fire via Claude Code's SubagentStop event; plain text output gets added to Claude's context as a non-blocking reminder
• Edge cases: Must not trigger for non-iloom agents; must respect disabled setting; must check stop_hook_active to avoid infinite loops

Third-Party Research

• Claude Code Hooks: SubagentStop hook receives subagent_type in hook input. Plain text stdout (non-JSON, exit code 0) gets added as context to Claude's conversation (Source: Claude Code Hooks Docs)
• Non-blocking reminders: Output plain text to stdout - it's added to Claude's context without blocking the agent

Codebase Research

• Entry point: /templates/hooks/iloom-hook.js:119-148 - mapEventToStatus() currently skips SubagentStop (returns null)
• Settings schema: /src/lib/SettingsManager.ts:218-377 - IloomSettingsSchema needs recap section added
• Hook installer: /src/lib/ClaudeHookManager.ts:252-280 - already registers SubagentStop hook event
• Similar pattern: Attribution setting at /src/lib/SettingsManager.ts:368-376 shows pattern for optional config with default

Affected Files

• /src/lib/SettingsManager.ts:368-547 - Add recap schema section with phaseReminders boolean
• /templates/hooks/iloom-hook.js:119-258 - Add SubagentStop handling with settings check
• /src/lib/SettingsManager.test.ts - Add tests for recap settings validation

Integration Points

• Hook reads subagent_type from hook input to identify agent name
• Hook reads .iloom/settings.json from cwd provided in hook input
• Hook outputs plain text reminder to stdout (non-JSON) which gets added as context

---

Implementation Plan

Automated Test Cases to Create

Test File: /src/lib/SettingsManager.test.ts (MODIFY)

// Add to existing describe('SettingsManager')
describe('recap settings', () => {
  it('should default phaseReminders to true')
  it('should accept phaseReminders: false') 
  it('should validate recap is optional object')
})

Files to Modify

1. /src/lib/SettingsManager.ts:368-377

Change: Add recap schema section with phaseReminders boolean (default: true) after the attribution field

Add to IloomSettingsSchema after line 376:

recap: z
  .object({
    phaseReminders: z
      .boolean()
      .default(true)
      .describe(
        'Show phase boundary recap reminders when iloom agents complete. ' +
        'Reminds the orchestrator to capture decisions, insights, risks, and assumptions.'
      ),
  })
  .optional()
  .describe('Recap MCP configuration for capturing session context'),

Add matching non-defaulting schema to IloomSettingsSchemaNoDefaults after line 546:

recap: z
  .object({
    phaseReminders: z
      .boolean()
      .optional()
      .describe('Show phase boundary recap reminders when iloom agents complete'),
  })
  .optional()
  .describe('Recap MCP configuration'),

2. /templates/hooks/iloom-hook.js:119-258

Change: Add SubagentStop handling for iloom agents with settings check, outputting plain text reminder

Click to expand complete hook changes (~50 lines)

// Add after line 110 (after findAllIloomSockets function):

/**
 * Read .iloom/settings.json from workspace directory
 * @param {string} cwd - Workspace directory
 * @returns {object} Settings object or empty default
 */
function readIloomSettings(cwd) {
  try {
    const settingsPath = path.join(cwd, '.iloom', 'settings.json');
    if (!fs.existsSync(settingsPath)) {
      return { recap: { phaseReminders: true } }; // Default
    }
    const content = fs.readFileSync(settingsPath, 'utf8');
    return JSON.parse(content);
  } catch {
    return { recap: { phaseReminders: true } }; // Default on error
  }
}

/**
 * Handle SubagentStop for iloom agents - output plain text reminder
 * @param {object} hookData - Hook input data
 * @returns {string|null} Reminder text or null to skip
 */
function handleSubagentStop(hookData) {
  // Prevent infinite loops
  if (hookData.stop_hook_active) {
    return null;
  }
  
  const agentName = hookData.subagent_type;
  debug('SubagentStop for agent', { agentName });
  
  // Only handle iloom agents
  if (!agentName || !agentName.includes('iloom')) {
    return null;
  }
  
  // Check settings
  const cwd = hookData.cwd;
  if (cwd) {
    const settings = readIloomSettings(cwd);
    const phaseReminders = settings?.recap?.phaseReminders ?? true;
    if (!phaseReminders) {
      debug('Phase reminders disabled');
      return null;
    }
  }
  
  // Return plain text reminder (non-blocking)
  const friendlyName = agentName.replace('iloom-', '').replace(/-/g, ' ');
  return `📋 **Phase Recap Reminder**: The ${friendlyName} phase just completed. Before continuing, consider using the Recap MCP to capture any:
- **Decisions** made during this phase
- **Insights** discovered about the codebase or problem
- **Risks** identified that could affect the solution
- **Assumptions** made about requirements or approach

Only log things not already captured. Keep entries concise.`;
}

// Modify main() to handle SubagentStop specially (around line 222):
// In main(), after checking ILOOM env var and parsing hookData:

if (hook_event_name === 'SubagentStop') {
  const reminder = handleSubagentStop(hookData);
  if (reminder) {
    // Output plain text (non-JSON) - added to Claude's context
    console.log(reminder);
  }
  process.exit(0);
}

// Continue with existing broadcast logic for other events...

3. /src/lib/SettingsManager.test.ts

Change: Add test cases for recap settings schema validation

describe('recap settings', () => {
  it('should default phaseReminders to true when recap not specified', async () => {
    // Create settings without recap
    // Load and verify recap.phaseReminders defaults to true
  })

  it('should accept recap.phaseReminders: false', async () => {
    // Create settings with recap.phaseReminders: false
    // Verify it loads correctly without error
  })

  it('should validate recap as optional object', async () => {
    // Verify recap can be omitted entirely
    // Verify recap: {} is valid
  })
})

Detailed Execution Order

Phase 1: Schema Update

1. Add recap schema to IloomSettingsSchema in /src/lib/SettingsManager.ts after line 376 -> Verify: TypeScript compiles
2. Add matching schema to IloomSettingsSchemaNoDefaults after line 546 -> Verify: No defaults applied before merge
3. Run pnpm build -> Verify: Compiles successfully

Phase 2: Settings Tests

1. Add recap settings tests to /src/lib/SettingsManager.test.ts -> Verify: pnpm test src/lib/SettingsManager.test.ts passes

Phase 3: Hook Enhancement

1. Add readIloomSettings(cwd) function to /templates/hooks/iloom-hook.js -> Verify: Reads .iloom/settings.json
2. Add handleSubagentStop(hookData) function with settings check -> Verify: Returns plain text for iloom agents
3. Modify main() to handle SubagentStop before broadcast logic -> Verify: Outputs plain text reminder

Phase 4: Final Build & Verify

1. Run pnpm build -> Verify: Compiles successfully and copies hook template to dist
2. Manual test: Create loom, run agent, verify reminder appears -> Verify: Reminder shows when phaseReminders: true
3. Manual test: Set recap.phaseReminders: false, verify no reminder -> Verify: Setting respected

Dependencies and Configuration

None

---

Analysis and Planning Status: Complete (Updated to use non-blocking reminder mechanism)

Sources:

• Claude Code Hooks Documentation

[acreeger]

Implementation Complete - Issue #348

Summary

Added a SubagentStop hook that fires when iloom agents complete, outputting a plain text reminder to the orchestrator to capture recap entries (decisions, insights, risks, assumptions). The hook reads settings from .iloom/settings.json and respects the recap.phaseReminders configuration (defaults to true).

Changes Made

• src/lib/SettingsManager.ts: Added recap schema section with phaseReminders boolean (default: true)
• templates/hooks/iloom-hook.js: Added readIloomSettings() and handleSubagentStop() functions, modified main() to handle SubagentStop
• src/lib/SettingsManager.test.ts: Added 4 test cases for recap settings validation

Validation Results

• Tests: 3003 passed / 3004 total (1 skipped)
• Typecheck: Passed
• Lint: Passed

---

Detailed Changes by File (click to expand)

Files Modified

/src/lib/SettingsManager.ts

Changes: Added recap schema to both IloomSettingsSchema and IloomSettingsSchemaNoDefaults

• Added recap.phaseReminders boolean field with default true
• Follows the pattern of existing settings like attribution

/templates/hooks/iloom-hook.js

Changes: Added SubagentStop handling with settings check

• readIloomSettings(cwd): Reads .iloom/settings.json and returns settings or default
• handleSubagentStop(hookData): Checks for iloom agents, reads settings, returns plain text reminder
• Modified main(): Handles SubagentStop before broadcast logic, outputs plain text to stdout

/src/lib/SettingsManager.test.ts

Changes: Added recap settings test cases

• Tests for omitting recap (undefined, hook applies default)
• Tests for explicit phaseReminders: false
• Tests for empty recap object (default applied)
• Tests for local settings override

Configuration

To disable phase reminders, add to .iloom/settings.json:

{
  "recap": {
    "phaseReminders": false
  }
}

[acreeger]

Hook should reinforce recap quality, not just remind to log

The hook text should include the quality filter, not just a reminder to add entries.

Example hook reminder:

Before continuing, check if this phase produced anything worth capturing in the recap:

• A decision that affects the codebase?
• An insight someone picking this up later would need?
• A risk or assumption?

Do NOT log: workflow progress, phases skipped, complexity classifications, or status updates.

This acts as a backstop against process-log entries.

[acreeger]

Stronger hook language

The hook must be blunt. Suggested text:

Recap check: Did this phase produce anything the USER would want to know?

✅ Add if: architectural choice, non-obvious discovery, risk, assumption
❌ SKIP if: phase skipped, complexity classification, "tests pass", anything about YOUR process

The recap is for the USER, not a log of your workflow.

[acreeger]

Implementation In Progress

Fixing the phase recap reminder implementation to use environment variables instead of reading settings files directly in the hook.

Tasks

• Remove readIloomSettings() function from /templates/hooks/iloom-hook.js
• Update handleSubagentStop() to check ILOOM_RECAP_PHASE_REMINDERS env var
• Update /src/commands/ignite.ts to inject ILOOM_RECAP_PHASE_REMINDERS env var based on settings
• Run validation (typecheck, tests, lint)

ETA: ~10 minutes

[acreeger]

Implementation Complete - Issue #348 (Fix)

Summary

Fixed premature process.exit(0) issue in /templates/hooks/iloom-hook.js that was preventing other SubagentStop handlers from running. Also removed the unused friendlyName variable that was causing a lint warning.

Changes Made

• templates/hooks/iloom-hook.js: Removed process.exit(0) after SubagentStop handling, allowing code flow to continue to broadcast logic
• templates/hooks/iloom-hook.js: Removed unused friendlyName variable (line 141)

Validation Results

• Tests: 3003 passed / 3004 total (1 skipped)
• Typecheck: Passed
• Lint: Passed

---

Detailed Changes by File (click to expand)

Files Modified

/templates/hooks/iloom-hook.js

Changes: Fixed premature exit and removed unused variable

1. Line 141: Removed unused friendlyName variable assignment

   • Before: const friendlyName = agentName.replace('iloom-', '').replace(/-/g, ' ');
   • After: Removed (reminder text doesn't use the friendly name)

2. Lines 265-275: Removed process.exit(0) call after SubagentStop handling

   • Before: Called process.exit(0) immediately after outputting reminder
   • After: Code continues to allow other processing (e.g., broadcasting) to occur
   • Added comment explaining the change

[acreeger]

Implementation Complete - Issue #348

Summary

Switched the phase recap reminder hook from SubagentStop to PostToolUse with a Task matcher. The hook now fires after Task tool completion, outputting recap reminders to the parent agent via hookSpecificOutput.additionalContext.

Changes Made

• templates/hooks/iloom-hook.js: Renamed handleSubagentStop to handleTaskPostToolUse, changed detection from agent_id parsing to hookData.tool_name === 'Task', changed output format from {decision: 'block', reason: ...} to {hookSpecificOutput: {hookEventName: 'PostToolUse', additionalContext: ...}}
• Updated main() to handle PostToolUse for Task tools instead of SubagentStop
• src/lib/ClaudeHookManager.ts: No changes needed - PostToolUse already registered with matcher: '*'

Validation Results

• Build: Passed (pnpm build succeeded)

---

Detailed Changes by File (click to expand)

Files Modified

templates/hooks/iloom-hook.js

Changes: Switched recap reminder from SubagentStop to PostToolUse for Task tools

• Renamed handleSubagentStop to handleTaskPostToolUse
• Changed detection: now checks hookData.tool_name === 'Task' instead of parsing transcript for agent_id
• Gets subagent_type directly from hookData.tool_input?.subagent_type
• Changed output format from {decision: 'block', reason: ...} to {hookSpecificOutput: {hookEventName: 'PostToolUse', additionalContext: ...}}
• Updated main() to call handleTaskPostToolUse on PostToolUse events when tool_name === 'Task'
• Updated file header comments to reflect new behavior
• Kept findSubagentType function (unused but retained for potential future use)
• Kept existing debug logging to RECAP_LOG_FILE

src/lib/ClaudeHookManager.ts

Changes: None required - PostToolUse already registered with matcher: '*' at line 271-273

[acreeger]

iloom Session Summary

Key Themes:

• Claude Code hooks don't provide a mechanism to pass information from subagents back to parent orchestrators
• SubagentStop hook output goes to the subagent itself, not the parent agent (explicitly documented behavior)
• PostToolUse with Task matcher fires for parent but additionalContext doesn't appear in conversation
• Environment variable injection and settings schema work correctly, but hook mechanism is fundamentally blocked

---

Session Details (click to expand)

Key Insights

• Hook output destinations are event-specific: Research into Claude Code documentation revealed that SubagentStop hooks explicitly send their output (including decision: "block" with reason) to the subagent, not the parent orchestrator
• PostToolUse fires at the right time but doesn't work: The PostToolUse hook with Task matcher fires for the parent agent after a subagent completes, but the hookSpecificOutput.additionalContext field doesn't actually appear in the parent's conversation
• Agent ID is available in hookData: The agent_id field exists in SubagentStop hookData and can be matched against toolUseResult.agentId in the parent transcript to identify which Task call spawned the agent
• Tool input is directly available in PostToolUse: When using PostToolUse for Task tools, hookData.tool_input.subagent_type is directly accessible, eliminating the need for transcript parsing

Decisions Made

• Use environment variable instead of reading settings file in hook: Hooks should read ILOOM_RECAP_PHASE_REMINDERS env var rather than parsing .iloom/settings.json, since the env var is automatically passed through to hooks and avoids file I/O complexity
• Non-blocking reminder approach (initially): Started with plain text output to avoid disrupting subagent flow, but switched to blocking when plain text had no effect
• Switch from SubagentStop to PostToolUse: After discovering SubagentStop only communicates with the subagent, pivoted to PostToolUse with Task matcher which fires for the parent agent
• Transcript parsing for agent matching: Built logic to parse parent transcript JSONL, map Task tool_use IDs to subagent_types, and match via toolUseResult.agentId (later became unnecessary with PostToolUse approach)

Challenges Encountered

• Missing subagent_type in hookData: SubagentStop hookData doesn't include the subagent_type field, requiring transcript parsing to determine which agent stopped. Workaround involved parsing the parent transcript to find Task tool calls and matching by agent_id
• Hook output not reaching parent agent: Multiple attempts to surface reminders to the parent orchestrator all failed:
  • Plain text stdout from SubagentStop: No effect
  • decision: "block" with reason from SubagentStop: Only visible to subagent
  • hookSpecificOutput.additionalContext from PostToolUse: Hook fires but context doesn't appear
• Build/copy workflow confusion: Hook template changes weren't appearing in ~/.claude/hooks/ because updates require rebuild + il spin to copy from dist/hooks/ to global config

Lessons Learned

• Read hook documentation thoroughly before implementation: The Claude Code hooks documentation explicitly states SubagentStop output goes to the subagent. This could have saved several implementation attempts
• Hooks have limited capability for cross-agent communication: There may not be a supported way to inject context from a completed subagent into the parent's conversation via hooks
• Manual hook copying breaks workflow: Manually copying hooks to ~/.claude/hooks/ circumvents the content comparison in ClaudeHookManager.installHookScript() and causes confusion about which version is active
• Debug logging to separate files is essential: Using RECAP_LOG_FILE separate from main hook log made it much easier to trace the specific logic flow for recap reminders

Implementation Artifacts

The branch contains working code for:

• Settings schema with recap.phaseReminders boolean (default: true)
• Environment variable injection in ignite.ts
• PostToolUse hook handler that detects iloom agents via tool_input.subagent_type
• Comprehensive debug logging to /tmp/iloom-recap-hook.log
• Tests for recap settings validation

The hook fires correctly and detects iloom agents, but the additionalContext mechanism doesn't actually surface content to the parent agent.

---

Generated with 🤖❤️ by iloom.ai