FabledScribe/plugin/hooks/scribe_prior_art.sh

#!/usr/bin/env bash
# Scribe plugin — PreToolUse write-path trigger (prior-art recall).
#
# Auto-inject (scribe_autoinject.sh) fires on the operator's prompt. The moment
# reuse is actually lost is later: when the AGENT decides mid-task to write a
# helper. This hook fires there — on Write/Edit — and asks the operator's Scribe
# instance what prior art is already recorded for the target file: a snippet at
# that path or in its directory, plus snippets resembling the code about to be
# written. Titles + ids only, never bodies.
#
# The answer comes in two framings (#2708). A snippet recorded AT the exact
# file being edited is the SYNC class — "you are editing the recorded file;
# updating the record is part of the edit" — which is how records stay current
# on an instance with no forge connection (decision #2707). Everything else is
# the REUSE menu. The two dedup separately (see the state files below).
#
# It is also the shape ledger's write-path feed (#2791): it names the
# definitions being written (`shapes=`), and the server — only when the
# session has PULLED a snippet this code references or resembles — records
# them as instance rows, classified_by=hook. Evidence, not judgment; the
# context line says what landed so a wrong stamp is corrected in the moment.
#
# NEVER BLOCKS. It returns `additionalContext` with no `permissionDecision`, so
# the write proceeds untouched and Claude sees the note beside the tool result.
# Any failure — unconfigured, unreachable, malformed — exits 0 in silence. A
# recall aid must not be able to stop the operator's work.
#
# Config (same as the other hooks), exported to the hook by Claude Code with the
# userConfig key UPPERCASED (see #2198 — the lowercase spelling reads as empty
# and this hook then exits 0 in silence, looking exactly like "no prior art"):
#   CLAUDE_PLUGIN_OPTION_API_ENDPOINT  base URL, no trailing slash
#   CLAUDE_PLUGIN_OPTION_API_TOKEN     fmcp_ API key (sensitive)
#   SCRIBE_URL / SCRIBE_TOKEN override for the settings.json dogfooding path.
set -uo pipefail

command -v curl >/dev/null 2>&1 || exit 0

# Shared with the after-write hook (#2901): the prose/data skip list, the
# definition extractor and the local by-name duplicate arm live in
# scribe_defs.sh so the two hooks cannot drift apart. Sourced FIRST because the
# JSON reader is there too now (#4107).
# shellcheck source=plugin/hooks/scribe_defs.sh
. "$(dirname "${BASH_SOURCE[0]}")/scribe_defs.sh"

# PreToolUse delivers { session_id, cwd, tool_name, tool_input: {...}, ... }
# One parse, five fields. `.tool_input.content` on a Write is the entire file
# being written, so parsing per field would mean reading it five times.
event=$(cat 2>/dev/null || true)
event_flat=$(printf '%s' "$event" | scribe_json_flat)
file_path=$(scribe_json_pick "$event_flat" '.tool_input.file_path')
session_id=$(scribe_json_pick "$event_flat" '.session_id')
event_cwd=$(scribe_json_pick "$event_flat" '.cwd')

[ -n "$file_path" ] || exit 0

# The code about to be written. Write and Edit name this field differently, and
# the names have changed across Claude Code versions — take whichever is present
# rather than betting on one shape.
code=$(scribe_json_pick "$event_flat" '.tool_input.content')
[ -n "$code" ] || code=$(scribe_json_pick "$event_flat" '.tool_input.file_content')
[ -n "$code" ] || code=$(scribe_json_pick "$event_flat" '.tool_input.new_string')
[ -n "$code" ] || code=$(scribe_json_pick "$event_flat" '.tool_input.new_str')

scribe_skip_path "$file_path" && exit 0

