eagle-mem 4.11.0 → 4.12.0

package/CHANGELOG.md

@@ -4,6 +4,18 @@ All notable changes to the **Eagle Mem** project are documented here.
 
 ---
 
+## v4.12.0 Clean, Branded Session Capture
+
+Session endings are now clean across every agent — no more raw `<eagle-summary>` XML blocks in the visible reply.
+
+- **CLI-first capture**: Agents persist structured summaries by running `eagle-mem session save --session-id <id> ...` (a pre-approved, quiet Bash call), then end with a short human recap plus one branded line: `Eagle Mem | Session captured — N decisions, M gotchas`. The installer adds a `permissions.allow` entry so the capture runs without a prompt.
+- **Extended `session save`**: New flags `--session-id`, `--completed`, `--investigated`, `--files-read`, `--files-modified`, `--affected-features`, `--verified-features`, `--regression-risks`. With `--session-id` the capture merges into the live session row instead of creating a standalone `manual-*` row, and no longer marks the session completed.
+- **Capture-integrity fixes**: New `capture_source` column (`agent`/`hook`/`enrich`) with an atomic fill-only upsert. Agent-authored captures are authoritative — Stop-hook heuristics and background LLM enrichment now only fill empty gaps and can never clobber richer data (previously the winning-COALESCE upsert could overwrite it). Enrichment queueing is skipped once a session is agent-authored.
+- **Cross-agent**: Claude Code, Codex, OpenCode, Grok, and Antigravity all capture through the same CLI. Instruction text updated in SessionStart/UserPromptSubmit (Claude + Codex), the installed CLAUDE.md/AGENTS.md sections, and `compaction.sh`.
+- **Backward compatible**: The Stop hook still parses any `<eagle-summary>` block it finds; agents are simply no longer instructed to emit one.
+
+---
+
 ## v4.11.0 Agent Compatibility and Governance Surfaces
 
 This feature release expands Eagle Mem from Claude/Codex memory hooks into a broader multi-agent governance substrate:

package/README.md

@@ -88,7 +88,7 @@ Hooks fire automatically at different points in the agent lifecycle:
 | **PreToolUse** | before Bash/shell, Read, Edit, Write, apply_patch | Surfaces guardrails and decisions before edits. Blocks release-boundary commands while feature verification is pending. Rewrites noisy commands through RTK when available. Detects redundant reads, nudges co-edit partners, detects stuck loops. |
 | **UserPromptSubmit** | user sends a message | FTS5 search across past sessions and indexed code for relevant context |
 | **PostToolUse** | after tool calls | Records file touches, mirrors memory/plan/task writes, surfaces decision history and feature impacts on reads, stale memory warnings on edits |
-| **Stop** | agent turn ends | Saves fast heuristic summaries and extracts `<eagle-summary>` blocks when present. LLM enrichment runs later in the background so the agent lifecycle is not blocked. |
+| **Stop** | agent turn ends | Saves the session summary. Agent-authored captures from `eagle-mem session save` are authoritative; heuristic extraction only fills gaps and LLM enrichment runs later in the background so the agent lifecycle is not blocked. |
 | **SessionEnd** | session closes | Re-syncs tasks, marks session completed |
 
 Codex shell hooks are registered for `Bash`, `exec_command`, `shell_command`, and `unified_exec` tool names so release-boundary protection works across current Codex shell paths. OpenCode uses a global local plugin to normalize `chat.message`, `tool.execute.before`, `tool.execute.after`, `todo.updated`, `session.idle`, and compaction events into the same Eagle Mem hook payloads.
@@ -128,7 +128,7 @@ Run `eagle-mem compaction` anytime to check readiness.
 
 Eagle Mem prevents Claude from repeating past mistakes:
 
-- **Decision surfacing** — when you edit a file that has past decisions recorded (from `<eagle-summary>` blocks), PreToolUse reminds Claude not to revert without asking
+- **Decision surfacing** — when you edit a file that has past decisions recorded (from captured session summaries), PreToolUse reminds Claude not to revert without asking
 - **Guardrails** — file-level rules (manual or curator-discovered) that fire before every Edit/Write
 - **Feature verification** — tracks features with smoke tests and dependencies; current git diffs create fingerprinted pending verification records, and release-boundary commands such as `git push`, `gh pr create`, and package publish are blocked until the current fingerprint is verified or waived
 - **Gotcha surfacing** — past surprises and gotchas are surfaced when editing related files

package/db/044_summary_capture_source.sql

@@ -0,0 +1,12 @@
+-- Migration 044: Summary capture provenance
+-- Tracks how each summary row was captured so later writers do not clobber
+-- richer data. Values:
+--   'agent'  — agent-authored via `eagle-mem session save` or a parsed
+--              <eagle-summary> block (authoritative)
+--   'hook'   — Stop-hook heuristic extraction (gap-fill only once 'agent')
+--   'enrich' — background LLM enrichment (gap-fill only once 'agent')
+-- Empty default preserves existing rows. Not indexed by FTS.
+
+ALTER TABLE summaries ADD COLUMN capture_source TEXT NOT NULL DEFAULT '';
+
+CREATE INDEX IF NOT EXISTS idx_summaries_capture_source ON summaries(capture_source);

package/docs/agent-compatibility/claude-code.md

@@ -1,6 +1,6 @@
 # Claude Code Compatibility
 
-Last verified: 2026-06-02
+Last verified: 2026-06-10
 
 ## Official Sources
 
@@ -21,6 +21,14 @@ Last verified: 2026-06-02
 - `SessionEnd` runs when a session terminates.
 - The custom statusline is configured with `statusLine` in Claude settings; its command receives JSON on stdin and the first stdout line becomes the visible statusline text.
 
+## Session Capture Behavior
+
+- Eagle Mem no longer instructs Claude to print a raw `<eagle-summary>` block. `SessionStart` injects guidance to capture the session by running `eagle-mem session save --session-id <session_id> ...` (a quiet shell call), then to end the turn with human prose plus one branded line: `Eagle Mem | Session captured — N decisions, M gotchas`.
+- The `session_id` injected into the instruction is the same id Claude passes to every hook, so the CLI capture merges into the live session row rather than creating a standalone `manual-*` row.
+- The installer adds `permissions.allow: ["Bash(eagle-mem session save:*)"]` to Claude settings so the capture runs without a permission prompt. The instruction must use that exact command prefix (no leading path, no `cd &&`) for the permission to match.
+- Agent-authored captures are authoritative (`capture_source = agent`). The `Stop` hook still parses any `<eagle-summary>` block for backward compatibility, but when an agent row already exists its heuristics only fill empty fields and background enrichment is skipped — neither can clobber agent data.
+- `UserPromptSubmit` context-pressure nudges (≥20 / ≥30 turns) also point at `eagle-mem session save`, not the raw block.
+
 ## Eagle Mem Files Depending On This
 
 - `lib/hooks.sh`

