feat(msg): add Phase A - prompt detection, hooks, watcher refinement

- Add prompt-empty detection (Claude ❯, Codex ›) to avoid
  typing into panes where user is mid-input
- Consolidated msg-hook CLI for Stop + UserPromptSubmit hooks
  (replaces old stop_hook.py)
- Revised watcher: quick idle check, prompt detection,
  only injects when idle+empty, releases for busy/typing
- Add /msg:inbox slash command for plugin-based notification
- Add msg plugin to marketplace.json
- Add --local flag for project-local DB (sandbox fallback)
- Helpful error message when sandbox blocks ~/.msg/ writes
- Watcher uses /msg:inbox (Claude) and /prompts:inbox (Codex)
- 39 tests passing

Ref: docs/msg-phase-a-plan.md, docs/msg-plan-v2.md

Author: pchalasani

.claude-plugin/marketplace.json

@@ -34,6 +34,11 @@
       "name": "voice",
       "source": "./plugins/voice",
       "description": "Audio feedback when Claude Code agent completes tasks using pocket-tts"
+    },
+    {
+      "name": "msg",
+      "source": "./plugins/msg",
+      "description": "Inter-agent communication for Claude Code and Codex CLI sessions via threads and messages"
     }
   ]
 }

claude_code_tools/msg/cli.py

@@ -10,11 +10,47 @@
 import click
 
 from .models import AgentKind
-from .store import MsgStore, DEFAULT_DB_PATH
+from .store import MsgStore, DEFAULT_DB_PATH, DEFAULT_DB_DIR
 
 
-def _get_store(db_path: str | None = None) -> MsgStore:
-    return MsgStore(db_path or DEFAULT_DB_PATH)
+def _check_db_writable(db_dir: str) -> bool:
+    """Check if we can write to the DB directory."""
+    from pathlib import Path
+    try:
+        Path(db_dir).mkdir(parents=True, exist_ok=True)
+        test_file = os.path.join(db_dir, ".write_test")
+        with open(test_file, "w") as f:
+            f.write("test")
+        os.remove(test_file)
+        return True
+    except OSError:
+        return False
+
+
+def _get_local_db_path() -> str:
+    """Get project-local DB path."""
+    try:
+        result = subprocess.run(
+            ["git", "rev-parse", "--show-toplevel"],
+            capture_output=True, text=True, timeout=5,
+        )
+        if result.returncode == 0:
+            root = result.stdout.strip()
+            return os.path.join(root, ".msg", "msg.db")
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        pass
+    return os.path.join(os.getcwd(), ".msg", "msg.db")
+
+
+def _get_store(
+    db_path: str | None = None,
+    local: bool = False,
+) -> MsgStore:
+    if db_path:
+        return MsgStore(db_path)
+    if local:
+        return MsgStore(_get_local_db_path())
+    return MsgStore(DEFAULT_DB_PATH)
 
 
 def _detect_tmux_pane() -> str | None:
@@ -193,16 +229,50 @@ def _ensure_watcher_running(store: MsgStore) -> None:
 @click.group()
 @click.option(
     "--db", default=None,
-    help="Path to msg database (default: ~/.msg/msg.db)",
+    help="Path to msg database",
+)
+@click.option(
+    "--local", is_flag=True, default=False,
+    help="Use project-local DB instead of global ~/.msg/",
 )
 @click.pass_context
-def cli(ctx: click.Context, db: str | None) -> None:
+def cli(
+    ctx: click.Context,
+    db: str | None,
+    local: bool,
+) -> None:
     """msg: Inter-agent communication for coding agents."""
     ctx.ensure_object(dict)
