oh-my-claude-sisyphus 3.3.10 → 3.4.0

package/docs/DELEGATION-ENFORCER.md

@@ -0,0 +1,282 @@
+# Delegation Enforcer
+
+**Automatic model parameter injection for Task/Agent calls**
+
+## Problem
+
+Claude Code does NOT automatically apply model parameters from agent definitions. When you invoke the `Task` tool (or `Agent` tool), you must manually specify the `model` parameter every time, even though each agent has a default model defined in its configuration.
+
+This leads to:
+- Verbose delegation code
+- Forgotten model parameters defaulting to parent model
+- Inconsistent model usage across codebase
+
+## Solution
+
+The **Delegation Enforcer** is middleware that automatically injects the model parameter based on agent definitions when not explicitly specified.
+
+## How It Works
+
+### 1. Pre-Tool-Use Hook
+
+The enforcer runs as a pre-tool-use hook that intercepts `Task` and `Agent` tool calls:
+
+```typescript
+// Before enforcement
+Task(
+  subagent_type="oh-my-claudecode:executor",
+  prompt="Implement feature X"
+)
+
+// After enforcement (automatic)
+Task(
+  subagent_type="oh-my-claudecode:executor",
+  model="sonnet",  // ← Automatically injected
+  prompt="Implement feature X"
+)
+```
+
+### 2. Agent Definition Lookup
+
+Each agent has a default model in its definition:
+
+```typescript
+export const executorAgent: AgentConfig = {
+  name: 'executor',
+  description: '...',
+  prompt: '...',
+  tools: [...],
+  model: 'sonnet'  // ← Default model
+};
+```
+
+The enforcer reads this definition and injects the model when not specified.
+
+### 3. Explicit Models Preserved
+
+If you explicitly specify a model, it's always preserved:
+
+```typescript
+// Explicit model is never overridden
+Task(
+  subagent_type="oh-my-claudecode:executor",
+  model="haiku",  // ← Explicitly using haiku instead of default sonnet
+  prompt="Quick lookup"
+)
+```
+
+## API
+
+### Core Functions
+
+#### `enforceModel(agentInput: AgentInput): EnforcementResult`
+
+Enforces model parameter for a single agent delegation call.
+
+```typescript
+import { enforceModel } from 'oh-my-claude-sisyphus';
+
+const input = {
+  description: 'Implement feature',
+  prompt: 'Add validation',
+  subagent_type: 'executor'
+};
+
+const result = enforceModel(input);
+console.log(result.modifiedInput.model); // 'sonnet'
+console.log(result.injected); // true
+```
+
+#### `getModelForAgent(agentType: string): ModelType`
+
+Get the default model for an agent type.
+
+```typescript
+import { getModelForAgent } from 'oh-my-claude-sisyphus';
+
+getModelForAgent('executor'); // 'sonnet'
+getModelForAgent('executor-low'); // 'haiku'
+getModelForAgent('executor-high'); // 'opus'
+```
+
+#### `isAgentCall(toolName: string, toolInput: unknown): boolean`
+
+Check if a tool invocation is an agent delegation call.
+
+```typescript
+import { isAgentCall } from 'oh-my-claude-sisyphus';
+
+isAgentCall('Task', { subagent_type: 'executor', ... }); // true
+isAgentCall('Bash', { command: 'ls' }); // false
+```
+
+### Hook Integration
+
+The enforcer automatically integrates with the pre-tool-use hook:
+
+```typescript
+import { processHook } from 'oh-my-claude-sisyphus';
+
+const hookInput = {
+  toolName: 'Task',
+  toolInput: {
+    description: 'Test',
+    prompt: 'Test',
+    subagent_type: 'executor'
+  }
+};
+
+const result = await processHook('pre-tool-use', hookInput);
+console.log(result.modifiedInput.model); // 'sonnet'
+```
+
+## Agent Model Mapping
+
+| Agent Type | Default Model | Use Case |
+|------------|---------------|----------|
+| `architect` | opus | Complex analysis, debugging |
+| `architect-medium` | sonnet | Standard analysis |
+| `architect-low` | haiku | Quick questions |
+| `executor` | sonnet | Standard implementation |
+| `executor-high` | opus | Complex refactoring |
+| `executor-low` | haiku | Simple changes |
+| `explore` | haiku | Fast code search |
+| `explore-medium` | sonnet | Thorough search |
+| `designer` | sonnet | UI implementation |
+| `designer-high` | opus | Complex UI architecture |
+| `designer-low` | haiku | Simple styling |
+| `researcher` | sonnet | Documentation lookup |
+| `researcher-low` | haiku | Quick docs |
+| `writer` | haiku | Documentation writing |
+| `vision` | sonnet | Image analysis |
+| `planner` | opus | Strategic planning |
+| `critic` | opus | Plan review |
+| `analyst` | opus | Pre-planning analysis |
+| `qa-tester` | sonnet | CLI testing |
+| `qa-tester-high` | opus | Comprehensive QA |
+| `scientist` | sonnet | Data analysis |
+| `scientist-low` | haiku | Quick inspection |
+| `scientist-high` | opus | Complex research |
+
+## Debug Mode
+
+Enable debug logging to see when models are auto-injected:
+
+```bash
+export OMC_DEBUG=true
+```
+
+When enabled, you'll see warnings like:
+
+```
+[OMC] Auto-injecting model: sonnet for executor
+```
+
+**Important:** Warnings are ONLY shown when `OMC_DEBUG=true`. Without this flag, enforcement happens silently.
+
+## Usage Examples
+
+### Before (Manual)
+
+```typescript
+// Every delegation needs explicit model
+Task(
+  subagent_type="oh-my-claudecode:executor",
+  model="sonnet",
+  prompt="Implement X"
+)
+
+Task(
+  subagent_type="oh-my-claudecode:executor-low",
+  model="haiku",
+  prompt="Quick lookup"
+)
+```
+
+### After (Automatic)
+
+```typescript
+// Model automatically injected from definition
+Task(
+  subagent_type="oh-my-claudecode:executor",
+  prompt="Implement X"
+)
+
+Task(
+  subagent_type="oh-my-claudecode:executor-low",
+  prompt="Quick lookup"
+)
+```
+
+### Override When Needed
+
+```typescript
+// Use haiku for a simple executor task
+Task(
+  subagent_type="oh-my-claudecode:executor",
+  model="haiku",  // Override default sonnet
+  prompt="Find definition of X"
+)
+```
+
+## Implementation Details
+
+### Hook Integration
+
+The enforcer runs in the `pre-tool-use` hook:
+
+1. Hook receives tool invocation
+2. Checks if tool is `Task` or `Agent`
+3. Checks if `model` parameter is missing
+4. Looks up agent definition
+5. Injects default model
+6. Returns modified input
+
+### Error Handling
+
+- Unknown agent types throw errors
+- Agents without default models throw errors
+- Invalid input structures are passed through unchanged
+- Non-agent tools are ignored
+
+### Performance
+
+- O(1) lookup: Direct hash map lookup for agent definitions
+- No async operations: Synchronous enforcement
+- Minimal overhead: Only applies to Task/Agent calls
+
+## Testing
+
+Run tests:
+
+```bash
+npm test -- delegation-enforcer
+```
+
+Run demo:
+
+```bash
+npx tsx examples/delegation-enforcer-demo.ts
+```
+
+## Benefits
+
+1. **Cleaner Code**: No need to manually specify model every time
+2. **Consistency**: Always uses correct model tier for each agent
+3. **Safety**: Explicit models always preserved
+4. **Transparency**: Debug mode shows when models are injected
+5. **Zero Config**: Works automatically with existing agent definitions
+
+## Migration
+
+No migration needed! The enforcer is backward compatible:
+
+- Existing code with explicit models continues working
+- New code can omit model parameter
+- No breaking changes
+
+## Related
+
+- [Model Routing](./MODEL-ROUTING.md) - Intelligent task complexity analysis
+- [Agent Definitions](./AGENTS.md) - Complete agent reference
+- [Delegation Categories](./DELEGATION-CATEGORIES.md) - Semantic task grouping

package/docs/FULL-README.md

@@ -10,7 +10,7 @@
 
 # oh-my-claudecode
 
-[![Version](https://img.shields.io/badge/version-3.3.10-ff6b6b)](https://github.com/Yeachan-Heo/oh-my-claudecode)
+[![Version](https://img.shields.io/badge/version-3.4.0-ff6b6b)](https://github.com/Yeachan-Heo/oh-my-claudecode)
 [![npm version](https://img.shields.io/npm/v/oh-my-claudecode?color=cb3837)](https://www.npmjs.com/package/oh-my-claudecode)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Node.js](https://img.shields.io/badge/Node.js-20+-339933?logo=node.js&logoColor=white)](https://nodejs.org/)

package/docs/LOCAL_PLUGIN_INSTALL.md

@@ -43,7 +43,7 @@ The plugin requires a `plugin.json` manifest:
 ```json
 {
   "name": "oh-my-claudecode",
-  "version": "3.0.11",
+  "version": "3.4.0",
   "description": "Multi-agent orchestration system for Claude Code",
   "hooks": {
     "PreToolUse": ["scripts/pre-tool-enforcer.mjs"],