htmlgraph 0.23.5__py3-none-any.whl → 0.24.0__py3-none-any.whl

htmlgraph/hooks/cigs_pretool_enforcer.py

@@ -0,0 +1,350 @@
+"""
+CIGS PreToolUse Enforcer - Enhanced Orchestrator Enforcement with Escalation
+
+Integrates the Computational Imperative Guidance System (CIGS) into the PreToolUse
+hook for intelligent delegation enforcement with escalating guidance.
+
+Architecture:
+1. Uses existing OrchestratorValidator for base classification
+2. Loads session violation count from ViolationTracker
+3. Classifies operation using CostCalculator
+4. Generates imperative message with escalation via ImperativeMessageGenerator
+5. Records violation if should_delegate=True
+6. Returns hookSpecificOutput with imperative message
+
+Escalation Levels:
+- Level 0 (0 violations): Guidance - informative, no cost shown
+- Level 1 (1 violation): Imperative - commanding, includes cost
+- Level 2 (2 violations): Final Warning - urgent, includes consequences
+- Level 3 (3+ violations): Circuit Breaker - blocking, requires acknowledgment
+
+Design Reference:
+    .htmlgraph/spikes/computational-imperative-guidance-system-design.md
+    Part 2: CIGS PreToolUse Hook Integration
+    Part 4: Imperative Message Generation
+"""
+
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+from htmlgraph.cigs.cost import CostCalculator
+from htmlgraph.cigs.messaging import ImperativeMessageGenerator
+from htmlgraph.cigs.tracker import ViolationTracker
+from htmlgraph.hooks.orchestrator import is_allowed_orchestrator_operation
+from htmlgraph.orchestrator_mode import OrchestratorModeManager
+
+
+class CIGSPreToolEnforcer:
+    """
+    CIGS-enhanced PreToolUse enforcement with escalating imperative messages.
+
+    Integrates all CIGS components for comprehensive delegation enforcement.
+    """
+
+    # Tools that are ALWAYS allowed (orchestrator core)
+    ALWAYS_ALLOWED = {"Task", "AskUserQuestion", "TodoWrite"}
+
+    # Exploration tools that require delegation after first use
+    EXPLORATION_TOOLS = {"Read", "Grep", "Glob"}
+
+    # Implementation tools that always require delegation
+    IMPLEMENTATION_TOOLS = {"Edit", "Write", "NotebookEdit", "Delete"}
+
+    def __init__(self, graph_dir: Path | None = None):
+        """
+        Initialize CIGS PreToolUse enforcer.
+
+        Args:
+            graph_dir: Root directory for HtmlGraph (defaults to .htmlgraph)
+        """
+        if graph_dir is None:
+            graph_dir = self._find_graph_dir()
+
+        self.graph_dir = graph_dir
+        self.manager = OrchestratorModeManager(graph_dir)
+        self.cost_calculator = CostCalculator()
+        self.message_generator = ImperativeMessageGenerator()
+        self.tracker = ViolationTracker(graph_dir)
+
+        # Ensure session ID is set (detect from environment or use current session)
+        if self.tracker._session_id is None:
+            self.tracker.set_session_id(self._get_or_create_session_id())
+
+    def _find_graph_dir(self) -> Path:
+        """Find .htmlgraph directory starting from cwd."""
+        cwd = Path.cwd()
+        graph_dir = cwd / ".htmlgraph"
+
+        if not graph_dir.exists():
+            for parent in [cwd.parent, cwd.parent.parent, cwd.parent.parent.parent]:
+                candidate = parent / ".htmlgraph"
+                if candidate.exists():
+                    graph_dir = candidate
+                    break
+
+        return graph_dir
+
+    def enforce(self, tool: str, params: dict) -> dict[str, Any]:
+        """
+        Enforce CIGS delegation rules with escalating guidance.
+
+        Args:
+            tool: Tool name (Read, Edit, Bash, etc.)
+            params: Tool parameters
+
+        Returns:
+            Hook response dict in Claude Code standard format:
+            {
+                "hookSpecificOutput": {
+                    "hookEventName": "PreToolUse",
+                    "permissionDecision": "allow" | "deny",
+                    "additionalContext": "...",  # If allow with guidance
+                    "permissionDecisionReason": "...",  # If deny
+                }
+            }
+        """
+        # Check if orchestrator mode is enabled
+        if not self.manager.is_enabled():
+            return self._allow()
+
+        enforcement_level = self.manager.get_enforcement_level()
+
+        # ALWAYS ALLOWED tools pass through
+        if tool in self.ALWAYS_ALLOWED:
+            return self._allow()
+
+        # Check if SDK operation (always allowed)
+        if self._is_sdk_operation(tool, params):
+            return self._allow()
+
+        # Get session violation summary
+        summary = self.tracker.get_session_violations()
+        violation_count = summary.total_violations
+
+        # Check circuit breaker (3+ violations)
+        if violation_count >= 3 and enforcement_level == "strict":
+            return self._circuit_breaker(violation_count)
+
+        # Classify operation using existing orchestrator logic
+        is_allowed, reason, category = is_allowed_orchestrator_operation(tool, params)
+
+        # CIGS enforces stricter rules in strict mode:
+        # - Even "single lookups" should be delegated (exploration tools)
+        # - All implementation tools should be delegated
+        should_delegate = False
+        if enforcement_level == "strict":
+            if tool in self.EXPLORATION_TOOLS or tool in self.IMPLEMENTATION_TOOLS:
+                should_delegate = True
+                # Override is_allowed - CIGS wants delegation even for first use
+                is_allowed = False
+
+        # If orchestrator allows and CIGS doesn't override, proceed
+        if is_allowed and not should_delegate:
+            return self._allow()
+
+        # Operation should be delegated - classify with cost analysis
+        classification = self.cost_calculator.classify_operation(
+            tool=tool,
+            params=params,
+            is_exploration_sequence=self._is_exploration_sequence(tool),
+        )
+
+        # Generate imperative message with escalation
+        imperative_message = self.message_generator.generate(
+            tool=tool,
+            classification=classification,
+            violation_count=violation_count,
+            autonomy_level=enforcement_level,
+        )
+
+        # Record violation for session tracking
+        predicted_waste = classification.predicted_cost - classification.optimal_cost
+        self.tracker.record_violation(
+            tool=tool,
+            params=params,
+            classification=classification,
+            predicted_waste=predicted_waste,
+        )
+
+        # Return response based on enforcement level and escalation
+        if enforcement_level == "strict":
+            # STRICT mode - deny with imperative message
+            return {
+                "hookSpecificOutput": {
+                    "hookEventName": "PreToolUse",
+                    "permissionDecision": "deny",
+                    "permissionDecisionReason": imperative_message,
+                }
+            }
+        else:
+            # GUIDANCE mode - allow but with strong message
+            return {
+                "hookSpecificOutput": {
+                    "hookEventName": "PreToolUse",
+                    "permissionDecision": "allow",
+                    "additionalContext": imperative_message,
+                }
+            }
+
+    def _allow(self) -> dict[str, Any]:
+        """Return allow response."""
+        return {
+            "hookSpecificOutput": {
+                "hookEventName": "PreToolUse",
+                "permissionDecision": "allow",
+            }
+        }
+
+    def _circuit_breaker(self, violation_count: int) -> dict[str, Any]:
+        """Return circuit breaker blocking response."""
+        message = (
+            "🚨 CIRCUIT BREAKER TRIGGERED\n\n"
+            f"You have violated delegation rules {violation_count} times this session.\n\n"
+            "**Violations detected:**\n"
+            "- Direct execution instead of delegation\n"
+            "- Context waste on tactical operations\n"
+            "- Ignored imperative guidance messages\n\n"
+            "**REQUIRED:** Acknowledge violations before proceeding:\n"
+            "`uv run htmlgraph orchestrator acknowledge-violation`\n\n"
+            "**OR** Change enforcement settings:\n"
+            "- Disable: `uv run htmlgraph orchestrator disable`\n"
+            "- Guidance mode: `uv run htmlgraph orchestrator set-level guidance`\n"
+            "- Reset violations: `uv run htmlgraph orchestrator reset-violations`"
+        )
+
+        return {
+            "hookSpecificOutput": {
+                "hookEventName": "PreToolUse",
+                "permissionDecision": "deny",
+                "permissionDecisionReason": message,
+            }
+        }
+
+    def _is_sdk_operation(self, tool: str, params: dict) -> bool:
+        """Check if operation is an SDK operation (always allowed)."""
+        if tool != "Bash":
+            return False
+
+        command = params.get("command", "")
+
+        # Allow htmlgraph SDK commands
+        if command.startswith("uv run htmlgraph ") or command.startswith("htmlgraph "):
+            return True
+
+        # Allow git read-only commands
+        if command.startswith(("git status", "git diff", "git log")):
+            return True
+
+        # Allow SDK inline usage
+        if "from htmlgraph import" in command or "import htmlgraph" in command:
+            return True
+
+        return False
+
+    def _is_exploration_sequence(self, tool: str) -> bool:
+        """Check if this is part of an exploration sequence."""
+        if tool not in self.EXPLORATION_TOOLS:
+            return False
+
+        # Check recent history for exploration pattern
+        # This is simplified - could use tool_history from orchestrator.py
+        summary = self.tracker.get_session_violations()
+
+        # If we've already had exploration violations, this is a sequence
+        exploration_violations = [
+            v for v in summary.violations if v.tool in self.EXPLORATION_TOOLS
+        ]
+
+        return len(exploration_violations) >= 1
+
+    def _get_or_create_session_id(self) -> str:
+        """Get or create a session ID for tracking."""
+        # Try to get from environment
+        if "HTMLGRAPH_SESSION_ID" in os.environ:
+            return os.environ["HTMLGRAPH_SESSION_ID"]
+
+        # Try to get from session manager
+        try:
+            from htmlgraph.session_manager import SessionManager
+
+            sm = SessionManager(self.graph_dir)
+            current = sm.get_active_session()
+            if current:
+                return str(current.id)
+        except Exception:
+            pass
+
+        # Fallback: create a session ID for this test/run
+        # Use a consistent ID for the process
+        if not hasattr(self.__class__, "_fallback_session_id"):
+            from uuid import uuid4
+
+            fallback_id: str = f"test-session-{uuid4().hex[:8]}"
+            setattr(self.__class__, "_fallback_session_id", fallback_id)
+            return fallback_id
+
+        return str(getattr(self.__class__, "_fallback_session_id"))
+
+
+def enforce_cigs_pretool(tool_input: dict[str, Any]) -> dict[str, Any]:
+    """
+    Main entry point for CIGS PreToolUse enforcement.
+
+    Args:
+        tool_input: Hook input with tool name and parameters
+
+    Returns:
+        Hook response dict in Claude Code standard format
+    """
+    # Extract tool and params from input
+    tool = tool_input.get("name", "") or tool_input.get("tool_name", "")
+    params = tool_input.get("input", {}) or tool_input.get("tool_input", {})
+
+    # Create enforcer and run
+    try:
+        enforcer = CIGSPreToolEnforcer()
+        return enforcer.enforce(tool, params)
+    except Exception as e:
+        # Graceful degradation - allow on error
+        print(f"Warning: CIGS enforcement error: {e}", file=sys.stderr)
+        return {
+            "hookSpecificOutput": {
+                "hookEventName": "PreToolUse",
+                "permissionDecision": "allow",
+            }
+        }
+
+
+def main() -> None:
+    """Hook entry point for script wrapper."""
+    # Check environment overrides
+    if os.environ.get("HTMLGRAPH_DISABLE_TRACKING") == "1":
+        print(json.dumps({"hookSpecificOutput": {"permissionDecision": "allow"}}))
+        sys.exit(0)
+
+    if os.environ.get("HTMLGRAPH_ORCHESTRATOR_DISABLED") == "1":
+        print(json.dumps({"hookSpecificOutput": {"permissionDecision": "allow"}}))
+        sys.exit(0)
+
+    # Read tool input from stdin
+    try:
+        tool_input = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        tool_input = {}
+
+    # Run CIGS enforcement
+    result = enforce_cigs_pretool(tool_input)
+
+    # Output response
+    print(json.dumps(result))
+
+    # Exit code based on permission decision
+    permission = result.get("hookSpecificOutput", {}).get("permissionDecision", "allow")
+    sys.exit(0 if permission == "allow" else 1)
+
+
+if __name__ == "__main__":
+    main()

