jackherd 1.16.0 → 1.18.0

package/dist/plan-format.js

@@ -8,6 +8,7 @@ import {
   PLAN_LANGUAGE,
   PLAN_STATUS,
   PLAN_VOCABULARY,
+  RECOMMENDED_MARK,
   RESPONSE_ADDRESS,
   SELF_MERGE_LABEL,
   STANDING_APPROVAL_TEXTS,
@@ -17,7 +18,7 @@ import {
   phaseHeading,
   sectionHeading,
   terminalSafe
-} from "./chunk-4LUFR7RC.js";
+} from "./chunk-N5FAOQZL.js";
 
 // src/plan-format/lanes.ts
 import { posix } from "path";
@@ -830,6 +831,10 @@ var mergedPhasesWithOpenBoxes = (markdown, base, language) => {
   };
   return phaseSections(markdown, language).filter(({ id, openLines }) => openLines.length > 0 && isMerged(id)).map(({ line, id, title, openLines }) => ({ line, id, title, openLines }));
 };
+var openBoxesOfPhase = (markdown, language, id) => {
+  const section = phaseSections(markdown, language).find((candidate) => candidate.id === id);
+  return section && section.openLines.length > 0 ? { line: section.line, id: section.id, title: section.title, openLines: section.openLines } : null;
+};
 var boardRowsWithoutPhase = (markdown, language, previousLines) => changedOpenLaneRows(markdown, language, previousLines).filter(
   ({ phases }) => phaseIdsOfCell(phases, language).length === 0
 );
