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

hcom/__main__.py

@@ -19,7 +19,7 @@ import platform
 import random
 from pathlib import Path
 from datetime import datetime, timedelta
-from typing import Any, NamedTuple
+from typing import Any, Callable, NamedTuple, TextIO
 from dataclasses import dataclass
 
 if sys.version_info < (3, 10):
@@ -50,8 +50,6 @@ def is_termux() -> bool:
         'com.termux' in os.environ.get('PREFIX', '')   # Fallback: PREFIX check
     )
 
-EXIT_SUCCESS = 0
-EXIT_BLOCK = 2
 
 # Windows API constants
 CREATE_NO_WINDOW = 0x08000000  # Prevent console window creation
@@ -125,7 +123,7 @@ class CLIError(Exception):
 
 # ==================== Help Text ====================
 
-HELP_TEXT = """hcom - Claude Hook Comms
+HELP_TEXT = """hcom 0.5.0
 
 Usage: [ENV_VARS] hcom <COUNT> [claude <ARGS>...]
        hcom watch [--logs|--status|--wait [SEC]]
@@ -138,6 +136,7 @@ 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
+  claude 'run hcom start'    claude code with prompt will also work
 
 Commands:
   watch              Interactive messaging/status dashboard
@@ -165,8 +164,9 @@ 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)
+  HCOM_PROMPT=text   "Say hi in hcom chat" (default)
+  HCOM_HINTS=text    Text appended to all messages received by instance
+  HCOM_TIMEOUT=secs  Time until disconnected from hcom chat (default 1800s / 30mins)
 
 Config: ~/.hcom/config.env
 Docs: https://github.com/aannoo/claude-hook-comms"""
@@ -204,16 +204,30 @@ SKIP_HISTORY = True  # New instances start at current log position (skip old mes
 # Path constants
 LOG_FILE = "hcom.log"
 INSTANCES_DIR = "instances"
-LOGS_DIR = "logs"
-SCRIPTS_DIR = "scripts"
+LOGS_DIR = ".tmp/logs"
+SCRIPTS_DIR = ".tmp/scripts"
+FLAGS_DIR = ".tmp/flags"
 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 configuration - single source of truth for setup_hooks() and verify_hooks_installed()
+# Format: (hook_type, matcher, command_suffix, timeout)
+# Command gets built as: hook_cmd_base + ' ' + command_suffix (e.g., '${HCOM} poll')
+HOOK_CONFIGS = [
+    ('SessionStart', '', 'sessionstart', None),
+    ('UserPromptSubmit', '', 'userpromptsubmit', None),
+    ('PreToolUse', 'Bash', 'pre', None),
+    ('PostToolUse', 'Bash', 'post', None),   # Match Bash only
+    ('Stop', '', 'poll', 86400),          # Poll for messages (24hr max timeout)
+    ('Notification', '', 'notify', None),
+    ('SessionEnd', '', 'sessionend', None),
+]
+
+# Derived from HOOK_CONFIGS - guaranteed to stay in sync
+ACTIVE_HOOK_TYPES = [cfg[0] for cfg in HOOK_CONFIGS]
+HOOK_COMMANDS = [cfg[2] for cfg in HOOK_CONFIGS]
+LEGACY_HOOK_TYPES = ACTIVE_HOOK_TYPES
+LEGACY_HOOK_COMMANDS = HOOK_COMMANDS
 
 # Hook removal patterns - used by _remove_hcom_hooks_from_settings()
 # Dynamically build from LEGACY_HOOK_COMMANDS to match current and legacy hook formats
@@ -233,11 +247,11 @@ HCOM_HOOK_PATTERNS = [
 # - hcom send (any args)
 # - hcom stop (no args) | hcom start (no args)
 # - hcom help | hcom --help | hcom -h
-# - hcom watch --status | hcom watch --launch
+# - hcom watch --status | hcom watch --launch | hcom watch --logs | hcom watch --wait
 # 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)'
+    r'(?:send\b|(?:stop|start)(?!\s+[-\w])|(?:help|--help|-h)\b|watch\s+(?:--status|--launch|--logs|--wait)\b)'
 )
 
 # ==================== File System Utilities ====================
@@ -256,7 +270,7 @@ def ensure_hcom_directories() -> bool:
     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]:
+        for dir_name in [INSTANCES_DIR, LOGS_DIR, SCRIPTS_DIR, FLAGS_DIR, ARCHIVE_DIR]:
             hcom_path(dir_name).mkdir(parents=True, exist_ok=True)
         return True
     except (OSError, PermissionError):
