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).
#
# 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 jq   >/dev/null 2>&1 || exit 0
command -v curl >/dev/null 2>&1 || exit 0

# PreToolUse delivers { session_id, cwd, tool_name, tool_input: {...}, ... }
event=$(cat 2>/dev/null || true)
file_path=$(printf '%s' "$event" | jq -r '.tool_input.file_path // empty' 2>/dev/null) || exit 0
session_id=$(printf '%s' "$event" | jq -r '.session_id // empty' 2>/dev/null) || session_id=""
event_cwd=$(printf '%s' "$event" | jq -r '.cwd // empty' 2>/dev/null) || event_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=$(printf '%s' "$event" | jq -r '
  .tool_input.content // .tool_input.file_content //
  .tool_input.new_string // .tool_input.new_str // empty' 2>/dev/null) || code=""

# Skip formats that hold prose or data rather than reusable code. Purely to
# avoid a pointless round-trip — the server would return nothing for these
# anyway. Config formats are NOT skipped: a CI workflow or a compose file is
# often exactly the thing worth reusing.
case "$file_path" in
  *.md|*.mdx|*.txt|*.rst|*.json|*.lock|*.log|*.csv|*.tsv|*.svg|*.png|*.jpg|*.jpeg|*.gif|*.ico|*.pdf)
    exit 0 ;;
esac

# 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?
#
# The other two arms ask Scribe what was RECORDED. Scribe has never read a line
# of the codebase, so a helper nobody thought to record is invisible to them —
# which is how `.btn-primary` came to be defined four times, in four scoped
# stylesheets, already diverged. It was never a snippet, so no threshold and no
# query rewrite could ever have surfaced it.
#
# This arm closes that by asking the only question the record cannot answer,
# in the only place that can: the hook already runs on the developer's machine,
# inside the repo, holding the code about to be written. No index, no storage,
# no staleness, and no server — it deliberately runs even on an install that
# has never configured Scribe.
#
# Definition-shaped patterns only. Grepping for bare occurrences would match
# every CALL site and drown the real finding — and a hint that is mostly noise
# is one people learn to skip, which is worse than none.
#
# ALL code, not a language shortlist (#2682): the detector was born covering
# only the languages of the repo it was written in, which silently amputated
# this whole arm — and the record nudge gated on it — for every Go/Kotlin/Rust
# project. Definitions are announced by a small keyword family across
# languages (func/fun/fn/function/def/sub · class/struct/trait/interface/
# enum/object/protocol/type), so one modifier-strip + keyword match covers
# them all. Known out of scope: keyword-less declaration syntax (C/Java/Dart
# `ReturnType name(...)`) needs a real parser, and `impl` blocks are excluded
# because several per type is normal Rust, not duplication.
# ---------------------------------------------------------------------------
local_lines=""
if [ -n "$repo_root" ] && [ -n "$code" ]; then
  # kind<TAB>name for each thing this payload DEFINES.
  names=$(printf '%s' "$code" | awk '
    {
      # CSS class definition: .name { or .name,
      if (match($0, /^[[:space:]]*\.[A-Za-z][A-Za-z0-9_-]*[[:space:]]*[,{]/)) {
        t = $0; sub(/^[[:space:]]*\./, "", t); sub(/[[:space:]]*[,{].*$/, "", t)
        if (t != "") print "css\t" t; next
      }
      line = $0; sub(/^[[:space:]]+/, "", line)
      # Strip leading declaration modifiers so the definition keyword is the
      # first word regardless of language (export/pub/private/suspend/...).
      sub(/^((pub(\([a-z]+\))?|export|default|private|internal|protected|public|static|suspend|async|open|sealed|data|abstract|final|inline|unsafe|extern|override)[[:space:]]+)*/, "", line)
      # Go method with receiver: func (r *T) Name(
      if (match(line, /^func[[:space:]]*\([^)]*\)[[:space:]]*[A-Za-z_]/)) {
        t = line; sub(/^func[[:space:]]*\([^)]*\)[[:space:]]*/, "", t)
        sub(/[^A-Za-z0-9_].*$/, "", t)
        if (t != "") print "sym\t" t; next
      }
      # Keyword-announced definitions, functions and named types alike.
      # Dunders are skipped: every class defines __init__, so "already defined
      # in N other files" is guaranteed noise for them — and noise is what
      # teaches sessions to skip the hint.
      if (match(line, /^(function|def|class|func|fun|fn|sub|struct|trait|interface|enum|object|protocol|type)[[:space:]]+[A-Za-z_$]/)) {
        t = line; sub(/^[a-z]+[[:space:]]+/, "", t)
        sub(/[^A-Za-z0-9_$].*$/, "", t)
        if (t != "" && t !~ /^__.*__$/) print "sym\t" t; next
      }
      # Arrow/expression assignment: const name = (…) / let name = async (
      if (match(line, /^(const|let)[[:space:]]+[A-Za-z_$][A-Za-z0-9_$]*[[:space:]]*=[[:space:]]*(async[[:space:]]*)?[(<]/)) {
        t = line; sub(/^(const|let)[[:space:]]+/, "", t)
        sub(/[^A-Za-z0-9_$].*$/, "", t)
        if (t != "") print "sym\t" t; next
      }
    }
  ' 2>/dev/null | sort -u | head -12) || names=""

  while IFS=$'\t' read -r kind name; do
    [ -n "${name:-}" ] || continue
    case "$kind" in
      css) pat="^[[:space:]]*\.${name}[[:space:]]*[,{]" ;;
      *)   pat="(function|def|class|func|fun|fn|sub|struct|trait|interface|enum|object|protocol|type)[[:space:]]+${name}[^A-Za-z0-9_]|func[[:space:]]*\([^)]*\)[[:space:]]*${name}[[:space:]]*\(|(const|let)[[:space:]]+${name}[[:space:]]*=" ;;
    esac
    # -I skips binaries; :(exclude) drops the file being written, which would
    # otherwise always match itself on an Edit.
    hits=$(git -C "$repo_root" grep -I -l -E -e "$pat" -- . ":(exclude)${rel_path}" 2>/dev/null | head -4) || hits=""
    [ -n "$hits" ] || continue
    count=$(printf '%s\n' "$hits" | grep -c . 2>/dev/null || echo 0)
    label=$([ "$kind" = css ] && printf '.%s' "$name" || printf '%s' "$name")
    files=$(printf '%s' "$hits" | tr '\n' ' ' | sed 's/ $//')
    local_lines="${local_lines}> - \`${label}\` is already defined in ${count} other file(s): ${files}"$'\n'
  done <<< "$names"
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