package/docs/agent-compatibility/codex.md

@@ -1,6 +1,6 @@
 # Codex Compatibility
 
-Last verified: 2026-06-02
+Last verified: 2026-06-10
 
 ## Official Sources
 
@@ -22,6 +22,12 @@ Last verified: 2026-06-02
 - Hook `timeout` is measured in seconds; `statusMessage` is optional.
 - Codex memory files are generated state. Required team guidance belongs in `AGENTS.md` or checked-in documentation, not only in local memories.
 
+## Session Capture Behavior
+
+- Codex replies stay prose-only; Eagle Mem never asks Codex to print summary blocks, XML, or hook payloads. The `Stop` hook captures a summary from the Codex rollout transcript automatically.
+- For a richer structured capture, Codex may run `eagle-mem session save --session-id <session_id> --agent codex ...` once at wrap-up (injected by `SessionStart` and the `AGENTS.md` section). This sets `capture_source = agent`, which is authoritative: later Stop-hook heuristics only fill empty fields and background enrichment is skipped, so the capture is never clobbered.
+- Modified-file lists are most reliable when Codex passes `--files-modified` explicitly; the transcript heuristic is Claude-shaped and may not populate file lists from Codex rollout tool calls.
+
 ## Eagle Mem Files Depending On This
 
 - `lib/codex-hooks.sh`

package/docs/agent-compatibility/opencode.md

@@ -1,6 +1,6 @@
 # OpenCode Compatibility
 
-Last verified: 2026-06-02
+Last verified: 2026-06-10
 
 ## Official Sources
 
@@ -37,6 +37,7 @@ Last verified: 2026-06-02
 - `session.idle` maps to Eagle Mem `Stop` using the latest assistant text accumulated from message events.
 - `session.deleted` maps to Eagle Mem `SessionEnd`.
 - `experimental.session.compacting` maps to Eagle Mem compact recall by running `SessionStart` with `source=compact` and appending the returned context.
+- Session capture follows the shared clean-capture flow: the agent may run `eagle-mem session save --session-id <id> ...` at wrap-up (sets `capture_source = agent`, authoritative) and keep replies prose-only. The `session.idle` → `Stop` path then only fills gaps and never clobbers an agent-authored row.
 
 ## Eagle Mem Files Depending On This
 

package/hooks/session-start.sh

@@ -625,33 +625,24 @@ fi
 if [ "$agent" = "codex" ]; then
     context+="
 === Eagle Mem: Active ===
-Memory active for '$project'. Keep user-facing Codex replies clean: do not print Eagle Mem summary capture blocks, XML, JSON hook payloads, or internal templates unless the user explicitly asks. The Stop hook captures summaries from the transcript automatically.
+Memory active for '$project'. Keep user-facing Codex replies clean: do not print Eagle Mem summary capture blocks, XML, JSON hook payloads, or internal templates unless the user explicitly asks. The Stop hook captures summaries from the transcript automatically. When you wrap up substantive work, you may persist a richer structured capture by running once: eagle-mem session save --session-id $session_id --agent codex --completed \"...\" --decisions \"choice — why\" --gotchas \"...\" --files-modified \"a.ts,b.ts\" (fill what applies). Keep the visible reply prose-only.
 "
 elif [ "$source_type" = "compact" ] || [ "$source_type" = "clear" ]; then
     context+="
 === Eagle Mem: Active ===
-Memory active. Attribute recalled context to Eagle Mem. Do not revert PostToolUse-surfaced decisions without asking. Emit <eagle-summary> before final response.
+Memory active. Attribute recalled context to Eagle Mem. Do not revert PostToolUse-surfaced decisions without asking. Before your final response, capture the session quietly via the Bash tool (pre-approved): eagle-mem session save --session-id $session_id --completed \"...\" --decisions \"choice — why\" --gotchas \"...\" (fill what applies, omit the rest). Then give a short human recap — NEVER print <eagle-summary> tags or raw field lists.
 "
 else
     context+="
 === Eagle Mem: Active ===
 Memory active for '$project'. Scan, index, prune, and self-learning run automatically — never ask the user to run these. Attribute recalled context: \"Eagle Mem recalls:\" Do not revert PostToolUse-surfaced decisions without user request. No raw secrets in summaries. If you contradict a loaded memory, update the memory file.
 
-Before your final response, emit:
-<eagle-summary>
-request: [what user asked]
-completed: [what shipped]
-learned: [non-obvious discoveries]
-decisions: [choice — why]
-gotchas: [what surprised]
-next_steps: [concrete actions]
-key_files: [path — role]
-files_read: [path, ...]
-files_modified: [path, ...]
-affected_features: [feature, ...]
-verified_features: [feature, ...]
-regression_risks: [risk, ...]
-</eagle-summary>
+Session capture is clean: NEVER print <eagle-summary> tags, XML, or raw field lists (request:/completed:/...) in your visible reply. When you wrap up substantive work (shipped a change, made decisions worth remembering, the user signals done, or Eagle Mem warns of context pressure), capture it by running this ONCE via the Bash tool — it is pre-approved and prints only a short confirmation. Fill the flags you have; omit the rest:
+
+  eagle-mem session save --session-id $session_id --request \"...\" --completed \"...\" --learned \"...\" --decisions \"choice — why; choice — why\" --gotchas \"...\" --next-steps \"...\" --key-files \"path — role\" --files-modified \"a.ts,b.ts\" --affected-features \"...\" --verified-features \"...\" --regression-risks \"...\"
+
+Then end with a brief, human recap of the session in prose, followed by one line:
+**Eagle Mem** | Session captured — N decisions, M gotchas
 "
 fi
 

package/hooks/stop.sh

@@ -396,10 +396,30 @@ if [ -n "$regression_notes" ]; then
 fi
 
 # ─── Write to database ─────────────────────────────────────
+#
+# Capture-source precedence:
+#   - A parsed <eagle-summary> block this turn is agent-authored → write 'agent'.
+#   - An existing 'agent' row (CLI `eagle-mem session save` or an earlier block)
+#     is authoritative → fill empty gaps only, never overwrite with heuristics.
+#   - Otherwise this is a heuristic capture → normal 'hook' write.
+# agent_authored also gates background enrichment so it can't clobber later.
+
+existing_source=$(eagle_summary_capture_source "$session_id" 2>/dev/null || true)
+agent_authored=0
+[ -n "$summary_block" ] && agent_authored=1
+[ "$existing_source" = "agent" ] && agent_authored=1
 
 if [ -n "$request" ] || [ -n "$completed" ] || [ -n "$learned" ]; then
