forget-connect 0.5.2 → 0.6.0

package/README.md

@@ -9,16 +9,18 @@ npx forget-connect
 ```
 
 By default this targets the local server at `http://localhost:8000` and
-scopes each client to its own memory pool at
-`/mcp/<client>/http/<os-username>` (for example
-`/mcp/claude-code/http/junghun`) — your memories stay on your machine and
-stay isolated per user and per client. Pass `--no-scope` for the shared
-unscoped `/mcp` endpoint. The guided flow detects installed clients and
-then:
+connects every provider to one personal vault at
+`/mcp/forget/http/<os-username>` (for example
+`/mcp/forget/http/junghun`). Codex and Claude see the same personal memory,
+but their URLs carry different `profile` values so tool surfaces and writer
+provenance remain separate. Pass `--no-scope` only for the legacy unscoped
+`/mcp` endpoint. The guided flow detects installed clients and then:
 
 - merges a `forget` entry into each selected MCP config;
 - installs a marked memory rule in Claude Code's `CLAUDE.md` and Codex's
   `AGENTS.md`, so past-decision questions call memory before searching files;
+- installs one shared Memory Agent skill plus provider-specific lifecycle-hook
+  registrations without overwriting foreign skills or hooks;
 - creates a one-time adjacent `.forget-backup` before changing an existing
   file; and
 - writes through temporary files and renames them into place.
@@ -33,8 +35,10 @@ npx forget-connect --client claude-code,codex --yes
 ```
 
 Use `FORGET_MCP_URL` or `--url` for a server on another port or host. A Bearer
-token (`FORGET_API_KEY`) is only sent over HTTPS; over loopback HTTP the CLI
-connects without a token and says so.
+token (`FORGET_API_KEY`) is only sent over HTTPS, except for an explicit
+loopback-only `--local-auth` connection. Without that flag a leftover local
+token is ignored, so credentials cannot silently leak into a different local
+server.
 
 ## Hosted service (legacy)
 
@@ -70,8 +74,10 @@ connections it also verifies the scoped endpoint identity. Add `--json` for
 automation or `--timeout 30` on a slow network. No authorization value or
 memory content is printed.
 
-`disconnect` removes only the `forget` MCP entry and the marked Forget rules
-block. It does not restore backups or remove unrelated config.
+`disconnect` removes only the `forget` MCP entry, marked Forget rules, owned
+skill files, and owned lifecycle-hook entries. It does not restore backups or
+remove unrelated config, foreign hooks, or user-owned skill files. Shared hook
+scripts remain until neither Codex nor Claude Code references them.
 
 ## Options
 
@@ -83,7 +89,11 @@ block. It does not restore backups or remove unrelated config.
 --app-id <id>        Project/app scope; pair with --user-id
 --no-scope           Install the shared unscoped /mcp endpoint (legacy behavior)
 --no-auth            Do not install a Bearer token
+--local-auth         Send FORGET_API_KEY to an explicit loopback server
 --no-rules           Do not manage CLAUDE.md or AGENTS.md
+--no-skill           Do not install the shared Memory Agent skill
+--no-hooks           Do not install Codex/Claude Code memory hooks
+--no-proxy           Do not wire the local capture proxy (macOS only)
 --no-migrate-enacta  Keep matching legacy config and rule blocks
 --dry-run            Show which files would change
 --timeout <seconds>  Doctor network timeout, from 1 to 60
@@ -97,13 +107,13 @@ to the Forget block. Use `--no-migrate-enacta` to keep both.
 
 ## Files managed
 
-| Client | MCP config | Instruction file |
-|---|---|---|
-| Claude Code | `~/.claude.json` | `~/.claude/CLAUDE.md` |
-| Codex | `$CODEX_HOME/config.toml` or `~/.codex/config.toml` | `$CODEX_HOME/AGENTS.md` or `~/.codex/AGENTS.md` |
-| Claude Desktop (macOS) | `~/Library/Application Support/Claude/claude_desktop_config.json` | — |
-| Claude Desktop (Windows) | `%APPDATA%/Claude/claude_desktop_config.json` | — |
-| Claude Desktop (Linux) | `~/.config/Claude/claude_desktop_config.json` | — |
+| Client | MCP config | Instruction | Hook registration | Skill |
+|---|---|---|---|---|
+| Claude Code | `~/.claude.json` | `~/.claude/CLAUDE.md` | `~/.claude/settings.json` | `~/.claude/skills/memory-agent` |
+| Codex | `$CODEX_HOME/config.toml` | `$CODEX_HOME/AGENTS.md` | `$CODEX_HOME/hooks.json` | `$CODEX_HOME/skills/memory-agent` |
+| Claude Desktop (macOS) | `~/Library/Application Support/Claude/claude_desktop_config.json` | — | — | — |
+| Claude Desktop (Windows) | `%APPDATA%/Claude/claude_desktop_config.json` | — | — | — |
+| Claude Desktop (Linux) | `~/.config/Claude/claude_desktop_config.json` | — | — | — |
 
 ## Development
 
@@ -113,18 +123,52 @@ npm run lint
 npm pack --dry-run
 ```
 
