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

.claude-plugin/marketplace.json

@@ -8,8 +8,8 @@
       "name": "matrix",
       "source": "./",
       "description": "Claude on Rails Tooling System - Persistent memory for Claude Code",
-      "version": "2.0.1"
+      "version": "2.0.2"
     }
   ],
-  "version": "2.0.1"
+  "version": "2.0.2"
 }

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "matrix",
   "description": "Claude on Rails Tooling System",
-  "version": "2.0.1",
+  "version": "2.0.2",
   "author": {
     "name": "Matrix Contributors"
   },

CHANGELOG.md

@@ -2,6 +2,91 @@
 
 All notable changes to Claude Matrix are documented here.
 
+## [2.0.2] - 2025-01-13
+
+### Added
+
+#### Subagent Hooks
+- **New `SubagentStart` Hook** - Inject Matrix guidance when subagents spawn
+  - Fires when Explore, Plan, or other subagents start
+  - Injects guidance to prefer Matrix index tools over Grep for code search
+  - Injects guidance to prefer Context7 over WebSearch for library docs
+  - Respects `toolSearch.preferMatrixIndex` and `toolSearch.preferContext7` config
+  - Verbosity-aware output (full/compact/minimal)
+  - Agent-specific hints for explore/plan agents to use `matrix_recall`
+
+- **New `SubagentStop` Hook** - Track subagent completion
+  - Fires when Explore, Plan, or other subagents complete
+  - Logs completion in verbose mode
+
+#### Token Optimization
+- **Reduced MCP Tool Token Usage** - ~10-12% reduction in Matrix tool definitions
+  - Shortened parameter descriptions across all schemas
+  - Removed redundant "Optional:", "default:" phrases
+  - Optimized tool description verbosity
+
+#### Index Tools Accessibility
+- **Index Tools Always Available** - Can now use from any directory
+  - Changed visibility from `'indexable'` → `'always'` for query tools
+  - Pass `repoPath` parameter to query any indexed repository
+  - Tools: `matrix_find_definition`, `matrix_find_callers`, `matrix_list_exports`, `matrix_search_symbols`, `matrix_get_imports`
+
+#### Auto-Install Features
+- **File Suggestion Script** - Auto-installs `~/.claude/file-suggestion.sh`
+  - Uses ripgrep + fzf for fast fuzzy file matching
+  - Follows symlinks and respects .gitignore
+  - Auto-merges `fileSuggestion` config into `~/.claude/settings.json`
+
+#### Model Delegation Config
+- **New `delegation` Config Section** - Control sub-agent model selection
+  - `enabled`: Toggle delegation (default: true)
+  - `model`: `'haiku'` or `'sonnet'` (default: `'haiku'`)
+  - MCP instructions updated to tell Claude which model to use for read-only tools
+
+#### Config Auto-Upgrade
+- **Session Start Config Migration** - Automatically adds missing config sections
+  - Detects missing: `memoryInjection`, `permissions`, `userRules`, `gitCommitReview`, `delegation`
+  - Preserves existing user settings while adding new defaults
+  - No manual `/matrix:doctor` needed after upgrades
+
+### Changed
+
+#### Code Review Refactored
+- **Simplified Review Modes** - Two modes instead of three depths
+  - `default`: Comprehensive 5-phase review with full index utilization
+  - `lazy`: Quick single-pass review, no index queries
+- **New Config Structure** - `hooks.gitCommitReview`
+  - `suggestOnCommit`: Suggest review before commits (default: true)
+  - `defaultMode`: `'default'` or `'lazy'` (default: `'default'`)
+  - `autoRun`: Never auto-runs, always suggests (default: false)
+- **BREAKING**: Removed `depth` setting (`quick`/`standard`/`thorough`)
+
+#### Memory Injection Config
+- **Proper Config Usage** - `hooks.promptAnalysis.memoryInjection` now actually used
+  - `enabled`: Toggle memory injection (default: true)
+  - `maxSolutions`: Max solutions to inject (default: 3)
+  - `maxFailures`: Max failures to inject (default: 2)
+  - `minScore`: Minimum similarity score (default: 0.35)
+
+#### Wildcard Permission Patterns
+- **Simplified PermissionRequest matchers** - Leverages Claude Code 2.1.0+ wildcards
+  - `mcp__plugin_matrix_matrix__*` replaces 11 individual tool matchers
+  - `mcp__plugin_matrix_context7__*` replaces 2 individual tool matchers
+  - Auto-includes new tools added to MCP servers
+
+#### Increased Hook Timeouts
+- **Leverage Claude Code 2.1.3's 10-minute limit** for complex analysis
+  - `UserPromptSubmit`: 60s → **600s** (deep-research, review commands)
+  - `PreCompact`: 30s → **600s** (session analysis before compaction)
+  - `PreToolUse:Bash`: 30s → 60s (package auditing)
+  - `Stop`: 30s → 60s (session summary)
+
+### Fixed
+
+- Removed unused imports in `session-start.ts` (oxlint warnings)
+
+---
+
 ## [2.0.1] - 2025-01-09
 
 ### Added