url=${SCRIBE_URL:-${CLAUDE_PLUGIN_OPTION_API_ENDPOINT:-}}
token=${SCRIBE_TOKEN:-${CLAUDE_PLUGIN_OPTION_API_TOKEN:-}}
# Guard against an unexpanded ${...} placeholder arriving as a literal.
case "$url"   in *'${'*) url="" ;;  esac
case "$token" in *'${'*) token="" ;; esac
# 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
    jq -n --arg c "$local_context" \
      '{hookSpecificOutput: {hookEventName: "PreToolUse", additionalContext: $c}}'
  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)

# `-sRr`, not `-rR`: jq -R reads 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. -s slurps the
# whole input into one string first. Newlines are exactly what code contains, so
# this hook could never have worked without it (issue #2198 / #2082).
path_enc=$(printf '%s' "$rel_path" | jq -sRr '@uri' 2>/dev/null) || exit 0
code_enc=$(printf '%s' "$q" | jq -sRr '@uri' 2>/dev/null) || code_enc=""

# Resolve the working repo's remote so the server can scope to the bound project.
repo=$(git -C "$lookup_dir" remote get-url origin 2>/dev/null || true)
repo_q=""
if [ -n "$repo" ]; then
  enc=$(printf '%s' "$repo" | jq -sRr '@uri' 2>/dev/null) || enc=""
  [ -n "$enc" ] && repo_q="&repo=${enc}"
fi

# 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
idfile=""
syncfile=""
exclude_q=""
sync_exclude_q=""
if [ -n "$session_id" ]; then
  safe_sid=$(printf '%s' "$session_id" | tr -c 'A-Za-z0-9._-' '_')
  idfile="$state_dir/${safe_sid}.ids"
  syncfile="$state_dir/${safe_sid}.sync.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
fi

# `|| true`, not `|| exit 0`: an unreachable instance must not discard a local
# finding that needed no instance to produce.
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}" 2>/dev/null) || body=""

context=""
if [ -n "$body" ]; then
  context=$(printf '%s' "$body" | jq -r '.context // empty' 2>/dev/null) || 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
      printf '%s' "$body" | jq -r '((.note_ids // []) - (.sync_note_ids // []))[]?' 2>/dev/null >> "$idfile" || true
    fi
    if [ -n "$syncfile" ]; then
      printf '%s' "$body" | jq -r '(.sync_note_ids // [])[]?' 2>/dev/null >> "$syncfile" || 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. An unreachable server counts as "nothing recorded": the
# local finding needed no server, and the nudge fails open with it.
if [ -n "$local_lines" ]; then
  n_recorded=$(printf '%s' "$body" | jq -r '.note_ids | length' 2>/dev/null) || n_recorded=0
  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

# Local first. It answers "this already EXISTS", which is a stronger claim than
# "this resembles something recorded" — and it is the one the recorded arms are
# structurally unable to make.
combined="$local_context"
if [ -n "$context" ]; then
  [ -n "$combined" ] && combined="${combined}"$'\n'
  combined="${combined}${context}"
fi
[ -n "$combined" ] || exit 0

# No permissionDecision: this is a nudge, not a gate. The write goes ahead.
jq -n --arg c "$combined" \
  '{hookSpecificOutput: {hookEventName: "PreToolUse", additionalContext: $c}}'
exit 0