# Snippet locations are recorded repo-relative, so send a repo-relative path —
# an absolute one would simply match nothing. Resolved BEFORE the config gate
# because the local arm below needs the repo root and needs no server at all.
lookup_dir=$(dirname -- "$file_path" 2>/dev/null || true)
[ -d "$lookup_dir" ] || lookup_dir=${event_cwd:-${CLAUDE_PROJECT_DIR:-$PWD}}
repo_root=$(git -C "$lookup_dir" rev-parse --show-toplevel 2>/dev/null || true)
rel_path="$file_path"
if [ -n "$repo_root" ]; then
  case "$file_path" in
    "$repo_root"/*) rel_path="${file_path#"$repo_root"/}" ;;
  esac
fi

# ARM 1 — BY NAME, LOCALLY (#2280): does a definition of this already exist
# in the repo? (scribe_local_dups in scribe_defs.sh carries the why.)
names=""
if [ -n "$code" ]; then
  # `|| true` inside: an early-exiting `head` must not void its own output (#4042).
  names=$(printf '%s' "$code" | scribe_defs | sort -u | head -12 || true)
fi

local_lines=""
if [ -n "$repo_root" ] && [ -n "$names" ]; then
  local_lines=$(scribe_local_dups "$repo_root" "$rel_path" <<< "$names") || local_lines=""
  [ -n "$local_lines" ] && local_lines="${local_lines}"$'\n'
fi

local_context=""
if [ -n "$local_lines" ]; then
  local_context="> Already defined elsewhere in this repo — check before adding another copy (\`git grep\` shown; this is a nudge, not a gate):"$'\n'"${local_lines}"
fi

# ---------------------------------------------------------------------------
# THE LEDGER FEED (#2791). The server keeps a shape ledger — every definition
# in the bound repo, classified against recorded canon — and this hook is the
# one place that sees a shape AT THE MOMENT IT IS WRITTEN. So it names the
# shapes in play: every definition in the payload, or — for an Edit that
# changes the inside of a function rather than its signature — the definition
# enclosing the edit, found by walking the target file upward from the edited
# lines. The server decides whether evidence exists (the session pulled a
# snippet this code references or resembles) and stamps instance rows; with
# no pulled canon in play, nothing is recorded. Titles only still — this sends
# names, not bodies.
# ---------------------------------------------------------------------------
#
# THE ENCLOSING DEFINITION IS THE LAST ONE AT OR ABOVE THE EDIT, and taking it
# needs no `tac`. This read `head -n $ln | tac | scribe_defs | head -1` — reverse
# the lines, extract, take the first. `tac` is GNU-only: it is absent on macOS
# (whose equivalent is `tail -r`), so the guard below it meant this arm did
# nothing at all on every Mac, silently, since the day it shipped. scribe_defs
# judges each line independently, so reversing first and taking the head is the
# same answer as extracting forward and taking the tail — and `tail` also drops
# the `head -1` whose early exit is the SIGPIPE trap #4042 was filed for.
shapes="$names"
if [ -z "$shapes" ] && [ -f "$file_path" ]; then
  old_first=$(scribe_json_pick "$event_flat" '.tool_input.old_string')
  [ -n "$old_first" ] || old_first=$(scribe_json_pick "$event_flat" '.tool_input.old_str')
  old_first=$(printf '%s' "$old_first" | grep -m1 -v '^[[:space:]]*$' || true)
  if [ -n "$old_first" ]; then
    ln=$(grep -nF -m1 -- "$old_first" "$file_path" 2>/dev/null | cut -d: -f1) || ln=""
    if [ -n "$ln" ]; then
      shapes=$(head -n "$ln" "$file_path" | scribe_defs | tail -1 || true)
    fi
  fi
fi
shapes_q=""
if [ -n "$shapes" ]; then
  enc=$(printf '%s\n' "$shapes" \
    | awk -F'\t' 'NF>=2 {printf "%s%s:%s", (n++?",":""), $1, $2}' \
    | scribe_urlenc) || enc=""
  [ -n "$enc" ] && shapes_q="&shapes=${enc}"
fi

scribe_config || :   # sets url/token; unconfigured is handled just below
# Unconfigured install → the recorded-prior-art arms are skipped, but the local
# arm above already ran and may have something to say.
if [ -z "$url" ] || [ -z "$token" ]; then
  if [ -n "$local_context" ]; then
    scribe_json_out PreToolUse "$local_context"
  fi
  exit 0
fi

# Cap the code sent as the semantic query. The embedder truncates at its own
# token limit well before this, so a bigger slice buys no extra signal — and the
# payload has to stay a GET (a read-scoped API key cannot POST, and every other
# plugin hook works with a read key).
# `head -c`, not `cut -c1-1200`: cut is line-oriented and caps each line
# separately, so a 400-line edit sailed past the "1200 char" budget entirely and
# built a URL from the whole payload. head -c caps the total, which is the point.
q=$(printf '%s' "$code" | head -c 1200)

# Encoded whole, never line by line. The predecessor (`jq -rR`) read input LINE
# BY LINE, so a multi-line payload came back as several separately-encoded lines
# joined by raw newlines — an invalid URL that made curl fail, and this hook then
# exited 0 in silence. Newlines are exactly what code contains, so this hook
# could never have worked that way (issue #2198 / #2082). scribe_urlenc reads
# bytes and has no notion of a line.
path_enc=$(printf '%s' "$rel_path" | scribe_urlenc)
[ -n "$path_enc" ] || exit 0
code_enc=$(printf '%s' "$q" | scribe_urlenc)

# Scope to this directory's project — a `.scribe` marker, else the git remote.
scope=$(scribe_scope_query "$lookup_dir")
repo_q=""
[ -n "$scope" ] && repo_q="&${scope}"

# Per-session dedup, in its own file rather than sharing auto-inject's. Each
# surface shows a given snippet at most once per session, but they don't silence
# each other: a title that flew past in a prompt menu twenty turns ago is
# exactly what should reappear at the moment the duplicate is being written.
#
# TWO channels, not one (#2708). The server answers in two classes — REUSE
# ("something similar/nearby is recorded") and SYNC ("a snippet records the
# exact file being edited — updating the record is part of the edit"). They
# dedup separately: a reuse hint shown early in the session must not suppress
# the sync nudge when the recorded file itself is edited later.
state_dir="${TMPDIR:-/tmp}/scribe-priorart"
mkdir -p "$state_dir" 2>/dev/null || true
#
# A THIRD channel (#2900): the ledger's derive arm names a duplicate family
# (a derive group id) or a canon elsewhere (`canon:<snippet_id>`) for the
# shapes being written. Keyed by that token, not a note id, so it dedups on
# its own file and a family is named once per session, not at every edit.
#
# A FOURTH channel (milestone 307): standing RULES the write resembles. Its own
# file for the same reason as the others — a rule named once should not be
# re-offered on every subsequent write in the session.
idfile=""
syncfile=""
derivefile=""
rulefile=""
exclude_q=""
sync_exclude_q=""
derive_exclude_q=""
rule_exclude_q=""
if [ -n "$session_id" ]; then
  safe_sid=$(printf '%s' "$session_id" | tr -c 'A-Za-z0-9._-' '_')
  # What this write defined, for the end-of-turn question (milestone 439). A
  # Write onto a path that does not exist yet creates a file, which may be a
  # unit in its own right (see scribe_written_append). Written before any
  # server call: the ask at the end of the turn must not depend on this
  # write's hint having been answered.
  fresh=""
  [ -e "$file_path" ] || fresh="new"
  printf '%s\n' "$shapes" | scribe_written_append "$safe_sid" "$rel_path" "$fresh" "$code"
  idfile="$state_dir/${safe_sid}.ids"
  syncfile="$state_dir/${safe_sid}.sync.ids"
  derivefile="$state_dir/${safe_sid}.derive.ids"
  rulefile="$state_dir/${safe_sid}.rules.ids"
  if [ -f "$idfile" ]; then
    seen=$(tr '\n' ',' < "$idfile" 2>/dev/null | sed 's/,$//')
    [ -n "$seen" ] && exclude_q="&exclude_ids=${seen}"
  fi
  if [ -f "$syncfile" ]; then
    sync_seen=$(tr '\n' ',' < "$syncfile" 2>/dev/null | sed 's/,$//')
    [ -n "$sync_seen" ] && sync_exclude_q="&exclude_sync_ids=${sync_seen}"
  fi
  if [ -f "$derivefile" ]; then
    derive_seen=$(tr '\n' ',' < "$derivefile" 2>/dev/null | sed 's/,$//' | scribe_urlenc) || derive_seen=""
    [ -n "$derive_seen" ] && derive_exclude_q="&exclude_derive=${derive_seen}"
  fi
  # Ageing, not a flat read (#3751), and the ONLY ledger here that ages: the
  # note channels above are a different question with a different answer, and
  # this arm's sibling hook reads the same rule file through the same helper.
  rule_seen=$(scribe_rules_live "$rulefile")
  [ -n "$rule_seen" ] && rule_exclude_q="&exclude_rule_ids=${rule_seen}"
  # What the session actually OPENED, as against what it was shown (#4100).
  rule_exclude_q="${rule_exclude_q}$(scribe_held_query "$state_dir/${safe_sid}.opened.ids")"
fi

# Not `|| exit 0`: an unreachable instance must not discard a local finding
# that needed no instance to produce. And not silence either (#2932): a call
# that was owed and didn't come back is said, once per outage, so the session
# knows this write went unchecked.
reached=1
body=$(curl -fsS --max-time 5 \
  -H "Authorization: Bearer ${token}" \
  "${url%/}/api/plugin/prior-art?path=${path_enc}&code=${code_enc}${repo_q}${exclude_q}${sync_exclude_q}${derive_exclude_q}${rule_exclude_q}${shapes_q}" 2>/dev/null) || { body=""; reached=0; }
unreached_context=""
if [ "$reached" = 1 ]; then
  scribe_reached "$state_dir" "${safe_sid:-nosession}"
else
  unreached_context=$(scribe_unreached "$state_dir" "${safe_sid:-nosession}" 5 "$rel_path")
fi

context=""
body_flat=""
if [ -n "$body" ]; then
  body_flat=$(printf '%s' "$body" | scribe_json_flat)
  context=$(scribe_json_pick "$body_flat" '.context')
  # Remember what was surfaced so it isn't shown again this session — each
  # class into its own channel: sync ids (snippets recording the edited file)
  # to the sync file, everything else to the reuse file.
  if [ -n "$context" ]; then
    if [ -n "$idfile" ]; then
      scribe_json_list_minus "$body_flat" '.note_ids' '.sync_note_ids' >> "$idfile" || true
    fi
    if [ -n "$syncfile" ]; then
      scribe_json_list "$body_flat" '.sync_note_ids' >> "$syncfile" || true
    fi
    if [ -n "$rulefile" ]; then
      scribe_json_list "$body_flat" '.rule_ids' | scribe_rules_append "$rulefile"
    fi
    if [ -n "$derivefile" ]; then
      scribe_json_list "$body_flat" '.derive_keys' >> "$derivefile" || true
    fi
  fi
fi

# ARM 1½ — the RECORD nudge (#2664). The local arm just proved the thing being
# written already exists elsewhere in this repo, and Scribe returned no record
# of anything for it. That is the one moment "record it" is earned rather than
# noise: the duplication is demonstrated, not guessed. Gated on BOTH sides so
# an ordinary new helper (no other copies) and an already-recorded one (the
# server spoke) stay nudge-free — a reflex that fires on everything is one
# that gets skipped. A server that did not ANSWER earns no nudge (#2932): "none
# of those copies is recorded" is a claim only an answer can back — the
# unreached line says what actually happened instead.
if [ -n "$local_lines" ] && [ "$reached" = 1 ]; then
  n_recorded=$(scribe_json_len "$body_flat" '.note_ids')
  if [ "${n_recorded:-0}" = "0" ] || [ "$n_recorded" = "" ]; then
    local_context="${local_context}"$'\n'"> None of those existing copies is recorded in Scribe. If the version being written is the canonical one — or this edit is consolidating the copies — record it now with create_snippet (name, code, when-to-reach-for-it, location) so the next session is offered it instead of writing another copy."
  fi
fi

# ---------------------------------------------------------------------------
# ARM 0 — THE CONTRACT AROUND THE CHANGE (#4215, milestone 419).
#
# "You altered the arity, name or shape of something — here is everything that
# reads it." Rule 33's interface-contract check one scope down: not between
# layers but between a definition and its callers.
#
# LOCAL AND SERVERLESS, like ARM 1. It needs the working tree and nothing
# else — the server has no checkout, so this is the only place the question
# can be asked at all.
#
# EDITS ONLY. The comparison is between what the definition exposed before and
# what it exposes now, so it needs both texts; a Write that creates a file has
# no "before" and nothing to break.
contract_context=""
if [ -n "$repo_root" ] && [ -n "$code" ]; then
  old_code=$(scribe_json_pick "$event_flat" '.tool_input.old_string')
  [ -n "$old_code" ] || old_code=$(scribe_json_pick "$event_flat" '.tool_input.old_str')
  # The SUBJECT is the definition whose contract may have moved. `shapes`
  # already holds either the definitions in the payload or — for an edit
  # inside a function body — the one enclosing the edit, which is exactly the
  # thing whose callers matter. CSS rows are skipped: a class has readers, but
  # they are markup files and `scribe_local_dups` already speaks for those.
  subject=$(printf '%s\n' "$shapes" \
    | awk -F'\t' 'NF>=2 && $1!="css" {print $2; exit}')
  if [ -n "$old_code" ] && [ -n "$subject" ]; then
    contract_file=""
    [ -n "${safe_sid:-}" ] && contract_file="$state_dir/${safe_sid}.contract.ids"
    contract_context=$(scribe_contract_block \
      "$repo_root" "$rel_path" "$subject" "$old_code" "$code" "$contract_file" \
      2>/dev/null) || contract_context=""
  fi
fi

# CONTRACT FIRST of the three, and the order is the strength of the claim.
# This one says something may already be BROKEN by the edit in hand. The local
# arm says a copy exists. The recorded arms say something resembles this. A
# reader who reads one line should read that one.
combined="$contract_context"
if [ -n "$local_context" ]; then
  [ -n "$combined" ] && combined="${combined}"$'\n'
  combined="${combined}${local_context}"
fi
if [ -n "$context" ]; then
  [ -n "$combined" ] && combined="${combined}"$'\n'
  combined="${combined}${context}"
fi
if [ -n "$unreached_context" ]; then
  [ -n "$combined" ] && combined="${combined}"$'\n'
  combined="${combined}${unreached_context}"
fi
[ -n "$combined" ] || exit 0

# No permissionDecision: this is a nudge, not a gate. The write goes ahead.
scribe_json_out PreToolUse "$combined"
exit 0