-    if eagle_insert_summary "$session_id" "$project" "$request" "$investigated" "$learned" "$completed" "$next_steps" "$files_read" "$files_modified" "$notes" "$decisions" "$gotchas" "$key_files" "$agent"; then
-        eagle_log "INFO" "Stop: summary saved for session=$session_id"
+    write_rc=0
+    if [ -n "$summary_block" ]; then
+        eagle_insert_summary "$session_id" "$project" "$request" "$investigated" "$learned" "$completed" "$next_steps" "$files_read" "$files_modified" "$notes" "$decisions" "$gotchas" "$key_files" "$agent" "agent" || write_rc=$?
+    elif [ "$existing_source" = "agent" ]; then
+        eagle_insert_summary_fill_only "$session_id" "$project" "$request" "$investigated" "$learned" "$completed" "$next_steps" "$files_read" "$files_modified" "$notes" "$decisions" "$gotchas" "$key_files" "$agent" "hook" || write_rc=$?
+    else
+        eagle_insert_summary "$session_id" "$project" "$request" "$investigated" "$learned" "$completed" "$next_steps" "$files_read" "$files_modified" "$notes" "$decisions" "$gotchas" "$key_files" "$agent" "hook" || write_rc=$?
+    fi
+    if [ "$write_rc" -eq 0 ]; then
+        eagle_log "INFO" "Stop: summary saved for session=$session_id (prior_source=${existing_source:-none}, block=$([ -n "$summary_block" ] && echo yes || echo no))"
         eagle_insert_event "$project" "$session_id" "$agent" "memory_created" "" "Stop" "ok" "$(jq -nc --arg source "summary" '{source:$source}')" >/dev/null 2>&1 || true
     else
         eagle_log "ERROR" "Stop: summary insert FAILED for session=$session_id — check DB constraints"
@@ -413,7 +433,7 @@ eagle_hook_observability_set_detail "$(jq -nc \
     '{request_chars:($request | length), completed_chars:($completed | length), files_read:$files_read, files_modified:$files_modified}')"
 eagle_hook_observability_complete 0
 
-if [ "$defer_enrichment" -eq 1 ] && [ "${EAGLE_MEM_STOP_BACKGROUND_ENRICH:-1}" = "1" ] && [ -n "$text_content" ]; then
+if [ "$defer_enrichment" -eq 1 ] && [ "${EAGLE_MEM_STOP_BACKGROUND_ENRICH:-1}" = "1" ] && [ -n "$text_content" ] && [ "$agent_authored" -eq 0 ]; then
     mkdir -p "$EAGLE_MEM_DIR/tmp" 2>/dev/null || true
     enrich_job=$(mktemp "$EAGLE_MEM_DIR/tmp/summary-enrich.XXXXXX.json" 2>/dev/null)
     if [ -n "$enrich_job" ]; then

package/hooks/user-prompt-submit.sh

@@ -67,8 +67,9 @@ Eagle Mem context pressure: critical ($turn_count turns since compact)
         else
             context+="
 === Eagle Mem: Context Pressure Critical ($turn_count turns since compact) ===
-IMMEDIATELY emit a detailed <eagle-summary> covering ALL work this session.
-Tell the user to run /compact NOW to avoid losing context.
+IMMEDIATELY capture ALL work this session by running (pre-approved, quiet):
+eagle-mem session save --session-id $session_id --completed \"...\" --decisions \"choice — why\" --gotchas \"...\" --learned \"...\" --next-steps \"...\" --key-files \"path — role\"
+Then tell the user to run /compact NOW. Do NOT print <eagle-summary> tags or raw field lists.
 "
         fi
         echo "$turn_count" > "$EAGLE_MEM_DIR/.context-pressure"
@@ -83,8 +84,9 @@ Eagle Mem context pressure: high ($turn_count turns since compact)
         else
             context+="
 === Eagle Mem: Context Pressure High ($turn_count turns since compact) ===
-Include a thorough <eagle-summary> in your next response — capture all decisions, gotchas, and learned context before compaction.
-Suggest the user run /compact to free context for continued work.
+Capture your work before compaction by running (pre-approved, quiet):
+eagle-mem session save --session-id $session_id --completed \"...\" --decisions \"choice — why\" --gotchas \"...\" --learned \"...\"
+Then suggest the user run /compact. Do NOT print <eagle-summary> tags or raw field lists.
 "
         fi
         echo "$turn_count" > "$EAGLE_MEM_DIR/.context-pressure"

package/lib/common.sh

@@ -1893,16 +1893,19 @@ The person reading this transcript should experience natural, thoughtful, human
 
 The rich structured data still gets saved (so future sessions get excellent context and the anti-regression system keeps working), but it happens without making the transcript feel like you are reading a debug dump.
 
-**Recommended capture approaches (in order of preference):**
-- Best: Use `eagle-mem session save --summary "..."` or the equivalent capture skill/tool. The CLI writes the structured record cleanly; you only show the nice prose to the user.
-- Strong alternative: Put any machine block inside a collapsed `<details>` element so it is available for debugging but invisible by default.
-- Only as last resort: Emit the raw block at all — and only when the user has explicitly asked for technical output.
+**How to capture (clean, no raw blocks):**
+- When you wrap up substantive work, run this once via the shell — it is pre-approved and prints only a short confirmation. Fill the flags you have; omit the rest:
+  `eagle-mem session save --session-id <id> --request "..." --completed "..." --learned "..." --decisions "choice — why; choice — why" --gotchas "..." --next-steps "..." --key-files "path — role" --files-modified "a.ts,b.ts" --affected-features "..." --verified-features "..." --regression-risks "..."`
+  Your session id is injected by SessionStart; use it verbatim so the capture merges into the live session.
+- Then end with a short, human recap in prose, followed by one line: `**Eagle Mem** | Session captured — N decisions, M gotchas`.
+- NEVER print `<eagle-summary>` tags, XML, or raw field lists (`request:`/`completed:`/...) in the visible reply.
+- If you never run the CLI, the Stop hook still captures a summary automatically as a lower-fidelity fallback — so capture is never lost, it is just richer when you run the command.
 
 **Why this rule exists:** Every single session ends with a summary. If it looks technical, the entire conversation history slowly becomes unpleasant to read. The memory layer should make the experience of working with agents *more* human, not less.
 
 **How to apply:**
 - Write the visible recap in clear, narrative prose first.
-- Persist the structured details via tool or collapsed element — never as raw tags in the main reply.
+- Persist the structured details via the `session save` command — never as raw tags in the main reply.
 - Keep durable task descriptions truthful and up to date; they often carry more value across compactions than any one summary.
 - When Eagle Mem context appears, attribute it naturally.
 - Protect secrets. Update the durable record if you change direction.
