aiwcli 0.9.0 → 0.9.1

package/dist/templates/_shared/.windsurf/workflows/handoff.md

@@ -1,14 +1,226 @@
+# Handoff Workflow
+
+Generate a handoff document summarizing the current session's work, decisions, and pending items. Optionally update a plan document to track completed vs remaining tasks.
+
+## Triggers
+
+- `/handoff` command
+- `/handoff path/to/PLAN.md` - with plan document integration
+- Phrases like "write a handoff", "create a session summary", "document what we did", "end session with notes"
+
+## Arguments
+
+- `$ARGUMENTS` - Optional path to a plan document. If provided, the handoff will:
+  1. Mark completed items in the plan with `[x]`
+  2. Add notes about partial progress
+  3. Append a "Session Progress" section to the plan
+
+## Process
+
+### Step 1: Get Context ID
+
+Extract the `context_id` from the system reminder injected by the context enforcer hook.
+
+Look for the pattern in the system reminder:
+```
+Active Context: {context_id}
+```
+
+If no active context is found, inform the user and stop - handoffs require an active context.
+
+### Step 2: Gather Information
+
+1. Review conversation history for:
+   - Completed tasks and implementations
+   - Key decisions and their rationale
+   - Failed approaches (to avoid repeating)
+   - External context (deadlines, stakeholder requirements)
+
+2. Check git status if available:
+   ```bash
+   git status --short
+   git diff --stat
+   ```
+
+3. Look for TODOs/FIXMEs mentioned in session
+
+4. **If plan document provided**: Read the plan and identify:
+   - Tasks that are now completed
+   - Tasks that are partially done
+   - Tasks that were attempted but blocked
+   - New tasks discovered during implementation
+
+### Step 3: Generate Document
+
+Use this template. The `<!-- SECTION: name -->` markers are required for the save script to parse sections into sharded files.
+
+```markdown
 ---
-description: Generate a session handoff document when ending work
+title: Session Handoff
+date: {ISO timestamp}
+session_id: {conversation ID if available}
+project: {project name from package.json, Cargo.toml, or directory name}
+context_id: {context_id from Step 1}
+plan_document: {path to plan if provided, or "none"}
 ---
-# Session Handoff
 
-Generate a handoff document summarizing the current session's work, decisions, and pending items.
+# Session Handoff — {Date}
 
-## Arguments
+<!-- SECTION: summary -->
+## Summary
+{2-3 sentences: what's different now vs. session start}
+
+<!-- SECTION: completed -->
+## Work Completed
+{Grouped by category if multiple areas. Specific file:function references.}
+
+<!-- SECTION: dead-ends -->
+## Dead Ends — Do Not Retry
+
+These approaches were attempted and failed. Do not retry without addressing the root cause.
+
+| Approach | Why It Failed | Time Spent | Alternative |
+|----------|---------------|------------|-------------|
+| {What was attempted} | {Specific reason} | {Rough estimate} | {What to try instead} |
+
+<!-- SECTION: decisions -->
+## Key Decisions
+{Technical choices with rationale. Format: **Decision**: Rationale. Trade-off: X.}
+
+<!-- SECTION: pending -->
+## Pending Issues
+- [ ] {Issue} — {severity: HIGH/MED/LOW} {optional workaround note}
+
+<!-- SECTION: next-steps -->
+## Next Steps
+1. {Actionable item with file:line reference if applicable}
+
+<!-- SECTION: files -->
+## Files Modified
+{Significant changes only. Skip formatting-only edits.}
+
+<!-- SECTION: context -->
+## Context for Future Sessions
+{Non-obvious context: env quirks, stakeholder requirements}
+
+```
+
+### Step 4: Update Plan Document (if provided)
+
+If a plan document path was provided in `$ARGUMENTS`:
+
+1. **Read the plan document**
+2. **Identify completed items**:
+   - Find checkboxes `- [ ]` that match completed work
+   - Change them to `- [x]`
+3. **Add progress notes** to items that are partially complete:
+   - Append `(partial: {brief status})` to the line
+4. **Append Session Progress section** at the bottom:
+
+```markdown
+
+---
+
+## Session Progress Log
+
+### {Date} — Session {session_id or timestamp}
+
+**Completed this session:**
+- [x] {Task from plan that was completed}
+- [x] {Another completed task}
+
+**Partially completed:**
+- {Task} — {current state, what remains}
+
+**Blocked/Deferred:**
+- {Task} — {reason, what's needed}
+
+**New items discovered:**
+- [ ] {New task not in original plan}
+- [ ] {Another new task}
+
+---
+```
+
+5. **If no plan document was provided**:
+   - Skip plan creation - the handoff document serves as the session record
+
+### Step 5: Save and Update Status
+
+Instead of writing the file directly, pipe your handoff content to the save script:
+
+```bash
+python .aiwcli/_shared/scripts/save_handoff.py "{context_id}" <<'EOF'
+{Your complete handoff markdown content from Step 3}
+EOF
+```
+
+This script:
+1. Creates a folder at `_output/contexts/{context_id}/handoffs/{YYYY-MM-DD-HHMM}/`
+2. Parses sections and writes sharded files (index.md, completed-work.md, dead-ends.md, etc.)
+3. Copies the current plan (if any) to plan.md
+4. Records the event in the context's event log (informational only)
+
+Use the handoff folder for context in the next session.
+
+## Dead Ends Section Guidelines
+
+This section is critical for preventing context rot across sessions. Be specific:
+
+**Bad (too vague):**
+> - Tried using library X, didn't work
+
+**Good (actionable):**
+> ### Fixing the race condition in SessionStore
+> | Approach Tried | Why It Failed |
+> |----------------|---------------|
+> | `async-mutex` package | Deadlock when nested calls to `getSession()` |
+> | Redis WATCH/MULTI | Our Redis 6.x cluster doesn't support WATCH in cluster mode |
+> | In-memory lock Map | Works single-node but breaks in horizontal scaling |
+>
+> **What to try instead**: Upgrade to Redis 7.x which supports WATCH in cluster mode, or use Redlock algorithm
+
+**Capture these dead ends:**
+- Packages/libraries that had incompatibilities
+- Approaches that caused new bugs or regressions
+- Solutions that worked locally but failed in CI/staging/prod
+- Configurations that conflicted with existing setup
+- Rabbit holes that consumed significant time without progress
+
+## Post-Generation Output
+
+After creating file, output:
+
+```
+✓ Created handoff folder: _output/contexts/{context_id}/handoffs/{YYYY-MM-DD-HHMM}/
+  - index.md (entry point with navigation)
+  - completed-work.md, dead-ends.md, decisions.md, pending.md, context.md
+  - plan.md (copy of current plan, if any)
+
+To continue next session:
+  The index.md will be automatically suggested when you start a new session.
+  Read dead-ends.md first to avoid repeating failed approaches.
+
+⚠️  {N} dead ends documented — avoid re-attempting these approaches
+```
 
