@dieulc/workflow 0.5.0 → 0.5.1

package/README.md

@@ -41,7 +41,7 @@ Manage it with `pi list`, `pi update --extensions`, `pi remove npm:@dieulc/workf
 | `/review-prompt [global]` | Edit the reviewer's guidance (defaults to "align with the existing framework and industry best practice") |
 | `/review-status` | Show review phase, model, plan hash, findings and any error |
 | `/review` | Run one review round against the current plan file now |
-| `/commit` | Commit staged changes with an AI-summarized message (`-a`: stage tracked changes first). Confirmation-gated |
+| `/commit` | Commit staged changes with an AI-summarized message (`-a`: stage tracked changes first). Confirmation-gated; the confirmation arms the commit exemption for that run |
 | `/commit-policy [never\|ask\|allow] [global\|project]` | View or set the commit policy (default `never`: the agent cannot `git add`/`commit`/`push` — you commit, or use `/commit`) |
 
 ## Model Profiles
@@ -267,7 +267,7 @@ Settings live under `workflow.reviewMode` in `~/.pi/agent/settings.json` (global
 
 ## Commit policy
 
-By default the agent **cannot touch your git history**: the tool gate deterministically blocks `git add`, `git commit` and `git push` — including compound commands (`git add -A && git commit -m x`), global-option forms (`git -C path add`) and `powershell` wrappers. You commit manually, or run `/commit` for an AI-summarized, confirmation-gated commit (its own `git commit` runs under a one-turn bypass; `push` is never bypassed). Read-only git (`status`, `log`, `diff`, `branch -a`, `config --get`, …) stays free, and plan mode keeps its stricter read-only rules regardless.
+By default the agent **cannot touch your git history**: the tool gate deterministically blocks `git add`, `git commit` and `git push` — including compound commands (`git add -A && git commit -m x`), global-option forms (`git -C path add`) and `powershell` wrappers. You commit manually, or run `/commit` for an AI-summarized, confirmation-gated commit. Read-only git (`status`, `log`, `diff`, `branch -a`, `config --get`, …) stays free, and plan mode keeps its stricter read-only rules regardless.
 
 The default exists because prompt-only rules are soft: models habitually commit per plan step, and "never commit unless asked" instructions in CLAUDE.md-style files are famously ignored (anthropics/claude-code#58883, #68724, #7029). Claude Code, Codex CLI and OpenCode all treat agent-initiated commits as something to gate or approve — so the policy here is enforced where commands execute, not in prose:
 
@@ -288,6 +288,16 @@ The default exists because prompt-only rules are soft: models habitually commit
 
 The status line always shows the active policy (`▶ build 2/5 · commits:never`), so you can see at a glance what the agent may do to history.
 
+### `/commit` under any policy
+
+`/commit` works under `never` and `allow`-during-a-plan because it is the user's own request. The flow is multi-turn (read the staged diff → confirm the message in a questionnaire → commit), so the exemption is **armed at the user's confirmation**, not when the flow starts:
+
+- `/commit` records a *pending flow* and injects its agent turn. Nothing is exempted yet.
+- When the confirmation questionnaire is answered **positively** (✅ Commit, or a custom message), the extension arms a scoped *commit authorization*. Choosing ❌ Cancel clears the flow and arms nothing.
+- The authorization exempts **only `git commit`** — `git add` and `git push` stay blocked — and is valid until the run settles (`agent_settled`), additionally bounded by a 10-minute TTL and a 10-commit cap. It is also dropped on `session_shutdown` and on rewind (`session_tree`).
+
+The confirmation step is required: with no positive answer no authorization exists and the policy keeps blocking. `-a` staging happens extension-side before the flow, outside the tool gate.
+
 ```text
 /commit-policy                # status: mode, which scope supplied it, both settings paths
 /commit-policy never          # set globally (~/.pi/agent/settings.json)

package/commit-policy.ts

@@ -321,6 +321,176 @@ export function stepCommitDecision(
   };
 }
 