@@ -1916,8 +1919,11 @@ eagle_patch_claude_md() {
     mkdir -p "$HOME/.claude"
 
     if [ -f "$claude_md" ] && grep -qF "$marker" "$claude_md" 2>/dev/null; then
-        # Check if section has outdated pipe-separated format
-        if grep -qF 'request: \[what user asked\] | completed:' "$claude_md" 2>/dev/null; then
+        # Rewrite when the section uses an outdated capture doctrine:
+        #   - the old pipe-separated <eagle-summary> template, or
+        #   - the superseded "collapsed <details>" recommendation (pre-CLI-first).
+        if grep -qF 'request: \[what user asked\] | completed:' "$claude_md" 2>/dev/null \
+            || grep -qF 'collapsed `<details>` element' "$claude_md" 2>/dev/null; then
             # Replace the outdated section: remove old, append new
             local tmp_md
             tmp_md=$(mktemp)
@@ -1965,6 +1971,7 @@ Eagle Mem hooks are active for Codex in this project. SessionStart and UserPromp
 - For broad multi-agent work, YOU run `eagle-mem orchestrate`; do not ask the user to run these commands
 - Codex does not currently expose a persistent custom statusline like Claude Code; if the user asks for Eagle Mem status, run `eagle-mem statusline`
 - For important decisions, preferences, gotchas, or durable project facts, include them briefly in normal prose. Eagle Mem will extract them from the transcript.
+- To persist a richer structured capture without printing anything raw, run once at wrap-up: `eagle-mem session save --agent codex --completed "..." --decisions "choice — why" --gotchas "..." --files-modified "a.ts,b.ts"` (fill what applies)
 - Do not revert Eagle Mem-surfaced decisions without asking the user
 - If Eagle Mem reports pending feature verification, verify or waive it before push/PR/publish
 - Never put raw secrets in summaries

package/lib/db-summaries.sh

@@ -20,9 +20,10 @@ eagle_insert_summary() {
     local gotchas; gotchas=$(eagle_sql_escape "${12:-}")
     local key_files; key_files=$(eagle_sql_escape "${13:-}")
     local agent; agent=$(eagle_sql_escape "${14:-$(eagle_agent_source)}")
+    local capture_source; capture_source=$(eagle_sql_escape "${15:-}")
 
     eagle_db_pipe <<SQL
-INSERT INTO summaries (session_id, project, agent, request, investigated, learned, completed, next_steps, files_read, files_modified, notes, decisions, gotchas, key_files)
+INSERT INTO summaries (session_id, project, agent, request, investigated, learned, completed, next_steps, files_read, files_modified, notes, decisions, gotchas, key_files, capture_source)
 VALUES (
     '$session_id',
     '$project',
@@ -37,7 +38,8 @@ VALUES (
     '$notes',
     '$decisions',
     '$gotchas',
-    '$key_files'
+    '$key_files',
+    '$capture_source'
 )
 ON CONFLICT(session_id) DO UPDATE SET
     project        = excluded.project,
@@ -52,10 +54,75 @@ ON CONFLICT(session_id) DO UPDATE SET
     notes          = COALESCE(NULLIF(excluded.notes, ''), summaries.notes),
     decisions      = COALESCE(NULLIF(excluded.decisions, ''), summaries.decisions),
     gotchas        = COALESCE(NULLIF(excluded.gotchas, ''), summaries.gotchas),
-    key_files      = COALESCE(NULLIF(excluded.key_files, ''), summaries.key_files);
+    key_files      = COALESCE(NULLIF(excluded.key_files, ''), summaries.key_files),
+    capture_source = CASE
+                        WHEN summaries.capture_source = 'agent' THEN 'agent'
+                        ELSE COALESCE(NULLIF(excluded.capture_source, ''), summaries.capture_source)
+                     END;
 SQL
 }
 
+# Fill-only upsert: OLD value wins, only blank columns get filled. Atomic —
+# no read-modify-write race. Use when a richer agent-authored row already
+# exists and a later writer (Stop heuristics, background enrichment) should
+# only top up missing fields, never overwrite. capture_source stays 'agent'.
+eagle_insert_summary_fill_only() {
+    local session_id; session_id=$(eagle_sql_escape "$1")
+    local project; project=$(eagle_sql_escape "$2")
+    local request; request=$(eagle_sql_escape "$3")
+    local investigated; investigated=$(eagle_sql_escape "$4")
+    local learned; learned=$(eagle_sql_escape "$5")
+    local completed; completed=$(eagle_sql_escape "$6")
+    local next_steps; next_steps=$(eagle_sql_escape "$7")
+    local files_read; files_read=$(eagle_sql_escape "$8")
+    local files_modified; files_modified=$(eagle_sql_escape "$9")
+    local notes; notes=$(eagle_sql_escape "${10:-}")
+    local decisions; decisions=$(eagle_sql_escape "${11:-}")
+    local gotchas; gotchas=$(eagle_sql_escape "${12:-}")
+    local key_files; key_files=$(eagle_sql_escape "${13:-}")
+    local agent; agent=$(eagle_sql_escape "${14:-$(eagle_agent_source)}")
+    local capture_source; capture_source=$(eagle_sql_escape "${15:-}")
+
+    eagle_db_pipe <<SQL
+INSERT INTO summaries (session_id, project, agent, request, investigated, learned, completed, next_steps, files_read, files_modified, notes, decisions, gotchas, key_files, capture_source)
+VALUES (
+    '$session_id',
+    '$project',
+    '$agent',
+    '$request',
+    '$investigated',
+    '$learned',
+    '$completed',
+    '$next_steps',
+    '$files_read',
+    '$files_modified',
+    '$notes',
+    '$decisions',
+    '$gotchas',
+    '$key_files',
+    '$capture_source'
+)
+ON CONFLICT(session_id) DO UPDATE SET
+    request        = COALESCE(NULLIF(summaries.request, ''), NULLIF(excluded.request, ''), ''),
+    investigated   = COALESCE(NULLIF(summaries.investigated, ''), NULLIF(excluded.investigated, ''), ''),
+    learned        = COALESCE(NULLIF(summaries.learned, ''), NULLIF(excluded.learned, ''), ''),
+    completed      = COALESCE(NULLIF(summaries.completed, ''), NULLIF(excluded.completed, ''), ''),
+    next_steps     = COALESCE(NULLIF(summaries.next_steps, ''), NULLIF(excluded.next_steps, ''), ''),
+    files_read     = COALESCE(NULLIF(summaries.files_read, '[]'), NULLIF(excluded.files_read, '[]'), '[]'),
+    files_modified = COALESCE(NULLIF(summaries.files_modified, '[]'), NULLIF(excluded.files_modified, '[]'), '[]'),
+    notes          = COALESCE(NULLIF(summaries.notes, ''), NULLIF(excluded.notes, ''), ''),
+    decisions      = COALESCE(NULLIF(summaries.decisions, ''), NULLIF(excluded.decisions, ''), ''),
+    gotchas        = COALESCE(NULLIF(summaries.gotchas, ''), NULLIF(excluded.gotchas, ''), ''),
+    key_files      = COALESCE(NULLIF(summaries.key_files, ''), NULLIF(excluded.key_files, ''), '');
+SQL
+}
+
+# How a session's summary was captured: 'agent' | 'hook' | 'enrich' | ''
+eagle_summary_capture_source() {
+    local session_id; session_id=$(eagle_sql_escape "$1")
+    eagle_db "SELECT capture_source FROM summaries WHERE session_id = '$session_id' LIMIT 1;"
+}
+
 eagle_get_recent_summaries() {
     local project_scope="${1:-}"
     local limit; limit=$(eagle_sql_int "${2:-5}")

package/lib/hooks.sh

@@ -31,6 +31,35 @@ eagle_clean_hook_entries() {
         "$settings" > "$tmp" && mv "$tmp" "$settings"
 }
 
+# Add a permissions.allow rule to Claude settings.json so agent-issued capture
+# commands (e.g. `eagle-mem session save`) run without a permission prompt.
+# Idempotent and order-preserving: appends only when the rule is absent, and
+# leaves existing permissions.deny/ask and allow entries untouched.
+eagle_patch_permission_allow() {
+    local settings="$1"
+    local rule="$2"
+    [ -f "$settings" ] || return 0
+    command -v jq >/dev/null 2>&1 || return 0
+
+    if jq -e --arg r "$rule" '(.permissions.allow // []) | index($r) != null' "$settings" >/dev/null 2>&1; then
+        return 0
+    fi
+
+    eagle_backup_file "$settings"
+    local tmp
+    tmp=$(mktemp)
+    if jq --arg r "$rule" '
+            .permissions = (.permissions // {})
+            | .permissions.allow = ((.permissions.allow // []) + [$r])
+        ' "$settings" > "$tmp" 2>/dev/null; then
+        mv "$tmp" "$settings"
+    else
+        rm -f "$tmp" 2>/dev/null || true
+        return 1
+    fi
+    return 0
+}
+
 eagle_patch_hook() {
     local settings="$1"
     local event="$2"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eagle-mem",
-  "version": "4.11.0",
+  "version": "4.12.0",
   "description": "Shared memory, release guardrails, RTK token protection, and worker lanes for Claude Code, Codex, OpenCode, Grok, and Google Antigravity",
   "bin": {
     "eagle-mem": "bin/eagle-mem"

package/scripts/compaction.sh

@@ -157,7 +157,7 @@ if [ "$readiness" = "strong" ]; then
 elif [ "$readiness" = "moderate" ]; then
     eagle_info "Compaction Survival: Moderate — add more durable tasks and summaries"
 else
-    eagle_warn "Compaction Survival: Weak — start using durable tasks and <eagle-summary> blocks"
+    eagle_warn "Compaction Survival: Weak — start using durable tasks and 'eagle-mem session save' captures"
 fi
 
 echo ""

package/scripts/enrich-summary.sh

@@ -90,8 +90,14 @@ gotchas=$(extract_section "$enrich_result" "GOTCHAS" | eagle_redact)
 key_files=$(extract_section "$enrich_result" "KEY_FILES" | eagle_redact)
 
 if [ -n "$request" ] || [ -n "$completed" ] || [ -n "$learned" ] || [ -n "$decisions" ] || [ -n "$gotchas" ] || [ -n "$key_files" ]; then
-    eagle_insert_summary "$session_id" "$project" "$request" "" "$learned" "$completed" "" "[]" "[]" "" "$decisions" "$gotchas" "$key_files" "$agent"
-    eagle_log "INFO" "Summary enrichment saved for session=$session_id provider=$provider"
+    existing_source=$(eagle_summary_capture_source "$session_id" 2>/dev/null || true)
+    if [ "$existing_source" = "agent" ]; then
+        # An agent-authored row exists — only fill gaps, never overwrite it.
+        eagle_insert_summary_fill_only "$session_id" "$project" "$request" "" "$learned" "$completed" "" "[]" "[]" "" "$decisions" "$gotchas" "$key_files" "$agent" "enrich"
+    else
+        eagle_insert_summary "$session_id" "$project" "$request" "" "$learned" "$completed" "" "[]" "[]" "" "$decisions" "$gotchas" "$key_files" "$agent" "enrich"
+    fi
+    eagle_log "INFO" "Summary enrichment saved for session=$session_id provider=$provider source=${existing_source:-none}"
 fi
 
 rm -f "$job_file" 2>/dev/null || true

package/scripts/install.sh

@@ -319,6 +319,11 @@ if [ "$claude_found" = true ]; then
         eagle_patch_hook "$SETTINGS" "PreToolUse" "Bash|Read|Edit|Write" \
             "$EAGLE_MEM_DIR/hooks/pre-tool-use.sh" \
             "PreToolUse hook"
+
+        # Allow agent-issued session capture to run without a permission prompt
+        if eagle_patch_permission_allow "$SETTINGS" "Bash(eagle-mem session save:*)"; then
+            eagle_ok "Capture permission ${DIM}(eagle-mem session save)${RESET}"
+        fi
     fi
 else
     eagle_info "Claude hooks skipped ${DIM}(Claude Code not detected)${RESET}"

package/scripts/session.sh

@@ -19,21 +19,30 @@ show_help() {
     echo -e "    eagle-mem session ${CYAN}save <text>${RESET}"
     echo ""
     echo -e "  ${BOLD}Options for save:${RESET}"
-    echo -e "    ${CYAN}--summary${RESET} <text>       Summary to store"
+    echo -e "    ${CYAN}--completed${RESET} <text>     What was accomplished (alias: --summary)"
     echo -e "    ${CYAN}--request${RESET} <text>       User request that caused the work"
+    echo -e "    ${CYAN}--investigated${RESET} <text>  What was explored or analyzed"
     echo -e "    ${CYAN}--learned${RESET} <text>       Non-obvious discoveries"
     echo -e "    ${CYAN}--decisions${RESET} <text>     Decisions and why"
     echo -e "    ${CYAN}--gotchas${RESET} <text>       Surprises or pitfalls"
     echo -e "    ${CYAN}--next-steps${RESET} <text>    Follow-up work"
-    echo -e "    ${CYAN}--key-files${RESET} <text>     Important files"
+    echo -e "    ${CYAN}--key-files${RESET} <text>     Important files (path — role)"
+    echo -e "    ${CYAN}--files-read${RESET} <list>    Comma-separated files read"
+    echo -e "    ${CYAN}--files-modified${RESET} <list> Comma-separated files modified"
+    echo -e "    ${CYAN}--affected-features${RESET} <text>  Features touched (need re-verify)"
+    echo -e "    ${CYAN}--verified-features${RESET} <text>  Features verified this session"
+    echo -e "    ${CYAN}--regression-risks${RESET} <text>   Known risks introduced"
     echo -e "    ${CYAN}--notes${RESET} <text>         Extra notes"
+    echo -e "    ${CYAN}--session-id${RESET} <id>      Live session id (merges into the active row;"
+    echo -e "                              omit for a standalone manual save)"
     echo -e "    ${CYAN}-p, --project${RESET} <name>   Project name (default: current git root)"
-    echo -e "    ${CYAN}--agent${RESET} <name>         Source agent: codex or claude-code"
+    echo -e "    ${CYAN}--agent${RESET} <name>         Source: claude-code, codex, antigravity, opencode, grok"
     echo -e "    ${CYAN}--cwd${RESET} <path>           Working directory for project detection"
     echo -e "    ${CYAN}--json${RESET}                 Output JSON"
     echo ""
-    echo -e "  ${DIM}This command is mainly for agent fallbacks. Normal sessions are captured${RESET}"
-    echo -e "  ${DIM}automatically by hooks when Claude Code or Codex stops a turn.${RESET}"
+    echo -e "  ${DIM}Agents use this to capture a clean, branded session summary without printing${RESET}"
+    echo -e "  ${DIM}raw blocks. Pass --session-id <id> to merge into the live session row. Stop${RESET}"
+    echo -e "  ${DIM}hooks still capture automatically as a safety net when no save is made.${RESET}"
     echo ""
 }
 
@@ -49,24 +58,48 @@ json_string() {
     jq -Rn --arg v "${1:-}" '$v'
 }
 
+# Comma-separated list → JSON array (matches hooks/stop.sh storage shape).
+# Safe under set -e: empty input yields [] without a failing pipeline.
+# Slurp the whole value (-s) so embedded newlines split into items rather than
+# emitting one JSON array per line (which would corrupt the stored column).
+csv_to_json_array() {
+    local raw="${1:-}"
+    [ -z "$raw" ] && { echo '[]'; return 0; }
+    printf '%s' "$raw" | jq -Rsc 'split("[,\n]"; "") | map(gsub("^\\s+|\\s+$";"")) | map(select(. != ""))'
+}
+
+# Count items in a field separated by ';' or newlines (for the capture banner).
+count_items() {
+    local text="${1:-}"
+    [ -z "$text" ] && { echo 0; return 0; }
+    printf '%s' "$text" | awk 'BEGIN{RS="[;\n]"} {gsub(/^[ \t]+|[ \t]+$/,""); if($0!="") n++} END{print n+0}'
+}
+
 save_session() {
     local summary=""
-    local request="Manual session save"
+    local request=""
+    local investigated=""
     local learned=""
     local decisions=""
     local gotchas=""
     local next_steps=""
     local key_files=""
+    local files_read_raw=""
+    local files_modified_raw=""
+    local affected_features=""
+    local verified_features=""
+    local regression_risks=""
     local notes=""
     local project=""
     local cwd
     cwd="$(pwd)"
     local agent=""
+    local cli_session_id=""
     local json_output=false
 
     while [ $# -gt 0 ]; do
         case "$1" in
-            --summary)
+            --summary|--completed)
                 require_value "$1" "${2:-}"
                 summary="$2"
                 shift 2
@@ -76,6 +109,11 @@ save_session() {
                 request="$2"
                 shift 2
                 ;;
+            --investigated)
+                require_value "$1" "${2:-}"
+                investigated="$2"
+                shift 2
+                ;;
             --learned)
                 require_value "$1" "${2:-}"
                 learned="$2"
@@ -101,11 +139,41 @@ save_session() {
                 key_files="$2"
                 shift 2
                 ;;
+            --files-read)
+                require_value "$1" "${2:-}"
+                files_read_raw="$2"
+                shift 2
+                ;;
+            --files-modified)
+                require_value "$1" "${2:-}"
+                files_modified_raw="$2"
+                shift 2
+                ;;
+            --affected-features)
+                require_value "$1" "${2:-}"
+                affected_features="$2"
+                shift 2
+                ;;
+            --verified-features)
+                require_value "$1" "${2:-}"
+                verified_features="$2"
+                shift 2
+                ;;
+            --regression-risks)
+                require_value "$1" "${2:-}"
+                regression_risks="$2"
+                shift 2
+                ;;
             --notes)
                 require_value "$1" "${2:-}"
                 notes="$2"
                 shift 2
                 ;;
+            --session-id)
+                require_value "$1" "${2:-}"
+                cli_session_id="$2"
+                shift 2
+                ;;
             --project|-p)
                 require_value "$1" "${2:-}"
                 project="$2"