-    store = _get_store(db)
+
+    # If no explicit path, check if global DB is writable
+    if not db and not local:
+        if not _check_db_writable(DEFAULT_DB_DIR):
+            home = os.path.expanduser("~")
+            click.echo(
+                "Cannot write to ~/.msg/ "
+                "(sandbox restriction).\n\n"
+                "Ask the user which option they prefer:\n\n"
+                "Option A: Global messaging "
+                "(agents across any project can talk)\n"
+                "  User needs to add to "
+                "~/.codex/config.toml:\n"
+                "    [sandbox_workspace_write]\n"
+                f'    writable_roots = ["{home}/.msg"]\n'
+                "  Then restart Codex.\n\n"
+                "Option B: Local messaging "
+                "(this project only)\n"
+                "  Works immediately, no config "
+                "changes needed.\n\n"
+                "If user chooses B, re-run the same "
+                "command with --local flag prepended "
+                "after 'msg', e.g.: "
+                "msg --local register <name>",
+                err=True,
+            )
+            sys.exit(1)
+
+    store = _get_store(db=db, local=local)
     ctx.obj["store"] = store
-    # Auto-start watcher if not running
-    # (skip if the command itself is 'watch' to avoid loop)
     if ctx.invoked_subcommand != "watch":
         _ensure_watcher_running(store)
 

claude_code_tools/msg/hooks.py

