hcom 0.4.2.post3__py3-none-any.whl → 0.6.0__py3-none-any.whl

hcom/cli.py

@@ -0,0 +1,4613 @@
+#!/usr/bin/env python3
+"""
+hcom
+CLI tool for launching multiple Claude Code terminals with interactive subagents, headless persistence, and real-time communication via hooks
+"""
+
+import os
+import sys
+import json
+import io
+import tempfile
+import shutil
+import shlex
+import re
+import subprocess
+import time
+import select
+import platform
+import random
+from pathlib import Path
+from datetime import datetime, timedelta
+from typing import Any, Callable, NamedTuple, TextIO
+from dataclasses import dataclass
+from contextlib import contextmanager
+
+if os.name == 'nt':
+    import msvcrt
+else:
+    import fcntl
+
+# Import from shared module
+from .shared import (
+    __version__,
+    # ANSI codes
+    RESET, FG_YELLOW,
+    # Config
+    DEFAULT_CONFIG_HEADER, DEFAULT_CONFIG_DEFAULTS,
+    parse_env_file, parse_env_value, format_env_value,
+    # Utilities
+    format_age, get_status_counts,
+    # Claude args parsing
+    resolve_claude_args, add_background_defaults, validate_conflicts,
+    extract_system_prompt_args, merge_system_prompts,
+)
+
+# Backwards compatibility for modules importing legacy helpers
+_parse_env_value = parse_env_value
+_format_env_value = format_env_value
+_parse_env_file = parse_env_file
+
+_HEADER_COMMENT_LINES: list[str] = []
+_HEADER_DEFAULT_EXTRAS: dict[str, str] = {}
+_header_data_started = False
+for _line in DEFAULT_CONFIG_HEADER:
+    stripped = _line.strip()
+    if not _header_data_started and (not stripped or stripped.startswith('#')):
+        _HEADER_COMMENT_LINES.append(_line)
+        continue
+    if not _header_data_started:
+        _header_data_started = True
+    if _header_data_started and '=' in _line:
+        key, _, value = _line.partition('=')
+        _HEADER_DEFAULT_EXTRAS[key.strip()] = parse_env_value(value)
+
+KNOWN_CONFIG_KEYS: list[str] = []
+DEFAULT_KNOWN_VALUES: dict[str, str] = {}
+for _entry in DEFAULT_CONFIG_DEFAULTS:
+    if '=' not in _entry:
+        continue
+    key, _, value = _entry.partition('=')
+    key = key.strip()
+    KNOWN_CONFIG_KEYS.append(key)
+    DEFAULT_KNOWN_VALUES[key] = parse_env_value(value)
+
+if sys.version_info < (3, 10):
+    sys.exit("Error: hcom requires Python 3.10 or higher")
+
+# ==================== Constants ====================
+
+IS_WINDOWS = sys.platform == 'win32'
+
+def is_wsl() -> bool:
+    """Detect if running in WSL"""
+    if platform.system() != 'Linux':
+        return False
+    try:
+        with open('/proc/version', 'r') as f:
+            return 'microsoft' in f.read().lower()
+    except (FileNotFoundError, PermissionError, OSError):
+        return False
+
+def is_termux() -> bool:
+    """Detect if running in Termux on Android"""
+    return (
+        'TERMUX_VERSION' in os.environ or              # Primary: Works all versions
+        'TERMUX__ROOTFS' in os.environ or              # Modern: v0.119.0+
+        Path('/data/data/com.termux').exists() or     # Fallback: Path check
+        'com.termux' in os.environ.get('PREFIX', '')   # Fallback: PREFIX check
+    )
+
+
+# Windows API constants
+CREATE_NO_WINDOW = 0x08000000  # Prevent console window creation
+
+# Timing constants
+FILE_RETRY_DELAY = 0.01  # 10ms delay for file lock retries
+STOP_HOOK_POLL_INTERVAL = 0.1     # 100ms between stop hook polls
+
+MENTION_PATTERN = re.compile(r'(?<![a-zA-Z0-9._-])@([\w-]+)')
+AGENT_NAME_PATTERN = re.compile(r'^[a-z-]+$')
+TIMESTAMP_SPLIT_PATTERN = re.compile(r'\n(?=\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d+\|)')
+
+# STATUS_MAP and status constants moved to shared.py (imported above)
+# ANSI codes moved to shared.py (imported above)
+
+# ==================== Windows/WSL Console Unicode ====================
+
+# Apply UTF-8 encoding for Windows and WSL
+if IS_WINDOWS or is_wsl():
+    try:
+        sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8')
+        sys.stderr = io.TextIOWrapper(sys.stderr.buffer, encoding='utf-8')
+    except (AttributeError, OSError):
+        pass # Fallback if stream redirection fails
+
+# ==================== Error Handling Strategy ====================
+# Hooks: Must never raise exceptions (breaks hcom). Functions return True/False.
+# CLI: Can raise exceptions for user feedback. Check return values.
+# Critical I/O: atomic_write, save_instance_position
+# Pattern: Try/except/return False in hooks, raise in CLI operations.
+
+# ==================== CLI Errors ====================
+
+class CLIError(Exception):
+    """Raised when arguments cannot be mapped to command semantics."""
+
+# ==================== Help Text ====================
+
+def get_help_text() -> str:
+    """Generate help text with current version"""
+    return f"""hcom {__version__}
+
+Usage: hcom   # UI
+       [ENV_VARS] hcom <COUNT> [claude <ARGS>...]
+       hcom watch [--logs|--status|--wait [SEC]]
+       hcom send "message"
+       hcom stop [alias|all]
+       hcom start [alias]
+       hcom reset [logs|hooks|config]
+
+Launch Examples:
+  hcom 3             Open 3 terminals with claude connected to hcom
+  hcom 3 claude -p                            + Headless
+  HCOM_TAG=api hcom 3 claude -p               + @-mention group tag
+  claude 'run hcom start'    claude code with prompt will also work
+
+Commands:
+  watch              messaging/status/launch UI (same as hcom no args)
+    --logs           Print all messages
+    --status         Print instance status JSON
+    --wait [SEC]     Wait and notify for new message
+
+  send "msg"         Send message to all instances
+  send "@alias msg"  Send to specific instance/group
+
+  stop               Stop current instance (from inside Claude)
+  stop <alias>       Stop specific instance
+  stop all           Stop all instances
+
+  start              Start current instance (from inside Claude)
+  start <alias>      Start specific instance
+
+  reset              Stop all + archive logs + remove hooks + clear config
+  reset logs         Clear + archive conversation log
+  reset hooks        Safely remove hcom hooks from claude settings.json
+  reset config       Clear + backup config.env
+
+Environment Variables:
+  HCOM_TAG=name              Group tag (creates name-* instances)
+  HCOM_AGENT=type            Agent type (comma-separated for multiple)
+  HCOM_TERMINAL=mode         Terminal: new|here|print|"custom {{script}}"
+  HCOM_HINTS=text            Text appended to all messages received by instance
+  HCOM_TIMEOUT=secs          Time until disconnected from hcom chat (default 1800s / 30mins)
+  HCOM_SUBAGENT_TIMEOUT=secs Subagent idle timeout (default 30s)
+  HCOM_CLAUDE_ARGS=args      Claude CLI defaults (e.g., '-p --model opus "hello!"')
+
+  ANTHROPIC_MODEL=opus # Any env var passed through to Claude Code
+
+  Persist Env Vars in `~/.hcom/config.env`
+"""
+
+
+# ==================== Logging ====================
+
+def log_hook_error(hook_name: str, error: Exception | str | None = None) -> None:
+    """Log hook exceptions or just general logging to ~/.hcom/.tmp/logs/hooks.log for debugging"""
+    import traceback
+    try:
+        log_file = hcom_path(LOGS_DIR) / "hooks.log"
+        timestamp = datetime.now().isoformat()
+        if error and isinstance(error, Exception):
+            tb = ''.join(traceback.format_exception(type(error), error, error.__traceback__))
+            with open(log_file, 'a') as f:
+                f.write(f"{timestamp}|{hook_name}|{type(error).__name__}: {error}\n{tb}\n")
+        else:
+            with open(log_file, 'a') as f:
+                f.write(f"{timestamp}|{hook_name}|{error or 'checkpoint'}\n")
+    except (OSError, PermissionError):
+        pass  # Silent failure in error logging
+
+# ==================== File Locking ====================
+
+@contextmanager
+def locked(fp, timeout=5.0):
+    """Context manager for cross-platform file locking with timeout"""
+    start = time.time()
+
+    if os.name == 'nt':
+        fp.seek(0)
+        # Lock entire file (0x7fffffff = 2GB max)
+        while time.time() - start < timeout:
+            try:
+                msvcrt.locking(fp.fileno(), msvcrt.LK_NBLCK, 0x7fffffff)
+                break
+            except OSError:
+                time.sleep(0.01)
+        else:
+            raise TimeoutError(f"Lock timeout after {timeout}s")
+    else:
+        # Non-blocking with retry
+        while time.time() - start < timeout:
+            try:
+                fcntl.flock(fp.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
+                break
+            except BlockingIOError:
+                time.sleep(0.01)
+        else:
+            raise TimeoutError(f"Lock timeout after {timeout}s")
+
+    try:
+        yield
+    finally:
+        if os.name == 'nt':
+            fp.seek(0)
+            msvcrt.locking(fp.fileno(), msvcrt.LK_UNLCK, 0x7fffffff)
+        else:
+            fcntl.flock(fp.fileno(), fcntl.LOCK_UN)
+
+# ==================== Config Defaults ====================
+# Config precedence: env var > ~/.hcom/config.env > defaults
+# All config via HcomConfig dataclass (timeout, terminal, prompt, hints, tag, agent)
+
+# Constants (not configurable)
+MAX_MESSAGE_SIZE = 1048576  # 1MB
+MAX_MESSAGES_PER_DELIVERY = 50
+SENDER = 'bigboss'
+SENDER_EMOJI = '🐳'
+SKIP_HISTORY = True  # New instances start at current log position (skip old messages)
+
+# Path constants
+LOG_FILE = "hcom.log"
+INSTANCES_DIR = "instances"
+LOGS_DIR = ".tmp/logs"
+SCRIPTS_DIR = ".tmp/scripts"
+FLAGS_DIR = ".tmp/flags"
+CONFIG_FILE = "config.env"
+ARCHIVE_DIR = "archive"
+
+# Hook configuration - single source of truth for setup_hooks() and verify_hooks_installed()
+# Format: (hook_type, matcher, command_suffix, timeout)
+# Command gets built as: hook_cmd_base + ' ' + command_suffix (e.g., '${HCOM} poll')
+HOOK_CONFIGS = [
+    ('SessionStart', '', 'sessionstart', None),
+    ('UserPromptSubmit', '', 'userpromptsubmit', None),
+    ('PreToolUse', 'Bash|Task', 'pre', None),
+    ('PostToolUse', 'Bash|Task', 'post', 86400),
+    ('Stop', '', 'poll', 86400),          # Poll for messages (24hr max timeout)
+    ('SubagentStop', '', 'subagent-stop', 86400),  # Subagent coordination (24hr max)
+    ('Notification', '', 'notify', None),
+    ('SessionEnd', '', 'sessionend', None),
+]
+
+# Derived from HOOK_CONFIGS - guaranteed to stay in sync
+ACTIVE_HOOK_TYPES = [cfg[0] for cfg in HOOK_CONFIGS]
+HOOK_COMMANDS = [cfg[2] for cfg in HOOK_CONFIGS]
+LEGACY_HOOK_TYPES = ACTIVE_HOOK_TYPES
+LEGACY_HOOK_COMMANDS = HOOK_COMMANDS
+
+# Hook removal patterns - used by _remove_hcom_hooks_from_settings()
+# Dynamically build from LEGACY_HOOK_COMMANDS to match current and legacy hook formats
+_HOOK_ARGS_PATTERN = '|'.join(LEGACY_HOOK_COMMANDS)
+HCOM_HOOK_PATTERNS = [
+    re.compile(r'\$\{?HCOM'),                                # Current: Environment variable ${HCOM:-...}
+    re.compile(r'\bHCOM_ACTIVE.*hcom\.py'),                 # LEGACY: Unix HCOM_ACTIVE conditional
+    re.compile(r'IF\s+"%HCOM_ACTIVE%"'),                    # LEGACY: Windows HCOM_ACTIVE conditional
+    re.compile(rf'\bhcom\s+({_HOOK_ARGS_PATTERN})\b'),       # LEGACY: Direct hcom command
+    re.compile(rf'\buvx\s+hcom\s+({_HOOK_ARGS_PATTERN})\b'), # LEGACY: uvx hcom command
+    re.compile(rf'hcom\.py["\']?\s+({_HOOK_ARGS_PATTERN})\b'), # LEGACY: hcom.py with optional quote
+    re.compile(rf'["\'][^"\']*hcom\.py["\']?\s+({_HOOK_ARGS_PATTERN})\b(?=\s|$)'),  # LEGACY: Quoted path
+    re.compile(r'sh\s+-c.*hcom'),                           # LEGACY: Shell wrapper
+]
+
+# PreToolUse hook pattern - matches hcom commands for session_id injection and auto-approval
+# - hcom send (any args)
+# - hcom stop (no args) | hcom start (no args or --_hcom_sender only)
+# - hcom help | hcom --help | hcom -h
+# - hcom watch --status | hcom watch --launch | hcom watch --logs | hcom watch --wait
+# Supports: hcom, uvx hcom, python -m hcom, python hcom.py, python hcom.pyz, /path/to/hcom.py[z]
+# Negative lookahead ensures stop/start not followed by alias targets (except --_hcom_sender for start)
+# Allows shell operators (2>&1, >/dev/null, |, &&) but blocks identifier-like targets (myalias, 123abc)
+HCOM_COMMAND_PATTERN = re.compile(
+    r'((?:uvx\s+)?hcom|python3?\s+-m\s+hcom|(?:python3?\s+)?\S*hcom\.pyz?)\s+'
+    r'(?:send\b|stop(?!\s+(?:[a-zA-Z_]|[0-9]+[a-zA-Z_])[-\w]*(?:\s|$))|start(?:\s+--_hcom_sender\s+\S+)?(?!\s+(?:[a-zA-Z_]|[0-9]+[a-zA-Z_])[-\w]*(?:\s|$))|(?:help|--help|-h)\b|watch\s+(?:--status|--launch|--logs|--wait)\b)'
+)
+
+# ==================== File System Utilities ====================
+
+def hcom_path(*parts: str, ensure_parent: bool = False) -> Path:
+    """Build path under ~/.hcom (or _HCOM_DIR if set)"""
+    base = os.environ.get('_HCOM_DIR') # for testing (underscore prefix bypasses HCOM_* filtering)
+    path = Path(base) if base else (Path.home() / ".hcom")
+    if parts:
+        path = path.joinpath(*parts)
+    if ensure_parent:
+        path.parent.mkdir(parents=True, exist_ok=True)
+    return path
+
+def ensure_hcom_directories() -> bool:
+    """Ensure all critical HCOM directories exist. Idempotent, safe to call repeatedly.
+    Called at hook entry to support opt-in scenarios where hooks execute before CLI commands.
+    Returns True on success, False on failure."""
+    try:
+        for dir_name in [INSTANCES_DIR, LOGS_DIR, SCRIPTS_DIR, FLAGS_DIR, ARCHIVE_DIR]:
+            hcom_path(dir_name).mkdir(parents=True, exist_ok=True)
+        return True
+    except (OSError, PermissionError):
+        return False
+
+def atomic_write(filepath: str | Path, content: str) -> bool:
+    """Write content to file atomically to prevent corruption (now with NEW and IMPROVED (wow!) Windows retry logic (cool!!!)). Returns True on success, False on failure."""
+    filepath = Path(filepath) if not isinstance(filepath, Path) else filepath
+    filepath.parent.mkdir(parents=True, exist_ok=True)
+
+    for attempt in range(3):
+        with tempfile.NamedTemporaryFile(mode='w', encoding='utf-8', delete=False, dir=filepath.parent, suffix='.tmp') as tmp:
+            tmp.write(content)
+            tmp.flush()
+            os.fsync(tmp.fileno())
+
+        try:
+            os.replace(tmp.name, filepath)
+            return True
+        except PermissionError:
+            if IS_WINDOWS and attempt < 2:
+                time.sleep(FILE_RETRY_DELAY)
+                continue
+            else:
+                try: # Clean up temp file on final failure
+                    Path(tmp.name).unlink()
+                except (FileNotFoundError, PermissionError, OSError):
+                    pass
+                return False
+        except Exception:
+            try: # Clean up temp file on any other error
+                os.unlink(tmp.name)
+            except (FileNotFoundError, PermissionError, OSError):
+                pass
+            return False
+
+    return False  # All attempts exhausted
+
+def read_file_with_retry(filepath: str | Path, read_func: Callable[[TextIO], Any], default: Any = None, max_retries: int = 3) -> Any:
+    """Read file with retry logic for Windows file locking"""
+    if not Path(filepath).exists():
+        return default
+
+    for attempt in range(max_retries):
+        try:
+            with open(filepath, 'r', encoding='utf-8') as f:
+                return read_func(f)
+        except PermissionError:
+            # Only retry on Windows (file locking issue)
+            if IS_WINDOWS and attempt < max_retries - 1:
+                time.sleep(FILE_RETRY_DELAY)
+            else:
+                # Re-raise on Unix or after max retries on Windows
+                if not IS_WINDOWS:
+                    raise  # Unix permission errors are real issues
+                break  # Windows: return default after retries
+        except (json.JSONDecodeError, FileNotFoundError, IOError):
+            break  # Don't retry on other errors
+
+    return default
+
+def get_instance_file(instance_name: str) -> Path:
+    """Get path to instance's position file with path traversal protection"""
+    # Sanitize instance name to prevent directory traversal
+    if not instance_name:
+        instance_name = "unknown"
+    safe_name = instance_name.replace('..', '').replace('/', '-').replace('\\', '-').replace(os.sep, '-')
+    if not safe_name:
+        safe_name = "unknown"
+
+    return hcom_path(INSTANCES_DIR, f"{safe_name}.json")
+
+def load_instance_position(instance_name: str) -> dict[str, Any]:
+    """Load position data for a single instance"""
+    instance_file = get_instance_file(instance_name)
+
+    data = read_file_with_retry(
+        instance_file,
+        lambda f: json.load(f),
+        default={}
+    )
+
+    return data
+
+def save_instance_position(instance_name: str, data: dict[str, Any]) -> bool:
+    """Save position data for a single instance. Returns True on success, False on failure."""
+    try:
+        instance_file = hcom_path(INSTANCES_DIR, f"{instance_name}.json")
+        return atomic_write(instance_file, json.dumps(data, indent=2))
+    except (OSError, PermissionError, ValueError):
+        return False
+
+def get_claude_settings_path() -> Path:
+    """Get path to global Claude settings file"""
+    return Path.home() / '.claude' / 'settings.json'
+
+def load_settings_json(settings_path: Path, default: Any = None) -> dict[str, Any] | None:
+    """Load and parse settings JSON file with retry logic"""
+    return read_file_with_retry(
+        settings_path,
+        lambda f: json.load(f),
+        default=default
+    )
+
+def load_all_positions() -> dict[str, dict[str, Any]]:
+    """Load positions from all instance files"""
+    instances_dir = hcom_path(INSTANCES_DIR)
+    if not instances_dir.exists():
+        return {}
+
+    positions = {}
+    for instance_file in instances_dir.glob("*.json"):
+        instance_name = instance_file.stem
+        data = read_file_with_retry(
+            instance_file,
+            lambda f: json.load(f),
+            default={}
+        )
+        if data:
+            positions[instance_name] = data
+    return positions
+
+def clear_all_positions() -> None:
+    """Clear all instance position files and related mapping files"""
+    instances_dir = hcom_path(INSTANCES_DIR)
+    if instances_dir.exists():
+        for f in instances_dir.glob('*.json'):
+            f.unlink()
+
+def list_available_agents() -> list[str]:
+    """List available agent types from .claude/agents/"""
+    agents = []
+    for base_path in (Path.cwd(), Path.home()):
+        agents_dir = base_path / '.claude' / 'agents'
+        if agents_dir.exists():
+            for agent_file in agents_dir.glob('*.md'):
+                name = agent_file.stem
+                if name not in agents and AGENT_NAME_PATTERN.fullmatch(name):
+                    agents.append(name)
+    return sorted(agents)
+
+# ==================== Configuration System ====================
+
+class HcomConfigError(ValueError):
+    """Raised when HcomConfig contains invalid values."""
+
+    def __init__(self, errors: dict[str, str]):
+        self.errors = errors
+        if errors:
+            message = "Invalid config:\n" + "\n".join(f"  - {msg}" for msg in errors.values())
+        else:
+            message = "Invalid config"
+        super().__init__(message)
+
+
+@dataclass
+class HcomConfig:
+    """HCOM configuration with validation. Load priority: env → file → defaults"""
+    timeout: int = 1800
+    subagent_timeout: int = 30
+    terminal: str = 'new'
+    hints: str = ''
+    tag: str = ''
+    agent: str = ''
+    claude_args: str = ''
+
+    def __post_init__(self):
+        """Validate configuration on construction"""
+        errors = self.collect_errors()
+        if errors:
+            raise HcomConfigError(errors)
+
+    def validate(self) -> list[str]:
+        """Validate all fields, return list of errors"""
+        return list(self.collect_errors().values())
+
+    def collect_errors(self) -> dict[str, str]:
+        """Validate fields and return dict of field → error message"""
+        errors: dict[str, str] = {}
+
+        def set_error(field: str, message: str) -> None:
+            if field in errors:
+                errors[field] = f"{errors[field]}; {message}"
+            else:
+                errors[field] = message
+
+        # Validate timeout
+        if isinstance(self.timeout, bool):
+            set_error('timeout', f"timeout must be an integer, not boolean (got {self.timeout})")
+        elif not isinstance(self.timeout, int):
+            set_error('timeout', f"timeout must be an integer, got {type(self.timeout).__name__}")
+        elif not 1 <= self.timeout <= 86400:
+            set_error('timeout', f"timeout must be 1-86400 seconds (24 hours), got {self.timeout}")
+
+        # Validate subagent_timeout
+        if isinstance(self.subagent_timeout, bool):
+            set_error('subagent_timeout', f"subagent_timeout must be an integer, not boolean (got {self.subagent_timeout})")
+        elif not isinstance(self.subagent_timeout, int):
+            set_error('subagent_timeout', f"subagent_timeout must be an integer, got {type(self.subagent_timeout).__name__}")
+        elif not 1 <= self.subagent_timeout <= 86400:
+            set_error('subagent_timeout', f"subagent_timeout must be 1-86400 seconds, got {self.subagent_timeout}")
+
+        # Validate terminal
+        if not isinstance(self.terminal, str):
+            set_error('terminal', f"terminal must be a string, got {type(self.terminal).__name__}")
+        elif not self.terminal:  # Empty string
+            set_error('terminal', "terminal cannot be empty")
+        else:
+            valid_modes = ('new', 'here', 'print')
+            if self.terminal not in valid_modes:
+                if '{script}' not in self.terminal:
+                    set_error(
+                        'terminal',
+                        f"terminal must be one of {valid_modes} or custom command with {{script}}, "
+                        f"got '{self.terminal}'"
+                    )
+
+        # Validate tag (only alphanumeric and hyphens - security: prevent log delimiter injection)
+        if not isinstance(self.tag, str):
+            set_error('tag', f"tag must be a string, got {type(self.tag).__name__}")
+        elif self.tag and not re.match(r'^[a-zA-Z0-9-]+$', self.tag):
+            set_error('tag', "tag can only contain letters, numbers, and hyphens")
+
+        # Validate agent
+        if not isinstance(self.agent, str):
+            set_error('agent', f"agent must be a string, got {type(self.agent).__name__}")
+        elif self.agent:  # Non-empty
+            for agent_name in self.agent.split(','):
+                agent_name = agent_name.strip()
+                if agent_name and not re.match(r'^[a-z-]+$', agent_name):
+                    set_error(
+                        'agent',
+                        f"agent '{agent_name}' must match pattern ^[a-z-]+$ "
+                        f"(lowercase letters and hyphens only)"
+                    )
+
+        # Validate claude_args (must be valid shell-quoted string)
+        if not isinstance(self.claude_args, str):
+            set_error('claude_args', f"claude_args must be a string, got {type(self.claude_args).__name__}")
+        elif self.claude_args:
+            try:
+                # Test if it can be parsed as shell args
+                shlex.split(self.claude_args)
+            except ValueError as e:
+                set_error('claude_args', f"claude_args contains invalid shell quoting: {e}")
+
+        return errors
+
+    @classmethod
+    def load(cls) -> 'HcomConfig':
+        """Load config with precedence: env var → file → defaults"""
+        # Ensure config file exists
+        config_path = hcom_path(CONFIG_FILE, ensure_parent=True)
+        created_config = False
+        if not config_path.exists():
+            _write_default_config(config_path)
+            created_config = True
+
+        # Warn once if legacy config.json still exists when creating config.env
+        legacy_config = hcom_path('config.json')
+        if created_config and legacy_config.exists():
+            print(
+                format_error(
+                    "Found legacy ~/.hcom/config.json; new config file is: ~/.hcom/config.env."
+                ),
+                file=sys.stderr,
+            )
+
+        # Parse config file once
+        file_config = _parse_env_file(config_path) if config_path.exists() else {}
+
+        def get_var(key: str) -> str | None:
+            """Get variable with precedence: env → file"""
+            if key in os.environ:
+                return os.environ[key]
+            if key in file_config:
+                return file_config[key]
+            return None
+
+        data = {}
+
+        # Load timeout (requires int conversion)
+        timeout_str = get_var('HCOM_TIMEOUT')
+        if timeout_str is not None and timeout_str != "":
+            try:
+                data['timeout'] = int(timeout_str)
+            except (ValueError, TypeError):
+                pass  # Use default
+
+        # Load subagent_timeout (requires int conversion)
+        subagent_timeout_str = get_var('HCOM_SUBAGENT_TIMEOUT')
+        if subagent_timeout_str is not None and subagent_timeout_str != "":
+            try:
+                data['subagent_timeout'] = int(subagent_timeout_str)
+            except (ValueError, TypeError):
+                pass  # Use default
+
+        # Load string values
+        terminal = get_var('HCOM_TERMINAL')
+        if terminal is not None:  # Empty string will fail validation
+            data['terminal'] = terminal
+        hints = get_var('HCOM_HINTS')
+        if hints is not None:  # Allow empty string for hints (valid value)
+            data['hints'] = hints
+        tag = get_var('HCOM_TAG')
+        if tag is not None:  # Allow empty string for tag (valid value)
+            data['tag'] = tag
+        agent = get_var('HCOM_AGENT')
+        if agent is not None:  # Allow empty string for agent (valid value)
+            data['agent'] = agent
+        claude_args = get_var('HCOM_CLAUDE_ARGS')
+        if claude_args is not None:  # Allow empty string for claude_args (valid value)
+            data['claude_args'] = claude_args
+
+        return cls(**data)  # Validation happens in __post_init__
+
+
+@dataclass
+class ConfigSnapshot:
+    core: HcomConfig
+    extras: dict[str, str]
+    values: dict[str, str]
+
+
+def hcom_config_to_dict(config: HcomConfig) -> dict[str, str]:
+    """Convert HcomConfig to string dict for persistence/display."""
+    return {
+        'HCOM_TIMEOUT': str(config.timeout),
+        'HCOM_SUBAGENT_TIMEOUT': str(config.subagent_timeout),
+        'HCOM_TERMINAL': config.terminal,
+        'HCOM_HINTS': config.hints,
+        'HCOM_TAG': config.tag,
+        'HCOM_AGENT': config.agent,
+        'HCOM_CLAUDE_ARGS': config.claude_args,
+    }
+
+
+def dict_to_hcom_config(data: dict[str, str]) -> HcomConfig:
+    """Convert string dict (HCOM_* keys) into validated HcomConfig."""
+    errors: dict[str, str] = {}
+    kwargs: dict[str, Any] = {}
+
+    timeout_raw = data.get('HCOM_TIMEOUT')
+    if timeout_raw is not None:
+        stripped = timeout_raw.strip()
+        if stripped:
+            try:
+                kwargs['timeout'] = int(stripped)
+            except ValueError:
+                errors['timeout'] = f"timeout must be an integer, got '{timeout_raw}'"
+        else:
+            # Explicit empty string is an error (can't be blank)
+            errors['timeout'] = 'timeout cannot be empty (must be 1-86400 seconds)'
+
+    subagent_raw = data.get('HCOM_SUBAGENT_TIMEOUT')
+    if subagent_raw is not None:
+        stripped = subagent_raw.strip()
+        if stripped:
+            try:
+                kwargs['subagent_timeout'] = int(stripped)
+            except ValueError:
+                errors['subagent_timeout'] = f"subagent_timeout must be an integer, got '{subagent_raw}'"
+        else:
+            # Explicit empty string is an error (can't be blank)
+            errors['subagent_timeout'] = 'subagent_timeout cannot be empty (must be positive integer)'
+
+    terminal_val = data.get('HCOM_TERMINAL')
+    if terminal_val is not None:
+        stripped = terminal_val.strip()
+        if stripped:
+            kwargs['terminal'] = stripped
+        else:
+            # Explicit empty string is an error (can't be blank)
+            errors['terminal'] = 'terminal cannot be empty (must be: new, here, print, or custom command)'
+
+    # Optional fields - allow empty strings
+    if 'HCOM_HINTS' in data:
+        kwargs['hints'] = data['HCOM_HINTS']
+    if 'HCOM_TAG' in data:
+        kwargs['tag'] = data['HCOM_TAG']
+    if 'HCOM_AGENT' in data:
+        kwargs['agent'] = data['HCOM_AGENT']
+    if 'HCOM_CLAUDE_ARGS' in data:
+        kwargs['claude_args'] = data['HCOM_CLAUDE_ARGS']
+
+    if errors:
+        raise HcomConfigError(errors)
+
+    return HcomConfig(**kwargs)
+
+
+def load_config_snapshot() -> ConfigSnapshot:
+    """Load config.env into structured snapshot (file contents only)."""
+    config_path = hcom_path(CONFIG_FILE, ensure_parent=True)
+    if not config_path.exists():
+        _write_default_config(config_path)
+
+    file_values = parse_env_file(config_path)
+
+    extras: dict[str, str] = {k: v for k, v in _HEADER_DEFAULT_EXTRAS.items()}
+    raw_core: dict[str, str] = {}
+
+    for key in KNOWN_CONFIG_KEYS:
+        if key in file_values:
+            raw_core[key] = file_values.pop(key)
+        else:
+            raw_core[key] = DEFAULT_KNOWN_VALUES.get(key, '')
+
+    for key, value in file_values.items():
+        extras[key] = value
+
+    try:
+        core = dict_to_hcom_config(raw_core)
+    except HcomConfigError as exc:
+        core = HcomConfig()
+        # Keep raw values so the UI can surface issues; log once for CLI users.
+        if exc.errors:
+            print(exc, file=sys.stderr)
+
+    core_values = hcom_config_to_dict(core)
+    # Preserve raw strings for display when they differ from validated values.
+    for key, raw_value in raw_core.items():
+        if raw_value != '' and raw_value != core_values.get(key, ''):
+            core_values[key] = raw_value
+
+    return ConfigSnapshot(core=core, extras=extras, values=core_values)
+
+
+def save_config_snapshot(snapshot: ConfigSnapshot) -> None:
+    """Write snapshot to config.env in canonical form."""
+    config_path = hcom_path(CONFIG_FILE, ensure_parent=True)
+
+    lines: list[str] = list(_HEADER_COMMENT_LINES)
+    if lines and lines[-1] != '':
+        lines.append('')
+
+    core_values = hcom_config_to_dict(snapshot.core)
+    for entry in DEFAULT_CONFIG_DEFAULTS:
+        key, _, _ = entry.partition('=')
+        key = key.strip()
+        value = core_values.get(key, '')
+        formatted = _format_env_value(value)
+        if formatted:
+            lines.append(f"{key}={formatted}")
+        else:
+            lines.append(f"{key}=")
+
+    extras = {**_HEADER_DEFAULT_EXTRAS, **snapshot.extras}
+    for key in KNOWN_CONFIG_KEYS:
+        extras.pop(key, None)
+
+    if extras:
+        if lines and lines[-1] != '':
+            lines.append('')
+        for key in sorted(extras.keys()):
+            value = extras[key]
+            formatted = _format_env_value(value)
+            lines.append(f"{key}={formatted}" if formatted else f"{key}=")
+
+    content = '\n'.join(lines) + '\n'
+    atomic_write(config_path, content)
+
+
+def save_config(core: HcomConfig, extras: dict[str, str]) -> None:
+    """Convenience helper for writing canonical config."""
+    snapshot = ConfigSnapshot(core=core, extras=extras, values=hcom_config_to_dict(core))
+    save_config_snapshot(snapshot)
+def _write_default_config(config_path: Path) -> None:
+    """Write default config file with documentation"""
+    try:
+        content = '\n'.join(DEFAULT_CONFIG_HEADER) + '\n' + '\n'.join(DEFAULT_CONFIG_DEFAULTS) + '\n'
+        atomic_write(config_path, content)
+    except Exception:
+        pass
+
+# Global config instance (cached)
+_config: HcomConfig | None = None
+
+def get_config() -> HcomConfig:
+    """Get cached config, loading if needed"""
+    global _config
+    if _config is None:
+        # Detect if running as hook handler (called via 'hcom pre', 'hcom post', etc.)
+        is_hook_context = (
+            len(sys.argv) >= 2 and
+            sys.argv[1] in ('pre', 'post', 'sessionstart', 'userpromptsubmit', 'sessionend', 'subagent-stop', 'poll', 'notify')
+        )
+
+        try:
+            _config = HcomConfig.load()
+        except ValueError:
+            # Config validation failed
+            if is_hook_context:
+                # In hooks, use defaults silently (don't break vanilla Claude Code)
+                _config = HcomConfig()
+            else:
+                # In commands, re-raise to show user the error
+                raise
+
+    return _config
+
+
+def reload_config() -> HcomConfig:
+    """Clear cached config so next access reflects latest file/env values."""
+    global _config
+    _config = None
+    return get_config()
+
+def _build_quoted_invocation() -> str:
+    """Build invocation for fallback case - handles packages and pyz
+
+    For packages (pip/uvx/uv tool), uses 'python -m hcom'.
+    For pyz/zipapp, uses direct file path to re-invoke the same archive.
+    """
+    python_path = sys.executable
+
+    # Detect if running inside a pyz/zipapp
+    import zipimport
+    loader = getattr(sys.modules[__name__], "__loader__", None)
+    is_zipapp = isinstance(loader, zipimport.zipimporter)
+
+    # For pyz, use __file__ path; for packages, use -m
+    if is_zipapp or not __package__:
+        # Standalone pyz or script - use direct file path
+        script_path = str(Path(__file__).resolve())
+        if IS_WINDOWS:
+            py = f'"{python_path}"' if ' ' in python_path else python_path
+            sp = f'"{script_path}"' if ' ' in script_path else script_path
+            return f'{py} {sp}'
+        else:
+            return f'{shlex.quote(python_path)} {shlex.quote(script_path)}'
+    else:
+        # Package install (pip/uv tool/editable) - use -m
+        if IS_WINDOWS:
+            py = f'"{python_path}"' if ' ' in python_path else python_path
+            return f'{py} -m hcom'
+        else:
+            return f'{shlex.quote(python_path)} -m hcom'
+
+def get_hook_command() -> tuple[str, dict[str, Any]]:
+    """Get hook command - hooks always run, Python code gates participation
+
+    Uses ${HCOM} environment variable set in settings.json, with fallback to direct python invocation.
+    Participation is controlled by enabled flag in instance JSON files.
+
+    Windows uses direct invocation because hooks in settings.json run in CMD/PowerShell context,
+    not Git Bash, so ${HCOM} shell variable expansion doesn't work (would need %HCOM% syntax).
+    """
+    if IS_WINDOWS:
+        # Windows: hooks run in CMD context, can't use ${HCOM} syntax
+        return _build_quoted_invocation(), {}
+    else:
+        # Unix: Use HCOM env var from settings.json
+        return '${HCOM}', {}
+
+def _detect_hcom_command_type() -> str:
+    """Detect how to invoke hcom based on execution context
+    Priority:
+    1. uvx - If running in uv-managed Python and uvx available
+           (works for both temporary uvx runs and permanent uv tool install)
+    2. short - If hcom binary in PATH
+    3. full - Fallback to full python invocation
+    """
+    if 'uv' in Path(sys.executable).resolve().parts and shutil.which('uvx'):
+        return 'uvx'
+    elif shutil.which('hcom'):
+        return 'short'
+    else:
+        return 'full'
+
+def _parse_version(v: str) -> tuple:
+    """Parse version string to comparable tuple"""
+    return tuple(int(x) for x in v.split('.') if x.isdigit())
+
+def get_update_notice() -> str | None:
+    """Check PyPI for updates (once daily), return message if available"""
+    flag = hcom_path(FLAGS_DIR, 'update_available')
+
+    # Check PyPI if flag missing or >24hrs old
+    should_check = not flag.exists() or time.time() - flag.stat().st_mtime > 86400
+
+    if should_check:
+        try:
+            import urllib.request
+            with urllib.request.urlopen('https://pypi.org/pypi/hcom/json', timeout=2) as f:
+                latest = json.load(f)['info']['version']
+
+            if _parse_version(latest) > _parse_version(__version__):
+                atomic_write(flag, latest)  # mtime = cache timestamp
+            else:
+                flag.unlink(missing_ok=True)
+                return None
+        except Exception:
+            pass  # Network error, use cached value if exists
+
+    # Return message if update available
+    if not flag.exists():
+        return None
+
+    try:
+        latest = flag.read_text().strip()
+        # Double-check version (handles manual upgrades)
+        if _parse_version(__version__) >= _parse_version(latest):
+            flag.unlink(missing_ok=True)
+            return None
+
+        cmd = "uv tool upgrade hcom" if _detect_hcom_command_type() == 'uvx' else "pip install -U hcom"
+        return f"→ hcom v{latest} available: {cmd}"
+    except Exception:
+        return None
+
+def _build_hcom_env_value() -> str:
+    """Build the value for settings['env']['HCOM'] based on current execution context
+    Uses build_hcom_command() without caching for fresh detection on every call.
+    """
+    return build_hcom_command(None)
+
+def build_hcom_command(instance_name: str | None = None) -> str:
+    """Build base hcom command based on execution context
+
+    Detection always runs fresh to avoid staleness when installation method changes.
+    The instance_name parameter is kept for API compatibility but no longer used for caching.
+    """
+    cmd_type = _detect_hcom_command_type()
+
+    # Build command based on type
+    if cmd_type == 'short':
+        return 'hcom'
+    elif cmd_type == 'uvx':
+        return 'uvx hcom'
+    else:
+        # Full path fallback
+        return _build_quoted_invocation()
+
+def build_claude_env() -> dict[str, str]:
+    """Load config.env as environment variable defaults.
+
+    Returns all vars from config.env (including HCOM_*).
+    Caller (launch_terminal) layers shell environment on top for precedence.
+    """
+    env = {}
+
+    # Read all vars from config file as defaults
+    config_path = hcom_path(CONFIG_FILE)
+    if config_path.exists():
+        file_config = _parse_env_file(config_path)
+        for key, value in file_config.items():
+            if value == "":
+                continue  # Skip blank values
+            env[key] = str(value)
+
+    return env
+
+# ==================== Message System ====================
+
+def validate_message(message: str) -> str | None:
+    """Validate message size and content. Returns error message or None if valid."""
+    if not message or not message.strip():
+        return format_error("Message required")
+
+    # Reject control characters (except \n, \r, \t)
+    if re.search(r'[\x00-\x08\x0B-\x0C\x0E-\x1F\u0080-\u009F]', message):
+        return format_error("Message contains control characters")
+
+    if len(message) > MAX_MESSAGE_SIZE:
+        return format_error(f"Message too large (max {MAX_MESSAGE_SIZE} chars)")
+
+    return None
+
+def send_message(from_instance: str, message: str) -> bool:
+    """Send a message to the log"""
+    try:
+        log_file = hcom_path(LOG_FILE)
+
+        escaped_message = message.replace('|', '\\|')
+        escaped_from = from_instance.replace('|', '\\|')
+
+        timestamp = datetime.now().isoformat()
+        line = f"{timestamp}|{escaped_from}|{escaped_message}\n"
+
+        with open(log_file, 'a', encoding='utf-8') as f:
+            with locked(f):
+                f.write(line)
+                f.flush()
+
+        # Notify all instances of new message
+        notify_all_instances()
+
+        return True
+    except Exception:
+        return False
+
+def notify_all_instances(timeout: float = 0.05) -> None:
+    """Send TCP wake notifications to all instance notify ports.
+
+    Best effort - connection failures ignored. Polling fallback ensures
+    message delivery even if all notifications fail.
+
+    Only notifies enabled instances - disabled instances are skipped.
+    """
+    import socket
+    try:
+        positions = load_all_positions()
+    except Exception:
+        return
+
+    for instance_name, data in positions.items():
+        # Skip disabled instances (don't wake stopped instances)
+        if not data.get('enabled', False):
+            continue
+
+        notify_port = data.get('notify_port')
+        if not isinstance(notify_port, int) or notify_port <= 0:
+            continue
+
+        # Connection attempt doubles as notification
+        try:
+            with socket.create_connection(('127.0.0.1', notify_port), timeout=timeout) as sock:
+                sock.send(b'\n')
+        except Exception:
+            pass  # Port dead/unreachable - skip notification (best effort)
+
+def notify_instance(instance_name: str, timeout: float = 0.05) -> None:
+    """Send TCP notification to specific instance."""
+    import socket
+    try:
+        instance_data = load_instance_position(instance_name)
+        notify_port = instance_data.get('notify_port')
+        if not isinstance(notify_port, int) or notify_port <= 0:
+            return
+
+        with socket.create_connection(('127.0.0.1', notify_port), timeout=timeout) as sock:
+            sock.send(b'\n')
+    except Exception:
+        pass  # Instance will see change on next timeout (fallback)
+
+def build_hcom_bootstrap_text(instance_name: str) -> str:
+    """Build comprehensive HCOM bootstrap context for instances"""
+    hcom_cmd = build_hcom_command()
+
+    # Add command override notice if not using short form
+    command_notice = ""
+    if hcom_cmd != "hcom":
+        command_notice = f"""IMPORTANT:
+The hcom command in this environment is: {hcom_cmd}
+Replace all mentions of "hcom" below with this command.
+
+"""
+
+    # Add tag-specific notice if instance is tagged
+    tag = get_config().tag
+    tag_notice = ""
+    if tag:
+        tag_notice = f"""
+GROUP TAG: You are in the '{tag}' group.
+- To message your group: hcom send "@{tag} your message"
+- Group messages are targeted - only instances with an alias starting with {tag}-* receive them
+- If someone outside the group sends you @{tag} messages, they won't see your @{tag} replies. To reply to non-group members, either @mention them directly or broadcast.
+"""
+
+
+    return f"""{command_notice}{tag_notice}
+[HCOM SESSION CONFIG]
+- HCOM is a communication tool for you, other claude code instances, and the human user.
+- Your HCOM alias for this session: {instance_name}
+
+Your HCOM Tools:
+- hcom send "msg" (broadcast) / "@alias msg" (direct) / "@tag msg" (tag) - for you
+- hcom watch --status  → See participants JSON (for you only)
+- hcom watch --launch   → Open interactive TUI messaging+launch+monitor dashboard in new terminal (for the human user)
+- hcom start/stop   → Connect/disconnect from chat (you run these, user can't run it themselves unless they specify an alias)
+- hcom <count>  → Launch instances in new terminal (you MUST run 'hcom help' first to understand context or if user asks about hcom)
+- Claude code subagents launched with the Task tool can also connect to HCOM, just tell them to use 'hcom'.
+
+UI:
+- The human user has the 'hcom' (no args) command.
+- You use 'hcom watch --launch' to open it for them (you should offer to do so).
+- In conversation, call it 'hcom' (the command they'd run themselves) or the dashboard/ui, dont say 'hcom watch --launch'.
+
+Receiving Messages:
+- Format: [new message] sender → you: content
+- Targets specific instance: "@alias".
+- Targets all api-* tagged instances: "@api message".
+- Arrives automatically via hooks/bash. No proactive checking needed.
+- Stop hook feedback shows: {{"decision": "block"}} (this is normal operation).
+
+Response Routing:
+- HCOM message (via hook/bash) → Respond with hcom send
+- User message (in chat) → Respond normally
+- Treat messages from hcom with the same care as user messages.
+- Authority: Prioritize @{SENDER} over other participants.
+
+This is context for YOUR hcom session config. The human user cannot see this config text (but they can see subsequent hcom messages you receive).
+On connection, tell the human user about only these commands: 'hcom <count>', 'hcom', 'hcom start', 'hcom stop'
+Report to the human user using first-person, for example: "I'm connected to HCOM as {instance_name}, cool!"
+"""
+
+def build_launch_context(instance_name: str) -> str:
+    """Build context for launch command"""
+    return f"""[HCOM LAUNCH INFORMATION]
+BASIC USAGE:
+[ENV_VARS] hcom <COUNT> [claude <ARGS>...]
+- directory-specific (always cd to project directory first)
+- default to foreground instances unless told otherwise/good reason to do bg
+- Everyone shares the same conversation log, isolation is possible with tags and at-mentions.
+
+ENV VARS INFO:
+- YOU cannot use 'HCOM_TERMINAL=here' - Claude cannot launch claude within itself, must be in a new or custom terminal
+- HCOM_AGENT(s) are custom system prompt files created by users/Claude beforehand.
+- HCOM_AGENT(s) load from .claude/agents/<name>.md if they have been created
+
+KEY CLAUDE ARGS:
+Run 'claude --help' for all claude code CLI args. hcom 1 claude [options] [command] [prompt]
+-p           headless instance
+--allowedTools=Bash   (headless can only hcom chat otherwise, 'claude help' for more tools)
+--model sonnet/haiku/opus
+--resume <sessionid>       (get sessionid from hcom watch --status)
+--system-prompt (for interactive instances) --append-system-prompt (for headless instances)
+Example: HCOM_HINTS='essential responses only' hcom 2 claude --model sonnet -p "do task x"
+
+CONTROL: 
+  hcom watch --status    JSON status of all instances
+  hcom watch --logs      All messages (pipe to tail)
+  hcom watch --wait      Block until next message (only use when hcom stopped (started is automatic already))
+
+STATUS INDICATORS:
+  "active", "delivered" | "idle" - waiting for new messages
+  "blocked" - permission request (needs user approval)
+  "inactive" - timed out, disconnected etc
+  "unknown" / "stale" - crashed or hung
+
+LAUNCH PATTERNS:
+- HCOM_AGENT=reviewer,tester hcom 2 claude "do task x"  # 2x reviewers + 2x testers (4 in total) with initial prompt
+- clone with same context:
+    1. hcom 1 then hcom send 'analyze api' then hcom watch --status (get sessionid)
+    2. HCOM_TAG=clone hcom 3 claude --resume sessionid
+- System prompt (or agent file) + initial prompt + hcom_hints is a powerful combination.
+
+"""
+
+def should_deliver_message(msg: dict[str, str], instance_name: str, all_instance_names: list[str] | None = None) -> bool:
+    """Check if message should be delivered based on @-mentions and group isolation.
+    Group isolation rules:
+    - CLI (bigboss) broadcasts → everyone (all parents and subagents)
+    - Parent broadcasts → other parents only (subagents shut down during their own parent activity)
+    - Subagent broadcasts → same group subagents only (parent frozen during their subagents activity)
+    - @-mentions → cross all boundaries like a nice piece of chocolate cake or fried chicken
+    """
+    text = msg['message']
+    sender = msg['from']
+
+    # Load instance data for group membership
+    sender_data = load_instance_position(sender)
+    receiver_data = load_instance_position(instance_name)
+
+    # Determine if sender/receiver are parents or subagents
+    sender_is_parent = is_parent_instance(sender_data)
+    receiver_is_parent = is_parent_instance(receiver_data)
+
+    # Check for @-mentions first (crosses all boundaries! yay!)
+    if '@' in text:
+        mentions = MENTION_PATTERN.findall(text)
+
+        if mentions:
+            # Check if this instance matches any mention
+            this_instance_matches = any(instance_name.lower().startswith(mention.lower()) for mention in mentions)
+            if this_instance_matches:
+                return True
+
+            # Check if CLI sender (bigboss) is mentioned
+            sender_mentioned = any(SENDER.lower().startswith(mention.lower()) for mention in mentions)
+
+            # Broadcast fallback: no matches anywhere = broadcast with group rules
+            if all_instance_names:
+                any_mention_matches = any(
+                    any(name.lower().startswith(mention.lower()) for name in all_instance_names)
+                    for mention in mentions
+                ) or sender_mentioned
+
+                if not any_mention_matches:
+                    # Fall through to group isolation rules
+                    pass
+                else:
+                    # Mention matches someone else, not us
+                    return False
+            else:
+                # No instance list provided, assume mentions are valid and we're not the target
+                return False
+        # else: Has @ but no valid mentions, fall through to broadcast rules
+
+    # Special case: CLI sender (bigboss) broadcasts to everyone
+    if sender == SENDER:
+        return True
+
+    # GROUP ISOLATION for broadcasts
+    # Rule 1: Parent → Parent (main communication)
+    if sender_is_parent and receiver_is_parent:
+        # Different groups = allow (parent-to-parent is the main channel)
+        return True
+
+    # Rule 2: Subagent → Subagent (same group only)
+    if not sender_is_parent and not receiver_is_parent:
+        return in_same_group(sender_data, receiver_data)
+
+    # Rule 3: Parent → Subagent or Subagent → Parent (temporally impossible, filter)
+    # This shouldn't happen due to temporal isolation, but filter defensively TODO: consider if better to not filter these as parent could get it after children die - messages can be recieved any time you dont both have to be alive at the same time. like fried chicken.
+    return False
+
+def is_parent_instance(instance_data: dict[str, Any] | None) -> bool:
+    """Check if instance is a parent (has session_id, no parent_session_id)"""
+    if not instance_data:
+        return False
+    has_session = bool(instance_data.get('session_id'))
+    has_parent = bool(instance_data.get('parent_session_id'))
+    return has_session and not has_parent
+
+def is_subagent_instance(instance_data: dict[str, Any] | None) -> bool:
+    """Check if instance is a subagent (has parent_session_id)"""
+    if not instance_data:
+        return False
+    return bool(instance_data.get('parent_session_id'))
+
+def get_group_session_id(instance_data: dict[str, Any] | None) -> str | None:
+    """Get the session_id that defines this instance's group.
+    For parents: their own session_id, for subagents: parent_session_id
+    """
+    if not instance_data:
+        return None
+    # Subagent - use parent_session_id
+    if parent_sid := instance_data.get('parent_session_id'):
+        return parent_sid
+    # Parent - use own session_id
+    return instance_data.get('session_id')
+
+def in_same_group(sender_data: dict[str, Any] | None, receiver_data: dict[str, Any] | None) -> bool:
+    """Check if sender and receiver are in same group (share session_id)"""
+    sender_group = get_group_session_id(sender_data)
+    receiver_group = get_group_session_id(receiver_data)
+    if not sender_group or not receiver_group:
+        return False
+    return sender_group == receiver_group
+
+def in_subagent_context(instance_data: dict[str, Any] | None) -> bool:
+    """Check if hook (or any code) is being called from subagent context (not parent).
+    Returns True when parent has current_subagents list, meaning:
+    - A subagent is calling this code (parent is frozen during Task)
+    - instance_data is the parent's data (hooks resolve to parent session_id)
+    """
+    if not instance_data:
+        return False
+    return bool(instance_data.get('current_subagents'))
+
+# ==================== Parsing & Utilities ====================
+
+def extract_agent_config(content: str) -> dict[str, str]:
+    """Extract configuration from agent YAML frontmatter"""
+    if not content.startswith('---'):
+        return {}
+    
+    # Find YAML section between --- markers
+    if (yaml_end := content.find('\n---', 3)) < 0:
+        return {}  # No closing marker
+    
+    yaml_section = content[3:yaml_end]
+    config = {}
+    
+    # Extract model field
+    if model_match := re.search(r'^model:\s*(.+)$', yaml_section, re.MULTILINE):
+        value = model_match.group(1).strip()
+        if value and value.lower() != 'inherit':
+            config['model'] = value
+
+    # Extract tools field
+    if tools_match := re.search(r'^tools:\s*(.+)$', yaml_section, re.MULTILINE):
+        value = tools_match.group(1).strip()
+        if value:
+            config['tools'] = value.replace(', ', ',')
+    
+    return config
+
+def resolve_agent(name: str) -> tuple[str, dict[str, str]]:
+    """Resolve agent file by name with validation.
+    Looks for agent files in:
+    1. .claude/agents/{name}.md (local)
+    2. ~/.claude/agents/{name}.md (global)
+    Returns tuple: (content without YAML frontmatter, config dict)
+    """
+    hint = 'Agent names must use lowercase letters and dashes only'
+
+    if not isinstance(name, str):
+        raise FileNotFoundError(format_error(
+            f"Agent '{name}' not found",
+            hint
+        ))
+
+    candidate = name.strip()
+    display_name = candidate or name
+
+    if not candidate or not AGENT_NAME_PATTERN.fullmatch(candidate):
+        raise FileNotFoundError(format_error(
+            f"Agent '{display_name}' not found",
+            hint
+        ))
+
+    for base_path in (Path.cwd(), Path.home()):
+        agents_dir = base_path / '.claude' / 'agents'
+        try:
+            agents_dir_resolved = agents_dir.resolve(strict=True)
+        except FileNotFoundError:
+            continue
+
+        agent_path = agents_dir / f'{candidate}.md'
+        if not agent_path.exists():
+            continue
+
+        try:
+            resolved_agent_path = agent_path.resolve(strict=True)
+        except FileNotFoundError:
+            continue
+
+        try:
+            resolved_agent_path.relative_to(agents_dir_resolved)
+        except ValueError:
+            continue
+
+        content = read_file_with_retry(
+            agent_path,
+            lambda f: f.read(),
+            default=None
+        )
+        if content is None:
+            continue
+
+        config = extract_agent_config(content)
+        stripped = strip_frontmatter(content)
+        if not stripped.strip():
+            raise ValueError(format_error(
+                f"Agent '{candidate}' has empty content",
+                'Check the agent file is a valid format and contains text'
+            ))
+        return stripped, config
+
+    raise FileNotFoundError(format_error(
+        f"Agent '{candidate}' not found in project or user .claude/agents/ folder",
+        'Check available agents or create the agent file'
+    ))
+
+def strip_frontmatter(content: str) -> str:
+    """Strip YAML frontmatter from agent file"""
+    if content.startswith('---'):
+        # Find the closing --- on its own line
+        lines = content.splitlines()
+        for i, line in enumerate(lines[1:], 1):
+            if line.strip() == '---':
+                return '\n'.join(lines[i+1:]).strip()
+    return content
+
+def get_display_name(session_id: str | None, tag: str | None = None) -> str:
+    """Get display name for instance using session_id"""
+    # ~90 recognizable 3-letter words
+    words = [
+        'ace', 'air', 'ant', 'arm', 'art', 'axe', 'bad', 'bag', 'bar', 'bat',
+        'bed', 'bee', 'big', 'box', 'boy', 'bug', 'bus', 'cab', 'can', 'cap',
+        'car', 'cat', 'cop', 'cow', 'cry', 'cup', 'cut', 'day', 'dog', 'dry',
+        'ear', 'egg', 'eye', 'fan', 'pig', 'fly', 'fox', 'fun', 'gem', 'gun',
+        'hat', 'hit', 'hot', 'ice', 'ink', 'jet', 'key', 'law', 'map', 'mix',
+        'man', 'bob', 'noo', 'yes', 'poo', 'sue', 'tom', 'the', 'and', 'but',
+        'age', 'aim', 'bro', 'bid', 'shi', 'buy', 'den', 'dig', 'dot', 'dye',
+        'end', 'era', 'eve', 'few', 'fix', 'gap', 'gas', 'god', 'gym', 'nob',
+        'hip', 'hub', 'hug', 'ivy', 'jab', 'jam', 'jay', 'jog', 'joy', 'lab',
+        'lag', 'lap', 'leg', 'lid', 'lie', 'log', 'lot', 'mat', 'mop', 'mud',
+        'net', 'new', 'nod', 'now', 'oak', 'odd', 'off', 'oil', 'old', 'one',
+        'lol', 'owe', 'own', 'pad', 'pan', 'pat', 'pay', 'pea', 'pen', 'pet',
+        'pie', 'pig', 'pin', 'pit', 'pot', 'pub', 'nah', 'rag', 'ran', 'rap',
+        'rat', 'raw', 'red', 'rib', 'rid', 'rip', 'rod', 'row', 'rub', 'rug',
+        'run', 'sad', 'sap', 'sat', 'saw', 'say', 'sea', 'set', 'wii', 'she',
+        'shy', 'sin', 'sip', 'sir', 'sit', 'six', 'ski', 'sky', 'sly', 'son',
+        'boo', 'soy', 'spa', 'spy', 'rat', 'sun', 'tab', 'tag', 'tan', 'tap',
+        'pls', 'tax', 'tea', 'ten', 'tie', 'tip', 'toe', 'ton', 'top', 'toy',
+        'try', 'tub', 'two', 'use', 'van', 'bum', 'war', 'wax', 'way', 'web',
+        'wed', 'wet', 'who', 'why', 'wig', 'win', 'moo', 'won', 'wow', 'yak',
+        'too', 'gay', 'yet', 'you', 'zip', 'zoo', 'ann'
+    ]
+
+    # Use session_id directly instead of extracting UUID from transcript
+    if session_id:
+        # Hash to select word
+        hash_val = sum(ord(c) for c in session_id)
+        word = words[hash_val % len(words)]
+
+        # Add letter suffix that flows naturally with the word
+        last_char = word[-1]
+        if last_char in 'aeiou':
+            # After vowel: s/n/r/l creates plural/noun/verb patterns
+            suffix_options = 'snrl'
+        else:
+            # After consonant: add vowel or y for pronounceability
+            suffix_options = 'aeiouy'
+
+        letter_hash = sum(ord(c) for c in session_id[1:]) if len(session_id) > 1 else hash_val
+        suffix = suffix_options[letter_hash % len(suffix_options)]
+
+        base_name = f"{word}{suffix}"
+        collision_attempt = 0
+
+        # Collision detection: keep adding words until unique
+        while True:
+            instance_file = hcom_path(INSTANCES_DIR, f"{base_name}.json")
+            if not instance_file.exists():
+                break  # Name is unique
+
+            try:
+                with open(instance_file, 'r', encoding='utf-8') as f:
+                    data = json.load(f)
+
+                their_session_id = data.get('session_id', '')
+
+                # Same session_id = our file, reuse name
+                if their_session_id == session_id:
+                    break
+                # No session_id = stale/malformed file, use name
+                if not their_session_id:
+                    break
+
+                # Real collision - add another word
+                collision_hash = sum(ord(c) * (i + collision_attempt) for i, c in enumerate(session_id))
+                collision_word = words[collision_hash % len(words)]
+                base_name = f"{base_name}{collision_word}"
+                collision_attempt += 1
+
+            except (json.JSONDecodeError, KeyError, ValueError, OSError):
+                break  # Malformed file - assume stale, use base name
+    else:
+        # session_id is required - fail gracefully
+        raise ValueError("session_id required for instance naming")
+
+    if tag:
+        # Security: Sanitize tag to prevent log delimiter injection (defense-in-depth)
+        # Remove dangerous characters that could break message log parsing
+        sanitized_tag = ''.join(c for c in tag if c not in '|\n\r\t')
+        if not sanitized_tag:
+            raise ValueError("Tag contains only invalid characters")
+        if sanitized_tag != tag:
+            print(f"Warning: Tag contained invalid characters, sanitized to '{sanitized_tag}'", file=sys.stderr)
+        return f"{sanitized_tag}-{base_name}"
+    return base_name
+
+def resolve_instance_name(session_id: str, tag: str | None = None) -> tuple[str, dict | None]:
+    """
+    Resolve instance name for a session_id.
+    Searches existing instances first (reuses if found), generates new name if not found.
+    Returns: (instance_name, existing_data_or_none)
+    """
+    instances_dir = hcom_path(INSTANCES_DIR)
+
+    # Search for existing instance with this session_id
+    if session_id and instances_dir.exists():
+        for instance_file in instances_dir.glob("*.json"):
+            try:
+                data = load_instance_position(instance_file.stem)
+                if session_id == data.get('session_id'):
+                    return instance_file.stem, data
+            except (json.JSONDecodeError, OSError, KeyError):
+                continue
+
+    # Not found - generate new name
+    instance_name = get_display_name(session_id, tag)
+    return instance_name, None
+
+def _remove_hcom_hooks_from_settings(settings: dict[str, Any]) -> None:
+    """Remove hcom hooks from settings dict"""
+    if not isinstance(settings, dict) or 'hooks' not in settings:
+        return
+
+    if not isinstance(settings['hooks'], dict):
+        return
+
+    import copy
+
+    # Check all hook types including PostToolUse for backward compatibility cleanup
+    for event in LEGACY_HOOK_TYPES:
+        if event not in settings['hooks']:
+            continue
+        
+        # Process each matcher
+        updated_matchers = []
+        for matcher in settings['hooks'][event]:
+            # Fail fast on malformed settings - Claude won't run with broken settings anyway
+            if not isinstance(matcher, dict):
+                raise ValueError(f"Malformed settings: matcher in {event} is not a dict: {type(matcher).__name__}")
+
+            # Validate hooks field if present
+            if 'hooks' in matcher and not isinstance(matcher['hooks'], list):
+                raise ValueError(f"Malformed settings: hooks in {event} matcher is not a list: {type(matcher['hooks']).__name__}")
+
+            # Work with a copy to avoid any potential reference issues
+            matcher_copy = copy.deepcopy(matcher)
+            
+            # Filter out HCOM hooks from this matcher
+            non_hcom_hooks = [
+                hook for hook in matcher_copy.get('hooks', [])
+                if not any(
+                    pattern.search(hook.get('command', ''))
+                    for pattern in HCOM_HOOK_PATTERNS
+                )
+            ]
+            
+            # Only keep the matcher if it has non-HCOM hooks remaining
+            if non_hcom_hooks:
+                matcher_copy['hooks'] = non_hcom_hooks
+                updated_matchers.append(matcher_copy)
+            elif 'hooks' not in matcher or matcher['hooks'] == []:
+                # Preserve matchers that never had hooks (missing key or empty list only)
+                updated_matchers.append(matcher_copy)
+        
+        # Update or remove the event
+        if updated_matchers:
+            settings['hooks'][event] = updated_matchers
+        else:
+            del settings['hooks'][event]
+
+    # Remove HCOM from env section
+    if 'env' in settings and isinstance(settings['env'], dict):
+        settings['env'].pop('HCOM', None)
+        # Clean up empty env dict
+        if not settings['env']:
+            del settings['env']
+
+
+def build_env_string(env_vars: dict[str, Any], format_type: str = "bash") -> str:
+    """Build environment variable string for bash shells"""
+    if format_type == "bash_export":
+        # Properly escape values for bash
+        return ' '.join(f'export {k}={shlex.quote(str(v))};' for k, v in env_vars.items())
+    else:
+        return ' '.join(f'{k}={shlex.quote(str(v))}' for k, v in env_vars.items())
+
+
+def format_error(message: str, suggestion: str | None = None) -> str:
+    """Format error message consistently"""
+    base = f"Error: {message}"
+    if suggestion:
+        base += f". {suggestion}"
+    return base
+
+
+def has_claude_arg(claude_args: list[str] | None, arg_names: list[str], arg_prefixes: tuple[str, ...]) -> bool:
+    """Check if argument already exists in claude_args"""
+    return any(
+        arg in arg_names or arg.startswith(arg_prefixes)
+        for arg in (claude_args or [])
+    )
+
+def build_claude_command(agent_content: str | None = None, claude_args: list[str] | None = None, model: str | None = None, tools: str | None = None) -> tuple[str, str | None]:
+    """Build Claude command with proper argument handling
+    Returns tuple: (command_string, temp_file_path_or_none)
+    For agent content, writes to temp file and uses cat to read it.
+    Merges user's --system-prompt/--append-system-prompt with agent content.
+    Prompt comes from claude_args (positional tokens from HCOM_CLAUDE_ARGS).
+    """
+    cmd_parts = ['claude']
+    temp_file_path = None
+
+    # Extract user's system prompt flags
+    cleaned_args, user_append, user_system = extract_system_prompt_args(claude_args or [])
+
+    # Detect print mode
+    is_print_mode = bool(cleaned_args and any(arg in cleaned_args for arg in ['-p', '--print']))
+
+    # Add model if specified and not already in cleaned_args
+    if model:
+        if not has_claude_arg(cleaned_args, ['--model'], ('--model=',)):
+            cmd_parts.extend(['--model', model])
+
+    # Add allowed tools if specified and not already in cleaned_args
+    if tools:
+        if not has_claude_arg(cleaned_args, ['--allowedTools', '--allowed-tools'],
+                              ('--allowedTools=', '--allowed-tools=')):
+            cmd_parts.extend(['--allowedTools', tools])
+
+    # Add cleaned user args (system prompt flags removed, but positionals/prompt included)
+    if cleaned_args:
+        for arg in cleaned_args:
+            cmd_parts.append(shlex.quote(arg))
+
+    # Merge and apply system prompts
+    merged_content, flag = merge_system_prompts(user_append, user_system, agent_content, prefer_system_flag=is_print_mode)
+
+    if merged_content:
+        # Write merged content to temp file
+        scripts_dir = hcom_path(SCRIPTS_DIR)
+        temp_file = tempfile.NamedTemporaryFile(mode='w', encoding='utf-8', suffix='.txt', delete=False,
+                                              prefix='hcom_agent_', dir=str(scripts_dir))
+        temp_file.write(merged_content)
+        temp_file.close()
+        temp_file_path = temp_file.name
+
+        cmd_parts.append(flag)
+        cmd_parts.append(f'"$(cat {shlex.quote(temp_file_path)})"')
+
+    return ' '.join(cmd_parts), temp_file_path
+
+def create_bash_script(script_file: str, env: dict[str, Any], cwd: str | None, command_str: str, background: bool = False) -> None:
+    """Create a bash script for terminal launch
+    Scripts provide uniform execution across all platforms/terminals.
+    Cleanup behavior:
+    - Normal scripts: append 'rm -f' command for self-deletion
+    - Background scripts: persist until `hcom reset logs` cleanup (24 hours)
+    - Agent scripts: treated like background (contain 'hcom_agent_')
+    """
+    try:
+        script_path = Path(script_file)
+    except (OSError, IOError) as e:
+        raise Exception(f"Cannot create script directory: {e}")
+
+    with open(script_file, 'w', encoding='utf-8') as f:
+        f.write('#!/bin/bash\n')
+        f.write('echo "Starting Claude Code..."\n')
+
+        if platform.system() != 'Windows':
+            # 1. Discover paths once
+            claude_path = shutil.which('claude')
+            node_path = shutil.which('node')
+
+            # 2. Add to PATH for minimal environments
+            paths_to_add = []
+            for p in [node_path, claude_path]:
+                if p:
+                    dir_path = str(Path(p).resolve().parent)
+                    if dir_path not in paths_to_add:
+                        paths_to_add.append(dir_path)
+
+            if paths_to_add:
+                path_addition = ':'.join(paths_to_add)
+                f.write(f'export PATH="{path_addition}:$PATH"\n')
+            elif not claude_path:
+                # Warning for debugging
+                print("Warning: Could not locate 'claude' in PATH", file=sys.stderr)
+
+            # 3. Write environment variables
+            f.write(build_env_string(env, "bash_export") + '\n')
+
+            if cwd:
+                f.write(f'cd {shlex.quote(cwd)}\n')
+
+            # 4. Platform-specific command modifications
+            if claude_path:
+                if is_termux():
+                    # Termux: explicit node to bypass shebang issues
+                    final_node = node_path or '/data/data/com.termux/files/usr/bin/node'
+                    # Quote paths for safety
+                    command_str = command_str.replace(
+                        'claude ',
+                        f'{shlex.quote(final_node)} {shlex.quote(claude_path)} ',
+                        1
+                    )
+                else:
+                    # Mac/Linux: use full path (PATH now has node if needed)
+                    command_str = command_str.replace('claude ', f'{shlex.quote(claude_path)} ', 1)
+        else:
+            # Windows: no PATH modification needed
+            f.write(build_env_string(env, "bash_export") + '\n')
+            if cwd:
+                f.write(f'cd {shlex.quote(cwd)}\n')
+
+        f.write(f'{command_str}\n')
+
+        # Self-delete for normal mode (not background or agent)
+        if not background and 'hcom_agent_' not in command_str:
+            f.write(f'rm -f {shlex.quote(script_file)}\n')
+
+    # Make executable on Unix
+    if platform.system() != 'Windows':
+        os.chmod(script_file, 0o755)
+
+def find_bash_on_windows() -> str | None:
+    """Find Git Bash on Windows, avoiding WSL's bash launcher"""
+    # Build prioritized list of bash candidates
+    candidates = []
+    # 1. Common Git Bash locations (highest priority)
+    for base in [os.environ.get('PROGRAMFILES', r'C:\Program Files'),
+                 os.environ.get('PROGRAMFILES(X86)', r'C:\Program Files (x86)')]:
+        if base:
+            candidates.extend([
+                str(Path(base) / 'Git' / 'usr' / 'bin' / 'bash.exe'),  # usr/bin is more common
+                str(Path(base) / 'Git' / 'bin' / 'bash.exe')
+            ])
+    # 2. Portable Git installation
+    if local_appdata := os.environ.get('LOCALAPPDATA', ''):
+        git_portable = Path(local_appdata) / 'Programs' / 'Git'
+        candidates.extend([
+            str(git_portable / 'usr' / 'bin' / 'bash.exe'),
+            str(git_portable / 'bin' / 'bash.exe')
+        ])
+    # 3. PATH bash (if not WSL's launcher)
+    if (path_bash := shutil.which('bash')) and not path_bash.lower().endswith(r'system32\bash.exe'):
+        candidates.append(path_bash)
+    # 4. Hardcoded fallbacks (last resort)
+    candidates.extend([
+        r'C:\Program Files\Git\usr\bin\bash.exe',
+        r'C:\Program Files\Git\bin\bash.exe',
+        r'C:\Program Files (x86)\Git\usr\bin\bash.exe',
+        r'C:\Program Files (x86)\Git\bin\bash.exe'
+    ])
+    # Find first existing bash
+    for bash in candidates:
+        if bash and Path(bash).exists():
+            return bash
+
+    return None
+
+# New helper functions for platform-specific terminal launching
+def get_macos_terminal_argv() -> list[str]:
+    """Return macOS Terminal.app launch command as argv list."""
+    return ['osascript', '-e', 'tell app "Terminal" to do script "bash {script}"', '-e', 'tell app "Terminal" to activate']
+
+def get_windows_terminal_argv() -> list[str]:
+    """Return Windows terminal launcher as argv list."""
+    if not (bash_exe := find_bash_on_windows()):
+        raise Exception(format_error("Git Bash not found"))
+
+    if shutil.which('wt'):
+        return ['wt', bash_exe, '{script}']
+    return ['cmd', '/c', 'start', 'Claude Code', bash_exe, '{script}']
+
+def get_linux_terminal_argv() -> list[str] | None:
+    """Return first available Linux terminal as argv list."""
+    terminals = [
+        ('gnome-terminal', ['gnome-terminal', '--', 'bash', '{script}']),
+        ('konsole', ['konsole', '-e', 'bash', '{script}']),
+        ('xterm', ['xterm', '-e', 'bash', '{script}']),
+    ]
+    for term_name, argv_template in terminals:
+        if shutil.which(term_name):
+            return argv_template
+
+    # WSL fallback integrated here
+    if is_wsl() and shutil.which('cmd.exe'):
+        if shutil.which('wt.exe'):
+            return ['cmd.exe', '/c', 'start', 'wt.exe', 'bash', '{script}']
+        return ['cmd.exe', '/c', 'start', 'bash', '{script}']
+
+    return None
+
+def windows_hidden_popen(argv: list[str], *, env: dict[str, str] | None = None, cwd: str | None = None, stdout: Any = None) -> subprocess.Popen:
+    """Create hidden Windows process without console window."""
+    if IS_WINDOWS:
+        startupinfo = subprocess.STARTUPINFO()  # type: ignore[attr-defined]
+        startupinfo.dwFlags |= subprocess.STARTF_USESHOWWINDOW  # type: ignore[attr-defined]
+        startupinfo.wShowWindow = subprocess.SW_HIDE  # type: ignore[attr-defined]
+
+        return subprocess.Popen(
+            argv,
+            env=env,
+            cwd=cwd,
+            stdin=subprocess.DEVNULL,
+            stdout=stdout,
+            stderr=subprocess.STDOUT,
+            startupinfo=startupinfo,
+            creationflags=CREATE_NO_WINDOW
+        )
+    else:
+        raise RuntimeError("windows_hidden_popen called on non-Windows platform")
+
+# Platform dispatch map
+PLATFORM_TERMINAL_GETTERS = {
+    'Darwin': get_macos_terminal_argv,
+    'Windows': get_windows_terminal_argv,
+    'Linux': get_linux_terminal_argv,
+}
+
+def _parse_terminal_command(template: str, script_file: str) -> list[str]:
+    """Parse terminal command template safely to prevent shell injection.
+    Parses the template FIRST, then replaces {script} placeholder in the
+    parsed tokens. This avoids shell injection and handles paths with spaces.
+    Args:
+        template: Terminal command template with {script} placeholder
+        script_file: Path to script file to substitute
+    Returns:
+        list: Parsed command as argv array
+    Raises:
+        ValueError: If template is invalid or missing {script} placeholder
+    """
+    if '{script}' not in template:
+        raise ValueError(format_error("Custom terminal command must include {script} placeholder",
+                                    'Example: open -n -a kitty.app --args bash "{script}"'))
+
+    try:
+        parts = shlex.split(template)
+    except ValueError as e:
+        raise ValueError(format_error(f"Invalid terminal command syntax: {e}",
+                                    "Check for unmatched quotes or invalid shell syntax"))
+
+    # Replace {script} in parsed tokens
+    replaced = []
+    placeholder_found = False
+    for part in parts:
+        if '{script}' in part:
+            replaced.append(part.replace('{script}', script_file))
+            placeholder_found = True
+        else:
+            replaced.append(part)
+
+    if not placeholder_found:
+        raise ValueError(format_error("{script} placeholder not found after parsing",
+                                    "Ensure {script} is not inside environment variables"))
+
+    return replaced
+
+def launch_terminal(command: str, env: dict[str, str], cwd: str | None = None, background: bool = False) -> str | bool | None:
+    """Launch terminal with command using unified script-first approach
+
+    Environment precedence: config.env < shell environment
+    Internal hcom vars (HCOM_LAUNCHED, etc) don't conflict with user vars.
+
+    Args:
+        command: Command string from build_claude_command
+        env: Contains config.env defaults + hcom internal vars
+        cwd: Working directory
+        background: Launch as background process
+    """
+    # config.env defaults + internal vars, then shell env overrides
+    env_vars = env.copy()
+    env_vars.update(os.environ)
+    command_str = command
+
+    # 1) Always create a script
+    script_file = str(hcom_path(SCRIPTS_DIR,
+        f'hcom_{os.getpid()}_{random.randint(1000,9999)}.sh'))
+    create_bash_script(script_file, env, cwd, command_str, background)
+
+    # 2) Background mode
+    if background:
+        logs_dir = hcom_path(LOGS_DIR)
+        log_file = logs_dir / env['HCOM_BACKGROUND']
+
+        try:
+            with open(log_file, 'w', encoding='utf-8') as log_handle:
+                if IS_WINDOWS:
+                    # Windows: hidden bash execution with Python-piped logs
+                    bash_exe = find_bash_on_windows()
+                    if not bash_exe:
+                        raise Exception("Git Bash not found")
+
+                    process = windows_hidden_popen(
+                        [bash_exe, script_file],
+                        env=env_vars,
+                        cwd=cwd,
+                        stdout=log_handle
+                    )
+                else:
+                    # Unix(Mac/Linux/Termux): detached bash execution with Python-piped logs
+                    process = subprocess.Popen(
+                        ['bash', script_file],
+                        env=env_vars, cwd=cwd,
+                        stdin=subprocess.DEVNULL,
+                        stdout=log_handle, stderr=subprocess.STDOUT,
+                        start_new_session=True
+                    )
+
+        except OSError as e:
+            print(format_error(f"Failed to launch headless instance: {e}"), file=sys.stderr)
+            return None
+
+        # Health check
+        time.sleep(0.2)
+        if process.poll() is not None:
+            error_output = read_file_with_retry(log_file, lambda f: f.read()[:1000], default="")
+            print(format_error("Headless instance failed immediately"), file=sys.stderr)
+            if error_output:
+                print(f"  Output: {error_output}", file=sys.stderr)
+            return None
+
+        return str(log_file)
+
+    # 3) Terminal modes
+    terminal_mode = get_config().terminal
+
+    if terminal_mode == 'print':
+        # Print script path and contents
+        try:
+            with open(script_file, 'r', encoding='utf-8') as f:
+                script_content = f.read()
+            print(f"# Script: {script_file}")
+            print(script_content)
+            Path(script_file).unlink()  # Clean up immediately
+            return True
+        except Exception as e:
+            print(format_error(f"Failed to read script: {e}"), file=sys.stderr)
+            return False
+
+    if terminal_mode == 'here':
+        print("Launching Claude in current terminal...")
+        if IS_WINDOWS:
+            bash_exe = find_bash_on_windows()
+            if not bash_exe:
+                print(format_error("Git Bash not found"), file=sys.stderr)
+                return False
+            result = subprocess.run([bash_exe, script_file], env=env_vars, cwd=cwd)
+        else:
+            result = subprocess.run(['bash', script_file], env=env_vars, cwd=cwd)
+        return result.returncode == 0
+
+    # 4) New window or custom command mode
+    # If terminal is not 'here' or 'print', it's either 'new' (platform default) or a custom command
+    custom_cmd = None if terminal_mode == 'new' else terminal_mode
+
+    if not custom_cmd:  # Platform default 'new' mode
+        if is_termux():
+            # Keep Termux as special case
+            am_cmd = [
+                'am', 'startservice', '--user', '0',
+                '-n', 'com.termux/com.termux.app.RunCommandService',
+                '-a', 'com.termux.RUN_COMMAND',
+                '--es', 'com.termux.RUN_COMMAND_PATH', script_file,
+                '--ez', 'com.termux.RUN_COMMAND_BACKGROUND', 'false'
+            ]
+            try:
+                subprocess.run(am_cmd, check=False)
+                return True
+            except Exception as e:
+                print(format_error(f"Failed to launch Termux: {e}"), file=sys.stderr)
+                return False
+
+        # Unified platform handling via helpers
+        system = platform.system()
+        if not (terminal_getter := PLATFORM_TERMINAL_GETTERS.get(system)):
+            raise Exception(format_error(f"Unsupported platform: {system}"))
+
+        custom_cmd = terminal_getter()
+        if not custom_cmd:  # e.g., Linux with no terminals
+            raise Exception(format_error("No supported terminal emulator found",
+                                       "Install gnome-terminal, konsole, or xterm"))
+
+    # Type-based dispatch for execution
+    if isinstance(custom_cmd, list):
+        # Our argv commands - safe execution without shell
+        final_argv = [arg.replace('{script}', script_file) for arg in custom_cmd]
+        try:
+            if platform.system() == 'Windows':
+                # Windows needs non-blocking for parallel launches
+                subprocess.Popen(final_argv)
+                return True  # Popen is non-blocking, can't check success
+            else:
+                result = subprocess.run(final_argv)
+                if result.returncode != 0:
+                    return False
+                return True
+        except Exception as e:
+            print(format_error(f"Failed to launch terminal: {e}"), file=sys.stderr)
+            return False
+    else:
+        # User-provided string commands - parse safely without shell=True
+        try:
+            final_argv = _parse_terminal_command(custom_cmd, script_file)
+        except ValueError as e:
+            print(str(e), file=sys.stderr)
+            return False
+
+        try:
+            if platform.system() == 'Windows':
+                # Windows needs non-blocking for parallel launches
+                subprocess.Popen(final_argv)
+                return True  # Popen is non-blocking, can't check success
+            else:
+                result = subprocess.run(final_argv)
+                if result.returncode != 0:
+                    return False
+                return True
+        except Exception as e:
+            print(format_error(f"Failed to execute terminal command: {e}"), file=sys.stderr)
+            return False
+
+def setup_hooks() -> bool:
+    """Set up Claude hooks globally in ~/.claude/settings.json"""
+
+    # TODO: Remove after v0.6.0 - cleanup legacy per-directory hooks
+    try:
+        positions = load_all_positions()
+        if positions:
+            directories = set()
+            for instance_data in positions.values():
+                if isinstance(instance_data, dict) and 'directory' in instance_data:
+                    directories.add(instance_data['directory'])
+            for directory in directories:
+                if Path(directory).exists():
+                    cleanup_directory_hooks(Path(directory))
+    except Exception:
+        pass  # Don't fail hook setup if cleanup fails
+
+    # Install to global user settings
+    settings_path = get_claude_settings_path()
+    settings_path.parent.mkdir(exist_ok=True)
+    try:
+        settings = load_settings_json(settings_path, default={})
+        if settings is None:
+            settings = {}
+    except (json.JSONDecodeError, PermissionError) as e:
+        raise Exception(format_error(f"Cannot read settings: {e}"))
+    
+    if 'hooks' not in settings:
+        settings['hooks'] = {}
+
+    _remove_hcom_hooks_from_settings(settings)
+        
+    # Get the hook command template
+    hook_cmd_base, _ = get_hook_command()
+
+    # Build hook commands from HOOK_CONFIGS
+    hook_configs = [
+        (hook_type, matcher, f'{hook_cmd_base} {cmd_suffix}', timeout)
+        for hook_type, matcher, cmd_suffix, timeout in HOOK_CONFIGS
+    ]
+
+    for hook_type, matcher, command, timeout in hook_configs:
+        if hook_type not in settings['hooks']:
+            settings['hooks'][hook_type] = []
+
+        hook_dict = {
+            'hooks': [{
+                'type': 'command',
+                'command': command
+            }]
+        }
+
+        # Only include matcher field if non-empty (PreToolUse/PostToolUse use matchers)
+        if matcher:
+            hook_dict['matcher'] = matcher
+
+        if timeout is not None:
+            hook_dict['hooks'][0]['timeout'] = timeout
+
+        settings['hooks'][hook_type].append(hook_dict)
+
+    # Set $HCOM environment variable for all Claude instances (vanilla + hcom-launched)
+    if 'env' not in settings:
+        settings['env'] = {}
+
+    # Set HCOM based on current execution context (uvx, hcom binary, or full path)
+    settings['env']['HCOM'] = _build_hcom_env_value()
+
+    # Write settings atomically
+    try:
+        atomic_write(settings_path, json.dumps(settings, indent=2))
+    except Exception as e:
+        raise Exception(format_error(f"Cannot write settings: {e}"))
+    
+    # Quick verification
+    if not verify_hooks_installed(settings_path):
+        raise Exception(format_error("Hook installation failed"))
+    
+    return True
+
+def verify_hooks_installed(settings_path: Path) -> bool:
+    """Verify that HCOM hooks were installed correctly with correct commands"""
+    try:
+        settings = load_settings_json(settings_path, default=None)
+        if not settings:
+            return False
+
+        # Check all hook types have correct commands and timeout values (exactly one HCOM hook per type)
+        # Derive from HOOK_CONFIGS (single source of truth)
+        hooks = settings.get('hooks', {})
+        for hook_type, _, cmd_suffix, expected_timeout in HOOK_CONFIGS:
+            hook_matchers = hooks.get(hook_type, [])
+            if not hook_matchers:
+                return False
+
+            # Find and verify HCOM hook for this type
+            hcom_hook_count = 0
+            hcom_hook_timeout_valid = False
+            for matcher in hook_matchers:
+                for hook in matcher.get('hooks', []):
+                    command = hook.get('command', '')
+                    # Check for HCOM and the correct subcommand
+                    if ('${HCOM}' in command or 'hcom' in command.lower()) and cmd_suffix in command:
+                        hcom_hook_count += 1
+                        # Verify timeout matches expected value
+                        actual_timeout = hook.get('timeout')
+                        if actual_timeout == expected_timeout:
+                            hcom_hook_timeout_valid = True
+
+            # Must have exactly one HCOM hook with correct timeout (not zero, not duplicates)
+            if hcom_hook_count != 1 or not hcom_hook_timeout_valid:
+                return False
+
+        # Check that HCOM env var is set
+        env = settings.get('env', {})
+        if 'HCOM' not in env:
+            return False
+
+        return True
+    except Exception:
+        return False
+
+def is_interactive() -> bool:
+    """Check if running in interactive mode"""
+    return sys.stdin.isatty() and sys.stdout.isatty()
+
+def get_archive_timestamp() -> str:
+    """Get timestamp for archive files"""
+    return datetime.now().strftime("%Y-%m-%d_%H%M%S")
+
+class LogParseResult(NamedTuple):
+    """Result from parsing log messages"""
+    messages: list[dict[str, str]]
+    end_position: int
+
+def parse_log_messages(log_file: Path, start_pos: int = 0) -> LogParseResult:
+    """Parse messages from log file
+    Args:
+        log_file: Path to log file
+        start_pos: Position to start reading from
+    Returns:
+        LogParseResult containing messages and end position
+    """
+    if not log_file.exists():
+        return LogParseResult([], start_pos)
+
+    def read_messages(f):
+        f.seek(start_pos)
+        content = f.read()
+        end_pos = f.tell()  # Capture actual end position
+
+        if not content.strip():
+            return LogParseResult([], end_pos)
+
+        messages = []
+        message_entries = TIMESTAMP_SPLIT_PATTERN.split(content.strip())
+
+        for entry in message_entries:
+            if not entry or '|' not in entry:
+                continue
+
+            parts = entry.split('|', 2)
+            if len(parts) == 3:
+                timestamp, from_instance, message = parts
+                messages.append({
+                    'timestamp': timestamp,
+                    'from': from_instance.replace('\\|', '|'),
+                    'message': message.replace('\\|', '|')
+                })
+
+        return LogParseResult(messages, end_pos)
+
+    return read_file_with_retry(
+        log_file,
+        read_messages,
+        default=LogParseResult([], start_pos)
+    )
+
+def get_subagent_messages(parent_name: str, since_pos: int = 0, limit: int = 0) -> tuple[list[dict[str, str]], int, dict[str, int]]:
+    """Get messages from/to subagents of parent instance
+    Args:
+        parent_name: Parent instance name (e.g., 'alice')
+        since_pos: Position to read from (default 0 = all messages)
+        limit: Max messages to return (0 = all)
+    Returns:
+        Tuple of (messages from/to subagents, end_position, per_subagent_counts)
+        per_subagent_counts: {'alice_reviewer': 2, 'alice_debugger': 0, ...}
+    """
+    log_file = hcom_path(LOG_FILE)
+    if not log_file.exists():
+        return [], since_pos, {}
+
+    result = parse_log_messages(log_file, since_pos)
+    all_messages, new_pos = result.messages, result.end_position
+
+    # Get all subagent names for this parent
+    positions = load_all_positions()
+    subagent_names = [name for name in positions.keys()
+                      if name.startswith(f"{parent_name}_") and name != parent_name]
+
+    # Initialize per-subagent counts
+    per_subagent_counts = {name: 0 for name in subagent_names}
+
+    # Filter for messages from/to subagents and track per-subagent counts
+    subagent_messages = []
+    for msg in all_messages:
+        sender = msg['from']
+        # Messages FROM subagents
+        if sender.startswith(f"{parent_name}_") and sender != parent_name:
+            subagent_messages.append(msg)
+            # Track which subagents would receive this message
+            for subagent_name in subagent_names:
+                if subagent_name != sender and should_deliver_message(msg, subagent_name, subagent_names):
+                    per_subagent_counts[subagent_name] += 1
+        # Messages TO subagents via @mentions or broadcasts
+        elif subagent_names:
+            # Check which subagents should receive this message
+            matched = False
+            for subagent_name in subagent_names:
+                if should_deliver_message(msg, subagent_name, subagent_names):
+                    if not matched:
+                        subagent_messages.append(msg)
+                        matched = True
+                    per_subagent_counts[subagent_name] += 1
+
+    if limit > 0:
+        subagent_messages = subagent_messages[-limit:]
+
+    return subagent_messages, new_pos, per_subagent_counts
+
+def get_unread_messages(instance_name: str, update_position: bool = False) -> list[dict[str, str]]:
+    """Get unread messages for instance with @-mention filtering
+    Args:
+        instance_name: Name of instance to get messages for
+        update_position: If True, mark messages as read by updating position
+    """
+    log_file = hcom_path(LOG_FILE)
+
+    if not log_file.exists():
+        return []
+
+    positions = load_all_positions()
+
+    # Get last position for this instance
+    last_pos = 0
+    if instance_name in positions:
+        pos_data = positions.get(instance_name, {})
+        last_pos = pos_data.get('pos', 0) if isinstance(pos_data, dict) else pos_data
+
+    # Atomic read with position tracking
+    result = parse_log_messages(log_file, last_pos)
+    all_messages, new_pos = result.messages, result.end_position
+
+    # Filter messages:
+    # 1. Exclude own messages
+    # 2. Apply @-mention filtering
+    all_instance_names = list(positions.keys())
+    messages = []
+    for msg in all_messages:
+        if msg['from'] != instance_name:
+            if should_deliver_message(msg, instance_name, all_instance_names):
+                messages.append(msg)
+
+    # Only update position (ie mark as read) if explicitly requested (after successful delivery)
+    if update_position:
+        update_instance_position(instance_name, {'pos': new_pos})
+
+    return messages
+
+def get_instance_status(pos_data: dict[str, Any]) -> tuple[bool, str, str, str]:
+    """Get current status of instance. Returns (enabled, status, age_string, description).
+
+    age_string format: "16m" (clean format, no parens/suffix - consumers handle display)
+
+    Status is activity state (what instance is doing).
+    Enabled is participation flag (whether instance can send/receive HCOM).
+    These are orthogonal - can be disabled but still active.
+    """
+    enabled = pos_data.get('enabled', False)
+    status = pos_data.get('status', 'unknown')
+    status_time = pos_data.get('status_time', 0)
+    status_context = pos_data.get('status_context', '')
+
+    now = int(time.time())
+    age = now - status_time if status_time else 0
+
+    # Subagent-specific status detection
+    if pos_data.get('parent_session_id'):
+        # Subagent in done polling loop: status='active' but heartbeat still updating
+        # PreToolUse sets all subagents to 'active', but one in polling loop has fresh heartbeat
+        if status == 'active' and enabled:
+            heartbeat_age = now - pos_data.get('last_stop', 0)
+            if heartbeat_age < 1.5:  # Heartbeat active (1s poll interval + margin)
+                status = 'waiting'
+                age = heartbeat_age
+
+    # Heartbeat timeout check: instance was waiting but heartbeat died
+    # This detects terminated instances (closed window/crashed) that were idle
+    if status == 'waiting':
+        heartbeat_age = now - pos_data.get('last_stop', 0)
+        tcp_mode = pos_data.get('tcp_mode', False)
+        threshold = 40 if tcp_mode else 2
+        if heartbeat_age > threshold:
+            status_context = status  # Save what it was doing
+            status = 'stale'
+            age = heartbeat_age
+
+    # Activity timeout check: no status updates for extended period
+    # This detects terminated instances that were active/blocked/etc when closed
+    if status not in ['exited', 'stale']:
+        timeout = pos_data.get('wait_timeout', 1800)
+        min_threshold = max(timeout + 60, 600)  # Timeout + 1min buffer, minimum 10min
+        status_age = now - status_time if status_time else 0
+        if status_age > min_threshold:
+            status_context = status  # Save what it was doing
+            status = 'stale'
+            age = status_age
+
+    # Build description from status and context
+    description = get_status_description(status, status_context)
+
+    return (enabled, status, format_age(age), description)
+
+
+def get_status_description(status: str, context: str = '') -> str:
+    """Build human-readable status description"""
+    if status == 'active':
+        return f"{context} executing" if context else "active"
+    elif status == 'delivered':
+        return f"msg from {context}" if context else "message delivered"
+    elif status == 'waiting':
+        return "idle"
+    elif status == 'blocked':
+        return f"{context}" if context else "permission needed"
+    elif status == 'exited':
+        return f"exited: {context}" if context else "exited"
+    elif status == 'stale':
+        # Show what it was doing when it went stale
+        if context == 'waiting':
+            return "idle [stale]"
+        elif context == 'active':
+            return "active [stale]"
+        elif context == 'blocked':
+            return "blocked [stale]"
+        elif context == 'delivered':
+            return "delivered [stale]"
+        else:
+            return "stale"
+    else:
+        return "unknown"
+
+def should_show_in_watch(d: dict[str, Any]) -> bool:
+    """Show previously-enabled instances, hide vanilla never-enabled instances"""
+    # Hide instances that never participated
+    if not d.get('previously_enabled', False):
+        return False
+
+    return True
+
+def initialize_instance_in_position_file(instance_name: str, session_id: str | None = None, parent_session_id: str | None = None, enabled: bool | None = None) -> bool:
+    """Initialize instance file with required fields (idempotent). Returns True on success, False on failure."""
+    try:
+        data = load_instance_position(instance_name)
+        file_existed = bool(data)
+
+        # Determine default enabled state: True for hcom-launched, False for vanilla
+        is_hcom_launched = os.environ.get('HCOM_LAUNCHED') == '1'
+
+        # Determine starting position: skip history or read from beginning (or last max_msgs num)
+        initial_pos = 0
+        if SKIP_HISTORY:
+            log_file = hcom_path(LOG_FILE)
+            if log_file.exists():
+                initial_pos = log_file.stat().st_size
+
+        # Determine enabled state: explicit param > hcom-launched > False
+        if enabled is not None:
+            default_enabled = enabled
+        else:
+            default_enabled = is_hcom_launched
+
+        defaults = {
+            "pos": initial_pos,
+            "enabled": default_enabled,
+            "previously_enabled": default_enabled,
+            "directory": str(Path.cwd()),
+            "last_stop": 0,
+            "created_at": time.time(),
+            "session_id": session_id or "",
+            "transcript_path": "",
+            "notification_message": "",
+            "alias_announced": False,
+            "tag": None
+        }
+
+        # Add parent_session_id for subagents
+        if parent_session_id:
+            defaults["parent_session_id"] = parent_session_id
+
+        # Add missing fields (preserve existing)
+        for key, value in defaults.items():
+            data.setdefault(key, value)
+
+        return save_instance_position(instance_name, data)
+    except Exception:
+        return False
+
+def update_instance_position(instance_name: str, update_fields: dict[str, Any]) -> None:
+    """Update instance position atomically with file locking"""
+    instance_file = hcom_path(INSTANCES_DIR, f"{instance_name}.json")
+
+    try:
+        if instance_file.exists():
+            with open(instance_file, 'r+', encoding='utf-8') as f:
+                with locked(f):
+                    data = json.load(f)
+                    data.update(update_fields)
+                    f.seek(0)
+                    f.truncate()
+                    json.dump(data, f, indent=2)
+                    f.flush()
+                    os.fsync(f.fileno())
+        else:
+            # File doesn't exist - create it first
+            initialize_instance_in_position_file(instance_name)
+    except Exception as e:
+        log_hook_error(f'update_instance_position:{instance_name}', e)
+        pass  # Silent to user, logged for debugging
+
+def enable_instance(instance_name: str) -> None:
+    """Enable instance - enables Stop hook polling"""
+    update_instance_position(instance_name, {
+        'enabled': True,
+        'previously_enabled': True
+    })
+
+def disable_instance(instance_name: str) -> None:
+    """Disable instance - stops Stop hook polling"""
+    updates = {
+        'enabled': False
+    }
+    update_instance_position(instance_name, updates)
+
+    # Notify instance to wake and see enabled=false
+    notify_instance(instance_name)
+
+def set_status(instance_name: str, status: str, context: str = ''):
+    """Set instance status with timestamp"""
+    update_instance_position(instance_name, {
+        'status': status,
+        'status_time': int(time.time()),
+        'status_context': context
+    })
+
+# ==================== Command Functions ====================
+
+def cmd_help() -> int:
+    """Show help text"""
+    print(get_help_text())
+    return 0
+
+def cmd_launch(argv: list[str]) -> int:
+    """Launch Claude instances: hcom [N] [claude] [args]"""
+    try:
+        # Parse arguments: hcom [N] [claude] [args]
+        count = 1
+        forwarded = []
+
+        # Extract count if first arg is digit
+        if argv and argv[0].isdigit():
+            count = int(argv[0])
+            if count <= 0:
+                raise CLIError('Count must be positive.')
+            if count > 100:
+                raise CLIError('Too many instances requested (max 100).')
+            argv = argv[1:]
+
+        # Skip 'claude' keyword if present
+        if argv and argv[0] == 'claude':
+            argv = argv[1:]
+
+        # Forward all remaining args to claude CLI
+        forwarded = argv
+
+        # Check for --no-auto-watch flag (used by TUI to prevent opening another watch window)
+        no_auto_watch = '--no-auto-watch' in forwarded
+        if no_auto_watch:
+            forwarded = [arg for arg in forwarded if arg != '--no-auto-watch']
+
+        # Get tag from config
+        tag = get_config().tag
+        if tag and '|' in tag:
+            raise CLIError('Tag cannot contain "|" characters.')
+
+        # Get agents from config (comma-separated)
+        agent_env = get_config().agent
+        agents = [a.strip() for a in agent_env.split(',') if a.strip()] if agent_env else ['']
+
+        # Phase 1: Parse Claude args using new resolve_claude_args
+        spec = resolve_claude_args(
+            forwarded if forwarded else None,
+            get_config().claude_args
+        )
+
+        # Validate parsed args
+        if spec.has_errors():
+            raise CLIError('\n'.join(spec.errors))
+
+        # Check for conflicts (warnings only, not errors)
+        warnings = validate_conflicts(spec)
+        for warning in warnings:
+            print(f"{FG_YELLOW}Warning:{RESET} {warning}", file=sys.stderr)
+
+        # Add HCOM background mode enhancements
+        spec = add_background_defaults(spec)
+
+        # Extract values from spec
+        background = spec.is_background
+        # Use full tokens (prompts included) - respects user's HCOM_CLAUDE_ARGS config
+        claude_args = spec.rebuild_tokens(include_system=True)
+
+        terminal_mode = get_config().terminal
+
+        # Calculate total instances to launch
+        total_instances = count * len(agents)
+
+        # Fail fast for here mode with multiple instances
+        if terminal_mode == 'here' and total_instances > 1:
+            print(format_error(
+                f"'here' mode cannot launch {total_instances} instances (it's one terminal window)",
+                "Use 'hcom 1' for one generic instance"
+            ), file=sys.stderr)
+            return 1
+
+        log_file = hcom_path(LOG_FILE)
+        instances_dir = hcom_path(INSTANCES_DIR)
+
+        if not log_file.exists():
+            log_file.touch()
+
+        # Build environment variables for Claude instances
+        base_env = build_claude_env()
+
+        # Add tag-specific hints if provided
+        if tag:
+            base_env['HCOM_TAG'] = tag
+
+        launched = 0
+
+        # Launch count instances of each agent
+        for agent in agents:
+            for _ in range(count):
+                instance_type = agent
+                instance_env = base_env.copy()
+
+                # Mark all hcom-launched instances
+                instance_env['HCOM_LAUNCHED'] = '1'
+
+                # Mark background instances via environment with log filename
+                if background:
+                    # Generate unique log filename
+                    log_filename = f'background_{int(time.time())}_{random.randint(1000, 9999)}.log'
+                    instance_env['HCOM_BACKGROUND'] = log_filename
+
+                # Build claude command
+                if not instance_type:
+                    # No agent - no agent content
+                    claude_cmd, _ = build_claude_command(
+                        agent_content=None,
+                        claude_args=claude_args
+                    )
+                else:
+                    # Agent instance
+                    try:
+                        agent_content, agent_config = resolve_agent(instance_type)
+                        # Mark this as a subagent instance for SessionStart hook
+                        instance_env['HCOM_SUBAGENT_TYPE'] = instance_type
+                        # Prepend agent instance awareness to system prompt
+                        agent_prefix = f"You are an instance of {instance_type}. Do not start a subagent with {instance_type} unless explicitly asked.\n\n"
+                        agent_content = agent_prefix + agent_content
+                        # Use agent's model and tools if specified and not overridden in claude_args
+                        agent_model = agent_config.get('model')
+                        agent_tools = agent_config.get('tools')
+                        claude_cmd, _ = build_claude_command(
+                            agent_content=agent_content,
+                            claude_args=claude_args,
+                            model=agent_model,
+                            tools=agent_tools
+                        )
+                        # Agent temp files live under ~/.hcom/scripts/ for unified housekeeping cleanup
+                    except (FileNotFoundError, ValueError) as e:
+                        print(str(e), file=sys.stderr)
+                        continue
+
+                try:
+                    if background:
+                        log_file = launch_terminal(claude_cmd, instance_env, cwd=os.getcwd(), background=True)
+                        if log_file:
+                            print(f"Headless instance launched, log: {log_file}")
+                            launched += 1
+                    else:
+                        if launch_terminal(claude_cmd, instance_env, cwd=os.getcwd()):
+                            launched += 1
+                except Exception as e:
+                    print(format_error(f"Failed to launch terminal: {e}"), file=sys.stderr)
+
+        requested = total_instances
+        failed = requested - launched
+
+        if launched == 0:
+            print(format_error(f"No instances launched (0/{requested})"), file=sys.stderr)
+            return 1
+
+        # Show results
+        if failed > 0:
+            print(f"Launched {launched}/{requested} Claude instance{'s' if requested != 1 else ''} ({failed} failed)")
+        else:
+            print(f"Launched {launched} Claude instance{'s' if launched != 1 else ''}")
+
+        # Auto-launch watch dashboard if in new window mode (new or custom) and all instances launched successfully
+        terminal_mode = get_config().terminal
+
+        # Only auto-watch if ALL instances launched successfully and launches windows (not 'here' or 'print') and not disabled by TUI
+        if terminal_mode not in ('here', 'print') and failed == 0 and is_interactive() and not no_auto_watch:
+            # Show tips first if needed
+            if tag:
+                print(f"\n  • Send to {tag} team: hcom send '@{tag} message'")
+
+            # Clear transition message
+            print("\nOpening hcom UI...")
+            time.sleep(2)  # Brief pause so user sees the message
+
+            # Launch interactive watch dashboard in current terminal
+            return cmd_watch([])  # Empty argv = interactive mode
+        else:
+            tips = [
+                "Run 'hcom' to view/send in conversation dashboard",
+            ]
+            if tag:
+                tips.append(f"Send to {tag} team: hcom send '@{tag} message'")
+
+            if tips:
+                print("\n" + "\n".join(f"  • {tip}" for tip in tips) + "\n")
+
+            return 0
+        
+    except ValueError as e:
+        print(str(e), file=sys.stderr)
+        return 1
+    except Exception as e:
+        print(str(e), file=sys.stderr)
+        return 1
+
+def cmd_watch(argv: list[str]) -> int:
+    """View conversation dashboard: hcom watch [--logs|--status|--wait [SEC]]"""
+    # Extract launch flag for external terminals (used by claude code bootstrap)
+    cleaned_args: list[str] = []
+    for arg in argv:
+        if arg == '--launch':
+            watch_cmd = f"{build_hcom_command()} watch"
+            result = launch_terminal(watch_cmd, build_claude_env(), cwd=os.getcwd())
+            return 0 if result else 1
+        else:
+            cleaned_args.append(arg)
+    argv = cleaned_args
+
+    # Parse arguments
+    show_logs = '--logs' in argv
+    show_status = '--status' in argv
+    wait_timeout = None
+
+    # Check for --wait flag
+    if '--wait' in argv:
+        idx = argv.index('--wait')
+        if idx + 1 < len(argv):
+            try:
+                wait_timeout = int(argv[idx + 1])
+                if wait_timeout < 0:
+                    raise CLIError('--wait expects a non-negative number of seconds.')
+            except ValueError:
+                wait_timeout = 60  # Default for non-numeric values
+        else:
+            wait_timeout = 60  # Default timeout
+        show_logs = True  # --wait implies logs mode
+
+    log_file = hcom_path(LOG_FILE)
+    instances_dir = hcom_path(INSTANCES_DIR)
+
+    if not log_file.exists() and not instances_dir.exists():
+        print(format_error("No conversation log found", "Run 'hcom' first"), file=sys.stderr)
+        return 1
+
+    # Non-interactive mode (no TTY or flags specified)
+    if not is_interactive() or show_logs or show_status:
+        if show_logs:
+            # Atomic position capture BEFORE parsing (prevents race condition)
+            if log_file.exists():
+                last_pos = log_file.stat().st_size  # Capture position first
+                messages = parse_log_messages(log_file).messages
+            else:
+                last_pos = 0
+                messages = []
+            
+            # If --wait, show recent messages (max of: last 3 messages OR all messages in last 5 seconds)
+            if wait_timeout is not None:
+                cutoff = datetime.now() - timedelta(seconds=5)
+                recent_by_time = [m for m in messages if datetime.fromisoformat(m['timestamp']) > cutoff]
+                last_three = messages[-3:] if len(messages) >= 3 else messages
+                # Show whichever is larger: recent by time or last 3
+                recent_messages = recent_by_time if len(recent_by_time) > len(last_three) else last_three
+                # Status to stderr, data to stdout
+                if recent_messages:
+                    print(f'---Showing recent messages---', file=sys.stderr)
+                    for msg in recent_messages:
+                        print(f"[{msg['timestamp']}] {msg['from']}: {msg['message']}")
+                    print(f'---Waiting for new message... (exits on receipt or after {wait_timeout} seconds)---', file=sys.stderr)
+                else:
+                    print(f'---Waiting for new message... (exits on receipt or after {wait_timeout} seconds)---', file=sys.stderr)
+                
+                
+                # Wait loop
+                start_time = time.time()
+                while time.time() - start_time < wait_timeout:
+                    if log_file.exists():
+                        current_size = log_file.stat().st_size
+                        new_messages = []
+                        if current_size > last_pos:
+                            # Capture new position BEFORE parsing (atomic)
+                            new_messages = parse_log_messages(log_file, last_pos).messages
+                        if new_messages:
+                            for msg in new_messages:
+                                print(f"[{msg['timestamp']}] {msg['from']}: {msg['message']}")
+                            last_pos = current_size  # Update only after successful processing
+                            return 0  # Success - got new messages
+                        if current_size > last_pos:
+                            last_pos = current_size  # Update even if no messages (file grew but no complete messages yet)
+                    time.sleep(0.1)
+                
+                # Timeout message to stderr
+                print(f'[TIMED OUT] No new messages received after {wait_timeout} seconds.', file=sys.stderr)
+                return 1  # Timeout - no new messages
+            
+            # Regular --logs (no --wait): print all messages to stdout
+            else:
+                if messages:
+                    for msg in messages:
+                        print(f"[{msg['timestamp']}] {msg['from']}: {msg['message']}")
+                else:
+                    print("No messages yet", file=sys.stderr)
+            
+                    
+        elif show_status:
+            # Build JSON output
+            positions = load_all_positions()
+
+            instances = {}
+            status_counts = {}
+
+            for name, data in positions.items():
+                if not should_show_in_watch(data):
+                    continue
+                enabled, status, age, description = get_instance_status(data)
+                instances[name] = {
+                    "enabled": enabled,
+                    "status": status,
+                    "age": age if age else "",
+                    "description": description,
+                    "directory": data.get("directory", "unknown"),
+                    "session_id": data.get("session_id", ""),
+                    "background": bool(data.get("background"))
+                }
+                status_counts[status] = status_counts.get(status, 0) + 1
+
+            # Get recent messages
+            messages = []
+            if log_file.exists():
+                all_messages = parse_log_messages(log_file).messages
+                messages = all_messages[-5:] if all_messages else []
+
+            # Output JSON
+            output = {
+                "instances": instances,
+                "recent_messages": messages,
+                "status_summary": status_counts,
+                "log_file": str(log_file),
+                "timestamp": datetime.now().isoformat()
+            }
+
+            print(json.dumps(output, indent=2))
+        else:
+            print("No TTY - Automation usage:", file=sys.stderr)
+            print("  hcom watch --logs      Show message history", file=sys.stderr)
+            print("  hcom watch --status    Show instance status", file=sys.stderr)
+            print("  hcom watch --wait      Wait for new messages", file=sys.stderr)
+            print("  hcom watch --launch    Launch interactive dashboard in new terminal", file=sys.stderr)
+            print("  Full information: hcom --help")
+            
+        return 0
+
+    # Interactive mode - launch TUI
+    try:
+        from .ui import HcomTUI
+        tui = HcomTUI(hcom_path())
+        return tui.run()
+    except ImportError as e:
+        print(format_error("TUI not available", "Install with pip install hcom"), file=sys.stderr)
+        return 1
+
+def clear() -> int:
+    """Clear and archive conversation"""
+    log_file = hcom_path(LOG_FILE)
+    instances_dir = hcom_path(INSTANCES_DIR)
+
+    # cleanup: temp files, old scripts, old outbox files
+    cutoff_time = time.time() - (24 * 60 * 60)  # 24 hours ago
+    if instances_dir.exists():
+        sum(1 for f in instances_dir.glob('*.tmp') if f.unlink(missing_ok=True) is None)
+
+    scripts_dir = hcom_path(SCRIPTS_DIR)
+    if scripts_dir.exists():
+        sum(1 for f in scripts_dir.glob('*') if f.is_file() and f.stat().st_mtime < cutoff_time and f.unlink(missing_ok=True) is None)
+
+    # Check if hcom files exist
+    if not log_file.exists() and not instances_dir.exists():
+        print("No HCOM conversation to clear")
+        return 0
+
+    # Archive existing files if they have content
+    timestamp = get_archive_timestamp()
+    archived = False
+
+    try:
+        has_log = log_file.exists() and log_file.stat().st_size > 0
+        has_instances = instances_dir.exists() and any(instances_dir.glob('*.json'))
+        
+        if has_log or has_instances:
+            # Create session archive folder with timestamp
+            session_archive = hcom_path(ARCHIVE_DIR, f'session-{timestamp}')
+            session_archive.mkdir(parents=True, exist_ok=True)
+            
+            # Archive log file
+            if has_log:
+                archive_log = session_archive / LOG_FILE
+                log_file.rename(archive_log)
+                archived = True
+            elif log_file.exists():
+                log_file.unlink()
+            
+            # Archive instances
+            if has_instances:
+                archive_instances = session_archive / INSTANCES_DIR
+                archive_instances.mkdir(parents=True, exist_ok=True)
+
+                # Move json files only
+                for f in instances_dir.glob('*.json'):
+                    f.rename(archive_instances / f.name)
+
+                archived = True
+        else:
+            # Clean up empty files/dirs
+            if log_file.exists():
+                log_file.unlink()
+            if instances_dir.exists():
+                shutil.rmtree(instances_dir)
+        
+        log_file.touch()
+        clear_all_positions()
+
+        if archived:
+            print(f"Archived to archive/session-{timestamp}/")
+        print("Started fresh HCOM conversation log")
+        return 0
+        
+    except Exception as e:
+        print(format_error(f"Failed to archive: {e}"), file=sys.stderr)
+        return 1
+
+def remove_global_hooks() -> bool:
+    """Remove HCOM hooks from ~/.claude/settings.json
+    Returns True on success, False on failure."""
+    settings_path = get_claude_settings_path()
+
+    if not settings_path.exists():
+        return True  # No settings = no hooks to remove
+
+    try:
+        settings = load_settings_json(settings_path, default=None)
+        if not settings:
+            return False
+
+        _remove_hcom_hooks_from_settings(settings)
+        atomic_write(settings_path, json.dumps(settings, indent=2))
+        return True
+    except Exception:
+        return False
+
+def cleanup_directory_hooks(directory: Path | str) -> tuple[int, str]:
+    """Remove hcom hooks from a specific directory
+    Returns tuple: (exit_code, message)
+        exit_code: 0 for success, 1 for error
+        message: what happened
+    """
+    settings_path = Path(directory) / '.claude' / 'settings.local.json'
+    
+    if not settings_path.exists():
+        return 0, "No Claude settings found"
+    
+    try:
+        # Load existing settings
+        settings = load_settings_json(settings_path, default=None)
+        if not settings:
+            return 1, "Cannot read Claude settings"
+        
+        hooks_found = False
+
+        # Include PostToolUse for backward compatibility cleanup
+        original_hook_count = sum(len(settings.get('hooks', {}).get(event, []))
+                                  for event in LEGACY_HOOK_TYPES)
+
+        _remove_hcom_hooks_from_settings(settings)
+
+        # Check if any were removed
+        new_hook_count = sum(len(settings.get('hooks', {}).get(event, []))
+                             for event in LEGACY_HOOK_TYPES)
+        if new_hook_count < original_hook_count:
+            hooks_found = True
+                
+        if not hooks_found:
+            return 0, "No hcom hooks found"
+        
+        # Write back or delete settings
+        if not settings or (len(settings) == 0):
+            # Delete empty settings file
+            settings_path.unlink()
+            return 0, "Removed hcom hooks (settings file deleted)"
+        else:
+            # Write updated settings
+            atomic_write(settings_path, json.dumps(settings, indent=2))
+            return 0, "Removed hcom hooks from settings"
+        
+    except json.JSONDecodeError:
+        return 1, format_error("Corrupted settings.local.json file")
+    except Exception as e:
+        return 1, format_error(f"Cannot modify settings.local.json: {e}")
+
+
+def cmd_stop(argv: list[str]) -> int:
+    """Stop instances: hcom stop [alias|all] [--_hcom_session ID]"""
+    # Parse arguments
+    target = None
+    session_id = None
+
+    # Extract --_hcom_session if present
+    if '--_hcom_session' in argv:
+        idx = argv.index('--_hcom_session')
+        if idx + 1 < len(argv):
+            session_id = argv[idx + 1]
+            argv = argv[:idx] + argv[idx + 2:]
+
+    # Remove flags to get target
+    args_without_flags = [a for a in argv if not a.startswith('--')]
+    if args_without_flags:
+        target = args_without_flags[0]
+
+    # Handle 'all' target
+    if target == 'all':
+        positions = load_all_positions()
+
+        if not positions:
+            print("No instances found")
+            return 0
+
+        stopped_count = 0
+        bg_logs = []
+        stopped_names = []
+        for instance_name, instance_data in positions.items():
+            if instance_data.get('enabled', False):
+                # Set external stop flag (stop all is always external)
+                update_instance_position(instance_name, {'external_stop_pending': True})
+                disable_instance(instance_name)
+                stopped_names.append(instance_name)
+                stopped_count += 1
+
+                # Track background logs
+                if instance_data.get('background'):
+                    log_file = instance_data.get('background_log_file', '')
+                    if log_file:
+                        bg_logs.append((instance_name, log_file))
+
+        if stopped_count == 0:
+            print("No instances to stop")
+        else:
+            print(f"Stopped {stopped_count} instance(s): {', '.join(stopped_names)}")
+
+            # Show background logs if any
+            if bg_logs:
+                print()
+                print("Headless instance logs:")
+                for name, log_file in bg_logs:
+                    print(f"  {name}: {log_file}")
+
+        return 0
+
+    # Stop specific instance or self
+    # Get instance name from injected session or target
+    if session_id and not target:
+        instance_name, _ = resolve_instance_name(session_id, get_config().tag)
+    else:
+        instance_name = target
+
+    position = load_instance_position(instance_name) if instance_name else None
+
+    if not instance_name:
+        if os.environ.get('CLAUDECODE') == '1':
+            print("Error: Cannot determine instance", file=sys.stderr)
+            print("Usage: Prompt Claude to run 'hcom stop' (or directly use: hcom stop <alias> or hcom stop all)", file=sys.stderr)
+        else:
+            print("Error: Alias required", file=sys.stderr)
+            print("Usage: hcom stop <alias>", file=sys.stderr)
+            print("   Or: hcom stop all", file=sys.stderr)
+            print("   Or: prompt claude to run 'hcom stop' on itself", file=sys.stderr)
+            positions = load_all_positions()
+            visible = [alias for alias, data in positions.items() if should_show_in_watch(data)]
+            if visible:
+                print(f"Active aliases: {', '.join(sorted(visible))}", file=sys.stderr)
+        return 1
+
+    if not position:
+        print(f"No instance found for {instance_name}")
+        return 1
+
+    # Skip already stopped instances
+    if not position.get('enabled', False):
+        print(f"HCOM already stopped for {instance_name}")
+        return 0
+
+    # Check if this is a subagent - disable all siblings
+    if is_subagent_instance(position):
+        parent_session_id = position.get('parent_session_id')
+        positions = load_all_positions()
+        disabled_count = 0
+        disabled_names = []
+
+        for name, data in positions.items():
+            if data.get('parent_session_id') == parent_session_id and data.get('enabled', False):
+                # Set external stop flag (subagents can't self-stop, so any stop is external)
+                update_instance_position(name, {'external_stop_pending': True})
+                disable_instance(name)
+                disabled_count += 1
+                disabled_names.append(name)
+
+        if disabled_count > 0:
+            print(f"Stopped {disabled_count} subagent(s): {', '.join(disabled_names)}")
+            print("Note: All subagents of the same parent must be disabled together.")
+        else:
+            print(f"No enabled subagents found for {instance_name}")
+    else:
+        # Regular parent instance
+        # External stop = CLI user specified target, Self stop = no target (uses session_id)
+        is_external_stop = target is not None
+
+        if is_external_stop:
+            # Set flag to notify instance via PostToolUse
+            update_instance_position(instance_name, {'external_stop_pending': True})
+
+        disable_instance(instance_name)
+        print(f"Stopped HCOM for {instance_name}. Will no longer receive chat messages automatically.")
+
+    # Show background log location if applicable
+    if position.get('background'):
+        log_file = position.get('background_log_file', '')
+        if log_file:
+            print(f"\nHeadless instance log: {log_file}")
+            print(f"Monitor: tail -f {log_file}")
+
+    return 0
+
+def cmd_start(argv: list[str]) -> int:
+    """Enable HCOM participation: hcom start [alias] [--_hcom_session ID]"""
+    # Parse arguments
+    target = None
+    session_id = None
+
+    # Extract --_hcom_session if present
+    if '--_hcom_session' in argv:
+        idx = argv.index('--_hcom_session')
+        if idx + 1 < len(argv):
+            session_id = argv[idx + 1]
+            argv = argv[:idx] + argv[idx + 2:]
+
+    # Extract --_hcom_sender if present (for subagents)
+    sender_override = None
+    if '--_hcom_sender' in argv:
+        idx = argv.index('--_hcom_sender')
+        if idx + 1 < len(argv):
+            sender_override = argv[idx + 1]
+            argv = argv[:idx] + argv[idx + 2:]
+
+    # Remove flags to get target
+    args_without_flags = [a for a in argv if not a.startswith('--')]
+    if args_without_flags:
+        target = args_without_flags[0]
+
+    # SUBAGENT PATH: --_hcom_sender provided
+    if sender_override:
+        instance_data = load_instance_position(sender_override)
+        if not instance_data or instance_data.get('status') == 'exited':
+            print(f"Error: Instance '{sender_override}' not found or has exited", file=sys.stderr)
+            return 1
+
+        enable_instance(sender_override)
+        set_status(sender_override, 'active', 'start')
+        print(f"HCOM started for {sender_override}")
+        print(f"Send: hcom send 'message' --_hcom_sender {sender_override}")
+        print(f"When finished working always run: hcom send done --_hcom_sender {sender_override}")
+        return 0
+
+    # Get instance name from injected session or target
+    if session_id and not target:
+        instance_name, existing_data = resolve_instance_name(session_id, get_config().tag)
+
+        # Check for Task ambiguity (parent frozen, subagent calling)
+        if existing_data and in_subagent_context(existing_data):
+            # Get list of subagents from THIS Task execution that are disabled
+            active_list = existing_data.get('current_subagents', [])
+            positions = load_all_positions()
+            subagent_ids = [
+                sid for sid in active_list
+                if sid in positions and not positions[sid].get('enabled', False)
+            ]
+
+            print("Task tool running - you must provide an alias")
+            print("Use: hcom start --_hcom_sender {alias}")
+            if subagent_ids:
+                print(f"Choose from one of these valid aliases: {', '.join(subagent_ids)}")
+            return 1
+
+        # Create instance if it doesn't exist (opt-in for vanilla instances)
+        if not existing_data:
+            initialize_instance_in_position_file(instance_name, session_id)
+            # Enable instance (clears all stop flags)
+            enable_instance(instance_name)
+            print(f"\nStarted HCOM for {instance_name}")
+        else:
+            # Skip already started instances
+            if existing_data.get('enabled', False):
+                print(f"HCOM already started for {instance_name}")
+                return 0
+
+            # Check if background instance has exited permanently
+            if existing_data.get('session_ended') and existing_data.get('background'):
+                session = existing_data.get('session_id', '')
+                print(f"Cannot start {instance_name}: headless instance has exited permanently")
+                print(f"Headless instances terminate when stopped and cannot be restarted")
+                if session:
+                    print(f"Resume conversation with same alias: hcom 1 claude -p --resume {session}")
+                return 1
+
+            # Re-enabling existing instance
+            enable_instance(instance_name)
+            print(f"Started HCOM for {instance_name}")
+
+        return 0
+
+    # CLI path: start specific instance
+    positions = load_all_positions()
+
+    # Handle missing target from external CLI
+    if not target:
+        if os.environ.get('CLAUDECODE') == '1':
+            print("Error: Cannot determine instance", file=sys.stderr)
+            print("Usage: Prompt Claude to run 'hcom start' (or: hcom start <alias>)", file=sys.stderr)
+        else:
+            print("Error: Alias required", file=sys.stderr)
+            print("Usage: hcom start <alias> (or: prompt claude to run 'hcom start')", file=sys.stderr)
+            print("To launch new instances: hcom <count>", file=sys.stderr)
+        return 1
+
+    # Start specific instance
+    instance_name = target
+    position = positions.get(instance_name)
+
+    if not position:
+        print(f"Instance not found: {instance_name}")
+        return 1
+
+    # Skip already started instances
+    if position.get('enabled', False):
+        print(f"HCOM already started for {instance_name}")
+        return 0
+
+    # Check if background instance has exited permanently
+    if position.get('session_ended') and position.get('background'):
+        session = position.get('session_id', '')
+        print(f"Cannot start {instance_name}: headless instance has exited permanently")
+        print(f"Headless instances terminate when stopped and cannot be restarted")
+        if session:
+            print(f"Resume conversation with same alias: hcom 1 claude -p --resume {session}")
+        return 1
+
+    # Enable instance (clears all stop flags)
+    enable_instance(instance_name)
+
+    print(f"Started HCOM for {instance_name}")
+    return 0
+
+def cmd_reset(argv: list[str]) -> int:
+    """Reset HCOM components: logs, hooks, config
+    Usage:
+        hcom reset              # Everything (stop all + logs + hooks + config)
+        hcom reset logs         # Archive conversation only
+        hcom reset hooks        # Remove hooks only
+        hcom reset config       # Clear config (backup to config.env.TIMESTAMP)
+        hcom reset logs hooks   # Combine targets
+    """
+    # No args = everything
+    do_everything = not argv
+    targets = argv if argv else ['logs', 'hooks', 'config']
+
+    # Validate targets
+    valid = {'logs', 'hooks', 'config'}
+    invalid = [t for t in targets if t not in valid]
+    if invalid:
+        print(f"Invalid target(s): {', '.join(invalid)}", file=sys.stderr)
+        print("Valid targets: logs, hooks, config", file=sys.stderr)
+        return 1
+
+    exit_codes = []
+
+    # Stop all instances if doing everything
+    if do_everything:
+        exit_codes.append(cmd_stop(['all']))
+
+    # Execute based on targets
+    if 'logs' in targets:
+        exit_codes.append(clear())
+
+    if 'hooks' in targets:
+        exit_codes.append(cleanup('--all'))
+        if remove_global_hooks():
+            print("Removed hooks")
+        else:
+            print("Warning: Could not remove hooks. Check your claude settings.json file it might be invalid", file=sys.stderr)
+            exit_codes.append(1)
+
+    if 'config' in targets:
+        config_path = hcom_path(CONFIG_FILE)
+        if config_path.exists():
+            # Backup with timestamp
+            timestamp = datetime.now().strftime('%Y%m%d_%H%M%S')
+            backup_path = hcom_path(f'config.env.{timestamp}')
+            shutil.copy2(config_path, backup_path)
+            config_path.unlink()
+            print(f"Config backed up to config.env.{timestamp} and cleared")
+            exit_codes.append(0)
+        else:
+            print("No config file to clear")
+            exit_codes.append(0)
+
+    return max(exit_codes) if exit_codes else 0
+
+def cleanup(*args: str) -> int:
+    """Remove hcom hooks from current directory or all directories"""
+    if args and args[0] == '--all':
+        directories = set()
+
+        # Get all directories from current instances
+        try:
+            positions = load_all_positions()
+            if positions:
+                for instance_data in positions.values():
+                    if isinstance(instance_data, dict) and 'directory' in instance_data:
+                        directories.add(instance_data['directory'])
+        except Exception as e:
+            print(f"Warning: Could not read current instances: {e}")
+
+        # Also check archived instances for directories (until 0.5.0)
+        try:
+            archive_dir = hcom_path(ARCHIVE_DIR)
+            if archive_dir.exists():
+                for session_dir in archive_dir.iterdir():
+                    if session_dir.is_dir() and session_dir.name.startswith('session-'):
+                        instances_dir = session_dir / 'instances'
+                        if instances_dir.exists():
+                            for instance_file in instances_dir.glob('*.json'):
+                                try:
+                                    data = json.loads(instance_file.read_text())
+                                    if 'directory' in data:
+                                        directories.add(data['directory'])
+                                except Exception:
+                                    pass
+        except Exception as e:
+            print(f"Warning: Could not read archived instances: {e}")
+        
+        if not directories:
+            print("No directories found in current HCOM tracking")
+            return 0
+        
+        print(f"Found {len(directories)} unique directories to check")
+        cleaned = 0
+        failed = 0
+        already_clean = 0
+        
+        for directory in sorted(directories):
+            # Check if directory exists
+            if not Path(directory).exists():
+                print(f"\nSkipping {directory} (directory no longer exists)")
+                continue
+                
+            print(f"\nChecking {directory}...")
+
+            exit_code, message = cleanup_directory_hooks(Path(directory))
+            if exit_code == 0:
+                if "No hcom hooks found" in message or "No Claude settings found" in message:
+                    already_clean += 1
+                    print(f"  {message}")
+                else:
+                    cleaned += 1
+                    print(f"  {message}")
+            else:
+                failed += 1
+                print(f"  {message}")
+        
+        print(f"\nSummary:")
+        print(f"  Cleaned: {cleaned} directories")
+        print(f"  Already clean: {already_clean} directories")
+        if failed > 0:
+            print(f"  Failed: {failed} directories")
+            return 1
+        return 0
+            
+    else:
+        exit_code, message = cleanup_directory_hooks(Path.cwd())
+        print(message)
+        return exit_code
+
+def ensure_hooks_current() -> bool:
+    """Ensure hooks match current execution context - called on EVERY command.
+    Auto-updates hooks if execution context changes (e.g., pip → uvx).
+    Always returns True (warns but never blocks - Claude Code is fault-tolerant)."""
+
+    # Verify hooks exist and match current execution context
+    global_settings = get_claude_settings_path()
+
+    # Check if hooks are valid (exist + env var matches current context)
+    hooks_exist = verify_hooks_installed(global_settings)
+    env_var_matches = False
+
+    if hooks_exist:
+        try:
+            settings = load_settings_json(global_settings, default={})
+            if settings is None:
+                settings = {}
+            current_hcom = _build_hcom_env_value()
+            installed_hcom = settings.get('env', {}).get('HCOM')
+            env_var_matches = (installed_hcom == current_hcom)
+        except Exception:
+            # Failed to read settings - try to fix by updating
+            env_var_matches = False
+
+    # Install/update hooks if missing or env var wrong
+    if not hooks_exist or not env_var_matches:
+        try:
+            setup_hooks()
+            if os.environ.get('CLAUDECODE') == '1':
+                print("HCOM hooks updated. Please restart Claude Code to apply changes.", file=sys.stderr)
+                print("=" * 60, file=sys.stderr)
+        except Exception as e:
+            # Failed to verify/update hooks, but they might still work
+            # Claude Code is fault-tolerant with malformed JSON
+            print(f"⚠️  Could not verify/update hooks: {e}", file=sys.stderr)
+            print("If HCOM doesn't work, check ~/.claude/settings.json", file=sys.stderr)
+
+    return True
+
+def cmd_send(argv: list[str], force_cli: bool = False, quiet: bool = False) -> int:
+    """Send message to hcom: hcom send "message" [--_hcom_session ID] [--_hcom_sender NAME]"""
+    # Parse message and session_id
+    message = None
+    session_id = None
+    subagent_id = None
+
+    # Extract --_hcom_sender if present (for subagents)
+    if '--_hcom_sender' in argv:
+        idx = argv.index('--_hcom_sender')
+        if idx + 1 < len(argv):
+            subagent_id = argv[idx + 1]
+            argv = argv[:idx] + argv[idx + 2:]  # Remove flag and value
+
+    # Extract --_hcom_session if present (injected by PreToolUse hook)
+    if '--_hcom_session' in argv:
+        idx = argv.index('--_hcom_session')
+        if idx + 1 < len(argv):
+            session_id = argv[idx + 1]
+            argv = argv[:idx] + argv[idx + 2:]  # Remove flag and value
+
+    # First non-flag argument is the message
+    if argv:
+        message = argv[0]
+
+    # Check message is provided
+    if not message:
+        print(format_error("No message provided"), file=sys.stderr)
+        return 1
+
+    # Check if hcom files exist
+    log_file = hcom_path(LOG_FILE)
+    instances_dir = hcom_path(INSTANCES_DIR)
+
+    if not log_file.exists() and not instances_dir.exists():
+        print(format_error("No conversation found", "Run 'hcom <count>' first"), file=sys.stderr)
+        return 1
+
+    # Validate message
+    error = validate_message(message)
+    if error:
+        print(error, file=sys.stderr)
+        return 1
+
+    # Check for unmatched mentions (minimal warning)
+    mentions = MENTION_PATTERN.findall(message)
+    if mentions:
+        try:
+            positions = load_all_positions()
+            all_instances = list(positions.keys())
+            sender_name = SENDER
+            all_names = all_instances + [sender_name]
+            unmatched = [m for m in mentions
+                        if not any(name.lower().startswith(m.lower()) for name in all_names)]
+            if unmatched:
+                print(f"Note: @{', @'.join(unmatched)} don't match any instances - broadcasting to all", file=sys.stderr)
+        except Exception:
+            pass  # Don't fail on warning
+
+    # Determine sender from injected flags or CLI
+    if session_id and not force_cli:
+        # Instance context - use sender override if provided (subagent), otherwise resolve from session_id
+        if subagent_id: #subagent id is same as subagent name
+            sender_name = subagent_id
+            instance_data = load_instance_position(sender_name)
+            if not instance_data:
+                print(format_error(f"Subagent instance file missing for {subagent_id}"), file=sys.stderr)
+                return 1
+        else:
+            # Normal instance - resolve name from session_id
+            try:
+                sender_name, instance_data = resolve_instance_name(session_id, get_config().tag)
+            except (ValueError, Exception) as e:
+                print(format_error(f"Invalid session_id: {e}"), file=sys.stderr)
+                return 1
+
+            # Initialize instance if doesn't exist (first use)
+            if not instance_data:
+                initialize_instance_in_position_file(sender_name, session_id)
+                instance_data = load_instance_position(sender_name)
+
+            # Guard: If parent is in subagent context, subagent MUST provide --_hcom_sender
+            if in_subagent_context(instance_data):
+                # Get list of active subagents for helpful error message
+                positions = load_all_positions()
+                subagent_ids = [name for name in positions if name.startswith(f"{sender_name}_")]
+
+                suggestion = f"Use: hcom send 'message' --_hcom_sender {{alias}}"
+                if subagent_ids:
+                    suggestion += f". Valid aliases: {', '.join(subagent_ids)}"
+
+                print(format_error("Task tool subagent must provide sender identity", suggestion), file=sys.stderr)
+                return 1
+
+        # Check enabled state
+        if not instance_data.get('enabled', False):
+            previously_enabled = instance_data.get('previously_enabled', False)
+            if previously_enabled:
+                # Was enabled, now disabled - don't suggest re-enabling
+                print(format_error("HCOM stopped. Cannot send messages."), file=sys.stderr)
+            else:
+                # Never enabled - helpful message
+                print(format_error("HCOM not started for this instance. To send a message first run: 'hcom start' then use hcom send"), file=sys.stderr)
+            return 1
+
+        # Handle "done" command - subagent finished work, wait for messages (control command)
+        if message == "done" and subagent_id:
+            # Control command - don't write to log, PostToolUse will handle polling
+            print(f"Subagent {subagent_id}: Waiting for messages...", file=sys.stderr)
+            return 0
+
+        # Set status to active for subagents (identity confirmed, enabled verified)
+        if subagent_id:
+            set_status(subagent_id, 'active', 'send')
+
+        # Send message
+        if not send_message(sender_name, message):
+            print(format_error("Failed to send message"), file=sys.stderr)
+            return 1
+
+        # Show unread messages, grouped by subagent vs main
+        messages = get_unread_messages(sender_name, update_position=True)
+        if messages:
+            # Separate subagent messages from main messages
+            subagent_msgs = []
+            main_msgs = []
+            for msg in messages:
+                sender = msg['from']
+                # Check if sender is a subagent of this instance
+                if sender.startswith(f"{sender_name}_") and sender != sender_name:
+                    subagent_msgs.append(msg)
+                else:
+                    main_msgs.append(msg)
+
+            output_parts = ["Message sent"]
+            max_msgs = MAX_MESSAGES_PER_DELIVERY
+
+            if main_msgs:
+                formatted = format_hook_messages(main_msgs[:max_msgs], sender_name)
+                output_parts.append(f"\n{formatted}")
+
+            if subagent_msgs:
+                formatted = format_hook_messages(subagent_msgs[:max_msgs], sender_name)
+                output_parts.append(f"\n[Subagent messages]\n{formatted}")
+
+            print("".join(output_parts), file=sys.stderr)
+        else:
+            print("Message sent", file=sys.stderr)
+
+        return 0
+    else:
+        # CLI context - no session_id or force_cli=True
+
+        # Warn if inside Claude Code but no session_id (hooks not working(?))
+        if os.environ.get('CLAUDECODE') == '1' and not session_id and not force_cli:
+            if subagent_id:
+                # Subagent command not auto-approved
+                print(format_error(
+                    "Cannot determine alias - hcom command not auto-approved",
+                    "Run hcom commands directly with correct syntax: 'hcom send 'message' --_hcom_sender {alias}'"
+                ), file=sys.stderr)
+                return 1
+            else:
+                print(f"⚠️  Cannot determine alias - message sent as '{SENDER}'", file=sys.stderr)
+
+
+        sender_name = SENDER
+
+        if not send_message(sender_name, message):
+            print(format_error("Failed to send message"), file=sys.stderr)
+            return 1
+
+        if not quiet:
+            print(f"✓ Sent from {sender_name}", file=sys.stderr)
+
+        return 0
+
+def send_cli(message: str, quiet: bool = False) -> int:
+    """Force CLI sender (skip outbox, use config sender name)"""
+    return cmd_send([message], force_cli=True, quiet=quiet)
+
+# ==================== Hook Helpers ====================
+
+def format_subagent_hcom_instructions(alias: str) -> str:
+    """Format HCOM usage instructions for subagents"""
+    hcom_cmd = build_hcom_command()
+
+    # Add command override notice if not using short form
+    command_notice = ""
+    if hcom_cmd != "hcom":
+        command_notice = f"""IMPORTANT:
+The hcom command in this environment is: {hcom_cmd}
+Replace all mentions of "hcom" below with this command.
+
+"""
+
+    return f"""{command_notice}[HCOM INFORMATION]
+Your HCOM alias is: {alias}
+HCOM is a communication tool.
+
+- To Send a message, run:
+  hcom send 'your message' --_hcom_sender {alias}
+  (use '@alias' for direct messages)
+
+- Messages are delivered automatically via bash feedback or hooks.
+  There is no way to proactively check or poll for messages yourself.
+
+- When finished working, always run:
+  hcom send done --_hcom_sender {alias}
+
+- {{"decision": "block"}} text is normal operation
+- Prioritize @{SENDER} over other participants
+- First action: Announce your online presence to @{SENDER}
+------"""
+
+def format_hook_messages(messages: list[dict[str, str]], instance_name: str) -> str:
+    """Format messages for hook feedback"""
+    if len(messages) == 1:
+        msg = messages[0]
+        reason = f"[new message] {msg['from']} → {instance_name}: {msg['message']}"
+    else:
+        parts = [f"{msg['from']} → {instance_name}: {msg['message']}" for msg in messages]
+        reason = f"[{len(messages)} new messages] | {' | '.join(parts)}"
+
+    # Only append hints to messages
+    hints = get_config().hints
+    if hints:
+        reason = f"{reason} | [{hints}]"
+
+    return reason
+
+# ==================== Hook Handlers ====================
+
+def init_hook_context(hook_data: dict[str, Any], hook_type: str | None = None) -> tuple[str, dict[str, Any], bool]:
+    """
+    Initialize instance context. Flow:
+    1. Resolve instance name (search by session_id, generate if not found)
+    2. Create instance file if fresh start in UserPromptSubmit
+    3. Build updates dict
+    4. Return (instance_name, updates, is_matched_resume)
+    """
+    session_id = hook_data.get('session_id', '')
+    transcript_path = hook_data.get('transcript_path', '')
+    tag = get_config().tag
+
+    # Resolve instance name - existing_data is None for fresh starts
+    instance_name, existing_data = resolve_instance_name(session_id, tag)
+
+    # Save migrated data if we have it
+    if existing_data:
+        save_instance_position(instance_name, existing_data)
+
+    # Create instance file if fresh start in UserPromptSubmit
+    if existing_data is None and hook_type == 'userpromptsubmit':
+        initialize_instance_in_position_file(instance_name, session_id)
+
+    # Build updates dict
+    updates: dict[str, Any] = {
+        'directory': str(Path.cwd()),
+        'tag': tag,
+    }
+
+    if session_id:
+        updates['session_id'] = session_id
+
+    if transcript_path:
+        updates['transcript_path'] = transcript_path
+
+    bg_env = os.environ.get('HCOM_BACKGROUND')
+    if bg_env:
+        updates['background'] = True
+        updates['background_log_file'] = str(hcom_path(LOGS_DIR, bg_env))
+
+    # Simple boolean: matched resume if existing_data found
+    is_matched_resume = (existing_data is not None)
+
+    return instance_name, updates, is_matched_resume
+
+def is_safe_hcom_command(command: str) -> bool:
+    """Security check: verify ALL parts of chained command are hcom commands"""
+    # Strip quoted strings, split on &&/||/;, check all parts match hcom pattern
+    cmd = re.sub(r'''(["'])(?:(?=(\\?))\2.)*?\1''', '', command)
+    parts = [p.strip() for p in re.split(r'\s*(?:&&|\|\||;)\s*', cmd) if p.strip()]
+    return bool(parts) and all(HCOM_COMMAND_PATTERN.match(p) for p in parts)
+
+def handle_pretooluse(hook_data: dict[str, Any], instance_name: str) -> None:
+    """Handle PreToolUse hook - check force_closed, inject session_id, inject subagent identity"""
+    instance_data = load_instance_position(instance_name)
+    tool_name = hook_data.get('tool_name', '')
+    session_id = hook_data.get('session_id', '')
+
+    # Record status for tool execution tracking (only if enabled)
+    # Skip if --_hcom_sender present (subagent status set in cmd_send/cmd_start instead)
+    if instance_data.get('enabled', False):
+        has_sender_flag = False
+        if tool_name == 'Bash':
+            command = hook_data.get('tool_input', {}).get('command', '')
+            has_sender_flag = '--_hcom_sender' in command
+
+        if not has_sender_flag:
+            if in_subagent_context(instance_data):
+                # In Task - update only subagents in current_subagents list
+                current_list = instance_data.get('current_subagents', [])
+                for subagent_id in current_list:
+                    set_status(subagent_id, 'active', tool_name)
+            else:
+                # Not in Task - update parent only
+                set_status(instance_name, 'active', tool_name)
+
+
+    # Inject session_id into hcom commands via updatedInput
+    if tool_name == 'Bash' and session_id:
+        command = hook_data.get('tool_input', {}).get('command', '')
+
+        # Match hcom commands for session_id injection and auto-approval
+        matches = list(re.finditer(HCOM_COMMAND_PATTERN, command))
+        if matches and is_safe_hcom_command(command):
+            # Security validated: ALL command parts are hcom commands
+            # Inject all if chained (&&, ||, ;, |), otherwise first only (avoids quoted text in messages)
+            inject_all = len(matches) > 1 and any(op in command[matches[0].end():matches[1].start()] for op in ['&&', '||', ';', '|'])
+            modified_command = HCOM_COMMAND_PATTERN.sub(rf'\g<0> --_hcom_session {session_id}', command, count=0 if inject_all else 1)
+
+            output = {
+                "hookSpecificOutput": {
+                    "hookEventName": "PreToolUse",
+                    "permissionDecision": "allow",
+                    "updatedInput": {
+                        "command": modified_command
+                    }
+                }
+            }
+            print(json.dumps(output, ensure_ascii=False))
+            sys.exit(0)
+
+    # Subagent identity injection for Task tool (only if HCOM enabled)
+    if tool_name == 'Task':
+        tool_input = hook_data.get('tool_input', {})
+        subagent_type = tool_input.get('subagent_type', 'unknown')
+
+        # Check for resume parameter and look up existing HCOM ID
+        resume_agent_id = tool_input.get('resume')
+        existing_hcom_id = None
+
+        if resume_agent_id:
+            # Look up existing HCOM ID for this agentId (reverse lookup)
+            mappings = instance_data.get('subagent_mappings', {}) if instance_data else {}
+            for hcom_id, agent_id in mappings.items():
+                if agent_id == resume_agent_id:
+                    existing_hcom_id = hcom_id
+                    break
+
+        # Generate or reuse subagent ID
+        parent_enabled = instance_data.get('enabled', False)
+
+        if existing_hcom_id:
+            # Resuming: reuse existing HCOM ID
+            subagent_id = existing_hcom_id
+            subagent_file = hcom_path(INSTANCES_DIR, f"{subagent_id}.json")
+
+            # Reinitialize instance file (may have been cleaned up)
+            if not subagent_file.exists():
+                initialize_instance_in_position_file(subagent_id, parent_session_id=session_id, enabled=parent_enabled)
+            else:
+                # File exists: inherit parent's enabled state (overwrite disabled from cleanup)
+                update_instance_position(subagent_id, {'enabled': parent_enabled})
+        else:
+            # New subagent: generate unique ID with atomic collision detection (parallel-safe)
+            count = 1
+
+            for _ in range(1000):
+                subagent_id = f"{instance_name}_{subagent_type}_{count}"
+
+                subagent_file = hcom_path(INSTANCES_DIR, f"{subagent_id}.json")
+
+                # Atomic test-and-create using O_EXCL (cross-platform)
+                try:
+                    subagent_file.touch(exist_ok=False)  # Fails if file exists
+                    break
+                except FileExistsError:
+                    count += 1
+                    continue
+
+            # Initialize the reserved file (inherit parent's enabled state)
+            initialize_instance_in_position_file(subagent_id, parent_session_id=session_id, enabled=parent_enabled)
+
+        # Add subagent to parent's current list
+        current_subagents = instance_data.get('current_subagents', [])
+        if subagent_id not in current_subagents:
+            current_subagents.append(subagent_id)
+        update_instance_position(instance_name, {'current_subagents': current_subagents})
+
+        # Detect HCOM intent in prompt
+        hcom_detected = 'hcom' in tool_input.get('prompt', '').lower()
+
+        original_prompt = tool_input.get('prompt', '')
+
+        # Conditional prompt injection based on parent state and detection
+        if parent_enabled:
+            # Full bootstrap (parent enabled)
+            modified_prompt = f"""{format_subagent_hcom_instructions(subagent_id)}
+
+{original_prompt}"""
+        elif hcom_detected:
+            # Minimal opt-in (parent disabled + 'hcom' detected)
+            hcom_cmd = build_hcom_command()
+            modified_prompt = f"""[To use hcom run this command: '{hcom_cmd} start --_hcom_sender {subagent_id}']
+
+{original_prompt}"""
+        else:
+            # Silent opt-in (parent disabled + no 'hcom')
+            modified_prompt = original_prompt
+
+        # Preserve all original tool_input fields, only modify prompt
+        updated_input = tool_input.copy()
+        updated_input['prompt'] = modified_prompt
+
+        # Inject modified prompt and allow Task to proceed
+        output = {"hookSpecificOutput": {"hookEventName": "PreToolUse", "permissionDecision": "allow", "updatedInput": updated_input}}
+        print(json.dumps(output, ensure_ascii=False))
+        sys.exit(0)
+
+
+def handle_stop(hook_data: dict[str, Any], instance_name: str, updates: dict[str, Any], instance_data: dict[str, Any] | None) -> None:
+    """Handle Stop hook - poll for messages and deliver"""
+
+    try:
+        updates['last_stop'] = time.time()
+        timeout = get_config().timeout
+        updates['wait_timeout'] = timeout
+        set_status(instance_name, 'waiting')
+
+        # Disable orphaned subagents (backup cleanup if UserPromptSubmit missed them)
+        if instance_data:
+            positions = load_all_positions()
+            for name, pos_data in positions.items():
+                if name.startswith(f"{instance_name}_"):
+                    disable_instance(name)
+                    # Only set exited if not already exited
+                    current_status = pos_data.get('status', 'unknown')
+                    if current_status != 'exited':
+                        set_status(name, 'exited', 'orphaned')
+            # Clear active subagents list if set
+            if in_subagent_context(instance_data):
+                updates['current_subagents'] = []
+
+        # Setup TCP notify listener (best effort)
+        import socket, select
+        notify_server = None
+        try:
+            notify_server = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+            notify_server.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+            notify_server.bind(('127.0.0.1', 0))
+            notify_server.listen(128)
+            notify_server.setblocking(False)
+            notify_port = notify_server.getsockname()[1]
+            updates['notify_port'] = notify_port
+            updates['tcp_mode'] = True  # Declare TCP mode active
+        except Exception as e:
+            log_hook_error('stop:notify_setup', e)
+            # notify_server stays None - will fall back to polling
+            updates['tcp_mode'] = False  # Declare fallback mode
+
+        # Adaptive timeout: 30s with TCP, 0.1s without
+        poll_timeout = 30.0 if notify_server else STOP_HOOK_POLL_INTERVAL
+
+        try:
+            update_instance_position(instance_name, updates)
+        except Exception as e:
+            log_hook_error(f'stop:update_instance_position({instance_name})', e)
+
+        start_time = time.time()
+
+        try:
+            first_poll = True
+            last_heartbeat = start_time
+            # Actual polling loop - this IS the holding pattern
+            while time.time() - start_time < timeout:
+                if first_poll:
+                    first_poll = False
+
+                # Reload instance data each poll iteration
+                instance_data = load_instance_position(instance_name)
+
+                # Check flag file FIRST (highest priority coordination signal)
+                flag_file = get_user_input_flag_file(instance_name)
+                if flag_file.exists():
+                    try:
+                        flag_file.unlink()
+                    except (FileNotFoundError, PermissionError):
+                        # Already deleted or locked, continue anyway
+                        pass
+                    sys.exit(0)
+
+                # Check if session ended (SessionEnd hook fired) - exit without changing status
+                if instance_data.get('session_ended'):
+                    sys.exit(0)  # Don't overwrite session_ended status (already set by SessionEnd)
+
+                # Check if user input is pending (timestamp fallback) - exit cleanly if recent input
+                last_user_input = instance_data.get('last_user_input', 0)
+                if time.time() - last_user_input < 0.2:
+                    sys.exit(0)  # Don't overwrite status - let current status remain
+
+                # Check if disabled - mark exited and stop delivering messages (already stopped delivering messages by being disabled at this point...)
+                if not instance_data.get('enabled', False):
+                    set_status(instance_name, 'exited')
+                    sys.exit(0)
+
+                # Check for new messages and deliver
+                if messages := get_unread_messages(instance_name, update_position=True):
+                    messages_to_show = messages[:MAX_MESSAGES_PER_DELIVERY]
+                    reason = format_hook_messages(messages_to_show, instance_name)
+                    set_status(instance_name, 'delivered', messages_to_show[0]['from'])
+
+                    output = {"decision": "block", "reason": reason}
+                    print(json.dumps(output, ensure_ascii=False), file=sys.stderr)
+                    sys.exit(2)
+
+                # Wait for notification or timeout
+                if notify_server:
+                    try:
+                        readable, _, _ = select.select([notify_server], [], [], poll_timeout)
+                        # Update heartbeat after select (timeout or wake) to prove loop is alive
+                        try:
+                            update_instance_position(instance_name, {'last_stop': time.time()})
+                        except Exception:
+                            pass
+                        if readable:
+                            # Drain all pending notifications
+                            while True:
+                                try:
+                                    conn, _ = notify_server.accept()
+                                    conn.close()
+                                except BlockingIOError:
+                                    break
+                    except (OSError, ValueError, InterruptedError) as e:
+                        # Socket became invalid or interrupted - switch to polling
+                        log_hook_error(f'stop:select_failed({instance_name})', e)
+                        try:
+                            notify_server.close()
+                        except:
+                            pass
+                        notify_server = None
+                        poll_timeout = STOP_HOOK_POLL_INTERVAL  # Fallback to fast polling
+                        # Declare fallback mode (self-reporting state)
+                        try:
+                            update_instance_position(instance_name, {'tcp_mode': False, 'notify_port': None})
+                        except Exception:
+                            pass
+                else:
+                    # Fallback mode - still need heartbeat for staleness detection
+                    now = time.time()
+                    if now - last_heartbeat >= 0.5:
+                        try:
+                            update_instance_position(instance_name, {'last_stop': now})
+                            last_heartbeat = now
+                        except Exception as e:
+                            log_hook_error(f'stop:heartbeat_update({instance_name})', e)
+                    time.sleep(poll_timeout)
+
+        except Exception as loop_e:
+            # Log polling loop errors but continue to cleanup
+            log_hook_error(f'stop:polling_loop({instance_name})', loop_e)
+        finally:
+            # Cleanup for ALL exit paths (sys.exit, exception, or normal completion)
+            if notify_server:
+                try:
+                    notify_server.close()
+                    update_instance_position(instance_name, {
+                        'notify_port': None,
+                        'tcp_mode': False
+                    })
+                except Exception:
+                    pass  # Suppress cleanup errors
+
+        # If we reach here, timeout occurred (all other paths exited in loop)
+        set_status(instance_name, 'exited')
+        sys.exit(0)
+
+    except Exception as e:
+        # Log error and exit gracefully
+        log_hook_error('handle_stop', e)
+        sys.exit(0)  # Preserve previous status on exception
+
+
+def handle_subagent_stop(hook_data: dict[str, Any], parent_name: str, updates: dict[str, Any], instance_data: dict[str, Any] | None) -> None:
+    """SubagentStop: Guard hook - directs subagents to use 'done' command.
+    Group timeout: if any subagent disabled or idle too long, disable ALL.
+    parent_name is because subagents share the same session_id as parents
+    (so instance_data in this case is the same for parents and children).
+    Parents will never run this hook. Normal instances will never hit this hook.
+    This hook is only for subagents. Only subagent will ever hit this hook.
+    The name will resolve to parents name. This is normal and does not mean that
+    the parent is running this hook. Only subagents run this hook.
+    """
+
+    # Check subagent states
+    positions = load_all_positions()
+    has_enabled = False
+    has_disabled = False
+    any_subagent_exists = False
+
+    for name, data in positions.items():
+        if name.startswith(f"{parent_name}_") and name != parent_name:
+            any_subagent_exists = True
+            if data.get('enabled', False):
+                has_enabled = True
+            else:
+                has_disabled = True
+
+    # Exit silently if no subagents
+    if not any_subagent_exists:
+        sys.exit(0)
+
+    # If any subagent disabled (timed out in PostToolUse), disable all and exit
+    if has_disabled:
+        for name in positions:
+            if name.startswith(f"{parent_name}_") and name != parent_name:
+                update_instance_position(name, {'enabled': False})
+                set_status(name, 'exited', 'timeout')
+        sys.exit(0)
+
+    # Exit silently if all disabled
+    if not has_enabled:
+        sys.exit(0)
+
+    # Check timeout - if any subagent idle too long, disable all and exit
+    timeout = get_config().subagent_timeout
+    now = time.time()
+
+    for name, data in positions.items():
+        if name.startswith(f"{parent_name}_") and name != parent_name:
+            if data.get('enabled', False):
+                last_stop = data.get('last_stop', 0)
+                if last_stop > 0 and (now - last_stop) > timeout:
+                    # Timeout exceeded - disable all subagents
+                    for name2 in positions:
+                        if name2.startswith(f"{parent_name}_") and name2 != parent_name:
+                            update_instance_position(name2, {'enabled': False})
+                            set_status(name2, 'exited', 'timeout')
+                    sys.exit(0)
+
+    # reminder to run 'done' command
+    reminder = (
+        "[HCOM]: You MUST run 'hcom send done --_hcom_sender <your_alias>' "
+        "This allows you to receive messages and prevents timeout. "
+        "Run this command NOW."
+    )
+
+    output = {"decision": "block", "reason": reminder}
+    print(json.dumps(output, ensure_ascii=False), file=sys.stderr)
+    sys.exit(2)
+
+
+def handle_notify(hook_data: dict[str, Any], instance_name: str, updates: dict[str, Any], instance_data: dict[str, Any] | None) -> None:
+    """Handle Notification hook - track permission requests"""
+    message = hook_data.get('message', '')
+
+    # Filter generic message only when instance is already idle (Stop hook running)
+    if message == "Claude is waiting for your input":
+        current_status = instance_data.get('status', '') if instance_data else ''
+        if current_status == 'waiting':
+            return  # Instance is idle, Stop hook will maintain waiting status
+
+    # Update status based on subagent context
+    if instance_data and in_subagent_context(instance_data):
+        # In subagent context - update only subagents in current_subagents list (don't update parent)
+        current_list = instance_data.get('current_subagents', [])
+        for subagent_id in current_list:
+            set_status(subagent_id, 'blocked', message)
+    else:
+        # Not in Task (parent context) - update parent only
+        updates['notification_message'] = message
+        update_instance_position(instance_name, updates)
+        set_status(instance_name, 'blocked', message)
+
+
+def get_user_input_flag_file(instance_name: str) -> Path:
+    """Get path to user input coordination flag file"""
+    return hcom_path(FLAGS_DIR, f'{instance_name}.user_input')
+
+def wait_for_stop_exit(instance_name: str, max_wait: float = 0.2) -> int:
+    """
+    Wait for Stop hook to exit using flag file coordination.
+    Returns wait time in ms.
+    Strategy:
+    1. Create flag file
+    2. Wait for Stop hook to delete it (proof it exited)
+    3. Fallback to timeout if Stop hook doesn't delete flag
+    """
+    start = time.time()
+    flag_file = get_user_input_flag_file(instance_name)
+
+    # Wait for flag file to be deleted by Stop hook
+    while flag_file.exists() and time.time() - start < max_wait:
+        time.sleep(0.01)
+
+    return int((time.time() - start) * 1000)
+
+def handle_userpromptsubmit(hook_data: dict[str, Any], instance_name: str, updates: dict[str, Any], is_matched_resume: bool, instance_data: dict[str, Any] | None) -> None:
+    """Handle UserPromptSubmit hook - track when user sends messages"""
+    is_enabled = instance_data.get('enabled', False) if instance_data else False
+    last_stop = instance_data.get('last_stop', 0) if instance_data else 0
+    alias_announced = instance_data.get('alias_announced', False) if instance_data else False
+    notify_port = instance_data.get('notify_port') if instance_data else None
+
+    # Session_ended prevents user receiving messages(?) so reset it.
+    if is_matched_resume and instance_data and instance_data.get('session_ended'):
+        update_instance_position(instance_name, {'session_ended': False})
+        instance_data['session_ended'] = False  # Resume path reactivates Stop hook polling
+
+    # Disable orphaned subagents (user cancelled/interrupted Task or resumed)
+    if instance_data:
+        positions = load_all_positions()
+        for name, pos_data in positions.items():
+            if name.startswith(f"{instance_name}_"):
+                disable_instance(name)
+                # Only set exited if not already exited
+                current_status = pos_data.get('status', 'unknown')
+                if current_status != 'exited':
+                    set_status(name, 'exited', 'orphaned')
+        # Clear current subagents list if set
+        if (instance_data.get('current_subagents')):
+            update_instance_position(instance_name, {'current_subagents': []})
+
+    # Coordinate with Stop hook only if enabled AND Stop hook is active
+    # Determine if stop hook is active - check tcp_mode or timestamp
+    tcp_mode = instance_data.get('tcp_mode', False) if instance_data else False
+    if tcp_mode:
+        # TCP mode - assume active (stop hook self-reports if it exits/fails)
+        stop_is_active = True
+    else:
+        # Fallback mode - check timestamp
+        stop_is_active = (time.time() - last_stop) < 1.0
+
+    if is_enabled and stop_is_active:
+        # Create flag file FIRST (must exist before Stop hook wakes)
+        flag_file = get_user_input_flag_file(instance_name)
+        try:
+            flag_file.touch()
+        except (OSError, PermissionError):
+            # Failed to create flag, fall back to timestamp-only coordination
+            pass
+
+        # Set timestamp (backup mechanism)
+        updates['last_user_input'] = time.time()
+        update_instance_position(instance_name, updates)
+
+        # Send TCP notification LAST (Stop hook wakes, sees flag, exits immediately)
+        if notify_port:
+            notify_instance(instance_name)
+
+        # Wait for Stop hook to delete flag file (PROOF of exit)
+        wait_for_stop_exit(instance_name)
+
+    # Build message based on what happened
+    msg = None
+
+    # Determine if this is an HCOM-launched instance
+    is_hcom_launched = os.environ.get('HCOM_LAUNCHED') == '1'
+
+    # Show bootstrap if not already announced
+    if not alias_announced:
+        if is_hcom_launched:
+            # HCOM-launched instance - show bootstrap immediately
+            msg = build_hcom_bootstrap_text(instance_name)
+            update_instance_position(instance_name, {'alias_announced': True})
+        else:
+            # Vanilla Claude instance - check if user is about to run an hcom command
+            user_prompt = hook_data.get('prompt', '')
+            hcom_command_pattern = r'\bhcom\s+\w+'
+            if re.search(hcom_command_pattern, user_prompt, re.IGNORECASE):
+                # Bootstrap not shown yet - show it preemptively before hcom command runs
+                msg = "[HCOM COMMAND DETECTED]\n\n"
+                msg += build_hcom_bootstrap_text(instance_name)
+                update_instance_position(instance_name, {'alias_announced': True})
+
+    # Add resume status note if we showed bootstrap for a matched resume
+    if msg and is_matched_resume:
+        if is_enabled:
+            msg += "\n[HCOM Session resumed. Your alias and conversation history preserved.]"
+    if msg:
+        output = {
+            "hookSpecificOutput": {
+                "hookEventName": "UserPromptSubmit",
+                "additionalContext": msg
+            }
+        }
+        print(json.dumps(output), file=sys.stdout)
+
+def handle_sessionstart(hook_data: dict[str, Any]) -> None:
+    """Handle SessionStart hook - initial msg & reads environment variables"""
+    # Only show message for HCOM-launched instances
+    if os.environ.get('HCOM_LAUNCHED') == '1':
+        parts = f"[HCOM is started, you can send messages with the command: {build_hcom_command()} send]"
+    else:
+        parts = f"[You can start HCOM with the command: {build_hcom_command()} start]"
+
+    output = {
+        "hookSpecificOutput": {
+            "hookEventName": "SessionStart",
+            "additionalContext": parts
+        }
+    }
+
+    print(json.dumps(output))
+
+def handle_posttooluse(hook_data: dict[str, Any], instance_name: str) -> None:
+    """Handle PostToolUse hook - show launch context or bootstrap"""
+    tool_name = hook_data.get('tool_name', '')
+    tool_input = hook_data.get('tool_input', {})
+    tool_response = hook_data.get('tool_response', {})
+    instance_data = load_instance_position(instance_name)
+
+    # Deliver freeze-period message history when Task tool completes (parent context only)
+    if tool_name == 'Task':
+        parent_pos = instance_data.get('pos', 0) if instance_data else 0
+
+        # Get ALL messages from freeze period first (to get correct end position)
+        result = parse_log_messages(hcom_path('hcom.log'), start_pos=parent_pos)
+        all_messages = result.messages
+        new_pos = result.end_position  # Correct end position from full parse
+
+        # Get subagent activity (messages FROM/TO subagents)
+        subagent_msgs, _, _ = get_subagent_messages(instance_name, since_pos=parent_pos)
+
+        # Get messages that parent would have received (broadcasts, @mentions to parent)
+        positions = load_all_positions()
+        all_instance_names = list(positions.keys())
+
+        parent_msgs = []
+        for msg in all_messages:
+            # Skip if already in subagent messages
+            if msg in subagent_msgs:
+                continue
+            # Get parent's normal messages (broadcasts, @mentions) that arrived during freeze
+            if should_deliver_message(msg, instance_name, all_instance_names):
+                parent_msgs.append(msg)
+
+        # Combine and sort by timestamp
+        all_relevant = subagent_msgs + parent_msgs
+        all_relevant.sort(key=lambda m: m['timestamp'])
+
+        if all_relevant:
+            # Format as conversation log with clear temporal framing
+            msg_lines = []
+            for msg in all_relevant:
+                msg_lines.append(f"{msg['from']}: {msg['message']}")
+
+            formatted = '\n'.join(msg_lines)
+            summary = (
+                f"[Task tool completed - Message history during Task tool]\n"
+                f"The following {len(all_relevant)} message(s) occurred between Task tool start and completion:\n\n"
+                f"{formatted}\n\n"
+                f"[End of message history. These subagent(s) have finished their Task and are no longer active.]"
+            )
+
+            output = {
+                "hookSpecificOutput": {
+                    "hookEventName": "PostToolUse",
+                    "additionalContext": summary
+                }
+            }
+            print(json.dumps(output, ensure_ascii=False))
+            update_instance_position(instance_name, {'pos': new_pos, 'current_subagents': []})
+        else:
+            # No relevant messages, just clear current subagents and advance position
+            update_instance_position(instance_name, {'pos': new_pos, 'current_subagents': []})
+
+        # Extract and save agentId mapping
+        agent_id = tool_response.get('agentId')
+        if agent_id:
+            # Extract HCOM subagent_id from injected prompt
+            prompt = tool_input.get('prompt', '')
+            match = re.search(r'--_hcom_sender\s+(\S+)', prompt)
+            if match:
+                hcom_subagent_id = match.group(1)
+
+                # Store bidirectional mapping in parent instance
+                mappings = instance_data.get('subagent_mappings', {}) if instance_data else {}
+                mappings[hcom_subagent_id] = agent_id
+                update_instance_position(instance_name, {'subagent_mappings': mappings})
+
+        # Mark all subagents exited (Task completed, confirmed all exited)
+        positions = load_all_positions()
+        for name in positions:
+            if name.startswith(f"{instance_name}_"):
+                set_status(name, 'exited', 'task_completed')
+        sys.exit(0)
+
+    # Bash-specific logic: check for hcom commands and show context/bootstrap
+    if tool_name == 'Bash':
+        command = hook_data.get('tool_input', {}).get('command', '')
+        # Detect subagent context
+        if instance_data and in_subagent_context(instance_data):
+            # Inject instructions when subagent runs 'hcom start'
+            if '--_hcom_sender' in command and re.search(r'\bhcom\s+start\b', command):
+                match = re.search(r'--_hcom_sender\s+(\S+)', command)
+                if match:
+                    subagent_alias = match.group(1)
+                    msg = format_subagent_hcom_instructions(subagent_alias)
+                    output = {
+                        "hookSpecificOutput": {
+                            "hookEventName": "PostToolUse",
+                            "additionalContext": msg
+                        }
+                    }
+                    print(json.dumps(output, ensure_ascii=False))
+                    sys.exit(0)
+
+            # Detect subagent 'done' command - subagent finished work, waiting for messages
+            if 'done' in command and '--_hcom_sender' in command:
+                match = re.search(r'--_hcom_sender\s+(\S+)', command)
+                if match:
+                    subagent_id = match.group(1)
+                    # Check if disabled - exit immediately
+                    instance_data_sub = load_instance_position(subagent_id)
+                    if not instance_data_sub or not instance_data_sub.get('enabled', False):
+                        sys.exit(0)
+
+                    # Update heartbeat and status to mark as waiting
+                    update_instance_position(subagent_id, {'last_stop': time.time()})
+                    set_status(subagent_id, 'waiting')
+
+                    # Run polling loop with KNOWN identity
+                    timeout = get_config().subagent_timeout
+                    start = time.time()
+
+                    while time.time() - start < timeout:
+                        # Check disabled on each iteration
+                        instance_data_sub = load_instance_position(subagent_id)
+                        if not instance_data_sub or not instance_data_sub.get('enabled', False):
+                            sys.exit(0)
+
+                        messages = get_unread_messages(subagent_id, update_position=False)
+
+                        if messages:
+                            # Targeted delivery to THIS subagent only
+                            formatted = format_hook_messages(messages, subagent_id)
+                            # Mark as read and set delivery status
+                            result = parse_log_messages(hcom_path(LOG_FILE),
+                                                       instance_data_sub.get('pos', 0))
+                            update_instance_position(subagent_id, {'pos': result.end_position})
+                            set_status(subagent_id, 'delivered', messages[-1]['from'])
+                            # Use additionalContext only (no decision:block)
+                            output = {
+                                "hookSpecificOutput": {
+                                    "hookEventName": "PostToolUse",
+                                    "additionalContext": formatted
+                                }
+                            }
+                            print(json.dumps(output, ensure_ascii=False))
+                            sys.exit(0)
+
+                        # Update heartbeat during wait
+                        update_instance_position(subagent_id, {'last_stop': time.time()})
+                        time.sleep(1)
+
+                    # Timeout - no messages, disable this subagent
+                    update_instance_position(subagent_id, {'enabled': False})
+                    set_status(subagent_id, 'waiting', 'timeout')
+                    sys.exit(0)
+
+            # All exits above handled - this code unreachable but keep for consistency
+            sys.exit(0)
+
+        # Parent context - show launch context and bootstrap
+
+        # Check for help or launch commands (combined pattern)
+        if re.search(r'\bhcom\s+(?:(?:help|--help|-h)\b|\d+)', command):
+            if not instance_data.get('launch_context_announced', False):
+                msg = build_launch_context(instance_name)
+                update_instance_position(instance_name, {'launch_context_announced': True})
+
+                output = {
+                    "hookSpecificOutput": {
+                        "hookEventName": "PostToolUse",
+                        "additionalContext": msg
+                    }
+                }
+                print(json.dumps(output, ensure_ascii=False))
+            sys.exit(0)
+
+        # Check HCOM_COMMAND_PATTERN for bootstrap (other hcom commands)
+        matches = list(re.finditer(HCOM_COMMAND_PATTERN, command))
+
+        if not matches:
+            sys.exit(0)
+
+        # Check for external stop notification
+        # Detect subagent context for stop notification
+        check_name = instance_name
+        check_data = instance_data
+        if '--_hcom_sender' in command:
+            match = re.search(r'--_hcom_sender\s+(\S+)', command)
+            if match:
+                check_name = match.group(1)
+                check_data = load_instance_position(check_name)
+
+        if check_data and check_data.get('external_stop_pending'):
+            # Clear flag immediately so it only shows once
+            update_instance_position(check_name, {'external_stop_pending': False})
+
+            # Only show if disabled AND was previously enabled (within the window)
+            if not check_data.get('enabled', False) and check_data.get('previously_enabled', False):
+                message = (
+                    "[HCOM NOTIFICATION]\n"
+                    "Your HCOM connection has been stopped by an external command.\n"
+                    "You will no longer receive messages automatically. Stop your current work unless instructed otherwise."
+                )
+                output = {
+                    "hookSpecificOutput": {
+                        "hookEventName": "PostToolUse",
+                        "additionalContext": message
+                    }
+                }
+                print(json.dumps(output, ensure_ascii=False))
+                sys.exit(0)
+
+        # Show bootstrap if not announced yet
+        if not instance_data.get('alias_announced', False):
+            msg = build_hcom_bootstrap_text(instance_name)
+            update_instance_position(instance_name, {'alias_announced': True})
+
+            output = {
+                "hookSpecificOutput": {
+                    "hookEventName": "PostToolUse",
+                    "additionalContext": msg
+                }
+            }
+            print(json.dumps(output, ensure_ascii=False))
+            sys.exit(0)
+
+def handle_sessionend(hook_data: dict[str, Any], instance_name: str, updates: dict[str, Any], instance_data: dict[str, Any] | None) -> None:
+    """Handle SessionEnd hook - mark session as ended and set final status"""
+    reason = hook_data.get('reason', 'unknown')
+
+    # Set session_ended flag to tell Stop hook to exit
+    updates['session_ended'] = True
+
+    # Set status to exited with reason as context (reason: clear, logout, prompt_input_exit, other)
+    set_status(instance_name, 'exited', reason)
+
+    try:
+        update_instance_position(instance_name, updates)
+    except Exception as e:
+        log_hook_error(f'sessionend:update_instance_position({instance_name})', e)
+
+    # Notify instance to wake and exit cleanly
+    notify_instance(instance_name)
+
+def should_skip_vanilla_instance(hook_type: str, hook_data: dict) -> bool:
+    """
+    Returns True if hook should exit early.
+    Vanilla instances (not HCOM-launched) exit early unless:
+    - Enabled
+    - PreToolUse (handles opt-in)
+    - UserPromptSubmit with hcom command in prompt (shows preemptive bootstrap)
+    """
+    # PreToolUse always runs (handles toggle commands)
+    # HCOM-launched instances always run
+    if hook_type == 'pre' or os.environ.get('HCOM_LAUNCHED') == '1':
+        return False
+
+    session_id = hook_data.get('session_id', '')
+    if not session_id:  # No session_id = can't identify instance, skip hook
+        return True
+
+    instance_name = get_display_name(session_id, get_config().tag)
+    instance_file = hcom_path(INSTANCES_DIR, f'{instance_name}.json')
+
+    if not instance_file.exists():
+        # Allow UserPromptSubmit if prompt contains hcom command
+        if hook_type == 'userpromptsubmit':
+            user_prompt = hook_data.get('prompt', '')
+            return not re.search(r'\bhcom\s+\w+', user_prompt, re.IGNORECASE)
+        return True
+
+    return False
+
+def handle_hook(hook_type: str) -> None:
+    """Unified hook handler for all HCOM hooks"""
+    hook_data = json.load(sys.stdin)
+
+    if not ensure_hcom_directories():
+        log_hook_error('handle_hook', Exception('Failed to create directories'))
+        sys.exit(0)
+
+    # SessionStart is standalone - no instance files
+    if hook_type == 'sessionstart':
+        handle_sessionstart(hook_data)
+        sys.exit(0)
+
+    # Vanilla instance check - exit early if should skip
+    if should_skip_vanilla_instance(hook_type, hook_data):
+        sys.exit(0)
+
+    # Initialize instance context (creates file if needed, reuses existing if session_id matches)
+    instance_name, updates, is_matched_resume = init_hook_context(hook_data, hook_type)
+
+    # Load instance data once (for enabled check and to pass to handlers)
+    instance_data = None
+    if hook_type != 'pre':
+        instance_data = load_instance_position(instance_name)
+
+        # Clean up current_subagents if set (regardless of enabled state)
+        # Skip for PostToolUse - let handle_posttooluse deliver messages first, then cleanup
+        # Only run for parent instances (subagents don't manage current_subagents)
+        # NOW: LET HOOKS HANDLE THIS
+
+        # Skip enabled check for UserPromptSubmit when bootstrap needs to be shown
+        # (alias_announced=false means bootstrap hasn't been shown yet)
+        # Skip enabled check for PostToolUse in subagent context (need to deliver subagent messages)
+        # Skip enabled check for SubagentStop (resolves to parent name, but runs for subagents)
+        skip_enabled_check = (
+            (hook_type == 'userpromptsubmit' and not instance_data.get('alias_announced', False)) or
+            (hook_type == 'post' and in_subagent_context(instance_data)) or
+            (hook_type == 'subagent-stop')
+        )
+
+        if not skip_enabled_check:
+            # Skip vanilla instances (never participated)
+            if not instance_data.get('previously_enabled', False):
+                sys.exit(0)
+
+            # Skip exited instances - frozen until restart
+            status = instance_data.get('status')
+            if status == 'exited':
+                # Exception: Allow Stop hook to run when re-enabled (transitions back to 'waiting')
+                if not (hook_type == 'poll' and instance_data.get('enabled', False)):
+                    sys.exit(0)
+
+    match hook_type:
+        case 'pre':
+            handle_pretooluse(hook_data, instance_name)
+        case 'post':
+            handle_posttooluse(hook_data, instance_name)
+        case 'poll':
+            handle_stop(hook_data, instance_name, updates, instance_data)
+        case 'subagent-stop':
+            handle_subagent_stop(hook_data, instance_name, updates, instance_data)
+        case 'notify':
+            handle_notify(hook_data, instance_name, updates, instance_data)
+        case 'userpromptsubmit':
+            handle_userpromptsubmit(hook_data, instance_name, updates, is_matched_resume, instance_data)
+        case 'sessionend':
+            handle_sessionend(hook_data, instance_name, updates, instance_data)
+
+    sys.exit(0)
+
+
+# ==================== Main Entry Point ====================
+
+def main(argv: list[str] | None = None) -> int | None:
+    """Main command dispatcher"""
+    if argv is None:
+        argv = sys.argv[1:]
+    else:
+        argv = argv[1:] if len(argv) > 0 and argv[0].endswith('hcom.py') else argv
+
+    # Hook handlers only (called BY hooks, not users)
+    if argv and argv[0] in ('poll', 'notify', 'pre', 'post', 'sessionstart', 'userpromptsubmit', 'sessionend', 'subagent-stop'):
+        handle_hook(argv[0])
+        return 0
+
+    # Ensure directories exist first (required for version check cache)
+    if not ensure_hcom_directories():
+        print(format_error("Failed to create HCOM directories"), file=sys.stderr)
+        return 1
+
+    # Check for updates and show message if available (once daily check, persists until upgrade)
+    if msg := get_update_notice():
+        print(msg, file=sys.stderr)
+
+    # Ensure hooks current (warns but never blocks)
+    ensure_hooks_current()
+
+    # Route to commands
+    try:
+        if not argv:
+            return cmd_watch([])
+        elif argv[0] in ('help', '--help', '-h'):
+            return cmd_help()
+        elif argv[0] in ('--version', '-v'):
+            print(f"hcom {__version__}")
+            return 0
+        elif argv[0] == 'send_cli':
+            if len(argv) < 2:
+                print(format_error("Message required"), file=sys.stderr)
+                return 1
+            return send_cli(argv[1])
+        elif argv[0] == 'watch':
+            return cmd_watch(argv[1:])
+        elif argv[0] == 'send':
+            return cmd_send(argv[1:])
+        elif argv[0] == 'stop':
+            return cmd_stop(argv[1:])
+        elif argv[0] == 'start':
+            return cmd_start(argv[1:])
+        elif argv[0] == 'reset':
+            return cmd_reset(argv[1:])
+        elif argv[0].isdigit() or argv[0] == 'claude':
+            # Launch instances: hcom <1-100> [args] or hcom claude [args]
+            return cmd_launch(argv)
+        else:
+            print(format_error(
+                f"Unknown command: {argv[0]}",
+                "Run 'hcom --help' for usage"
+            ), file=sys.stderr)
+            return 1
+    except (CLIError, ValueError) as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+
+# ==================== Exports for UI Module ====================
+
+__all__ = [
+    # Core functions
+    'cmd_launch', 'cmd_start', 'cmd_stop', 'cmd_reset', 'send_message',
+    'get_instance_status', 'parse_log_messages', 'ensure_hcom_directories',
+    'format_age', 'list_available_agents', 'get_status_counts',
+    # Path utilities
+    'hcom_path',
+    # Configuration
+    'get_config', 'reload_config', '_parse_env_value',
+    # Instance operations
+    'load_all_positions', 'should_show_in_watch',
+    # Constants
+    'SENDER', 'SENDER_EMOJI', 'LOG_FILE', 'INSTANCES_DIR',
+]
+
+if __name__ == '__main__':
+    sys.exit(main())