@suwujs/codex-vault 0.5.3 → 0.7.0

package/README.md

@@ -63,20 +63,20 @@ git commit (persistent)
 Next session → session-start hook injects context back
 ```
 
-Three hooks power the loop:
+Hooks power the loop:
 
-| Hook | When | What |
-|------|------|------|
-| **session-start** | Agent starts | Injects North Star goals, recent git changes, active work, vault file listing |
-| **classify-message** | Every message | Detects decisions, wins, project updates — hints the agent where to file them |
-| **validate-write** | After writing `.md` | Checks frontmatter and wikilinks — catches mistakes before they stick |
+| Hook | When | What | Claude Code | Codex CLI |
+|------|------|------|-------------|-----------|
+| **session-start** | Agent starts | Injects North Star goals, recent git changes, active work, vault file listing | SessionStart | SessionStart |
+| **classify-message** | Every message | Detects decisions, wins, project updates — hints the agent where to file them | UserPromptSubmit | UserPromptSubmit |
+| **validate-write** | After writing `.md` | Checks frontmatter and wikilinks — catches mistakes before they stick | PostToolUse (Write\|Edit) | N/A (Codex only supports Bash) |
 
 ## Supported Agents
 
 | Agent | Hooks | Skills | Status |
 |-------|-------|--------|--------|
 | Claude Code | 3 hooks via `.claude/settings.json` | `/dump` `/recall` `/ingest` `/wrap-up` | Full support |
-| Codex CLI | 3 hooks via `.codex/hooks.json` | `$dump` `$recall` `$ingest` `$wrap-up` | Full support |
+| Codex CLI | 2 hooks via `.codex/hooks.json` | `$dump` `$recall` `$ingest` `$wrap-up` | Full support (PostToolUse limited to Bash by Codex) |
 | Other | Write an adapter ([docs/adding-an-agent.md](docs/adding-an-agent.md)) | Depends on agent | Community |
 
 ## Vault Structure

package/README.zh-CN.md

@@ -95,20 +95,20 @@ git commit（持久化）
 下次 session → session-start hook 注入上下文
 ```
 
-三个 hook 驱动整个循环：
+Hook 驱动整个循环：
 
-| Hook | 触发时机 | 做什么 |
-|------|---------|--------|
-| **session-start** | Agent 启动 | 注入 North Star 目标、近期 git 变更、活跃项目、vault 文件清单 |
-| **classify-message** | 每条消息 | 检测决策、成果、项目更新 — 提示 agent 该归档到哪里 |
-| **validate-write** | 写 `.md` 后 | 检查 frontmatter 和 wikilinks — 在落盘前纠错 |
+| Hook | 触发时机 | 做什么 | Claude Code | Codex CLI |
+|------|---------|--------|-------------|-----------|
+| **session-start** | Agent 启动 | 注入 North Star 目标、近期 git 变更、活跃项目、vault 文件清单 | SessionStart | SessionStart |
+| **classify-message** | 每条消息 | 检测决策、成果、项目更新 — 提示 agent 该归档到哪里 | UserPromptSubmit | UserPromptSubmit |
+| **validate-write** | 写 `.md` 后 | 检查 frontmatter 和 wikilinks — 在落盘前纠错 | PostToolUse (Write\|Edit) | 不支持（Codex 仅支持 Bash） |
 
 ## 支持的 Agent
 
 | Agent | Hooks | Skills | 状态 |
 |-------|-------|--------|------|
 | Claude Code | `.claude/settings.json` 3 hooks | `/dump` `/recall` `/ingest` `/wrap-up` | 完整支持 |
-| Codex CLI | `.codex/hooks.json` 3 hooks | `$dump` `$recall` `$ingest` `$wrap-up` | 完整支持 |
+| Codex CLI | `.codex/hooks.json` 2 hooks | `$dump` `$recall` `$ingest` `$wrap-up` | 完整支持（PostToolUse 受 Codex 限制仅支持 Bash） |
 | 其他 | 写适配器（[指南](docs/adding-an-agent.md)） | 取决于 agent | 社区贡献 |
 
 ## Vault 结构

package/bin/codex-vault-run.sh