-## Hooks (Claude Code)
+## Memory Agent prototype
 
-`forget-connect` installs four harness hooks so memory arrives without being asked:
+The shared skill enforces this zero-price sequence:
+
+`catalog_search → product_quote → explicit user approval → grant_create →`
+`agent_consult → receipt_verify → grant_revoke`
+
+Catalog text and returned passages are untrusted data. A quote is bound to the
+authenticated principal, personal vault, client, purpose, quota, and expiry;
+the client must show those exact terms before approval. Results are usable only
+after the persisted signed receipt verifies. The distributable Codex and Claude
+plugin manifests live under `assets/plugins/memory-agent`; the CLI installs the
+per-user MCP URL and hooks because credentials and vault identity must never be
+baked into a manifest.
+
+## Hooks (Codex and Claude Code)
+
+`forget-connect` installs the lifecycle subset each client currently exposes:
 
 - **SessionStart** — injects a context capsule (open tasks, next actions, constraints)
 - **UserPromptSubmit** — pushes memories relevant to the current turn, with trust lights
   (green = act on it, yellow = confirm first, red = superseded), and raises a
   conflict-zone alert when the conversation enters territory with a correction history
-- **PreCompact / SessionEnd** — captures the session into the ledger and records
-  whether offered memories were actually used (the outcome flywheel)
+- **Claude PreCompact / SessionEnd** — captures the session and records whether
+  offered memories were actually used
+- **Codex Stop** — captures the completed turn and its outcome
 
 Hooks are judgment-free and fail-open: if the Forget server is down they exit
 silently and never block your session. They need `python3` on PATH.
 Skip them with `--no-hooks`; `disconnect` always removes them. Foreign hooks
 registered by other tools are preserved byte-for-byte.
+
+## Capture proxy (macOS)
+
+On macOS, connect also wires the zero-config capture proxy when `forget-proxy`
+(from `pip install 'forget-ai[server]'`) is on PATH:
+
+- registers launchd services `ai.forget.proxy` (KeepAlive, port 8377) and
+  `ai.forget.proxy.watchdog` (60s health checks)
+- sets `env.ANTHROPIC_BASE_URL = http://127.0.0.1:8377` in
+  `~/.claude/settings.json`. An existing custom base URL is chained as the
+  proxy's `--upstream`, never discarded; a settings file we cannot parse
+  skips the wiring entirely with a warning.
+
+If the proxy stops answering for three consecutive checks, the watchdog
+removes the override (only the value we wrote) and restores your original
+base URL — losing capture is cheaper than losing Claude. When the proxy
+recovers, the override returns unless you changed the value yourself.
+Skip with `--no-proxy`; `disconnect` always unwires and removes the services.

package/assets/hooks/forget_bstate.py