@@ -147,11 +215,25 @@ save_session() {
         esac
     done
 
-    if [ -z "$summary" ]; then
-        eagle_err "Nothing to save. Pass --summary <text>."
+    if [ -z "$summary" ] && [ -z "$learned" ] && [ -z "$decisions" ] && [ -z "$gotchas" ] \
+        && [ -z "$next_steps" ] && [ -z "$key_files" ] && [ -z "$investigated" ] \
+        && [ -z "$files_read_raw" ] && [ -z "$files_modified_raw" ] \
+        && [ -z "$affected_features" ] && [ -z "$verified_features" ] && [ -z "$regression_risks" ]; then
+        eagle_err "Nothing to save. Pass --completed/--summary (or another field)."
         exit 1
     fi
 
+    if [ -n "$cli_session_id" ] && ! eagle_validate_session_id "$cli_session_id"; then
+        eagle_err "Invalid --session-id (allowed: letters, digits, '_', '-', max 128 chars)."
+        exit 1
+    fi
+
+    # For a live session, prefer its recorded project so a save issued from a
+    # subdirectory (whose cwd derives a different key) does not trigger an
+    # unintended project rekey of the active session.
+    if [ -z "$project" ] && [ -n "$cli_session_id" ] && [ -f "${EAGLE_MEM_DB:-}" ]; then
+        project=$(eagle_db "SELECT project FROM sessions WHERE id='$(eagle_sql_escape "$cli_session_id")' LIMIT 1;" 2>/dev/null || true)
+    fi
     [ -z "$project" ] && project=$(eagle_project_from_cwd "$cwd")
     if [ -z "$project" ]; then
         eagle_err "Could not determine project. Re-run with --project <name>."
@@ -165,44 +247,99 @@ save_session() {
             codex|openai-codex) agent="codex" ;;
             claude|claude-code|cloud-code) agent="claude-code" ;;
             antigravity*|google-antigravity*|google_antigravity*) agent="antigravity" ;;