@@ -0,0 +1,146 @@
+"""Hook commands for msg inter-agent communication.
+
+Provides Stop and UserPromptSubmit hooks that check
+for unread messages and inject notifications into the
+agent's context. Used by both Claude Code and Codex CLI.
+
+Both hooks use the same claim protocol as the watcher
+to prevent double-notification.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+
+import click
+
+from .models import _new_uuid
+from .store import MsgStore
+
+
+def _find_self_agent(store: MsgStore) -> object | None:
+    """Find the agent registered for this pane."""
+    pane_id = os.environ.get("TMUX_PANE")
+    if not pane_id:
+        return None
+
+    try:
+        result = subprocess.run(
+            ["tmux", "display-message",
+             "-t", pane_id,
+             "-p", "#{session_name}"],
+            capture_output=True, text=True, timeout=5,
+        )
+        tmux_session = result.stdout.strip()
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        return None
+
+    if not tmux_session:
+        return None
+
+    agents = store.list_agents(tmux_session=tmux_session)
+    for a in agents:
+        if a.pane_id == pane_id:
+            return a
+    return None
+
+
+def _check_and_notify(
+    hook_event: str,
+) -> None:
+    """Common logic for both Stop and UserPromptSubmit.
+
+    Reads JSON from stdin, checks DB for unread messages,
+    claims deliveries, outputs JSON response.
+    """
+    # Read hook input
+    try:
+        hook_input = json.load(sys.stdin)
+    except (json.JSONDecodeError, EOFError):
+        hook_input = {}
+
+    try:
+        store = MsgStore()
+    except Exception:
+        _approve()
+        return
+
+    me = _find_self_agent(store)
+    if not me:
+        _approve()
+        return
+
+    # Check for unread messages
+    messages = store.get_inbox(me.session_id)
+    if not messages:
+        _approve()
+        return
+
+    # Claim deliveries (same protocol as watcher)
+    claimer_id = f"hook-{hook_event}-{_new_uuid()[:8]}"
+    claimed = store.claim_pending_deliveries(claimer_id)
+
+    # Filter to our deliveries only
+    our_claims = [
+        d for d in claimed
+        if d["recipient_id"] == me.session_id
+    ]
+
+    # Build notification
+    count = len(messages)
+    senders = list(dict.fromkeys(
+        m.get("from_name", "unknown") for m in messages
+    ))
+    sender_str = ", ".join(senders)
+    notification = (
+        f"[MSG] {count} unread message(s) "
+        f"from {sender_str}. "
+        f"Run msg inbox when ready."
+    )
+
+    # Mark claimed as notified
+    for d in our_claims:
+        store.mark_notified(d["id"])
+
+    # Output with additionalContext
+    print(json.dumps({
+        "hookSpecificOutput": {
+            "hookEventName": hook_event,
+            "additionalContext": notification,
+        }
+    }))
+
+
+def _approve() -> None:
+    """Output a simple approve response."""
+    print(json.dumps({"decision": "approve"}))
+
+
+@click.group()
+def cli() -> None:
+    """msg-hook: Hook commands for msg notifications."""
+    pass
+
+
+@cli.command()
+def stop() -> None:
+    """Stop hook — check inbox when agent stops."""
+    _check_and_notify("Stop")
+
+
+@cli.command("prompt-submit")
+def prompt_submit() -> None:
+    """UserPromptSubmit hook — check inbox on user input."""
+    _check_and_notify("UserPromptSubmit")
+
+
+def main() -> None:
+    """Entry point for msg-hook CLI."""
+    cli()
+
+
+if __name__ == "__main__":
+    main()

claude_code_tools/msg/prompt_detect.py

@@ -0,0 +1,108 @@
+"""Detect whether a tmux pane's prompt is empty or has text.
+
+Used by the watcher to decide if it's safe to type a
+slash command into the pane, or if the user is mid-typing.
+"""
+
+from __future__ import annotations
+
+import re
+import subprocess
+from enum import Enum
+
+
+class PromptState(str, Enum):
+    """State of an agent's input prompt."""
+
+    EMPTY = "empty"          # Prompt visible, no user text
+    HAS_TEXT = "has_text"    # User is typing something
+    UNKNOWN = "unknown"      # Can't determine
+
+# Prompt patterns: regex matching an empty prompt line.
+# The key is agent_kind, value is a compiled regex.
+# These match the prompt character with optional
+# whitespace and nothing else after it.
+PROMPT_PATTERNS: dict[str, re.Pattern] = {
+    "claude": re.compile(
+        r"^\s*[❯>]\s*$"
+    ),
+    "codex": re.compile(
+        r"^\s*[›>]\s*$"
+    ),
+}
+
+# Patterns for a prompt with text after it
+PROMPT_WITH_TEXT_PATTERNS: dict[str, re.Pattern] = {
+    "claude": re.compile(
+        r"^\s*[❯>]\s+.+"
+    ),
+    "codex": re.compile(
+        r"^\s*[›>]\s+.+"
+    ),
+}
+
+
+def detect_prompt_state(
+    pane_target: str,
+    agent_kind: str = "claude",
+) -> PromptState:
+    """Check if a tmux pane's prompt is empty.
+
+    Args:
+        pane_target: tmux pane identifier
+            (e.g., "cctools:1.4" or "%12")
+        agent_kind: "claude" or "codex"
+
+    Returns:
+        PromptState indicating the prompt state.
+    """
+    lines = _capture_last_lines(pane_target)
+    if not lines:
+        return PromptState.UNKNOWN
+
+    empty_pattern = PROMPT_PATTERNS.get(agent_kind)
+    text_pattern = PROMPT_WITH_TEXT_PATTERNS.get(
+        agent_kind,
+    )
+
+    if not empty_pattern:
+        return PromptState.UNKNOWN
+
+    # Scan all captured lines for prompt patterns.
+    # The prompt may be surrounded by decorative lines
+    # (separators, status bars, etc.) so we check all
+    # lines, not just the last non-empty one.
+    for line in reversed(lines):
+        stripped = line.rstrip()
+        if not stripped:
+            continue
+        if empty_pattern.match(stripped):
+            return PromptState.EMPTY
+        if text_pattern and text_pattern.match(stripped):
+            return PromptState.HAS_TEXT
+
+    return PromptState.UNKNOWN
+
+
+def _capture_last_lines(
+    pane_target: str,
+    count: int = 15,
+) -> list[str]:
+    """Capture the last N lines from a tmux pane."""
+    try:
+        result = subprocess.run(
+            [
+                "tmux", "capture-pane",
+                "-t", pane_target,
+                "-p",  # print to stdout
+            ],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        if result.returncode != 0:
+            return []
+        all_lines = result.stdout.splitlines()
+        return all_lines[-count:] if all_lines else []
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        return []

claude_code_tools/msg/store.py

@@ -19,7 +19,10 @@
     _now_iso,
 )
 
-DEFAULT_DB_DIR = os.path.expanduser("~/.msg")
+DEFAULT_DB_DIR = os.environ.get(
+    "MSG_DB_DIR",
+    os.path.expanduser("~/.msg"),
+)
 DEFAULT_DB_PATH = os.path.join(DEFAULT_DB_DIR, "msg.db")
 
 SCHEMA_SQL = """