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

hcom/__main__.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 """
-hcom 0.3.1
+hcom
 CLI tool for launching multiple Claude Code terminals with interactive subagents, headless persistence, and real-time communication via hooks
 """
 
@@ -19,18 +19,20 @@ import platform
 import random
 from pathlib import Path
 from datetime import datetime, timedelta
-from typing import Optional, Any, NamedTuple
-from dataclasses import dataclass, asdict, field
+from typing import Any, NamedTuple
+from dataclasses import dataclass
 
 if sys.version_info < (3, 10):
     sys.exit("Error: hcom requires Python 3.10 or higher")
 
+__version__ = "0.5.0"
+
 # ==================== Constants ====================
 
 IS_WINDOWS = sys.platform == 'win32'
 
-def is_wsl():
-    """Detect if running in WSL (Windows Subsystem for Linux)"""
+def is_wsl() -> bool:
+    """Detect if running in WSL"""
     if platform.system() != 'Linux':
         return False
     try:
@@ -39,7 +41,7 @@ def is_wsl():
     except (FileNotFoundError, PermissionError, OSError):
         return False
 
-def is_termux():
+def is_termux() -> bool:
     """Detect if running in Termux on Android"""
     return (
         'TERMUX_VERSION' in os.environ or              # Primary: Works all versions
@@ -48,51 +50,15 @@ def is_termux():
         'com.termux' in os.environ.get('PREFIX', '')   # Fallback: PREFIX check
     )
 
-HCOM_ACTIVE_ENV = 'HCOM_ACTIVE'
-HCOM_ACTIVE_VALUE = '1'
-
 EXIT_SUCCESS = 0
 EXIT_BLOCK = 2
 
-ERROR_ACCESS_DENIED = 5     # Windows - Process exists but no permission
-ERROR_INVALID_PARAMETER = 87  # Windows - Invalid PID or parameters
-
 # Windows API constants
 CREATE_NO_WINDOW = 0x08000000  # Prevent console window creation
-PROCESS_QUERY_LIMITED_INFORMATION = 0x1000  # Vista+ minimal access rights
-PROCESS_QUERY_INFORMATION = 0x0400  # Pre-Vista process access rights TODO: is this a joke? why am i supporting pre vista? who the fuck is running claude code on vista let alone pre?! great to keep this comment here! and i will be leaving it here!
 
 # Timing constants
 FILE_RETRY_DELAY = 0.01  # 10ms delay for file lock retries
 STOP_HOOK_POLL_INTERVAL = 0.1     # 100ms between stop hook polls
-KILL_CHECK_INTERVAL = 0.1  # 100ms between process termination checks
-MERGE_ACTIVITY_THRESHOLD = 10  # Seconds of inactivity before allowing instance merge
-
-# Windows kernel32 cache
-_windows_kernel32_cache = None
-
-def get_windows_kernel32():
-    """Get cached Windows kernel32 with function signatures configured.
-    This eliminates repeated initialization in hot code paths (e.g., stop hook polling).
-    """
-    global _windows_kernel32_cache
-    if _windows_kernel32_cache is None and IS_WINDOWS:
-        import ctypes
-        import ctypes.wintypes
-        kernel32 = ctypes.windll.kernel32  # type: ignore[attr-defined]
-
-        # Set proper ctypes function signatures to avoid ERROR_INVALID_PARAMETER
-        kernel32.OpenProcess.argtypes = [ctypes.wintypes.DWORD, ctypes.wintypes.BOOL, ctypes.wintypes.DWORD]
-        kernel32.OpenProcess.restype = ctypes.wintypes.HANDLE
-        kernel32.GetLastError.argtypes = []
-        kernel32.GetLastError.restype = ctypes.wintypes.DWORD
-        kernel32.CloseHandle.argtypes = [ctypes.wintypes.HANDLE]
-        kernel32.CloseHandle.restype = ctypes.wintypes.BOOL
-        kernel32.GetExitCodeProcess.argtypes = [ctypes.wintypes.HANDLE, ctypes.POINTER(ctypes.wintypes.DWORD)]
-        kernel32.GetExitCodeProcess.restype = ctypes.wintypes.BOOL
-
-        _windows_kernel32_cache = kernel32
-    return _windows_kernel32_cache
 
 MENTION_PATTERN = re.compile(r'(?<![a-zA-Z0-9._-])@(\w+)')
 AGENT_NAME_PATTERN = re.compile(r'^[a-z-]+$')
@@ -127,9 +93,11 @@ STATUS_INFO = {
     'tool_pending': ('active', '{} executing'),
     'waiting': ('waiting', 'idle'),
     'message_delivered': ('delivered', 'msg from {}'),
-    'stop_exit': ('inactive', 'stopped'),
     'timeout': ('inactive', 'timeout'),
-    'killed': ('inactive', 'killed'),
+    'stopped': ('inactive', 'stopped'),
+    'force_stopped': ('inactive', 'force stopped'),
+    'started': ('active', 'starting'),
+    'session_ended': ('inactive', 'ended: {}'),
     'blocked': ('blocked', '{} blocked'),
     'unknown': ('unknown', 'unknown'),
 }
@@ -147,15 +115,70 @@ if IS_WINDOWS or is_wsl():
 # ==================== 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, merge_instance_immediately
+# Critical I/O: atomic_write, save_instance_position
 # Pattern: Try/except/return False in hooks, raise in CLI operations.
 
-def log_hook_error(hook_name: str, error: Exception | None = None):
+# ==================== CLI Errors ====================
+
+class CLIError(Exception):
+    """Raised when arguments cannot be mapped to command semantics."""
+
+# ==================== Help Text ====================
+
+HELP_TEXT = """hcom - Claude Hook Comms
+
+Usage: [ENV_VARS] hcom <COUNT> [claude <ARGS>...]
+       hcom watch [--logs|--status|--wait [SEC]]
+       hcom send "message"
+       hcom stop [alias|all] [--force]
+       hcom start [alias]
+       hcom reset [logs|hooks|config]
+
+Launch Examples:
+  hcom 3             Open 3 terminals with claude connected to hcom
+  hcom 3 claude -p                            + Background/headless
+  HCOM_TAG=api hcom 3 claude -p               + @-mention group tag
+
+Commands:
+  watch              Interactive messaging/status dashboard
+    --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
+    --force          Emergency stop (denies Bash tool)
+
+  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_PROMPT=text   Initial prompt
+  HCOM_TIMEOUT=secs  Timeout in seconds (default: 1800)
+
+Config: ~/.hcom/config.env
+Docs: https://github.com/aannoo/claude-hook-comms"""
+
+
+# ==================== Logging ====================
+
+def log_hook_error(hook_name: str, error: Exception | str | None = None) -> None:
     """Log hook exceptions or just general logging to ~/.hcom/scripts/hooks.log for debugging"""
     import traceback
     try:
         log_file = hcom_path(SCRIPTS_DIR) / "hooks.log"
-        log_file.parent.mkdir(parents=True, exist_ok=True)
         timestamp = datetime.now().isoformat()
         if error and isinstance(error, Exception):
             tb = ''.join(traceback.format_exception(type(error), error, error.__traceback__))
@@ -168,43 +191,55 @@ def log_hook_error(hook_name: str, error: Exception | None = None):
         pass  # Silent failure in error logging
 
 # ==================== Config Defaults ====================
+# Config precedence: env var > ~/.hcom/config.env > defaults
+# All config via HcomConfig dataclass (timeout, terminal, prompt, hints, tag, agent)
 
-# Type definition for configuration
-@dataclass
-class HcomConfig:
-    terminal_command: str | None = None
-    terminal_mode: str = "new_window"
-    initial_prompt: str = "Say hi in chat"
-    sender_name: str = "bigboss"
-    sender_emoji: str = "🐳"
-    cli_hints: str = ""
-    wait_timeout: int = 1800  # 30mins
-    max_message_size: int = 1048576  # 1MB
-    max_messages_per_delivery: int = 50
-    first_use_text: str = "Essential, concise messages only, say hi in hcom chat now"
-    instance_hints: str = ""
-    env_overrides: dict = field(default_factory=dict)
-    auto_watch: bool = True  # Auto-launch watch dashboard after open
-
-DEFAULT_CONFIG = HcomConfig()
-
-_config = None
-
-# Generate env var mappings from dataclass fields (except env_overrides)
-HOOK_SETTINGS = {
-    field: f"HCOM_{field.upper()}"
-    for field in DEFAULT_CONFIG.__dataclass_fields__
-    if field != 'env_overrides'
-}
+# 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 = "logs"
 SCRIPTS_DIR = "scripts"
-CONFIG_FILE = "config.json"
+CONFIG_FILE = "config.env"
 ARCHIVE_DIR = "archive"
 
+# Hook type constants
+ACTIVE_HOOK_TYPES = ['SessionStart', 'UserPromptSubmit', 'PreToolUse', 'Stop', 'Notification', 'SessionEnd']
+LEGACY_HOOK_TYPES = ACTIVE_HOOK_TYPES + ['PostToolUse']  # For backward compatibility cleanup
+HOOK_COMMANDS = ['sessionstart', 'userpromptsubmit', 'pre', 'poll', 'notify', 'sessionend']
+LEGACY_HOOK_COMMANDS = HOOK_COMMANDS + ['post']
+
+# 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)
+# - hcom help | hcom --help | hcom -h
+# - hcom watch --status | hcom watch --launch
+# Negative lookahead (?!\s+[-\w]) ensures stop/start not followed by arguments or flags
+HCOM_COMMAND_PATTERN = re.compile(
+    r'((?:uvx\s+)?hcom|(?:python3?\s+)?\S*hcom\.py)\s+'
+    r'(?:send\b|(?:stop|start)(?!\s+[-\w])|(?:help|--help|-h)\b|watch\s+(?:--status|--launch)\b)'
+)
+
 # ==================== File System Utilities ====================
 
 def hcom_path(*parts: str, ensure_parent: bool = False) -> Path:
@@ -216,9 +251,21 @@ def hcom_path(*parts: str, ensure_parent: bool = False) -> Path:
         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, 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:
@@ -297,11 +344,23 @@ def load_instance_position(instance_name: str) -> dict[str, Any]:
 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", ensure_parent=True)
+        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)
@@ -326,132 +385,354 @@ def clear_all_positions() -> None:
     if instances_dir.exists():
         for f in instances_dir.glob('*.json'):
             f.unlink()
-        # Clean up orphaned mapping files
-        for f in instances_dir.glob('.launch_map_*'):
-            f.unlink(missing_ok=True)
-    else:
-        instances_dir.mkdir(exist_ok=True)
 
 # ==================== Configuration System ====================
 
-def get_cached_config():
-    """Get cached configuration, loading if needed"""
+@dataclass
+class HcomConfig:
+    """HCOM configuration with validation. Load priority: env → file → defaults"""
+    timeout: int = 1800
+    terminal: str = 'new'
+    prompt: str = 'say hi in hcom chat'
+    hints: str = ''
+    tag: str = ''
+    agent: str = 'generic'
+
+    def __post_init__(self):
+        """Validate configuration on construction"""
+        errors = self.validate()
+        if errors:
+            raise ValueError(f"Invalid config:\n" + "\n".join(f"  - {e}" for e in errors))
+
+    def validate(self) -> list[str]:
+        """Validate all fields, return list of errors"""
+        errors = []
+
+        # Validate timeout
+        # Validate timeout (bool is subclass of int in Python, must check explicitly)
+        if isinstance(self.timeout, bool):
+            errors.append(f"timeout must be an integer, not boolean (got {self.timeout})")
+        elif not isinstance(self.timeout, int):
+            errors.append(f"timeout must be an integer, got {type(self.timeout).__name__}")
+        elif not 1 <= self.timeout <= 86400:
+            errors.append(f"timeout must be 1-86400 seconds (24 hours), got {self.timeout}")
+
+        # Validate terminal
+        if not isinstance(self.terminal, str):
+            errors.append(f"terminal must be a string, got {type(self.terminal).__name__}")
+        else:
+            valid_modes = ('new', 'here', 'print')
+            if self.terminal not in valid_modes and '{script}' not in self.terminal:
+                errors.append(
+                    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):
+            errors.append(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):
+            errors.append("tag can only contain letters, numbers, and hyphens")
+
+        # Validate agent
+        if not isinstance(self.agent, str):
+            errors.append(f"agent must be a string, got {type(self.agent).__name__}")
+
+        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:
+            try:
+                data['timeout'] = int(timeout_str)
+            except (ValueError, TypeError):
+                pass  # Use default
+
+        # Load string values
+        terminal = get_var('HCOM_TERMINAL')
+        if terminal is not None:
+            data['terminal'] = terminal
+        prompt = get_var('HCOM_PROMPT')
+        if prompt is not None:
+            data['prompt'] = prompt
+        hints = get_var('HCOM_HINTS')
+        if hints is not None:
+            data['hints'] = hints
+        tag = get_var('HCOM_TAG')
+        if tag is not None:
+            data['tag'] = tag
+        agent = get_var('HCOM_AGENT')
+        if agent is not None:
+            data['agent'] = agent
+
+        return cls(**data)  # Validation happens in __post_init__
+
+def _parse_env_file(config_path: Path) -> dict[str, str]:
+    """Parse ENV file (KEY=VALUE format) with security validation"""
+    config = {}
+
+    # Dangerous shell metacharacters that enable command injection
+    DANGEROUS_CHARS = ['`', '$', ';', '|', '&', '\n', '\r']
+
+    try:
+        content = config_path.read_text(encoding='utf-8')
+        for line in content.splitlines():
+            line = line.strip()
+            if not line or line.startswith('#'):
+                continue
+            if '=' in line:
+                key, _, value = line.partition('=')
+                key = key.strip()
+                value = value.strip()
+
+                # Security: Validate HCOM_TERMINAL for command injection
+                if key == 'HCOM_TERMINAL':
+                    if any(c in value for c in DANGEROUS_CHARS):
+                        print(
+                            f"Warning: Unsafe characters in HCOM_TERMINAL "
+                            f"({', '.join(repr(c) for c in DANGEROUS_CHARS if c in value)}), "
+                            f"ignoring custom terminal command",
+                            file=sys.stderr
+                        )
+                        continue
+                    # Additional check: custom commands must contain {script} placeholder
+                    if value not in ('new', 'here', 'print') and '{script}' not in value:
+                        print(
+                            f"Warning: HCOM_TERMINAL custom command must include {{script}} placeholder, "
+                            f"ignoring",
+                            file=sys.stderr
+                        )
+                        continue
+
+                # Remove outer quotes only if they match
+                if len(value) >= 2:
+                    if (value[0] == '"' and value[-1] == '"') or (value[0] == "'" and value[-1] == "'"):
+                        value = value[1:-1]
+                if key:
+                    config[key] = value
+    except (FileNotFoundError, PermissionError, UnicodeDecodeError):
+        pass
+    return config
+
+def _write_default_config(config_path: Path) -> None:
+    """Write default config file with documentation"""
+    header = """# HCOM Configuration
+#
+# All HCOM_* settings can be set here (persistent) or via environment variables (temporary).
+# Environment variables override config file values.
+#
+# HCOM settings:
+#   HCOM_TIMEOUT - Instance Stop hook wait timeout in seconds (default: 1800)
+#   HCOM_TERMINAL - Terminal mode: "new", "here", "print", or custom command with {script}
+#   HCOM_PROMPT - Initial prompt for new instances (empty = no auto prompt)
+#   HCOM_HINTS - Text appended to all messages received by instances
+#   HCOM_TAG - Group tag for instances (creates tag-* instances)
+#   HCOM_AGENT - Claude code subagent from .claude/agents/, comma-separated for multiple
+#
+# NOTE: Inline comments are not supported. Use separate comment lines.
+#
+# Claude Code settings (passed to Claude instances):
+#   ANTHROPIC_MODEL=opus
+#   Any other Claude Code environment variable
+#
+# Custom terminal examples:
+#   HCOM_TERMINAL="wezterm start -- bash {script}"
+#   HCOM_TERMINAL="kitty -e bash {script}"
+#
+"""
+    defaults = [
+        'HCOM_TIMEOUT=1800',
+        'HCOM_TERMINAL=new',
+        'HCOM_PROMPT=say hi in hcom chat',
+        'HCOM_HINTS=',
+    ]
+    try:
+        atomic_write(config_path, header + '\n'.join(defaults) + '\n')
+    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:
-        _config = _load_config_from_file()
+        _config = HcomConfig.load()
     return _config
 