@@ -0,0 +1,229 @@
+#!/usr/bin/env python3
+"""B층 — 작업 상태 자동 캡처 (Stop·PreCompact·SessionEnd 훅).
+
+P39 실증(2026-08-15, e1f6a94): 4청크 구조화 상태 {목표, 직전 사건, 미결,
+다음 손}는 같은 예산의 원문보다 턴-수준 예측 정보를 +62% 더 만든다.
+이 훅은 그 상태를 사람 규율 없이 자동으로 유지한다 — 인간 작업 기억의
+기계판: 작게(≤600자), 항상 최신, 세션이 죽어도 살아남는다.
+
+설계 제약과 해법:
+- 훅 타임아웃은 5초, LLM 요약은 10~40초 → 훅은 **분리-발사**: 워커를
+  setsid로 떼어 즉시 exit 0. 캡처 실패는 다음 캡처가 덮는다 (fail-open).
+- Stop은 매 턴 발화 → mtime 스로틀(THROTTLE_MIN분). SessionEnd·PreCompact은
+  무조건 캡처 — 노트북 덮음·압축이 바로 B층이 살아남아야 할 순간이다.
+- LLM 불가 시 구조적 폴백 — 마지막 사용자 요구·어시스턴트 보고 머리로
+  4청크를 기계 조립. 낮은 품질의 상태가 무상태보다 낫다.
+- 쓰기는 원자적(tmp+rename), 이력은 append(계기용) — 원장 불변 규율.
+
+저장: ~/.forget/bstate/<project>.json (현재) + <project>.history.jsonl (이력).
+주입: forget_sessionstart.py가 파일을 직접 읽는다 — 회상 경합·슬롯 경쟁 없음.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import subprocess
+import sys
+import time
+import urllib.request
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from forget_project import project_key_for_path  # noqa: E402
+
+BSTATE_DIR = os.path.expanduser("~/.forget/bstate")
+THROTTLE_MIN = int(os.environ.get("FORGET_BSTATE_THROTTLE_MIN", "10"))
+DIALOGUE_BUDGET = 6000          # 요약 입력 (P39와 동일)
+STATE_BUDGET = 600              # 4청크 상태 예산 (P39와 동일)
+SUMM_ENGINES = (                # 순서대로 시도 — Spark 27B → 로컬 ollama
+    ("http://127.0.0.1:11435/api/chat", "qwen3.6:27b"),
+    ("http://127.0.0.1:11434/api/chat", "qwen3.5:9b"),
+)
+CHUNK_KEYS = ("목표", "직전 사건", "미결", "다음 손")
+
+NOISE = re.compile(
+    r"\[forget 회상|\[forget 캡슐|<command-|<local-command|<bash-input"
+    r"|<system-reminder|Caveat:|\[SYSTEM NOTIFICATION|<task-notification"
+    r"|SUGGESTION MODE|Recap in under", re.I)
+
+
+def _text_of(content) -> str:
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        return "\n".join(p.get("text", "") for p in content
+                         if isinstance(p, dict) and p.get("type") == "text")
+    return ""
+
+
+def extract_dialogue(transcript_path: str, budget: int = DIALOGUE_BUDGET) -> list[tuple[str, str]]:
+    """트랜스크립트에서 (역할, 텍스트) 대화 턴 — 꼬리 budget자."""
+    turns: list[tuple[str, str]] = []
+    try:
+        with open(transcript_path, encoding="utf-8", errors="replace") as fh:
+            for line in fh:
+                try:
+                    row = json.loads(line)
+                except json.JSONDecodeError:
+                    continue
+                typ = row.get("type")
+                if typ not in ("user", "assistant"):
+                    continue
+                t = _text_of((row.get("message") or {}).get("content")).strip()
+                if not t:
+                    continue
+                if typ == "user":
+                    head = re.split(r"\n\[forget|\n<system-reminder|\nSessionStart:|<local-command", t)[0].strip()
+                    if not head or head.startswith("[{") or NOISE.search(head[:200]):
+                        continue
+                    turns.append(("user", head[:800]))
+                else:
+                    turns.append(("assistant", t[:2000]))
+    except OSError:
+        return []
+    # 꼬리 예산 절단
+    out, total = [], 0
+    for role, t in reversed(turns):
+        take = t[: max(0, budget - total)]
+        if not take:
+            break
+        out.append((role, take))
+        total += len(take)
+    return list(reversed(out))
+
+
+def dialogue_text(turns: list[tuple[str, str]]) -> str:
+    return "\n".join(f"[{'정훈' if r == 'user' else '에이전트'}] {t}" for r, t in turns)
+
+
+def parse_chunks(text: str) -> dict:
+    """요약 출력에서 4청크를 관대하게 파싱 — 누락 키는 폴백 몫."""
+    chunks = {}
+    for key in CHUNK_KEYS:
+        m = re.search(rf"{key}\s*[:：]\s*(.+)", text)
+        if m:
+            chunks[key] = m.group(1).strip()[:160]
+    return chunks
+
+
+def llm_state(turns: list[tuple[str, str]]) -> dict:
+    prompt = ("다음은 개발자(정훈)와 에이전트의 대화다. 이 시점의 작업 상태를 정확히 4줄로 압축하라.\n"
+              "형식(각 줄 120자 이내):\n목표: …\n직전 사건: …\n미결: …\n다음 손: …\n\n"
+              + dialogue_text(turns))
+    for url, model in SUMM_ENGINES:
+        try:
+            req = urllib.request.Request(url, data=json.dumps({
+                "model": model, "stream": False, "think": False, "keep_alive": "3h",
+                "messages": [{"role": "user", "content": prompt}],
+                "options": {"temperature": 0.0, "num_predict": 300},
+            }).encode(), headers={"Content-Type": "application/json"})
+            body = json.loads(urllib.request.urlopen(req, timeout=90).read())
+            chunks = parse_chunks(str((body.get("message") or {}).get("content") or ""))
+            if len(chunks) >= 3:
+                chunks["_engine"] = model
+                return chunks
+        except Exception:
+            continue
+    return {}
+
+
+def structural_state(turns: list[tuple[str, str]]) -> dict:
+    """LLM 불가 시 기계 조립 — 낮은 품질의 상태가 무상태보다 낫다."""
+    last_user = next((t for r, t in reversed(turns) if r == "user"), "")
+    last_asst = next((t for r, t in reversed(turns) if r == "assistant"), "")
+    return {
+        "목표": last_user[:160] or "(요약 불가)",
+        "직전 사건": last_asst[:160] or "(요약 불가)",
+        "미결": "(구조적 폴백 — LLM 요약 실패)",
+        "다음 손": last_user[:160] or "(요약 불가)",
+        "_engine": "structural-fallback",
+    }
+
+
+def write_state(project: str, chunks: dict, transcript_path: str, event: str) -> None:
+    os.makedirs(BSTATE_DIR, exist_ok=True)
+    state = {
+        "project": project,
+        "captured_at": time.strftime("%FT%T%z"),
+        "event": event,
+        "engine": chunks.pop("_engine", "?"),
+        "chunks": {k: chunks.get(k, "") for k in CHUNK_KEYS},
+        "transcript": os.path.basename(transcript_path),
+    }
+    path = os.path.join(BSTATE_DIR, f"{project}.json")
+    tmp = path + ".tmp"
+    with open(tmp, "w", encoding="utf-8") as fh:
+        json.dump(state, fh, ensure_ascii=False, indent=1)
+    os.replace(tmp, path)  # 원자적 — 반쯤 쓰인 상태 파일은 존재하지 않는다
+    with open(os.path.join(BSTATE_DIR, f"{project}.history.jsonl"), "a", encoding="utf-8") as fh:
+        fh.write(json.dumps(state, ensure_ascii=False) + "\n")
+
+
+def load_state(project: str) -> dict | None:
+    try:
+        with open(os.path.join(BSTATE_DIR, f"{project}.json"), encoding="utf-8") as fh:
+            return json.load(fh)
+    except Exception:
+        return None
+
+
+def render_block(state: dict) -> str:
+    """세션 시작 주입용 — 작게, 신선도 명기."""
+    try:
+        captured = time.mktime(time.strptime(state["captured_at"][:19], "%Y-%m-%dT%H:%M:%S"))
+        age_min = int((time.time() - captured) / 60)
+    except Exception:
+        age_min = -1
+    age = (f"{age_min}분 전" if 0 <= age_min < 120 else
+           f"{age_min // 60}시간 전" if age_min >= 0 else "시각 불명")
+    stale = " ⚠오래됨 — 재검증 후 행동" if age_min > 24 * 60 else ""
+    lines = [f"[B층 — 마지막 작업 상태 (캡처 {age}{stale}, {state.get('event', '?')})]"]
+    for k in CHUNK_KEYS:
+        v = (state.get("chunks") or {}).get(k, "")
+        if v:
+            lines.append(f"{k}: {v}")
+    return "\n".join(lines)[:STATE_BUDGET + 200]
+
+
+def worker(transcript_path: str, project: str, event: str) -> None:
+    turns = extract_dialogue(transcript_path)
+    if len(turns) < 2:
+        return
+    chunks = llm_state(turns) or structural_state(turns)
+    write_state(project, chunks, transcript_path, event)
+
+
+def hook_entry() -> None:
+    """훅 본체 — 즉시 반환. 판단은 전부 여기서, 노동은 워커에서."""
+    try:
+        payload = json.load(sys.stdin)
+    except Exception:
+        return
+    transcript = str(payload.get("transcript_path") or "")
+    cwd = str(payload.get("cwd") or os.getcwd())
+    event = str(payload.get("hook_event_name") or "?")
+    if not transcript or not os.path.exists(transcript):
+        return
+    project = project_key_for_path(cwd) or "global"
+    # Stop은 매 턴 — 스로틀. 종료·압축은 B층이 살아남아야 할 순간이라 무조건.
+    if event == "Stop":
+        try:
+            age = time.time() - os.path.getmtime(os.path.join(BSTATE_DIR, f"{project}.json"))
+            if age < THROTTLE_MIN * 60:
+                return
+        except OSError:
+            pass  # 상태 없음 — 첫 캡처
+    subprocess.Popen(
+        [sys.executable, os.path.abspath(__file__), "--worker", transcript, project, event],
+        stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
+        start_new_session=True,  # 훅 프로세스와 운명 분리
+    )
+
+
+if __name__ == "__main__":
+    if len(sys.argv) >= 5 and sys.argv[1] == "--worker":
+        worker(sys.argv[2], sys.argv[3], sys.argv[4])
+    else:
+        hook_entry()

package/assets/hooks/forget_capture.py

@@ -1,16 +1,21 @@
 #!/usr/bin/env python3
-"""Session capture + mechanical outcome labeling (PreCompact and SessionEnd).
+"""Session capture + mechanical outcome labeling (PreCompact, SessionEnd, Stop).
 
 Two judgment-free jobs, each fail-open on its own:
 1. capture — register the session in forget: pointer + mechanical digest,
    source_role="tool" (green). The transcript on disk is the lossless ledger;
    this makes it findable.
-2. outcome — if a SessionStart capsule was offered this session (state file
+2. outcome — if a SessionStart capsule was offered this session/turn (state file
    exists), measure mechanically whether the session echoed it and record a
    context outcome against the capsule's trace. This is the crudest possible
    label (all-or-none echo, substring match); its job is to start the data
    flywheel, not to be right — retire it when a learned labeler exists
    (observer W2) or when per-memory matching lands.
+
+At Claude PreCompact a third job is delegated, not owned: forget_digest.flush()
+digests the whole undigested segment before the handoff note is written
+(rolling consolidation ②), so a compaction can only evaporate turns that
+already reached forget.
 """
 
 from __future__ import annotations