htmlgraph/hooks/posttooluse.py

@@ -8,6 +8,7 @@ in parallel using asyncio:
 3. Task validation - validates task results
 4. Error tracking - logs errors and auto-creates debug spikes
 5. Debugging suggestions - suggests resources when errors detected
+6. CIGS analysis - cost accounting and reinforcement for delegation
 
 Architecture:
 - All tasks run simultaneously via asyncio.gather()
@@ -25,8 +26,10 @@ import asyncio
 import json
 import os
 import sys
+from pathlib import Path
 from typing import Any
 
+from htmlgraph.cigs import CIGSPostToolAnalyzer
 from htmlgraph.hooks.event_tracker import track_event
 from htmlgraph.hooks.orchestrator_reflector import orchestrator_reflect
 from htmlgraph.hooks.post_tool_use_failure import run as track_error
@@ -233,11 +236,48 @@ async def suggest_debugging_resources(hook_input: dict[str, Any]) -> dict[str, A
         return {}
 
 
+async def run_cigs_analysis(hook_input: dict[str, Any]) -> dict[str, Any]:
+    """
+    Run CIGS cost accounting and reinforcement analysis.
+
+    Args:
+        hook_input: Hook input with tool execution details
+
+    Returns:
+        CIGS analysis response: {"hookSpecificOutput": {...}}
+    """
+    try:
+        loop = asyncio.get_event_loop()
+
+        # Extract tool info
+        tool_name = hook_input.get("name", "") or hook_input.get("tool_name", "")
+        tool_params = hook_input.get("input", {}) or hook_input.get("tool_input", {})
+        tool_response = hook_input.get("result", {}) or hook_input.get(
+            "tool_response", {}
+        )
+
+        # Initialize CIGS analyzer
+        graph_dir = Path.cwd() / ".htmlgraph"
+        analyzer = CIGSPostToolAnalyzer(graph_dir)
+
+        # Run analysis in executor (may involve I/O)
+        return await loop.run_in_executor(
+            None,
+            analyzer.analyze,
+            tool_name,
+            tool_params,
+            tool_response,
+        )
+    except Exception:
+        # Graceful degradation - allow on error
+        return {}
+
+
 async def posttooluse_hook(
     hook_type: str, hook_input: dict[str, Any]
 ) -> dict[str, Any]:
     """
-    Unified PostToolUse hook - runs tracking, reflection, validation, error tracking, and debugging suggestions in parallel.
+    Unified PostToolUse hook - runs tracking, reflection, validation, error tracking, debugging suggestions, and CIGS analysis in parallel.
 
     Args:
         hook_type: "PostToolUse" or "Stop"
@@ -254,19 +294,21 @@ async def posttooluse_hook(
             }
         }
     """
-    # Run all five in parallel using asyncio.gather
+    # Run all six in parallel using asyncio.gather
     (
         event_response,
         reflection_response,
         validation_response,
         error_tracking_response,
         debug_suggestions,
+        cigs_response,
     ) = await asyncio.gather(
         run_event_tracking(hook_type, hook_input),
         run_orchestrator_reflection(hook_input),
         run_task_validation(hook_input),
         run_error_tracking(hook_input),
         suggest_debugging_resources(hook_input),
+        run_cigs_analysis(hook_input),
     )
 
     # Combine responses (all should return continue=True)
@@ -307,6 +349,12 @@ async def posttooluse_hook(
         if ctx:
             guidance_parts.append(ctx)
 
+    # CIGS analysis (cost accounting and reinforcement)
+    if "hookSpecificOutput" in cigs_response:
+        ctx = cigs_response["hookSpecificOutput"].get("additionalContext", "")
+        if ctx:
+            guidance_parts.append(ctx)
+
     # Build unified response
     response: dict[str, Any] = {"continue": True}  # PostToolUse never blocks
 

htmlgraph/hooks/task_enforcer.py

@@ -9,6 +9,7 @@ Architecture:
 - Checks if prompt already includes save instructions
 - Auto-injects SDK save template if missing
 - Returns updatedInput with modified prompt
+- Tracks parent session context and nesting depth (Phase 2)
 
 Usage:
     from htmlgraph.hooks.task_enforcer import enforce_task_saving
@@ -17,6 +18,7 @@ Usage:
     # Returns: {"continue": True, "hookSpecificOutput": {"updatedInput": {...}}}
 """
 
+import os
 from typing import Any
 
 
@@ -124,8 +126,56 @@ def enforce_task_saving(tool_name: str, tool_params: dict[str, Any]) -> dict[str
     if not prompt:
         return {"continue": True}
 
+    # Phase 2: Track parent session context and increment nesting depth
+    parent_session = os.environ.get("HTMLGRAPH_PARENT_SESSION")
+    parent_agent = os.environ.get("HTMLGRAPH_PARENT_AGENT", "claude-code")
+    nesting_depth = int(os.environ.get("HTMLGRAPH_NESTING_DEPTH", "0"))
+
+    # Track Task invocation as activity (if parent session exists)
+    task_activity_id = None
+    if parent_session:
+        try:
+            from htmlgraph import SDK
+
+            sdk = SDK(agent=parent_agent, parent_session=parent_session)
+
+            # Track Task invocation
+            entry = sdk.track_activity(
+                tool="Task",
+                summary=f"Task invoked: {tool_params.get('description', 'Unnamed task')[:100]}",
+                payload={
+                    "subagent_type": tool_params.get("subagent_type"),
+                    "description": tool_params.get("description"),
+                    "prompt_preview": prompt[:200] if prompt else "",
+                    "nesting_depth": nesting_depth,
+                },
+                success=True,
+            )
+
+            if entry:
+                task_activity_id = entry.id
+
+        except Exception:
+            # Graceful degradation - continue even if tracking fails
+            pass
+
+    # Increment nesting depth for child
+    new_depth = nesting_depth + 1
+
+    # Set parent activity and increment depth in environment
+    if task_activity_id:
+        os.environ["HTMLGRAPH_PARENT_ACTIVITY"] = task_activity_id
+
+    os.environ["HTMLGRAPH_NESTING_DEPTH"] = str(new_depth)
+
+    # Warn about runaway recursion
+    warning = ""
+    if new_depth > 3:
+        warning = f"\n⚠️  Warning: Nesting depth exceeds 3 levels (depth={new_depth}). Consider flattening task hierarchy."
+
     # Check if save instructions already present
     if has_save_instructions(prompt):
+        # Even if save instructions exist, we still need to update environment
         return {"continue": True}
 
     # Detect subagent type from prompt context
@@ -146,15 +196,21 @@ def enforce_task_saving(tool_name: str, tool_params: dict[str, Any]) -> dict[str
     updated_params = tool_params.copy()
     updated_params["prompt"] = modified_prompt
 
+    # Build context message
+    context_msg = (
+        f"📝 Auto-injected HtmlGraph save instructions into Task prompt. "
+        f"Subagent will be reminded to save findings using SDK.spikes. "
+        f"(depth={new_depth}, parent={parent_session[:12] if parent_session else 'none'})"
+    )
+    if warning:
+        context_msg += warning
+
     # Return response with updatedInput
     return {
         "continue": True,
         "hookSpecificOutput": {
             "hookEventName": "PreToolUse",
             "updatedInput": updated_params,
-            "additionalContext": (
-                "📝 Auto-injected HtmlGraph save instructions into Task prompt. "
-                "Subagent will be reminded to save findings using SDK.spikes."
-            ),
+            "additionalContext": context_msg,
         },
     }

htmlgraph/models.py

@@ -925,6 +925,11 @@ class Session(BaseModel):
     worked_on: list[str] = Field(default_factory=list)  # Feature IDs
     continued_from: str | None = None  # Previous session ID
 
+    # Parent session context (for nested Task() calls)
+    parent_session: str | None = None  # Parent session ID
+    parent_activity: str | None = None  # Parent activity ID
+    nesting_depth: int = 0  # Depth of nesting (0 = top-level)
+
     # Handoff context
     handoff_notes: str | None = None
     recommended_next: str | None = None
@@ -1357,6 +1362,14 @@ class Session(BaseModel):
             if self.primary_work_type
             else ""
         )
+        # Parent session attributes
+        parent_session_attrs = ""
+        if self.parent_session:
+            parent_session_attrs += f' data-parent-session="{self.parent_session}"'
+        if self.parent_activity:
+            parent_session_attrs += f' data-parent-activity="{self.parent_activity}"'
+        if self.nesting_depth > 0:
+            parent_session_attrs += f' data-nesting-depth="{self.nesting_depth}"'
 
         # Serialize work_breakdown as JSON if present
         import json
@@ -1466,7 +1479,7 @@ class Session(BaseModel):
              data-agent="{self.agent}"
              data-started-at="{self.started_at.isoformat()}"
              data-last-activity="{self.last_activity.isoformat()}"
-             data-event-count="{self.event_count}"{subagent_attr}{commit_attr}{ended_attr}{primary_work_type_attr}{work_breakdown_attr}{context_attrs}{transcript_attrs}>
+             data-event-count="{self.event_count}"{subagent_attr}{commit_attr}{ended_attr}{primary_work_type_attr}{work_breakdown_attr}{context_attrs}{transcript_attrs}{parent_session_attrs}>
 
         <header>
             <h1>{title}</h1>