@@ -0,0 +1,28 @@
+#!/bin/bash
+# Codex-Vault wrapper — shows vault banner then launches Codex CLI
+# Usage: codex-vault-run [codex args...]
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PROJECT_DIR="$(pwd)"
+
+# Find session-start hook relative to project or plugin
+HOOK=""
+for candidate in \
+  "$PROJECT_DIR/plugin/hooks/codex/session-start.py" \
+  "$PROJECT_DIR/.codex-vault/hooks/codex/session-start.py" \
+  "$SCRIPT_DIR/../plugin/hooks/codex/session-start.py"; do
+  if [ -f "$candidate" ]; then
+    HOOK="$candidate"
+    break
+  fi
+done
+
+if [ -n "$HOOK" ]; then
+  SUMMARY=$(echo '{}' | python3 "$HOOK" 2>/dev/null \
+    | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('systemMessage',''))" 2>/dev/null)
+  if [ -n "$SUMMARY" ]; then
+    echo "  $SUMMARY"
+  fi
+fi
+
+exec codex "$@"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suwujs/codex-vault",
-  "version": "0.5.3",
+  "version": "0.7.0",
   "description": "Persistent knowledge vault for LLM agents (Claude Code, Codex CLI)",
   "license": "MIT",
   "repository": {

package/plugin/VERSION

@@ -1 +1 @@
-0.5.3
+0.6.0

package/plugin/hooks/{classify-message.py → claude/classify-message.py}

@@ -1,9 +1,8 @@
 #!/usr/bin/env python3
-"""Classify user messages and inject routing hints.
+"""Classify user messages and inject routing hints — Claude Code version.
 
 Lightweight version: 5 core signals + session-end vault integrity check.
-Agent-agnostic — outputs hookSpecificOutput compatible with both
-Claude Code and Codex CLI.
+Outputs hookSpecificOutput with systemMessage for Claude Code terminal display.
 """
 import json
 import os
@@ -87,8 +86,7 @@ def _match(patterns, text):
 
 def _find_vault_root():
     """Find vault root from CWD — check for Home.md/brain/, then vault/ subdir."""
-    cwd = os.environ.get("CLAUDE_PROJECT_DIR",
-           os.environ.get("CODEX_PROJECT_DIR", os.getcwd()))
+    cwd = os.environ.get("CLAUDE_PROJECT_DIR", os.getcwd())
     if os.path.isfile(os.path.join(cwd, "Home.md")) or os.path.isdir(os.path.join(cwd, "brain")):
         return cwd
     vault_sub = os.path.join(cwd, "vault")
@@ -281,7 +279,7 @@ def main():
             feedback_parts.append(f"{s['name']} → {s['skill']}")
         if is_session_end(prompt):
             feedback_parts.append("SESSION END → /wrap-up")
-        icon = "🔄" if mode == "auto" else "💡"
+        icon = "\U0001f504" if mode == "auto" else "\U0001f4a1"
         label = ", ".join(feedback_parts) if feedback_parts else "intent detected"
 
         # Hook trigger notification

package/plugin/hooks/{session-start.py → claude/session-start.py}

@@ -1,7 +1,6 @@
 #!/usr/bin/env python3
-"""Session-start hook — injects vault context into the agent's prompt.
+"""Session-start hook for Claude Code — injects vault context into the agent's prompt.
 
-Works with any agent that supports SessionStart hooks (Claude Code, Codex CLI).
 Outputs structured JSON: additionalContext for LLM, systemMessage for terminal.
 
 Dynamic context: adapts git log window, reads full North Star,
@@ -19,8 +18,7 @@ from pathlib import Path
 
 def _find_vault_root():
     """Find vault root from CWD — check for Home.md/brain/, then vault/ subdir."""
-    cwd = os.environ.get("CLAUDE_PROJECT_DIR",
-           os.environ.get("CODEX_PROJECT_DIR", os.getcwd()))
+    cwd = os.environ.get("CLAUDE_PROJECT_DIR", os.getcwd())
     if os.path.isfile(os.path.join(cwd, "Home.md")) or os.path.isdir(os.path.join(cwd, "brain")):
         return cwd
     vault_sub = os.path.join(cwd, "vault")
@@ -343,23 +341,6 @@ def _build_banner(vault_dir):
 # ── Main ───────────────────────────────────────────────────────────────
 
 
-def _detect_platform():
-    """Detect whether we're running under Claude Code or Codex CLI."""
-    if os.environ.get("CLAUDE_PROJECT_DIR"):
-        return "claude"
-    if os.environ.get("CODEX_PROJECT_DIR") or os.environ.get("CODEX_HOME"):
-        return "codex"
-    # Fallback: check parent process name
-    try:
-        ppid = os.getppid()
-        cmdline = Path(f"/proc/{ppid}/cmdline").read_text() if os.path.exists(f"/proc/{ppid}/cmdline") else ""
-        if "codex" in cmdline.lower():
-            return "codex"
-    except Exception:
-        pass
-    return "claude"  # default
-
-
 def main():
     vault_dir = _find_vault_root()
     if not vault_dir:
@@ -378,7 +359,6 @@ def main():
     except Exception:
         event = {}
 
-    platform = _detect_platform()
     context = _build_context(vault_dir)
     banner = _build_banner(vault_dir)
 
@@ -387,16 +367,9 @@ def main():
             "hookEventName": "SessionStart",
             "additionalContext": context
         },