-def _load_config_from_file() -> dict:
-    """Load configuration from ~/.hcom/config.json"""
-    config_path = hcom_path(CONFIG_FILE, ensure_parent=True)
+def _build_quoted_invocation() -> str:
+    """Build properly quoted python + script path for current platform"""
+    python_path = sys.executable
+    script_path = str(Path(__file__).resolve())
+
+    if IS_WINDOWS:
+        if ' ' in python_path or ' ' in script_path:
+            return f'"{python_path}" "{script_path}"'
+        return f'{python_path} {script_path}'
+    else:
+        return f'{shlex.quote(python_path)} {shlex.quote(script_path)}'
+
+def get_hook_command() -> tuple[str, dict[str, Any]]:
+    """Get hook command - hooks always run, Python code gates participation
 
-    # Start with default config as dict
-    config_dict = asdict(DEFAULT_CONFIG)
+    Uses ${HCOM} environment variable set in settings.json, with fallback to direct python invocation.
+    Participation is controlled by enabled flag in instance JSON files.
+    """
+    if IS_WINDOWS:
+        # Windows: use python path directly
+        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. short - If plugin enabled (plugin installs hcom binary to PATH)
+    2. uvx - If running in uv-managed Python and uvx available
+           (works for both temporary uvx runs and permanent uv tool install)
+    3. short - If hcom binary in PATH
+    4. full - Fallback to full python invocation
+
+    Note: uvx hcom reuses uv tool install environments with zero overhead.
+    """
+    if is_plugin_active():
+        return 'short'
+    elif 'uv' in Path(sys.executable).resolve().parts and shutil.which('uvx'):
+        return 'uvx'
+    elif shutil.which('hcom'):
+        return 'short'
+    else:
+        return 'full'
 
+def check_version_once_daily() -> None:
+    """Check PyPI for newer version, show update command based on install method"""
+    cache_file = hcom_path() / '.version_check'
     try:
-        if user_config := read_file_with_retry(
-            config_path,
-            lambda f: json.load(f),
-            default=None
-        ):
-            # Merge user config into default config
-            config_dict.update(user_config)
-        elif not config_path.exists():
-            # Write default config if file doesn't exist
-            atomic_write(config_path, json.dumps(config_dict, indent=2))
-    except (json.JSONDecodeError, UnicodeDecodeError, PermissionError):
-        print("Warning: Cannot read config file, using defaults", file=sys.stderr)
-        # config_dict already has defaults
-
-    return config_dict
-
-def get_config_value(key: str, default: Any = None) -> Any:
-    """Get config value with proper precedence:
-    1. Environment variable (if in HOOK_SETTINGS)
-    2. Config file
-    3. Default value
+        if cache_file.exists() and time.time() - cache_file.stat().st_mtime < 86400:
+            return
+        
+        import urllib.request
+        with urllib.request.urlopen('https://pypi.org/pypi/hcom/json', timeout=2) as f:
+            data = json.load(f)
+            latest = data['info']['version']
+            
+            # Simple version comparison (tuple of ints)
+            def parse_version(v: str) -> tuple:
+                return tuple(int(x) for x in v.split('.') if x.isdigit())
+            
+            if parse_version(latest) > parse_version(__version__):
+                # Use existing detection to show correct update command
+                if _detect_hcom_command_type() == 'uvx':
+                    update_cmd = "uv tool upgrade hcom"
+                else:
+                    update_cmd = "pip install -U hcom"    
+                
+                print(f"→ hcom v{latest} available: {update_cmd}", file=sys.stderr)
+        
+        cache_file.touch()  # Update cache
+    except:
+        pass  # Silent fail on network/parse errors
+
+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.
     """
-    if key in HOOK_SETTINGS:
-        env_var = HOOK_SETTINGS[key]
-        if (env_value := os.environ.get(env_var)) is not None:
-            # Type conversion based on key
-            if key in ['wait_timeout', 'max_message_size', 'max_messages_per_delivery']:
-                try:
-                    return int(env_value)
-                except ValueError:
-                    # Invalid integer - fall through to config/default
-                    pass
-            elif key == 'auto_watch':
-                return env_value.lower() in ('true', '1', 'yes', 'on')
+    return build_hcom_command(None)
+
+def build_hcom_command(instance_name: str | None = None) -> str:
+    """Build base hcom command - caches PATH check in instance file on first use"""
+    # Determine command type (cached or detect)
+    cmd_type = None
+    if instance_name:
+        data = load_instance_position(instance_name)
+        if data.get('session_id'):
+            if 'hcom_cmd_type' not in data:
+                cmd_type = _detect_hcom_command_type()
+                data['hcom_cmd_type'] = cmd_type
+                save_instance_position(instance_name, data)
             else:
-                # String values - return as-is
-                return env_value
+                cmd_type = data.get('hcom_cmd_type')
 
-    config = get_cached_config()
-    return config.get(key, default)
+    if not cmd_type:
+        cmd_type = _detect_hcom_command_type()
 
-def get_hook_command():
-    """Get hook command with silent fallback
-    
-    Uses ${HCOM:-true} for clean paths, conditional for paths with spaces.
-    Both approaches exit silently (code 0) when not launched via 'hcom open'.
-    """
-    python_path = sys.executable
-    script_path = str(Path(__file__).resolve())
-    
-    if IS_WINDOWS:
-        # Windows cmd.exe syntax - no parentheses so arguments append correctly
-        if ' ' in python_path or ' ' in script_path:
-            return f'IF "%HCOM_ACTIVE%"=="1" "{python_path}" "{script_path}"', {}
-        return f'IF "%HCOM_ACTIVE%"=="1" {python_path} {script_path}', {}
-    elif ' ' in python_path or ' ' in script_path:
-        # Unix with spaces: use conditional check
-        escaped_python = shlex.quote(python_path)
-        escaped_script = shlex.quote(script_path)
-        return f'[ "${{HCOM_ACTIVE}}" = "1" ] && {escaped_python} {escaped_script} || true', {}
+    # Build command based on type
+    if cmd_type == 'short':
+        return 'hcom'
+    elif cmd_type == 'uvx':
+        return 'uvx hcom'
     else:
-        # Unix clean paths: use environment variable
-        return '${HCOM:-true}', {}
+        # Full path fallback
+        return _build_quoted_invocation()
 
-def build_send_command(example_msg: str = '') -> str:
-    """Build send command string - checks if $HCOM exists, falls back to full path"""
+def build_send_command(example_msg: str = '', instance_name: str | None = None) -> str:
+    """Build send command - caches PATH check in instance file on first use"""
     msg = f" '{example_msg}'" if example_msg else ''
-    if os.environ.get('HCOM'):
-        return f'eval "$HCOM send{msg}"'
-    python_path = shlex.quote(sys.executable)
-    script_path = shlex.quote(str(Path(__file__).resolve()))
-    return f'{python_path} {script_path} send{msg}'
-
-def build_claude_env():
-    """Build environment variables for Claude instances"""
-    env = {HCOM_ACTIVE_ENV: HCOM_ACTIVE_VALUE}
-    
-    # Get config file values
-    config = get_cached_config()
-    
-    # Pass env vars only when they differ from config file values
-    for config_key, env_var in HOOK_SETTINGS.items():
-        actual_value = get_config_value(config_key)  # Respects env var precedence
-        config_file_value = config.get(config_key)
-        
-        # Only pass if different from config file (not default)
-        if actual_value != config_file_value and actual_value is not None:
-            env[env_var] = str(actual_value)
-    
-    # Still support env_overrides from config file
-    env.update(config.get('env_overrides', {}))
-    
-    # Set HCOM only for clean paths (spaces handled differently)
-    python_path = sys.executable
-    script_path = str(Path(__file__).resolve())
-    if ' ' not in python_path and ' ' not in script_path:
-        env['HCOM'] = f'{python_path} {script_path}'
-    
+    base_cmd = build_hcom_command(instance_name)
+    return f'{base_cmd} send{msg}'
+
+def build_claude_env() -> dict[str, str]:
+    """Build environment variables for Claude instances
+
+    Passes current environment to Claude, with config.env providing defaults.
+    HCOM_* variables are filtered out (consumed by hcom, not passed to Claude).
+    """
+    env = {}
+
+    # Read config file directly for Claude Code env vars (non-HCOM_ keys)
+    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 not key.startswith('HCOM_'):
+                env[key] = str(value)
+
+    # Overlay with current environment (except HCOM_*)
+    # This ensures user's shell environment is respected
+    for key, value in os.environ.items():
+        if not key.startswith('HCOM_'):
+            env[key] = value
+
     return env
 
 # ==================== Message System ====================
 
-def validate_message(message: str) -> Optional[str]:
+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")
@@ -460,32 +741,90 @@ def validate_message(message: str) -> Optional[str]:
     if re.search(r'[\x00-\x08\x0B-\x0C\x0E-\x1F\u0080-\u009F]', message):
         return format_error("Message contains control characters")
 
-    max_size = get_config_value('max_message_size', 1048576)
-    if len(message) > max_size:
-        return format_error(f"Message too large (max {max_size} chars)")
+    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, ensure_parent=True)
-        
+        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:
             f.write(line)
             f.flush()
-        
+
         return True
     except Exception:
         return False
 
-def should_deliver_message(msg: dict[str, str], instance_name: str, all_instance_names: Optional[list[str]] = None) -> bool:
+def build_hcom_bootstrap_text(instance_name: str) -> str:
+    """Build comprehensive HCOM bootstrap context for instances"""
+    hcom_cmd = build_hcom_command(instance_name=instance_name)
+
+    # 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 user.
+Your HCOM alias for this session: {instance_name}
+
+**Your HCOM Tools:**
+hcom send "msg" / "@alias msg" / "@tag msg"
+hcom watch --status  → Monitor participants in JSON
+hcom watch --launch   → Open dashboard for user in new terminal
+hcom start/stop   → join/leave HCOM chat
+hcom <num>  → Launch instances in new terminal (always run 'hcom help' first)
+
+Commands relevant to user: hcom <num>/start/stop/watch (dont announce others to user)
+Context: User runs 'hcom watch' in new terminal, you run hcom watch --launch for the user ("I'll open 'hcom watch' for you"). 
+
+**Receiving Messages:**
+Format: [new message] sender → you: content
+direct: "@alias" targets a specific instance.
+tag: "@api message" targets all api-* instances.
+Arrives automatically via hooks/bash. {{"decision": "block"}} text is normal operation. No proactive checking needed.
+
+**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 upcoming command execution. User cannot see this.
+Report connection results and overview of relevant hcom info to user using first-person: "I'm connected as {instance_name}"
+"""
+
+
+
+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"""
     text = msg['message']
     
@@ -504,8 +843,7 @@ def should_deliver_message(msg: dict[str, str], instance_name: str, all_instance
         return True
     
     # Check if any mention is for the CLI sender (bigboss)
-    sender_name = get_config_value('sender_name', 'bigboss')
-    sender_mentioned = any(sender_name.lower().startswith(mention.lower()) for mention in mentions)
+    sender_mentioned = any(SENDER.lower().startswith(mention.lower()) for mention in mentions)
     
     # If we have all_instance_names, check if ANY mention matches ANY instance or sender
     if all_instance_names:
@@ -521,69 +859,13 @@ def should_deliver_message(msg: dict[str, str], instance_name: str, all_instance
 
 # ==================== Parsing & Utilities ====================
 
-def parse_open_args(args: list[str]) -> tuple[list[str], Optional[str], list[str], bool]:
-    """Parse arguments for open command
-    
-    Returns:
-        tuple: (instances, prefix, claude_args, background)
-            instances: list of agent names or 'generic'
-            prefix: team name prefix or None
-            claude_args: additional args to pass to claude
-            background: bool, True if --background or -p flag
-    """
-    instances = []
-    prefix = None
-    claude_args = []
-    background = False
-    
-    i = 0
-    while i < len(args):
-        arg = args[i]
-        
-        if arg == '--prefix':
-            if i + 1 >= len(args):
-                raise ValueError(format_error('--prefix requires an argument'))
-            prefix = args[i + 1]
-            if '|' in prefix:
-                raise ValueError(format_error('Prefix cannot contain pipe characters'))
-            i += 2
-        elif arg == '--claude-args':
-            # Next argument contains claude args as a string
-            if i + 1 >= len(args):
-                raise ValueError(format_error('--claude-args requires an argument'))
-            claude_args = shlex.split(args[i + 1])
-            i += 2
-        elif arg == '--background' or arg == '-p':
-            background = True
-            i += 1
-        else:
-            try:
-                count = int(arg)
-                if count < 0:
-                    raise ValueError(format_error(f"Cannot launch negative instances: {count}"))
-                if count > 100:
-                    raise ValueError(format_error(f"Too many instances requested: {count}", "Maximum 100 instances at once"))
-                instances.extend(['generic'] * count)
-            except ValueError as e:
-                if "Cannot launch" in str(e) or "Too many instances" in str(e):
-                    raise
-                # Not a number, treat as agent name
-                instances.append(arg)
-            i += 1
-    
-    if not instances:
-        instances = ['generic']
-    
-    return instances, prefix, claude_args, background
-
 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
-    yaml_end = content.find('\n---', 3)
-    if yaml_end < 0:
+    if (yaml_end := content.find('\n---', 3)) < 0:
         return {}  # No closing marker
     
     yaml_section = content[3:yaml_end]
@@ -682,7 +964,7 @@ def strip_frontmatter(content: str) -> str:
                 return '\n'.join(lines[i+1:]).strip()
     return content
 
-def get_display_name(session_id: Optional[str], prefix: Optional[str] = None) -> str:
+def get_display_name(session_id: str | None, tag: str | None = None) -> str:
     """Get display name for instance using session_id"""
     syls = ['ka', 'ko', 'ma', 'mo', 'na', 'no', 'ra', 'ro', 'sa', 'so', 'ta', 'to', 'va', 'vo', 'za', 'zo', 'be', 'de', 'fe', 'ge', 'le', 'me', 'ne', 're', 'se', 'te', 've', 'we', 'hi']
     # Phonetic letters (5 per syllable, matches syls order)
@@ -726,42 +1008,52 @@ def get_display_name(session_id: Optional[str], prefix: Optional[str] = None) ->
         # session_id is required - fail gracefully
         raise ValueError("session_id required for instance naming")
 
-    if prefix:
-        return f"{prefix}-{base_name}"
+    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 _remove_hcom_hooks_from_settings(settings):
+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
-    
-    # Patterns to match any hcom hook command
-    # Modern hooks (patterns 1-2, 7): Match all hook types via env var or wrapper
-    # - ${HCOM:-true} sessionstart/pre/stop/notify/userpromptsubmit
-    # - [ "${HCOM_ACTIVE}" = "1" ] && ... hcom.py ... || true
-    # - sh -c "[ ... ] && ... hcom ..."
-    # Legacy hooks (patterns 3-6): Direct command invocation
-    # - hcom pre/post/stop/notify/sessionstart/userpromptsubmit
-    # - uvx hcom pre/post/stop/notify/sessionstart/userpromptsubmit
-    # - /path/to/hcom.py pre/post/stop/notify/sessionstart/userpromptsubmit
-    hcom_patterns = [
-        r'\$\{?HCOM',                                # Environment variable (${HCOM:-true}) - all hook types
-        r'\bHCOM_ACTIVE.*hcom\.py',                 # Conditional with full path - all hook types
-        r'\bhcom\s+(pre|post|stop|notify|sessionstart|userpromptsubmit)\b',           # Direct hcom command
-        r'\buvx\s+hcom\s+(pre|post|stop|notify|sessionstart|userpromptsubmit)\b',     # uvx hcom command
-        r'hcom\.py["\']?\s+(pre|post|stop|notify|sessionstart|userpromptsubmit)\b',   # hcom.py with optional quote
-        r'["\'][^"\']*hcom\.py["\']?\s+(pre|post|stop|notify|sessionstart|userpromptsubmit)\b(?=\s|$)',  # Quoted path
-        r'sh\s+-c.*hcom',                           # Shell wrapper with hcom
-    ]
-    compiled_patterns = [re.compile(pattern) for pattern in hcom_patterns]
 
     # Check all hook types including PostToolUse for backward compatibility cleanup
-    for event in ['SessionStart', 'UserPromptSubmit', 'PreToolUse', 'PostToolUse', 'Stop', 'Notification']:
+    for event in LEGACY_HOOK_TYPES:
         if event not in settings['hooks']:
             continue
         
@@ -780,7 +1072,7 @@ def _remove_hcom_hooks_from_settings(settings):
                 hook for hook in matcher_copy.get('hooks', [])
                 if not any(
                     pattern.search(hook.get('command', ''))
-                    for pattern in compiled_patterns
+                    for pattern in HCOM_HOOK_PATTERNS
                 )
             ]
             
@@ -796,9 +1088,16 @@ def _remove_hcom_hooks_from_settings(settings):
             settings['hooks'][event] = updated_matchers
         else:
             del settings['hooks'][event]
-    
 
-def build_env_string(env_vars, format_type="bash"):
+    # 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
@@ -807,7 +1106,7 @@ def build_env_string(env_vars, format_type="bash"):
         return ' '.join(f'{k}={shlex.quote(str(v))}' for k, v in env_vars.items())
 
 
-def format_error(message: str, suggestion: Optional[str] = None) -> str:
+def format_error(message: str, suggestion: str | None = None) -> str:
     """Format error message consistently"""
     base = f"Error: {message}"
     if suggestion:
@@ -815,14 +1114,14 @@ def format_error(message: str, suggestion: Optional[str] = None) -> str:
     return base
 
 
-def has_claude_arg(claude_args, arg_names, arg_prefixes):
+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 claude_args and any(
+    return bool(claude_args and any(
         arg in arg_names or arg.startswith(arg_prefixes)
         for arg in claude_args
-    )
+    ))
 
-def build_claude_command(agent_content: Optional[str] = None, claude_args: Optional[list[str]] = None, initial_prompt: str = "Say hi in chat", model: Optional[str] = None, tools: Optional[str] = None) -> tuple[str, Optional[str]]:
+def build_claude_command(agent_content: str | None = None, claude_args: list[str] | None = None, initial_prompt: str = "Say hi in chat", 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.
@@ -848,7 +1147,6 @@ def build_claude_command(agent_content: Optional[str] = None, claude_args: Optio
     if agent_content:
         # Create agent files in scripts directory for unified cleanup
         scripts_dir = hcom_path(SCRIPTS_DIR)
-        scripts_dir.mkdir(parents=True, exist_ok=True)
         temp_file = tempfile.NamedTemporaryFile(mode='w', encoding='utf-8', suffix='.txt', delete=False,
                                               prefix='hcom_agent_', dir=str(scripts_dir))
         temp_file.write(agent_content)
@@ -862,27 +1160,23 @@ def build_claude_command(agent_content: Optional[str] = None, claude_args: Optio
         
         cmd_parts.append(flag)
         cmd_parts.append(f'"$(cat {shlex.quote(temp_file_path)})"')
-    
-    if claude_args or agent_content:
-        cmd_parts.append('--')
-    
-    # Quote initial prompt normally
-    cmd_parts.append(shlex.quote(initial_prompt))
-    
+
+    # Add initial prompt if non-empty
+    if initial_prompt:
+        cmd_parts.append(shlex.quote(initial_prompt))
+
     return ' '.join(cmd_parts), temp_file_path
 
-def create_bash_script(script_file, env, cwd, command_str, background=False):
+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 clear` housekeeping (24 hours)
+    - Background scripts: persist until `hcom reset logs` cleanup (24 hours)
     - Agent scripts: treated like background (contain 'hcom_agent_')
     """
     try:
-        # Ensure parent directory exists
         script_path = Path(script_file)
-        script_path.parent.mkdir(parents=True, exist_ok=True)
     except (OSError, IOError) as e:
         raise Exception(f"Cannot create script directory: {e}")
 
@@ -946,7 +1240,7 @@ def create_bash_script(script_file, env, cwd, command_str, background=False):
     if platform.system() != 'Windows':
         os.chmod(script_file, 0o755)
 
-def find_bash_on_windows():
+def find_bash_on_windows() -> str | None:
     """Find Git Bash on Windows, avoiding WSL's bash launcher"""
     # Build prioritized list of bash candidates
     candidates = []
@@ -961,8 +1255,7 @@ def find_bash_on_windows():
             ])
 
     # 2. Portable Git installation
-    local_appdata = os.environ.get('LOCALAPPDATA', '')
-    if local_appdata:
+    if local_appdata := os.environ.get('LOCALAPPDATA', ''):
         git_portable = Path(local_appdata) / 'Programs' / 'Git'
         candidates.extend([
             str(git_portable / 'usr' / 'bin' / 'bash.exe'),
@@ -970,8 +1263,7 @@ def find_bash_on_windows():
         ])
 
     # 3. PATH bash (if not WSL's launcher)
-    path_bash = shutil.which('bash')
-    if path_bash and not path_bash.lower().endswith(r'system32\bash.exe'):
+    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)
@@ -990,21 +1282,20 @@ def find_bash_on_windows():
     return None
 
 # New helper functions for platform-specific terminal launching
-def get_macos_terminal_argv():
+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():
+def get_windows_terminal_argv() -> list[str]:
     """Return Windows terminal launcher as argv list."""
-    bash_exe = find_bash_on_windows()
-    if not bash_exe:
+    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():
+def get_linux_terminal_argv() -> list[str] | None:
     """Return first available Linux terminal as argv list."""
     terminals = [
         ('gnome-terminal', ['gnome-terminal', '--', 'bash', '{script}']),
@@ -1023,7 +1314,7 @@ def get_linux_terminal_argv():
 
     return None
 
-def windows_hidden_popen(argv, *, env=None, cwd=None, stdout=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]
@@ -1050,7 +1341,7 @@ PLATFORM_TERMINAL_GETTERS = {
     'Linux': get_linux_terminal_argv,
 }
 
-def _parse_terminal_command(template, script_file):
+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.
@@ -1088,7 +1379,7 @@ def _parse_terminal_command(template, script_file):
 
     return replaced
 
-def launch_terminal(command, env, cwd=None, background=False):
+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
     Args:
         command: Command string from build_claude_command
@@ -1102,14 +1393,12 @@ def launch_terminal(command, env, cwd=None, background=False):
 
     # 1) Always create a script
     script_file = str(hcom_path(SCRIPTS_DIR,
-        f'hcom_{os.getpid()}_{random.randint(1000,9999)}.sh',
-        ensure_parent=True))
+        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)
-        logs_dir.mkdir(parents=True, exist_ok=True)
         log_file = logs_dir / env['HCOM_BACKGROUND']
 
         try:
@@ -1152,9 +1441,9 @@ def launch_terminal(command, env, cwd=None, background=False):
         return str(log_file)
 
     # 3) Terminal modes
-    terminal_mode = get_config_value('terminal_mode', 'new_window')
+    terminal_mode = get_config().terminal
 
-    if terminal_mode == 'show_commands':
+    if terminal_mode == 'print':
         # Print script path and contents
         try:
             with open(script_file, 'r', encoding='utf-8') as f:
@@ -1167,7 +1456,7 @@ def launch_terminal(command, env, cwd=None, background=False):
             print(format_error(f"Failed to read script: {e}"), file=sys.stderr)
             return False
 
-    if terminal_mode == 'same_terminal':
+    if terminal_mode == 'here':
         print("Launching Claude in current terminal...")
         if IS_WINDOWS:
             bash_exe = find_bash_on_windows()
@@ -1179,10 +1468,11 @@ def launch_terminal(command, env, cwd=None, background=False):
             result = subprocess.run(['bash', script_file], env=env_vars, cwd=cwd)
         return result.returncode == 0
 
-    # 4) New window mode
-    custom_cmd = get_config_value('terminal_command')
+    # 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:  # No string sentinel checks
+    if not custom_cmd:  # Platform default 'new' mode
         if is_termux():
             # Keep Termux as special case
             am_cmd = [
@@ -1201,8 +1491,7 @@ def launch_terminal(command, env, cwd=None, background=False):
 
         # Unified platform handling via helpers
         system = platform.system()
-        terminal_getter = PLATFORM_TERMINAL_GETTERS.get(system)
-        if not terminal_getter:
+        if not (terminal_getter := PLATFORM_TERMINAL_GETTERS.get(system)):
             raise Exception(format_error(f"Unsupported platform: {system}"))
 
         custom_cmd = terminal_getter()
@@ -1249,18 +1538,30 @@ def launch_terminal(command, env, cwd=None, background=False):
             print(format_error(f"Failed to execute terminal command: {e}"), file=sys.stderr)
             return False
 
-def setup_hooks():
-    """Set up Claude hooks in current directory"""
-    claude_dir = Path.cwd() / '.claude'
-    claude_dir.mkdir(exist_ok=True)
-    
-    settings_path = claude_dir / 'settings.local.json'
+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:
-        settings = read_file_with_retry(
-            settings_path,
-            lambda f: json.load(f),
-            default={}
-        )
+        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}"))
     
@@ -1271,24 +1572,29 @@ def setup_hooks():
         
     # Get the hook command template
     hook_cmd_base, _ = get_hook_command()
-    
-    # Get wait_timeout (needed for Stop hook)
-    wait_timeout = get_config_value('wait_timeout', 1800)
-    
-    # Define all hooks (PostToolUse removed - causes API 400 errors)
+
+    # Define all hooks - must match ACTIVE_HOOK_TYPES
+    # Format: (hook_type, matcher, command, timeout)
     hook_configs = [
         ('SessionStart', '', f'{hook_cmd_base} sessionstart', None),
         ('UserPromptSubmit', '', f'{hook_cmd_base} userpromptsubmit', None),
         ('PreToolUse', 'Bash', f'{hook_cmd_base} pre', None),
-        # ('PostToolUse', '.*', f'{hook_cmd_base} post', None),  # DISABLED
-        ('Stop', '', f'{hook_cmd_base} stop', wait_timeout),
+        ('Stop', '', f'{hook_cmd_base} poll', 86400),  # 24hr timeout max; internal timeout 30min default via config
         ('Notification', '', f'{hook_cmd_base} notify', None),
+        ('SessionEnd', '', f'{hook_cmd_base} sessionend', None),
     ]