@@ -25,6 +30,11 @@ sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
 
 from forget_project import project_key_for_path, scope_disabled  # noqa: E402
 
+try:
+    import forget_digest  # noqa: E402 — sibling; packaged installs may not ship it yet
+except Exception:
+    forget_digest = None
+
 FORGET_URL = os.environ.get("FORGET_MCP_URL", "http://127.0.0.1:8000/mcp")
 STATE_DIR = os.path.expanduser("~/.forget/hooks/state")
 TAIL_BYTES = 400_000
@@ -200,13 +210,20 @@ def main() -> None:
     except Exception:
         pass
     if str(hook_input.get("hook_event_name") or "") == "PreCompact":
+        # ② final flush BEFORE the handoff note: everything the compaction is
+        # about to evaporate reaches forget first (rolling-consolidation ②).
+        if forget_digest is not None:
+            try:
+                forget_digest.flush(transcript_path, session_id)
+            except Exception:
+                pass
         try:
             _handoff(digest, transcript_path, session_id)
         except Exception:
             pass
-    # Outcome is a session-final label: a mid-session compact must not consume
-    # the offer ledger, or usage after the compact goes unmeasured.
-    if str(hook_input.get("hook_event_name") or "") == "SessionEnd":
+    # Outcome is terminal for Claude (SessionEnd) and per completed Codex turn
+    # (Stop). A mid-session compact must not consume the offer ledger.
+    if str(hook_input.get("hook_event_name") or "") in {"SessionEnd", "Stop"}:
         try:
             _outcome(digest, session_id)
         except Exception:

package/assets/hooks/forget_sessionstart.py

@@ -27,7 +27,7 @@ HANDOFF_MAX_AGE_SECONDS = 48 * 3600  # a stale shift-note is worse than none
 # The server capability these hooks are built against. The capsule response
 # carries server_version from 0.3.9 on; older servers silently drop arguments
 # these hooks send (project layering) — that mismatch must never be silent.
-REQUIRED_SERVER_VERSION = "0.3.9"
+REQUIRED_SERVER_VERSION = "0.5.0"
 
 
 def _version_tuple(value: str) -> tuple:
@@ -53,7 +53,8 @@ def _version_notice(server_version: str) -> str:
             "프로젝트 층 등이 조용히 무시됨. 처방: forget-server upgrade"
         )
     try:
-        with open(os.path.expanduser("~/.forget/update-check.json"), encoding="utf-8") as fh:
+        forget_home = os.environ.get("FORGET_HOME") or os.path.expanduser("~/.forget")
+        with open(os.path.join(forget_home, "update-check.json"), encoding="utf-8") as fh:
             latest = str(json.load(fh).get("latest") or "")
         if latest and _version_tuple(server_version) < _version_tuple(latest):
             return f"새 버전 {latest} 나옴 (현재 {server_version}) — forget-server upgrade"