README.md

@@ -6,7 +6,7 @@
 
 **Persistent Memory & Tooling for Claude Code**
 
-[![Version](https://img.shields.io/badge/v2.0.0-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/v2.0.2-blue.svg)](CHANGELOG.md)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
 [![LLM Reference](https://img.shields.io/badge/LLM-reference-purple.svg)](docs/reference-for-llms.md)
@@ -52,18 +52,23 @@ Verify with `/matrix:doctor`
 
 ## What's New in v2.0
 
-### Core Improvements
+### v2.0.2
+- **Subagent Hooks** — `SubagentStart` injects Matrix guidance to Explore/Plan agents
+- **Wildcard Warnings** — Glob patterns in warning rules (`src/legacy/**`)
+- **Hook Timeouts** — Configurable timeout (default 30s, max 120s)
+- **Index Tools Anywhere** — Query any indexed repo via `repoPath` parameter
+- **Token Optimization** — ~10-12% reduction in MCP tool definitions
+
+### v2.0.0
 - **Hook Verbosity** — `compact` mode cuts token overhead by 80%
 - **Unified Warn API** — Single `matrix_warn` tool with `action` parameter
-
-### New Capabilities
 - **Skill Factory** — Promote high-value solutions to Claude Code Skills
 - **Blast Radius** — `matrix_find_callers` shows impact before changes
 - **Code Review** — 5-phase review pipeline via `/matrix:review`
 - **Deep Research** — Multi-source aggregation via `/matrix:deep-research`
 - **User Rules** — Custom pattern matching (block, warn, allow)
 
-### Breaking Changes
+### Breaking Changes (v2.0)
 - Removed: `/matrix:verify`, `/matrix:stats`, `/matrix:search`
 - Changed: Four warn tools → single `matrix_warn`
 

commands/review.md

@@ -4,22 +4,35 @@ description: Conduct a multi-phase code review with blast radius analysis
 
 # Matrix Code Review
 
-Perform a comprehensive, context-aware code review using Matrix's 5-phase review pipeline.
+Perform a comprehensive, context-aware code review using Matrix's review pipeline with full index integration.
+
+> **Tip:** For best results, run `/matrix:review` in a **fresh session**. A new session has no prior context about the code, which provides an unbiased perspective—similar to how a human reviewer would approach the code for the first time.
 
 ## Usage
 
 Parse arguments: `$ARGUMENTS`
 
-**Expected format:** `<target> [depth]`
+**Expected format:** `<target> [mode]`
 
 - **target**: File path, PR number, or "staged" for staged changes
-- **depth** (optional): `quick` | `standard` | `thorough` (default: `standard`)
+- **mode** (optional): `default` | `lazy` (default: from config or `default`)
+
+## Modes
 
-## Depth Levels
+### Default Mode (Comprehensive)
+Full 5-phase review pipeline with maximum index utilization:
+- Blast radius analysis via `matrix_find_callers`
+- Symbol lookup via `matrix_find_definition` and `matrix_search_symbols`
+- Memory recall via `matrix_recall` for relevant past solutions
+- Deep security and edge case analysis
+- ~10+ comments, thorough coverage
 
-- **quick**: Single-pass review, main issues only (~2-3 comments)
-- **standard**: Full pipeline, balanced coverage (~5-10 comments)
-- **thorough**: Deep analysis, edge cases, security review (~10+ comments)
+### Lazy Mode (Quick)
+Single-pass review for fast feedback:
+- Direct code inspection only
+- No index queries (faster)
+- Main issues only
+- ~2-3 comments
 
 ## 5-Phase Review Pipeline
 
@@ -200,9 +213,11 @@ Generate final review output in Greptile-style format:
 ## Examples
 
 ```
-/matrix:review src/utils/auth.ts standard
-/matrix:review staged thorough
-/matrix:review 123 quick
+/matrix:review src/utils/auth.ts          # Default mode (comprehensive)
+/matrix:review staged                     # Review staged changes
+/matrix:review staged lazy                # Quick review of staged changes
+/matrix:review 123                        # Review PR #123
+/matrix:review 123 lazy                   # Quick review of PR #123
 ```
 
 ## Output Location

hooks/hooks.json

@@ -17,7 +17,7 @@
           {
             "type": "command",
             "command": "${CLAUDE_PLUGIN_ROOT}/scripts/run-hooks.sh user-prompt-submit",
-            "timeout": 60
+            "timeout": 600
           }
         ]
       }
@@ -34,7 +34,7 @@
         ]
       },
       {
-        "matcher": "mcp__plugin_matrix_matrix__matrix_recall|mcp__plugin_matrix_matrix__matrix_status|mcp__plugin_matrix_matrix__matrix_warn|mcp__plugin_matrix_matrix__matrix_find_definition|mcp__plugin_matrix_matrix__matrix_search_symbols|mcp__plugin_matrix_matrix__matrix_list_exports|mcp__plugin_matrix_matrix__matrix_get_imports|mcp__plugin_matrix_matrix__matrix_index_status|mcp__plugin_matrix_matrix__matrix_reindex|mcp__plugin_matrix_matrix__matrix_repomix|mcp__plugin_matrix_matrix__matrix_prompt",
+        "matcher": "mcp__plugin_matrix_matrix__*",
         "hooks": [
           {
             "type": "command",
@@ -44,7 +44,7 @@
         ]
       },
       {
-        "matcher": "mcp__plugin_matrix_context7__resolve-library-id|mcp__plugin_matrix_context7__query-docs",
+        "matcher": "mcp__plugin_matrix_context7__*",
         "hooks": [
           {
             "type": "command",
@@ -71,7 +71,7 @@
           {
             "type": "command",
             "command": "${CLAUDE_PLUGIN_ROOT}/scripts/run-hooks.sh pre-tool-bash",
-            "timeout": 30
+            "timeout": 60
           }
         ]
       },
@@ -124,7 +124,7 @@
           {
             "type": "command",
             "command": "${CLAUDE_PLUGIN_ROOT}/scripts/run-hooks.sh pre-compact",
-            "timeout": 30
+            "timeout": 600
           }
         ]
       }