@@ -295,7 +309,7 @@ def atomic_write(filepath: str | Path, content: str) -> bool:
 
     return False  # All attempts exhausted
 
-def read_file_with_retry(filepath: str | Path, read_func, default: Any = None, max_retries: int = 3) -> Any:
+def read_file_with_retry(filepath: str | Path, read_func: Callable[[TextIO], Any], default: Any = None, max_retries: int = 3) -> Any:
     """Read file with retry logic for Windows file locking"""
     if not Path(filepath).exists():
         return default
@@ -396,7 +410,7 @@ class HcomConfig:
     prompt: str = 'say hi in hcom chat'
     hints: str = ''
     tag: str = ''
-    agent: str = 'generic'
+    agent: str = ''
 
     def __post_init__(self):
         """Validate configuration on construction"""
@@ -539,7 +553,7 @@ def _parse_env_file(config_path: Path) -> dict[str, str]:
 
                 # Remove outer quotes only if they match
                 if len(value) >= 2:
-                    if (value[0] == '"' and value[-1] == '"') or (value[0] == "'" and value[-1] == "'"):
+                    if (value[0] == value[-1]) and value[0] in ('"', "'"):
                         value = value[1:-1]
                 if key:
                     config[key] = value
@@ -551,7 +565,8 @@ 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).
+# All HCOM_* settings (and any env var ie. Claude Code settings)
+# can be set here or via environment variables.
 # Environment variables override config file values.
 #
 # HCOM settings:
@@ -562,15 +577,8 @@ def _write_default_config(config_path: Path) -> None:
 #   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.
+# Put each value on separate lines without comments.
 #
-# 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 = [
@@ -578,6 +586,8 @@ def _write_default_config(config_path: Path) -> None:
         'HCOM_TERMINAL=new',
         'HCOM_PROMPT=say hi in hcom chat',
         'HCOM_HINTS=',
+        'HCOM_TAG=',
+        'HCOM_AGENT=',
     ]
     try:
         atomic_write(config_path, header + '\n'.join(defaults) + '\n')
@@ -622,51 +632,58 @@ def get_hook_command() -> tuple[str, dict[str, Any]]:
 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
+    1. 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.
+    2. short - If hcom binary in PATH
+    3. full - Fallback to full python invocation
     """
-    if is_plugin_active():
-        return 'short'
-    elif 'uv' in Path(sys.executable).resolve().parts and shutil.which('uvx'):
+    if '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'
+def _parse_version(v: str) -> tuple:
+    """Parse version string to comparable tuple"""
+    return tuple(int(x) for x in v.split('.') if x.isdigit())
+
+def get_update_notice() -> str | None:
+    """Check PyPI for updates (once daily), return message if available"""
+    flag = hcom_path(FLAGS_DIR, 'update_available')
+
+    # Check PyPI if flag missing or >24hrs old
+    should_check = not flag.exists() or time.time() - flag.stat().st_mtime > 86400
+
+    if should_check:
+        try:
+            import urllib.request
+            with urllib.request.urlopen('https://pypi.org/pypi/hcom/json', timeout=2) as f:
+                latest = json.load(f)['info']['version']
+
+            if _parse_version(latest) > _parse_version(__version__):
+                atomic_write(flag, latest)  # mtime = cache timestamp
+            else:
+                flag.unlink(missing_ok=True)
+                return None
+        except Exception:
+            pass  # Network error, use cached value if exists
+
+    # Return message if update available
+    if not flag.exists():
+        return None
+
     try:
-        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
+        latest = flag.read_text().strip()
+        # Double-check version (handles manual upgrades)
+        if _parse_version(__version__) >= _parse_version(latest):
+            flag.unlink(missing_ok=True)
+            return None
+
+        cmd = "uv tool upgrade hcom" if _detect_hcom_command_type() == 'uvx' else "pip install -U hcom"
+        return f"→ hcom v{latest} available: {cmd}"
+    except Exception:
+        return None
 
 def _build_hcom_env_value() -> str:
     """Build the value for settings['env']['HCOM'] based on current execution context
@@ -792,37 +809,81 @@ GROUP TAG: You are in the '{tag}' group.
 
     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}"