@@ -94,6 +95,18 @@ def _consume_handoff() -> str:
     return "\n".join(lines)
 
 
+def _bstate_block(project: str | None) -> str:
+    """B층 파일 직독 — 회상 경합·캡슐 슬롯 경쟁 없음 (P39 처분)."""
+    try:
+        import forget_bstate
+        state = forget_bstate.load_state(project or "global")
+        if not state:
+            return ""
+        return forget_bstate.render_block(state)
+    except Exception:
+        return ""
+
+
 def main() -> None:
     hook_input = json.load(sys.stdin)
     cwd = str(hook_input.get("cwd") or os.getcwd())
@@ -134,12 +147,17 @@ def main() -> None:
             capsule = "\n".join(f"- {item}" for item in items[:6] if isinstance(item, str))
     handoff = _consume_handoff()
     notice = _version_notice(str(result.get("server_version") or ""))
-    if not capsule and not handoff:
+    bstate = _bstate_block(project)
+    if not capsule and not handoff and not bstate:
         return  # low confidence → silence (version nags don't earn a lone injection)
     shown = capsule[:CAPSULE_CHAR_BUDGET]
     parts = []
     if notice:
         parts.append(f"[forget 버전] {notice}")
+    # B층이 캡슐보다 먼저 — 인간이 깨어날 때 "무엇의 한가운데였나"가
+    # 백과사전보다 먼저 오듯이 (P39: 구조화 상태가 예측 정보 +62%).
+    if bstate:
+        parts.append(bstate)
     if handoff:
         parts.append(handoff)
     if shown:

package/assets/hooks/forget_toolrecall.py