@@ -135,7 +135,29 @@
           {
             "type": "command",
             "command": "${CLAUDE_PLUGIN_ROOT}/scripts/run-hooks.sh stop-session",
-            "timeout": 30
+            "timeout": 60
+          }
+        ]
+      }
+    ],
+    "SubagentStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/run-hooks.sh subagent-start",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/run-hooks.sh subagent-stop",
+            "timeout": 10
           }
         ]
       }

package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-matrix",
-  "version": "2.0.1",
+  "version": "2.0.2",
   "description": "Claude on Rails Tooling System",
   "type": "module",
   "main": "src/index.ts",

src/__tests__/registry.test.ts

@@ -105,9 +105,9 @@ describe('Tool Registry', () => {
       expect(toolNames).toContain('matrix_warn');
       expect(toolNames).toContain('matrix_doctor');
 
-      // Index tools should be hidden (not indexable)
-      expect(toolNames).not.toContain('matrix_find_definition');
-      expect(toolNames).not.toContain('matrix_search_symbols');
+      // Index tools should also be visible (can query any repo via repoPath)
+      expect(toolNames).toContain('matrix_find_definition');
+      expect(toolNames).toContain('matrix_search_symbols');
     });
 
     it('should show index tools for indexable projects', async () => {

src/config/index.ts

@@ -101,12 +101,15 @@ export interface PromptAnalysisConfig {
 }
 
 // ═══════════════════════════════════════════════════════════════
-// Pre-Commit Review Config
+// Code Review Config
 // ═══════════════════════════════════════════════════════════════
 export interface GitCommitReviewConfig {
-  enabled: boolean;
-  /** Review depth: 'quick' | 'standard' | 'thorough' */
-  depth: 'quick' | 'standard' | 'thorough';
+  /** Suggest review before git commits */
+  suggestOnCommit: boolean;
+  /** Default review mode: 'default' (comprehensive) | 'lazy' (quick) */
+  defaultMode: 'default' | 'lazy';
+  /** Auto-run review (NOT recommended - prefer suggestion) */
+  autoRun: boolean;
 }
 
 // ═══════════════════════════════════════════════════════════════
@@ -204,6 +207,13 @@ export interface MatrixConfig {
     /** Log when tools are shown/hidden due to project context */
     verbose: boolean;
   };
+  /** Model delegation settings for read-only tools */
+  delegation: {
+    /** Enable tool delegation to cheaper models */
+    enabled: boolean;
+    /** Model for delegable tools: 'haiku' (cheaper) or 'sonnet' (more capable) */
+    model: 'haiku' | 'sonnet';
+  };
 }
 
 function getDownloadsDirectory(): string {
@@ -327,11 +337,12 @@ export const DEFAULT_CONFIG: MatrixConfig = {
       },
     },
 
-    // ─── Pre-Commit Review (PreToolUse:Bash hook) ───
-    // Triggers Matrix review before git/jj commits
+    // ─── Code Review Config ───
+    // Controls /matrix:review behavior and commit suggestions
     gitCommitReview: {
-      enabled: true,
-      depth: 'standard' as const,
+      suggestOnCommit: true,  // Suggest review before git commits
+      defaultMode: 'default' as const,  // 'default' (comprehensive) or 'lazy' (quick)
+      autoRun: false,  // Never auto-run, always suggest
     },
 
     // ─── User Rules (v2.0) ───
@@ -380,6 +391,10 @@ export const DEFAULT_CONFIG: MatrixConfig = {
     preferContext7: true,
     verbose: false,
   },
+  delegation: {
+    enabled: true,
+    model: 'haiku' as const,  // Use haiku for cheaper read-only operations
+  },
 };
 
 let cachedConfig: MatrixConfig | null = null;

src/hooks/index.ts

@@ -43,6 +43,26 @@ export interface StopInput extends HookInput {
   stop_hook_active: boolean;
 }
 
+/**
+ * SubagentStart hook input (Claude Code 2.0.43+)
+ * Fires when a subagent (Explore, Plan, etc.) starts
+ */
+export interface SubagentStartInput extends HookInput {
+  agent_id: string;
+  agent_type: string;
+  hook_event_name: 'SubagentStart';
+}
+
+/**
+ * SubagentStop hook input (Claude Code 2.0.42+)
+ * Fires when a subagent completes
+ */
+export interface SubagentStopInput extends HookInput {
+  agent_id: string;
+  agent_transcript_path: string;
+  stop_hook_active?: boolean;
+}
+
 /**
  * PermissionRequest decision structure
  */