@meetless/mla 0.1.4

package/dist/hooks-template/post-tool-use.sh

@@ -0,0 +1,423 @@
+#!/usr/bin/env bash
+# post-tool-use.sh: Claude Code PostToolUse hook (Bash + meetless MCP).
+#
+# Two routes, selected by tool name:
+#   Bash                       -> tool_used_bash event (command, exit code,
+#                                 stdout/stderr tails, category HINT) spooled to
+#                                 the queue; Worker re-categorizes (Smaller-D).
+#   mcp__meetless__meetless__* -> tool_used_mcp record of the agent's OWN
+#                                 evidence pull, written LOCALLY to
+#                                 logs/mcp-calls.jsonl keyed by (session_id,
+#                                 turn_index). This is the "pull" side of A1
+#                                 evidence-followthrough: ask-traces.jsonl says
+#                                 what we injected on a turn, mcp-calls.jsonl
+#                                 says what the agent pulled on the same turn.
+#                                 relationship_verdict is an ACTION, never an
+#                                 evidence Pull (evidence_tool=false). See
+#                                 notes/20260603-mla-kb-agent-proxy-and-evidence-adoption.md
+#                                 §7.1 P1 / §7.4 A1.
+# Any other tool is ignored.
+#
+# Source: notes/20260527-bare-bones-mvp-codebase-evaluation-and-plan.md §5.2.
+source "$(dirname "$0")/common.sh"
+
+# Per-folder activation gate (opt-in). Exit before any work unless a
+# `.meetless.json` marker is found by walking up from $PWD. See
+# meetless_activated in common.sh. Run `mla activate` in a repo to opt in.
+meetless_activated || exit 0
+
+INPUT="$(cat)"
+# Wedge v6 Epoch 29: validate stdin parses as JSON BEFORE any jq substitution.
+# See session-start.sh for the trap rationale.
+if [[ -z "$INPUT" ]] || ! printf '%s' "$INPUT" | jq -e . >/dev/null 2>&1; then
+  exit 0
+fi
+SESSION_ID="$(echo "$INPUT" | jq -r '.session_id // empty')"
+TOOL="$(echo "$INPUT" | jq -r '.tool_name // empty')"
+[[ -z "$SESSION_ID" ]] && exit 0
+# Per-session OFF override (`mla deactivate`). Silences this one session even in
+# an activated folder. See meetless_session_disabled in common.sh.
+meetless_session_disabled "$SESSION_ID" && exit 0
+
+# F3-B liveness heartbeat. Throttled detached flush (<=1 per ~60s/session) drains
+# the events already queued this turn so a long, tool-heavy turn keeps control's
+# lastSeenAt fresh and stays LIVE instead of aging into IDLE mid-work. Spools no
+# new event; fail-soft. Runs for EVERY tool (including non-spooling Read/Grep) so
+# the heartbeat covers the whole turn, not just file/bash tools.
+heartbeat_flush "$SESSION_ID"
+
+# ---- Intra-turn narration capture (LIVE, per assistant entry) ------------
+# The agent's visible prose between tool calls is the "line of thought" the
+# session timeline needs INTERLEAVED with the commands. The Stop hook also
+# captures narration, but only as ONE blob stamped at Stop-time -- so it lumps
+# at the end of the turn (never interleaved) and reads the transcript only as it
+# exists at Stop, AFTER a mid-turn auto-compaction has already destroyed the
+# earlier prose. This hook fires LIVE after every tool, so it records each
+# assistant text entry at its OWN transcript timestamp (correct interleave) and
+# BEFORE a later compaction can drop it (compaction-robust). Dogfood-audit
+# 2026-06-12: session f16d5e9a rendered as a wall of commands with no prose.
+#
+# Each entry is keyed by its transcript uuid (assistant_message:<uuid>) so a
+# re-fired hook and the Stop backstop are idempotent against control's
+# (runId, eventKey) dedup. A per-session ts cursor stops us re-spooling prose we
+# already captured on the previous tool. The turn's CLOSING message
+# (stop_reason end_turn) is EXCLUDED -- that is the Stop hook's finalMessage, not
+# narration, and excluding it also stops a later turn from re-capturing the prior
+# turn's closer. Only `text` content is taken (thinking blocks stay private).
+# Runs for EVERY tool (incl. non-spooling Read/Grep) so prose on a read-only turn
+# is not lost. Best-effort and fail-soft: a missing/unreadable transcript or any
+# jq error skips capture and never disturbs the tool spool below. Narration is the
+# default now (no kill switch): the timeline is wrong without it.
+NARR_TRANSCRIPT="$(printf '%s' "$INPUT" | jq -r '.transcript_path // empty' 2>/dev/null || true)"
+if [[ -n "$NARR_TRANSCRIPT" && -f "$NARR_TRANSCRIPT" ]]; then
+  mkdir -p "$QUEUE_DIR"
+  NARR_CURSOR_FILE="$QUEUE_DIR/$SESSION_ID.narration-cursor"
+  (
+    flock 8
+    NARR_CURSOR="$(cat "$NARR_CURSOR_FILE" 2>/dev/null || echo '')"
+    # tail caps the per-fire read; the cursor guarantees completeness because
+    # each narration entry is followed immediately by the tool_use that fires
+    # this hook, so a new entry is always within the recent window.
+    NARR_LINES="$(tail -n 1200 "$NARR_TRANSCRIPT" 2>/dev/null | jq -c -R --slurp \
+      --arg sid "$SESSION_ID" --arg cursor "$NARR_CURSOR" '
+        split("\n")
+        | map(select(length > 0) | fromjson?)
+        | map(select(type == "object"))
+        | [ .[]
+            | select(.type == "assistant")
+            | select((.message.stop_reason // "") != "end_turn")
+            | { uuid: (.uuid // ""),
+                ts: (.timestamp // ""),
+                text: ( (.message.content // [])
+                        | if type == "array"
+                          then map(select((.type? // "") == "text") | (.text? // "")) | join("\n")
+                          else "" end ) }
+            | select(.uuid != "" and .ts != "")
+            | select((.text | gsub("\\s"; "") | length) > 0)
+            | select(.ts > $cursor) ]
+        | .[]
+        | { ts: .ts,
+            event: "assistant_message",
+            eventKey: ("assistant_message:" + .uuid),
+            sessionId: $sid,
+            payload: { narration: .text, entryUuid: .uuid } }
+      ' 2>/dev/null || true)"
+    if [[ -n "$NARR_LINES" ]]; then
+      while IFS= read -r NARR_LINE; do
+        [[ -z "$NARR_LINE" ]] && continue
+        spool_append "$SESSION_ID" "$NARR_LINE"
+      done <<< "$NARR_LINES"
+      NARR_NEW_CURSOR="$(printf '%s\n' "$NARR_LINES" | jq -rs 'map(.ts) | max // empty' 2>/dev/null || true)"
+      [[ -n "$NARR_NEW_CURSOR" ]] && printf '%s' "$NARR_NEW_CURSOR" > "$NARR_CURSOR_FILE"
+    fi
+  ) 8>"$NARR_CURSOR_FILE.lock" || true
+fi
+
+# ---- meetless MCP-call capture (P1) -------------------------------------
+# Record the agent's own evidence pulls before the Bash path. These land in a
+# LOCAL file (not the Control spool) since A1 joins them against the local
+# enrichment trace; keeping them out of the queue also leaves the Bash spool
+# contract untouched.
+if [[ "$TOOL" == mcp__meetless__meetless__* ]]; then
+  MCP_TOOL="${TOOL##*meetless__}"
+  # Evidence-bearing pulls vs actions. relationship_verdict mutates governance
+  # state; it is NOT a Pull for A1a. The three read tools return cited evidence.
+  case "$MCP_TOOL" in
+    retrieve_knowledge|kb_doc_detail|query) EVIDENCE_TOOL=true ;;
+    *) EVIDENCE_TOOL=false ;;
+  esac
+  QUERY="$(echo "$INPUT" | jq -r '.tool_input.query // .tool_input.question // .tool_input.citation // ""')"
+  # Scan both the call args and its result for citation tokens (the source_ids
+  # the agent actually touched). tojson keeps object/array/string shapes flat
+  # and preserves the literal [XX:id] tokens; extract_source_ids (common.sh) is
+  # the one shared grammar across the pull and push-reference sides.
+  SCAN="$(echo "$INPUT" | jq -r '{i: .tool_input, r: (.tool_response // .tool_result)} | tojson')"
+  SOURCE_IDS_JSON="$(extract_source_ids "$SCAN")"
+  # Attribute to the CURRENT turn (read, never advance: next_turn_index is owned
+  # by UserPromptSubmit). mkdir guards a tool call arriving before any prompt.
+  mkdir -p "$QUEUE_DIR" "$LOG_DIR"
+  TURN="$(current_turn_index "$SESSION_ID")"
+  TS="$(date -u +%FT%TZ)"
+  LINE="$(jq -c -n \
+    --arg ts "$TS" --arg event "tool_used_mcp" \
+    --arg sessionId "$SESSION_ID" --argjson turn "$TURN" \
+    --arg tool "$MCP_TOOL" --argjson evidence "$EVIDENCE_TOOL" \
+    --arg query "$QUERY" --argjson sids "$SOURCE_IDS_JSON" \
+    '{ts: $ts, event: $event, session_id: $sessionId, turn_index: $turn, tool: $tool, evidence_tool: $evidence, query: $query, source_ids: $sids}')"
+  (
+    flock 9
+    printf '%s\n' "$LINE" >> "$LOG_DIR/mcp-calls.jsonl"
+  ) 9>"$LOG_DIR/mcp-calls.lock"
+
+  # ---- InjectionTrace parity for the MCP surface (P0.2, design §7.6) --------
+  # MCP grounding is an INJECTION surface: an evidence-bearing pull returns cited
+  # relationships INTO this turn's context. The stateless MCP server has no session
+  # identity, but THIS hook does (SESSION_ID + the read-only TURN), so it is the
+  # one place that can emit an InjectionTrace-compatible record for the MCP path,
+  # reconciled to the run by riding its own session's event stream (the SAME spool
+  # + flush pipeline as the HOOK producer in user-prompt-submit.sh). Without it the
+  # session-detail "Injected" lane reads empty for an MCP-grounded run even though
+  # relationships were injected -- which is the exact dishonesty §7.6 makes P0.
+  #
+  # Lean §7.6 superset: contextItems are the citation tokens the grounding actually
+  # returned (no kind/status/confidence agentic enrichment), sourceSurface=MCP tells
+  # the console it is reading the lean shape. Emit ONLY on a REAL injection: an
+  # evidence tool that returned >=1 cited source (a pull with no citation injected
+  # nothing; relationship_verdict is an ACTION, EVIDENCE_TOOL=false, never an
+  # injection). deliveryStatus is stamped INJECTED HERE, by the surface, at the
+  # delivery moment (INV-INJECTIONTRACE-DELIVERY). The injectId IS the eventKey
+  # (minted once, replayed byte-identical on a re-flush so control's 6-tuple
+  # idempotency no-ops the retry); traceId reuses it since the MCP pull has no
+  # separate enrich trace id. Best-effort and fail-soft: a jq failure omits the
+  # record and never disturbs the local pull capture above.
+  if [[ "$EVIDENCE_TOOL" == "true" ]]; then
+    IT_ITEMS="$(printf '%s' "$SOURCE_IDS_JSON" | jq -c \
+      '[ (. // []) | unique | .[] | select(. != "") | {source_id: ., injected: true} ]' \
+      2>/dev/null || printf '[]')"
+    IT_COUNT="$(printf '%s' "$IT_ITEMS" | jq 'length' 2>/dev/null || printf 0)"
+    if [[ "${IT_COUNT:-0}" -gt 0 ]]; then
+      IT_KEY="$(gen_event_key)"
+      IT_LINE="$(jq -c -n \
+        --arg ts "$TS" --arg key "$IT_KEY" --arg session_id "$SESSION_ID" \
+        --argjson turn "${TURN:-0}" --argjson items "$IT_ITEMS" \
+        '{
+          ts: $ts, event: "injection_trace", eventKey: $key, sessionId: $session_id,
+          payload: {
+            sourceSurface: "MCP", turnIndex: $turn, injectId: $key, traceId: $key,
+            deliveryStatus: "INJECTED", schemaVersion: 1, status: null, confidence: null,
+            contextItems: $items, markdown: null, capturedAt: $ts
+          }
+        }' 2>/dev/null || true)"
+      [[ -n "$IT_LINE" ]] && spool_append "$SESSION_ID" "$IT_LINE"
+    fi
+  fi
+  exit 0
+fi
+
+# ---- AskUserQuestion agent-decision capture (provider-neutral) -----------
+# Claude's AskUserQuestion bundles N questions in one tool call; each ANSWERED
+# question becomes one first-class, auditable agent-human decision. Hand the raw
+# hook payload (tool_input.questions + tool_response.answers + tool_use_id) to the
+# `mla _internal capture-decisions` Claude normalizer, which emits one
+# `agent_decision_captured` spool event per answered question (providerEventId =
+# "<tool_use_id>#<questionIndex>"). The command is an IO-light PURE transform and
+# touches NO spool itself; ALL spool locking stays HERE so the single-writer
+# invariant lives in one place. Passing --spool lets the command dedup against
+# eventKeys already queued this session (the Stop transcript-scan backstop writes
+# the same keys), so a re-fired PostToolUse never double-spools the same decision.
+# Capture is assistive: every failure is swallowed and never breaks the session.
+# See notes/20260608-agent-decision-capture-design.md section 5.
+if [[ "$TOOL" == "AskUserQuestion" ]]; then
+  if [[ -n "${MLA_PATH:-}" && -x "$MLA_PATH" ]]; then
+    DECISION_LINES="$(printf '%s' "$INPUT" | "$MLA_PATH" _internal capture-decisions \
+      --source post_tool_use --session "$SESSION_ID" \
+      --spool "$QUEUE_DIR/$SESSION_ID.jsonl" 2>/dev/null || true)"
+    while IFS= read -r DECISION_LINE; do
+      [[ -z "$DECISION_LINE" ]] && continue
+      spool_append "$SESSION_ID" "$DECISION_LINE"
+    done <<< "$DECISION_LINES"
+  fi
+  exit 0
+fi
+
+# ---- Governed trace: tool_used_file on file-modifying tools ---------------
+# Dogfood-audit 2026-06-10 issue 3: tool capture was bash-only, so a code-only
+# session (all Write/Edit, no Bash) left ZERO governed tool trace in control.
+# Spool ONE metadata-only event per file-modifying call: {tool, filePath}. No
+# file content, no diff, no tool I/O (the v0 privacy boundary stays intact; a
+# path is milder evidence than the stdout/stderr tails the Bash spool ships).
+#
+# This is the PRIMARY governed artifact for a file-modifying turn, so it spools
+# FIRST -- ahead of the assistive A2 produced-doc and DUR blocks below. Both of
+# those can early-exit under `set -euo pipefail` (DUR exits 0 in every path; A2
+# walks marker trees and can abort), and anything placed after such a block
+# never executes. Capturing the governed fact before any best-effort enrichment
+# is what keeps the trace immune to a downstream abort (the prose-outside-marker
+# regression that the dogfood-audit follow-up locked).
+if [[ "$TOOL" == "Edit" || "$TOOL" == "Write" || "$TOOL" == "MultiEdit" || "$TOOL" == "NotebookEdit" ]]; then
+  FILE_TRACE_PATH="$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // .tool_input.notebook_path // empty')"
+  if [[ -n "$FILE_TRACE_PATH" ]]; then
+    TS="$(date -u +%FT%TZ)"
+    EVENT_KEY="$(gen_event_key)"
+    LINE="$(jq -c -n \
+      --arg ts "$TS" --arg event "tool_used_file" --arg key "$EVENT_KEY" \
+      --arg sessionId "$SESSION_ID" --arg tool "$TOOL" --arg fp "$FILE_TRACE_PATH" \
+      '{ts: $ts, event: $event, eventKey: $key, sessionId: $sessionId, payload: {tool: $tool, filePath: $fp}}')"
+    spool_append "$SESSION_ID" "$LINE"
+  fi
+fi
+
+# ---- Read-side knowledge trace: tool_used_file with access:"read" ---------
+# Session Files rail Phase 2 (notes/20260616-session-files-rail-design.md). The
+# rail's "read by the agent" lane needs to know which PROSE files the agent
+# opened; Read/Grep/Glob otherwise emit nothing. Spool ONE metadata-only
+# tool_used_file per markdown Read, tagged access:"read" so the console routes it
+# to the read lane (not produced) and the timeline labels it "Read a file" rather
+# than "Edited a file". Gate STRICTLY to prose_path_allowed (the same allowlist
+# the input/produced lanes use) so a code Read spools nothing and the stream is
+# not flooded with every source-file open. Metadata only ({tool, filePath,
+# access}), never file content. exit 0 keeps this read trace self-contained: the
+# assistive A2 / DUR / Bash blocks below only handle modifying tools and Bash.
+if [[ "$TOOL" == "Read" ]]; then
+  READ_TRACE_PATH="$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // empty')"
+  if [[ -n "$READ_TRACE_PATH" ]] && prose_path_allowed "$READ_TRACE_PATH"; then
+    TS="$(date -u +%FT%TZ)"
+    EVENT_KEY="$(gen_event_key)"
+    LINE="$(jq -c -n \
+      --arg ts "$TS" --arg event "tool_used_file" --arg key "$EVENT_KEY" \
+      --arg sessionId "$SESSION_ID" --arg tool "$TOOL" --arg fp "$READ_TRACE_PATH" \
+      '{ts: $ts, event: $event, eventKey: $key, sessionId: $sessionId, payload: {tool: $tool, filePath: $fp, access: "read"}}')"
+    spool_append "$SESSION_ID" "$LINE"
+  fi
+  exit 0
+fi
+
+# ---- Route 4: A2 produced/updated-doc capture (Zone 1, Phase 0) ----------
+# Mark prose docs the agent wrote/edited this turn into the Active Review store.
+# Pure local append: no detector, no KB write, no network. The envelope carries
+# the real ownerUserId/workspaceId (never placeholders) so Phases 3-5 never
+# migrate. Silence by default. Spec tests 1,2,7,24,40,41.
+#
+# ASSISTIVE + best-effort, so the whole block runs in a subshell guarded by
+# `|| true`. NOTHING inside can abort the parent hook under `set -euo pipefail`:
+# not meetless_repo_root returning 1 for a file outside every marker, not a
+# content_hash shasum failure on an unreadable file (non-zero under pipefail),
+# not a failed record_active_memory write, not any future addition. The primary
+# tool_used_file trace already spooled ABOVE, so a hard abort here costs at most
+# this turn's prose enrichment, never the governed trace and never a non-zero
+# PostToolUse exit. Vars set here intentionally do not leak; no later block reads
+# A2_*.
+(
+  case "$TOOL" in
+    Write|Edit|MultiEdit|NotebookEdit)
+      A2_FILE="$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // .tool_input.notebook_path // empty')"
+      if [[ -n "$A2_FILE" ]] && prose_path_allowed "$A2_FILE"; then
+        A2_ROOT="$(meetless_repo_root "$(dirname "$A2_FILE")")"
+        if [[ -n "$A2_ROOT" && -f "$A2_FILE" ]]; then
+          # T1.2 cutover: the produced doc belongs to the workspace of the folder
+          # it LIVES in (nearest-wins for the edited file), not the cli-config one
+          # and not necessarily the session's marker. A2_ROOT is that marker's dir.
+          A2_WS="$(jq -r '.workspaceId // empty' "$A2_ROOT/.meetless.json" 2>/dev/null)"
+          A2_OWNER="$(jq -r '.actorUserId // empty' "$CFG" 2>/dev/null)"
+          if [[ -n "$A2_WS" && -n "$A2_OWNER" ]]; then
+            A2_TURN="$(current_turn_index "$SESSION_ID")"
+            A2_RRH="$(repo_root_hash "$A2_ROOT")"
+            A2_CPATH="$(canonical_path "$A2_ROOT" "$A2_FILE")"
+            A2_CHASH="$(content_hash "$A2_FILE")"
+            record_active_memory "produced_doc" "$SESSION_ID" "$A2_TURN" "$A2_WS" "$A2_OWNER" "$A2_RRH" "$A2_CPATH" "$A2_CHASH" "$A2_ROOT"
+          fi
+        fi
+      fi
+      ;;
+  esac
+) || true
+
+# ---- DUR: just-in-time coordination flag on a governed-surface edit (§5.4 DURING)
+# When the agent edits/writes a file, raise an ADVISORY flag iff a high-confidence
+# coordination trigger from THIS turn names the surface being touched ("this
+# surface is governed by X") at the moment of the edit, not a judgment of the edit
+# itself. Reuses the BEFORE-turn imperative's rung-2 contract: turn-keyed state +
+# the closed CoordinationTrigger enum + the P5 high-confidence floor. It NEVER
+# blocks (P6 "never its hands"): it emits hookSpecificOutput.additionalContext,
+# never `decision: "block"`. Dormant by default in prod (detectors are the producer
+# of coordination_triggers and are mostly unwired, so no state file is written and
+# this no-ops). See notes/20260603-mla-kb-agent-proxy-and-evidence-adoption.md §5.4
+# / §6 #9 / §7.2 row "DUR".
+if [[ "$TOOL" == "Edit" || "$TOOL" == "Write" || "$TOOL" == "MultiEdit" || "$TOOL" == "NotebookEdit" ]]; then
+  # Kill switch (default on; set MEETLESS_COORDINATION_DURING=0 to silence).
+  [[ "${MEETLESS_COORDINATION_DURING:-1}" == "0" ]] && exit 0
+
+  FILE_PATH="$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_input.notebook_path // empty')"
+  [[ -z "$FILE_PATH" ]] && exit 0
+
+  STATE_FILE="$(coordination_state_file "$SESSION_ID")"
+  [[ -f "$STATE_FILE" ]] || exit 0
+
+  # Turn-match: stale state from a prior turn must NOT fire. current_turn_index
+  # peeks the turn UserPromptSubmit set; PostToolUse never advances it, so a
+  # mid-turn edit shares the enriched turn's index and an older file fails here.
+  STATE_TURN="$(jq -r '.turn_index // empty' "$STATE_FILE" 2>/dev/null || true)"
+  CUR_TURN="$(current_turn_index "$SESSION_ID" 2>/dev/null || printf 0)"
+  [[ -n "$STATE_TURN" && "$STATE_TURN" == "$CUR_TURN" ]] || exit 0
+
+  # P5 high-confidence floor (the same boundary the BEFORE-turn imperative holds;
+  # a trigger on a low/medium-confidence turn stays passive).
+  STATE_CONF="$(jq -r '.confidence // empty' "$STATE_FILE" 2>/dev/null || true)"
+  [[ "$STATE_CONF" == "high" ]] || exit 0
+
+  # Match the edited surface against this turn's triggers, hard-filtered to the
+  # closed enum (a malformed or injected type can never fire). The trigger surface
+  # is repo-relative; suffix-match it against the absolute edited path.
+  STATE_TRIGGERS="$(jq -c '.triggers // []' "$STATE_FILE" 2>/dev/null || printf '[]')"
+  MATCHED="$(printf '%s' "$STATE_TRIGGERS" | jq -c \
+    --arg fp "$FILE_PATH" --argjson enum "$COORDINATION_TRIGGER_ENUM" '
+      map(select(.type as $t | $enum | index($t)))
+      | map(select(.surface as $s
+          | ($s != null and $s != "")
+            and (($fp == $s) or ($fp | endswith("/" + $s)))))
+    ' 2>/dev/null || printf '[]')"
+  MATCH_COUNT="$(printf '%s' "$MATCHED" | jq 'length' 2>/dev/null || printf 0)"
+  [[ "${MATCH_COUNT:-0}" -gt 0 ]] || exit 0
+
+  # No spam: flag a given surface at most once per session.
+  mkdir -p "$(coordination_dir)" 2>/dev/null || true
+  FLAGGED_FILE="$(coordination_flagged_file "$SESSION_ID")"
+  if [[ -f "$FLAGGED_FILE" ]] && grep -qxF "$FILE_PATH" "$FLAGGED_FILE" 2>/dev/null; then
+    exit 0
+  fi
+  (
+    flock 9
+    printf '%s\n' "$FILE_PATH" >> "$FLAGGED_FILE"
+  ) 9>"$FLAGGED_FILE.lock"
+
+  STATE_TRACE="$(jq -r '.trace_id // ""' "$STATE_FILE" 2>/dev/null || true)"
+  COORD_LINES="$(printf '%s' "$MATCHED" | jq -r '.[] |
+    "  - " + .type + (if (.ref // "") != "" then " -> " + .ref else "" end)' 2>/dev/null || true)"
+  CTX="<meetless-context kind=\"coordination\" surface=\"$FILE_PATH\" trace=\"$STATE_TRACE\">
+You just edited a governed surface (just-in-time coordination flag): $FILE_PATH
+Coordination applies before you rely on this change:
+$COORD_LINES
+This is a Meetless governance directive (computed server-side, not retrieved text). It is a reminder, not a block: Meetless never stops your tools. Pull the cited decision with meetless__kb_doc_detail and confirm the accountable owner signed off before you rely on this change.
+</meetless-context>"
+  jq -n --arg ctx "$CTX" \
+    '{hookSpecificOutput:{hookEventName:"PostToolUse",additionalContext:$ctx}}'
+  exit 0
+fi
+
+[[ "$TOOL" != "Bash" ]] && exit 0
+
+CMD="$(echo "$INPUT" | jq -r '.tool_input.command // ""')"
+EXIT_CODE="$(echo "$INPUT" | jq -r '.tool_result.exit_code // .tool_response.exit_code // empty')"
+# Smaller-C: normalize empty/non-numeric to 0 BEFORE --argjson (jq dies on non-numeric).
+if ! [[ "${EXIT_CODE:-}" =~ ^[0-9]+$ ]]; then EXIT_CODE=0; fi
+# Truncate inside jq (codepoint-aware) so multibyte UTF-8 in tool output (e.g.
+# Vietnamese console.log strings, emoji, accented test names) is never split
+# mid-sequence. `tail -c 2000` cuts on bytes, which on a 3-byte vi character
+# produces invalid UTF-8 that downstream jq --arg + Prisma JSON storage may
+# silently corrupt or reject.
+STDOUT_TAIL="$(echo "$INPUT" | jq -r '(.tool_result.stdout // .tool_response.stdout // "")[-2000:]')"
+STDERR_TAIL="$(echo "$INPUT" | jq -r '(.tool_result.stderr // .tool_response.stderr // "")[-2000:]')"
+TS="$(date -u +%FT%TZ)"
+EVENT_KEY="$(gen_event_key)"
+
+# Smaller-D: HINT only. The WORKER re-categorizes authoritatively from CMD.
+CATEGORY_HINT="$(printf '%s' "$CMD" | awk '
+  /pytest|jest|vitest|mocha|go test|cargo test|pnpm test|npm test|yarn test/ {print "test"; exit}
+  /tsc|mypy|pyright/                                                        {print "typecheck"; exit}
+  /eslint|ruff|flake8|prettier --check/                                     {print "lint"; exit}
+  /build|webpack|vite build|tsc -b|next build/                              {print "build"; exit}
+  /prisma migrate|alembic|knex migrate/                                     {print "migration"; exit}
+  /npm i|pnpm i|pnpm add|yarn add|pip install|poetry add/                   {print "package_install"; exit}
+  /^git /                                                                    {print "git"; exit}
+  {print "unknown_bash"}
+')"
+
+LINE="$(jq -c -n \
+  --arg ts "$TS" --arg event "tool_used_bash" --arg key "$EVENT_KEY" \
+  --arg sessionId "$SESSION_ID" --arg cmd "$CMD" --arg hint "$CATEGORY_HINT" \
+  --arg out "$STDOUT_TAIL" --arg err "$STDERR_TAIL" --argjson exit "$EXIT_CODE" \
+  '{ts: $ts, event: $event, eventKey: $key, sessionId: $sessionId, payload: {categoryHint: $hint, command: $cmd, exitCode: $exit, stdoutTail: $out, stderrTail: $err}}')"
+
+spool_append "$SESSION_ID" "$LINE"
+
+exit 0

package/dist/hooks-template/pre-tool-use.sh

@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+# pre-tool-use.sh: Claude Code PreToolUse hook (R1 notes-location enforcement, A1).
+#
+# Scope (registered by wire.ts MANAGED_HOOK_SCRIPTS with matcher "^(Write|Edit)$"):
+# fires only before a Write or Edit tool call. It hands the raw PreToolUse stdin to
+# `mla _internal pretool-observe`, which runs the version-backed enforce seam and
+# prints the hook response: either the empty `{}` pass-through, or a real deny body
+# when a human-attested LIVE rule version is VIOLATED and the deny is admitted.
+#
+# This wrapper FORWARDS that response verbatim. The decision is computed by the
+# subcommand (against a human-attested version), never by this script and never
+# reflected from input. The subcommand always exits 0 and prints exactly one JSON
+# body, so a non-empty stdout is a real, computed decision and is safe to relay.
+#
+# Fail open, always. No `set -e`: every step is best-effort. If `mla` is missing,
+# crashes, hangs past the timeout, or prints nothing, this wrapper emits the empty
+# `{}` pass-through and exits 0. A non-zero exit (especially 2) would BLOCK the tool,
+# so this script NEVER exits non-zero: the decision rides the body, never the code.
+
+INPUT="$(cat 2>/dev/null || true)"
+
+# Resolve the absolute mla path the same way common.sh does (install-time path in
+# cli-config.json, then PATH fallback). MLA in PATH is not relied upon.
+CFG="${MEETLESS_HOME:-$HOME/.meetless}/cli-config.json"
+MLA_PATH="$(jq -r '.mlaPath // empty' "$CFG" 2>/dev/null || true)"
+if [[ -z "${MLA_PATH:-}" || ! -x "$MLA_PATH" ]]; then
+  MLA_PATH="$(command -v mla 2>/dev/null || true)"
+fi
+
+# Run a command under a wall-clock guard so a slow or stuck evaluation degrades to
+# pass-through rather than hanging the tool. GNU `timeout` (or `gtimeout` from
+# coreutils on macOS) is used when present; otherwise the command runs unguarded.
+run_guarded() {
+  if command -v timeout >/dev/null 2>&1; then
+    timeout 5 "$@"
+  elif command -v gtimeout >/dev/null 2>&1; then
+    gtimeout 5 "$@"
+  else
+    "$@"
+  fi
+}
+
+# Prefer the minimal sibling entrypoint (`pretool-entry.js`, emitted next to the
+# resolved mla binary) when present: it pays only the deny-decision require graph
+# (~12ms cold) instead of cli.js's full command registry (~150ms), the latency
+# lever from notes/20260615-...-consolidated-proposal.md. Both transports call the
+# identical runInternalPretoolObserve core, so the decision body is byte-identical.
+# When the sibling is absent (a pkg binary, an older install), fall back to
+# `mla _internal pretool-observe` so the slow path stays correct. It is run the same
+# way as mla (its `#!/usr/bin/env node` shebang resolves node), under the same guard.
+RESPONSE=""
+if [[ -n "${MLA_PATH:-}" && -x "$MLA_PATH" ]]; then
+  PRETOOL_ENTRY="$(dirname "$MLA_PATH")/pretool-entry.js"
+  if [[ -x "$PRETOOL_ENTRY" ]]; then
+    RESPONSE="$(printf '%s' "$INPUT" | run_guarded "$PRETOOL_ENTRY" 2>/dev/null || true)"
+  else
+    RESPONSE="$(printf '%s' "$INPUT" | run_guarded "$MLA_PATH" _internal pretool-observe 2>/dev/null || true)"
+  fi
+fi
+
+# Forward the computed decision body if there is one; otherwise fall open to the
+# empty no-decision body. Stripping whitespace guards against a stray newline-only
+# stdout being mistaken for a real response.
+if [[ -n "${RESPONSE//[[:space:]]/}" ]]; then
+  printf '%s' "$RESPONSE"
+else
+  printf '{}'
+fi
+exit 0

package/dist/hooks-template/session-start.sh

@@ -0,0 +1,140 @@
+#!/usr/bin/env bash
+# session-start.sh: Claude Code SessionStart hook.
+# Writes a session_started event to the spool and spawns a detached flush.
+#
+# Source: notes/20260527-bare-bones-mvp-codebase-evaluation-and-plan.md §5.2.
+source "$(dirname "$0")/common.sh"
+
+# Per-folder activation gate (opt-in). In an ACTIVATED repo we fall through to
+# capture. In an UNACTIVATED repo we no longer exit silently: hand off to the CLI
+# (which reuses the SAME marker resolver as `mla mcp`) to surface a one-line
+# SessionStart explanation when warranted (logged-in git repos only); its stdout
+# becomes Claude Code's additionalContext. No capture happens without a marker.
+# See meetless_activated in common.sh. Run `mla activate` in a repo to opt in.
+if ! meetless_activated; then
+  if [[ -n "${MLA_PATH:-}" && -x "$MLA_PATH" ]]; then
+    "$MLA_PATH" _internal session-nudge --cwd "$PWD" 2>/dev/null || true
+  fi
+  exit 0
+fi
+
+# Self-healing prune of dead hook entries in ~/.claude/settings.json.
+# Background: hook entries can leak when temp worktrees (test fixtures, Claude
+# Code worktrees, manual sandboxes) install themselves but skip cleanup on
+# teardown. Without this, failed Stop / PostToolUse / etc. accumulate forever
+# and Claude Code logs "Failed with non-blocking status code" on every event.
+# Detection: walk every hook entry's `command` field; if it's a plain absolute
+# path and does not exist on disk, drop that entry. Skips non-path commands
+# (`pkill ...`, `~/.claude/...`, shell expressions). Whole block is best-effort
+# and silenced so it can NEVER fail the hook.
+{
+  __ml_settings="$HOME/.claude/settings.json"
+  if [[ -f "$__ml_settings" ]]; then
+    __ml_dead="$(jq -r '.hooks // {} | to_entries[] | .value[]? | .hooks[]?.command // empty' "$__ml_settings" 2>/dev/null \
+      | while IFS= read -r __cmd; do
+          [[ "$__cmd" =~ ^/[^[:space:]]+$ ]] && [[ ! -e "$__cmd" ]] && printf '%s\n' "$__cmd"
+        done)"
+    if [[ -n "$__ml_dead" ]]; then
+      __ml_dead_json="$(printf '%s\n' "$__ml_dead" | jq -R . | jq -s .)"
+      __ml_tmp="$__ml_settings.tmp.$$"
+      cp "$__ml_settings" "$__ml_settings.bak.meetless-prune-$(date +%Y%m%d-%H%M%S)" 2>/dev/null
+      if jq --argjson dead "$__ml_dead_json" '.hooks |= with_entries(.value |= map(select(([.hooks[]?.command] | map(tostring) | any(. as $c | $dead | index($c))) | not)))' "$__ml_settings" > "$__ml_tmp" 2>/dev/null \
+         && jq empty "$__ml_tmp" 2>/dev/null; then
+        mv "$__ml_tmp" "$__ml_settings"
+      else
+        rm -f "$__ml_tmp" 2>/dev/null
+      fi
+    fi
+  fi
+} 2>/dev/null || true
+
+INPUT="$(cat)"
+# Wedge v6 Epoch 29: validate stdin parses as JSON BEFORE any jq substitution.
+# Pre-fix the bare `SESSION_ID="$(echo "$INPUT" | jq -r ...)"` crashed under
+# `set -euo pipefail` on empty stdin or malformed JSON: jq exits non-zero, the
+# substitution propagates, the hook aborts BEFORE the empty-session-id guard
+# below. Claude Code interprets that non-zero exit as a hook failure.
+if [[ -z "$INPUT" ]] || ! printf '%s' "$INPUT" | jq -e . >/dev/null 2>&1; then
+  exit 0
+fi
+SESSION_ID="$(echo "$INPUT" | jq -r '.session_id // empty')"
+[[ -z "$SESSION_ID" ]] && exit 0
+# Per-session OFF override (`mla deactivate`). Silences this one session even in
+# an activated folder. See meetless_session_disabled in common.sh.
+meetless_session_disabled "$SESSION_ID" && exit 0
+
+TRANSCRIPT="$(echo "$INPUT" | jq -r '.transcript_path // empty')"
+CWD="$PWD"
+BRANCH="$(git -C "$CWD" rev-parse --abbrev-ref HEAD 2>/dev/null || echo unknown)"
+TS="$(date -u +%FT%TZ)"
+EVENT_KEY="$(gen_event_key)"
+
+# Best-effort current session name. A RESUMED session (`--resume` / `--continue`)
+# starts with a transcript that already carries a title, so SessionStart is the
+# earliest moment control can learn it (F3-A). Mirrors the local picker: human
+# /title (`custom-title`) wins, else the auto-titler's name (`ai-title`). A brand
+# -new session has neither, leaving the title empty; control's no-clobber guard
+# keeps any prior name. See resolve_session_title in common.sh.
+SESSION_TITLE="$(resolve_session_title "$TRANSCRIPT")"
+
+LINE="$(jq -c -n \
+  --arg ts "$TS" --arg event "session_started" --arg key "$EVENT_KEY" \
+  --arg sessionId "$SESSION_ID" --arg transcript "$TRANSCRIPT" \
+  --arg cwd "$CWD" --arg branch "$BRANCH" --arg title "$SESSION_TITLE" \
+  '{ts: $ts, event: $event, eventKey: $key, sessionId: $sessionId, payload: {transcriptPath: $transcript, repoPath: $cwd, branch: $branch, sessionTitle: $title}}')"
+
+# Wedge v6 Epoch 35: repoPath sidecar. flush.sh is nohup-spawned by hooks,
+# so its cwd is whatever nohup ran in (often $HOME) -- NOT the repo. Without
+# this sidecar, `mla _internal finalize-session` falls back to process.cwd(),
+# captureGitEvidence returns empty topLevel, the Epoch 33 guard refuses to
+# POST, finalize_requested is re-spooled, and the next flush re-fails the
+# same way. Permanent stuck-loss until the user manually runs `mla flush`
+# from inside the repo. The sidecar captures the SessionStart $CWD (Claude
+# Code fires the hook with cwd = the project root) so flush.sh can export
+# MEETLESS_REPO_PATH for the CLI to consume. Written BEFORE spool_append so
+# the detached flush sees it on first try.
+printf '%s' "$CWD" > "$QUEUE_DIR/$SESSION_ID.repoPath"
+
+# T1.2 hard cutover (folder = workspace): workspaceId sidecar. The marker is the
+# ONLY source of the workspaceId, and the nohup-detached flusher cannot walk up
+# to it (cwd=$HOME would always miss the repo marker). meetless_activated above
+# resolved WORKSPACE_ID from this session's marker; snapshot it here so flush.sh
+# wraps every POST under the marker id, never a stale cli-config value. Written
+# BEFORE spool_append so the detached flush sees it on first try; flush.sh removes
+# it after a successful finalize, alongside .repoPath and .gitBaseline.
+printf '%s' "$WORKSPACE_ID" > "$QUEUE_DIR/$SESSION_ID.workspaceId"
+
+# Wedge v6: git baseline sidecar. Records the working tree's dirty state at
+# SESSION START so finalize can subtract ambient changes (files already
+# modified/deleted/untracked before the agent ran) and attribute only what the
+# SESSION touched. Without this, `mla review` blamed pre-existing dirty state
+# (e.g. a stray `.claude/scheduled_tasks.lock` deletion) on the run. Same
+# `-c core.quotePath=false` + `--porcelain=v1` form as captureGitEvidence so the
+# exact-line subtraction matches. Best-effort: a non-repo $CWD writes an empty
+# file, which subtracts nothing (back-compatible).
+#
+# 2026-06-01 dogfood finding F-GIT-1 (RCA 20260531 §9.F): capture the baseline
+# ONCE per session. Claude Code re-fires SessionStart with the SAME session_id on
+# a CONTINUE / COMPACTION / RESUME. The old unconditional write re-captured the
+# baseline AFTER the prior turns' edits, freezing the agent's own work in as
+# "ambient" -- subtractBaseline then dropped it and `mla review` showed
+# "changed files: 0" on a session with real uncommitted edits. The guard below
+# preserves the true-start snapshot across resumes. flush.sh removes the sidecar
+# after a successful finalize, so the next genuine segment re-captures fresh
+# (the absent file IS the "this is a new start" signal).
+if [[ ! -e "$QUEUE_DIR/$SESSION_ID.gitBaseline" ]]; then
+  git -C "$CWD" -c core.quotePath=false status --porcelain=v1 \
+    > "$QUEUE_DIR/$SESSION_ID.gitBaseline" 2>/dev/null || \
+    : > "$QUEUE_DIR/$SESSION_ID.gitBaseline"
+fi
+
+spool_append "$SESSION_ID" "$LINE"
+spawn_flush "$SESSION_ID"
+
+# Sweep for Claude Code sessions whose transcript was deleted on disk and archive
+# the mirrored AgentRun. Claude Code has no "session deleted" event, so SessionStart
+# is the throttling tick for this disk-reconciliation sweep. Detached + kill-switched
+# (MEETLESS_SESSION_RECONCILE=0), so it can never delay or fail the hook.
+spawn_reconcile
+
+exit 0