+- HCOM is a communication tool for you, other claude code instances, and the human user.
+- Your HCOM alias for this session: {instance_name}
+
+Your HCOM Tools:
+- hcom send "msg" (broadcast) / "@alias msg" (direct) / "@tag msg" (tag) - for you
+- hcom watch --status  → See participants JSON (for you only)
+- hcom watch --launch   → Open interactive TUI messaging+status dashboard in new terminal (for the human user)
+- hcom start/stop   → Connect/disconnect from chat (you run these, user can't run it themselves unless they specify an alias)
+- hcom <count>  → Launch instances in new terminal (you MUST run 'hcom help' first to understand context)
+
+UI Separation:
+- The human user has 'hcom watch' (interactive TUI dashboard).
+- You use 'hcom watch --launch' to open it for them (offer to do so).
+- In conversation, call it "hcom watch" (the command they'd run themselves).
+
+Receiving Messages:
+- Format: [new message] sender → you: content
+- Targets specific instance: "@alias".
+- Targets all api-* tagged instances: "@api message".
+- Arrives automatically via hooks/bash. No proactive checking needed.
+- Stop hook feedback shows: {{"decision": "block"}} (this is normal operation).
+
+Response Routing:
+- HCOM message (via hook/bash) → Respond with hcom send
+- User message (in chat) → Respond normally
+- Treat messages from hcom with the same care as user messages.
+- Authority: Prioritize @{SENDER} over other participants.
+
+This is context for YOUR hcom session config. The human user cannot see this config text (but they can see subsequent hcom messages you receive).
+On connection, tell the human user about only these commands: 'hcom <count>', 'hcom watch', 'hcom start', 'hcom stop'
+Report to the human user using first-person, for example: "I'm connected to HCOM as {instance_name}, cool!"
 """
 
+def build_launch_context(instance_name: str) -> str:
+    """Build context for launch command"""
+    return f"""[HCOM LAUNCH INFORMATION]
+BASIC USAGE:
+[ENV_VARS] hcom <COUNT> [claude <ARGS>...]
+- directory-specific (always cd to project directory first)
+- default to foreground instances unless told otherwise/good reason to do bg
+- Everyone shares the same conversation log, isolation is possible with tags and at-mentions.
+
+ENV VARS INFO:
+- YOU cannot use 'HCOM_TERMINAL=here' - Claude cannot launch claude within itself, must be in a new or custom terminal
+- HCOM_AGENT(s) are custom system prompt files created by users/Claude beforehand.
+- HCOM_AGENT(s) load from .claude/agents/<name>.md if they have been created
+
+KEY CLAUDE ARGS:
+Run 'claude --help' for all claude code CLI args. hcom 1 claude [options] [command] [prompt]
+-p           background/headless instance
+--allowedTools=Bash   (background can only hcom chat otherwise, 'claude help' for more tools)
+--model sonnet/haiku/opus
+--resume <sessionid>       (get sessionid from hcom watch --status)
+--system-prompt (for foreground instances) --append-system-prompt (for background instances)
+Example: HCOM_HINTS='essential responses only' hcom 2 claude --model sonnet -p "do task x"
+
+CONTROL: 
+  hcom watch --status    JSON status of all instances
+  hcom watch --logs      All messages (pipe to tail)
+  hcom watch --wait      Block until next message (only use when hcom stopped (started is automatic already))
+
+STATUS INDICATORS:
+  "active", "delivered" | "idle" - waiting for new messages
+  "blocked" - permission request (needs user approval)
+  "inactive" - timed out, disconnected etc
+  "unknown" / "stale" - could be dead
+
+LAUNCH PATTERNS:
+- HCOM_AGENT=reviewer,tester hcom 2 claude "do task x"  # 2x reviewers + 2x testers (4 in total) with initial prompt
+- clone with same context:
+    1. hcom 1 then hcom send 'analyze api' then hcom watch --status (get sessionid)
+    2. HCOM_TAG=clone hcom 3 claude --resume sessionid
+- System prompt (or agent file) + initial prompt + hcom_hints is a powerful combination.
 
+"""
 
 def should_deliver_message(msg: dict[str, str], instance_name: str, all_instance_names: list[str] | None = None) -> bool:
     """Check if message should be delivered based on @-mentions"""
@@ -887,11 +948,9 @@ def extract_agent_config(content: str) -> dict[str, str]:
 
 def resolve_agent(name: str) -> tuple[str, dict[str, str]]:
     """Resolve agent file by name with validation.
-
     Looks for agent files in:
     1. .claude/agents/{name}.md (local)
     2. ~/.claude/agents/{name}.md (global)
-
     Returns tuple: (content without YAML frontmatter, config dict)
     """
     hint = 'Agent names must use lowercase letters and dashes only'
@@ -966,44 +1025,63 @@ def strip_frontmatter(content: str) -> 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)
-    phonetic = "nrlstnrlstnrlstnrlstnrlstnrlstnmlstnmlstnrlmtnrlmtnrlmsnrlmsnrlstnrlstnrlmtnrlmtnrlaynrlaynrlaynrlayaanxrtanxrtdtraxntdaxntraxnrdaynrlaynrlasnrlst"
-
-    dir_char = (Path.cwd().name + 'x')[0].lower()
+    # 50 most recognizable 3-letter words
+    words = [
+        'ace', 'air', 'ant', 'arm', 'art', 'axe', 'bad', 'bag', 'bar', 'bat',
+        'bed', 'bee', 'big', 'box', 'boy', 'bug', 'bus', 'cab', 'can', 'cap',
+        'car', 'cat', 'cop', 'cow', 'cry', 'cup', 'cut', 'day', 'dog', 'dry',
+        'ear', 'egg', 'eye', 'fan', 'fin', 'fly', 'fox', 'fun', 'gem', 'gun',
+        'hat', 'hit', 'hot', 'ice', 'ink', 'jet', 'key', 'law', 'map', 'mix',
+    ]
 
     # Use session_id directly instead of extracting UUID from transcript
     if session_id:
+        # Hash to select word
         hash_val = sum(ord(c) for c in session_id)
-        syl_idx = hash_val % len(syls)
-        syllable = syls[syl_idx]
+        word = words[hash_val % len(words)]
+
+        # Add letter suffix that flows naturally with the word
+        last_char = word[-1]
+        if last_char in 'aeiou':
+            # After vowel: s/n/r/l creates plural/noun/verb patterns
+            suffix_options = 'snrl'
+        else:
+            # After consonant: add vowel or y for pronounceability
+            suffix_options = 'aeiouy'
 
-        letters = phonetic[syl_idx * 5:(syl_idx + 1) * 5]
         letter_hash = sum(ord(c) for c in session_id[1:]) if len(session_id) > 1 else hash_val
-        letter = letters[letter_hash % 5]
+        suffix = suffix_options[letter_hash % len(suffix_options)]
 
-        # Session IDs are UUIDs like "374acbe2-978b-4882-9c0b-641890f066e1"
-        hex_char = session_id[0] if session_id else 'x'
-        base_name = f"{dir_char}{syllable}{letter}{hex_char}"
+        base_name = f"{word}{suffix}"
+        collision_attempt = 0
+
+        # Collision detection: keep adding words until unique
+        while True:
+            instance_file = hcom_path(INSTANCES_DIR, f"{base_name}.json")
+            if not instance_file.exists():
+                break  # Name is unique
 
-        # Collision detection: if taken by different session_id, use more chars
-        instance_file = hcom_path(INSTANCES_DIR, f"{base_name}.json")
-        if instance_file.exists():
             try:
                 with open(instance_file, 'r', encoding='utf-8') as f:
                     data = json.load(f)
 
                 their_session_id = data.get('session_id', '')
 
-                # Deterministic check: different session_id = collision
-                if their_session_id and their_session_id != session_id:
-                    # Use first 4 chars of session_id for collision resolution
-                    base_name = f"{dir_char}{session_id[0:4]}"
-                # If same session_id, it's our file - reuse the name (no collision)
-                # If no session_id in file, assume it's stale/malformed - use base name
+                # Same session_id = our file, reuse name
+                if their_session_id == session_id:
+                    break
+                # No session_id = stale/malformed file, use name
+                if not their_session_id:
+                    break
+
+                # Real collision - add another word
+                collision_hash = sum(ord(c) * (i + collision_attempt) for i, c in enumerate(session_id))
+                collision_word = words[collision_hash % len(words)]
+                base_name = f"{base_name}{collision_word}"
+                collision_attempt += 1
 
             except (json.JSONDecodeError, KeyError, ValueError, OSError):
-                pass  # Malformed file - assume stale, use base name
+                break  # Malformed file - assume stale, use base name
     else:
         # session_id is required - fail gracefully
         raise ValueError("session_id required for instance naming")
@@ -1023,7 +1101,6 @@ def resolve_instance_name(session_id: str, tag: str | None = None) -> tuple[str,
     """
     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)
@@ -1063,7 +1140,11 @@ def _remove_hcom_hooks_from_settings(settings: dict[str, Any]) -> None:
             # Fail fast on malformed settings - Claude won't run with broken settings anyway
             if not isinstance(matcher, dict):
                 raise ValueError(f"Malformed settings: matcher in {event} is not a dict: {type(matcher).__name__}")
-            
+
+            # Validate hooks field if present
+            if 'hooks' in matcher and not isinstance(matcher['hooks'], list):
+                raise ValueError(f"Malformed settings: hooks in {event} matcher is not a list: {type(matcher['hooks']).__name__}")
+
             # Work with a copy to avoid any potential reference issues
             matcher_copy = copy.deepcopy(matcher)
             
@@ -1080,7 +1161,8 @@ def _remove_hcom_hooks_from_settings(settings: dict[str, Any]) -> None:
             if non_hcom_hooks:
                 matcher_copy['hooks'] = non_hcom_hooks
                 updated_matchers.append(matcher_copy)
-            elif not matcher.get('hooks'):  # Preserve matchers that never had hooks
+            elif 'hooks' not in matcher or matcher['hooks'] == []:
+                # Preserve matchers that never had hooks (missing key or empty list only)
                 updated_matchers.append(matcher_copy)
         
         # Update or remove the event
@@ -1244,7 +1326,6 @@ def find_bash_on_windows() -> str | None:
     """Find Git Bash on Windows, avoiding WSL's bash launcher"""
     # Build prioritized list of bash candidates
     candidates = []
-
     # 1. Common Git Bash locations (highest priority)
     for base in [os.environ.get('PROGRAMFILES', r'C:\Program Files'),
                  os.environ.get('PROGRAMFILES(X86)', r'C:\Program Files (x86)')]:
@@ -1253,7 +1334,6 @@ def find_bash_on_windows() -> str | None:
                 str(Path(base) / 'Git' / 'usr' / 'bin' / 'bash.exe'),  # usr/bin is more common
                 str(Path(base) / 'Git' / 'bin' / 'bash.exe')
             ])
