@warren-dean/code-kit 0.3.12 → 0.4.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.3.12",
+      "version": "0.4.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.3.12",
+  "version": "0.4.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,40 @@
 
 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.4.1 (2026-10-07)
+
+- **The band keeps other plugins' lines:** code-kit's lines go above whatever else the band holds, such as Context Graph's "N proposals to ratify", instead of replacing it.
+
+## 0.4.0 (2026-10-07)
+
+code-kit in the session: a mod for Claude Code 2.1.287 or later, in the terminal and the Desktop app. Older versions skip it and keep enforcing everything through the hooks, as before. See [In the session](README.md#in-the-session).
+
+- **The band** above the prompt shows what waits for you: approvals agents asked for (**Approve…**, with a reason you keep or rewrite), stories ready for review (**Review**, **Merge**), and a finish check failing. Each has a digit hotkey, and the band is gone when nothing waits.
+- **`/lanes`** opens a pane with each lane's agent, story, branch and state, the agents at work, and what's ready. It stays current within 2 seconds of a change.
+- **Refusal cards:** a code-kit refusal reads as a card with the rule, what to do, and Approve… where an approval would allow it.
+- **`/approvals`** and **`/verify-branch`** print without a model call.
+- **New in the CLI:** `code-kit stops` lists finish checks still failing, and `check --json` reports the config's state for the mod.
+- A merge from the pane says so in its commit.
+- `code-kit` with no command now prints its whole usage.
+
+## 0.3.15 (2026-10-06)
+
+- **`verify` accepts your Context Graph ratifications:** a change to `.ctx/graph.ctx` whose commits all carry your `Ctx-Ratified-By` trailer passes without an approval-log entry. That's what `ctx ratify --commit` and `ctx drop --commit` write from your terminal, where code-kit's hooks don't run to log it. Agents still can't write that trailer, and a delegated trailer still needs the log.
+
+## 0.3.14 (2026-10-06)
+
+- **Context Graph's person acts:** with Context Graph in the project, the hooks refuse `ctx ratify … --commit` and `ctx drop` from every agent, matching Context Graph 0.2.11, which makes both the person's own acts. Only a real command counts; text that mentions one, such as an `echo` or documentation, isn't refused.
+
+## 0.3.13 (2026-10-06)
+
+The command-line groundwork for the coming code-kit mod (`docs/brief.md`), useful on its own:
+
+- **Approval requests:** every refusal that a person's approval would allow is now recorded as a request, once per actor and command. `code-kit requests [--json]` lists the open requests and the approvals in force, with minutes left. A request closes when its approvals are given.
+- **`code-kit approve … --via pane`** marks an approval as given in the code-kit pane.
+- **`code-kit merge <branch> --person`:** the person merges a branch after `verify` passes, with no delegation needed.
+- **Agents:** the hooks refuse `--via` and `--person` from every agent.
+- **`code-kit verify --json`** prints the branch, its lane and the problems by group.
+
 ## 0.3.12 (2026-10-05)
 
 - **Delegated merges:** with `"approvals": { "delegate": { "merge": true } }`, the lead can merge a reviewed branch into a protected branch with `code-kit merge <branch> --delegated`. This is for an autonomous lead.

package/README.md

@@ -101,6 +101,7 @@ Set it up at the start of a new build, straight from the architecture docs, or b
   | `Stop`, `SubagentStop`   | `hooks/stop-check.mjs`      | proof before finishing                                            |
 
 - **For the main session and every subagent**, including agents in worktrees under `.claude/worktrees/`.
+- **In front of you, in the terminal and the Desktop app,** through the code-kit mod (Claude Code 2.1.287 or later; see [In the session](#in-the-session)). It shows and acts, and never enforces: the hooks above do that everywhere, the mod or not.
 - **In CI**, through `code-kit verify` in a GitHub Actions workflow that init can install (`templates/github-workflow.yml`).
 - **Locally, with Node 22 or later.** Nothing is sent anywhere. The CLI in `bin/` runs the same rules from a terminal.
 
@@ -261,6 +262,23 @@ Editing an agent file can't loosen a rule. And the agent files are kit files (`.
 
 **Kept in step.** When the project changes (a new app, a new lane, moved folders), re-run `/code-kit:init`. It drafts new agents for new lanes and updates the paths of existing ones, keeping anything written by hand. You see the difference and approve it before anything changes.
 
+## In the session
+
+With Claude Code 2.1.287 or later, code-kit's mod shows the project in the session, in the terminal (VS Code's terminal included) and the Desktop app. Older versions skip it and keep enforcing everything through the hooks.
+
+- **The band** sits above the prompt whenever something waits for you, and is gone when nothing does. It shows:
+  - approvals agents have asked for: **Approve…** opens a confirmation with a reason prefilled from the request, which you keep or rewrite;
+  - stories finished and waiting for review: **Review** asks the lead to run `/code-kit:review` on the branch, and **Merge** runs `verify`, checks included, then merges if it passes;
+  - a finish check failing in this session: **Lanes** opens the pane.
+
+  Each button has a digit: type it in an empty prompt to press it.
+
+- **`/lanes`** opens the Lanes pane: each lane with its agent, story, branch and state (building, in review, blocked, idle), a mark while its agent is at work, and the stories ready to start. 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.
+- **`/approvals`** lists the requests waiting and the approvals in force, with minutes left. **`/verify-branch`** runs `code-kit verify` on this branch. Neither calls the model.
+
+Approving from the band records `(approved in the code-kit pane)` with your reason, and a merge from it says it was merged by the person from the pane. Both happen only on your press: the hooks refuse `approve --via pane` and `merge --person` from every agent. Outside a project with `.claude/code-kit.json`, the mod draws nothing. Mods don't draw in the VS Code extension's chat panel, the Agent SDK or `claude -p`.
+
 ## Build
 
 Once init has switched the rules on, the lead runs the build in a loop:
@@ -299,18 +317,20 @@ Lanes never change silently: only when you approve the diff.
 Run from the project root, as `code-kit <command>` once installed (`npm i -g @warren-dean/code-kit`), or `npx @warren-dean/code-kit <command>`. Add `--config .claude/code-kit.draft.json` to any command to read a draft instead. In a session, the `/code-kit:check` skill runs `check` and `unowned` for you. `next` also works in a project without code-kit, or outside a git repository.
 
 ```bash
-code-kit check              # validate and summarise
+code-kit check [--json]     # validate and summarise
 code-kit who <path>...      # owner and layer of each path
 code-kit unowned            # tracked files nobody may write
 code-kit diff --config .claude/code-kit.draft.json  # what a draft changes
 code-kit baseline [--write] # layer violations in the code as it is
 code-kit graph [--depth N]  # which folders import which
-code-kit verify [--base ref] [--branch name] [--no-checks]  # a branch's changes, for CI and review
+code-kit verify [--base ref] [--branch name] [--no-checks] [--json]  # a branch's changes, for CI and review
 code-kit status [--base ref] [--json]  # stories and requirements against the spec
 code-kit next [--base ref] [--json]    # the step to take now, from the project's state
 code-kit trace <path>... [--json]      # what a file is for: requirements, lane, layer rules
-code-kit merge <branch> --delegated [--into branch]  # the lead merges a branch that passes verify, where approvals.delegate.merge is on
-code-kit approve <name>... --reason "…" [--lane name] [--delegated]  # record a person's approval from chat, or (--delegated) grant one within the delegated rules; a package name stands for its dep- approval
+code-kit merge <branch> --delegated|--person [--into branch]  # merge a branch that passes verify: the lead where approvals.delegate.merge is on, or the person
+code-kit requests [--json]                                   # approval requests the hooks refused, still open, and the approvals in force
+code-kit stops [--session id] [--json]                       # finish checks that refused an agent's last stop and still fail
+code-kit approve <name>... --reason "…" [--lane name] [--delegated | --via pane]  # record a person's approval from chat, or (--delegated) grant one within the delegated rules; a package name stands for its dep- approval
 ```
 
 `verify` compares the branch with where it left `--base` (default `origin/main`, then `main`). A branch named `<lane>/…`, or given as `--branch`, is held to that lane. `--no-checks` leaves the project's checks to CI's own steps. `status` reads `docs.specs` and `docs.plan`.
@@ -372,6 +392,12 @@ code-kit approve dep-dayjs --lane web --reason "Yes, add dayjs for ST-12"
 - The lead may also run `shell.block` commands marked `person: true`, such as Context Graph's ratification trailer.
 - It trusts the lead to act only on the person's own words. Leave it off when the lead runs without a person watching.
 
+### Requests
+
+Every refusal that a person's approval would allow is recorded as a request in `.claude/state/requests.jsonl` in the main checkout: who was refused, the approvals that would allow it, the command or file, and why. A request stays open until approvals for all its names are in force, or for 60 minutes. `code-kit requests` lists the open ones and the approvals in force, with minutes left, and the code-kit mod shows them above the prompt.
+
+`--via pane` and `merge --person` are the person's own acts, which the code-kit mod uses for a press in its pane. The hooks refuse both from every agent.
+
 ### Delegated
 
 For a lead that runs without a person watching, such as an autonomous team, `approvals.delegate` lets the lead approve some things on its own authority, within rules the person sets in the config:
@@ -404,9 +430,9 @@ Other tools share a project with code-kit and keep files of their own. An adapte
 
 While the tool is detected, its additions are merged into the effective config, like the kit's own defaults. Run `code-kit adapters` to see them, or switch one off with `"adapters": { "<name>": false }`.
 
-| Adapter         | Detected by | Adds                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| --------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `context-graph` | `.ctx/`     | `.ctx/**` for the lead. `.ctx/decisions.ctx` and `.ctx/cards.ctx` for any actor, since every agent records decisions and file cards. `graph.ctx` and `config.toml` are protected (approval `ctx`). No Claude actor may write a person's `Ctx-Ratified-By` trailer: ratifying is a person's act (with `approvals.lead`, the lead may add it when the person says so in chat). A delegated trailer, `Ctx-Ratified-By: <ratifier> (delegated)`, is the lead's alone, under Context Graph's `[delegate]` rules. |
+| Adapter         | Detected by | Adds                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| --------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `context-graph` | `.ctx/`     | `.ctx/**` for the lead. `.ctx/decisions.ctx` and `.ctx/cards.ctx` for any actor, since every agent records decisions and file cards. `graph.ctx` and `config.toml` are protected (approval `ctx`). No Claude actor may write a person's `Ctx-Ratified-By` trailer: ratifying is a person's act (with `approvals.lead`, the lead may add it when the person says so in chat). A delegated trailer, `Ctx-Ratified-By: <ratifier> (delegated)`, is the lead's alone, under Context Graph's `[delegate]` rules. `verify` accepts a `graph.ctx` change whose commits carry a person's trailer (`ctx ratify --commit`, `ctx drop --commit`) without an approval-log entry. Agents can't run those commands. |
 
 Its setup:
 

package/bin/code-kit.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // Run from the project root: node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs" <command>
-//   check                 validate the config and summarise it
+//   check [--json]        validate the config and summarise it
 //   who <path>...         who may write each path, and its layer
 //   unowned               tracked files nobody may write
 //   diff                  what a draft changes against the live config, and whose files move
@@ -15,11 +15,14 @@
 //   next [--base ref] [--json]
 //                         the step to take now (spec-design, init, dispatch, review…), from the project's state
 //   approve <name>... --reason "…" [--lane name]
-//   merge <branch> --delegated [--into branch]  the lead merges a branch that passes verify (approvals.delegate.merge)
+//   merge <branch> --delegated|--person [--into branch]  merge a branch that passes verify: the lead
+//                                    (approvals.delegate.merge) or the person (the code-kit pane)
+//   requests [--json]                 open approval requests and approvals in force
+//   stops [--session id] [--json]     finish checks that refused an agent's last stop, still failing
 //                         record approvals a person gave in chat (with approvals.lead on, the lead runs it)
 // --config <file> reads a draft (.claude/code-kit.draft.json) instead of .claude/code-kit.json.
 import { execFileSync } from 'node:child_process';
-import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join, posix, resolve } from 'node:path';
 import { BASELINE_FILE, loadBaseline } from '../hooks/lib/baseline.mjs';
@@ -34,8 +37,11 @@ import { buildStatus } from '../hooks/lib/plan.mjs';
 import {
   APPROVAL_MINUTES,
   currentBranch,
+  PANE,
+  approvalsInForce,
   delegatedMark,
   grantApprovals,
+  openRequests,
   ownerOf,
 } from '../hooks/lib/rules.mjs';
 import { DEPENDENCY_APPROVAL, dependencyApproval } from '../hooks/lib/dependencies.mjs';
@@ -65,7 +71,9 @@ const branchName = option('--branch');
 const reason = option('--reason');
 const laneName = option('--lane');
 const intoName = option('--into');
-const FLAGS = ['--write', '--no-checks', '--json', '--delegated'];
+const via = option('--via');
+const sessionId = option('--session');
+const FLAGS = ['--write', '--no-checks', '--json', '--delegated', '--person'];
 const flag = (name) => args.includes(name);
 const writeBaseline = flag('--write');
 const [command, ...rest] = args.filter((a) => !FLAGS.includes(a));
@@ -86,7 +94,32 @@ function load(path = file) {
   return { raw, config: effectiveConfig(raw, '.') };
 }
 
+/** The config as the mod reads it: whether it's there and valid, and the lead's and lanes' paths. */
+function checkJson() {
+  const report = { file, exists: existsSync(resolve(file)), valid: false, problems: [] };
+  if (!report.exists) return (out(JSON.stringify(report, null, 2)), process.exit(1));
+  let raw;
+  try {
+    raw = JSON.parse(read(file));
+  } catch (e) {
+    report.problems = [e.message];
+    return (out(JSON.stringify(report, null, 2)), process.exit(1));
+  }
+  report.problems = validate(raw);
+  if (report.problems.length) return (out(JSON.stringify(report, null, 2)), process.exit(1));
+  const config = effectiveConfig(raw, '.');
+  report.valid = true;
+  report.lead = { paths: config.lead.paths };
+  report.lanes = Object.fromEntries(
+    Object.entries(config.lanes).map(([name, l]) => [name, { agent: l.agent, paths: l.paths }]),
+  );
+  report.adapters = config.adapters;
+  report.docs = config.docs ?? null;
+  out(JSON.stringify(report, null, 2));
+}
+
 function check() {
+  if (flag('--json')) return checkJson();
   const { raw } = load();
   out(`${file} is valid.`);
   out(`Lead: ${raw.lead.paths.join(', ')}`);
@@ -253,13 +286,18 @@ const VERIFY_GROUPS = {
 
 // The lead merges a reviewed branch into a protected branch on its own, only where the config delegates
 // merges, and only when `verify` passes on that branch, checks included. A person merges with git.
+// With --person, the person merges (the mod passes it for a press in its pane): the same verify first,
+// with no delegation needed. The hooks refuse --person from every agent.
 function merge(branch) {
   const { config } = load();
-  if (!flag('--delegated'))
+  const byPerson = flag('--person');
+  if (!flag('--delegated') && !byPerson)
     die(
-      "code-kit merge is the lead's delegated merge: code-kit merge <branch> --delegated. A person merges with git as usual.",
+      'code-kit merge needs --delegated (the lead, within the delegated rules) or --person (the person, as from the code-kit pane).',
     );
-  if (!config.approvals.delegate?.merge)
+  if (flag('--delegated') && byPerson)
+    die("A merge is either the lead's (--delegated) or the person's (--person), not both.");
+  if (!byPerson && !config.approvals.delegate?.merge)
     die(
       'This project doesn\'t delegate merges to the lead ("approvals.delegate.merge" isn\'t true). A person merges after review.',
     );
@@ -336,7 +374,7 @@ function merge(branch) {
         '-m',
         `Merge ${branch} into ${into}`,
         '-m',
-        `Verified with code-kit verify (${changed.length} file(s)${lane ? `, held to the ${lane} lane` : ''}) and merged by the lead within the delegated rules.`,
+        `Verified with code-kit verify (${changed.length} file(s)${lane ? `, held to the ${lane} lane` : ''}) and merged ${byPerson ? 'by the person, from the code-kit pane' : 'by the lead within the delegated rules'}.`,
         branch,
       );
     } catch (e) {
@@ -357,6 +395,51 @@ function merge(branch) {
   }
 }
 
+// Open approval requests and the approvals in force, for the person and the mod's band.
+function requests() {
+  load();
+  const open = openRequests(resolve('.'));
+  const granted = approvalsInForce(resolve('.'));
+  if (flag('--json')) return out(JSON.stringify({ open, inForce: granted }, null, 2));
+  out(open.length ? `${open.length} approval request(s) open:` : 'No approval requests open.');
+  for (const r of open)
+    out(
+      `  ${r.names.join(', ')} for ${r.lane ? `the ${r.lane} lane` : r.actor}: ${r.what}  (${r.why})`,
+    );
+  out(granted.length ? `\n${granted.length} approval(s) in force:` : '\nNo approvals in force.');
+  for (const a of granted)
+    out(
+      `  ${a.name} for ${a.lane ? `the ${a.lane} lane` : 'any agent'}, ${a.minutesLeft} min left: ${a.reason}`,
+    );
+}
+
+/** Finish checks still failing: the stop hook's last refusal for each session and agent. */
+function stops() {
+  load();
+  const dir = resolve('.claude/state/stop-blocks');
+  const found = [];
+  for (const name of existsSync(dir) ? readdirSync(dir) : []) {
+    try {
+      const b = JSON.parse(readFileSync(join(dir, name), 'utf8'));
+      if (sessionId && b.session !== sessionId) continue;
+      found.push({
+        session: b.session ?? null,
+        agent: b.agent ?? null,
+        agentType: b.agentType ?? null,
+        title: String(b.message ?? '').split('\n')[0],
+        count: b.count ?? 1,
+        at: b.at ?? null,
+      });
+    } catch {
+      // a file the hook is still writing, or not one of its own
+    }
+  }
+  if (flag('--json')) return out(JSON.stringify(found, null, 2));
+  if (!found.length) return out('No finish check is failing.');
+  for (const s of found)
+    out(`${s.agentType ?? 'the lead'}${s.session ? ` (session ${s.session})` : ''}: ${s.title}`);
+}
+
 function verify() {
   const { config } = load();
   const from = base(config, true);
@@ -376,6 +459,18 @@ function verify() {
     lane,
     checks: !flag('--no-checks'),
   });
+  if (flag('--json')) {
+    const count = Object.values(found).reduce((n, list) => n + list.length, 0);
+    out(
+      JSON.stringify(
+        { base: from, branch, lane, changed: changed.length, found, problems: count },
+        null,
+        2,
+      ),
+    );
+    if (count) process.exit(1);
+    return;
+  }
   out(
     `${changed.length} file(s) changed since ${from}${lane ? `, held to the ${lane} lane (branch ${branch})` : ''}.`,
   );
@@ -529,6 +624,11 @@ async function approve(given) {
       `Not an approval or package name: ${bad.join(', ')}. Use the name the refusal gave, e.g. kit or dep-zod, or the package's name.`,
     );
   const marks = {};
+  if (via !== undefined && via !== 'pane')
+    die('--via takes only "pane": the code-kit mod passes it for a press in its pane.');
+  if (via === 'pane' && delegated)
+    die("An approval is either the person's (--via pane) or the lead's (--delegated), not both.");
+  if (via === 'pane') for (const n of names) marks[n] = PANE;
   if (delegated) {
     const rules = config.approvals.delegate;
     if (!rules)
@@ -569,6 +669,8 @@ const commands = {
   check,
   approve: () => (rest.length ? approve(rest) : usage()),
   merge: () => (rest.length === 1 ? merge(rest[0]) : usage()),
+  requests,
+  stops,
   trace: () => (rest.length ? trace(rest) : usage()),
   adapters,
   next,
@@ -585,8 +687,9 @@ function usage() {
     'Usage: code-kit check | who <path>... | unowned | diff | baseline [--write] | graph [--depth N]\n' +
       '              | verify [--base ref] [--branch name] [--no-checks] | status [--base ref] [--json]\n' +
       '              | next [--base ref] [--json] | adapters | trace <path>... [--json]\n' +
-      '              | approve <name>... --reason "…" [--lane name]   [--config file]',
-    '              | merge <branch> --delegated [--into branch]',
+      '              | approve <name>... --reason "…" [--lane name]   [--config file]\n' +
+      '              | merge <branch> --delegated|--person [--into branch] | requests [--json]\n' +
+      '              | stops [--session id] [--json]',
   );
 }
 await (commands[command] ?? usage)();

package/hooks/guard-bash.mjs

@@ -20,6 +20,7 @@ import {
   dependencyGrants,
   owns,
   protectedEntry,
+  recordRequest,
   sessionRoot,
 } from './lib/rules.mjs';
 
@@ -101,6 +102,11 @@ if (approves && actor.kind !== 'lead')
   block(
     `Blocked: only the lead records or grants approvals. Write a short change request for the lead (what needs approving, and why), and stop.\nCommand: ${cmd}`,
   );
+// The pane's acts are the person's: no agent passes --person or --via, whatever its other permissions.
+if ((delegatedMerge && /\s--person\b/.test(cmd)) || (approves && /\s--via\b/.test(cmd)))
+  block(
+    `Blocked: merging or approving as the person is the person's own act, from the code-kit pane or their terminal. Ask them, and stop.\nCommand: ${cmd}`,
+  );
 if (delegatedMerge && actor.kind !== 'lead')
   block(
     `Blocked: only the lead merges into a protected branch. Finish your story and commit it on your branch; the lead reviews and merges it.\nCommand: ${cmd}`,
@@ -130,6 +136,13 @@ if (packages.length) {
     (p) => !approval(sessionIn ?? project, dependencyApproval(p), actor),
   );
   if (unapproved.length) {
+    recordRequest(
+      sessionIn ?? project,
+      actor,
+      unapproved.map(dependencyApproval),
+      cmd,
+      "A new dependency needs a person's approval.",
+    );
     const ask =
       actor.kind === 'lead'
         ? 'Ask the person to approve it by running'
@@ -185,6 +198,13 @@ const writes =
     cmd,
   );
 if (touchesKit && writes && actor.kind !== 'lead' && !approval(root, 'kit', actor)) {
+  recordRequest(
+    root,
+    actor,
+    'kit',
+    cmd,
+    "The .claude kit is changed only by the lead or with a person's approval.",
+  );
   block(
     `Blocked: the .claude kit is changed only by the lead or with a person's approval. Ask the lead to run\n${approvalHowTo('kit', actor, root, undefined, config)}`,
   );
@@ -237,6 +257,7 @@ function recordApprovals() {
     const granted = entry && approval(root, entry.approval, actor);
     const byDependency = actor.kind === 'lane' && dependencyChange(actor, file, root, config);
     if (entry && !granted && actor.kind !== 'lead' && !byDependency) {
+      recordRequest(root, actor, entry.approval, file, entry.why);
       block(
         `Blocked: ${file} is ${entry.why}; committing it needs a person's approval in force. Ask the lead to run\n${approvalHowTo(entry.approval, actor, root, undefined, config)}`,
       );

package/hooks/hooks.json

@@ -1,5 +1,6 @@
 {
   "description": "code-kit: lanes, protected paths with an approval log, spec-check and design gates, layer rules and the project's checks, from .claude/code-kit.json",
+  "modules": ["./mod/register.mjs"],
   "hooks": {
     "PreToolUse": [
       {

package/hooks/lib/adapters/context-graph.mjs

@@ -7,9 +7,14 @@
 // lead act on what the person says in chat (`approvals.lead`). A delegated ratification, signed
 // `Ctx-Ratified-By: <ratifier> (delegated)`, is the lead's own act under the repository's [delegate]
 // rules: only the lead may write that trailer, and Context Graph's gate checks the kinds it covers.
+// Ratifying with `--commit`, and dropping a proposal, are the person's acts in ctx too, so no actor runs
+// them; only a command in command position counts, so text that mentions one isn't refused.
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 
+const CTX = String.raw`(?:ctx|node\s+["']?[^\s"']*ctx\.mjs["']?|npx\s+(?:--yes\s+)?@warren-dean/context-graph(?:@\S+)?)`;
+const PERSONS_ACT = String.raw`(?:^|[;&|\n])\s*${CTX}\s+(?:ratify\b[^;&|\n]*\s--commit\b|drop\b)`;
+
 export default {
   name: 'context-graph',
   detect: (root) => existsSync(join(root, '.ctx')),
@@ -17,7 +22,13 @@ export default {
     lead: ['.ctx/**'],
     anyActor: ['.ctx/decisions.ctx', '.ctx/cards.ctx'],
     protected: [
-      { glob: '.ctx/graph.ctx', approval: 'ctx', why: "Context Graph's rules and concepts" },
+      {
+        glob: '.ctx/graph.ctx',
+        approval: 'ctx',
+        why: "Context Graph's rules and concepts",
+        // A person's ratification (`ctx ratify --commit`, `ctx drop --commit`) is signed, not logged.
+        signedBy: '^Ctx-Ratified-By:(?![^\\n]*\\(delegated\\))\\s*\\S',
+      },
       { glob: '.ctx/config.toml', approval: 'ctx', why: "Context Graph's settings" },
     ],
   },
@@ -28,6 +39,10 @@ export default {
         why: "Ratifying a Context Graph rule is a person's act: they add the Ctx-Ratified-By trailer themselves, with a `!` git command.",
         person: true,
       },
+      {
+        pattern: PERSONS_ACT,
+        why: "Ratifying a Context Graph proposal with --commit, and dropping one, are the person's own acts: they run them themselves, with a `!` command, or from the Context Graph pane.",
+      },
     ],
     restricted: [
       {

package/hooks/lib/adapters/index.mjs

@@ -3,7 +3,10 @@
 //
 //   name      the tool, and the key that switches it off in the config: "adapters": { "<name>": false }
 //   detect    (root) => true when the tool is in use in this project
-//   config    { lead?, anyActor?, protected? } merged into the effective config, like the kit's defaults
+//   config    { lead?, anyActor?, protected? } merged into the effective config, like the kit's defaults.
+//             A protected entry may name `signedBy`, a pattern for a commit-message line that only a
+//             person may write (the hooks block it for every actor); verify accepts a change whose
+//             commits all carry it in place of an approval-log entry
 //   shell     { block?, restricted? } block: commands refused for every Claude actor, merged into
 //             shell.block (`person: true` marks a person's act the lead may do for them under
 //             approvals.lead); restricted: commands only the lead and the listed lanes may run

package/hooks/lib/rules.mjs

@@ -14,6 +14,7 @@
 // sets `approvals.lead` (a person on a phone has no `!`), by saying so in chat for the lead to record
 // with `code-kit approve`.
 import {
+  appendFileSync,
   existsSync,
   mkdirSync,
   readFileSync,
@@ -38,6 +39,10 @@ const NEVER_WRITABLE = [`${APPROVALS_DIR}/**`, APPROVAL_LOG];
 export const CLI = fileURLToPath(new URL('../../bin/code-kit.mjs', import.meta.url));
 // Marks an approval the lead recorded from chat, so the log shows how it was given.
 export const RELAYED = '(given in chat, recorded by the lead)';
+/** Marks an approval the person gave with a button in the code-kit pane (the mod). */
+export const PANE = '(approved in the code-kit pane)';
+/** Refusals a person's approval would allow, for the mod's band and `code-kit requests`. */
+export const REQUESTS_FILE = '.claude/state/requests.jsonl';
 
 /** The command the lead runs to record approvals a person gave in chat. */
 /** Marks an approval the lead granted on its own, within `approvals.delegate`; `rule` names the rule. */
@@ -218,6 +223,102 @@ export function approval(root, name, actor) {
   return lane ?? inForce(join(dir, name));
 }
 
+const requestsFile = (root) => join(projectWorktrees(root)[0] ?? root, REQUESTS_FILE);
+const sameRequest = (a, b) =>
+  a.actor === b.actor &&
+  a.what === b.what &&
+  [...a.names].sort().join() === [...b.names].sort().join();
+
+/** Every request recorded, oldest first; unreadable lines are skipped. */
+export function readRequests(root) {
+  try {
+    return readFileSync(requestsFile(root), 'utf8')
+      .split('\n')
+      .filter(Boolean)
+      .flatMap((l) => {
+        try {
+          return [JSON.parse(l)];
+        } catch {
+          return [];
+        }
+      });
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Records that `actor` was refused something the approvals `names` would allow, once: the same
+ * actor, names and command or file within the approval lifetime count as one request. Recording
+ * never changes the refusal, so any failure here is ignored.
+ */
+export function recordRequest(root, actor, names, what, why, now = Date.now()) {
+  try {
+    const request = {
+      at: new Date(now).toISOString(),
+      actor: actor?.label ?? 'unknown',
+      ...(actor?.kind === 'lane' ? { lane: actor.lane } : {}),
+      names: [names].flat(),
+      what: String(what).slice(0, 200),
+      why: String(why).slice(0, 300),
+    };
+    const fresh = readRequests(root).filter(
+      (r) => now - Date.parse(r.at) < APPROVAL_MINUTES * 60_000,
+    );
+    if (fresh.some((r) => sameRequest(r, request))) return;
+    const file = requestsFile(root);
+    mkdirSync(dirname(file), { recursive: true });
+    appendFileSync(file, `${JSON.stringify(request)}\n`);
+  } catch {
+    // the refusal stands either way
+  }
+}
+
+/** Requests from the last 60 minutes that an approval in force doesn't yet answer, newest first. */
+export function openRequests(root, now = Date.now()) {
+  const open = [];
+  for (const r of readRequests(root).reverse()) {
+    if (now - Date.parse(r.at) >= APPROVAL_MINUTES * 60_000) continue;
+    if (open.some((o) => sameRequest(o, r))) continue;
+    const actor = r.lane ? { kind: 'lane', lane: r.lane } : { kind: 'lead' };
+    if (r.names.every((n) => approval(root, n, actor))) continue;
+    open.push(r);
+  }
+  return open;
+}
+
+/** Approvals in force now: [{ name, lane?, reason, grantedAt, minutesLeft }]. */
+export function approvalsInForce(root, now = Date.now()) {
+  const dir = approvalsDir(root);
+  const found = [];
+  const look = (folder, lane) => {
+    let names = [];
+    try {
+      names = readdirSync(folder);
+    } catch {
+      return;
+    }
+    for (const name of names) {
+      const file = join(folder, name);
+      if (statSync(file).isDirectory()) {
+        if (!lane) look(file, name);
+        continue;
+      }
+      const a = inForce(file);
+      if (!a) continue;
+      const left = APPROVAL_MINUTES - (now - Date.parse(a.grantedAt)) / 60_000;
+      found.push({
+        name,
+        ...(lane ? { lane } : {}),
+        ...a,
+        minutesLeft: Math.max(0, Math.floor(left)),
+      });
+    }
+  };
+  look(dir);
+  return found;
+}
+
 /** The dependency approvals in force for `actor`: [{ name, reason, grantedAt }]. */
 export function dependencyGrants(root, actor) {
   if (actor?.kind === 'readonly') return [];
@@ -277,6 +378,7 @@ export function writeProblem(actor, rel, root, config) {
   // The lead writes protected files without an approval: the person reviews them in the pull request,
   // and every committed change is in the audit log. Anyone else needs a person's approval as well.
   if (guarded && actor.kind !== 'lead' && !approval(root, guarded.approval, actor)) {
+    recordRequest(root, actor, guarded.approval, rel, guarded.why);
     return `${rel} is ${guarded.why} and needs a person's approval. Ask the lead (a person) to run\n${approvalHowTo(guarded.approval, actor, root, undefined, config)}`;
   }
   if (actor.kind === 'readonly') return `${actor.label} is read-only; it may not write ${rel}.`;

package/hooks/lib/verify.mjs

@@ -80,6 +80,22 @@ function logEntries(root, base) {
   return { entries, problems };
 }
 
+/**
+ * Whether every commit since `from` that changed `file` carries the trailer a protected entry names as
+ * a person's signature (`signedBy`, a pattern for one line of the message). A person's own commit from
+ * their terminal never passes through the hooks, so for such files the signature stands in for the log.
+ */
+function signedByPerson(root, from, file, signedBy) {
+  if (!signedBy) return false;
+  const out = git(root, 'log', '--format=%B%x1e', `${from}..HEAD`, '--', file);
+  const messages = out
+    .split('\x1e')
+    .map((m) => m.trim())
+    .filter(Boolean);
+  const line = new RegExp(signedBy, 'm');
+  return messages.length > 0 && messages.every((m) => line.test(m));
+}
+
 /**
  * Every problem with the branch, grouped: { ownership, protected, layers, baseline, design, checks }.
  * `lane` holds the branch to that lane's paths; `checks: false` leaves the project's checks to CI's
@@ -100,7 +116,8 @@ export function verifyBranch({ root, base, config, lane = null, checks = true })
       found.ownership.push(`${f} may hold secrets; secrets never go in the repository.`);
     if (f === APPROVAL_LOG) continue;
     const guarded = protectedEntry(f, config);
-    if (guarded && !logged.has(f))
+    const signed = guarded && !logged.has(f) && signedByPerson(root, from, f, guarded.signedBy);
+    if (guarded && !logged.has(f) && !signed)
       found.protected.push(
         `${f} is ${guarded.why}, but no approval-log entry records this change. Protected files are committed through Claude Code with code-kit, which logs them.`,
       );
@@ -114,7 +131,7 @@ export function verifyBranch({ root, base, config, lane = null, checks = true })
         isDependencyFile(f) &&
         entry?.approval === 'dependency' &&
         [null, lane].includes(laneOf(f, config));
-      const approved = (guarded && entry?.approval === guarded.approval) || dependency;
+      const approved = (guarded && entry?.approval === guarded.approval) || signed || dependency;
       if (!own && !approved)
         found.ownership.push(
           `${f}: the ${lane} lane doesn't own it (owner: ${ownerOf(f, config) ?? 'nobody'}).`,