+            opencode) agent="opencode" ;;
+            grok|grok-cli) agent="grok" ;;
             *)
-                eagle_err "--agent must be codex, claude-code, or antigravity"
+                eagle_err "--agent must be codex, claude-code, antigravity, opencode, or grok"
                 exit 1
                 ;;
         esac
     fi
 
+    # Default request only for manual (non-session-id) saves; for a live
+    # session leave it empty so the Stop hook's real request is preserved.
+    if [ -z "$request" ] && [ -z "$cli_session_id" ]; then
+        request="Manual session save"
+    fi
+
+    local files_read files_modified
+    files_read=$(csv_to_json_array "$files_read_raw")
+    files_modified=$(csv_to_json_array "$files_modified_raw")
+
     summary=$(printf '%s' "$summary" | eagle_redact)
     request=$(printf '%s' "$request" | eagle_redact)
+    investigated=$(printf '%s' "$investigated" | eagle_redact)
     learned=$(printf '%s' "$learned" | eagle_redact)
     decisions=$(printf '%s' "$decisions" | eagle_redact)
     gotchas=$(printf '%s' "$gotchas" | eagle_redact)
     next_steps=$(printf '%s' "$next_steps" | eagle_redact)
     key_files=$(printf '%s' "$key_files" | eagle_redact)
     notes=$(printf '%s' "$notes" | eagle_redact)