-- `$ARGUMENTS` - Optional path to a plan document to update with progress tracking
+If plan was updated:
+```
+✓ Updated plan document: {path}
+   - {N} items marked complete
+   - {N} items partially complete
+   - {N} new items added
+```
 
-Load and execute `_shared/workflows/handoff.md`.
+## Success Criteria
 
-Follow the Gather → Analyze → Write → Update Context pattern.
+- [ ] Handoff folder created at `handoffs/{YYYY-MM-DD-HHMM}/`
+- [ ] index.md contains summary and navigation table
+- [ ] All section files created (completed-work.md, dead-ends.md, etc.)
+- [ ] Dead ends use structured table format for quick scanning
+- [ ] plan.md copied from context if plan exists
+- [ ] Next steps are actionable with file references
+- [ ] Git status included in index.md
+- [ ] If plan provided: checkboxes updated to reflect completion status
+- [ ] If plan provided: Session Progress Log appended
+- [ ] Context state updated to indicate handoff pending

package/dist/templates/_shared/hooks/context_enforcer.py

@@ -13,7 +13,7 @@ Context selection priority:
    - 1 in-flight context -> Auto-select that context
    - Multiple in-flight contexts -> Block and show picker
 
-In-flight modes: planning, pending_implementation, implementing, handoff_pending
+In-flight modes: planning, pending_implementation, implementing
 
 Prefix syntax:
 - ^: Show context picker (bare caret)