+// ── /commit authorization (scoped exemption from the gate) ───────────
+//
+// The /commit flow is multi-turn (read diff → confirm via questionnaire →
+// commit), so a single-turn exemption is always disarmed before the commit
+// runs. Instead the flow starts a PendingCommitFlow and the authorization is
+// armed only when the user CONFIRMS in the extension-owned questionnaire
+// tool. The authorization is valid until the run settles, bounded by a TTL and
+// a commit cap, and exempts ONLY `git commit` (never `add`/`push`).
+
+/** How long a /commit flow may sit awaiting the user's decision. */
+export const COMMIT_FLOW_TTL_MS = 30 * 60 * 1000;
+
+/** How long an armed authorization stays valid (run-settle is the primary bound). */
+export const COMMIT_AUTH_TTL_MS = 10 * 60 * 1000;
+
+/** Defense-in-depth cap on commits made under one /commit authorization. */
+export const COMMIT_AUTH_MAX_COMMITS = 10;
+
+let commitFlowCounter = 0;
+
+/** A /commit flow awaiting the user's confirmation. */
+export interface PendingCommitFlow {
+  id: string;
+  startedAt: number;
+  expiresAt: number;
+}
+
+/** An armed exemption from the commit gate, created at the user's confirmation. */
+export interface CommitAuthorizationState {
+  flowId: string;
+  armedAt: number;
+  expiresAt: number;
+  commits: number;
+  maxCommits: number;
+}
+
+/** Start a new /commit flow (id is unique within the process). */
+export function startCommitFlow(
+  now: number,
+  ttlMs: number = COMMIT_FLOW_TTL_MS,
+): PendingCommitFlow {
+  commitFlowCounter += 1;
+  return {
+    id: `commit-${now}-${commitFlowCounter}`,
+    startedAt: now,
+    expiresAt: now + ttlMs,
+  };
+}
+
+/** Arm the exemption for one flow. Never throws. */
+export function armCommitAuthorization(input: {
+  flowId: string;
+  now: number;
+  ttlMs?: number;
+  maxCommits?: number;
+}): CommitAuthorizationState {
+  const ttlMs = input.ttlMs ?? COMMIT_AUTH_TTL_MS;
+  return {
+    flowId: input.flowId,
+    armedAt: input.now,
+    expiresAt: input.now + ttlMs,
+    commits: 0,
+    maxCommits: input.maxCommits ?? COMMIT_AUTH_MAX_COMMITS,
+  };
+}
+
+/** True only while an authorization is present, unexpired and under its cap. */
+export function isAuthorizationActive(
+  auth: CommitAuthorizationState | null | undefined,
+  now: number,
+): boolean {
+  if (!auth) return false;
+  if (!(now < auth.expiresAt)) return false;
+  return auth.commits < auth.maxCommits;
+}
+
+/** A normalized questionnaire question (only the fields the detector needs). */
+export interface CommitConfirmationQuestion {
+  question?: string;
+  header?: string;
+  options?: { label?: string; description?: string }[];
+}
+
+/**
+ * Is this questionnaire the /commit confirmation? Signals, in order: the
+ * "Commit" header, the canonical question text, or the "✅ Commit" option
+ * label. Deliberately tolerant — a missed match leaves the policy blocking
+ * (fail safe), so false negatives are a UX regression, false positives a risk.
+ */
+export function isCommitConfirmation(
+  questions: readonly CommitConfirmationQuestion[] | undefined,
+): boolean {
+  if (!Array.isArray(questions)) return false;
+  return questions.some((q) => {
+    if (!q || typeof q !== "object") return false;
+    if (typeof q.header === "string" && /^commit$/i.test(q.header.trim())) {
+      return true;
+    }
+    if (
+      typeof q.question === "string" &&
+      /commit these staged changes/i.test(q.question)
+    ) {
+      return true;
+    }
+    return (q.options ?? []).some(
+      (o: { label?: string; description?: string }) =>
+        typeof o?.label === "string" && /✅\s*commit/i.test(o.label),
+    );
+  });
+}
+
+/** One questionnaire answer, as far as the decision needs to know. */
+export interface CommitConfirmationAnswer {
+  answer?: string;
+  wasCustom?: boolean;
+}
+
+/**
+ * Did the user authorize the commit? Cancel (`cancelled` or a ❌/cancel-only
+ * label) never arms. Freeform text always arms (it is the user's own commit
+ * message) unless it is exactly a cancel token. A canned label arms unless it
+ * reads as cancel without commit.
+ */
+export function isPositiveCommitDecision(input: {
+  cancelled?: boolean;
+  answer?: CommitConfirmationAnswer;
+}): boolean {
+  if (input?.cancelled) return false;
+  const answer = input?.answer;
+  if (!answer) return false;
+  const label = String(answer.answer ?? "").trim();
+  if (!label) return false;
+  const isBareCancel = /^(❌\s*)?cancel[.!]?$/i.test(label);
+  if (isBareCancel) return false;
+  if (answer.wasCustom) return true;
+  if (/\bcancel\b/i.test(label) && !/\bcommit\b/i.test(label)) return false;
+  return true;
+}
+
+/** The commit-policy gate outcome for one tool call. */
+export type CommitGateDecision = "allow" | "block" | "ask";
+
+/** Git subcommands the commit policy gates (mirrors permissions.ts CommitPolicyHit). */
+export type CommitGateHit = "add" | "commit" | "push";
+
+export interface CommitGateInput {
+  policy: CommitPolicyMode;
+  hit: CommitGateHit;
+  hasTodos: boolean;
+  auth?: CommitAuthorizationState | null;
+  now: number;
+}
+
+/**
+ * The pure commit-policy decision. Ordering mirrors the original inline gate:
+ * an `allow` policy with no active plan owns nothing → allow; `ask` keeps
+ * fresh staging free; an armed authorization exempts ONLY `git commit`; then
+ * never/allow block and anything left (`ask`) prompts. Never throws.
+ */
+export function decideCommitGate(input: CommitGateInput): CommitGateDecision {
+  const { policy, hit, hasTodos } = input;
+  if (policy === "allow" && !hasTodos) return "allow";
+  if (policy === "ask" && hit === "add") return "allow";
+  if (hit === "commit" && isAuthorizationActive(input.auth, input.now)) {
+    return "allow";
+  }
+  if (policy === "never" || policy === "allow") return "block";
+  return "ask";
+}
+
 /**
  * Read-modify-write `workflow.commitPolicy` into a settings file, preserving
  * every other key in that file (Pi owns settings.json — we must not clobber it).

package/index.ts

@@ -89,12 +89,24 @@ import {
   type WorkflowRole,
 } from "./permissions.ts";
 import {
+  COMMIT_AUTH_MAX_COMMITS,
+  COMMIT_AUTH_TTL_MS,
+  COMMIT_FLOW_TTL_MS,
+  armCommitAuthorization,
   commitConfigPaths,
+  decideCommitGate,
   describeCommitPolicyMode,
+  isAuthorizationActive,
+  isCommitConfirmation,
+  isPositiveCommitDecision,
   readCommitPolicyConfig,
+  startCommitFlow,
   stepCommitDecision,
   writeCommitPolicyConfig,
+  type CommitAuthorizationState,
+  type CommitGateHit,
   type CommitPolicyMode,
+  type PendingCommitFlow,
   type StepCommitCandidate,
 } from "./commit-policy.ts";
 import {
@@ -400,11 +412,19 @@ export default function workflowExtension(pi: ExtensionAPI) {
   let todoItems: TodoItem[] = [];
   // Plan file the current todo list was derived from (drives merge vs replace).
   let todoPlanPath: string | undefined;
-  // Armed while the user-invoked /commit flow's agent turn is running: its
-  // `git commit` bypasses the commit-policy gate (staging already happened
-  // extension-side via piExecGit, outside the tool gate). Cleared on
-  // turn_end/agent_settled so the window stays one turn wide.
-  let commitBypassActive = false;
+  // ── /commit flow authorization ──
+  // The /commit flow is multi-turn (read diff → confirm → commit), so a
+  // single-turn exemption is always disarmed before the commit runs. Instead:
+  //   pendingCommitFlow  — set when /commit injects its agent turn, cleared on
+  //                        the user's confirmation (or a negative/cancel answer),
+  //                        so only THIS flow's questionnaire can arm.
+  //   commitAuthorization — armed only when the user confirms in that
+  //                        questionnaire; exempts ONLY `git commit` (never
+  //                        add/push) until the run settles, bounded by a TTL
+  //                        and a commit cap.
+  // Both are cleared on agent_settled, session_shutdown and session_tree.
+  let pendingCommitFlow: PendingCommitFlow | null = null;
+  let commitAuthorization: CommitAuthorizationState | null = null;
   // ── Deterministic per-step commits (allow mode) ──
   // In 'allow' mode the EXTENSION — not the model — owns commit timing:
   // exactly one commit per batch of newly completed plan steps, made at the
@@ -2532,16 +2552,28 @@ export default function workflowExtension(pi: ExtensionAPI) {
 
     // Inject a user message → triggers an agent turn that proposes + confirms + commits
     const message = buildCommitPrompt(statSummary, stageAll);
-    // Arm the commit-policy bypass for exactly this agent turn: its `git
-    // commit` must run even under policy 'never'. Disarmed on turn_end /
-    // agent_settled, so the window is one turn wide.
-    commitBypassActive = true;
-    if ((pi as any).sendUserMessage) {
-      (pi as any).sendUserMessage(message);
-    } else {
-      (pi as any).sendMessage?.(
-        { customType: "workflow-commit", content: message, display: true },
-        { triggerTurn: true, deliverAs: "followUp" },
+    // Start a commit flow. The exemption is NOT armed here: it is armed only
+    // when the user confirms in THIS flow's questionnaire (see the
+    // questionnaire tool), so an unconfirmed commit stays blocked under any
+    // policy. A flow TTL bounds an abandoned confirmation.
+    pendingCommitFlow = startCommitFlow(Date.now(), COMMIT_FLOW_TTL_MS);
+    commitAuthorization = null;
+    try {
+      if ((pi as any).sendUserMessage) {
+        await (pi as any).sendUserMessage(message);
+      } else {
+        await (pi as any).sendMessage?.(
+          { customType: "workflow-commit", content: message, display: true },
+          { triggerTurn: true, deliverAs: "followUp" },
+        );
+      }
+    } catch (e: any) {
+      // The turn never started → no questionnaire can arm; do not leave a
+      // stale flow behind.
+      pendingCommitFlow = null;
+      ctx.ui.notify(
+        `Failed to start the commit flow: ${String(e?.message ?? e ?? e)}`,
+        "error",
       );
     }
   }
@@ -5801,6 +5833,34 @@ export default function workflowExtension(pi: ExtensionAPI) {
         overlayActive = false;
       }
 
+      // /commit authorization: arm the commit-policy exemption ONLY when the
+      // user confirms THIS flow's commit questionnaire. A cancel (or any
+      // non-confirmation questionnaire) clears the pending flow and arms
+      // nothing, so the policy keeps blocking. Headless never reaches here
+      // (early return above), which is the intended fail-closed behaviour.
+      if (pendingCommitFlow && isCommitConfirmation(questions)) {
+        const cancelled = !result || result.cancelled === true;
+        const answer =
+          !result || result.cancelled ? undefined : result.answers?.[0];
+        if (isPositiveCommitDecision({ cancelled, answer })) {
+          commitAuthorization = armCommitAuthorization({
+            flowId: pendingCommitFlow.id,
+            now: Date.now(),
+            ttlMs: COMMIT_AUTH_TTL_MS,
+            maxCommits: COMMIT_AUTH_MAX_COMMITS,
+          });
+          try {
+            ctx.ui.notify?.(
+              "Commit authorized — this run may commit the staged changes.",
+              "info",
+            );
+          } catch (_e) {
+            void _e;
+          }
+        }
+        pendingCommitFlow = null;
+      }
+
       if (!result || result.cancelled) {
         return {
           content: [{ type: "text", text: "User cancelled questionnaire" }],
@@ -6421,6 +6481,10 @@ export default function workflowExtension(pi: ExtensionAPI) {
     }
     ctx.ui.setStatus("workflow", undefined);
     ctx.ui.setWidget("workflow-todos", undefined);
+    // Drop any /commit authorization or flow: a reload/quit must never leave
+    // an exemption armed for whatever runs next.
+    commitAuthorization = null;
+    pendingCommitFlow = null;
     // Release the reviewer session (and its custom tools) on shutdown so a
     // reload or quit never leaves an orphaned in-process session behind.
     await teardownReview();
@@ -6432,6 +6496,9 @@ export default function workflowExtension(pi: ExtensionAPI) {
     todoItems = [];
     todoPlanPath = undefined;
     btwNotes = [];
+    // A rewind must not preserve a /commit exemption across branches.
+    commitAuthorization = null;
+    pendingCommitFlow = null;
     try {
       const branch = ctx.sessionManager.getBranch();
       for (const e of branch as any[]) {
@@ -6468,32 +6535,52 @@ export default function workflowExtension(pi: ExtensionAPI) {
    *   allow → automatic per-step commits while a plan todo list is active
    * (the extension owns commit timing — model-initiated git add/commit/push
    * are blocked); outside a plan the model may commit as before. The
-   * user-invoked /commit flow arms `commitBypassActive` so its own `git
-   * commit` runs (staging is extension-side; `push` and `add` are never
-   * bypassed).
+   * user-invoked /commit flow arms `commitAuthorization` ONLY when the user
+   * confirms its questionnaire; that exemption covers just `git commit` for
+   * the rest of the run (staging is extension-side; `push` and `add` are
+   * never exempted).
+   *
+   * The decision itself is the pure `decideCommitGate`; this wrapper supplies
+   * the runtime inputs and renders the block reasons / ask overlay.
    */
   async function commitPolicyGate(
     event: any,
     ctx: any,
     cwd: string,
   ): Promise<{ block: true; reason: string } | undefined> {
-    const policy = readCommitPolicyConfig(cwd, getAgentDir()).config.mode;
-    // allow outside a plan: no per-step automation to own commit timing, so
-    // the model keeps its previous freedom.
-    if (policy === "allow" && todoItems.length === 0) return undefined;
     const cmd = String(event?.input?.command ?? "");
     const hit = gitCommitPolicyHit(cmd);
     if (!hit) return undefined;
-    // `add` is only gated in `never` mode; `ask` prompts on commit/push only
-    // (staging alone pollutes nothing).
-    if (policy === "ask" && hit === "add") return undefined;
-    // /commit bypass: only the flow's own `git commit` is exempt — `add` and
-    // `push` are not.
-    if (commitBypassActive && hit === "commit") {
+    const policy = readCommitPolicyConfig(cwd, getAgentDir()).config.mode;
+    const now = Date.now();
+    const decision = decideCommitGate({
+      policy,
+      hit: hit as CommitGateHit,
+      hasTodos: todoItems.length > 0,
+      auth: commitAuthorization,
+      now,
+    });
+    if (decision === "allow") {
+      // Count a granted `git commit` against the authorization, but only when
+      // the authorization was actually the deciding factor (never/ask, or
+      // allow-with-an-active-plan). `allow` outside a plan is free regardless.
+      const authWasDecisive =
+        hit === "commit" &&
+        commitAuthorization !== null &&
+        !(policy === "allow" && todoItems.length === 0);
+      if (authWasDecisive && commitAuthorization) {
+        const auth = commitAuthorization;
+        if (!isAuthorizationActive(auth, now)) {
+          commitAuthorization = null;
+        } else {
+          const next = { ...auth, commits: auth.commits + 1 };
+          commitAuthorization = next.commits >= next.maxCommits ? null : next;
+        }
+      }
       return undefined;
     }
 
-    if (policy === "never" || policy === "allow") {
+    if (decision === "block") {
       return {
         block: true,
         reason:
@@ -6507,7 +6594,7 @@ export default function workflowExtension(pi: ExtensionAPI) {
               cmd,
       };
     }
-    // policy === "ask" → confirmation overlay. Headless has no one to ask →
+    // decision === "ask" → confirmation overlay. Headless has no one to ask →
     // fail closed rather than commit unbidden.
     const ui = ctx?.ui;
     if (!ui || !ctx.hasUI) {
@@ -6886,9 +6973,11 @@ export default function workflowExtension(pi: ExtensionAPI) {
   });
 
   pi.on("agent_settled", async () => {
-    // Belt-and-braces: the run is over (completed, aborted or errored) — the
-    // /commit bypass must not leak into whatever runs next.
-    commitBypassActive = false;
+    // The run is over (completed, aborted or errored). The /commit flow lives
+    // within one run, so both the armed exemption and any unconfirmed flow are
+    // dropped here — nothing that runs next inherits them.
+    commitAuthorization = null;
+    pendingCommitFlow = null;
     // keep persisted CustomEntry for reload, clear in-memory tombstone only on explicit prune; for now no clear to survive fork
   });
 
@@ -7067,10 +7156,10 @@ export default function workflowExtension(pi: ExtensionAPI) {
 
   // Track progress (all modes, whenever todos exist)
   pi.on("turn_end", async (event, ctx) => {
-    // Disarm the /commit bypass as soon as any turn ends: the /commit flow's
-    // `git commit` runs as a tool call WITHIN its turn, so this never disarms
-    // too early — and nothing after the turn inherits the exemption.
-    commitBypassActive = false;
+    // NOTE: do NOT disarm the /commit authorization here. `turn_end` fires
+    // after EVERY assistant response, but /commit is multi-turn (read diff →
+    // confirm → commit), so disarming per turn kills the exemption before the
+    // commit turn. Lifetime is the run: `agent_settled` clears it.
     if (todoItems.length === 0) return;
     if (!isAssistantMessage(event.message as AgentMessage)) return;
     const text = getTextContent(event.message as AssistantMessage);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dieulc/workflow",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "type": "module",
   "private": false,
   "keywords": ["pi-package", "workflow", "plan-mode", "review-mode", "questionnaire", "rewind"],