-
     # 2. Portable Git installation
     if local_appdata := os.environ.get('LOCALAPPDATA', ''):
         git_portable = Path(local_appdata) / 'Programs' / 'Git'
@@ -1261,11 +1341,9 @@ def find_bash_on_windows() -> str | None:
             str(git_portable / 'usr' / 'bin' / 'bash.exe'),
             str(git_portable / 'bin' / 'bash.exe')
         ])
-
     # 3. PATH bash (if not WSL's launcher)
     if (path_bash := shutil.which('bash')) and not path_bash.lower().endswith(r'system32\bash.exe'):
         candidates.append(path_bash)
-
     # 4. Hardcoded fallbacks (last resort)
     candidates.extend([
         r'C:\Program Files\Git\usr\bin\bash.exe',
@@ -1273,7 +1351,6 @@ def find_bash_on_windows() -> str | None:
         r'C:\Program Files (x86)\Git\usr\bin\bash.exe',
         r'C:\Program Files (x86)\Git\bin\bash.exe'
     ])
-
     # Find first existing bash
     for bash in candidates:
         if bash and Path(bash).exists():
@@ -1573,24 +1650,12 @@ def setup_hooks() -> bool:
     # Get the hook command template
     hook_cmd_base, _ = get_hook_command()
 
-    # Define all hooks - must match ACTIVE_HOOK_TYPES
-    # Format: (hook_type, matcher, command, timeout)
+    # Build hook commands from HOOK_CONFIGS
     hook_configs = [
-        ('SessionStart', '', f'{hook_cmd_base} sessionstart', None),
-        ('UserPromptSubmit', '', f'{hook_cmd_base} userpromptsubmit', None),
-        ('PreToolUse', 'Bash', f'{hook_cmd_base} pre', None),
-        ('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),
+        (hook_type, matcher, f'{hook_cmd_base} {cmd_suffix}', timeout)
+        for hook_type, matcher, cmd_suffix, timeout in HOOK_CONFIGS
     ]
 
-    # 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] = []
@@ -1634,8 +1699,9 @@ def verify_hooks_installed(settings_path: Path) -> bool:
             return False
 
         # Check all hook types have correct commands (exactly one HCOM hook per type)
+        # Derive from HOOK_CONFIGS (single source of truth)
         hooks = settings.get('hooks', {})
-        for hook_type, expected_cmd in zip(ACTIVE_HOOK_TYPES, HOOK_COMMANDS):
+        for hook_type, _, cmd_suffix, _ in HOOK_CONFIGS:
             hook_matchers = hooks.get(hook_type, [])
             if not hook_matchers:
                 return False
@@ -1646,7 +1712,7 @@ def verify_hooks_installed(settings_path: Path) -> bool:
                 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:
+                    if ('${HCOM}' in command or 'hcom' in command.lower()) and cmd_suffix in command:
                         hcom_hook_count += 1
 
             # Must have exactly one HCOM hook (not zero, not duplicates)
@@ -1994,7 +2060,6 @@ def initialize_instance_in_position_file(instance_name: str, session_id: str | N
 
         defaults = {
             "pos": initial_pos,
-            "starting_pos": initial_pos,
             "enabled": is_hcom_launched,
             "directory": str(Path.cwd()),
             "last_stop": 0,
@@ -2079,67 +2144,6 @@ def show_main_screen_header() -> list[dict[str, str]]:
 def cmd_help() -> int:
     """Show help text"""
     print(HELP_TEXT)
-
-    # Additional help for AI assistants
-    if os.environ.get('CLAUDECODE') == '1' or not sys.stdin.isatty():
-        print("""
-
-=== ADDITIONAL INFO ===
-
-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 commands.
-
-KEY UNDERSTANDING:
-• Single conversation - All instances share ~/.hcom/hcom.log
-• 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
-• 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 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
-  hcom send "@api fix this"     # Targets all api-* instances (api-hova7, api-kolec)
-  hcom send "@hova7 status?"    # Targets specific instance
-  (Unmatched @mentions broadcast to everyone)
-
-STATUS INDICATORS:
-• ▶ 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: ~/.hcom/config.env (KEY=VALUE format)
-
-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)
-
-
-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.""")
-
-    else:
-        if not IS_WINDOWS:
-            print("\nFor additional info & examples: hcom --help | cat")
-
     return 0
 
 def cmd_launch(argv: list[str]) -> int:
@@ -2172,7 +2176,7 @@ def cmd_launch(argv: list[str]) -> int:
 
         # 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']
+        agents = [a.strip() for a in agent_env.split(',') if a.strip()] if agent_env else ['']
 
         # Detect background mode from -p/--print flags in forwarded args
         background = '-p' in forwarded or '--print' in forwarded
@@ -2227,8 +2231,8 @@ def cmd_launch(argv: list[str]) -> int:
                     instance_env['HCOM_BACKGROUND'] = log_filename
 
                 # Build claude command
-                if instance_type == 'generic':
-                    # Generic instance - no agent content
+                if not instance_type:
+                    # No agent - no agent content
                     claude_cmd, _ = build_claude_command(
                         agent_content=None,
                         claude_args=claude_args,
@@ -2462,7 +2466,6 @@ def cmd_watch(argv: list[str]) -> int:
             print("  hcom watch --launch    Launch interactive dashboard in new terminal", file=sys.stderr)
             print("  Full information: hcom --help")
             
-        
         return 0
     
     # Interactive dashboard mode
@@ -2824,23 +2827,12 @@ def cmd_start(argv: list[str]) -> int:
     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):
@@ -2858,17 +2850,7 @@ def cmd_start(argv: list[str]) -> int:
 
             # 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:
-                print(f"\nStarted HCOM for {instance_name}. Joined chat.")
-
-                        # 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})
+            print(f"Started HCOM for {instance_name}")
 
         return 0
 
@@ -2916,7 +2898,6 @@ def cmd_start(argv: list[str]) -> int:
 
 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
@@ -3045,55 +3026,12 @@ def cleanup(*args: str) -> int:
         print(message)
         return exit_code
 
-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
+    # Verify hooks exist and match current execution context
     global_settings = get_claude_settings_path()
 
     # Check if hooks are valid (exist + env var matches current context)
@@ -3154,7 +3092,7 @@ def cmd_send(argv: list[str], force_cli: bool = False, quiet: bool = False) -> i
     instances_dir = hcom_path(INSTANCES_DIR)
 
     if not log_file.exists() and not instances_dir.exists():
-        print(format_error("No conversation found", "Run 'hcom open' first"), file=sys.stderr)
+        print(format_error("No conversation found", "Run 'hcom <count>' first"), file=sys.stderr)
         return 1
 
     # Validate message
@@ -3316,7 +3254,7 @@ def pretooluse_decision(decision: str, reason: str) -> None:
         }
     }
     print(json.dumps(output, ensure_ascii=False))
-    sys.exit(EXIT_SUCCESS)
+    sys.exit(0)
 
 def handle_pretooluse(hook_data: dict[str, Any], instance_name: str) -> None:
     """Handle PreToolUse hook - check force_closed, inject session_id"""
@@ -3353,7 +3291,7 @@ def handle_pretooluse(hook_data: dict[str, Any], instance_name: str) -> None:
                 }
             }
             print(json.dumps(output, ensure_ascii=False))