-    
+
+    # Validate hook_configs matches ACTIVE_HOOK_TYPES
+    configured_types = [hook_type for hook_type, _, _, _ in hook_configs]
+    if configured_types != ACTIVE_HOOK_TYPES:
+        raise Exception(format_error(
+            f"Hook configuration mismatch: {configured_types} != {ACTIVE_HOOK_TYPES}"
+        ))
+
     for hook_type, matcher, command, timeout in hook_configs:
         if hook_type not in settings['hooks']:
             settings['hooks'][hook_type] = []
-        
+
         hook_dict = {
             'matcher': matcher,
             'hooks': [{
@@ -1298,9 +1604,16 @@ def setup_hooks():
         }
         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))
@@ -1313,104 +1626,50 @@ def setup_hooks():
     
     return True
 
-def verify_hooks_installed(settings_path):
-    """Verify that HCOM hooks were installed correctly"""
+def verify_hooks_installed(settings_path: Path) -> bool:
+    """Verify that HCOM hooks were installed correctly with correct commands"""
     try:
-        settings = read_file_with_retry(
-            settings_path,
-            lambda f: json.load(f),
-            default=None
-        )
+        settings = load_settings_json(settings_path, default=None)
         if not settings:
             return False
 
-        # Check all hook types exist with HCOM commands (PostToolUse removed)
+        # Check all hook types have correct commands (exactly one HCOM hook per type)
         hooks = settings.get('hooks', {})
-        for hook_type in ['SessionStart', 'UserPromptSubmit', 'PreToolUse', 'Stop', 'Notification']:
-            if not any('hcom' in str(h).lower() or 'HCOM' in str(h)
-                      for h in hooks.get(hook_type, [])):
+        for hook_type, expected_cmd in zip(ACTIVE_HOOK_TYPES, HOOK_COMMANDS):
+            hook_matchers = hooks.get(hook_type, [])
+            if not hook_matchers:
+                return False
+
+            # Count HCOM hooks for this type
+            hcom_hook_count = 0
+            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 expected_cmd in command:
+                        hcom_hook_count += 1
+
+            # Must have exactly one HCOM hook (not zero, not duplicates)
+            if hcom_hook_count != 1:
                 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():
+def is_interactive() -> bool:
     """Check if running in interactive mode"""
     return sys.stdin.isatty() and sys.stdout.isatty()
 
-def get_archive_timestamp():
+def get_archive_timestamp() -> str:
     """Get timestamp for archive files"""
     return datetime.now().strftime("%Y-%m-%d_%H%M%S")
 
-def is_parent_alive(parent_pid=None):
-    """Check if parent process is alive"""
-    if parent_pid is None:
-        parent_pid = os.getppid()
-
-    # Orphan detection - PID 1 == definitively orphaned
-    if parent_pid == 1:
-        return False
-
-    result = is_process_alive(parent_pid)
-    return result
-
-def is_process_alive(pid):
-    """Check if a process with given PID exists - cross-platform"""
-    if pid is None:
-        return False
-
-    try:
-        pid = int(pid)
-    except (TypeError, ValueError):
-        return False
-
-    if IS_WINDOWS:
-        # Windows: Use Windows API to check process existence
-        try:
-            kernel32 = get_windows_kernel32()  # Use cached kernel32 instance
-            if not kernel32:
-                return False
-
-            # Try limited permissions first (more likely to succeed on Vista+)
-            handle = kernel32.OpenProcess(PROCESS_QUERY_LIMITED_INFORMATION, False, pid)
-            error = kernel32.GetLastError()
-
-            if not handle:  # Check for None or 0
-                # ERROR_ACCESS_DENIED (5) means process exists but no permission
-                if error == ERROR_ACCESS_DENIED:
-                    return True
-
-                # Try fallback with broader permissions for older Windows
-                handle = kernel32.OpenProcess(PROCESS_QUERY_INFORMATION, False, pid)
-
-                if not handle:  # Check for None or 0
-                    return False  # Process doesn't exist or no permission at all
-
-            # Check if process is still running (not just if handle exists)
-            import ctypes.wintypes
-            exit_code = ctypes.wintypes.DWORD()
-            STILL_ACTIVE = 259
-
-            if kernel32.GetExitCodeProcess(handle, ctypes.byref(exit_code)):
-                kernel32.CloseHandle(handle)
-                is_still_active = exit_code.value == STILL_ACTIVE
-                return is_still_active
-
-            kernel32.CloseHandle(handle)
-            return False  # Couldn't get exit code
-        except Exception:
-            return False
-    else:
-        # Unix: Use os.kill with signal 0
-        try:
-            os.kill(pid, 0)
-            return True
-        except ProcessLookupError:
-            return False
-        except Exception:
-            return False
-
 class LogParseResult(NamedTuple):
     """Result from parsing log messages"""
     messages: list[dict[str, str]]
@@ -1465,7 +1724,7 @@ def get_unread_messages(instance_name: str, update_position: bool = False) -> li
         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, ensure_parent=True)
+    log_file = hcom_path(LOG_FILE)
 
     if not log_file.exists():
         return []
@@ -1512,10 +1771,6 @@ def get_instance_status(pos_data: dict[str, Any]) -> tuple[str, str, str]:
     # Returns: (display_category, formatted_age, status_description)
     now = int(time.time())
 
-    # Check if killed
-    if pos_data.get('pid') is None: #TODO: replace this later when process management stuff removed
-        return "inactive", "", "killed"
-
     # Get last known status
     last_status = pos_data.get('last_status', '')
     last_status_time = pos_data.get('last_status_time', 0)
@@ -1529,10 +1784,25 @@ def get_instance_status(pos_data: dict[str, Any]) -> tuple[str, str, str]:
 
     # Check timeout
     age = now - last_status_time
-    timeout = pos_data.get('wait_timeout', get_config_value('wait_timeout', 1800))
+    timeout = pos_data.get('wait_timeout', get_config().timeout)
     if age > timeout:
         return "inactive", "", "timeout"
 
+    # Check Stop hook heartbeat for both blocked-generic and waiting-stale detection
+    last_stop = pos_data.get('last_stop', 0)
+    heartbeat_age = now - last_stop if last_stop else 999999
+
+    # Generic "Claude is waiting for your input" from Notification hook is meaningless
+    # If Stop hook is actively polling (heartbeat < 2s), instance is actually idle
+    if last_status == 'blocked' and last_context == "Claude is waiting for your input" and heartbeat_age < 2:
+        last_status = 'waiting'
+        display_status, desc_template = 'waiting', 'idle'
+
+    # Detect stale 'waiting' status - check heartbeat, not status timestamp
+    if last_status == 'waiting' and heartbeat_age > 2:
+        status_suffix = " (bg)" if pos_data.get('background') else ""
+        return "unknown", f"({format_age(heartbeat_age)}){status_suffix}", "stale"
+
     # Format description with context if template has {}
     if '{}' in desc_template and last_context:
         status_desc = desc_template.format(last_context)
@@ -1548,15 +1818,12 @@ def get_status_block(status_type: str) -> str:
     text_color = FG_BLACK if color == BG_YELLOW else FG_WHITE
     return f"{text_color}{BOLD}{color} {symbol} {RESET}"
 
-def format_message_line(msg, truncate=False):
+def format_message_line(msg: dict[str, str], truncate: bool = False) -> str:
     """Format a message for display"""
     time_obj = datetime.fromisoformat(msg['timestamp'])
     time_str = time_obj.strftime("%H:%M")
-    
-    sender_name = get_config_value('sender_name', 'bigboss')
-    sender_emoji = get_config_value('sender_emoji', '🐳')
-    
-    display_name = f"{sender_emoji} {msg['from']}" if msg['from'] == sender_name else msg['from']
+
+    display_name = f"{SENDER_EMOJI} {msg['from']}" if msg['from'] == SENDER else msg['from']
     
     if truncate:
         sender = display_name[:10]
@@ -1565,7 +1832,7 @@ def format_message_line(msg, truncate=False):
     else:
         return f"{DIM}{time_str}{RESET} {BOLD}{display_name}{RESET}: {msg['message']}"
 
-def show_recent_messages(messages, limit=None, truncate=False):
+def show_recent_messages(messages: list[dict[str, str]], limit: int | None = None, truncate: bool = False) -> None:
     """Show recent messages"""
     if limit is None:
         messages_to_show = messages
@@ -1577,14 +1844,14 @@ def show_recent_messages(messages, limit=None, truncate=False):
         print(format_message_line(msg, truncate))
 
 
-def get_terminal_height():
+def get_terminal_height() -> int:
     """Get current terminal height"""
     try:
         return shutil.get_terminal_size().lines
     except (AttributeError, OSError):
         return 24
 
-def show_recent_activity_alt_screen(limit=None):
+def show_recent_activity_alt_screen(limit: int | None = None) -> None:
     """Show recent messages in alt screen format with dynamic height"""
     if limit is None:
         # Calculate available height: total - header(8) - instances(varies) - footer(4) - input(3)
@@ -1596,21 +1863,36 @@ def show_recent_activity_alt_screen(limit=None):
         messages = parse_log_messages(log_file).messages
         show_recent_messages(messages, limit, truncate=True)
 
-def show_instances_by_directory():
+def should_show_in_watch(d: dict[str, Any]) -> bool:
+    """Show only enabled instances by default"""
+    # Hide disabled instances
+    if not d.get('enabled', False):
+        return False
+
+    # Hide truly ended sessions
+    if d.get('session_ended'):
+        return False
+
+    # Show all other instances (including 'closed' during transition)
+    return True
+
+def show_instances_by_directory() -> None:
     """Show instances organized by their working directories"""
     positions = load_all_positions()
     if not positions:
         print(f"   {DIM}No Claude instances connected{RESET}")
         return
-    
+
     if positions:
         directories = {}
         for instance_name, pos_data in positions.items():
+            if not should_show_in_watch(pos_data):
+                continue
             directory = pos_data.get("directory", "unknown")
             if directory not in directories:
                 directories[directory] = []
             directories[directory].append((instance_name, pos_data))
-        
+
         for directory, instances in directories.items():
             print(f" {directory}")
             for instance_name, pos_data in instances:
@@ -1622,7 +1904,7 @@ def show_instances_by_directory():
     else:
         print(f"   {DIM}Error reading instance data{RESET}")
 
-def alt_screen_detailed_status_and_input():
+def alt_screen_detailed_status_and_input() -> str:
     """Show detailed status in alt screen and get user input"""
     sys.stdout.write("\033[?1049h\033[2J\033[H")
     
@@ -1651,7 +1933,7 @@ def alt_screen_detailed_status_and_input():
     
     return message
 
-def get_status_summary():
+def get_status_summary() -> str:
     """Get a one-line summary of all instance statuses"""
     positions = load_all_positions()
     if not positions:
@@ -1660,6 +1942,9 @@ def get_status_summary():
     status_counts = {status: 0 for status in STATUS_MAP.keys()}
 
     for _, pos_data in positions.items():
+        # Only count instances that should be shown in watch
+        if not should_show_in_watch(pos_data):
+            continue
         status_type, _, _ = get_instance_status(pos_data)
         if status_type in status_counts:
             status_counts[status_type] += 1
@@ -1681,30 +1966,43 @@ def get_status_summary():
     else:
         return f"{BG_BLUE}{BOLD}{FG_WHITE} no instances {RESET}"
 
-def update_status(s):
+def update_status(s: str) -> None:
     """Update status line in place"""
     sys.stdout.write("\r\033[K" + s)
     sys.stdout.flush()
 
-def log_line_with_status(message, status):
+def log_line_with_status(message: str, status: str) -> None:
     """Print message and immediately restore status"""
     sys.stdout.write("\r\033[K" + message + "\n")
     sys.stdout.write("\033[K" + status)
     sys.stdout.flush()
 
-def initialize_instance_in_position_file(instance_name, session_id=None):
+def initialize_instance_in_position_file(instance_name: str, session_id: str | None = None) -> bool:
     """Initialize instance file with required fields (idempotent). Returns True on success, False on failure."""
     try:
         data = load_instance_position(instance_name)
 
+        # 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
+
         defaults = {
-            "pos": 0,
+            "pos": initial_pos,
+            "starting_pos": initial_pos,
+            "enabled": is_hcom_launched,
             "directory": str(Path.cwd()),
             "last_stop": 0,
             "session_id": session_id or "",
             "transcript_path": "",
             "notification_message": "",
-            "alias_announced": False
+            "alias_announced": False,
+            "tag": None
         }
 
         # Add missing fields (preserve existing)
@@ -1715,7 +2013,7 @@ def initialize_instance_in_position_file(instance_name, session_id=None):
     except Exception:
         return False
 
-def update_instance_position(instance_name, update_fields):
+def update_instance_position(instance_name: str, update_fields: dict[str, Any]) -> None:
     """Update instance position (with NEW and IMPROVED Windows file locking tolerance!!)"""
     try:
         data = load_instance_position(instance_name)
@@ -1734,6 +2032,25 @@ def update_instance_position(instance_name, update_fields):
         else:
             raise
 
+def enable_instance(instance_name: str) -> None:
+    """Enable instance - clears all stop flags and enables Stop hook polling"""
+    update_instance_position(instance_name, {
+        'enabled': True,
+        'force_closed': False,
+        'session_ended': False
+    })
+    set_status(instance_name, 'started')
+
+def disable_instance(instance_name: str, force: bool = False) -> None:
+    """Disable instance - stops Stop hook polling"""
+    updates = {
+        'enabled': False
+    }
+    if force:
+        updates['force_closed'] = True
+    update_instance_position(instance_name, updates)
+    set_status(instance_name, 'force_stopped' if force else 'stopped')
+
 def set_status(instance_name: str, status: str, context: str = ''):
     """Set instance status event with timestamp"""
     update_instance_position(instance_name, {
@@ -1741,98 +2058,14 @@ def set_status(instance_name: str, status: str, context: str = ''):
         'last_status_time': int(time.time()),
         'last_status_context': context
     })