+        "systemMessage": banner
     }
 
-    if platform == "claude":
-        # Claude Code renders systemMessage in terminal
-        output["systemMessage"] = banner
-    else:
-        # Codex CLI: systemMessage not rendered by TUI,
-        # use stderr for terminal visibility (best effort)
-        sys.stderr.write(banner + "\n")
-
     json.dump(output, sys.stdout)
     sys.stdout.flush()
     sys.exit(0)

package/{vault/.codex-vault/hooks → plugin/hooks/claude}/validate-write.py

@@ -1,9 +1,8 @@
 #!/usr/bin/env python3
-"""Post-write validation for vault notes.
+"""Post-write validation for vault notes — Claude Code version.
 
 Checks frontmatter and wikilinks on any .md file written to the vault.
-Agent-agnostic — outputs hookSpecificOutput compatible with both
-Claude Code and Codex CLI.
+Outputs hookSpecificOutput with systemMessage for Claude Code terminal display.
 """
 import json
 import re
@@ -97,9 +96,9 @@ def main():
         count = len(warnings)
         first = warnings[0]
         if count == 1:
-            feedback = f"⚠️  vault: {basename} — {first}"
+            feedback = f"\u26a0\ufe0f  vault: {basename} — {first}"
         else:
-            feedback = f"⚠️  vault: {basename} — {first} (+{count - 1} more)"
+            feedback = f"\u26a0\ufe0f  vault: {basename} — {first} (+{count - 1} more)"
 
         # Hook trigger notification
         print(f"  {feedback}")

package/plugin/hooks/codex/classify-message.py

@@ -0,0 +1,303 @@
+#!/usr/bin/env python3
+"""Classify user messages and inject routing hints — Codex CLI version.
+
+Lightweight version: 5 core signals + session-end vault integrity check.
+Outputs hookSpecificOutput for Codex CLI. Feedback via stderr
+(Codex CLI does not render systemMessage).
+"""
+import json
+import os
+import subprocess
+import sys
+import re
+from pathlib import Path
+
+
+SIGNALS = [
+    {
+        "name": "DECISION",
+        "skill": "/dump",
+        "message": "DECISION detected — suggest the user run /dump to capture this decision",
+        "auto_message": "DECISION detected — execute /dump now to capture this decision from the user's message",
+        "patterns": [
+            "decided", "deciding", "decision", "we chose", "agreed to",
+            "let's go with", "the call is", "we're going with",
+        ],
+    },
+    {
+        "name": "WIN",
+        "skill": "/dump",
+        "message": "WIN detected — suggest the user run /dump to record this achievement",
+        "auto_message": "WIN detected — execute /dump now to record this achievement from the user's message",
+        "patterns": [
+            "achieved", "won", "praised",
+            "kudos", "shoutout", "great feedback", "recognized",
+        ],
+    },
+    {
+        "name": "PROJECT UPDATE",
+        "skill": "/dump",
+        "message": "PROJECT UPDATE detected — suggest the user run /dump to log this progress",
+        "auto_message": "PROJECT UPDATE detected — execute /dump now to log this progress from the user's message",
+        "patterns": [
+            "project update", "sprint", "milestone",
+            "shipped", "shipping", "launched", "launching",
+            "completed", "completing", "released", "releasing",
+            "deployed", "deploying",
+            "went live", "rolled out", "merged", "cut the release",
+        ],
+    },
+    {
+        "name": "QUERY",
+        "skill": "/recall",
+        "message": "QUERY detected — suggest the user run /recall to check existing knowledge first",
+        "auto_message": "QUERY detected — execute /recall now to search vault for relevant information before answering",
+        "patterns": [
+            "what is", "how does", "why did", "compare", "analyze",
+            "explain the", "what's the difference", "summarize the",
+            "relationship between",
+        ],
+    },
+    {
+        "name": "INGEST",
+        "skill": "/ingest",
+        "message": "INGEST detected — suggest the user run /ingest to process the source",
+        "auto_message": "INGEST detected — execute /ingest now to process the source from the user's message",
+        "patterns": [
+            "ingest", "process this", "read this article",
+            "summarize this", "new source", "clip this", "web clip",
+        ],
+    },
+]
+
+SESSION_END_PATTERNS = [
+    "wrap up", "wrapping up", "that's all", "that's it",
+    "done for now", "done for today", "i'm done", "call it a day",
+    "end session", "bye", "goodbye", "good night", "see you",
+    "结束", "收工", "今天到这", "就这样",
+]
+
+
+def _match(patterns, text):
+    for phrase in patterns:
+        if re.search(r'(?<![a-zA-Z])' + re.escape(phrase) + r'(?![a-zA-Z])', text):
+            return True
+    return False
+
+
+def _find_vault_root():
+    """Find vault root from CWD — check for Home.md/brain/, then vault/ subdir."""
+    cwd = os.environ.get("CODEX_PROJECT_DIR", os.getcwd())
+    if os.path.isfile(os.path.join(cwd, "Home.md")) or os.path.isdir(os.path.join(cwd, "brain")):
+        return cwd
+    vault_sub = os.path.join(cwd, "vault")
+    if os.path.isdir(vault_sub) and (
+        os.path.isfile(os.path.join(vault_sub, "Home.md")) or
+        os.path.isdir(os.path.join(vault_sub, "brain"))
+    ):
+        return vault_sub
+    return None
+
+
+def _read_mode():
+    """Read classify mode from vault config. Default: suggest."""
+    vault_root = _find_vault_root()
+    if not vault_root:
+        return "suggest"
+    config_path = os.path.join(vault_root, ".codex-vault", "config.json")
+    try:
+        with open(config_path) as f:
+            config = json.load(f)
+        mode = config.get("classify_mode", "suggest")
+        if mode in ("suggest", "auto"):
+            return mode
+    except (OSError, ValueError, KeyError):
+        pass
+    return "suggest"
+
+
+def _get_changed_files(vault_root):
+    """Get list of changed/new .md files relative to vault root."""
+    files = set()
+    try:
+        # Staged + unstaged changes
+        result = subprocess.run(
+            ["git", "diff", "--name-only", "HEAD"],
+            capture_output=True, text=True, cwd=vault_root, timeout=5,
+        )
+        for f in result.stdout.strip().splitlines():
+            if f.endswith(".md"):
+                files.add(f)
+
+        # Untracked files
+        result = subprocess.run(
+            ["git", "ls-files", "--others", "--exclude-standard"],
+            capture_output=True, text=True, cwd=vault_root, timeout=5,
+        )
+        for f in result.stdout.strip().splitlines():
+            if f.endswith(".md"):
+                files.add(f)
+    except Exception:
+        pass
+    return files
+
+
+def _check_vault_integrity(vault_root):
+    """Check for common memory-write omissions."""
+    warnings = []
+    changed = _get_changed_files(vault_root)
+    if not changed:
+        return warnings
+
+    # Check 1: New work notes but Index.md not updated
+    new_work = [f for f in changed if f.startswith("work/active/") and f != "work/Index.md"]
+    index_updated = "work/Index.md" in changed
+    if new_work and not index_updated:
+        names = ", ".join(os.path.basename(f).replace(".md", "") for f in new_work)
+        warnings.append(f"New work notes ({names}) but work/Index.md not updated")
+
+    # Check 2: Decision content written but brain/Key Decisions.md not updated
+    decision_keywords = ["decided", "decision", "agreed to", "we chose", "the call is"]
+    brain_decisions_updated = "brain/Key Decisions.md" in changed
+    if not brain_decisions_updated:
+        for f in changed:
+            if f.endswith(".md") and not f.startswith("brain/"):
+                try:
+                    content = Path(os.path.join(vault_root, f)).read_text(encoding="utf-8").lower()
+                    if any(kw in content for kw in decision_keywords):
+                        warnings.append(
+                            f"'{f}' contains decision content but brain/Key Decisions.md not updated"
+                        )
+                        break
+                except Exception:
+                    pass
+
+    # Check 3: Pattern content written but brain/Patterns.md not updated
+    pattern_keywords = ["pattern", "convention", "always do", "never do", "recurring"]
+    brain_patterns_updated = "brain/Patterns.md" in changed
+    if not brain_patterns_updated:
+        for f in changed:
+            if f.endswith(".md") and not f.startswith("brain/"):
+                try:
+                    content = Path(os.path.join(vault_root, f)).read_text(encoding="utf-8").lower()
+                    if any(kw in content for kw in pattern_keywords):
+                        warnings.append(
+                            f"'{f}' contains pattern content but brain/Patterns.md not updated"
+                        )
+                        break
+                except Exception:
+                    pass
+
+    # Check 4: operation log not updated after significant changes
+    log_updated = "log.md" in changed
+    significant_changes = len([f for f in changed
+                               if f.startswith(("work/", "reference/", "brain/"))]) >= 2
+    if significant_changes and not log_updated:
+        warnings.append("Multiple vault changes but log.md not updated")
+
+    return warnings
+
+
+def classify(prompt, mode="suggest"):
+    p = prompt.lower()
+    key = "auto_message" if mode == "auto" else "message"
+    return [s[key] for s in SIGNALS if _match(s["patterns"], p)]
+
+
+def is_session_end(prompt):
+    p = prompt.lower()
+    return _match(SESSION_END_PATTERNS, p)
+
+
+def main():
+    try:
+        input_data = json.load(sys.stdin)
+    except (ValueError, EOFError, OSError):
+        sys.exit(0)
+
+    prompt = input_data.get("prompt", "")
+    if not isinstance(prompt, str) or not prompt:
+        sys.exit(0)
+
+    signal_messages = []
+    session_end_messages = []
+
+    try:
+        mode = _read_mode()
+
+        # Regular signal classification
+        signals = classify(prompt, mode)
+        signal_messages.extend(signals)
+
+        # Session-end check (always suggest mode — never auto-execute wrap-up)
+        if is_session_end(prompt):
+            vault_root = _find_vault_root()
+            if vault_root:
+                integrity_warnings = _check_vault_integrity(vault_root)
+                if integrity_warnings:
+                    session_end_messages.append(
+                        "SESSION END — vault integrity check found issues:\n"
+                        + "\n".join(f"  - {w}" for w in integrity_warnings)
+                        + "\nFix these before wrapping up."
+                    )
+                else:
+                    session_end_messages.append("SESSION END — vault integrity check passed.")
+    except Exception:
+        sys.exit(0)
+
+    parts = []
+
+    if signal_messages:
+        hints = "\n".join(f"- {s}" for s in signal_messages)
+        if mode == "auto":
+            parts.append(
+                "Auto-execute the following skills based on user intent:\n"
+                + hints
+                + "\n\nExecute the skill immediately with the user's message as input. Do not ask for confirmation."
+            )
+        else:
+            parts.append(
+                "Skill suggestions (do NOT auto-execute — suggest the skill to the user and let them decide):\n"
+                + hints
+                + "\n\nWait for the user to invoke the skill. Do not create vault notes without explicit user action."
+            )
+
+    if session_end_messages:
+        hints = "\n".join(f"- {s}" for s in session_end_messages)
+        parts.append(
+            "Skill suggestions (do NOT auto-execute — suggest the skill to the user and let them decide):\n"
+            + hints
+            + "\n\nWait for the user to invoke the skill. Do not create vault notes without explicit user action."
+        )
+
+    if parts:
+        context = "\n\n".join(parts)
+
+        # Build feedback label
+        matched = [s for s in SIGNALS if _match(s["patterns"], prompt.lower())]
+        feedback_parts = []
+        for s in matched:
+            feedback_parts.append(f"{s['name']} → {s['skill']}")
+        if is_session_end(prompt):
+            feedback_parts.append("SESSION END → /wrap-up")
+        icon = "\U0001f504" if mode == "auto" else "\U0001f4a1"
+        label = ", ".join(feedback_parts) if feedback_parts else "intent detected"
+
+        # hookSpecificOutput + additionalContext → injected into LLM context
+        output = {
+            "hookSpecificOutput": {
+                "hookEventName": "UserPromptSubmit",
+                "additionalContext": context
+            }
+        }
+        sys.stdout.write(json.dumps(output) + "\n")
+        sys.stdout.flush()
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except Exception:
+        sys.exit(0)