feat: subagent hooks, wildcards, timeouts, token optimization (v2.0.2)

[ojowwalker77]

New Features:

• SubagentStart hook: inject Matrix guidance when subagents spawn
• SubagentStop hook: track subagent completion
• Wildcard support in warning rules (glob patterns)
• Hook timeout configuration (default 30s, max 120s)
• Index tools accessible from any directory via repoPath
• Auto-install file-suggestion.sh script

Token Optimization:

• ~10-12% reduction in MCP tool definition tokens
• Shortened parameter descriptions across all schemas

Bug Fixes:

• Improved doctor diagnostics for subagent hooks
• Better validation for timeout configurations

[github-actions]

Version files synced to 2.0.2 from CHANGELOG.md

[github-actions]

Version files synced to 2.0.2 from CHANGELOG.md

[greptile-apps]

Greptile Summary

This PR introduces v2.0.2 with significant enhancements to Matrix's hook system and token optimization. The implementation adds SubagentStart/Stop hooks that inject Matrix-specific guidance when Claude Code spawns subagents (Explore, Plan agents), ensuring they prefer Matrix index tools and Context7 over generic alternatives.

Key Changes:

• Subagent Hooks: New SubagentStart hook injects context-aware guidance to subagents, promoting Matrix tools (matrix_find_definition, matrix_search_symbols) over Grep, and Context7 over WebSearch. The SubagentStop hook tracks completion.
• Token Optimization: Achieved ~10-12% reduction in MCP tool definition tokens by shortening parameter descriptions across all schemas while preserving clarity.
• Index Tools Accessibility: Index tools now visible from any directory with repoPath parameter support, enabling cross-repository queries.
• Timeout Configuration: Leverages Claude Code 2.1.3's 10-minute timeout limit, increasing critical hook timeouts (UserPromptSubmit: 60s→600s, PreCompact: 30s→600s).
• Wildcard Support: Simplified hook matchers using mcp__plugin_matrix_matrix__* wildcards instead of listing individual tools.
• Auto-Install: Session start now auto-installs file-suggestion.sh script and migrates config to v2.0+ structure.
• Config Improvements: Refactored gitCommitReview config with clearer structure (suggestOnCommit, defaultMode), added delegation config for model selection, and properly implemented memoryInjection config.

Code Quality:

• Clean implementation with proper error handling and exit codes
• Tests updated to reflect new behavior
• Comprehensive CHANGELOG documentation
• Backward compatible with graceful fallbacks

Confidence Score: 5/5

• This PR is safe to merge with no blocking issues
• All changes are well-structured, properly tested, and maintain backward compatibility. The new hooks follow established patterns, token optimizations preserve functionality, and config migrations are safe with defaults.
• No files require special attention

Important Files Changed

Filename	Overview
src/hooks/subagent-start.ts	New hook implementation that injects Matrix guidance when subagents start. Clean implementation with proper error handling and verbosity control.
src/hooks/subagent-stop.ts	New hook for tracking subagent completion. Simple, clean implementation with appropriate logging.
hooks/hooks.json	Added SubagentStart/Stop hooks with proper timeouts, increased critical hook timeouts, simplified matchers with wildcards.
src/config/index.ts	Refactored gitCommitReview config with improved structure, added delegation config for model selection.
src/tools/validation.ts	Optimized parameter descriptions for token reduction (~10-12% savings). All functionality preserved.
src/tools/schemas.ts	Changed index tools visibility to 'always' (support repoPath parameter), shortened descriptions for token savings.
src/hooks/session-start.ts	Added auto-install for file-suggestion.sh script and config migration for v2.0+ sections. Well-structured upgrade logic.
src/index.ts	Made delegation instructions configurable based on delegation.enabled and delegation.model settings.

Sequence Diagram

sequenceDiagram
    participant User
    participant ClaudeCode
    participant SessionStart
    participant SubagentStart
    participant Subagent
    participant SubagentStop
    participant UserPromptSubmit

    User->>ClaudeCode: Start session
    ClaudeCode->>SessionStart: Hook: SessionStart
    SessionStart->>SessionStart: ensureConfigComplete()
    SessionStart->>SessionStart: installFileSuggestion()
    SessionStart->>SessionStart: Run migrations & indexing
    SessionStart-->>ClaudeCode: Context injected

    User->>ClaudeCode: Submit prompt
    ClaudeCode->>UserPromptSubmit: Hook: UserPromptSubmit
    UserPromptSubmit->>UserPromptSubmit: Check memoryInjection.enabled
    alt Memory injection enabled
        UserPromptSubmit->>UserPromptSubmit: matrixRecall(query, limit, minScore)
        UserPromptSubmit->>UserPromptSubmit: searchFailures(query)
        UserPromptSubmit-->>ClaudeCode: Inject memory context
    else Memory injection disabled
        UserPromptSubmit-->>ClaudeCode: Skip memory, inject other context
    end

    ClaudeCode->>ClaudeCode: Spawn Explore subagent
    ClaudeCode->>SubagentStart: Hook: SubagentStart
    SubagentStart->>SubagentStart: Check toolSearch.preferMatrixIndex
    SubagentStart->>SubagentStart: Check toolSearch.preferContext7
    SubagentStart->>SubagentStart: buildSubagentGuidance(agent_type)
    SubagentStart-->>Subagent: Inject Matrix guidance
    
    Subagent->>Subagent: Execute with guidance
    Subagent->>Subagent: Prefer matrix_find_definition over Grep
    Subagent->>Subagent: Prefer Context7 over WebSearch
    
    Subagent-->>ClaudeCode: Return results
    ClaudeCode->>SubagentStop: Hook: SubagentStop
    SubagentStop->>SubagentStop: Log completion (if verbose)
    SubagentStop-->>ClaudeCode: Complete

    ClaudeCode-->>User: Response with subagent results

Loading