-            sys.exit(EXIT_SUCCESS)
+            sys.exit(0)
 
 
 
@@ -3392,20 +3330,20 @@ def handle_stop(hook_data: dict[str, Any], instance_name: str, updates: dict[str
                     except (FileNotFoundError, PermissionError):
                         # Already deleted or locked, continue anyway
                         pass
-                    sys.exit(EXIT_SUCCESS)
+                    sys.exit(0)
 
                 # 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
+                    sys.exit(0)  # 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:
-                    sys.exit(EXIT_SUCCESS)  # Don't overwrite status - let current status remain
+                    sys.exit(0)  # 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
+                    sys.exit(0)  # Preserve 'stopped' status set by cmd_stop
 
                 # Check for new messages and deliver
                 if messages := get_unread_messages(instance_name, update_position=True):
@@ -3414,17 +3352,8 @@ def handle_stop(hook_data: dict[str, Any], instance_name: str, updates: dict[str
                     set_status(instance_name, 'message_delivered', messages_to_show[0]['from'])
 
                     output = {"decision": "block", "reason": reason}
-                    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)
-
-                    # 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)
+                    print(json.dumps(output, ensure_ascii=False), file=sys.stderr)
+                    sys.exit(2)
 
                 # Update heartbeat every 0.5 seconds for staleness detection
                 now = time.time()
@@ -3443,11 +3372,12 @@ def handle_stop(hook_data: dict[str, Any], instance_name: str, updates: dict[str
 
         # Timeout reached
         set_status(instance_name, 'timeout')
+        sys.exit(0)
 
     except Exception as e:
         # Log error and exit gracefully
         log_hook_error('handle_stop', e)
-        sys.exit(EXIT_SUCCESS)  # Preserve previous status on exception
+        sys.exit(0)  # Preserve previous status on exception
 
 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"""
@@ -3457,13 +3387,12 @@ def handle_notify(hook_data: dict[str, Any], instance_name: str, updates: dict[s
 
 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')
+    return hcom_path(FLAGS_DIR, f'{instance_name}.user_input')
 
 def wait_for_stop_exit(instance_name: str, max_wait: float = 0.2) -> int:
     """
     Wait for Stop hook to exit using flag file coordination.
     Returns wait time in ms.
-
     Strategy:
     1. Create flag file
     2. Wait for Stop hook to delete it (proof it exited)
@@ -3484,7 +3413,7 @@ def handle_userpromptsubmit(hook_data: dict[str, Any], instance_name: str, updat
     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
 
-    # Session_ended prevents user recieving messages(?) so reset it.
+    # Session_ended prevents user receiving messages(?) so reset it.
     if is_matched_resume and instance_data and instance_data.get('session_ended'):
         update_instance_position(instance_name, {'session_ended': False})
         instance_data['session_ended'] = False  # Resume path reactivates Stop hook polling
@@ -3533,10 +3462,7 @@ def handle_userpromptsubmit(hook_data: dict[str, Any], instance_name: str, updat
     # 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.]"
-
+            msg += "\n[HCOM Session resumed. Your alias and conversation history preserved.]"
     if msg:
         output = {
             "hookSpecificOutput": {
@@ -3549,47 +3475,58 @@ def handle_userpromptsubmit(hook_data: dict[str, Any], instance_name: str, updat
 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
+    if os.environ.get('HCOM_LAUNCHED') == '1':
+        parts = f"[HCOM is started, you can send messages with the command: {build_hcom_command()} send]"
+    else:
+        parts = f"[You can start HCOM with the command: {build_hcom_command()} start]"
 
-    # Build minimal context from environment
-    parts = ["[HCOM active]"]
+    output = {
+        "hookSpecificOutput": {
+            "hookEventName": "SessionStart",
+            "additionalContext": parts
+        }
+    }
 
-    if agent_type := os.environ.get('HCOM_SUBAGENT_TYPE'):
-        parts.append(f"[agent: {agent_type}]")
+    print(json.dumps(output))
 
-    if tag := os.environ.get('HCOM_TAG'):
-        parts.append(f"[tag: {tag}]")
+def handle_posttooluse(hook_data: dict[str, Any], instance_name: str) -> None:
+    """Handle PostToolUse hook - show launch context or bootstrap"""
+    command = hook_data.get('tool_input', {}).get('command', '')
+    instance_data = load_instance_position(instance_name)
 
-    help_text = " ".join(parts)
+    # Check for help or launch commands (combined pattern)
+    if re.search(r'\bhcom\s+(?:(?:help|--help|-h)\b|\d+)', command):
+        if not instance_data.get('launch_context_announced', False):
+            msg = build_launch_context(instance_name)
+            update_instance_position(instance_name, {'launch_context_announced': True})
 
-    # First time: no instance files or archives exist
-    is_first_time = not any(hcom_path().rglob('*.json'))
+            output = {
+                "hookSpecificOutput": {
+                    "hookEventName": "PostToolUse",
+                    "additionalContext": msg
+                }
+            }
+            print(json.dumps(output, ensure_ascii=False))
+        return
 
-    is_first_time = True
-    if is_first_time:
-        help_text += """
+    # Check HCOM_COMMAND_PATTERN for bootstrap (other hcom commands)
+    matches = list(re.finditer(HCOM_COMMAND_PATTERN, command))
 
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-  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
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    if not matches:
+        return
 
-"""
+    # Show bootstrap if not announced yet
+    if not instance_data.get('alias_announced', False):
+        msg = build_hcom_bootstrap_text(instance_name)
+        update_instance_position(instance_name, {'alias_announced': True})
 
-    output = {
-        "hookSpecificOutput": {
-            "hookEventName": "SessionStart",
-            "additionalContext": help_text
+        output = {
+            "hookSpecificOutput": {
+                "hookEventName": "PostToolUse",
+                "additionalContext": msg
+            }
         }
-    }
-
-    print(json.dumps(output))
+        print(json.dumps(output, ensure_ascii=False))
 
 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"""
@@ -3641,16 +3578,16 @@ def handle_hook(hook_type: str) -> None:
 
     if not ensure_hcom_directories():
         log_hook_error('handle_hook', Exception('Failed to create directories'))
-        sys.exit(EXIT_SUCCESS)
+        sys.exit(0)
 
     # SessionStart is standalone - no instance files
     if hook_type == 'sessionstart':
         handle_sessionstart(hook_data)
-        sys.exit(EXIT_SUCCESS)
+        sys.exit(0)
 
     # Vanilla instance check - exit early if should skip
     if should_skip_vanilla_instance(hook_type, hook_data):
-        sys.exit(EXIT_SUCCESS)
+        sys.exit(0)
 
     # Initialize instance context (creates file if needed, reuses existing if session_id matches)
     instance_name, updates, is_matched_resume = init_hook_context(hook_data, hook_type)
@@ -3666,11 +3603,13 @@ def handle_hook(hook_type: str) -> None:
                              not instance_data.get('alias_announced', False))
 
         if not skip_enabled_check and not instance_data.get('enabled', False):
-            sys.exit(EXIT_SUCCESS)
+            sys.exit(0)
 
     match hook_type:
         case 'pre':
             handle_pretooluse(hook_data, instance_name)
+        case 'post':
+            handle_posttooluse(hook_data, instance_name)
         case 'poll':
             handle_stop(hook_data, instance_name, updates, instance_data)
         case 'notify':
@@ -3680,7 +3619,7 @@ def handle_hook(hook_type: str) -> None:
         case 'sessionend':
             handle_sessionend(hook_data, instance_name, updates, instance_data)
 
-    sys.exit(EXIT_SUCCESS)
+    sys.exit(0)
 
 
 # ==================== Main Entry Point ====================
@@ -3693,18 +3632,19 @@ def main(argv: list[str] | None = None) -> int | None:
         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'):
+    if argv and argv[0] in ('poll', 'notify', 'pre', 'post', 'sessionstart', 'userpromptsubmit', 'sessionend'):
         handle_hook(argv[0])
         return 0
 
-    # Check for updates (CLI commands only, not hooks)
-    check_version_once_daily()
-
-    # Ensure directories exist
+    # Ensure directories exist first (required for version check cache)
     if not ensure_hcom_directories():
         print(format_error("Failed to create HCOM directories"), file=sys.stderr)
         return 1
 
+    # Check for updates and show message if available (once daily check, persists until upgrade)
+    if msg := get_update_notice():
+        print(msg, file=sys.stderr)
+
     # Ensure hooks current (warns but never blocks)
     ensure_hooks_current()