-    log_hook_error(f"Set status for {instance_name} to {status} with context {context}") #TODO: change to 'log'?
+    log_hook_error('set_status', f'Setting status to {status} with context {context} for {instance_name}')
 
-def merge_instance_data(to_data, from_data):
-    """Merge instance data from from_data into to_data."""
-    # Use current session_id from source (overwrites previous)
-    to_data['session_id'] = from_data.get('session_id', to_data.get('session_id', ''))
+# ==================== Command Functions ====================
 
-    # Update transient fields from source
-    to_data['pid'] = os.getppid()  # Always use current PID
-    to_data['transcript_path'] = from_data.get('transcript_path', to_data.get('transcript_path', ''))
-
-    # Preserve maximum position
-    to_data['pos'] = max(to_data.get('pos', 0), from_data.get('pos', 0))
-
-    # Update directory to most recent
-    to_data['directory'] = from_data.get('directory', to_data.get('directory', str(Path.cwd())))
-
-    # Update heartbeat timestamp to most recent
-    to_data['last_stop'] = max(to_data.get('last_stop', 0), from_data.get('last_stop', 0))
-
-    # Merge new status fields - take most recent status event
-    from_time = from_data.get('last_status_time', 0)
-    to_time = to_data.get('last_status_time', 0)
-    if from_time > to_time:
-        to_data['last_status'] = from_data.get('last_status', '')
-        to_data['last_status_time'] = from_time
-        to_data['last_status_context'] = from_data.get('last_status_context', '')
-
-    # Preserve background mode if set
-    to_data['background'] = to_data.get('background') or from_data.get('background')
-    if from_data.get('background_log_file'):
-        to_data['background_log_file'] = from_data['background_log_file']
-
-    return to_data
-
-def terminate_process(pid, force=False):
-    """Cross-platform process termination"""
-    try:
-        if IS_WINDOWS:
-            cmd = ['taskkill', '/PID', str(pid)]
-            if force:
-                cmd.insert(1, '/F')
-            subprocess.run(cmd, capture_output=True, check=True)
-        else:
-            os.kill(pid, 9 if force else 15)  # SIGKILL or SIGTERM
-        return True
-    except (ProcessLookupError, OSError, subprocess.CalledProcessError):
-        return False  # Process already dead
-
-def merge_instance_immediately(from_name, to_name):
-    """Merge from_name into to_name with safety checks. Returns success message or error message."""
-    if from_name == to_name:
-        return ""
-
-    try:
-        from_data = load_instance_position(from_name)
-        to_data = load_instance_position(to_name)
-
-        # Check if target has recent activity (time-based check instead of PID)
-        now = time.time()
-        last_activity = max(
-            to_data.get('last_stop', 0),
-            to_data.get('last_status_time', 0)
-        )
-        time_since_activity = now - last_activity
-        if time_since_activity < MERGE_ACTIVITY_THRESHOLD:
-            return f"Cannot recover {to_name}: instance is active (activity {int(time_since_activity)}s ago)"
-
-        # Merge data using helper
-        to_data = merge_instance_data(to_data, from_data)
-
-        # Save merged data - check for success
-        if not save_instance_position(to_name, to_data):
-            return f"Failed to save merged data for {to_name}"
-
-        # Cleanup source file only after successful save
-        try:
-            hcom_path(INSTANCES_DIR, f"{from_name}.json").unlink()
-        except (FileNotFoundError, PermissionError, OSError):
-            pass  # Non-critical if cleanup fails
-
-        return f"[SUCCESS] ✓ Recovered alias: {to_name}"
-    except Exception:
-        return f"Failed to recover alias: {to_name}"
-
-
-# ==================== Command Functions ====================
-
-def show_main_screen_header():
+def show_main_screen_header() -> list[dict[str, str]]:
     """Show header for main screen"""
     sys.stdout.write("\033[2J\033[H")
-    
+
     log_file = hcom_path(LOG_FILE)
     all_messages = []
     if log_file.exists():
@@ -1843,42 +2076,9 @@ def show_main_screen_header():
     
     return all_messages
 
-def show_cli_hints(to_stderr=True):
-    """Show CLI hints if configured"""
-    cli_hints = get_config_value('cli_hints', '')
-    if cli_hints:
-        if to_stderr:
-            print(f"\n{cli_hints}", file=sys.stderr)
-        else:
-            print(f"\n{cli_hints}")
-
-def cmd_help():
+def cmd_help() -> int:
     """Show help text"""
-    # Basic help for interactive users
-    print("""hcom - Claude Hook Comms
-
-Usage:
-  hcom open [n]                Launch n Claude instances
-  hcom open <agent>            Launch named agent from .claude/agents/
-  hcom open --prefix <team> n  Launch n instances with team prefix
-  hcom open --background       Launch instances as background processes (-p also works)
-  hcom open --claude-args "--model sonnet"  Pass claude code CLI flags
-  hcom watch                   View conversation dashboard
-  hcom clear                   Clear and archive conversation
-  hcom cleanup                 Remove hooks from current directory
-  hcom cleanup --all           Remove hooks from all tracked directories
-  hcom kill [instance alias]   Kill specific instance
-  hcom kill --all              Kill all running instances
-  hcom help                    Show this help
-
-Automation:
-  hcom send 'msg'              Send message to all
-  hcom send '@prefix msg'      Send to specific instances
-  hcom watch --logs            Show conversation log
-  hcom watch --status          Show status of instances
-  hcom watch --wait [seconds]  Wait for new messages (default 60s)
-
-Docs: https://raw.githubusercontent.com/aannoo/claude-hook-comms/main/README.md""")
+    print(HELP_TEXT)
 
     # Additional help for AI assistants
     if os.environ.get('CLAUDECODE') == '1' or not sys.stdin.isatty():
@@ -1888,26 +2088,26 @@ Docs: https://raw.githubusercontent.com/aannoo/claude-hook-comms/main/README.md"
 
 CONCEPT: HCOM launches Claude Code instances in new terminal windows.
 They communicate with each other via a shared conversation.
-You communicate with them via hcom automation commands.
+You communicate with them via hcom commands.
 
 KEY UNDERSTANDING:
 • Single conversation - All instances share ~/.hcom/hcom.log
-• Messaging - Use 'hcom send "message"' from CLI to send messages to instances
-• Instances receive messages via hooks automatically and send with 'eval $HCOM send "message"'
+• Messaging - CLI and instances send with hcom send "message"
+• Instances receive messages via hooks automatically
 • hcom open is directory-specific - always cd to project directory first
-• hcom watch --wait outputs existing logs, then waits for the next message, prints it, and exits. 
-Times out after [seconds]
-• Named agents are custom system prompts created by users/claude code.
-"reviewer" named agent loads .claude/agents/reviewer.md (if it was ever created)
+• Named agents are custom system prompt files created by users/claude code beforehand.
+• Named agents load from .claude/agents/<name>.md - if they have been created
+• hcom watch --wait outputs last 5 seconds of messages, waits for the next message, prints it, and exits. 
 
 LAUNCH PATTERNS:
-  hcom open 2 reviewer                   # 2 generic + 1 reviewer agent
-  hcom open reviewer reviewer            # 2 separate reviewer instances
-  hcom open --prefix api 2               # Team naming: api-hova7, api-kolec
-  hcom open --claude-args "--model sonnet"  # Pass 'claude' CLI flags
-  hcom open --background (or -p) then hcom kill  # Detached background process
-  hcom watch --status (get sessionid) then hcom open --claude-args "--resume <sessionid>"
-  HCOM_INITIAL_PROMPT="do x task" hcom open  # initial prompt to instance
+  hcom 2 claude                          # 2 generic instances
+  hcom claude --model sonnet             # 1 instance with sonnet model
+  hcom 3 claude -p "task"                # 3 instances in background with prompt
+  HCOM_AGENT=reviewer hcom 3 claude      # 3 reviewer instances (agent file must exist)
+  HCOM_TAG=api hcom 2 claude             # Team naming: api-hova7, api-kolec
+  HCOM_AGENT=reviewer,tester hcom 2 claude  # 2 reviewers + 2 testers
+  hcom claude --resume <sessionid>       # Resume specific session
+  HCOM_PROMPT="task" hcom claude         # Set initial prompt for instance
 
 @MENTION TARGETING:
   hcom send "message"           # Broadcasts to everyone
@@ -1916,144 +2116,161 @@ LAUNCH PATTERNS:
   (Unmatched @mentions broadcast to everyone)
 
 STATUS INDICATORS:
-• ▶ active - instance is working (processing/executing)
-• ▷ delivered - instance just received a message
-• ◉ waiting - instance is waiting for new messages
-• ■ blocked - instance is blocked by permission request (needs user approval)
-• ○ inactive - instance is timed out, disconnected, etc
-• ○ unknown - no status information available
+• ▶ active - processing/executing • ▷ delivered - instance just received a message
+• ◉ idle - waiting for new messages • ■ blocked - permission request (needs user approval)
+• ○ inactive - timed out, disconnected, etc • ○ unknown
               
 CONFIG:
-Config file (persistent): ~/.hcom/config.json
+Config file: ~/.hcom/config.env (KEY=VALUE format)
 
-Key settings (full list in config.json):
-  terminal_mode: "new_window" (default) | "same_terminal" | "show_commands"
-  initial_prompt: "Say hi in chat", first_use_text: "Essential messages only..."
-  instance_hints: "text", cli_hints: "text"  # Extra info for instances/CLI
-  env_overrides: "custom environment variables for instances"
+Environment variables (override config file):
+  HCOM_TERMINAL="new" (default) | "here" | "print" | "kitty -e {script}" (custom)
+  HCOM_PROMPT="say hi in hcom chat"
+  HCOM_HINTS="text"     # Extra info appended to all messages sent to instances
+  HCOM_TAG="api"        # Group instances under api-* names
+  HCOM_AGENT="reviewer" # Launch with agent (comma-separated for multiple)
 