@@ -37,6 +37,7 @@ Hook output:
 - Exit 2 + stderr: Block request, show context picker to user
 """
 import json
+import os
 import re
 import sys
 from dataclasses import dataclass
@@ -48,6 +49,7 @@ SCRIPT_DIR = Path(__file__).resolve().parent
 SHARED_LIB = SCRIPT_DIR.parent / "lib"
 sys.path.insert(0, str(SHARED_LIB.parent))
 
+from lib.base.subprocess_utils import is_internal_call
 from lib.context.context_manager import (
     Context,
     get_all_contexts,
@@ -61,7 +63,6 @@ from lib.context.discovery import (
     get_in_flight_context,
     format_active_context_reminder,
     format_context_created,
-    format_handoff_continuation,
     format_pending_plan_continuation,
     format_implementation_continuation,
     _format_relative_time,
@@ -358,6 +359,11 @@ def determine_context(
     Raises:
         BlockRequest: When request should be blocked to show picker to user
     """
+    # 0. Skip context creation for internal subprocess calls (orchestrator, agents)
+    if is_internal_call():
+        eprint("[context_enforcer] Skipping: internal subprocess call")
+        return (None, "skip_internal", None)
+
     # 1. Check if session already belongs to a context (HIGHEST PRIORITY)
     # This prevents context switching on subsequent prompts - one context per session
     if session_id:
@@ -426,9 +432,7 @@ def determine_context(
         eprint(f"[context_enforcer] Auto-selected single in-flight context: {ctx.id} (mode={mode})")
 
         # Use mode-specific formatter for better continuation context
-        if mode == "handoff_pending":
-            output = format_handoff_continuation(ctx)
-        elif mode == "pending_implementation":
+        if mode == "pending_implementation":
             output = format_pending_plan_continuation(ctx)
         elif mode == "implementing":
             output = format_implementation_continuation(ctx)

package/dist/templates/_shared/hooks/context_monitor.py

@@ -191,11 +191,17 @@ Context ID: `{context_id}`"""
 
 def check_and_transition_mode(hook_input: dict) -> None:
     """
-    Check if context needs to transition from pending_implementation to implementing.
+    Check if context needs to transition to implementing mode.
 
-    This handles the case where a plan was approved and implementation has started,
-    but the context mode wasn't updated. If we're seeing tool usage (Edit, Write, Bash)
-    and the context is in "pending_implementation", we transition to "implementing".
+    This handles two cases:
+    1. Plan was approved (pending_implementation) and implementation tools are used
+    2. Plan was in planning mode but permission_mode is no longer "plan"
+       (e.g., after /clear which clears permissions and pastes the plan)
+
+    If we're seeing tool usage (Edit, Write, Bash) and either:
+    - Context is in "pending_implementation", OR
+    - Context is in "planning" and permission_mode is not "plan"
+    We transition to "implementing".
 
     Args:
         hook_input: Hook input data from Claude Code
@@ -218,11 +224,22 @@ def check_and_transition_mode(hook_input: dict) -> None:
     if not context:
         return
 
-    # Check if we need to transition
-    if context.in_flight and context.in_flight.mode == "pending_implementation":
+    if not context.in_flight:
+        return
+
+    current_mode = context.in_flight.mode
+    permission_mode = hook_input.get("permission_mode", "default")
+
+    # Transition from pending_implementation to implementing
+    if current_mode == "pending_implementation":
         eprint(f"[context_monitor] Transitioning {context.id} from pending_implementation to implementing")
         update_plan_status(context.id, "implementing", project_root=project_root)
 
+    # Transition from planning to implementing if permission_mode is not "plan"
+    elif current_mode == "planning" and permission_mode != "plan":
+        eprint(f"[context_monitor] Transitioning {context.id} from planning to implementing (permission_mode={permission_mode})")
+        update_plan_status(context.id, "implementing", project_root=project_root)
+
 
 def check_context_level(hook_input: dict) -> Optional[str]:
     """
@@ -261,9 +278,6 @@ def check_context_level(hook_input: dict) -> Optional[str]:
     eprint(f"[context_monitor] Context: {percent_remaining}% remaining "
            f"(~{tokens_used//1000}k/{max_tokens//1000}k tokens)")
 
-    # Check mode transition (file I/O)
-    check_and_transition_mode(hook_input)
-
     # Get current context for handoff info (file I/O)
     project_root = project_dir(hook_input)
     context_id = get_current_context_id(project_root)
@@ -283,7 +297,7 @@ def main():
     """
     Main entry point for PostToolUse hook.
 
-    Reads hook input from stdin, estimates context usage,
+    Reads hook input from stdin, checks for mode transitions,
     and prints system reminder if context is low.
     """
     try:
@@ -298,6 +312,10 @@ def main():
         except json.JSONDecodeError:
             return
 
+        # Always check for mode transitions on implementation tools
+        # This handles the case where /clear pastes the plan with non-plan permission mode
+        check_and_transition_mode(hook_input)
+
         # Check context level
         warning = check_context_level(hook_input)
 

package/dist/templates/_shared/hooks/file-suggestion.py

@@ -49,8 +49,8 @@ def get_context_files(context_id: str, project_root: Path) -> List[str]:
     Collects:
     - Context file (context.json)
     - Plans (most recent first)
-    - Handoffs (most recent first)
-    - Reviews (most recent first)
+    - Handoffs: index.md from subdirectories (folder-based) OR flat .md files (legacy)
+    - Reviews: index.md from subdirectories (folder-based) OR flat review.md (legacy)
 
     Args:
         context_id: Context identifier
@@ -76,22 +76,52 @@ def get_context_files(context_id: str, project_root: Path) -> List[str]:
         files.extend([str(p) for p in plan_files])
         eprint(f"[file-suggestion] Found {len(plan_files)} plans in {context_id}")
 
-    # Get handoffs directory
+    # Get handoffs - prefer folder-based (index.md in subdirectories), fall back to legacy
     handoffs_dir = get_context_handoffs_dir(context_id, project_root)
     if handoffs_dir.exists():
-        handoff_files = list(handoffs_dir.glob("*.md"))
-        handoff_files.sort(key=lambda p: p.stat().st_mtime, reverse=True)
-        files.extend([str(p) for p in handoff_files])
-        eprint(f"[file-suggestion] Found {len(handoff_files)} handoffs in {context_id}")
-
-    # Get reviews directory (includes cc-native subdirectory)
-    reviews_dir = get_context_reviews_dir(context_id, project_root)
+        # Find handoff folders (named like YYYY-MM-DD-HHMM or YYYY-MM-DD-HHMM-N)
+        handoff_folders = sorted(
+            [d for d in handoffs_dir.iterdir() if d.is_dir()],
+            key=lambda d: d.name,
+            reverse=True  # Most recent first (alphabetically sorts by date)
+        )
+
+        if handoff_folders:
+            # Use folder-based: get index.md from most recent folder only
+            index_file = handoff_folders[0] / "index.md"
+            if index_file.exists():
+                files.append(str(index_file))
+                eprint(f"[file-suggestion] Found handoff folder: {handoff_folders[0].name}")
+        else:
+            # Legacy support: flat .md files directly in handoffs/
+            legacy_handoffs = [f for f in handoffs_dir.glob("*.md") if f.is_file()]
+            legacy_handoffs.sort(key=lambda p: p.stat().st_mtime, reverse=True)
+            if legacy_handoffs:
+                files.append(str(legacy_handoffs[0]))  # Only most recent legacy
+                eprint(f"[file-suggestion] Found {len(legacy_handoffs)} legacy handoffs in {context_id}")
+
+    # Get reviews - prefer folder-based (index.md in subdirectories), fall back to legacy
+    reviews_dir = get_context_reviews_dir(context_id, project_root) / "cc-native"
     if reviews_dir.exists():
-        # Find review.md files in reviews/ and subdirectories (e.g., reviews/cc-native/review.md)
-        review_files = list(reviews_dir.glob("**/review.md"))
-        review_files.sort(key=lambda p: p.stat().st_mtime, reverse=True)
-        files.extend([str(p) for p in review_files])
-        eprint(f"[file-suggestion] Found {len(review_files)} reviews in {context_id}")
+        # Find review folders (named like YYYY-MM-DD-HHMM-iteration-N)
+        review_folders = sorted(
+            [d for d in reviews_dir.iterdir() if d.is_dir()],
+            key=lambda d: d.name,
+            reverse=True  # Most recent first
+        )
+
+        if review_folders:
+            # Use folder-based: get index.md from most recent folder only
+            index_file = review_folders[0] / "index.md"
+            if index_file.exists():
+                files.append(str(index_file))
+                eprint(f"[file-suggestion] Found review folder: {review_folders[0].name}")
+        else:
+            # Legacy support: flat review.md directly in cc-native/
+            legacy_review = reviews_dir / "review.md"
+            if legacy_review.exists():
+                files.append(str(legacy_review))
+                eprint(f"[file-suggestion] Found legacy review.md in {context_id}")
 
     return files
 

package/dist/templates/_shared/hooks/user_prompt_submit.py

@@ -33,7 +33,6 @@ from lib.base.utils import eprint, project_dir
 from lib.context.context_manager import (
     update_context_session_id,
     update_plan_status,
-    clear_handoff_status,
     get_context,
     get_context_by_session_id,
 )
@@ -47,7 +46,6 @@ def _update_in_flight_status(context_id: str, hook_input: dict, project_root: Pa
     """
     Update context in-flight status based on permission mode.
 
-    - If handoff_pending: clear it (handoff has been consumed by this session)
     - If permission_mode == "plan": set to "planning"
     - If permission_mode in ["acceptEdits", "bypassPermissions"]: set to "implementing"
     """
@@ -59,14 +57,6 @@ def _update_in_flight_status(context_id: str, hook_input: dict, project_root: Pa
     permission_mode = hook_input.get("permission_mode", "default")
     eprint(f"[user_prompt_submit] Current mode: {current_mode}, permission_mode: {permission_mode}")
 
-    # Clear handoff_pending if set (session resumption clears the handoff)
-    if current_mode == "handoff_pending":
-        clear_handoff_status(context_id, project_root)
-        eprint(f"[user_prompt_submit] Cleared handoff_pending status")
-        # Refresh context after clearing
-        context = get_context(context_id, project_root)
-        current_mode = context.in_flight.mode if context and context.in_flight else "none"
-
     # Set status based on permission mode
     if permission_mode == "plan":
         if current_mode != "planning":

package/dist/templates/_shared/lib/base/constants.py

@@ -297,3 +297,48 @@ def get_archive_index_path(project_root: Path = None) -> Path:
         Path to _output/contexts/archive/index.json
     """
     return get_archive_dir(project_root) / INDEX_FILENAME
+
+
+def get_handoff_folder_path(context_id: str, project_root: Path = None) -> Path:
+    """Get path for a new handoff folder with datetime naming.
+
+    Returns: _output/contexts/{context_id}/handoffs/{YYYY-MM-DD-HHMM}/
+    Handles collisions by appending -N suffix if folder exists.
+
+    Args:
+        context_id: Context identifier
+        project_root: Project root directory (default: cwd)
+
+    Returns:
+        Path to new handoff folder (not yet created)
+    """
+    from datetime import datetime
+    handoffs_dir = get_context_handoffs_dir(context_id, project_root)
+    timestamp = datetime.now().strftime("%Y-%m-%d-%H%M")
+    folder = handoffs_dir / timestamp
+
+    counter = 1
+    while folder.exists():
+        folder = handoffs_dir / f"{timestamp}-{counter}"
+        counter += 1
+
+    return folder
+
+
+def get_review_folder_path(context_id: str, iteration: int, project_root: Path = None) -> Path:
+    """Get path for a new review folder with datetime and iteration naming.
+
+    Returns: _output/contexts/{context_id}/reviews/cc-native/{YYYY-MM-DD-HHMM-iteration-N}/
+
+    Args:
+        context_id: Context identifier
+        iteration: Iteration number (1-based)
+        project_root: Project root directory (default: cwd)
+
+    Returns:
+        Path to new review folder (not yet created)
+    """
+    from datetime import datetime
+    reviews_dir = get_context_reviews_dir(context_id, project_root) / "cc-native"
+    timestamp = datetime.now().strftime("%Y-%m-%d-%H%M")
+    return reviews_dir / f"{timestamp}-iteration-{iteration}"

package/dist/templates/_shared/lib/base/inference.py

@@ -126,28 +126,54 @@ def inference(
         )
 
 
-# System prompt for generating context ID summaries
-CONTEXT_ID_SYSTEM_PROMPT = """Generate a 10-word summary of what the user wants to do. Start with a gerund (verb ending in -ing).
+# Minimum word length for context IDs (filters out short words like "I", "a", "to", "is")
+MIN_WORD_LENGTH = 3
+
+# Maximum number of words in context ID
+MAX_WORDS = 10
+
+
+def filter_short_words(text: str) -> str:
+    """Filter words by minimum length, keeping only words with 3+ characters.
+
+    This replaces the stopword list approach - a 3-char minimum naturally
+    filters out most function words (the, to, a, an, of, on, is, it, etc.)
+    """
+    # Handle contractions by replacing apostrophes before splitting
+    text = text.replace("'", " ").replace("'", " ")
+    words = text.lower().split()
+    # Filter to words with 3+ characters and limit to MAX_WORDS
+    filtered = [w for w in words if len(w) >= MIN_WORD_LENGTH][:MAX_WORDS]
+    return ' '.join(filtered)
+
+
+# System prompt for generating context ID summaries (recognition-focused, not summarization)
+CONTEXT_ID_SYSTEM_PROMPT = """Generate a memorable context ID that helps instantly recall what was being worked on.
+
+This is for RECOGNITION - the user will see this ID in a list and needs to immediately remember "oh yeah, THAT session."
 
 Rules:
-- Exactly 10 words
-- Start with gerund: Creating, Fixing, Adding, Updating, Implementing, etc.
-- Be specific about the task
-- No punctuation
-- No quotes
+- Output 3-6 words that capture the DISTINCTIVE essence
+- Lead with the ACTION (verb) being taken
+- Include the SPECIFIC target (file name, feature name, component name)
+- Prefer proper nouns and specific names over generic categories
+- NO function words: the, to, with, for, in, a, an, of, on, is, it, and, or
+- NO generic padding: code, project, app, webapp, system, implementation
+- No punctuation, no quotes
 
 Examples:
-- "I want to add user authentication" -> "Adding user authentication with JWT tokens to the web app"
-- "Fix the bug in the login flow" -> "Fixing critical bug in user login flow validation logic"
-- "Can you help me refactor this code" -> "Refactoring legacy code for better maintainability and cleaner architecture"
-- "Update the README with new instructions" -> "Updating README with new setup instructions and configuration examples"
+- "I want to add user authentication using JWT" -> "adding jwt auth user-service"
+- "Fix the bug in the login flow where users get redirected to a 404" -> "fixing login 404 redirect bug"
+- "Can you help me refactor the PaymentProcessor class" -> "refactoring paymentprocessor class"
+- "Update the README with new installation instructions" -> "readme installation instructions"
+- "Search for where the context ID extraction prompt is" -> "search context extraction prompt"
 
-Output ONLY the 10-word summary, nothing else."""
+Output ONLY the words separated by spaces, nothing else."""
 
 
 def generate_semantic_summary(prompt: str, timeout: int = 15) -> Optional[str]:
     """
-    Generate a semantic 10-word summary of a user prompt.
+    Generate a keyword summary of a user prompt.
 
     Uses Sonnet for quality inference. Returns None if inference fails.
 
@@ -156,9 +182,8 @@ def generate_semantic_summary(prompt: str, timeout: int = 15) -> Optional[str]:
         timeout: Timeout in seconds (default 15)
 
     Returns:
-        10-word summary string or None if failed
+        Keyword summary string (5-10 words) or None if failed
     """
-    # Pass full prompt - AI can summarize any length into 10 words
     result = inference(
         system_prompt=CONTEXT_ID_SYSTEM_PROMPT,
         user_prompt=prompt,
@@ -176,14 +201,12 @@ def generate_semantic_summary(prompt: str, timeout: int = 15) -> Optional[str]:
     # Remove trailing punctuation
     summary = summary.rstrip('.!?')
 
-    # Validate it starts with a gerund (capital letter + letters + "ing")
-    import re
-    if not re.match(r'^[A-Z][a-z]*ing\b', summary):
-        return None
+    # Filter to words with 3+ characters (removes short function words)
+    summary = filter_short_words(summary)
 
-    # Validate roughly 10 words (allow 8-12 for flexibility)
+    # Validate 3-10 words (allow flexibility for short prompts)
     words = summary.split()
-    if len(words) < 8 or len(words) > 12:
+    if len(words) < 3 or len(words) > 10:
         return None
 
     return summary

package/dist/templates/_shared/lib/base/subprocess_utils.py

@@ -0,0 +1,46 @@
+"""Utilities for subprocess calls that invoke Claude Code CLI.
+
+Provides centralized management of environment flags for internal subprocess calls
+(orchestrator, agents, inference) to prevent recursion and unnecessary hook overhead.
+"""
+import os
+from typing import Dict
+
+# Environment variable names - single source of truth
+ENV_INTERNAL_CALL = "AIWCLI_INTERNAL_CALL"
+
+
+def get_internal_subprocess_env() -> Dict[str, str]:
+    """Get environment dict for internal Claude Code subprocess calls.
+
+    This prevents internal subprocess calls (orchestrator, agents, inference)
+    from triggering hooks that would cause recursion or unnecessary overhead.
+
+    All hooks should check is_internal_call() and return early if True.
+
+    Returns:
+        Environment dict with AIWCLI_INTERNAL_CALL flag set
+
+    Example:
+        >>> env = get_internal_subprocess_env()
+        >>> subprocess.run(['claude', '--agent', 'my-agent'], env=env)
+    """
+    env = os.environ.copy()
+    env[ENV_INTERNAL_CALL] = 'true'
+    return env
+
+
+def is_internal_call() -> bool:
+    """Check if current process is an internal subprocess call.
+
+    Hooks should check this at the beginning and return early to avoid
+    recursion and unnecessary processing for internal subprocess calls.
+
+    Returns:
+        True if this is an internal call that should skip hooks
+
+    Example:
+        >>> if is_internal_call():
+        ...     return  # Skip hook processing
+    """
+    return os.environ.get(ENV_INTERNAL_CALL) == 'true'