@@ -0,0 +1,118 @@
+#!/usr/bin/env python3
+"""forget_toolrecall — 진행-중 회상 v0 (PostToolUse, Bash 전용).
+
+설계 정본: research/proxy-native-redesign.md §3.6 지평 1. 트리거는 사용자
+프롬프트가 아니라 진행 중인 사고의 내용물 — 도구가 **실패**했을 때 그 에러
+서명으로 러닝북을 소환해 결과에 동승시킨다. 원조 사례: 2026-08-12 새벽 pkill
+자기-매칭 침묵 자살 3연속 — 첫 실패 때 러닝북이 도착했다면 한 번으로 끝났다.
+
+v0 규율:
+- Bash 결과에만 반응 (서명 전부 Bash-급 함정 + Read/Grep가 러닝북 파일을
+  읽을 때의 자기-매칭 차단 — pkill 러닝북이 가르친 바로 그 함정의 훅판).
+- 정적 패턴만, LLM·서버 호출 없음 (ms급 — 지연 예산 논쟁 원천 차단).
+- 실패 판정이 애매한 페이로드는 발동하지 않되 **형상을 원장에 남긴다**
+  (계기-우선 — 내일 실측으로 보정). 원장엔 내용 무기록, 형상 메타만.
+- 세션당 같은 러닝북 1회. 텍스트 4000자 초과는 실패 메시지가 아니라
+  산출물로 간주하고 침묵.
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import sys
+import time
+from pathlib import Path
+
+RUNBOOKS = Path(os.environ.get("FORGET_RUNBOOKS", str(Path.home() / ".forget/runbooks.md")))
+STATE_DIR = Path.home() / ".forget/hooks/state"
+LEDGER = STATE_DIR / "toolrecall_ledger.jsonl"
+MAX_BODY_CHARS = 700
+MAX_ERR_CHARS = 4000
+
+SIGNATURES: list[tuple[str, str]] = [
+    (r"contains multiple operations|requires approval", "복합 Bash 명령 승인 회피"),
+    (r"brace with quote character", "heredoc·따옴표 중괄호 차단"),
+    (r"rm in '.*내-프롬프트를", "워크트리 한글 경로 rm 차단"),
+    (r"timed out after|output discarded", "타임아웃 계층 산수"),
+]
+
+
+def _note(kind: str, **fields) -> None:
+    try:
+        STATE_DIR.mkdir(parents=True, exist_ok=True)
+        row = {"ts": time.strftime("%F %T"), "kind": kind, **fields}
+        with LEDGER.open("a") as fh:
+            fh.write(json.dumps(row, ensure_ascii=False) + "\n")
+    except Exception:
+        pass
+
+
+def _response_text(response) -> tuple[str, bool | None]:
+    """(텍스트, 실패 여부) — 실패를 모르면 None."""
+    if isinstance(response, str):
+        return response, None
+    if isinstance(response, dict):
+        err = response.get("is_error", response.get("isError"))
+        parts = [str(response.get(k) or "") for k in ("error", "stderr", "stdout", "content", "message")]
+        text = "\n".join(p for p in parts if p) or json.dumps(response, ensure_ascii=False)
+        if err is None and response.get("stderr"):
+            err = None  # stderr 존재만으로 실패 단정 금지 (경고 흔함)
+        return text, bool(err) if err is not None else None
+    return "", None
+
+
+def _load_runbook(title: str) -> str | None:
+    try:
+        text = RUNBOOKS.read_text(encoding="utf-8")
+    except Exception:
+        return None
+    match = re.search(rf"## runbook: {re.escape(title)}.*?(?=\n## |\Z)", text, re.S)
+    return match.group(0)[:MAX_BODY_CHARS] if match else None
+
+
+def main() -> None:
+    try:
+        payload = json.load(sys.stdin)
+    except Exception:
+        return
+    if str(payload.get("tool_name") or "") != "Bash":
+        return
+    text, failed = _response_text(payload.get("tool_response"))
+    if not text or len(text) > MAX_ERR_CHARS:
+        return
+    hit = next((title for pattern, title in SIGNATURES if re.search(pattern, text, re.I)), None)
+    if hit is None:
+        return
+    if failed is False:
+        _note("sig_in_success", sig=hit, chars=len(text))
+        return
+    if failed is None:
+        # 형상 미상 — 발동 대신 관측 (내일 이 원장으로 실패 판정을 보정한다)
+        _note("sig_shape_unknown", sig=hit, chars=len(text),
+              keys=sorted(payload.get("tool_response", {}).keys()) if isinstance(payload.get("tool_response"), dict) else "str")
+        return
+
+    session_id = str(payload.get("session_id") or "nosession")
+    seen_path = STATE_DIR / f"toolrecall_{session_id}.json"
+    try:
+        seen = set(json.loads(seen_path.read_text()))
+    except Exception:
+        seen = set()
+    if hit in seen:
+        return
+    body = _load_runbook(hit)
+    if not body:
+        _note("runbook_missing", sig=hit)
+        return
+    seen.add(hit)
+    try:
+        seen_path.write_text(json.dumps(sorted(seen), ensure_ascii=False))
+    except Exception:
+        pass
+    _note("injected", sig=hit)
+    print(f"[forget 러닝북 — 이 실패 서명엔 검증된 절차가 있음]\n{body}")
+
+
+if __name__ == "__main__":
+    main()