-Temporary environment overrides for any setting (all caps & append HCOM_):
-HCOM_INSTANCE_HINTS="useful info" hcom open  # applied to all messages received by instance
-export HCOM_CLI_HINTS="useful info" && hcom send 'hi'  # applied to all cli commands
 
 EXPECT: hcom instance aliases are auto-generated (5-char format: "hova7"). Check actual aliases 
 with 'hcom watch --status'. Instances respond automatically in shared chat.
 
 Run 'claude --help' to see all claude code CLI flags.""")
 
-        show_cli_hints(to_stderr=False)
     else:
         if not IS_WINDOWS:
             print("\nFor additional info & examples: hcom --help | cat")
 
     return 0
 
-def cmd_open(*args):
-    """Launch Claude instances with chat enabled"""
+def cmd_launch(argv: list[str]) -> int:
+    """Launch Claude instances: hcom [N] [claude] [args]"""
     try:
-        # Parse arguments
-        instances, prefix, claude_args, background = parse_open_args(list(args))
+        # 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
+
+        # 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 ['generic']
+
+        # Detect background mode from -p/--print flags in forwarded args
+        background = '-p' in forwarded or '--print' in forwarded
 
         # Add -p flag and stream-json output for background mode if not already present
+        claude_args = forwarded
         if background and '-p' not in claude_args and '--print' not in claude_args:
             claude_args = ['-p', '--output-format', 'stream-json', '--verbose'] + (claude_args or [])
-        
-        terminal_mode = get_config_value('terminal_mode', 'new_window')
-        
-        # Fail fast for same_terminal with multiple instances
-        if terminal_mode == 'same_terminal' and len(instances) > 1:
+
+        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"same_terminal mode cannot launch {len(instances)} instances",
-                "Use 'hcom open' for one generic instance or 'hcom open <agent>' for one agent"
+                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
-        
-        try:
-            setup_hooks()
-        except Exception as e:
-            print(format_error(f"Failed to setup hooks: {e}"), file=sys.stderr)
-            return 1
-        
-        log_file = hcom_path(LOG_FILE, ensure_parent=True)
+
+        log_file = hcom_path(LOG_FILE)
         instances_dir = hcom_path(INSTANCES_DIR)
-        instances_dir.mkdir(exist_ok=True)
-        
+
         if not log_file.exists():
             log_file.touch()
-        
+
         # Build environment variables for Claude instances
         base_env = build_claude_env()
 
-        # Add prefix-specific hints if provided
-        if prefix:
-            base_env['HCOM_PREFIX'] = prefix
-            send_cmd = build_send_command()
-            hint = f"To respond to {prefix} group: {send_cmd} '@{prefix} message'"
-            base_env['HCOM_INSTANCE_HINTS'] = hint
-            first_use = f"You're in the {prefix} group. Use {prefix} to message: {send_cmd} '@{prefix} message'"
-            base_env['HCOM_FIRST_USE_TEXT'] = first_use
-        
+        # Add tag-specific hints if provided
+        if tag:
+            base_env['HCOM_TAG'] = tag
+
         launched = 0
-        initial_prompt = get_config_value('initial_prompt', 'Say hi in chat')
-        
-        for _, instance_type in enumerate(instances):
-            instance_env = base_env.copy()
-
-            # Set unique launch ID for sender detection in cmd_send()
-            launch_id = f"{int(time.time())}_{random.randint(10000, 99999)}"
-            instance_env['HCOM_LAUNCH_ID'] = launch_id
-
-            # 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 instance_type == 'generic':
-                # Generic instance - no agent content
-                claude_cmd, _ = build_claude_command(
-                    agent_content=None,
-                    claude_args=claude_args,
-                    initial_prompt=initial_prompt
-                )
-            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')
+        initial_prompt = get_config().prompt
+
+        # 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 instance_type == 'generic':
+                    # Generic instance - no agent content
                     claude_cmd, _ = build_claude_command(
-                        agent_content=agent_content,
+                        agent_content=None,
                         claude_args=claude_args,
-                        initial_prompt=initial_prompt,
-                        model=agent_model,
-                        tools=agent_tools
+                        initial_prompt=initial_prompt
                     )
-                    # 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"Background 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 = len(instances)
+                    # 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,
+                            initial_prompt=initial_prompt,
+                            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"Background 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:
@@ -2066,36 +2283,31 @@ def cmd_open(*args):
         else:
             print(f"Launched {launched} Claude instance{'s' if launched != 1 else ''}")
 
-        # Auto-launch watch dashboard if configured and conditions are met
-        terminal_mode = get_config_value('terminal_mode')
-        auto_watch = get_config_value('auto_watch', True)
+        # 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
-        if terminal_mode == 'new_window' and auto_watch and failed == 0 and is_interactive():
+        # Only auto-watch if ALL instances launched successfully and launches windows (not 'here' or 'print')
+        if terminal_mode not in ('here', 'print') and failed == 0 and is_interactive():
             # Show tips first if needed
-            if prefix:
-                print(f"\n  • Send to {prefix} team: hcom send '@{prefix} message'")
+            if tag:
+                print(f"\n  • Send to {tag} team: hcom send '@{tag} message'")
 
             # Clear transition message
             print("\nOpening hcom watch...")
             time.sleep(2)  # Brief pause so user sees the message
 
             # Launch interactive watch dashboard in current terminal
-            return cmd_watch()
+            return cmd_watch([])  # Empty argv = interactive mode
         else:
             tips = [
                 "Run 'hcom watch' to view/send in conversation dashboard",
             ]
-            if prefix:
-                tips.append(f"Send to {prefix} team: hcom send '@{prefix} message'")
+            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")
 
-            # Show cli_hints if configured (non-interactive mode)
-            if not is_interactive():
-                show_cli_hints(to_stderr=False)
-
             return 0
         
     except ValueError as e:
@@ -2105,40 +2317,45 @@ def cmd_open(*args):
         print(str(e), file=sys.stderr)
         return 1
 
-def cmd_watch(*args):
-    """View conversation dashboard"""
+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 open' first"), file=sys.stderr)
+        print(format_error("No conversation log found", "Run 'hcom' first"), file=sys.stderr)
         return 1
-    
-    # Parse arguments
-    show_logs = False
-    show_status = False
-    wait_timeout = None
-    
-    i = 0
-    while i < len(args):
-        arg = args[i]
-        if arg == '--logs':
-            show_logs = True
-        elif arg == '--status':
-            show_status = True
-        elif arg == '--wait':
-            # Check if next arg is a number
-            if i + 1 < len(args) and args[i + 1].isdigit():
-                wait_timeout = int(args[i + 1])
-                i += 1  # Skip the number
-            else:
-                wait_timeout = 60  # Default
-        i += 1
-    
-    # If wait is specified, enable logs to show the messages
-    if wait_timeout is not None:
-        show_logs = True
-    
+
     # Non-interactive mode (no TTY or flags specified)
     if not is_interactive() or show_logs or show_status:
         if show_logs:
@@ -2150,14 +2367,16 @@ def cmd_watch(*args):
                 last_pos = 0
                 messages = []
             
-            # If --wait, show only recent messages to prevent context bloat
+            # 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_messages = [m for m in messages if datetime.fromisoformat(m['timestamp']) > cutoff]
-                
+                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 last 5 seconds of messages---', file=sys.stderr) #TODO: change this to recent messages and have logic like last 3 messages + all messages in last 5 seconds.
+                    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)
@@ -2195,7 +2414,6 @@ def cmd_watch(*args):
                 else:
                     print("No messages yet", file=sys.stderr)
             
-            show_cli_hints()
                     
         elif show_status:
             # Build JSON output
@@ -2205,6 +2423,8 @@ def cmd_watch(*args):
             status_counts = {}
 
             for name, data in positions.items():
+                if not should_show_in_watch(data):
+                    continue
                 status, age, _ = get_instance_status(data)
                 instances[name] = {
                     "status": status,
@@ -2214,7 +2434,6 @@ def cmd_watch(*args):
                     "last_status": data.get("last_status", ""),
                     "last_status_time": data.get("last_status_time", 0),
                     "last_status_context": data.get("last_status_context", ""),
-                    "pid": data.get("pid"),
                     "background": bool(data.get("background"))
                 }
                 status_counts[status] = status_counts.get(status, 0) + 1
@@ -2235,16 +2454,14 @@ def cmd_watch(*args):
             }
 
             print(json.dumps(output, indent=2))
-            show_cli_hints()
         else:
             print("No TTY - Automation usage:", file=sys.stderr)
-            print("  hcom send 'message'    Send message to chat", 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")
             
-            show_cli_hints()
         
         return 0
     
@@ -2320,10 +2537,9 @@ def cmd_watch(*args):
                     last_pos = log_file.stat().st_size
                 
                 if message and message.strip():
-                    sender_name = get_config_value('sender_name', 'bigboss')
-                    send_message(sender_name, message.strip())
+                    send_cli(message.strip(), quiet=True)
                     print(f"{FG_GREEN}✓ Sent{RESET}")
-                
+
                 print()
                 
                 current_status = get_status_summary()
@@ -2337,37 +2553,24 @@ def cmd_watch(*args):
         
     return 0
 
-def cmd_clear():
+def clear() -> int:
     """Clear and archive conversation"""
-    log_file = hcom_path(LOG_FILE, ensure_parent=True)
+    log_file = hcom_path(LOG_FILE)
     instances_dir = hcom_path(INSTANCES_DIR)
     archive_folder = hcom_path(ARCHIVE_DIR)
-    archive_folder.mkdir(exist_ok=True)
 
-    # Clean up temp files from failed atomic writes
+    # cleanup: temp files, old scripts, old outbox files
+    cutoff_time = time.time() - (24 * 60 * 60)  # 24 hours ago
     if instances_dir.exists():
-        deleted_count = sum(1 for f in instances_dir.glob('*.tmp') if f.unlink(missing_ok=True) is None)
-        if deleted_count > 0:
-            print(f"Cleaned up {deleted_count} temp files")
+        sum(1 for f in instances_dir.glob('*.tmp') if f.unlink(missing_ok=True) is None)
 
-    # Clean up old script files (older than 24 hours)
     scripts_dir = hcom_path(SCRIPTS_DIR)
     if scripts_dir.exists():
-        cutoff_time = time.time() - (24 * 60 * 60)  # 24 hours ago
-        script_count = 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)
-        if script_count > 0:
-            print(f"Cleaned up {script_count} old script files")
-
-    # Clean up old launch mapping files (older than 24 hours)
-    if instances_dir.exists():
-        cutoff_time = time.time() - (24 * 60 * 60)  # 24 hours ago
-        mapping_count = sum(1 for f in instances_dir.glob('.launch_map_*') if f.is_file() and f.stat().st_mtime < cutoff_time and f.unlink(missing_ok=True) is None)
-        if mapping_count > 0:
-            print(f"Cleaned up {mapping_count} old launch mapping files")
+        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")
+        print("No HCOM conversation to clear")
         return 0
 
     # Archive existing files if they have content
@@ -2381,7 +2584,7 @@ def cmd_clear():
         if has_log or has_instances:
             # Create session archive folder with timestamp
             session_archive = hcom_path(ARCHIVE_DIR, f'session-{timestamp}')
-            session_archive.mkdir(exist_ok=True)
+            session_archive.mkdir(parents=True, exist_ok=True)
             
             # Archive log file
             if has_log:
@@ -2394,16 +2597,12 @@ def cmd_clear():
             # Archive instances
             if has_instances:
                 archive_instances = session_archive / INSTANCES_DIR
-                archive_instances.mkdir(exist_ok=True)
+                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)
 
-                # Clean up orphaned mapping files (position files are archived)
-                for f in instances_dir.glob('.launch_map_*'):
-                    f.unlink(missing_ok=True)
-
                 archived = True
         else:
             # Clean up empty files/dirs
@@ -2417,14 +2616,33 @@ def cmd_clear():
 
         if archived:
             print(f"Archived to archive/session-{timestamp}/")
-        print("Started fresh hcom conversation log")
+        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 cleanup_directory_hooks(directory):
+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
@@ -2437,25 +2655,21 @@ def cleanup_directory_hooks(directory):
     
     try:
         # Load existing settings
-        settings = read_file_with_retry(
-            settings_path,
-            lambda f: json.load(f),
-            default=None
-        )
+        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 ['SessionStart', 'UserPromptSubmit', 'PreToolUse', 'PostToolUse', 'Stop', 'Notification'])
+                                  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 ['SessionStart', 'UserPromptSubmit', 'PreToolUse', 'PostToolUse', 'Stop', 'Notification'])
+                             for event in LEGACY_HOOK_TYPES)
         if new_hook_count < original_hook_count:
             hooks_found = True
                 
@@ -2478,59 +2692,289 @@ def cleanup_directory_hooks(directory):
         return 1, format_error(f"Cannot modify settings.local.json: {e}")
 
 
-def cmd_kill(*args):
-    """Kill instances by name or all with --all"""
+def cmd_stop(argv: list[str]) -> int:
+    """Stop instances: hcom stop [alias|all] [--force] [--_hcom_session ID]"""
+    # Parse arguments
+    target = None
+    force = '--force' in argv
+    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
 
-    instance_name = args[0] if args and args[0] != '--all' else None
-    positions = load_all_positions() if not instance_name else {instance_name: load_instance_position(instance_name)}
+        stopped_count = 0
+        bg_logs = []
+        stopped_names = []
+        for instance_name, instance_data in positions.items():
+            if instance_data.get('enabled', False):
+                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))
 
-    # Filter to instances with PIDs (any instance that's running)
-    targets = [(name, data) for name, data in positions.items() if data.get('pid')]
+        if stopped_count == 0:
+            print("No instances to stop")
+        else:
+            print(f"Stopped {stopped_count} instance(s): {', '.join(stopped_names)}")
 
-    if not targets:
-        print(f"No running process found for {instance_name}" if instance_name else "No running instances found")
-        return 1 if instance_name else 0
+            # Show background logs if any
+            if bg_logs:
+                print()
+                print("Background instance logs:")
+                for name, log_file in bg_logs:
+                    print(f"  {name}: {log_file}")
 
-    killed_count = 0
-    for target_name, target_data in targets:
-        status, age, _ = get_instance_status(target_data)
-        instance_type = "background" if target_data.get('background') else "foreground"
+        return 0
 
-        pid = int(target_data['pid'])
-        try:
-            # Try graceful termination first
-            terminate_process(pid, force=False)
-
-            # Wait for process to exit gracefully
-            for _ in range(20):
-                time.sleep(KILL_CHECK_INTERVAL)
-                if not is_process_alive(pid):
-                    # Process terminated successfully
-                    break
+    # 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 (unless forcing)
+    if not position.get('enabled', False) and not force:
+        print(f"HCOM already stopped for {instance_name}")
+        return 0
+
+    # Disable instance (optionally with force)
+    disable_instance(instance_name, force=force)
+
+    if force:
+        print(f"⚠️  Force stopped HCOM for {instance_name}.")
+        print(f"    Bash tool use is now DENIED.")
+        print(f"    To restart: hcom start {instance_name}")
+    else:
+        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"\nBackground log: {log_file}")
+            print(f"Monitor: tail -f {log_file}")
+            if not force:
+                print(f"Force stop: hcom stop --force {instance_name}")
+
+    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:]
+
+    # 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]
+
+    # 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 if bootstrap needed (before any state changes)
+        needs_bootstrap = not (existing_data and existing_data.get('alias_announced', False))
+
+        # 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}")
+
+                        # Show bootstrap for new instances
+            if needs_bootstrap:
+                print(f"\n\n\n{build_hcom_bootstrap_text(instance_name)}")
+                update_instance_position(instance_name, {'alias_announced': True})
+        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}: background instance has exited permanently")
+                print(f"Background 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)
+            # First time vs rejoining: check if has read messages (pos > starting_pos)
+            has_participated = existing_data.get('pos', 0) > existing_data.get('starting_pos', 0)
+            if has_participated:
+                print(f"\nStarted HCOM for {instance_name}. Rejoined chat.")
             else:
-                # Process didn't die from graceful attempt, force kill
-                terminate_process(pid, force=True)
-                time.sleep(0.1)
+                print(f"\nStarted HCOM for {instance_name}. Joined chat.")
 
-            print(f"Killed {target_name} ({instance_type}, {status}{age}, PID {pid})")
-            killed_count += 1
-        except (TypeError, ValueError) as e:
-            print(f"Process {pid} invalid: {e}")
+                        # Show bootstrap before re-enabling if needed
+            if needs_bootstrap:
+                print(f"\n\n\n{build_hcom_bootstrap_text(instance_name)}")
+                update_instance_position(instance_name, {'alias_announced': True})
 
-        # Mark instance as killed
-        update_instance_position(target_name, {'pid': None})
-        set_status(target_name, 'killed')
+        return 0
 
-    if not instance_name:
-        print(f"Killed {killed_count} instance(s)")
+    # 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}: background instance has exited permanently")
+        print(f"Background 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}. Rejoined chat.")
     return 0
 
-def cmd_cleanup(*args):
+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()
@@ -2540,9 +2984,27 @@ def cmd_cleanup(*args):
                         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")
+            print("No directories found in current HCOM tracking")
             return 0
         
         print(f"Found {len(directories)} unique directories to check")
@@ -2583,8 +3045,110 @@ def cmd_cleanup(*args):
         print(message)
         return exit_code
 
-def cmd_send(message):
-    """Send message to hcom"""
+def is_plugin_active() -> bool:
+    """Check if hcom plugin is enabled in Claude Code settings."""
+    settings_path = get_claude_settings_path()
+    if not settings_path.exists():
+        return False
+
+    try:
+        settings = load_settings_json(settings_path, default={})
+        return settings.get('enabledPlugins', {}).get('hcom@hcom', False)
+    except Exception:
+        return False
+
+def has_direct_hooks_present() -> bool:
+    """Check if direct HCOM hooks exist in settings.json
+    Direct hooks always set env.HCOM, plugin hooks don't touch settings.json.
+    """
+    settings_path = get_claude_settings_path()
+    if not settings_path.exists():
+        return False
+    try:
+        settings = load_settings_json(settings_path, default=None)
+        # Direct hooks marker: HCOM environment variable
+        return bool(settings and 'HCOM' in settings.get('env', {}))
+    except Exception:
+        return False
+
+def ensure_hooks_current() -> bool:
+    """Ensure hooks match current execution context - called on EVERY command.
+    Manages transition between plugin and direct hooks automatically.
+    Auto-updates hooks if execution context changes (e.g., pip → uvx).
+    Always returns True (warns but never blocks - Claude Code is fault-tolerant)."""
+
+    # Plugin manages hooks?
+    if is_plugin_active():
+        # Clean up any stale direct hooks (plugin/direct transition)
+        if has_direct_hooks_present():
+            print("Plugin detected. Cleaning up direct hooks...", file=sys.stderr)
+            if remove_global_hooks():
+                print("✓ Using plugin hooks exclusively.", file=sys.stderr)
+                # Only ask for restart if inside Claude Code
+                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)
+            else:
+                # Failed to remove - warn but continue (plugin hooks still work)
+                print("⚠️  Could not remove direct hooks. Check ~/.claude/settings.json", file=sys.stderr)
+        return True  # Plugin hooks active, all good
+
+    # Direct hooks: verify they 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]"""
+    # Parse message and session_id
+    message = None
+    session_id = None
+
+    # 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)
@@ -2605,7 +3169,7 @@ def cmd_send(message):
         try:
             positions = load_all_positions()
             all_instances = list(positions.keys())