+    affected_features=$(printf '%s' "$affected_features" | eagle_redact)
+    verified_features=$(printf '%s' "$verified_features" | eagle_redact)
+    regression_risks=$(printf '%s' "$regression_risks" | eagle_redact)
+
+    # Fold feature-tracking fields into notes (same shape as hooks/stop.sh)
+    local regression_notes=""
+    [ -n "$affected_features" ] && regression_notes+="affected_features: $affected_features"
+    if [ -n "$verified_features" ]; then
+        [ -n "$regression_notes" ] && regression_notes+="; "
+        regression_notes+="verified_features: $verified_features"
+    fi
+    if [ -n "$regression_risks" ]; then
+        [ -n "$regression_notes" ] && regression_notes+="; "
+        regression_notes+="regression_risks: $regression_risks"
+    fi
+    if [ -n "$regression_notes" ]; then
+        if [ -n "$notes" ]; then
+            notes="${notes}; ${regression_notes}"
+        else
+            notes="$regression_notes"
+        fi
+    fi
 
     eagle_ensure_db
 
-    local stamp session_id
-    stamp=$(date -u +%Y%m%dT%H%M%SZ)
-    session_id="manual-${stamp}-$$-${RANDOM:-0}"
+    local session_id end_after_save=1
+    if [ -n "$cli_session_id" ]; then
+        # Live session: ensure the row exists and stays active. Empty source/cwd
+        # preserve whatever SessionStart already recorded; do NOT end the session.
+        session_id="$cli_session_id"
+        end_after_save=0
+        eagle_upsert_session "$session_id" "$project" "" "" "" "$agent"
+    else
+        local stamp
+        stamp=$(date -u +%Y%m%dT%H%M%SZ)
+        session_id="manual-${stamp}-$$-${RANDOM:-0}"
+        eagle_upsert_session "$session_id" "$project" "$cwd" "" "manual" "$agent"
+    fi
+
+    # capture_source=agent: agent-authored capture is authoritative and must not
+    # be clobbered by later Stop-hook heuristics or background enrichment.
+    eagle_insert_summary "$session_id" "$project" "$request" "$investigated" "$learned" "$summary" "$next_steps" "$files_read" "$files_modified" "$notes" "$decisions" "$gotchas" "$key_files" "$agent" "agent"
+
+    [ "$end_after_save" = "1" ] && eagle_end_session "$session_id"
 
-    eagle_upsert_session "$session_id" "$project" "$cwd" "" "manual" "$agent"
-    eagle_insert_summary "$session_id" "$project" "$request" "" "$learned" "$summary" "$next_steps" "[]" "[]" "$notes" "$decisions" "$gotchas" "$key_files" "$agent"
-    eagle_end_session "$session_id"
+    local n_dec n_got dec_word got_word
+    n_dec=$(count_items "$decisions")
+    n_got=$(count_items "$gotchas")
+    [ "$n_dec" = "1" ] && dec_word="decision" || dec_word="decisions"
+    [ "$n_got" = "1" ] && got_word="gotcha" || got_word="gotchas"
 
     if [ "$json_output" = true ]; then
         printf '{'
         printf '"session_id":%s,' "$(json_string "$session_id")"
         printf '"project":%s,' "$(json_string "$project")"
         printf '"agent":%s,' "$(json_string "$agent")"
+        printf '"decisions":%s,' "$n_dec"
+        printf '"gotchas":%s,' "$n_got"
         printf '"summary":%s' "$(json_string "$summary")"
         printf '}\n'
     else
-        eagle_ok "Session summary saved"
+        printf '  %bEagle Mem%b | Session captured — %s %s, %s %s\n' \
+            "$CYAN" "$RESET" "$n_dec" "$dec_word" "$n_got" "$got_word"
         eagle_kv "Project:" "$project"
         eagle_kv "Source:" "$(eagle_agent_label "$agent")"
-        eagle_kv "Session:" "$session_id"
     fi
 }
 

package/scripts/update.sh

@@ -100,6 +100,9 @@ if [ "$claude_found" = true ] && [ -f "$SETTINGS" ] && command -v jq &>/dev/null
     eagle_patch_hook "$SETTINGS" "UserPromptSubmit" "" "$EAGLE_MEM_DIR/hooks/user-prompt-submit.sh"
     eagle_patch_hook "$SETTINGS" "PreToolUse" "Bash|Read|Edit|Write" "$EAGLE_MEM_DIR/hooks/pre-tool-use.sh"
 
+    # Allow agent-issued session capture to run without a permission prompt
+    eagle_patch_permission_allow "$SETTINGS" "Bash(eagle-mem session save:*)"
+
     eagle_ok "Hooks registered"
 fi
 

package/tests/test_clean_session_capture.sh

