docs(plugin): a request for the operator's approval gets its own "Approval requested" section (#4084)

A session's go-ahead request sat inside a completion list as "Blocked by the
permission check", and the operator read it as a fault rather than a question
waiting on them. The reporting-back skill now puts any action held for a yes
under a section headed "Approval requested", near the top of whatever reply
it is: each change numbered so part can be approved, why it needs them, how
it is undone, and what happens after. The Asks table gains an Approval row,
and the completion report's "Needs you" points at the section.

test_reporting_back_skill pins the heading and the row. Plugin version minted:
2026.09.15.1921.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01821k5B3Ysecp9fNYs92Kuy

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), and syncs your saved Scribe Processes as skills (/scribe:sync).",
-  "version": "2026.09.15.1744",
+  "version": "2026.09.15.1921",
   "author": {
     "name": "Bryan Van Deusen"
   },

plugin/skills/reporting-back/SKILL.md

@@ -23,6 +23,12 @@ when one is short — "**Needs you:** nothing" is an answer they were looking fo
   plain.
 - **End with the ask, in bold** — the one thing they need to decide or do. If
   there is nothing, say so.
+- **A request for approval gets its own section, headed "Approval requested".**
+  Whenever you are holding an action until the operator says yes — a permission
+  prompt their client raised, something hard to undo, a change you have
+  prepared and not made — put it there, near the top, whatever kind of reply
+  this is. Inside a progress or completion list it reads as a status line, and
+  the operator does not see that you are waiting on them.
 - **Plain words.** Use the operator's vocabulary, not the names you coined while
   working. If a term has to appear, explain it once.
 - **Place the work in Scribe.** Name the task, issue or milestone it belongs to,
@@ -76,6 +82,7 @@ default differ, the preference is what they asked for.
 | **Decision** | The question first · 2–4 options, each with what it changes · recommendation first |
 | **Clarification** | "My reading is X · the gap is Y · unless you say otherwise I'll do Z" |
 | **Handoff** (only they can do it) | The action · why it needs them · what it unblocks · what you'll do after · any way to skip it |
+| **Approval** (you are ready to act and holding for a yes) | **Approval requested:** exactly what happens once they approve, one numbered item per change so they can approve part · why it needs their yes · how it can be undone · what you'll do after |
 | **Conflict** (what you're about to do clashes with a rule, a plan or an earlier decision) | What it says · what you were about to do · where they clash · A or B? |
 
 Before asking, check whether you can find the answer yourself — something that
@@ -128,7 +135,8 @@ Notes on each section:
   verified**. If something could not be verified, say what and why here rather
   than letting it read as passed.
 - **Needs you** — an action, an approval, a decision, or "nothing". If it's an
-  action, give the reason with it.
+  action, give the reason with it. An approval you are holding for also gets
+  its own **Approval requested** section, and this line points at it.
 - **Next** — from `placement.next`, or say the milestone is finished. If you
   found something you didn't fix, the offer to fix it goes here.
 

tests/test_reporting_back_skill.py

@@ -38,6 +38,16 @@ def test_the_completion_report_keeps_its_sections():
         assert section in text, f"the completion report lost its {section!r} section"
 
 
+def test_a_request_for_approval_has_its_own_named_section():
+    """The operator, 2026-09-15 (#4084): a session's go-ahead request sat inside
+    a completion list as "Blocked by the permission check", and read as a
+    fault rather than a question waiting on them. The heading is what they
+    scan for, so it is pinned by name."""
+    text = _text()
+    assert "Approval requested" in text
+    assert "| **Approval**" in text, "the Asks table lost its Approval row"
+
+
 def test_placement_comes_from_the_record():
     """The failure this milestone started from: a placement written from memory
     reads exactly like a real one when it is wrong."""