-            sender_name = get_config_value('sender_name', 'bigboss')
+            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)]
@@ -2614,90 +3178,72 @@ def cmd_send(message):
         except Exception:
             pass  # Don't fail on warning
 
-    # Determine sender: lookup by launch_id, fallback to config
-    sender_name = None
-    launch_id = os.environ.get('HCOM_LAUNCH_ID')
-    if launch_id:
+    # Determine sender from injected session_id or CLI
+    if session_id and not force_cli:
+        # Instance context - resolve name from session_id (searches existing instances first)
         try:
-            mapping_file = hcom_path(INSTANCES_DIR, f'.launch_map_{launch_id}')
-            if mapping_file.exists():
-                sender_name = mapping_file.read_text(encoding='utf-8').strip()
-        except Exception:
-            pass
+            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
 
-    if not sender_name:
-        sender_name = get_config_value('sender_name', 'bigboss')
-
-    if send_message(sender_name, message):
-        # For instances: check for new messages and display immediately
-        if launch_id:  # Only for instances with HCOM_LAUNCH_ID
-            messages = get_unread_messages(sender_name, update_position=True)
-            if messages:
-                max_msgs = get_config_value('max_messages_per_delivery', 50)
-                messages_to_show = messages[:max_msgs]
-                formatted = format_hook_messages(messages_to_show, sender_name)
-                print(f"Message sent\n\n{formatted}", file=sys.stderr)
-            else:
-                print("Message sent", file=sys.stderr)
+        # 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)
+
+        # Check force_closed
+        if instance_data.get('force_closed'):
+            print(format_error(f"HCOM force stopped for this instance. To recover, delete instance file: rm ~/.hcom/instances/{sender_name}.json"), file=sys.stderr)
+            return 1
+
+        # Check enabled state
+        if not instance_data.get('enabled', False):
+            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
+
+        # Send message
+        if not send_message(sender_name, message):
+            print(format_error("Failed to send message"), file=sys.stderr)
+            return 1
+
+        # Show unread messages
+        messages = get_unread_messages(sender_name, update_position=True)
+        if messages:
+            max_msgs = MAX_MESSAGES_PER_DELIVERY
+            formatted = format_hook_messages(messages[:max_msgs], sender_name)
+            print(f"Message sent\n\n{formatted}", file=sys.stderr)
         else:
-            # Bigboss: just confirm send
             print("Message sent", file=sys.stderr)
-        
-        # Show cli_hints if configured (non-interactive mode)
-        if not is_interactive():
-            show_cli_hints()
-        
+
         return 0
     else:
-        print(format_error("Failed to send message"), file=sys.stderr)
-        return 1
+        # CLI context - no session_id or force_cli=True
 
-def cmd_resume_merge(alias: str) -> int:
-    """Resume/merge current instance into an existing instance by alias.
+        # 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:
+            print(f"⚠️  Cannot determine alias - message sent as '{SENDER}'", file=sys.stderr)
+            print("   Prompt Claude to send a hcom message instead of using bash mode (! prefix).", file=sys.stderr)
 
-    INTERNAL COMMAND: Only called via 'eval $HCOM send --resume alias' during implicit resume workflow.
-    Not meant for direct CLI usage.
-    """
-    # Get current instance name via launch_id mapping (same mechanism as cmd_send)
-    # The mapping is created by init_hook_context() when hooks run
-    launch_id = os.environ.get('HCOM_LAUNCH_ID')
-    if not launch_id:
-        print(format_error("Not in HCOM instance context - no launch ID"), file=sys.stderr)
-        return 1
 
-    instance_name = None
-    try:
-        mapping_file = hcom_path(INSTANCES_DIR, f'.launch_map_{launch_id}')
-        if mapping_file.exists():
-            instance_name = mapping_file.read_text(encoding='utf-8').strip()
-    except Exception:
-        pass
+        sender_name = SENDER
 
-    if not instance_name:
-        print(format_error("Could not determine instance name"), file=sys.stderr)
-        return 1
-
-    # Sanitize alias: only allow alphanumeric, dash, underscore
-    # This prevents path traversal attacks (e.g., ../../etc, /etc, etc.)
-    if not re.match(r'^[A-Za-z0-9\-_]+$', alias):
-        print(format_error("Invalid alias format. Use alphanumeric, dash, or underscore only"), file=sys.stderr)
-        return 1
+        if not send_message(sender_name, message):
+            print(format_error("Failed to send message"), file=sys.stderr)
+            return 1
 
-    # Attempt to merge current instance into target alias
-    status = merge_instance_immediately(instance_name, alias)
+        if not quiet:
+            print(f"✓ Sent from {sender_name}", file=sys.stderr)
 
-    # Handle results
-    if not status:
-        # Empty status means names matched (from_name == to_name)
-        status = f"[SUCCESS] ✓ Already using alias {alias}"
+        return 0
 
-    # Print status and return
-    print(status, file=sys.stderr)
-    return 0 if status.startswith('[SUCCESS]') else 1
+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_hook_messages(messages, instance_name):
+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]
@@ -2706,147 +3252,117 @@ def format_hook_messages(messages, instance_name):
         parts = [f"{msg['from']} → {instance_name}: {msg['message']}" for msg in messages]
         reason = f"[{len(messages)} new messages] | {' | '.join(parts)}"
 
-    # Only append instance_hints to messages (first_use_text is handled separately)
-    instance_hints = get_config_value('instance_hints', '')
-    if instance_hints:
-        reason = f"{reason} | [{instance_hints}]"
+    # 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, hook_type=None):
-    """Initialize instance context - shared by post/stop/notify hooks"""
+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', '')
-    prefix = os.environ.get('HCOM_PREFIX')
-
-    instances_dir = hcom_path(INSTANCES_DIR)
-    instance_name = None
-    merged_state = None
-
-    # Check if current session_id matches any existing instance
-    # This maintains identity after resume/merge operations
-    if not instance_name and 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'):
-                    instance_name = instance_file.stem
-                    merged_state = data
-                    log_hook_error(f'DEBUG: Session_id {session_id[:8]} matched {instance_file.stem}, reusing that name')
-                    break
-            except (json.JSONDecodeError, OSError, KeyError):
-                continue
+    tag = get_config().tag
 
-    # If not found or not resuming, generate new name from session_id
-    if not instance_name:
-        instance_name = get_display_name(session_id, prefix)
-        # DEBUG: Log name generation
-        log_hook_error(f'DEBUG: Generated instance_name={instance_name} from session_id={session_id[:8] if session_id else "None"}')
-
-    # Save launch_id → instance_name mapping for cmd_send()
-    launch_id = os.environ.get('HCOM_LAUNCH_ID')
-    if launch_id:
-        try:
-            mapping_file = hcom_path(INSTANCES_DIR, f'.launch_map_{launch_id}', ensure_parent=True)
-            mapping_file.write_text(instance_name, encoding='utf-8')
-            log_hook_error(f'DEBUG: FINAL - Wrote launch_map_{launch_id} → {instance_name} (session_id={session_id[:8] if session_id else "None"})')
-        except Exception:
-            pass  # Non-critical
+    # 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 merged_state:
-        save_instance_position(instance_name, merged_state)
-
-    # Check if instance is brand new or pre-existing (before creation (WWJD))
-    instance_file = hcom_path(INSTANCES_DIR, f'{instance_name}.json')
-    is_new_instance = not instance_file.exists()
+    if existing_data:
+        save_instance_position(instance_name, existing_data)
 
-    # Skip instance creation for unmatched SessionStart resumes (prevents orphans)
-    # Instance will be created in UserPromptSubmit with correct session_id
-    should_create_instance = not (
-        hook_type == 'sessionstart' and
-            hook_data.get('source', 'startup') == 'resume' and not merged_state
-    )
-    if should_create_instance:
+    # 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)
 
-    # Prepare updates
+    # Build updates dict
     updates: dict[str, Any] = {
         'directory': str(Path.cwd()),
+        'tag': tag,
     }
 
-    # Update session_id (overwrites previous)
     if session_id:
         updates['session_id'] = session_id
 
-    # Update transcript_path to current
     if transcript_path:
         updates['transcript_path'] = transcript_path
 
-    # Always update PID to current (fixes stale PID on implicit resume)
-    updates['pid'] = os.getppid()
-
-    # Add background status if applicable
     bg_env = os.environ.get('HCOM_BACKGROUND')
     if bg_env:
         updates['background'] = True
         updates['background_log_file'] = str(hcom_path(LOGS_DIR, bg_env))
 
-    # Return flags indicating resume state
-    is_resume_match = merged_state is not None
-    return instance_name, updates, is_resume_match, is_new_instance
+    # Simple boolean: matched resume if existing_data found
+    is_matched_resume = (existing_data is not None)
+
+    return instance_name, updates, is_matched_resume
+
+def pretooluse_decision(decision: str, reason: str) -> None:
+    """Exit PreToolUse hook with permission decision"""
+    output = {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": decision,
+            "permissionDecisionReason": reason
+        }
+    }
+    print(json.dumps(output, ensure_ascii=False))
+    sys.exit(EXIT_SUCCESS)
 
-def handle_pretooluse(hook_data, instance_name, updates):
-    """Handle PreToolUse hook - auto-approve HCOM_SEND commands when safe"""
+def handle_pretooluse(hook_data: dict[str, Any], instance_name: str) -> None:
+    """Handle PreToolUse hook - check force_closed, inject session_id"""
+    instance_data = load_instance_position(instance_name)
     tool_name = hook_data.get('tool_name', '')
+    session_id = hook_data.get('session_id', '')
+
+    # FORCE CLOSE CHECK - deny ALL tools
+    if instance_data.get('force_closed'):
+        pretooluse_decision("deny", f"FORCE CLOSED: The user has force stopped HCOM for this instance (you, {instance_name}). Stop using all tools immediately and wait for user instructions.")
 
-    # Non-HCOM_SEND tools: record status (they'll run without permission check)
-    set_status(instance_name, 'tool_pending', tool_name)
+    # Record status for tool execution tracking (only if enabled)
+    if instance_data.get('enabled', False):
+        set_status(instance_name, 'tool_pending', tool_name)
 
-    # Handle HCOM commands in Bash
-    if tool_name == 'Bash':
+    # Inject session_id into hcom commands via updatedInput
+    if tool_name == 'Bash' and session_id:
         command = hook_data.get('tool_input', {}).get('command', '')
-        script_path = str(Path(__file__).resolve())
-
-        # === Auto-approve ALL 'eval $HCOM send' commands (including --resume) ===
-        # This includes:
-        #   - eval $HCOM send "message" (normal messaging between instances)
-        #   - eval $HCOM send --resume alias (resume/merge operation)
-        if ('$HCOM send' in command or
-            'hcom send' in command or
-            (script_path in command and ' send ' in command)):
+
+        # Match hcom commands for session_id injection and auto-approval
+        matches = list(re.finditer(HCOM_COMMAND_PATTERN, command))
+        if matches:
+            # 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",
-                    "permissionDecisionReason": "HCOM send command auto-approved"
+                    "updatedInput": {
+                        "command": modified_command
+                    }
                 }
             }
             print(json.dumps(output, ensure_ascii=False))
             sys.exit(EXIT_SUCCESS)
 
 
-def safe_exit_with_status(instance_name, code=EXIT_SUCCESS):
-    """Safely exit stop hook with proper status tracking"""
-    try:
-        set_status(instance_name, 'stop_exit')
-    except (OSError, PermissionError):
-        pass  # Silently handle any errors
-    sys.exit(code)
 