@@ -0,0 +1,105 @@
+#!/usr/bin/env bash
+# ═══════════════════════════════════════════════════════════
+# Eagle Mem — Clean, branded session capture regression test
+# Covers: CLI-first capture, clobber prevention, backward-compat
+#         <eagle-summary> override, and enrichment fill-only.
+# ═══════════════════════════════════════════════════════════
+set -uo pipefail
+
+ROOT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+tmp_dir=$(mktemp -d)
+trap 'rm -rf "$tmp_dir"' EXIT
+
+export EAGLE_MEM_DIR="$tmp_dir/em"
+export EAGLE_AGENT_SOURCE="claude-code"
+export EAGLE_MEM_DISABLE_HOOKS=0
+# Pin the project so both the CLI save and the Stop hook resolve identically
+# (the temp cwd lives under /var/folders, which Eagle Mem treats as ephemeral).
+export EAGLE_MEM_PROJECT="test/clean-capture"
+mkdir -p "$EAGLE_MEM_DIR"
+
+pass=0; fail=0
+ok()  { echo "  ok: $1"; pass=$((pass+1)); }
+bad() { echo "  FAIL: $1" >&2; fail=$((fail+1)); }
+
+bash "$ROOT_DIR/db/migrate.sh" >/dev/null 2>&1
+
+. "$ROOT_DIR/lib/common.sh"
+. "$ROOT_DIR/lib/db.sh"
+
+# A real cwd for the hook payload; project is pinned via EAGLE_MEM_PROJECT.
+work="$tmp_dir/work"
+mkdir -p "$work"
+PROJECT="$EAGLE_MEM_PROJECT"
+ok "pinned project: $PROJECT"
+
+field() { eagle_db "SELECT COALESCE($2,'') FROM summaries WHERE session_id='$1';"; }
+
+# ── Scenario A: CLI capture then a heuristic Stop must NOT clobber it ──
+SID="clean-capture-aaa111"
+eagle_upsert_session "$SID" "$PROJECT" "$work" "" "startup" "claude-code"
+
+bash "$ROOT_DIR/scripts/session.sh" save --session-id "$SID" --project "$PROJECT" \
+    --completed "Rich agent completed" \
+    --decisions "Pin v1 — why safety; Use TOTP — why no SMTP" \
+    --gotchas "needs PUBLIC_URL" >/dev/null 2>&1
+
+[ "$(field "$SID" capture_source)" = "agent" ] && ok "A: capture_source=agent after CLI save" || bad "A: capture_source not agent"
+
+# Heuristic Stop: transcript has an Edit (fills files), NO <eagle-summary> block.
+tA="$tmp_dir/transcriptA.jsonl"
+{
+  printf '%s\n' '{"type":"user","message":{"content":[{"type":"text","text":"please harden the pipeline"}]}}'
+  printf '%s\n' '{"type":"assistant","message":{"content":[{"type":"tool_use","name":"Edit","input":{"file_path":"'"$work"'/foo.sh"}}]}}'
+  printf '%s\n' '{"type":"assistant","message":{"content":[{"type":"text","text":"Done. We hardened the pipeline this session."}]}}'
+} > "$tA"
+
+stopA=$(jq -nc --arg s "$SID" --arg c "$work" --arg t "$tA" \
+    '{session_id:$s, cwd:$c, transcript_path:$t}')
+echo "$stopA" | EAGLE_MEM_STOP_BACKGROUND_ENRICH=0 bash "$ROOT_DIR/hooks/stop.sh" >/dev/null 2>&1
+
+[ "$(field "$SID" completed)" = "Rich agent completed" ] && ok "A: completed NOT clobbered by heuristic" || bad "A: completed was clobbered -> '$(field "$SID" completed)'"
+[ "$(field "$SID" capture_source)" = "agent" ] && ok "A: capture_source still agent after Stop" || bad "A: capture_source downgraded"
+case "$(field "$SID" files_modified)" in *foo.sh*) ok "A: files_modified gap-filled by heuristic" ;; *) bad "A: files_modified not filled -> '$(field "$SID" files_modified)'" ;; esac
+case "$(field "$SID" decisions)" in *"Pin v1"*) ok "A: decisions preserved" ;; *) bad "A: decisions lost" ;; esac
+mrows=$(eagle_db "SELECT COUNT(*) FROM summaries WHERE session_id LIKE 'manual-%';")
+[ "$mrows" = "0" ] && ok "A: no stray manual-* row" || bad "A: $mrows manual-* rows created"
+sstatus=$(eagle_db "SELECT status FROM sessions WHERE id='$SID';")
+[ "$sstatus" = "active" ] && ok "A: live session still active (not ended)" || bad "A: session status=$sstatus"
+
+# ── Scenario B: a <eagle-summary> block still overrides (backward compat) ──
+SIDB="clean-capture-bbb222"
+eagle_upsert_session "$SIDB" "$PROJECT" "$work" "" "startup" "claude-code"
+tB="$tmp_dir/transcriptB.jsonl"
+blocktext='Summary below.
+
+<eagle-summary>
+request: legacy block path
+completed: shipped via block
+decisions: keep parser — why backward compat
+gotchas: none
+</eagle-summary>'
+{
+  printf '%s\n' '{"type":"user","message":{"content":[{"type":"text","text":"do the legacy thing"}]}}'
+  printf '%s\n' "$(jq -nc --arg t "$blocktext" '{type:"assistant",message:{content:[{type:"text",text:$t}]}}')"
+} > "$tB"
+stopB=$(jq -nc --arg s "$SIDB" --arg c "$work" --arg t "$tB" '{session_id:$s, cwd:$c, transcript_path:$t}')
+echo "$stopB" | EAGLE_MEM_STOP_BACKGROUND_ENRICH=0 bash "$ROOT_DIR/hooks/stop.sh" >/dev/null 2>&1
+
+[ "$(field "$SIDB" capture_source)" = "agent" ] && ok "B: block sets capture_source=agent" || bad "B: capture_source=$(field "$SIDB" capture_source)"
+case "$(field "$SIDB" completed)" in *"shipped via block"*) ok "B: completed parsed from block" ;; *) bad "B: block completed not parsed" ;; esac
+case "$(field "$SIDB" decisions)" in *"keep parser"*) ok "B: decisions parsed from block" ;; *) bad "B: block decisions not parsed" ;; esac
+
+# ── Scenario C: enrichment must not overwrite an agent row ──
+SIDC="clean-capture-ccc333"
+eagle_upsert_session "$SIDC" "$PROJECT" "$work" "" "startup" "claude-code"
+eagle_insert_summary "$SIDC" "$PROJECT" "req" "" "" "agent completed C" "" "[]" "[]" "" "agent decision C" "" "" "claude-code" "agent"
+# fill-only path used by enrich when source=agent: simulate enrich trying to overwrite
+eagle_insert_summary_fill_only "$SIDC" "$PROJECT" "" "" "enriched learned" "ENRICH OVERWRITE" "" "[]" "[]" "" "ENRICH DECISION" "" "" "claude-code" "enrich"
+[ "$(field "$SIDC" completed)" = "agent completed C" ] && ok "C: enrich fill-only did NOT overwrite completed" || bad "C: enrich overwrote -> '$(field "$SIDC" completed)'"
+case "$(field "$SIDC" learned)" in *"enriched learned"*) ok "C: enrich filled empty learned gap" ;; *) bad "C: enrich did not fill empty learned" ;; esac
+[ "$(field "$SIDC" capture_source)" = "agent" ] && ok "C: capture_source stays agent through enrich" || bad "C: capture_source changed"
+
+echo ""
+echo "test_clean_session_capture: $pass passed, $fail failed"
+[ "$fail" -eq 0 ]