@warren-dean/code-kit 0.12.0 → 0.12.2

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
       "name": "code-kit",
       "source": "./",
       "description": "Keeps AI coding agents inside your project's rules, from idea to merged code: spec design, lanes, layer rules, protected paths with an approval log, spec-check and design gates, proof-before-finish checks, dispatch, review, build status and CI verification, configured per project from its docs",
-      "version": "0.12.0",
+      "version": "0.12.2",
       "category": "development",
       "tags": ["guardrails", "architecture", "lanes", "layers", "spec-driven", "ci", "multi-agent"],
       "license": "MIT"

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "code-kit",
-  "version": "0.12.0",
+  "version": "0.12.2",
   "description": "Keeps AI coding agents inside your project's rules, from idea to merged code: spec design, lanes, layer rules, protected paths with an approval log, spec-check and design gates, proof-before-finish checks, dispatch, review, build status and CI verification, configured per project from its docs",
   "author": {
     "name": "Warren Langeveldt"

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 What changed in each release of code-kit, newest first. Versions follow the plugin manifest and the npm package `@warren-dean/code-kit`. Each release is also on [GitHub Releases](https://github.com/warrendeanlangeveldt/code-kit/releases).
 
+## 0.12.2 (2026-10-13)
+
+The Decisions tab is readable, and old package requests stop waiting.
+
+- **Decisions as short cards.** The tab says how many of each kind wait ("10 approvals · 2 questions"), then lists each as a card: its kind, a one-line headline ("Approve fastify, jose, drizzle-orm and 4 more") and who it's for, with commands cut at their first pipe instead of whole scripts. Five show at a time; **j** and **k** move, and the selected one opens in full below.
+- **Package requests close once installed.** A request for a package closes once the package is in a committed `package.json`, whoever installed it, so installs already done no longer wait for you.
+
+## 0.12.1 (2026-10-13)
+
+Ask about an approval before you give it.
+
+- **Ask about it, in the Approve pane.** When a request isn't clear, ask what it's for right there. The answer comes from a side call over the lead's conversation and what code-kit knows of the request (what was asked for and for whom, why it was refused, its story, the limits it missed), and it stays in the pane: nothing is added to the lead's session. Follow-ups carry on the conversation. Before the lead has replied, it answers from code-kit's facts alone. Nothing is approved until you press Approve.
+
 ## 0.12.0 (2026-10-13)
 
 What only you can decide reaches you, and waits until you answer.

package/README.md

@@ -280,7 +280,7 @@ With Claude Code 2.1.287 or later, code-kit's mod shows the project in the sessi
 - **The band** sits above the prompt. While the build is moving (the lead mid-turn, an agent at work, the loop started) it opens with the mission: **goal**, the milestone being built and how many of its stories are done; **now**, what the lead is doing and the loop's state, with **Pause** or **Resume**; **next**, the step the loop takes next; and **agents**, a line per agent at work with its current tool and how long since. With Context Graph installed, a line says when a lane edited files without understanding them, and only then. Beneath, labelled **you**, what only you can decide, each with the story it's for ("for ST-4 Booking form (BOOK-1)"), and **d** ("Why, and what each choice does") opens it as a card in the Decisions tab; usage and the plan's pause are labelled **note**. In a team (`team` in the config), it also names what of the team needs you, and only that: your stale claim (Keep or Release), a claim of yours changing the same files as someone else's, an intent touching what you own or lease (every intent, with Agree and Drop, for the tech lead), and a pull request in a lane you own. While the loop runs, a lane's finished work is the lead's to review and merge, so it never waits here; with the loop off, Review and Merge are offered to you. With nothing happening and nothing waiting, the band is gone. It shows:
   - an agent's call held for you: installing a new package, writing or committing a protected file, or a lane changing the kit. Rather than stopping the agent, the call waits while the band asks ("web wants to install dayjs · 1:53"). **Approve** opens the confirmation and, once you confirm, the same call runs; **Refuse**, or no answer within `harness.hold.minutes` (2 unless set), refuses it as before. Under `autonomy: autonomous`, a call within `approvals.delegate` is approved as delegated without asking. Nothing is held under `claude -p` or the SDK, where nobody can answer;
   - the lead loop, under `harness.autonomy`. `/code-kit:init` asks you how hands-off you want it. Until you've chosen, the loop's first step waits in the band ("code-kit can keep the build moving between your prompts") with **Keep going**, **Ask each time** and **Off**, and your answer is recorded as your setting. Once the lead has finished a turn, the loop keeps the build moving: with the lead idle and nothing typed in the prompt, it asks `code-kit next` and prompts the lead to dispatch the ready stories, review a finished one, or build its own, never the same step twice while nothing has changed, and never a story an agent is still on: one its lane agent is building, or a reviewer is reviewing, waits until that agent finishes ("waiting: ST-10 is still with its agent"). A step the lead was prompted with twice in a row and that is still next goes to you instead, in the band: "Merge lead/st-1: still next after 2 prompts. Ask the lead again?" with **Go**. **Pause** and **Resume** stop and start it. Under `propose`, each step waits in the band for **Go**; under `off`, the loop does nothing. A lane agent with no tool call for `harness.stall.nudgeMinutes` (5) is messaged, unless its work is done (it handed back, or its branch is in review or the merge queue); at `stall.restartMinutes` (10) the lead is asked to stop it and dispatch its story again, at most `stall.maxRestarts` (2) times, and then the band flags the lane. When every story is done, the band says so and the loop stops. With `harness.agents.reviewer.on`, a finished branch is first reviewed in the background by code-kit's reviewer agent, which the lead starts: it runs `verify` and the review checklist, read-only, and grades each finding blocker, concern or nit. The lead's review prompt then carries the findings, and a blocker means the branch is sent back. The pane shows each review, running with its clock or what it found. If the reviewer hasn't reported within 15 minutes, or the plan's 5-hour use is past `harness.background.pauseAtPercent`, the lead reviews without it. A branch the lead's review passes joins the merge queue (`code-kit queue`). Branches merge one at a time, in the order they passed, each verified against the base as it is then: the lead merges where `approvals.delegate.merge` is on under `autonomous`, otherwise the band shows the head with **Merge** for you. Who may merge is read from the config committed on the base, so a branch can't grant itself merges. There's no first merge for you: setting up commits the rules you approved straight onto the base, and in a project set up before that, the lead puts them there itself (`code-kit queue rules`) before its first merge. A merged lane's worktree is removed when it holds nothing uncommitted. A head that conflicts or fails verify goes back to its lane. The pane lists the queue, and lanes whose branch waits in it read `queued`;
-  - approvals agents have asked for: **Approve…** opens a confirmation with a reason prefilled from the request, which you keep or rewrite. A request waits until it's answered, its file is committed by someone who could, or it's dropped (at most a week); on its card, **Not needed** drops it;
+  - approvals agents have asked for: **Approve…** opens a confirmation with a reason prefilled from the request, which you keep or rewrite. When it isn't clear what it's for, **Ask about it** in that pane: the answer comes from a side call over the lead's conversation and code-kit's facts about the request, shown in the pane and never added to the lead's session; follow-ups carry on the aside. A request waits until it's answered, its file is committed by someone who could, or it's dropped (at most a week); on its card, **Not needed** drops it;
   - questions from the lead ("The lead asks: which weather provider?"): what it can't settle and only you can, asked with `code-kit ask`. **Answer…** opens it as a card with each of the lead's options and what it does, and **Something else…** for your own words; your answer is recorded and sent to the lead. A question can hold its story, which then reads `waiting on you`: nothing dispatches or reviews it, and the stories that depend on it wait, until you answer;
   - your brief's open questions: **Answer…** sends your answer to the lead, which records it in the brief's decisions; **Later** puts one off until the next session;
   - a call Claude Code's own permission check refused (its auto mode, a deny rule), which code-kit can't approve past: "Claude Code refused the lead's `pnpm db:generate`". **Put it in the prompt** puts a command in your prompt after `!` for you to run, **Done it** tells the lead you ran or allowed it, and **Not now** tells it to carry on with other work;
@@ -290,7 +290,7 @@ With Claude Code 2.1.287 or later, code-kit's mod shows the project in the sessi
   - a story using more than three times the median of the stories finished this session (once three have finished): **Lanes** opens the pane;
   - background agents paused, once the plan’s 5-hour use passes `harness.background.pauseAtPercent` (80% unless set).
 
-  Each button has a digit: type it in an empty prompt to press it. The band keeps one line per kind ("2 approvals waiting"); the Decisions tab has a card for each decision.
+  Each button has a digit: type it in an empty prompt to press it. The band keeps one line per kind ("2 approvals waiting"); the Decisions tab says how many of each kind, then lists a short card for each decision, five at a time (**j** and **k** move), with the selected one in full below.
 
 - **`/lanes`** opens the Lanes pane. Its first line counts the stories by state (building, in review, queued, sent back, blocked, ready, merged), with the loop's state and the plan's 5-hour use; press a count to show only those lanes. Beneath it, whatever needs you (held calls, approvals, reviews, merges, stalled lanes, outliers) is pinned with its key. Tabs on **1** to **7**: **Lanes** opens on the loop as a card: its mode, the steps it took, the one running and the next. Then each lane on fixed columns: its name, state and story, its agent's current or last tool call with the time since beneath (amber once quiet, red when stalled), and its tokens; the lead reads orchestrating while its turn runs. A selected lane shows its stories as cards (state, requirements, what each waits on or its branch), then its agent and the paths it owns. **Decisions**, each decision that needs you as a card: what you asked for, the story and its requirements, what was happening, what's already settled, why the lead couldn't settle it, and each option with what it does; **Journal**, the build from your request to now in plain sentences, by day: the request and the decisions in the brief, the specification, each story handed out, sent back and merged, each approval and who gave it, each milestone finished, and the loop's steps this session, yours in yellow. Each lane has its own small pixel character, tinted in the lane's colour, whose pose shows its state: working (animated while its agent works), waiting on you, quiet, stalled, done or resting; the lead's wears a crown. Under each lane, its story's timeline on a shared time axis: building, then in review, with send-backs (↩), approvals (◆) and the merge (✓) marked where they fell; **Code map**, the whole project's folders by layer when no story is at work, or a story's files in a column per layer with the imports between them: a file fills with a lane's colour while that lane reads or edits it, and says whether its why (its Context Graph card) is written, out of date or not written yet; **j**/**k** select a file to see its card and what it imports and what imports it, and **o** opens it in Context Graph (box-drawing text in the terminal, an SVG on Desktop); **Trail**, every requirement in the specs as a cell by spec, its glyph and colour saying whether it's done and tested, done but untested, in progress, todo, without a story or removed, with a legend counting each. **h**/**l** and **j**/**k** move between cells and specs (or pick one from the list), showing the requirement's stories, their branches, the code they changed and the tests that name it; beneath the cells, the spec's trail drawn as a flow, each requirement to its stories, code and tests, with a missing link dashed in red; **Queue**, the merge queue; and **Usage**. **j** and **k** move between lanes, and the selected lane's acts are on **a** (approve), **r** (review), **s** (send back, with your reason), **m** (merge), **n** (nudge its agent) and **x** (stop it); **p** pauses or resumes the loop, and **f** filters the lanes by name, agent or story. **Enter** (or **o**) opens the selected lane's story: its requirements beside its spec-check report, the reviewer's findings by severity (each a way into the diff), `verify`'s problems, its usage and loop steps, and its diff against the base, file by file, with the acts its state allows. **b** or Escape goes back to the lanes. Inline (when the terminal can't dock it beside the transcript), it shows the counts, what needs you and a line per lane. It stays current within 2 seconds of a commit, a branch change, a plan edit or an agent starting or stopping. `/lanes` again, or Escape, closes it.
 - **Refusals** a code-kit hook gives an agent are drawn as cards: what was refused, the rule, what to do, and Approve… where your approval would allow it. The full text is a press away.

package/hooks/lib/rules.mjs

@@ -415,6 +415,7 @@ export function openRequests(root, now = Date.now()) {
     // allowed), or the file it named was committed since by someone who could.
     if (r.names.every((n) => grantedSince(root, given, n, r))) continue;
     if (committedSince(root, r)) continue;
+    if (installedSince(root, r)) continue;
     open.push(r);
   }
   return open;
@@ -439,6 +440,39 @@ function grantedSince(root, given, name, r) {
   });
 }
 
+/**
+ * CARD-7: whether every package a dependency request named has since been added to a committed
+ * manifest, on any branch: the install happened (approved, or run by the person themselves), so it no
+ * longer waits.
+ */
+function installedSince(root, r) {
+  if (!r.names.length || !r.names.every((n) => n.startsWith(DEPENDENCY_APPROVAL))) return false;
+  return r.names.every((name) => {
+    const pkg = name.slice(DEPENDENCY_APPROVAL.length).replaceAll('+', '/');
+    try {
+      const out = execFileSync(
+        'git',
+        [
+          '-C',
+          root,
+          'log',
+          '--all',
+          '-1',
+          '--format=%ct',
+          `--since=@${Math.floor(Date.parse(r.at) / 1000)}`,
+          `-S"${pkg}"`,
+          '--',
+          ':(glob)**/package.json',
+        ],
+        { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] },
+      );
+      return Boolean(out.trim());
+    } catch {
+      return false;
+    }
+  });
+}
+
 /** Whether the file a request named has been committed, on any branch, since it was asked. */
 function committedSince(root, r) {
   const path = String(r.what);

package/hooks/mod/decisions.mjs

@@ -2,7 +2,7 @@
 // the person, each with its lineage. The band's "you" lines say what needs them; a decision card says why:
 // what they asked for, the story and requirements it belongs to, what the agent was doing, what was already
 // settled, why the lead couldn't settle this itself, and each option with what happens next.
-import { askWords } from './view.mjs';
+import { approvalLabel, askWords, commandItself } from './view.mjs';
 
 /** The kinds of band line that are the person's to decide; the rest are notes. */
 export const DECISION_KINDS = new Set([
@@ -136,6 +136,70 @@ function optionsOf(line) {
   return line.actions;
 }
 
+/** A kind of decision as its card's tag says it. */
+const TAG = {
+  held: 'held call',
+  approvals: 'approval',
+  stalled: 'stalled',
+  proposal: 'next step',
+  queue: 'merge',
+  review: 'review',
+  notice: 'notice',
+  question: 'question',
+  brief: 'your brief',
+  denied: 'refused',
+  report: 'bug report',
+};
+
+/** At most `n` characters on one line, cut with an ellipsis. */
+const clip = (text, n) => {
+  const one = String(text ?? '')
+    .replace(/\s+/g, ' ')
+    .trim();
+  return one.length > n ? `${one.slice(0, n - 1)}…` : one;
+};
+
+/** Names as a person reads them, at most three, then how many more. */
+const someNames = (names) => {
+  const shown = names.slice(0, 3).map(approvalLabel).join(', ');
+  return names.length > 3 ? `${shown} and ${names.length - 3} more` : shown;
+};
+
+/**
+ * CARD-9: a decision's headline and the line under it, short enough for a card in a list:
+ * { tag, headline, sub }.
+ */
+function headlineOf(line, story) {
+  const forStory = story ? ` · ${story.id}` : '';
+  if (line.kind === 'approvals') {
+    const who = line.request.lane ? `the ${line.request.lane} lane` : line.request.actor;
+    return {
+      headline: `Approve ${someNames(line.request.names)}`,
+      sub: `for ${who}${forStory} · ${clip(commandItself(line.files?.[0] ?? line.request.what), 70)}`,
+    };
+  }
+  if (line.kind === 'held')
+    return {
+      headline: `${line.held.who} wants to ${line.text.replace(/^.*? wants to /, '').replace(/ · \d+:\d+$/, '')}`,
+      sub: `held${forStory} · ${line.text.match(/\d+:\d+$/)?.[0] ?? ''} left`,
+    };
+  if (line.kind === 'question')
+    return {
+      headline: line.question.question,
+      sub: `from the lead${forStory}${line.question.blocks ? ', which waits on it' : ''}`,
+    };
+  if (line.kind === 'brief')
+    return { headline: line.brief.question, sub: `open in ${line.brief.path}` };
+  if (line.kind === 'denied')
+    return {
+      headline: `Claude Code refused ${line.denial.who}'s call`,
+      sub: clip(line.denial.command ?? line.denial.what, 80),
+    };
+  if (line.kind === 'report')
+    return { headline: line.report.title, sub: "drafted by an agent, for code-kit's GitHub" };
+  return { headline: line.text, sub: story ? `${story.id} ${story.title ?? ''}` : '' };
+}
+
 /** Why a line needs the person, when the line itself doesn't say. */
 function whyOf(line, check) {
   if (line.kind === 'held') {
@@ -243,9 +307,13 @@ export function decisionCards(lines, context = {}) {
               `${a.name} is approved${a.lane ? ` for the ${a.lane} lane` : ''}${a.reason ? `: ${a.reason}` : ''}`,
           ),
       ].slice(-5);
+      const { headline, sub } = headlineOf(line, story);
       return {
         id: `${line.kind}-${i}`,
         kind: line.kind,
+        tag: TAG[line.kind] ?? 'decision',
+        headline: clip(headline, 100),
+        sub,
         line,
         // The band line it came from: one line can stand for several decisions (CARD-8).
         source,
@@ -260,14 +328,22 @@ export function decisionCards(lines, context = {}) {
         })),
         doing:
           line.held?.command ??
-          (line.request ? askWords(line.request, line.files ?? [line.request.what]) : null) ??
+          (line.request
+            ? clip(
+                askWords(
+                  line.request,
+                  (line.files ?? [line.request.what]).map((f) => commandItself(f)),
+                ),
+                300,
+              )
+            : null) ??
           (line.proposal?.label ? `Next step: ${line.proposal.label}` : null) ??
           (line.intent
             ? `Intent #${line.intent.id}: ${line.intent.about}${line.intent.touches.length ? ` (touches ${line.intent.touches.join(', ')})` : ''}`
             : null) ??
           (line.pull ? `Pull request #${line.pull.number} on ${line.pull.branch}` : null) ??
           (line.question?.blocks ? `${line.question.story} waits on your answer.` : null) ??
-          (line.denial ? (line.denial.command ?? line.denial.what) : null) ??
+          (line.denial ? clip(line.denial.command ?? line.denial.what, 400) : null) ??
           (line.report ? line.report.body : null),
         settled,
         why: whyOf(line, check),

package/hooks/mod/panes.mjs

@@ -1257,10 +1257,15 @@ export function codeTab(view, { Box, Text, Button, Svg }, on) {
   return [picker, drawing, legend, detail, keys];
 }
 
+/** CARD-9: how many decision cards the list shows at once, around the selected one. */
+const CARDS_SHOWN = 5;
+
 /**
- * DECIDE-3: the Decisions tab: each decision that needs the person, the selected one as a card with its
- * lineage (what they asked for, the story and requirements, what was happening, what's settled, why it
- * needs them) and its options, each saying what it does. `on`: onDecision(i), onNeed(id, line).
+ * DECIDE-3, CARD-9: the Decisions tab: how many decisions need the person, by kind; then each as a short
+ * card (its kind, a one-line headline, and who or what it's for), a few at a time around the selected
+ * one, with j and k to move; then the selected one in full, with its lineage (what they asked for, the
+ * story and requirements, what was happening, what's settled, why it needs them) and its options, each
+ * saying what it does. `on`: onDecision(i), onNeed(id, line).
  */
 export function decisionsTab(cards, ui, { Box, Text, Button }, on) {
   const text = (value, style = {}) => Text({ ...style, children: [value] });
@@ -1277,27 +1282,82 @@ export function decisionsTab(cards, ui, { Box, Text, Button }, on) {
         text(value, { wrap: 'wrap', ...style }),
       ],
     });
+  const kinds = new Map();
+  for (const c of cards) kinds.set(c.tag, (kinds.get(c.tag) ?? 0) + 1);
+  const from = Math.max(0, Math.min(at - Math.floor(CARDS_SHOWN / 2), cards.length - CARDS_SHOWN));
+  const shown = cards.slice(from, from + CARDS_SHOWN);
   const list = Box({
     key: 'decision-list',
     flexDirection: 'column',
-    children: cards.map((c, i) =>
+    children: [
+      ...(from > 0 ? [text(`  ↑ ${from} more`, { key: 'decision-above', dimColor: true })] : []),
+      ...shown.map((c, n) => {
+        const i = from + n;
+        return Box({
+          key: `decision-item-${i}`,
+          flexDirection: 'column',
+          borderStyle: 'round',
+          borderColor: i === at ? 'yellow' : 'gray',
+          paddingX: 1,
+          children: [
+            Box({
+              flexDirection: 'row',
+              columnGap: 1,
+              children: [
+                text(c.tag.toUpperCase(), { color: i === at ? 'yellow' : 'cyan', bold: true }),
+                Button({
+                  key: `decision-pick-${i}`,
+                  label: c.headline,
+                  plain: true,
+                  onPress: () => on.onDecision(i),
+                }),
+              ],
+            }),
+            ...(c.sub ? [text(c.sub, { dimColor: true, wrap: 'truncate-end' })] : []),
+          ],
+        });
+      }),
+      ...(from + CARDS_SHOWN < cards.length
+        ? [
+            text(`  ↓ ${cards.length - from - CARDS_SHOWN} more`, {
+              key: 'decision-below',
+              dimColor: true,
+            }),
+          ]
+        : []),
+    ],
+  });
+  const keys = Box({
+    key: 'decision-keys',
+    flexDirection: 'row',
+    columnGap: 2,
+    children: [
       Button({
-        key: `decision-pick-${i}`,
-        label: `${i === at ? '›' : ' '} ${c.title}`,
+        key: 'decision-next',
+        label: 'Next',
+        hotkey: 'j',
         plain: true,
-        onPress: () => on.onDecision(i),
+        onPress: () => on.onDecision(Math.min(at + 1, cards.length - 1)),
       }),
-    ),
+      Button({
+        key: 'decision-prev',
+        label: 'Previous',
+        hotkey: 'k',
+        plain: true,
+        onPress: () => on.onDecision(Math.max(at - 1, 0)),
+      }),
+      text(`${at + 1} of ${cards.length}`, { dimColor: true }),
+    ],
   });
   const detail = Box({
     key: 'decision-card',
     flexDirection: 'column',
-    borderStyle: 'round',
+    borderStyle: 'double',
     borderColor: 'yellow',
     paddingX: 1,
     rowGap: 0,
     children: [
-      text(card.title, { bold: true }),
+      text(card.headline, { bold: true, wrap: 'wrap' }),
       ...(card.asked ? [row('You asked for', card.asked)] : []),
       ...(card.story
         ? [
@@ -1353,7 +1413,18 @@ export function decisionsTab(cards, ui, { Box, Text, Button }, on) {
       `${cards.length} decision${cards.length === 1 ? '' : 's'} need${cards.length === 1 ? 's' : ''} you. Everything else is the lead's.`,
       { bold: true },
     ),
-    ...(cards.length > 1 ? [list] : []),
+    Box({
+      key: 'decision-kinds',
+      children: [
+        text(
+          [...kinds]
+            .map(([tag, n]) => `${n} ${tag}${n === 1 || tag.endsWith('brief') ? '' : 's'}`)
+            .join(' · '),
+          { dimColor: true },
+        ),
+      ],
+    }),
+    ...(cards.length > 1 ? [list, keys] : []),
     detail,
   ];
 }

package/hooks/mod/register.mjs

@@ -19,6 +19,7 @@ import {
   shownState,
   attribution,
   answerPane,
+  approvalAsidePrompt,
   approvePane,
   commandItself,
   band,
@@ -59,7 +60,7 @@ import {
   withoutInFlight,
 } from './loop.mjs';
 import { goalOf, nextText } from './mission.mjs';
-import { contextOf, decisionCards } from './decisions.mjs';
+import { contextOf, decisionCards, limitsWhy } from './decisions.mjs';
 import { DEFAULT_TEAM_UI, TEAM_ID, teamFrame } from './teamview.mjs';
 import { glowOf, mapStoryOf, touchOf } from './codemap.mjs';
 import { harnessSettings } from '../lib/harness.mjs';
@@ -501,6 +502,8 @@ export function register(on) {
           reason: prefilledReason(line.request),
           error: null,
           heldId: line.heldId ?? null,
+          outside: line.outside ?? null,
+          aside: { thread: [], draft: '' },
         };
         await $.ui.open({ id: APPROVE_ID, title: 'Approve', focus: true, closeOnEscape: true });
         $.ui.invalidate('ui.render');
@@ -663,9 +666,58 @@ export function register(on) {
       // HOLD-2: Approve opens ACT-1's confirmation for the held call; Refuse lets the refusal through.
       approveHeld: (line) =>
         act.approve({
-          request: { names: line.held.names, lane: line.held.lane, what: line.held.what },
+          request: {
+            names: line.held.names,
+            lane: line.held.lane,
+            what: line.held.what,
+            why: line.held.refusal ?? null,
+          },
           heldId: line.held.id,
+          outside: line.held.outside ?? null,
         }),
+      // ACT-5: a question about the approval, answered in its pane by a side call over the lead's own
+      // conversation (it shares the prompt cache, and nothing is added to the conversation); before the
+      // lead's first reply, from code-kit's facts alone.
+      askApproval: async (question) => {
+        const q = question.trim();
+        if (!approving || !q) return;
+        const asked = approving;
+        const thread = asked.aside.thread;
+        const turn = { question: q, pending: true };
+        approving = { ...asked, aside: { thread: [...thread, turn], draft: '' } };
+        $.ui.invalidate('ui.render');
+        const row = (model.state?.lanes ?? []).find((l) => l.name === asked.request.lane);
+        const prompt = approvalAsidePrompt({
+          request: asked.request,
+          story: row?.story ?? null,
+          outside: limitsWhy(asked.outside) ?? null,
+          thread,
+          question: q,
+        });
+        let reply = await $.model
+          .fork({ prompt })
+          .catch((err) => ({ isAnswered: false, reason: String(err?.message ?? err) }));
+        if (!reply.isAnswered && reply.reason === 'nothing-to-fork')
+          reply = await $.model
+            .complete({ model: 'sonnet', prompt, maxTokens: 800 })
+            .catch((err) => ({ isAnswered: false, reason: String(err?.message ?? err) }));
+        // Answered for this approval only: a pane closed or moved on meanwhile keeps what it has.
+        if (!approving || approving.request !== asked.request) return;
+        const done = reply.isAnswered
+          ? { question: q, answer: reply.text }
+          : {
+              question: q,
+              error: `No answer: ${reply.reason}${reply.status ? ` (${reply.status})` : ''}`,
+            };
+        approving = {
+          ...approving,
+          aside: {
+            ...approving.aside,
+            thread: approving.aside.thread.map((t) => (t === turn ? done : t)),
+          },
+        };
+        $.ui.invalidate('ui.render');
+      },
       refuseHeld: async (line) => {
         await answerHeld(line.held.id, 'refused');
       },
@@ -1934,6 +1986,11 @@ export function register(on) {
       },
       onSubmit: (value) => act.confirmApproval(value),
       onCancel: () => act.cancelApproval(),
+      onAskInput: (value) => {
+        approving = { ...approving, aside: { ...approving.aside, draft: value } };
+        $.ui.invalidate('ui.render');
+      },
+      onAsk: (value) => act.askApproval(value),
     });
   });
 

package/hooks/mod/register.test.ts

@@ -160,6 +160,8 @@ function project() {
     questions: [] as any[], // `code-kit ask --json`
     reports: [] as any[], // `code-kit report --json`
     fills: [] as string[], // what the mod put in the prompt
+    sideAsks: [] as any[], // side calls: { fork } or { model }, with their prompt
+    sideReply: { isAnswered: true, text: 'dayjs formats the booking dates.', usage: null } as any,
     holdWaits: false, // false: the hold ends at once, as if timed out (tests about cards, not hold)
     waiting: new Map<string, (answer: string) => void>(),
   };
@@ -347,6 +349,14 @@ function stub(on: any, w: World) {
     return { value: { agent: `code-kit:${e.name}` } };
   });
   on('prompt.read', () => ({ value: { text: w.draft, cursor: w.draft.length } }));
+  on('model.fork', ($: any, e: any) => {
+    w.sideAsks.push({ fork: true, prompt: e.prompt });
+    return { value: w.sideReply };
+  });
+  on('model.complete', ($: any, e: any) => {
+    w.sideAsks.push({ model: e.model, prompt: e.prompt });
+    return { value: { isAnswered: true, text: 'From the facts alone.', usage: null } };
+  });
   // Claude Code's own settings hooks beneath: none answer a permission denial.
   on('classic.PermissionDenied', () => ({}));
   on('prompt.fill', ($: any, e: any) => {
@@ -644,6 +654,56 @@ test('ACT-1 the person may type their own reason, and an empty one is not accept
   await ui.unmount();
 });
 
+test("ACT-5 the person asks about an approval in its pane; the answer stays there, out of the lead's conversation", async ($, on) => {
+  const w = project();
+  w.requests = [dayjs];
+  await start($, on, w);
+  const ui = await bandUi($);
+  await press($, 'band-approve');
+  const confirm = await pane($, APPROVE);
+  await $.ui.input({
+    plugin: 'code-kit',
+    key: 'approve-ask',
+    text: 'Why does the booking form need this?',
+  });
+  expect(w.sideAsks).toHaveLength(1);
+  expect(w.sideAsks[0].fork).toBe(true);
+  expect(w.sideAsks[0].prompt).toMatch(/approvals asked for: dep-dayjs/);
+  expect(w.sideAsks[0].prompt).toMatch(/for: the web lane/);
+  expect(w.sideAsks[0].prompt).toMatch(/story: ST-4 Booking form/);
+  expect(w.sideAsks[0].prompt).toMatch(/Question: Why does the booking form need this\?$/);
+  expect(
+    await confirm.find({ type: 'Text', text: 'You: Why does the booking form need this?' }),
+  ).toBeDefined();
+  expect(JSON.stringify(await confirm.find({ key: 'aside-a-0' }))).toMatch(
+    /dayjs formats the booking dates/,
+  );
+  // A follow-up carries the aside so far; nothing went to the lead, and nothing was approved.
+  await $.ui.input({ plugin: 'code-kit', key: 'approve-ask', text: 'Is it maintained?' });
+  expect(w.sideAsks[1].prompt).toMatch(
+    /Q: Why does the booking form need this\?\nA: dayjs formats the booking dates\./,
+  );
+  expect(w.prompts).toEqual([]);
+  expect(w.acts).toEqual([]);
+  await confirm.unmount();
+  await ui.unmount();
+});
+
+test('ACT-5 before the lead has replied there is nothing to fork: it answers from the facts alone', async ($, on) => {
+  const w = project();
+  w.requests = [dayjs];
+  w.sideReply = { isAnswered: false, reason: 'nothing-to-fork' };
+  await start($, on, w);
+  const ui = await bandUi($);
+  await press($, 'band-approve');
+  const confirm = await pane($, APPROVE);
+  await $.ui.input({ plugin: 'code-kit', key: 'approve-ask', text: 'What is it?' });
+  expect(w.sideAsks.map((a) => a.model ?? 'fork')).toEqual(['fork', 'sonnet']);
+  expect(JSON.stringify(await confirm.find({ key: 'aside-a-0' }))).toMatch(/From the facts alone/);
+  await confirm.unmount();
+  await ui.unmount();
+});
+
 test('ACT-1 cancelling writes nothing', async ($, on) => {
   const w = project();
   w.requests = [dayjs];
@@ -1461,13 +1521,10 @@ test("ASK-4 the brief's open questions are the person's decisions: answered to t
   await press($, 'band-openDecision');
   await band.unmount();
   const ui = await pane($, PANE);
-  expect(
-    await ui.find({ type: 'Text', text: 'From your brief: Accounts: AWS, Supabase, Fly' }),
-  ).toBeDefined();
+  expect(await ui.find({ type: 'Text', text: 'Accounts: AWS, Supabase, Fly' })).toBeDefined();
+  expect(await ui.find({ type: 'Text', text: 'open in docs/brief.md' })).toBeDefined();
   await press($, 'decide-laterBrief', PANE);
-  expect(
-    await ui.find({ type: 'Text', text: 'From your brief: The product domain' }),
-  ).toBeDefined();
+  expect(await ui.find({ type: 'Text', text: 'The product domain' })).toBeDefined();
   await press($, 'decide-answerBrief', PANE);
   const box = await pane($, 'code-kit-answer');
   await $.ui.input({ plugin: 'code-kit', key: 'answer-text', text: 'myaila.com.au' });
@@ -1542,6 +1599,45 @@ test('CARD-8 two approvals waiting are two decisions, each approved or dropped o
   await ui.unmount();
 });
 
+test('CARD-9 many decisions read as short cards, a few at a time, with the selected one in full', async ($, on) => {
+  const w = project();
+  w.requests = Array.from({ length: 8 }, (_, i) => ({
+    ...dayjs,
+    at: `2026-10-06T00:0${i}:00.000Z`,
+    names: [`dep-pkg${i}`, 'dep-a', 'dep-b', 'dep-c'],
+    what: `pnpm --filter @app/web add pkg${i} a b c 2>&1 | tail -20 && cat > tsconfig.json <<'EOF'\n{ "x": 1 }\nEOF`,
+  }));
+  w.questions = [question()];
+  await start($, on, w);
+  const band = await bandUi($);
+  await press($, 'band-decide');
+  await band.unmount();
+  const ui = await pane($, PANE);
+  expect((await ui.find({ key: 'decision-kinds' }))?.text).toBe('8 approvals · 1 question');
+  // Five cards at a time, each a headline and a line under it; the command cut at its pipe, on one line.
+  expect(await ui.find({ key: 'decision-item-4' })).toBeDefined();
+  expect(await ui.find({ key: 'decision-item-5' })).toBeUndefined();
+  expect(await ui.find({ type: 'Text', text: '  ↓ 4 more' })).toBeDefined();
+  expect((await ui.find({ key: 'decision-pick-0' }))?.props.label).toBe(
+    'Approve pkg0, a, b and 1 more',
+  );
+  expect(
+    await ui.find({
+      type: 'Text',
+      text: 'for the web lane · ST-4 · pnpm --filter @app/web add pkg0 a b c',
+    }),
+  ).toBeDefined();
+  expect((await ui.findAll({ type: 'Text' })).some((t: any) => /tsconfig|EOF/.test(t.text))).toBe(
+    false,
+  );
+  await press($, 'decision-next', PANE);
+  await press($, 'decision-next', PANE);
+  await press($, 'decision-next', PANE);
+  expect(await ui.find({ type: 'Text', text: /↑ \d+ more/ })).toBeDefined();
+  expect((await ui.findAll({ type: 'Text' })).some((t: any) => t.text === '4 of 9')).toBe(true);
+  await ui.unmount();
+});
+
 test('REPORT-3 a bug report an agent drafted waits for the person, who reads it and sends it, or discards it', async ($, on) => {
   const w = project();
   w.reports = [

package/hooks/mod/view.mjs

@@ -1057,10 +1057,11 @@ const NOTE_KINDS = new Set(['usage', 'paused', 'finish', 'done', 'teamDown']);
 /** The Approve… confirmation (ACT-1): what it grants, to whom, for how long, and the reason. */
 export function approvePane(
   approving,
-  { Box, Text, Input, Button },
-  { onInput, onSubmit, onCancel },
+  { Box, Text, Input, Button, Markdown },
+  { onInput, onSubmit, onCancel, onAskInput, onAsk },
 ) {
   const { request, reason, error } = approving;
+  const aside = approving.aside ?? { thread: [], draft: '' };
   return Box({
     flexDirection: 'column',
     rowGap: 1,
@@ -1071,6 +1072,30 @@ export function approvePane(
           `For ${request.lane ? `the ${request.lane} lane` : 'any agent'}, ${request.names.every((n) => n.startsWith('dep-')) ? 'until the install is committed (at most 7 days)' : 'for 60 minutes'}. Asked for: ${request.what}`,
         ],
       }),
+      // ACT-5: an aside about this approval, answered here and never in the lead's conversation.
+      ...aside.thread.flatMap((turn, i) => [
+        Text({ key: `aside-q-${i}`, color: 'cyan', children: [`You: ${turn.question}`] }),
+        turn.pending
+          ? Text({ key: `aside-a-${i}`, dimColor: true, children: ['Asking…'] })
+          : turn.error
+            ? Text({ key: `aside-a-${i}`, color: 'red', children: [turn.error] })
+            : Markdown
+              ? Markdown({ key: `aside-a-${i}`, text: turn.answer })
+              : Text({ key: `aside-a-${i}`, children: [turn.answer] }),
+      ]),
+      ...(onAsk
+        ? [
+            Input({
+              key: 'approve-ask',
+              label: 'Ask about it',
+              value: aside.draft,
+              placeholder: 'What is it for, and what does approving it let happen?',
+              submitLabel: 'Ask',
+              onInput: onAskInput,
+              onSubmit: onAsk,
+            }),
+          ]
+        : []),
       Input({
         key: 'approve-reason',
         label: 'Reason',
@@ -1093,6 +1118,44 @@ export function approvePane(
   });
 }
 
+/**
+ * ACT-5: the side call's prompt for a question about an approval: what code-kit knows of the request (the
+ * names, the lane, what was refused and why, its story, the limits it missed), the aside so far, and the
+ * question. It answers in the pane, never in the conversation, and acts on nothing.
+ */
+export function approvalAsidePrompt({
+  request,
+  story = null,
+  outside = null,
+  thread = [],
+  question,
+}) {
+  return [
+    "The person is deciding whether to approve something code-kit stopped, and asks you about it in code-kit's approval pane. Answer in a few short sentences, in plain words: what it is, why it's needed for the work, what approving it lets happen, and anything risky about it. Use what you know from this conversation and the facts below. If you don't know, say so; don't guess. This answer goes to that pane, not into the conversation: don't act on it, and don't change your plans because of it.",
+    '',
+    'The approval:',
+    `- approvals asked for: ${request.names.join(', ')}`,
+    `- for: ${request.lane ? `the ${request.lane} lane` : (request.actor ?? 'an agent')}`,
+    `- what was refused: ${request.what}`,
+    ...(request.why ? [`- why code-kit refused it: ${request.why}`] : []),
+    ...(story
+      ? [
+          `- story: ${story.id} ${story.title ?? ''}${story.requirements?.length ? ` (${story.requirements.join(', ')})` : ''}`,
+        ]
+      : []),
+    ...(outside ? [`- outside the limits the person set for the lead: ${outside}`] : []),
+    ...(thread.length
+      ? [
+          '',
+          'Asked so far:',
+          ...thread.flatMap((t) => [`Q: ${t.question}`, `A: ${t.answer ?? t.error ?? ''}`]),
+        ]
+      : []),
+    '',
+    `Question: ${question}`,
+  ].join('\n');
+}
+
 export const ANSWER_ID = 'code-kit-answer';
 
 /** ASK-2, ASK-4: the person's answer to the lead's question, or to one in their brief, typed. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warren-dean/code-kit",
-  "version": "0.12.0",
+  "version": "0.12.2",
   "description": "Keeps AI coding agents inside your project's rules: lanes, layer rules, protected paths and proof before finish, enforced by Claude Code hooks and in CI",
   "license": "MIT",
   "author": "Warren Langeveldt",