-def handle_stop(hook_data, instance_name, updates):
+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"""
-    parent_pid = os.getppid()
-    log_hook_error(f'stop:entering_stop_hook_now_pid_{os.getpid()}')
-    log_hook_error(f'stop:entering_stop_hook_now_ppid_{parent_pid}')
-
 
     try:
-        entry_time = time.time()
-        updates['last_stop'] = entry_time
-        timeout = get_config_value('wait_timeout', 1800)
+        updates['last_stop'] = time.time()
+        timeout = get_config().timeout
         updates['wait_timeout'] = timeout
         set_status(instance_name, 'waiting')
 
@@ -2856,45 +3372,63 @@ def handle_stop(hook_data, instance_name, updates):
             log_hook_error(f'stop:update_instance_position({instance_name})', e)
 
         start_time = time.time()
-        log_hook_error(f'stop:start_time_pid_{os.getpid()}')
 
         try:
-            loop_count = 0
+            first_poll = True
             last_heartbeat = start_time
-            # STEP 4: Actual polling loop - this IS the holding pattern
+            # Actual polling loop - this IS the holding pattern
             while time.time() - start_time < timeout:
-                if loop_count == 0:
-                    time.sleep(0.1)  # Initial wait before first poll
-                loop_count += 1
+                if first_poll:
+                    first_poll = False
 
-                # Check if parent is alive
-                if not is_parent_alive(parent_pid):
-                    log_hook_error(f'stop:parent_not_alive_pid_{os.getpid()}')
-                    safe_exit_with_status(instance_name, EXIT_SUCCESS)
-
-                # Load instance data once per poll (needed for messages and user input check)
+                # Reload instance data each poll iteration
                 instance_data = load_instance_position(instance_name)
 
-                # Check if user input is pending - exit cleanly if recent input
+                # 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(EXIT_SUCCESS)
+
+                # Check if session ended (SessionEnd hook fired) - exit without changing status
+                if instance_data.get('session_ended'):
+                    sys.exit(EXIT_SUCCESS)  # Don't overwrite session_ended status
+
+                # 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:
-                    log_hook_error(f'stop:user_input_pending_exiting_pid_{os.getpid()}')
-                    safe_exit_with_status(instance_name, EXIT_SUCCESS)
+                    sys.exit(EXIT_SUCCESS)  # Don't overwrite status - let current status remain
+
+                # Check if stopped/disabled - exit cleanly
+                if not instance_data.get('enabled', False):
+                    sys.exit(EXIT_SUCCESS)  # Preserve 'stopped' status set by cmd_stop
 
                 # Check for new messages and deliver
                 if messages := get_unread_messages(instance_name, update_position=True):
-                    messages_to_show = messages[:get_config_value('max_messages_per_delivery', 50)]
+                    messages_to_show = messages[:MAX_MESSAGES_PER_DELIVERY]
                     reason = format_hook_messages(messages_to_show, instance_name)
                     set_status(instance_name, 'message_delivered', messages_to_show[0]['from'])
 
-                    log_hook_error(f'stop:delivering_message_pid_{os.getpid()}')
                     output = {"decision": "block", "reason": reason}
-                    print(json.dumps(output, ensure_ascii=False), file=sys.stderr)
-                    sys.exit(EXIT_BLOCK)
+                    output_json = json.dumps(output, ensure_ascii=False)
+
+                    # Log what we're about to output for debugging
+                    log_hook_error(f'stop:delivering_message|output_len={len(output_json)}', None)
+                    log_hook_error(f'stop:output_json|{output_json}', None)
 
-                # Update heartbeat every 5 seconds instead of every poll
+                    # Use JSON output method: stdout + exit 0 (per Claude Code hooks reference)
+                    # The "decision": "block" field prevents stoppage, allowing next poll cycle
+                    print(output_json)
+                    sys.stdout.flush()
+                    sys.exit(EXIT_SUCCESS)
+
+                # Update heartbeat every 0.5 seconds for staleness detection
                 now = time.time()
-                if now - last_heartbeat >= 5.0:
+                if now - last_heartbeat >= 0.5:
                     try:
                         update_instance_position(instance_name, {'last_stop': now})
                         last_heartbeat = now
@@ -2913,183 +3447,298 @@ def handle_stop(hook_data, instance_name, updates):
     except Exception as e:
         # Log error and exit gracefully
         log_hook_error('handle_stop', e)
-        safe_exit_with_status(instance_name, EXIT_SUCCESS)
+        sys.exit(EXIT_SUCCESS)  # Preserve previous status on exception
 
-def handle_notify(hook_data, instance_name, updates):
+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"""
     updates['notification_message'] = hook_data.get('message', '')
     update_instance_position(instance_name, updates)
     set_status(instance_name, 'blocked', hook_data.get('message', ''))
 
-def handle_userpromptsubmit(hook_data, instance_name, updates, is_resume_match, is_new_instance):
+def get_user_input_flag_file(instance_name: str) -> Path:
+    """Get path to user input coordination flag file"""
+    return hcom_path(INSTANCES_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"""
-    # Update last user input timestamp
-    updates['last_user_input'] = time.time()
-    update_instance_position(instance_name, updates)
+    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
 
-    # Wait for Stop hook to detect timestamp and exit (prevents api errors / race condition)
-    time.sleep(0.15)
+    # Session_ended prevents user recieving 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
+
+    # Coordinate with Stop hook only if enabled AND Stop hook is active
+    stop_is_active = (time.time() - last_stop) < 1.0
+
+    if is_enabled and stop_is_active:
+        # Create flag file for coordination
+        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)
+
+        # Wait for Stop hook to delete flag file
+        wait_for_stop_exit(instance_name)
 
-    send_cmd = build_send_command('your message')
-    resume_cmd = send_cmd.replace("'your message'", "--resume your_old_alias")
     # Build message based on what happened
     msg = None
-    if is_resume_match:
-        msg = f"[Resumed with hcom chat alias: {instance_name}. Use {send_cmd} to send messages]"
-    elif is_new_instance:
-        # Unmatched resume - show critical recovery message
-        msg = (
-            f"[HCOM RESUME DETECTED - CRITICAL ACTION REQUIRED "
-            f"You MUST recover your HCOM identity to maintain conversation context "
-            f"Run: {resume_cmd} "
-            f"This is REQUIRED for message history and position tracking]"
-        )
-    else:
-        # Check if we need to announce alias (normal startup)
-        instance_data = load_instance_position(instance_name)
-        alias_announced = instance_data.get('alias_announced', False)
-        if not alias_announced:
-            msg = f"[Your hcom chat alias is {instance_name}. You can at-mention others in hcom chat by their alias to DM them. To send a message use: {send_cmd}]"
+
+    # 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[Session resumed. HCOM started for this instance - will receive chat messages. Your alias and conversation history preserved.]"
+        else:
+            msg += "\n[Session resumed. HCOM stopped for this instance - will not receive chat messages. Run 'hcom start' to rejoin chat. Your alias and conversation history preserved.]"
 
     if msg:
-        output = {"hookSpecificOutput": {"hookEventName": "UserPromptSubmit", "additionalContext": msg}}
-        print(json.dumps(output))
+        output = {
+            "hookSpecificOutput": {
+                "hookEventName": "UserPromptSubmit",
+                "additionalContext": msg
+            }
+        }
+        print(json.dumps(output), file=sys.stdout)
 
-def handle_sessionstart(hook_data, instance_name, updates, is_resume_match):
-    """Handle SessionStart hook - deliver welcome/resume message"""
-    source = hook_data.get('source', 'startup')
+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':
+        return
 
-    log_hook_error(f'sessionstart:is_resume_match_{is_resume_match}')
-    log_hook_error(f'sessionstart:instance_name_{instance_name}')
-    log_hook_error(f'sessionstart:source_{source}')
-    log_hook_error(f'sessionstart:updates_{updates}')
-    log_hook_error(f'sessionstart:hook_data_{hook_data}')
+    # Build minimal context from environment
+    parts = ["[HCOM active]"]
 
-    # Reset alias_announced flag so alias shows again on resume/clear/compact
-    updates['alias_announced'] = False
+    if agent_type := os.environ.get('HCOM_SUBAGENT_TYPE'):
+        parts.append(f"[agent: {agent_type}]")
 
-    # Only update instance position if file exists (startup or matched resume)
-    # For unmatched resumes, skip - UserPromptSubmit will create the file with correct session_id
-    if source == 'startup' or is_resume_match:
-        update_instance_position(instance_name, updates)
-        set_status(instance_name, 'session_start')
-
-    log_hook_error(f'sessionstart:instance_name_after_update_{instance_name}')
-
-    # Build send command using helper
-    send_cmd = build_send_command('your message')
-    help_text = f"[Welcome! HCOM chat active. Send messages: {send_cmd}]"
-
-    # Add subagent type if this is a named agent
-    subagent_type = os.environ.get('HCOM_SUBAGENT_TYPE')
-    if subagent_type:
-        help_text += f" [Subagent: {subagent_type}]"
-
-    # Add first use text only on startup
-    if source == 'startup':
-        first_use_text = get_config_value('first_use_text', '')
-        if first_use_text:
-            help_text += f" [{first_use_text}]"
-    elif source == 'resume':
-        if is_resume_match:
-            help_text += f" [Resumed alias: {instance_name}]"
-        else:
-            help_text += f" [Session resumed]"
+    if tag := os.environ.get('HCOM_TAG'):
+        parts.append(f"[tag: {tag}]")
 
-    # Add instance hints to all messages
-    instance_hints = get_config_value('instance_hints', '')
-    if instance_hints:
-        help_text += f" [{instance_hints}]"
+    help_text = " ".join(parts)
+
+    # First time: no instance files or archives exist
+    is_first_time = not any(hcom_path().rglob('*.json'))
+
+    is_first_time = True
+    if is_first_time:
+        help_text += """
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  Welcome to Hook Comms!
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  Dashboard:        hcom watch
+  Toggle on/off:    hcom stop / hcom start
+  Launch:           hcom 3
+  All commands:     hcom help
+  Config:           ~/.hcom/config.env
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+"""
 
-    # Output as additionalContext using hookSpecificOutput format
     output = {
         "hookSpecificOutput": {
             "hookEventName": "SessionStart",
             "additionalContext": help_text
         }
     }
+
     print(json.dumps(output))
 
+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 with reason as context (reason: clear, logout, prompt_input_exit, other)
+    set_status(instance_name, 'session_ended', reason)
+
+    try:
+        update_instance_position(instance_name, updates)
+    except Exception as e:
+        log_hook_error(f'sessionend:update_instance_position({instance_name})', e)
+
+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"""
-    if os.environ.get(HCOM_ACTIVE_ENV) != HCOM_ACTIVE_VALUE:
+    hook_data = json.load(sys.stdin)
+
+    if not ensure_hcom_directories():
+        log_hook_error('handle_hook', Exception('Failed to create directories'))
         sys.exit(EXIT_SUCCESS)
 
-    hook_data = json.load(sys.stdin)
-    log_hook_error(f'handle_hook:hook_data_{hook_data}')
+    # SessionStart is standalone - no instance files
+    if hook_type == 'sessionstart':
+        handle_sessionstart(hook_data)
+        sys.exit(EXIT_SUCCESS)
+
+    # Vanilla instance check - exit early if should skip
+    if should_skip_vanilla_instance(hook_type, hook_data):
+        sys.exit(EXIT_SUCCESS)
+
+    # 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)
 
-    # DEBUG: Log which hook is being called with which session_id
-    session_id_short = hook_data.get('session_id', 'none')[:8] if hook_data.get('session_id') else 'none'
-    log_hook_error(f'DEBUG: Hook {hook_type} called with session_id={session_id_short}')
+        # Skip enabled check for UserPromptSubmit when bootstrap needs to be shown
+        # (alias_announced=false means bootstrap hasn't been shown yet)
+        skip_enabled_check = (hook_type == 'userpromptsubmit' and
+                             not instance_data.get('alias_announced', False))
 
-    instance_name, updates, is_resume_match, is_new_instance = init_hook_context(hook_data, hook_type)
+        if not skip_enabled_check and not instance_data.get('enabled', False):
+            sys.exit(EXIT_SUCCESS)
 
     match hook_type:
         case 'pre':
-            handle_pretooluse(hook_data, instance_name, updates)
-        case 'stop':
-            handle_stop(hook_data, instance_name, updates)
+            handle_pretooluse(hook_data, instance_name)
+        case 'poll':
+            handle_stop(hook_data, instance_name, updates, instance_data)
         case 'notify':
-            handle_notify(hook_data, instance_name, updates)
+            handle_notify(hook_data, instance_name, updates, instance_data)
         case 'userpromptsubmit':
-            handle_userpromptsubmit(hook_data, instance_name, updates, is_resume_match, is_new_instance)
-        case 'sessionstart':
-            handle_sessionstart(hook_data, instance_name, updates, is_resume_match)
-
-    log_hook_error(f'handle_hook:instance_name_{instance_name}')
-
+            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(EXIT_SUCCESS)
 
 
 # ==================== Main Entry Point ====================
 
-def main(argv=None):
+def main(argv: list[str] | None = None) -> int | None:
     """Main command dispatcher"""
     if argv is None:
-        argv = sys.argv
-    
-    if len(argv) < 2:
-        return cmd_help()
-    
-    cmd = argv[1]
-    
-    match cmd:
-        case 'help' | '--help':
+        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', 'sessionstart', 'userpromptsubmit', 'sessionend'):
+        handle_hook(argv[0])
+        return 0
+
+    # Check for updates (CLI commands only, not hooks)
+    check_version_once_daily()
+
+    # Ensure directories exist
+    if not ensure_hcom_directories():
+        print(format_error("Failed to create HCOM directories"), file=sys.stderr)
+        return 1
+
+    # Ensure hooks current (warns but never blocks)
+    ensure_hooks_current()
+
+    # Route to commands
+    try:
+        if not argv or argv[0] in ('help', '--help', '-h'):
             return cmd_help()
-        case 'open':
-            return cmd_open(*argv[2:])
-        case 'watch':
-            return cmd_watch(*argv[2:])
-        case 'clear':
-            return cmd_clear()
-        case 'cleanup':
-            return cmd_cleanup(*argv[2:])
-        case 'send':
-            if len(argv) < 3:
+        elif argv[0] == 'send_cli':
+            if len(argv) < 2:
                 print(format_error("Message required"), file=sys.stderr)
                 return 1
-
-            # HIDDEN COMMAND: --resume is only used internally by instances during resume workflow
-            # Not meant for regular CLI usage. Primary usage:
-            #   - From instances: eval $HCOM send "message" (instances send messages to each other)
-            #   - From CLI: hcom send "message" (user/claude orchestrator sends to instances)
-            if argv[2] == '--resume':
-                if len(argv) < 4:
-                    print(format_error("Alias required for --resume"), file=sys.stderr)
-                    return 1
-                return cmd_resume_merge(argv[3])
-
-            return cmd_send(argv[2])
-        case 'kill':
-            return cmd_kill(*argv[2:])
-        case 'stop' | 'notify' | 'pre' | 'sessionstart' | 'userpromptsubmit':
-            handle_hook(cmd)
-            return 0
-        case _:
-            print(format_error(f"Unknown command: {cmd}", "Run 'hcom help' for available commands"), file=sys.stderr)
+            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 as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
 
 if __name__ == '__main__':
     sys.exit(main())