feat(500): one end-of-turn request - the completion-section check folds into the reply check

The Stop hook sent the finished reply twice: scribe_report_check.sh checked a
task-closing reply for the completion sections in shell and reported to
/report-check, and scribe_reply_check.sh sent the same reply to /reply-rules
for the rule hold. Now the reply goes once. When the turn closed a task the
hook adds the close count and ids, and the server runs the section check
(services/report_check, the same three patterns) beside the reply hold,
folding both into one reason.

The report_check adherence log is still written for every checked reply
(milestone 409's number). A section hold marks the session, so its rewrite is
sent back once with rewrite:true to record how it came out, and is never held.
The block reason carries the completion shape's one line and points at
list_reply_shapes rather than at the skill. #5496 (step 4 of milestone 500).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "scribe",
   "description": "Scribe for Claude Code: connects the scribe MCP server, adds the hooks that deliver live project state and relevant records at the right moment, ships the shared client-neutral Scribe skills (using-scribe, writing-plans, reporting-back, systematic-debugging, verification, brainstorming, reusing-code, shape-accounting, family-canon), and syncs your saved Scribe Processes as skills (/scribe:sync).",
-  "version": "2026.10.09.1850",
+  "version": "2026.10.09.1938",
   "author": {
     "name": "Bryan Van Deusen"
   },

plugin/PACKAGING.md

@@ -15,7 +15,7 @@ another one means adding files, not moving or rewriting any.
 |---|---|---|
 | **The skills** | `plugin/skills/*/SKILL.md` | Agent Skills (the open SKILL.md format). They state every Scribe reflex in full and name no client. `tests/test_guidance_ownership.py` fails if a skill names a particular client, or references anything outside its own folder. Every client package ships this folder verbatim. |
 | **The MCP server** | `<base URL>/mcp` | HTTP, `Authorization: Bearer <fmcp_ key>`. Its `_INSTRUCTIONS` is a client-neutral orientation — the workflow across tools (≤1,600 chars, #4389); each tool's description carries its contract; in-band responses (`placement`, `report_back`, `systems_hint`, the duplicate gate, the guessed-id refusal) fire in every client. |
-| **The adapter API** | `<base URL>/api/plugin/*` | Plain `GET` endpoints any client's hooks can call with the same key (read scope is enough): `context` (live session state), `retrieve` (rules, preferences and notes for a message), `prior-art` (records and shape-ledger hints for code being written), `tool-rules` (rules for a command about to run), `report-check` (records a completion-report check and returns the reason for a block), `processes` (stored Processes to expose as skills). |
+| **The adapter API** | `<base URL>/api/plugin/*` | Plain `GET` endpoints any client's hooks can call with the same key (read scope is enough): `context` (live session state), `retrieve` (rules, preferences and notes for a message), `prior-art` (records and shape-ledger hints for code being written), `tool-rules` (rules for a command about to run), `reply-rules` (a `POST`: the finished reply, held for an unopened rule or — when the turn closed a task — for missing completion sections), `processes` (stored Processes to expose as skills). |
 | **The API key** | Scribe → Settings → API Keys | One `fmcp_` key per install. Read scope for hooks; write scope for the MCP tools. |
 
 ## Added by each client
@@ -40,8 +40,7 @@ another one means adding files, not moving or rewriting any.
 | `hooks/scribe_after_write.sh` | PostToolUse on shell commands: the same check for code written through the shell. |
 | `hooks/scribe_tool_rules.sh` | PreToolUse on shell commands: `GET /api/plugin/tool-rules`. |
 | `hooks/scribe_moment.sh` | PreToolUse on every tool: the rules mounted on the moments the call reaches, `POST /api/plugin/moment`; skips tools `GET /api/plugin/moment-tools` says reach nothing mounted, and Scribe's own (their responses carry `moment_rules`). |
-| `hooks/scribe_report_check.sh` | Stop: when the turn closed a task, checks the reply for the completion sections and reports to `GET /api/plugin/report-check`; blocks once, with the reason the server returns. |
-| `hooks/scribe_reply_check.sh` | Stop: sends the finished reply to `POST /api/plugin/reply-rules` — the rules mounted on the reply moments, and the reply against every rule's trigger; holds once per rule, with the reason the server returns, and never holds the rewrite. |
+| `hooks/scribe_reply_check.sh` | Stop: sends the finished reply to `POST /api/plugin/reply-rules` — the rules mounted on the reply moments, and the reply against every rule's trigger, and — when the turn closed a task — the completion-section check; holds once per rule, with the reason the server returns, and never holds the rewrite. |
 | `hooks/scribe_shape_check.sh` | Stop: sends the definitions the turn wrote (the write hooks' `<sid>.written.ids` ledger) to `GET /api/plugin/shape-check`; blocks once, with the reason the server returns, so the agent judges what it built. |
 | `hooks/scribe_sync_processes.sh` + `commands/sync.md` | `GET /api/plugin/processes` → `~/.claude/skills/scribe-proc-*` stubs; `/scribe:sync` on demand. |
 | `hooks/scribe_defs.sh` | Shared shell helpers: config, dedup ledgers, outage line. |

plugin/README.md

@@ -82,15 +82,16 @@ On install you'll be asked for:
   answer" line (8 s budget here — it runs after the tool, so it gates
   nothing). The extractor, the prose/data skip list, the local by-name
   duplicate arm and the outage line are shared in `hooks/scribe_defs.sh`.
-- `hooks/hooks.json` → Stop hook (`hooks/scribe_report_check.sh`): when the
-  turn closed a Scribe task (`update_task`/`create_task` with status done),
-  checks the reply that ends it for the completion sections — where the work
-  sits, what needs you, what comes next — and reports the outcome to
-  `GET /api/plugin/report-check`. If sections are missing it blocks once with
-  the reason the server returns, and records how the rewrite came out; it
-  never blocks twice, and never blocks when the instance did not record the
-  check (unconfigured or unreachable). Outcomes land in the admin logs under
-  category `plugin`, action `report_check`.
+- `hooks/hooks.json` → Stop hook (`hooks/scribe_reply_check.sh`): sends the
+  reply that ends the turn to `POST /api/plugin/reply-rules`, which holds it
+  once for an unopened rule mounted on the reply moments or matching the reply.
+  When the turn closed a Scribe task (`update_task`/`create_task` with status
+  done), the same request has the server check the reply for the completion
+  sections — where the work sits, what needs you, what comes next. If they are
+  missing it blocks once with the reason the server returns, and records how
+  the rewrite came out; it never blocks twice, and never blocks when the
+  instance did not record the check (unconfigured or unreachable). Outcomes
+  land in the admin logs under category `plugin`, action `report_check`.
 - `hooks/hooks.json` → a second Stop hook (`hooks/scribe_shape_check.sh`): the
   write hooks note every definition a write names (and every new file) in a
   session ledger; at the end of the turn this sends them to

plugin/hooks/hooks.json

@@ -104,10 +104,6 @@
     "Stop": [
       {
         "hooks": [
-          {
-            "type": "command",
-            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/scribe_report_check.sh\""
-          },
           {
             "type": "command",
             "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/scribe_reply_check.sh\""

plugin/hooks/scribe_defs.sh

@@ -135,8 +135,8 @@ scribe_json_flat_lines() {
 # Cheap by construction, because it runs on every prompt: the last 512 KB only,
 # and grep narrows to assistant records carrying a text block BEFORE anything is
 # parsed — a transcript is mostly tool results, and parsing those in awk is the
-# multi-second cost scribe_report_check.sh already measured. Fixed strings with
-# UNESCAPED quotes can only match at a record's own top level (see that hook).
+# multi-second cost the completion-report check measured (#4107). Fixed strings
+# with UNESCAPED quotes can only match at a record's own top level.
 # A sidechain is a subagent talking, not this session, so it is skipped.
 scribe_recent_context() {
   [ -n "${1:-}" ] && [ -f "$1" ] || return 0

plugin/hooks/scribe_json.awk

@@ -39,7 +39,7 @@
 #
 #   mode=lines  the input is JSONL — one JSON value per line — and a line that
 #               does not parse is DROPPED, the rest still read. This is the
-#               transcript in scribe_report_check.sh, where the window starts
+#               transcript the Stop hooks read, where the window starts
 #               mid-record by construction: `tail -n 3000` cuts wherever it
 #               cuts, and the first line is routinely half a record. It is
 #               exactly the `map(try fromjson catch empty)` the jq program it

plugin/hooks/scribe_reply_check.sh

@@ -9,7 +9,15 @@
 # text against every rule's trigger, as the backstop for whatever the earlier
 # arms missed. An unopened rule from either half holds the reply for one read.
 #
-# THE SAME CONTRACT AS scribe_report_check.sh, and for its reasons:
+# ONE END-OF-TURN REQUEST (milestone 500 step 4). When the turn closed a task,
+# the same request carries the task ids and the server also checks the reply
+# for the completion sections — once a Stop hook of its own
+# (scribe_report_check.sh), now the same call. The section check's outcome is
+# recorded (`report_check`, milestone 409's adherence number), and when it
+# held the reply, the rewrite is sent back once with `rewrite: true` so the
+# server can record how it came out. A rewrite is never held.
+#
+# THE CONTRACT, and the reasons for it:
 #   - the server decides and supplies the words; this hook blocks only on a
 #     reason it was given, so an unconfigured or unreachable instance never
 #     stops a session;
@@ -34,15 +42,43 @@ session_id=$(scribe_json_pick "$event_flat" '.session_id')
 active=$(scribe_json_pick "$event_flat" '.stop_hook_active')
 event_cwd=$(scribe_json_pick "$event_flat" '.cwd')
 
-# The rewrite after a hold goes out as written.
-[ "$active" = "true" ] && exit 0
 [ -n "$transcript" ] && [ -f "$transcript" ] && [ -n "$session_id" ] || exit 0
+
+state_dir="${TMPDIR:-/tmp}/scribe-priorart"
+mkdir -p "$state_dir" 2>/dev/null || true
+safe_sid=$(printf '%s' "$session_id" | tr -c 'A-Za-z0-9._-' '_')
+rulefile="$state_dir/${safe_sid}.rules.ids"
+stopfile="$state_dir/${safe_sid}.checkpoint.ids"
+# Set when the section check held the reply: the next stop is its rewrite.
+reportfile="$state_dir/${safe_sid}.reportcheck"
+
+# The rewrite after a hold goes out as written. Only a rewrite of a SECTION
+# hold is sent at all — to record how it came out; one after a rule hold, or
+# another plugin's block, has nothing to report.
+if [ "$active" = "true" ]; then
+  [ -f "$reportfile" ] || exit 0
+  rm -f "$reportfile" 2>/dev/null || true
+  rewrite=true
+else
+  rm -f "$reportfile" 2>/dev/null || true
+  rewrite=false
+fi
 scribe_config || exit 0
 
 facts=$(scribe_turn_facts "$transcript")
 [ "$(scribe_turn_fact "$facts" bounded)" = "1" ] || exit 0
 reply=$(scribe_turn_fact "$facts" reply | scribe_json_unescape)
+# The reply may not be in the transcript yet when the hook fires: an empty
+# reply is "cannot tell", never "missing everything".
 [ -n "$(printf '%s' "$reply" | tr -d '[:space:]')" ] || exit 0
+# How many tasks this turn closed, and which — successful closes only, this
+# session only (scribe_turn.awk). A task created already done closes with no
+# id, so the count is what says a check is due. Digits and commas only, so
+# both drop straight into the JSON.
+closed=$(scribe_turn_fact "$facts" closed | tr -cd '0-9')
+closed=${closed:-0}
+task_ids=$(scribe_turn_fact "$facts" task_ids | tr -cd '0-9,' | sed 's/,,*/,/g; s/^,//; s/,$//')
+[ "$rewrite" = "true" ] && [ "$closed" = "0" ] && exit 0
 
 # Bounded before encoding. The server reads the head and the tail — the part
 # of a report that asks something of the reader is at its end — so a very
@@ -51,12 +87,10 @@ if [ "${#reply}" -gt 12000 ]; then
   reply="${reply:0:4000} … ${reply: -8000}"
 fi
 reply_esc=$(printf '%s' "$reply" | scribe_json_escape) || exit 0
-
-state_dir="${TMPDIR:-/tmp}/scribe-priorart"
-mkdir -p "$state_dir" 2>/dev/null || true
-safe_sid=$(printf '%s' "$session_id" | tr -c 'A-Za-z0-9._-' '_')
-rulefile="$state_dir/${safe_sid}.rules.ids"
-stopfile="$state_dir/${safe_sid}.checkpoint.ids"
+closing=""
+if [ "$closed" != "0" ]; then
+  closing=$(printf ',"closed":%d,"closed_task_ids":[%s],"rewrite":%s' "$closed" "$task_ids" "$rewrite")
+fi
 
 query=""
 scope=$(scribe_scope_query "${event_cwd:-${CLAUDE_PROJECT_DIR:-$PWD}}")
@@ -70,15 +104,17 @@ if [ -f "$stopfile" ]; then
 fi
 query=${query#&}
 
-answer=$(printf '{"reply":"%s"}' "$reply_esc" | curl -fsS --max-time 6 \
+answer=$(printf '{"reply":"%s"%s}' "$reply_esc" "$closing" | curl -fsS --max-time 6 \
   -H "Authorization: Bearer ${token}" \
   -H "Content-Type: application/json" \
   --data-binary @- \
   "${url%/}/api/plugin/reply-rules${query:+?$query}" 2>/dev/null) || exit 0
 
+[ "$rewrite" = "true" ] && exit 0
 answer_flat=$(printf '%s' "$answer" | scribe_json_flat)
 reason=$(scribe_json_pick "$answer_flat" '.reason')
 [ -n "$reason" ] || exit 0
+[ "$(scribe_json_pick "$answer_flat" '.report_check')" = "blocked" ] && : > "$reportfile" 2>/dev/null
 
 # Recorded BEFORE the block is emitted, for the act checkpoint's reason: a
 # hold that is shown and not recorded is one that can be shown again.

plugin/hooks/scribe_report_check.sh

@@ -1,155 +0,0 @@
-#!/usr/bin/env bash
-# Scribe plugin — Stop hook: a reply that closes a task carries the completion
-# sections (milestone 409 step 5).
-#
-# Everything else the plugin does happens BEFORE the agent writes: context,
-# retrieval, the reporting-back skill. This is the one moment the finished
-# reply exists, so it is both the last chance to fix a report the operator
-# cannot read and the only place adherence to the shape can be measured.
-#
-# DETERMINISTIC, NO MODEL CALL. Three questions, cheapest first:
-#
-#   1. Did this turn close a Scribe task? An `update_task` / `create_task` tool
-#      call with status "done" since the turn's prompt, whose result was not an
-#      error. Most turns stop here, silently.
-#   2. Does the reply that ends the turn have the completion sections? Loosely:
-#      where the work sits (a record named by id and title, or step N of M),
-#      what needs the operator, and what comes next. Matched on the words that
-#      carry the meaning rather than exact headings, so the skill's wording can
-#      change without breaking this.
-#   3. If sections are missing, block once with a reason naming them. The agent
-#      rewrites; the rewrite is checked and recorded, and never blocked again.
-#
-# MEASURED FROM THE FIRST CALL. Each checked reply is reported to the instance
-# (`/api/plugin/report-check`): passed, blocked, and after a rewrite either
-# passed_after_rewrite or missing_after_rewrite. Turns that closed no task are
-# not reported — they would cost a request on every turn and add nothing to
-# the rate step 6 reads (blocked among checked replies).
-#
-# IT BLOCKS ONLY WHEN THE BLOCK IS RECORDED, AND ONLY IN THE SERVER'S WORDS.
-# The report goes out first; the instance answers a recorded `blocked` with
-# the reason to send the agent back with, and the hook blocks only on that
-# reason. An unconfigured or unreachable instance therefore never stops a
-# session, every intervention is one the numbers can see, and the guidance
-# text lives on the server (plugin/PACKAGING.md: hooks carry timing and
-# transport).
-#
-# THE TRANSCRIPT FORMAT IS OBSERVED, NOT DOCUMENTED. Claude Code documents
-# `transcript_path` and `stop_hook_active` for Stop, not the JSONL inside. As
-# read from real transcripts (2026-09-14): one content block per line;
-# `type: "assistant"` lines carry `message.content[]` blocks of `text` /
-# `tool_use` ({id, name, input}); tool results arrive as `type: "user"` lines
-# whose content is a `tool_result` array ({tool_use_id, is_error}); a turn's
-# prompt — typed, or a background-task notification — is a `user` line whose
-# content is a plain string and which is not `isMeta`. Anything that does not
-# parse that way makes the hook stay out of the way rather than guess.
-#
-# Config (same as the other hooks):
-#   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
-
-# shellcheck source=plugin/hooks/scribe_defs.sh
-. "$(dirname "${BASH_SOURCE[0]}")/scribe_defs.sh"
-
-# Stop delivers { session_id, transcript_path, cwd, hook_event_name, stop_hook_active }.
-event=$(cat 2>/dev/null || true)
-event_flat=$(printf '%s' "$event" | scribe_json_flat)
-transcript=$(scribe_json_pick "$event_flat" '.transcript_path')
-[ -n "$transcript" ] && [ -f "$transcript" ] || exit 0
-session_id=$(scribe_json_pick "$event_flat" '.session_id')
-active=$(scribe_json_pick "$event_flat" '.stop_hook_active')
-event_cwd=$(scribe_json_pick "$event_flat" '.cwd')
-
-safe_sid=$(printf '%s' "${session_id:-nosession}" | tr -c 'A-Za-z0-9._-' '_')
-state_dir="${TMPDIR:-/tmp}/scribe-reportcheck"
-mkdir -p "$state_dir" 2>/dev/null || true
-marker="$state_dir/${safe_sid}.blocked"
-
-# Cheap prefilter: no task tool anywhere in the recent transcript → nothing to
-# check. Keeps the ordinary turn at one grep. Process substitution, NOT a pipe:
-# under `pipefail`, `grep -q` exiting on the first match kills `tail` with
-# SIGPIPE, and the pipeline then reports failure precisely when it matched.
-grep -q -E '"name":[[:space:]]*"([^"]*__)?(update|create)_task"' < <(tail -c 2000000 "$transcript" 2>/dev/null) || {
-  rm -f "$marker" 2>/dev/null || true
-  exit 0
-}
-
-# The turn, parsed once — scribe_turn_facts, shared with the reply check.
-facts=$(scribe_turn_facts "$transcript")
-fact() { scribe_turn_fact "$facts" "$1"; }
-
-[ "$(fact bounded)" = "1" ] || exit 0
-closed=$(fact closed)
-if [ "${closed:-0}" = "0" ]; then
-  rm -f "$marker" 2>/dev/null || true
-  exit 0
-fi
-# Escaped on one line coming out of awk, so the format survives a multi-line
-# reply; decoded here, once, where it is about to be read as text.
-reply=$(fact reply | scribe_json_unescape)
-task_ids=$(fact task_ids)
-
-# The reply may not be written to the transcript yet when the hook fires. An
-# empty reply is "cannot tell", not "missing everything" — stay out of the way.
-[ -n "$(printf '%s' "$reply" | tr -d '[:space:]')" ] || exit 0
-
-missing=()
-# Where the work sits: a record named by id AND title (#12 "…", milestone 3 "…"),
-# or a step position. A bare id is exactly the homework this shape removes.
-# shellcheck disable=SC2016 # backticks here are literal markdown, not an expansion
-grep -q -i -E '(#[0-9]+|milestone [0-9]+|task [0-9]+)[*_`]*[[:space:]]*[*_`]*["“]|step [0-9]+ of [0-9]+' <<< "$reply" \
-  || missing+=("where it sits")
-# What needs the operator — "needs you: nothing" counts; it is an answer.
-grep -q -i -E 'needs? (from )?you|nothing (is )?needed from you|your (call|decision)' <<< "$reply" \
-  || missing+=("needs you")
-# What comes next.
-grep -q -i -E '\bnext\b' <<< "$reply" \
-  || missing+=("next")
-
-# Reports the outcome; prints the instance's reply and returns 0 only if the
-# instance recorded it.
-report() {
-  scribe_config || return 1
-  local q repo enc m
-  q="outcome=$1&task_ids=${task_ids}"
-  m=$(IFS=,; printf '%s' "${missing[*]:-}")
-  if [ -n "$m" ]; then
-    enc=$(printf '%s' "$m" | scribe_urlenc) || enc=""
-    q="${q}&missing=${enc}"
-  fi
-  scope=$(scribe_scope_query "${event_cwd:-${CLAUDE_PROJECT_DIR:-$PWD}}")
-  [ -n "$scope" ] && q="${q}&${scope}"
-  curl -fsS --max-time 4 \
-    -H "Authorization: Bearer ${token}" \
-    "${url%/}/api/plugin/report-check?${q}" 2>/dev/null
-}
-
-if [ "$active" = "true" ]; then
-  # A Stop hook already blocked this stop. If it was this one, the reply is
-  # the rewrite: record how it came out, and let the session stop whatever
-  # the answer. If it was another plugin's block, this hook has nothing to add.
-  [ -f "$marker" ] || exit 0
-  rm -f "$marker" 2>/dev/null || true
-  if [ ${#missing[@]} -eq 0 ]; then report passed_after_rewrite >/dev/null; else report missing_after_rewrite >/dev/null; fi
-  exit 0
-fi
-rm -f "$marker" 2>/dev/null || true
-
-if [ ${#missing[@]} -eq 0 ]; then
-  report passed >/dev/null
-  exit 0
-fi
-
-# The words the agent is sent back with are the server's (plugin/PACKAGING.md:
-# a hook carries timing and transport). No reason back → nothing recorded →
-# no block.
-answer=$(report blocked) || exit 0
-reason=$(scribe_json_pick "$(printf '%s' "$answer" | scribe_json_flat)" '.reason')
-[ -n "$reason" ] || exit 0
-: > "$marker" 2>/dev/null || true
-printf '{"decision":"block","reason":"%s"}\n' "$(printf '%s' "$reason" | scribe_json_escape)"
-exit 0

plugin/hooks/scribe_shape_check.sh

@@ -10,7 +10,7 @@
 # words: the agent that built the code is the one participant who knows what
 # it is, and the end of the turn is the last moment that is still true.
 #
-# THE SAME DISCIPLINE AS scribe_report_check.sh, deliberately:
+# THE SAME DISCIPLINE AS the completion-section check in scribe_reply_check.sh:
 #   - it blocks only on a `reason` the instance returned, which it returns
 #     only for a block it RECORDED — an unconfigured or unreachable instance
 #     never stops a session, and every intervention is one the numbers see;

plugin/hooks/scribe_turn.awk

@@ -2,7 +2,7 @@
 #
 # Reads the flat `IDX<TAB>PATH<TAB>VALUE` stream that scribe_json.awk produces
 # in `mode=lines` from a Claude Code transcript, and answers the four questions
-# scribe_report_check.sh asks. It replaces a thirty-line jq program; the shape
+# the Stop hooks ask (scribe_reply_check.sh). It replaces a thirty-line jq program; the shape
 # of the answer is unchanged, so the hook around it reads the same.
 #
 #   bounded   1 if a user prompt was found in the window, else empty. A window