bvandeusenandClaude Fable 5
a8f35e465e
CI & Build / Python lint (push) Successful in 4s
CI & Build / Plugin hooks (push) Successful in 27s
CI & Build / TypeScript typecheck (push) Successful in 36s
CI & Build / integration (push) Successful in 1m34s
CI & Build / Python tests (push) Successful in 2m21s
CI & Build / Build & push image (push) Successful in 25s
DRY pass 3's remainder. Both halves start from enumeration, because the task's
candidate list was hypotheses and the process requires counting before
proposing — and counting changed the answer twice.
## The list_* family: a limit with no offset
Enumerated all 19 `list_*` MCP tools first. They are genuinely heterogeneous —
8 take `project_id`, 6 take `limit`, six take no arguments at all — so a
common-parameter guard would invent a convention the API does not have, which
is the over-DRY trap (§5). One contract IS real: a `limit` without an `offset`
is a truncation with no continuation. The caller is told there are 250 results,
handed 50, and given no way to ask for the rest.
Two tools had it, and both were capped over a service that already accepted an
offset: `snippets_svc.list_snippets(offset=0)` was simply not exposed, and
`list_processes` passed a hardcoded `offset=0` into `query_knowledge`. The
capability existed one layer down in both; only the door was missing — the
missing-sibling shape exactly. Both now expose it.
`tests/test_mcp_list_family.py` guards it, with `list_tags` exempted for a
stated reason (a ranked top-N over a bounded vocabulary has no "rest" to page
into). Candidates derived, decision explicit, same design as test_mcp_auth —
plus the reverse checks: a stale exemption, and an offset with no limit, which
would page through an unbounded result set. Verified non-vacuous by running the
sweep against the pre-fix tree, where it fails naming both tools.
## The verb pairs: no finding, which is the finding
`preview`/`apply` and `dry_run`/`commit` do not exist anywhere in the 102
tools — those were guesses about a shape Scribe never adopted. `count_*` does
not exist either. Of the create/delete stems only `project_rule` lacks a
`delete_X`, and deliberately: a project rule IS a rule, `delete_rule` removes
it, and the docstring says so. `force` sits on 6 of 7 duplicate-gated creates;
the exception is `create_system`, whose gate is an exact normalized-NAME match
rather than a semantic near-match — forcing it would split one area's records
across two piles, which its own message explains. No guard added: it would
need a seven-entry exemption list to defend against a hypothetical. Recorded
on the leave-alone list instead, which the process asks for by name.
## The hook config preamble
Not 3 of 6 hooks as recorded — all FIVE carried their own copy, and of four
lines rather than two. The extra two are a guard treating an unexpanded
`${...}` placeholder as unset, so it is never sent as a garbage Bearer token:
precisely the correctness detail a sixth hook would omit with nothing failing
loudly. Now `scribe_config` in scribe_defs.sh, which also declares the two
names it owns. It sets globals rather than echoing, so a token never passes
through a subshell's output where xtrace or a log could catch it, and returns
a status so a caller can bail (`|| exit 0`) or continue degraded — the
session-context hook still owes its static floor when Scribe is unconfigured.
`check_plugin.py` now runs shellcheck with `-x`. Without it the shared helpers
were invisible: every variable they set read as unassigned and every bug inside
them went unlinted at the call site, which is the opposite of what sharing them
was for. All twelve fail-open scenarios still pass, and all five hooks were
probed live against the instance — prior_art and after_write both still name
canon, autoinject returns context, session_context serves 11k chars of rules,
sync_processes stays silent. Plugin 0.1.46 (#2209).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
270 lines
13 KiB
Bash
Executable File
270 lines
13 KiB
Bash
Executable File
#!/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 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=""
|
|
|
|
# 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.
|
|
# shellcheck source=plugin/hooks/scribe_defs.sh
|
|
. "$(dirname "${BASH_SOURCE[0]}")/scribe_defs.sh"
|
|
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
|
|
names=$(printf '%s' "$code" | scribe_defs | sort -u | head -12) || names=""
|
|
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.
|
|
# ---------------------------------------------------------------------------
|
|
shapes="$names"
|
|
if [ -z "$shapes" ] && [ -f "$file_path" ] && command -v tac >/dev/null 2>&1; then
|
|
old_first=$(printf '%s' "$event" \
|
|
| jq -r '.tool_input.old_string // .tool_input.old_str // empty' 2>/dev/null \
|
|
| grep -m1 -v '^[[:space:]]*$') || old_first=""
|
|
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" | tac | scribe_defs | head -1) || shapes=""
|
|
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}' \
|
|
| jq -sRr '@uri' 2>/dev/null) || 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
|
|
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
|
|
#
|
|
# 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.
|
|
idfile=""
|
|
syncfile=""
|
|
derivefile=""
|
|
exclude_q=""
|
|
sync_exclude_q=""
|
|
derive_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"
|
|
derivefile="$state_dir/${safe_sid}.derive.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/,$//' | jq -sRr '@uri' 2>/dev/null) || derive_seen=""
|
|
[ -n "$derive_seen" ] && derive_exclude_q="&exclude_derive=${derive_seen}"
|
|
fi
|
|
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}${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=""
|
|
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
|
|
if [ -n "$derivefile" ]; then
|
|
printf '%s' "$body" | jq -r '(.derive_keys // [])[]?' 2>/dev/null >> "$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=$(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
|
|
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.
|
|
jq -n --arg c "$combined" \
|
|
'{hookSpecificOutput: {hookEventName: "PreToolUse", additionalContext: $c}}'
|
|
exit 0
|