@warren-dean/code-kit 0.12.0 → 0.12.1

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.1",
       "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.1",
   "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,12 @@
 
 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.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;

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];

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.1",
   "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",