@@ -920,6 +925,7 @@ export {
   PLAN_STATUS,
   PLAN_VOCABULARY,
   PROSE_REASON,
+  RECOMMENDED_MARK,
   RESPONSE_ADDRESS,
   SELF_MERGE_LABEL,
   SHORT_NAME_LIMIT,
@@ -955,6 +961,7 @@ export {
   misplacedDeferrals,
   newPhasesWithoutReviewGate,
   onlyDocumentationOpen,
+  openBoxesOfPhase,
   parallelGroups,
   parallelGroupsOfPlan,
   parseDependencyTable,

package/docs/plan-contract.md

@@ -82,3 +82,4 @@ dependencies: missing no dependency table: phases run one after another
 | 0 | the contract is met (a missing dependency table is a note, not a gap) |
 | 1 | at least one part is missing or malformed |
 | 2 | wrong command line: no subcommand, unknown subcommand, no file, unreadable file, unreadable config |
+| 3 | the contract is met, but the plan or a board that links it is not on the base branch (a `base:` line names each path); the coordinator commits it first (`/orchestrate` § 2 step 0), after which the check counts as done |

package/herdr-plugin/herdr-plugin.toml

@@ -1,6 +1,6 @@
 id = "crossdelta.jackherd"
 name = "jackherd"
-version = "1.16.0"
+version = "1.18.0"
 min_herdr_version = "0.8.2"
 description = "Show the herd, the state of a board's lanes, in a herdr pane"
 platforms = ["linux", "macos"]
@@ -20,3 +20,6 @@ command = ["bun", "open-plans.ts"]
 
 [[startup]]
 command = ["bun", "restore-plans.ts"]
+
+[[startup]]
+command = ["bun", "resume.ts"]

package/herdr-plugin/restore-plans.ts

@@ -1,8 +1,13 @@
 import { spawnSync } from 'node:child_process'
 import { dirname, join } from 'node:path'
+import { ENSURE_EXIT } from '../src/plans/plan-panes'
 
 type Limits = { attempts: number; intervalMs: number }
 
+/** What one `herd --ensure` left to do: nothing, wait for the coordinator's session, or try again. */
+export const ENSURE_OUTCOME = { done: 'done', awaitsCoordinator: 'awaits-coordinator', failed: 'failed' } as const
+type EnsureOutcome = (typeof ENSURE_OUTCOME)[keyof typeof ENSURE_OUTCOME]
+
 /**
  * Measured on herdr 0.9.0: the hook starts ~85 ms after the server, `pane process-info` answers
  * `pane_not_found` until the terminals spawn at ~0.9 s, and the agents are back at ~3 s. The panes get 10 s, ten
@@ -16,32 +21,41 @@ export const RESTORE_LIMITS = {
   coordinator: { attempts: 30, intervalMs: 2_000 },
 } as const satisfies Record<string, Limits>
 
-/** Runs `attempt` until it works or the attempts are used up, waiting the interval between two of them. */
-export const retried = (attempt: () => boolean, limits: Limits, sleep: (ms: number) => void): boolean => {
+/**
+ * Runs `attempt` until `isDone` accepts its value or the attempts are used up, waiting the interval between two of
+ * them; the value of the last attempt.
+ */
+export const retriedUntil = <T>(
+  attempt: () => T,
+  isDone: (value: T) => boolean,
+  limits: Limits,
+  sleep: (ms: number) => void,
+): T => {
   for (let tried = 1; ; tried++) {
-    if (attempt()) return true
-    if (tried >= limits.attempts) return false
+    const value = attempt()
+    if (isDone(value) || tried >= limits.attempts) return value
     sleep(limits.intervalMs)
   }
 }
 
+/** Runs `attempt` until it works or the attempts are used up, waiting the interval between two of them. */
+export const retried = (attempt: () => boolean, limits: Limits, sleep: (ms: number) => void): boolean =>
+  retriedUntil(attempt, (worked) => worked, limits, sleep)
+
 /**
- * Waits for every item in one shared window of `limits`, calls `onReady` for each as soon as `isReady` holds, and
- * returns the items that never got ready.
+ * Runs `attempt` for every pending item in one shared window of `limits` until it gives true for that item, and
+ * returns the items it never did.
  */
 export const awaitEach = <T>(
   items: readonly T[],
-  isReady: (item: T) => boolean,
-  onReady: (item: T) => void,
+  attempt: (item: T) => boolean,
   limits: Limits,
   sleep: (ms: number) => void,
 ): T[] => {
   let pending = [...items]
   retried(
     () => {
-      const ready = pending.filter(isReady)
-      for (const item of ready) onReady(item)
-      pending = pending.filter((item) => !ready.includes(item))
+      pending = pending.filter((item) => !attempt(item))
       return pending.length === 0
     },
     limits,
@@ -74,6 +88,16 @@ export const agentDirectoriesOf = (json: string, agentPanes: readonly string[]):
 export const hasAgentIn = (root: string, paneList: string, agentPanes: readonly string[]): boolean =>
   agentDirectoriesOf(paneList, agentPanes).includes(root)
 
+/** The outcome of one `herd --ensure` from its exit status; null when it did not start. */
+export const ensureOutcomeOf = (status: number | null): EnsureOutcome => {
+  if (status === ENSURE_EXIT.done) return ENSURE_OUTCOME.done
+  return status === ENSURE_EXIT.noCoordinator ? ENSURE_OUTCOME.awaitsCoordinator : ENSURE_OUTCOME.failed
+}
+
+/** The repositories whose first `herd --ensure` did not find the coordinator: the hook keeps waiting for these. */
+export const rootsAwaitingCoordinator = (outcomes: readonly { root: string; outcome: EnsureOutcome }[]): string[] =>
+  outcomes.filter((each) => each.outcome === ENSURE_OUTCOME.awaitsCoordinator).map((each) => each.root)
+
 /** The arguments for `bun` that run `herd --ensure` with the CLI of the package this plugin ships in. */
 export const ensureArguments = (pluginRoot: string): string[] => [
   join(dirname(pluginRoot), 'src', 'cli.ts'),
@@ -108,25 +132,34 @@ const herdrRun = (args: string[]) =>
 const panesAnswer = (panes: readonly string[]): boolean =>
   panes.every((pane) => herdrRun(['pane', 'process-info', '--pane', pane]).status === 0)
 
-const ensureIn = (root: string, pluginRoot: string): boolean =>
-  spawnSync('bun', ensureArguments(pluginRoot), { cwd: root, stdio: 'inherit' }).status === 0
+const ensureIn = (root: string, pluginRoot: string): EnsureOutcome =>
+  ensureOutcomeOf(spawnSync('bun', ensureArguments(pluginRoot), { cwd: root, stdio: 'inherit' }).status)
 
 const coordinatorBackIn = (root: string): boolean =>
   hasAgentIn(root, herdrRun(['pane', 'list']).stdout ?? '', idsOf(herdrRun(['agent', 'list']).stdout ?? '', 'agents'))
 
-const ensureWithRetries = (root: string, sleep: (ms: number) => void) => {
-  if (!retried(() => ensureIn(root, import.meta.dir), RESTORE_LIMITS.ensure, sleep))
-    console.error(`restore-plans: herd --ensure failed in ${root}`)
+/** Retries `herd --ensure` while it fails; a run that only misses the coordinator is not retried here. */
+const ensureWithRetries = (root: string, sleep: (ms: number) => void): EnsureOutcome => {
+  const outcome = retriedUntil(
+    () => ensureIn(root, import.meta.dir),
+    (each) => each !== ENSURE_OUTCOME.failed,
+    RESTORE_LIMITS.ensure,
+    sleep,
+  )
+  if (outcome === ENSURE_OUTCOME.failed) console.error(`restore-plans: herd --ensure failed in ${root}`)
+  return outcome
 }
 
+/** Runs `herd --ensure` once the coordinator of `root` is back; whether it found the coordinator's pane. */
+const ensureCoordinatorHerd = (root: string): boolean =>
+  coordinatorBackIn(root) && ensureIn(root, import.meta.dir) === ENSURE_OUTCOME.done
+
 /**
- * The herd beside each coordinator once its session is back, which can take longer than the lanes'. A coordinator
- * already back had its herd from the first `--ensure`; the others share one waiting window.
+ * The herd beside each coordinator whose pane the first `--ensure` did not find, once its session is back, which
+ * can take longer than the lanes'; they share one waiting window.
  */
-const ensureCoordinators = (roots: readonly string[], sleep: (ms: number) => void) => {
-  const missing = roots.filter((root) => !coordinatorBackIn(root))
-  const ensure = (root: string) => ensureWithRetries(root, sleep)
-  for (const root of awaitEach(missing, coordinatorBackIn, ensure, RESTORE_LIMITS.coordinator, sleep))
+const ensureCoordinators = (missing: readonly string[], sleep: (ms: number) => void) => {
+  for (const root of awaitEach(missing, ensureCoordinatorHerd, RESTORE_LIMITS.coordinator, sleep))
     console.error(`restore-plans: no coordinator came back in ${root}`)
 }
 
@@ -135,8 +168,9 @@ const ensureCoordinators = (roots: readonly string[], sleep: (ms: number) => voi
  * repository an agent runs in. It parses herdr's answers itself and never throws, unlike the strict parsers of
  * `src/plans/plan-panes.ts`: a hook that fails leaves nothing behind but a log line, and `herd --ensure`, which it
  * calls, reads the panes again strictly. It reads the panes at once, while herdr still names their agents, then waits until
- * herdr answers for every pane and retries `herd --ensure` within `RESTORE_LIMITS`. A repository whose coordinator
- * is not back yet gets one more `herd --ensure` once an agent runs in its main checkout. A repository without a
+ * herdr answers for every pane and retries `herd --ensure` within `RESTORE_LIMITS`. A repository where `herd --ensure`
+ * did not find the coordinator (`ENSURE_EXIT.noCoordinator`) gets it again, once an agent runs in its main
+ * checkout, until it finds the coordinator or `RESTORE_LIMITS.coordinator` runs out. A repository without a
  * board or config only prints why and is skipped.
  */
 const main = (): number => {
@@ -149,8 +183,8 @@ const main = (): number => {
   const sleep = (ms: number) => Bun.sleepSync(ms)
   if (!retried(() => panesAnswer(idsOf(listing, 'panes')), RESTORE_LIMITS.panes, sleep))
     console.error('restore-plans: herdr did not answer for every pane in time, trying anyway')
-  for (const root of roots) ensureWithRetries(root, sleep)
-  ensureCoordinators([...roots], sleep)
+  const outcomes = [...roots].map((root) => ({ root, outcome: ensureWithRetries(root, sleep) }))
+  ensureCoordinators(rootsAwaitingCoordinator(outcomes), sleep)
   return 0
 }
 

package/herdr-plugin/resume.ts

@@ -0,0 +1,18 @@
+import { spawnSync } from 'node:child_process'
+import { dirname, join } from 'node:path'
+
+/** The arguments for `bun` that run `jh resume` with the CLI of the package this plugin ships in. */
+export const resumeArguments = (pluginRoot: string): string[] => [join(dirname(pluginRoot), 'src', 'cli.ts'), 'resume']
+
+/**
+ * herdr's second `[[startup]]` hook, beside `restore-plans.ts`: runs `jh resume`, which decides from the watcher's
+ * record whether herdr starts after a crash and wakes the coordinator and the interrupted lanes. All logic lives in
+ * `src/resume/`; this stays thin and exits 0, a hook leaves nothing behind but the log of `jh resume`.
+ */
+const main = (): number => {
+  const result = spawnSync('bun', resumeArguments(import.meta.dir), { stdio: 'inherit' })
+  if (result.status !== 0) console.error(`resume: jh resume ended with ${result.status ?? result.signal}`)
+  return 0
+}
+
+if (import.meta.main) process.exitCode = main()

package/install.sh

@@ -9,7 +9,7 @@ set -eu
 
 # The default is the version this file ships with. The release bump changes it together with
 # package.json; install.test.ts fails while the two differ. Overridable, but only by a plain release.
-JACKHERD_VERSION="${JACKHERD_VERSION:-1.16.0}"
+JACKHERD_VERSION="${JACKHERD_VERSION:-1.18.0}"
 
 JACKHERD_PACKAGE='jackherd'
 # Test seam: the terminal the wizard asks its questions on.

package/kit/hooks/ask-rules.json

@@ -6,6 +6,17 @@
   "Bash(gh api *dispatches*)",
   "Bash(gh api *rerun*)",
   "Bash(gh api *git/refs*)",
+  "Bash(gh api *mergePullRequest*)",
+  "Bash(gh api *mergeBranch*)",
+  "Bash(gh api *enablePullRequestAutoMerge*)",
+  "Bash(gh api *enqueuePullRequest*)",
+  "Bash(gh api *createCommitOnBranch*)",
+  "Bash(gh api *createRef*)",
+  "Bash(gh api *updateRef*)",
+  "Bash(gh api *deleteRef*)",
+  "Bash(gh api *rerequestCheckSuite*)",
+  "Bash(gh api *graphql*query=@*)",
+  "Bash(gh api *graphql*--input*)",
   "Bash(jh lane close*)",
   "Bash(jackherd lane close*)",
   "Bash(bunx jackherd* lane close*)",

package/kit/hooks/hooks/approval-gate/checked-marks.ts

@@ -0,0 +1,59 @@
+/**
+ * The coordinator's marks that it checked a held call: a `jh approval checked <id> <hash>` it ran as a Bash call and
+ * that ended with exit 0, read from its transcript like the dialog answers. The transcript is written by the client,
+ * not by the agent; a file a lane could write is never a mark.
+ */
+import { contentOf } from '../shared/dialog-answers'
+import { isRecord, type JsonObject } from '../shared/json'
+import { CONTENT_BLOCK_TYPE } from '../shared/log-vocabulary'
+
+/** A call the coordinator marked checked: the request's id and the hash it showed, and when the command returned. */
+export type CheckedMark = { id: string; hash: string; checkedAt: number }
+
+type CheckCall = Pick<CheckedMark, 'id' | 'hash'>
+
+type BashUse = JsonObject & { id: string }
+
+const BASH_TOOL = 'Bash'
+const CHECKED_COMMAND = /^jh approval checked ([0-9a-f]{12}) ([0-9a-f]{16})$/
+
+const isMainThread = (entry: JsonObject): boolean => entry.isSidechain !== true
+
+const isBashUse = (block: JsonObject): block is BashUse =>
+  block.type === CONTENT_BLOCK_TYPE.toolUse && block.name === BASH_TOOL && typeof block.id === 'string'
+
+/** The command of a call that ran in the foreground; a background call returns before its exit code is known. */
+const commandOf = (block: JsonObject): string | undefined =>
+  isRecord(block.input) && typeof block.input.command === 'string' && block.input.run_in_background !== true
+    ? block.input.command.trim()
+    : undefined
+
+/** The id and hash of each `jh approval checked` Bash call of the main thread, by tool use id. */
+const checkCalls = (entries: readonly JsonObject[]): Map<string, CheckCall> =>
+  new Map(
+    entries
+      .flatMap(contentOf)
+      .filter(isBashUse)
+      .flatMap((block): [string, CheckCall][] => {
+        const match = CHECKED_COMMAND.exec(commandOf(block) ?? '')
+        return match ? [[block.id, { id: match[1], hash: match[2] }]] : []
+      }),
+  )
+
+const marksIn = (entry: JsonObject, calls: Map<string, CheckCall>): CheckedMark[] => {
+  const checkedAt = typeof entry.timestamp === 'string' ? Date.parse(entry.timestamp) : Number.NaN
+  if (Number.isNaN(checkedAt)) return []
+  return contentOf(entry)
+    .filter((block) => block.type === CONTENT_BLOCK_TYPE.toolResult && block.is_error === false)
+    .flatMap((block) => {
+      const call = calls.get(String(block.tool_use_id))
+      return call ? [{ ...call, checkedAt }] : []
+    })
+}
+
+/** Every call of the main thread the coordinator marked checked with exit 0, in transcript order. */
+export const checkedMarks = (entries: readonly unknown[]): CheckedMark[] => {
+  const main = entries.filter(isRecord).filter(isMainThread)
+  const calls = checkCalls(main)
+  return main.flatMap((entry) => marksIn(entry, calls))
+}

package/kit/hooks/hooks/approval-gate/index.ts

@@ -2,20 +2,24 @@
 // by the herdr agent of the pane and not by the directory of the call, it holds a call that would open a permission
 // dialog, records it for the coordinator and answers with the user's decision from the coordinator's dialog; the same for
 // a subagent of the coordinator, under its own name; elsewhere, and on any failure, it answers nothing and the dialog stays. argv[2..5]: the allow label, the deny label, the text for
-// a call still pending after the wait, the text for a denied call, rendered into the hook entry by `sync`.
-import { existsSync } from 'node:fs'
+// a call still pending after the wait, the text for a denied call; argv[6..7]: the label and the word before the end
+// of a standing approval, which lets a stage call the coordinator marked checked pass; all rendered by `sync`.
+import { existsSync, writeFileSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { join } from 'node:path'
+import { boardLocationOf, boardsIn } from '../shared/boards'
 import { mainCheckoutOf } from '../shared/checkout'
 import { commandOutput } from '../shared/command'
 import { readConfig } from '../shared/config'
+import { readTextOrNull } from '../shared/files'
 import { isRecord } from '../shared/json'
 import { ownPaneAgent } from '../shared/own-pane'
 import { gateSettingsOf } from './settings'
 import { coordinatorSessions } from './herdr-panes'
-import { type ClientCall, type GateDependencies, type GateOutcome, runGate } from './run'
+import { type ClientCall, type GateDependencies, type GateOutcome, type GateTexts, runGate } from './run'
+import { boardForLane, historyDate, type StandingHistoryEntry, standingHistoryLine, withHistoryRow } from './standing-history'
 import { approvalsDirectory, claimRequest, pruneRequests, readRequests, writeRequest } from './store'
-import { coordinatorAnswers } from './transcripts'
+import { coordinatorLog } from './transcripts'
 
 type ClaudeDecision = { behavior: 'allow' } | { behavior: 'deny'; message: string }
 
@@ -47,6 +51,27 @@ const clientCallOf = (text: string): ClientCall | null => {
   }
 }
 
+/**
+ * Writes the history row into the board that names the lane (the only board when none does), read again just before
+ * it is written; false when there is no such board, no history table, or the write fails.
+ */
+const writeHistory = (main: string, entry: StandingHistoryEntry): boolean => {
+  try {
+    const location = boardLocationOf(readConfig([main]))
+    if (location === null) return false
+    const board = boardForLane(boardsIn(main, location), entry.lane, location.planLanguage)
+    if (board === null) return false
+    const path = join(main, board.directory, location.board.file)
+    const text = readTextOrNull(path)
+    const next = text === null ? null : withHistoryRow(text, location.planLanguage, historyDate(entry.at), standingHistoryLine(entry))
+    if (next === null) return false
+    writeFileSync(path, next)
+    return true
+  } catch {
+    return false
+  }
+}
+
 const dependencies: GateDependencies = {
   paneAgent: () => ownPaneAgent(),
   mainCheckoutOf,
@@ -57,19 +82,23 @@ const dependencies: GateDependencies = {
   writeRequest: (main, request) => writeRequest(approvalsDirectory(main), request),
   claimRequest: (main, id, now) => claimRequest(approvalsDirectory(main), id, now),
   pruneRequests: (main, now, minutes) => pruneRequests(approvalsDirectory(main), now, minutes),
-  answers: (main) => coordinatorAnswers(coordinatorSessions(herdrPanes(), main)),
+  coordinatorLog: (main) => coordinatorLog(coordinatorSessions(herdrPanes(), main)),
+  writeHistory,
   now: () => Date.now(),
   sleep: (ms) => Bun.sleep(ms),
   randomBytes: () => crypto.getRandomValues(new Uint8Array(6)),
 }
 
-const [allow = '', deny = '', pending = '', denied = ''] = process.argv.slice(2)
+const [allow = '', deny = '', pending = '', denied = '', approve = '', until = ''] = process.argv.slice(2)
+
+/** The labels; the standing approval's only when the install passes both of its words. */
+const texts: GateTexts = { allow, deny, ...(approve && until ? { standing: { approve, until } } : {}) }
 
 const decide = async (): Promise<GateOutcome> => {
   if (!allow || !deny) return null
   try {
     const call = clientCallOf(await Bun.stdin.text())
-    return call ? await runGate(call, { allow, deny }, dependencies) : null
+    return call ? await runGate(call, texts, dependencies) : null
   } catch {
     return null
   }

package/kit/hooks/hooks/approval-gate/run.ts

@@ -1,16 +1,22 @@
-import type { DialogAnswer } from '../shared/dialog-answer'
 import { ASK_USER_QUESTION_TOOL } from '../shared/dialog-answers'
-import { isFresh } from '../shared/fresh'
+import { isFresh, MS_PER_MINUTE } from '../shared/fresh'
 import { isCoordinatorAgent, laneOfAgent } from '../shared/lane'
 import type { PaneAgent } from '../shared/pane-agent'
+import { type StandingLabels, standingGrants } from '../shared/standing-mark'
 import { gateDecision, type GateLabels } from './decision'
 import { type ApprovalRequest, callHash, type GateCall, isStorableInput, newRequest, requestId } from './request'
-import { gateSettingsOf } from './settings'
+import { type GateSettings, gateSettingsOf } from './settings'
+import { queryOf, type StandingHistoryEntry } from './standing-history'
+import { ENVIRONMENT_KIND, standingSqlDecision } from './standing-sql'
 import { type SubagentCall, subagentLabel } from './subagent'
+import type { CoordinatorLog } from './transcripts'
 
 /** A call as the client's hook hands it over, before it is known to be a lane's; `subagent` when a subagent makes it. */
 export type ClientCall = { cwd: string; session: string; tool: string; input: unknown; subagent?: SubagentCall }
 
+/** The two labels of the coordinator's question about a call, and those of a standing approval when the install passes them. */
+export type GateTexts = GateLabels & { standing?: StandingLabels }
+
 /** What the gate decided; null decides nothing, so the client's own dialog stays. */
 export type GateOutcome = { kind: 'allow' } | { kind: 'denied' } | { kind: 'pending' } | null
 
@@ -27,14 +33,16 @@ export type GateDependencies = {
   /** Creates the request's claim exclusively; true for the one caller that may act on its answer. */
   claimRequest: (main: string, id: string, now: number) => boolean
   pruneRequests: (main: string, now: number, minutes: number) => void
-  answers: (main: string) => DialogAnswer[]
+  /** The user's dialog answers and the coordinator's checked marks, from the coordinator's transcripts. */
+  coordinatorLog: (main: string) => CoordinatorLog
+  /** Writes the history row of a call passing under a standing approval into the board; false when it could not. */
+  writeHistory: (main: string, entry: StandingHistoryEntry) => boolean
   now: () => number
   sleep: (ms: number) => Promise<void>
   randomBytes: () => Uint8Array
 }
 
 const POLL_MS = 2000
-const MS_PER_MINUTE = 60_000
 /** An answer holds this long from the moment it was given (User decision, plan P18). */
 const VALID_MINUTES = 30
 /** A request is kept for its wait and the validity of an answer to it, then removed. */
@@ -54,22 +62,70 @@ const openRequest = (main: string, call: GateCall, dependencies: GateDependencie
   return request
 }
 
-/** Polls the coordinator's answers until the user decided, the answer was claimed elsewhere, or the wait is over. */
+/**
+ * The request this hook holds, as it opened it, with only its claim taken from disk: a file rewritten since (another
+ * call, another creation time) is no longer this request, and nothing passes by it.
+ */
+const heldRequest = (opened: ApprovalRequest, requests: readonly ApprovalRequest[]): ApprovalRequest | undefined => {
+  const current = requests.find(({ id }) => id === opened.id)
+  return current?.hash === opened.hash && current.createdAt === opened.createdAt
+    ? { ...opened, usedAt: current.usedAt }
+    : undefined
+}
+
+/** The request as it lies now, if a standing approval and the coordinator's mark let it pass; until when that holds. */
+const standingPass = (
+  request: ApprovalRequest | undefined,
+  log: CoordinatorLog,
+  texts: GateTexts,
+  settings: GateSettings,
+  now: number,
+): { request: ApprovalRequest; until: number } | null => {
+  if (request === undefined || texts.standing === undefined) return null
+  const grants = standingGrants(log.answers, ENVIRONMENT_KIND, texts.standing, now)
+  const pass = standingSqlDecision({ request, grants, checks: log.checks, standingTools: settings.standingTools, now })
+  return pass === null ? null : { request, until: pass.until }
+}
+
+/**
+ * Lets a call through under a standing approval: the request is claimed, so no dialog answer is spent on it as well,
+ * and its history row is written before the call passes. A row that cannot be written lets nothing through and leaves
+ * the request spent, so a later dialog answer cannot pass it either; the lane's retry opens a new request.
+ */
+const passStanding = (
+  main: string,
+  { request, until }: { request: ApprovalRequest; until: number },
+  now: number,
+  dependencies: GateDependencies,
+): GateOutcome => {
+  if (!dependencies.claimRequest(main, request.id, now)) return null
+  const entry = { id: request.id, lane: request.lane, hash: request.hash, query: queryOf(request.input), until, at: now }
+  return dependencies.writeHistory(main, entry) ? { kind: 'allow' } : { kind: 'pending' }
+}
+
+/**
+ * Polls the coordinator's transcripts until the user decided, a standing approval with the coordinator's mark lets the
+ * call pass, the answer was claimed elsewhere, or the wait is over.
+ */
 const awaitDecision = async (
   main: string,
-  hash: string,
-  labels: GateLabels,
-  waitMinutes: number,
+  opened: ApprovalRequest,
+  texts: GateTexts,
+  settings: GateSettings,
   dependencies: GateDependencies,
 ): Promise<GateOutcome> => {
-  const deadline = dependencies.now() + waitMinutes * MS_PER_MINUTE
+  const deadline = dependencies.now() + settings.waitMinutes * MS_PER_MINUTE
   for (;;) {
     const now = dependencies.now()
     const requests = dependencies.readRequests(main)
-    const answers = dependencies.answers(main)
-    const decision = gateDecision({ requests, hash, answers, labels, now, validMinutes: VALID_MINUTES })
+    const log = dependencies.coordinatorLog(main)
+    const { hash } = opened
+    const decision = gateDecision({ requests, hash, answers: log.answers, labels: texts, now, validMinutes: VALID_MINUTES })
     if (decision.kind !== 'pending' && dependencies.claimRequest(main, decision.id, now))
       return decision.kind === 'allow' ? { kind: 'allow' } : { kind: 'denied' }
+    const standing = standingPass(heldRequest(opened, requests), log, texts, settings, now)
+    const passed = standing === null ? null : passStanding(main, standing, now, dependencies)
+    if (passed !== null) return passed
     if (now >= deadline) return { kind: 'pending' }
     await dependencies.sleep(POLL_MS)
   }
@@ -106,7 +162,7 @@ const holderOf = (
  */
 export const runGate = async (
   clientCall: ClientCall,
-  labels: GateLabels,
+  texts: GateTexts,
   dependencies: GateDependencies,
 ): Promise<GateOutcome> => {
   if (!isHeld(clientCall)) return null
@@ -114,12 +170,12 @@ export const runGate = async (
     const agent = dependencies.paneAgent()
     if (agent === null || agent.cwd === null) return null
     const main = dependencies.mainCheckoutOf(agent.cwd)
-    const { worktreeDirectory, waitMinutes } = gateSettingsOf(dependencies.config(main))
-    const lane = holderOf(clientCall, agent, main, worktreeDirectory, dependencies)
+    const settings = gateSettingsOf(dependencies.config(main))
+    const lane = holderOf(clientCall, agent, main, settings.worktreeDirectory, dependencies)
     if (!lane) return null
     const { cwd, tool, input } = clientCall
     const request = openRequest(main, { lane, cwd, tool, input }, dependencies)
-    return await awaitDecision(main, request.hash, labels, waitMinutes, dependencies)
+    return await awaitDecision(main, request, texts, settings, dependencies)
   } catch {
     return null
   }

package/kit/hooks/hooks/approval-gate/settings.ts

@@ -1,18 +1,43 @@
+import { isRecord } from '../shared/json'
 import { sectionOf } from '../shared/config'
 import { isRepositoryDirectory } from '../shared/repository-directory'
 
+/** The one environment a standing approval may cover; the same as `STANDING_ENVIRONMENT` in the config schema. */
+export const STAGE = 'stage'
+
 export type GateSettings = {
   /** How long the hook holds a call for the coordinator; below the 10 minutes of the hook entry. */
   waitMinutes: number
   worktreeDirectory: string
+  /** The tools a standing approval may let through, by their full names, each with the environment it writes to. */
+  standingTools: Record<string, typeof STAGE>
+}
+
+export const DEFAULT_GATE_SETTINGS: GateSettings = {
+  waitMinutes: 8,
+  worktreeDirectory: '.claude/worktrees',
+  standingTools: {},
 }
 
-export const DEFAULT_GATE_SETTINGS: GateSettings = { waitMinutes: 8, worktreeDirectory: '.claude/worktrees' }
+const STANDING_TOOL = /^mcp__[A-Za-z0-9_-]+__execute_sql$/
+const PRODUCTION = /prod/i
 
 /** The same bounds as `guard.approvals.waitMinutes` in the config schema, which the hook cannot import. */
 const isWaitMinutes = (value: unknown): value is number =>
   typeof value === 'number' && Number.isInteger(value) && value >= 1 && value <= 9
 
+/** The same rule as the schema's standing tool: a full MCP tool name on `__execute_sql` that does not say `prod`. */
+export const isStandingTool = (tool: string): boolean => STANDING_TOOL.test(tool) && !PRODUCTION.test(tool)
+
+/** The standing tools of `guard.approvals.standing.tools`; one entry the schema refuses lets none through. */
+const standingToolsOf = (standing: Record<string, unknown>): GateSettings['standingTools'] => {
+  const { tools } = standing
+  if (!isRecord(tools)) return {}
+  const entries = Object.entries(tools)
+  const valid = entries.every(([tool, environment]) => environment === STAGE && isStandingTool(tool))
+  return valid ? Object.fromEntries(entries.map(([tool]): [string, typeof STAGE] => [tool, STAGE])) : {}
+}
+
 /** The gate's settings from a parsed config; whatever is missing or malformed keeps its default. */
 export const gateSettingsOf = (config: Record<string, unknown>): GateSettings => {
   const approvals = sectionOf(sectionOf(config, 'guard'), 'approvals')
@@ -22,5 +47,6 @@ export const gateSettingsOf = (config: Record<string, unknown>): GateSettings =>
     worktreeDirectory: isRepositoryDirectory(worktreeDirectory)
       ? worktreeDirectory
       : DEFAULT_GATE_SETTINGS.worktreeDirectory,
+    standingTools: standingToolsOf(sectionOf(approvals, 'standing')),
   }
 }