jackherd 1.1.0 → 1.3.0

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 What changed for people who use jackherd, newest first.
 
+## 1.3.0
+
+- **A merge or a release asks first.** The new hook `merge-guard` asks you before `gh pr merge` and `gh workflow run` run, behind options before the verb (`gh -R x pr merge`), a chain, a wrapper, `sh -c` and `eval`, also in auto mode. The commands are `guard.commands` in `.jackherd/config.json` (default these two, `git push` not among them); an empty list switches the hook off. It prints nothing unless it asks. It guards against a mistake, not against an agent that sets out to get around it; the README says where the line is.
+- **Self-merge in the PR question.** The `orchestrate` skill's PR question has three options: you merge, you approve and the coordinator merges once the checks are green, or you change something first. On the second, the coordinator waits for the checks in the background, merges with `gh pr merge <number> --squash --delete-branch` on green, does not on red, and tells you in one line. The hook lets exactly that merge pass (`gh pr merge <number>` on its own with merge-method and delete-branch flags), and only for the branch you were asked about, for `guard.selfMerge.approvalMinutes` (default 180): it reads your answer from the session transcript, never from the agent's text, and asks GitHub which branch the pull request carries. `guard.selfMerge.offer: false` takes the option away; a project supplement can block it per tier.
+- **Shorter questions in the dialog.** The `orchestrate` skill now asks in one short sentence of 15 words at most, with the context in the chat before it (three lines), options of a few words and mostly two or three of them, and several questions in one call only when they are independent. The pull request question keeps three bullets of context in the chat and a one-line question. A test measures the example dialogs in the skill.
+- **`jh sync` brings the hook.** A project install gets `merge-guard` in `.claude/hooks/` and an entry in `.claude/settings.json`; a global install ships no hook.
+
+## 1.2.0
+
+- **A running session hears about a new release.** The watcher asks npm once a day, on the timestamp of the `SessionStart` hook, and prints `=== update available <old> → <new>` once per version when there is a newer one; with nothing new it prints nothing. The `orchestrate` skill asks you (update now / not now) and runs `jh update` only after a yes.
+- **The hook also runs after `/clear`, `/resume` and compaction.** Its matcher is now `startup|resume|clear|compact`; `jh sync --global` moves a hook that matches `startup` only, exactly as an older install wrote it, and touches no other entry in `~/.claude/settings.json`.
+- **A silent npm is asked again after an hour.** Before, one unanswered question paused the check for a day. Nothing is printed on a failure.
+- **No `questions:` line for an empty section.** A `## Questions` section that only says "Keine." or "None." counts as no question, and the report keeps its full head.
+- **README.** Three badges at the top: npm version, license, dependencies.
+
 ## 1.1.0
 
 - **Questions in a lane's report reach you.** The watcher cut a new report to its first 15 lines, and the questions, which stand at the end, fell away. It now shows a `## Questions` section (also `## Fragen`, any level, any text after the word) whole, wherever it stands, under a `questions: <n>` line, within a budget of 20 lines and 1500 characters (over it, each question keeps the start of its first line and a closing line says how many were left out). A report with such a section gets a shorter head (8 lines, 900 characters: the diff stat and the checks), so the message stays about as long as before. The `orchestrate` skill makes every question a duty in the same wake-up: answered in the lane, or put to you, and a question the lane answered is reported to you in one line.

package/README.md

@@ -6,6 +6,8 @@
 <br>
 </p>
 
+[![npm](https://img.shields.io/npm/v/jackherd)](https://www.npmjs.com/package/jackherd) [![license: MIT](https://img.shields.io/npm/l/jackherd)](https://www.npmjs.com/package/jackherd) [![2 dependencies](https://img.shields.io/badge/dependencies-2-brightgreen)](https://www.npmjs.com/package/jackherd?activeTab=dependencies)
+
 **Plan. Delegate. Ship.** Your agents do the work. Jack keeps them together.
 
 Large tasks outgrow one chat, the context fills up, parallel sessions edit the same files, and
@@ -168,7 +170,7 @@ When `init` creates a new config, it asks:
 | Use it when | the team shares the kit through the repository | the repository must stay untouched, not even untracked files |
 | Lives in | the project's `.claude/` | `~/.claude/` |
 | Skill names | `/plan`, `/implement`, `/orchestrate`, … | `/jh-plan`, `/jh-implement`, `/jh-orchestrate`, … |
-| Hooks | `git-guard`, `watch-guard`, `format-on-edit` | none; `init --global` offers only a `SessionStart` update notice |
+| Hooks | `git-guard`, `watch-guard`, `merge-guard`, `format-on-edit` | none; `init --global` offers only a `SessionStart` update notice |
 | Config | `.jackherd/config.json` | `~/.jackherd/config.json`, used where a repository has none |
 | Update | `jh sync` | `jh update` |
 
@@ -260,10 +262,12 @@ A running `plans` view restarts itself with the new code, and a running `watch`
 `jh sync --global --if-changed` is meant to run at the start of every session. It syncs `~/.claude` only when the installed package is not the version the global lock was written by, so after `bun add -g jackherd@<version>` the next session brings the skills up to date. Once a day it asks npm for the newest release and, when there is one, prints a single line of this form:
 
 ```text
-jh 1.1.0 is on npm, 1.0.0 is installed. Ask the user with AskUserQuestion whether to run `jh update` now (update now / not now), and run it only after a yes.
+jh 1.2.0 is on npm, 1.1.0 is installed. Ask the user with AskUserQuestion whether to run `jh update` now (update now / not now), and run it only after a yes.
 ```
 
-It never installs anything itself: the session asks you, and `jh update` runs only after your yes. With nothing to do it prints nothing and exits 0; without a global install it syncs nothing. The time of the last npm question is kept in `~/.jackherd/update-check.json`.
+It never installs anything itself: the session asks you, and `jh update` runs only after your yes. With nothing to do it prints nothing and exits 0; without a global install it syncs nothing. The time of the last npm question is kept in `~/.jackherd/update-check.json`. If npm does not answer (3 seconds), the question is asked again after an hour, not after a day, and nothing is printed meanwhile.
+
+The hook runs when a session starts, resumes, is cleared or is compacted (`startup|resume|clear|compact`), so a hand-over by `/clear` sees the line too; the daily timestamp makes the extra runs free. A session that runs for days is covered by [the watcher](#user-content-the-watcher), which looks at npm once a day on the same timestamp. `jh sync --global` moves a hook that still reads `startup` only, exactly as an older install wrote it, to the new matcher; a hook of your own, or one with another command or extra keys, stays as it is.
 
 `init --global` asks once whether to add this hook to `~/.claude/settings.json`, appends it as a group of its own beside your other hooks, and does nothing when it is there already. A file it cannot read or merge into, or a symlink, stays as it is; the entry to add by hand:
 
@@ -271,7 +275,7 @@ It never installs anything itself: the session asks you, and `jh update` runs on
 {
   "hooks": {
     "SessionStart": [
-      { "matcher": "startup", "hooks": [{ "type": "command", "command": "jh sync --global --if-changed" }] }
+      { "matcher": "startup|resume|clear|compact", "hooks": [{ "type": "command", "command": "jh sync --global --if-changed" }] }
     ]
   }
 }
@@ -495,7 +499,7 @@ Lanes ask Jack, not you: the coordinator checks their questions against the plan
 3. **Runs dev servers.** A lane whose phase changes something a user sees gets its dev server in a pane of its own when the lane starts, never in the lane's shell.
 4. **Vets questions.** A lane never opens a dialog. It ends its turn with a text block: the question, the options, its recommendation, the evidence at `file:line`. The coordinator checks the premises against the code and the plan, answers what the plan or a rule already settles, and brings only the open decisions to you, each as a clickable choice. A question in a lane's report is closed in the same turn, in the lane or with you. A draft you review (a README, a page) goes in rounds: you pick the remarks, the lane changes it, you see it again, and the push waits for your approval. Your decision goes into the plan or the board in the same turn, with the date, so it is visible in the plan view and survives the chat.
 5. **Reviews results.** When a lane is `done` or `idle`, it checks the diff against the lane's `Writes` set and that checks are quoted with numbers, not claimed. Then it starts the lane's next ready phase or names the reason to wait.
-6. **Asks once per PR.** A lane works uncommitted until its PR is ready. The coordinator then asks you once, with the diff summary, the checks with numbers, open points and the commit message; for a visible change it first walks the changed path in the browser. That approval covers the commits, the push and the PR.
+6. **Asks once per PR.** A lane works uncommitted until its PR is ready. The coordinator then asks you once, with the diff summary, the checks with numbers, open points and the commit message; for a visible change it first walks the changed path in the browser. That approval covers the commits, the push and the PR. The question has three options: you merge, you approve and let the coordinator merge once the checks are green ([self-merge](#user-content-guarded-commands-and-self-merge)), or you change something first.
 7. **Keeps the merge order.** Merge order is the board's, and the documentation PR of a fresh plan merges first. Afterwards the lanes rebase as after any merge, and the coordinator removes the copies of the plan files in the main checkout that equal the merged ones, so the next update of the checkout does not stop on them. After each merge the remaining lanes fetch and rebase on the base branch and re-run their checks; a lock-file conflict is never resolved by hand. Each lane gets its next phase or a named reason to wait.
 8. **Closes lanes.** After a lane's last merge and your agreement, it ends the agent, proves the worktree holds nothing unmerged, removes the worktree and the branch, and notes the end in the board.
 
@@ -504,11 +508,34 @@ Lanes ask Jack, not you: the coordinator checks their questions against the plan
 | On its own | After your approval | Never |
 | --- | --- | --- |
 | Starting a ready phase in a new or running lane (one line to you afterwards) | Commits, push and PR: one approval per PR, the documentation PR for a fresh plan included | Implementing lane work itself |
-| Answering a question the plan, the board or a rule settles (reported in one line) | Every open decision a lane raises | Merging, unless a project supplement names PRs it may merge |
+| Answering a question the plan, the board or a rule settles (reported in one line) | Every open decision a lane raises | Merging, unless a project supplement names PRs it may merge or you picked self-merge for the PR |
 | Rebasing lanes after a merge, with their checks re-run | Database migrations and writes against a shared environment | Confirming a chained git command or storing a permission |
 | Writing your decisions into the plan or the board | Ending an agent, closing a lane, a hand-over to a fresh chat | Steering herdr from outside herdr |
 
-Who merges follows the project's own rules: by default you, unless the project supplement (`.claude/project/orchestrate.md`) names PRs the coordinator may merge itself and under which conditions.
+Who merges follows the project's own rules: by default you, unless the project supplement (`.claude/project/orchestrate.md`) names PRs the coordinator may merge itself and under which conditions, or you picked self-merge for that PR.
+
+#### Guarded commands and self-merge
+
+A merge or a release is the step nobody takes back. In a project install the `merge-guard` hook asks you before `gh pr merge` and `gh workflow run` (the usual production release) run: it recognises them when the command spells them out: behind options before the verb (`gh -R x pr merge`), a chain (`a && gh pr merge 12`), a wrapper (also one it does not know, such as `mise exec -- gh pr merge 12`, as any command whose words contain the guarded words in this order), `sh -c` and `eval`, and shows the dialog even in auto mode. A quoted text that names the words, such as a commit message, passes, and so does everything else; the hook prints nothing unless it asks.
+
+```json
+{
+  "guard": {
+    "commands": ["gh pr merge", "gh workflow run"],
+    "selfMerge": { "offer": true, "approvalMinutes": 180 }
+  }
+}
+```
+
+- `guard.commands` lists the guarded commands as words, a program and one to three plain words after it: letters, digits and `-`, no `:` and no option. These two are the default; `git push` is not on the list. An empty list switches the guard off.
+- `guard.selfMerge.offer` (default `true`) lets `/orchestrate` offer "approve, and merge it yourself after green checks" in its PR question. With `false` the question has two options and the hook honours no such answer.
+- `guard.selfMerge.approvalMinutes` (default 180) is how long that answer lets `gh pr merge <number>` pass without a second dialog.
+
+**What self-merge does.** You pick the second option of the PR question. The coordinator commits, pushes and opens the PR, waits for the checks in the background, merges with `gh pr merge <number> --squash --delete-branch` when they are green and tells you in one line; on a red check it does not merge and reports. The project supplement can block the option per approval tier.
+
+**What the hook checks.** It does not take the agent's word for your answer. It reads the session's transcript, which Claude Code writes, and looks for a dialog result where you picked that exact option for a question naming one branch. Then it asks GitHub which branch pull request `<number>` carries and lets the merge pass if the two match, the PR is open and not from a fork, and the command is exactly the plain form: `gh pr merge <number>` with `--squash`, `--merge`, `--rebase` and `--delete-branch` as the only flags, run on its own in the directory you work in (no `-R`, no `--admin`, no chain, no wrapper). `gh workflow run` and every other guarded command ask every time.
+
+**Its limit.** The hook reads the command as written, so it does not see what a command runs behind its back: a script file or a project script (`bash ./release.sh`, `./release.sh`, `bun run release`, `make release`) that calls `gh workflow run`, a shell alias or function, `gh alias` and git aliases, text that is encoded or assembled at run time, and a wrapper that spells the words differently. Add the script runners you use to `guard.commands`, or protect the repository itself. The agent runs with your account, so it can also edit a transcript, drop the hook from `.claude/settings.json` or merge through `gh api`. The guard stops a merge or a release by mistake, by a misread instruction or a mistyped command; it does not stop an agent that sets out to get around it. For that, use branch protection and required reviews on the repository. The approval covers the branch, not the commits you saw, for the configured minutes. A global install ships no hook, so there the skill text alone asks you. If Bun cannot start (a process out of file descriptors, say), the hook cannot run and every Bash call is blocked, on purpose: a guard that cannot run does not wave commands through.
 
 A permission dialog inside a lane the coordinator confirms itself only for the commit and push of the lane's own branch under its PR approval, and for the fetch, rebase and lock-file steps after a merge, always with the one-time option. Every other dialog goes to you.
 
@@ -528,6 +555,7 @@ Why it exists: the coordinator is a chat, and it only acts when something arrive
 - a deploy preview for a lane's new head commit, with its link (`watch.previews`)
 - a new or changed entry of an external service, such as a ticket comment, read by a command the config names (`watch.sources`)
 - `gh` became unreachable
+- npm has a newer jackherd than the one running: `=== update available <old> → <new>`, one line, once per version. The watcher asks npm once a day on the timestamp the `SessionStart` hook uses (`~/.jackherd/update-check.json`), so the two never ask twice a day or report twice; with nothing newer it prints nothing. The coordinator asks you and runs `jh update` only after your yes
 - a lane's context fill rose to `warn` or `alert` (`=== lane <name> alert 47 %`, with a duty line at `alert`: request the lane's hand-over at its next phase boundary), against the lanes' thresholds in `plans.context`
 - the coordinator's own context fill rose to `warn` or `alert`, so it hands itself over in time
 - `lane added` / `lane removed` when a worktree with an agent or a board row appears or goes
@@ -1048,6 +1076,7 @@ What usually stays to configure is what no file in the repository says, for exam
 - **Hooks** (project install only):
   - `git-guard` refuses a git command that hides `commit`, `push`, `rebase`, `reset`, `checkout` or `merge` from your permission rules (`git -C … push`, `sh -c "…"`).
   - `watch-guard` refuses a `jh watch` start whose reports would go unseen.
+  - `merge-guard` asks you before `gh pr merge` and `gh workflow run` run, when they are spelled out ([Guarded commands](#user-content-guarded-commands-and-self-merge)).
   - `format-on-edit` runs the project's own Biome on edited TS, JS and JSON files, when the project has it installed.
 - **herdr plugin:** a plans pane and an action that opens it ([Installation](#user-content-project-install)).
 

package/dist/{chunk-R6MGHCD7.js → chunk-UI3AZNZF.js}

@@ -4,6 +4,10 @@ var LANGUAGE_NAME = {
   [PLAN_LANGUAGE.en]: "English",
   [PLAN_LANGUAGE.de]: "German"
 };
+var SELF_MERGE_LABEL = {
+  [PLAN_LANGUAGE.en]: "Approve, and merge it yourself after green checks",
+  [PLAN_LANGUAGE.de]: "Freigeben, und nach gr\xFCnen Checks selbst mergen"
+};
 var isPlanLanguage = (value) => Object.values(PLAN_LANGUAGE).includes(value);
 var PLAN_STATUS = {
   done: "done",
@@ -84,6 +88,7 @@ var sectionHeading = (language, section) => `## ${PLAN_VOCABULARY[language].sect
 export {
   PLAN_LANGUAGE,
   LANGUAGE_NAME,
+  SELF_MERGE_LABEL,
   isPlanLanguage,
   PLAN_STATUS,
   PLAN_VOCABULARY,

package/dist/config.d.ts

@@ -132,6 +132,13 @@ declare const jackherdConfigSchema: z.ZodObject<{
             reportOn: z.ZodOptional<z.ZodArray<z.ZodString>>;
         }, z.core.$strict>>>;
     }, z.core.$strict>>;
+    guard: z.ZodPrefault<z.ZodObject<{
+        commands: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        selfMerge: z.ZodPrefault<z.ZodObject<{
+            offer: z.ZodDefault<z.ZodBoolean>;
+            approvalMinutes: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
     check: z.ZodOptional<z.ZodObject<{
         lintFilesCommand: z.ZodDefault<z.ZodString>;
         checks: z.ZodDefault<z.ZodArray<z.ZodObject<{

package/dist/config.js

@@ -1,6 +1,6 @@
 import {
   PLAN_LANGUAGE
-} from "./chunk-R6MGHCD7.js";
+} from "./chunk-UI3AZNZF.js";
 
 // src/config/json-schema.ts
 import { z as z3 } from "zod";
@@ -298,6 +298,20 @@ var coordinatorSchema = z2.strictObject({
   /** Share of the coordinator's context window from which the watcher reports `coordinator alert`. */
   alertAt: share.default(0.7)
 }).refine(warnBelowAlert, WARN_BELOW_ALERT);
+var guardedCommand = z2.string().regex(/^[a-z][a-z0-9-]*( [a-z][a-z0-9-]*){1,3}$/, "a program and one to three plain words, such as gh pr merge");
+var guardSchema = z2.strictObject({
+  /**
+   * The commands the merge guard hook asks the user about before they run, also behind options before the verb, a chain,
+   * a wrapper or `sh -c`. An empty list switches the guard off.
+   */
+  commands: z2.array(guardedCommand).default(["gh pr merge", "gh workflow run"]),
+  selfMerge: z2.strictObject({
+    /** Whether `/orchestrate` offers "merge it yourself after green checks" in the pull request question; off also stops the hook honouring such an answer. */
+    offer: z2.boolean().default(true),
+    /** How long an answer to that question lets `gh pr merge <number>` pass without asking, counted from the answer. */
+    approvalMinutes: z2.number().int().min(1).max(1440).default(180)
+  }).prefault({})
+});
 var contextSchema = z2.strictObject({
   /** Share of the context window from which a lane's fill shows yellow and `/implement` offers a new chat. */
   warnAt: share.default(0.6),
@@ -371,6 +385,8 @@ var jackherdConfigSchema = z2.strictObject({
     previews: previewsSchema.optional(),
     sources: z2.array(sourceSchema).refine(hasUniqueNames, "source names must be unique").default([])
   }).prefault({}),
+  /** Read by the merge guard hook, which asks before the listed commands run, and by `/orchestrate`. */
+  guard: guardSchema.prefault({}),
   /** Read by `jh check`; validated here too, so a typo fails every command alike. */
   check: checkConfigSchema.optional()
 });

package/dist/plan-format.d.ts

@@ -5,6 +5,12 @@ declare const PLAN_LANGUAGE: {
 type PlanLanguage = (typeof PLAN_LANGUAGE)[keyof typeof PLAN_LANGUAGE];
 /** The language's name as a reply or a question says it. */
 declare const LANGUAGE_NAME: Record<PlanLanguage, string>;
+/**
+ * The option of the pull request question that approves the PR and a merge by the coordinator once the checks are
+ * green. The merge guard hook matches the user's answer against this exact text, so it is fixed per language and not
+ * a config value.
+ */
+declare const SELF_MERGE_LABEL: Record<PlanLanguage, string>;
 declare const isPlanLanguage: (value: string) => value is PlanLanguage;
 declare const PLAN_STATUS: {
     readonly done: "done";
@@ -322,4 +328,4 @@ declare const readSprintDocument: (markdown: string, language: PlanLanguage) =>
  */
 declare const readPhaseDependencies: (planMarkdown: string, language: PlanLanguage) => Record<string, string>;
 
-export { type ChecklistItem, type DeferredItem, type DriftFinding, LANGUAGE_NAME, type LaneProgress, type MergedPhaseWithOpenBoxes, type MisplacedDeferral, PHASE_ID_PREFIX, PLAN_LANGUAGE, PLAN_STATUS, PLAN_VOCABULARY, type PhaseProgress, type PhaseTally, type PhaseWithoutGate, type PlanHeader, type PlanLanguage, type PlanPhase, type PlanStatus, type PlanStep, type PlanVocabulary, type PlansByHref, type RowWithoutPhase, type SprintDocument, type SprintLane, type SprintPlanRow, type SprintPlanTable, type StatusWord, type StepProgress, activeItem, boardRowsWithoutPhase, classifyStatus, countDecisions, currentPhase, currentPhaseOf, deferralTarget, endsPhase, findDrift, hasLanesTable, isCheckboxLine, isOpenCheckboxLine, isPlanLanguage, isReviewGateLine, isTickedUnmerged, keptPhaseIds, laneNameOf, laneProgress, mergedPhasesWithOpenBoxes, misplacedDeferrals, newPhasesWithoutReviewGate, parsePlanPhases, parseSprintLanes, phaseHeading, phaseHeadingPattern, phaseIdsOfCell, phaseIdsOfPlan, readPhaseDependencies, readPlanHeader, readSprintDocument, resolvePlanPath, sectionHeading, shortTitle, sprintTitleOf, sumPhases, tallyPhases, withoutRepeats };
+export { type ChecklistItem, type DeferredItem, type DriftFinding, LANGUAGE_NAME, type LaneProgress, type MergedPhaseWithOpenBoxes, type MisplacedDeferral, PHASE_ID_PREFIX, PLAN_LANGUAGE, PLAN_STATUS, PLAN_VOCABULARY, type PhaseProgress, type PhaseTally, type PhaseWithoutGate, type PlanHeader, type PlanLanguage, type PlanPhase, type PlanStatus, type PlanStep, type PlanVocabulary, type PlansByHref, type RowWithoutPhase, SELF_MERGE_LABEL, type SprintDocument, type SprintLane, type SprintPlanRow, type SprintPlanTable, type StatusWord, type StepProgress, activeItem, boardRowsWithoutPhase, classifyStatus, countDecisions, currentPhase, currentPhaseOf, deferralTarget, endsPhase, findDrift, hasLanesTable, isCheckboxLine, isOpenCheckboxLine, isPlanLanguage, isReviewGateLine, isTickedUnmerged, keptPhaseIds, laneNameOf, laneProgress, mergedPhasesWithOpenBoxes, misplacedDeferrals, newPhasesWithoutReviewGate, parsePlanPhases, parseSprintLanes, phaseHeading, phaseHeadingPattern, phaseIdsOfCell, phaseIdsOfPlan, readPhaseDependencies, readPlanHeader, readSprintDocument, resolvePlanPath, sectionHeading, shortTitle, sprintTitleOf, sumPhases, tallyPhases, withoutRepeats };

package/dist/plan-format.js

@@ -3,11 +3,12 @@ import {
   PLAN_LANGUAGE,
   PLAN_STATUS,
   PLAN_VOCABULARY,
+  SELF_MERGE_LABEL,
   classifyStatus,
   isPlanLanguage,
   phaseHeading,
   sectionHeading
-} from "./chunk-R6MGHCD7.js";
+} from "./chunk-UI3AZNZF.js";
 
 // src/plan-format/terminal-text.ts
 var UNSAFE_RANGES = [
@@ -596,6 +597,7 @@ export {
   PLAN_LANGUAGE,
   PLAN_STATUS,
   PLAN_VOCABULARY,
+  SELF_MERGE_LABEL,
   activeItem,
   boardRowsWithoutPhase,
   classifyStatus,

package/herdr-plugin/herdr-plugin.toml

@@ -1,6 +1,6 @@
 id = "crossdelta.jackherd"
 name = "jackherd"
-version = "1.1.0"
+version = "1.3.0"
 min_herdr_version = "0.8.2"
 description = "Show the plans of a board's lanes in a herdr pane"
 platforms = ["linux", "macos"]

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.1.0}"
+JACKHERD_VERSION="${JACKHERD_VERSION:-1.3.0}"
 
 JACKHERD_PACKAGE='jackherd'
 # Test seam: the terminal the wizard asks its questions on.

package/kit/hooks/hooks/git-guard/decision.ts

@@ -1,5 +1,14 @@
 import { posix } from 'node:path'
-import { parseShell, ShellParseError, type SimpleCommand, type Word } from './shell'
+import {
+  ASSIGNMENT,
+  inlineScript,
+  isOption,
+  isProgramPosition,
+  programName,
+  readsScriptFromInput,
+  ruleStart,
+} from '../shared/program-position'
+import { parseShell, ShellParseError, type SimpleCommand, type Word } from '../shared/shell'
 
 export type GitGuardDecision = { kind: 'pass' } | { kind: 'deny'; reason: string }
 
@@ -133,16 +142,6 @@ const OPTIONS_WITH_VALUE = new Set([
 const CONFIG_OPTIONS = new Set(['-c', '--config-env'])
 const CONFIG_ENV_ATTACHED = '--config-env='
 
-/**
- * Words Claude Code strips before it matches a Bash rule, so they do not hide the command. Its
- * permission matching also reaches into control-flow bodies, which the reserved words open.
- */
-const RULE_TRANSPARENT_WRAPPERS = new Set(['time', 'nohup', 'nice', 'command', 'builtin', 'noglob'])
-const RESERVED_WORDS = new Set(['!', '{', '}', 'if', 'then', 'elif', 'else', 'fi', 'do', 'done', 'while', 'until'])
-const ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*\+?=/
-const DURATION = /^\d+(\.\d+)?[smhd]?$/
-const SHELLS = new Set(['sh', 'bash', 'zsh', 'dash', 'ksh', 'mksh', 'fish'])
-const SHELL_COMMAND_FLAG = /^-[a-z]*c[a-z]*$/
 const INLINE_ALIAS = /^alias\./i
 /** Variables that make git or its hook manager skip the hooks. */
 const HOOK_SKIPPING_VARIABLE = /^(HUSKY|LEFTHOOK|SKIP)\+?=/
@@ -150,19 +149,6 @@ const HOOK_SKIPPING_VARIABLE = /^(HUSKY|LEFTHOOK|SKIP)\+?=/
 const REDIRECTING_VARIABLE = /^(GIT_CONFIG\w*|GIT_DIR|GIT_WORK_TREE|GIT_INDEX_FILE)\+?=/
 /** An option the shell rewrites before git sees it: `--forc{e,}` reaches git as `--force`. */
 const BRACE_IN_OPTION = /^-.*\{.*(,|\.\.).*\}/
-/** Programs that run their arguments as a command, so a `git` right after them is the program. */
-const COMMAND_RUNNERS = new Set([
-  ...RULE_TRANSPARENT_WRAPPERS,
-  'env',
-  'sudo',
-  'doas',
-  'exec',
-  'xargs',
-  'timeout',
-  'stdbuf',
-  'setsid',
-  'watch',
-])
 const PROTECTED_MENTION = new RegExp(`\\bgit\\b[\\s\\S]*\\b(${Object.values(PROTECTED_VERB).join('|')})\\b`)
 
 const isProtectedVerb = (value: string): value is ProtectedVerb =>
@@ -170,38 +156,7 @@ const isProtectedVerb = (value: string): value is ProtectedVerb =>
 
 const deny = (reason: string): GitGuardDecision => ({ kind: 'deny', reason })
 
-const transparentWidth = (words: SimpleCommand, index: number): number => {
-  const { value, literal } = words[index]
-  if (ASSIGNMENT.test(value)) return 1
-  if (!literal) return 0
-  if (RESERVED_WORDS.has(value) || RULE_TRANSPARENT_WRAPPERS.has(value)) return 1
-  return value === 'timeout' && DURATION.test(words[index + 1]?.value ?? '') ? 2 : 0
-}
-
-/** The index of the word a permission rule compares against: past assignments and stripped wrappers. */
-const ruleStart = (words: SimpleCommand): number => {
-  let index = 0
-  while (index < words.length) {
-    const width = transparentWidth(words, index)
-    if (width === 0) break
-    index += width
-  }
-  return index
-}
-
-/** The program a word names, as a case-insensitive file system would find it. */
-const programName = (word: Word): string =>
-  posix
-    .basename(word.value.replace(/^=/, ''))
-    .toLowerCase()
-    .replace(/\.exe$/, '')
-
 const isGit = (word: Word): boolean => programName(word) === 'git'
-
-/** At the rule start, or anywhere after a runner such as `sudo -u me` or `env FOO=1`: git runs as the program. */
-const isProgramPosition = (words: SimpleCommand, index: number): boolean =>
-  index === ruleStart(words) || words.slice(0, index).some((word) => COMMAND_RUNNERS.has(programName(word)))
-
 const gitPosition = (words: SimpleCommand, index: number, context: ScriptContext): GitPosition => {
   const word = words[index]
   const plain = context === SCRIPT_CONTEXT.top && index === ruleStart(words) && word.literal && word.value === 'git'
@@ -209,8 +164,6 @@ const gitPosition = (words: SimpleCommand, index: number, context: ScriptContext
   return isProgramPosition(words, index) ? GIT_POSITION.program : GIT_POSITION.argument
 }
 
-const isOption = (word: Word | undefined): boolean => word?.value.startsWith('-') ?? false
-
 const readInvocation = (words: SimpleCommand, gitIndex: number): GitInvocation | undefined => {
   const options: Word[] = []
   const directories: string[] = []
@@ -342,28 +295,6 @@ const judgeInvocation = (invocation: GitInvocation, position: GitPosition): GitG
   return literal || position === GIT_POSITION.argument ? PASS : deny(VERB_HINT)
 }
 
-const isShell = (word: Word): boolean => SHELLS.has(programName(word))
-
-/** The script word after `-c`: the first one that is neither an option nor `--`. */
-const shellCommandScript = (words: SimpleCommand, shellIndex: number): string | undefined => {
-  const flag = words.findIndex((word, position) => position > shellIndex && SHELL_COMMAND_FLAG.test(word.value))
-  if (flag === -1) return undefined
-  return words.slice(flag + 1).find((word) => !isOption(word))?.value
-}
-
-const inlineScript = (words: SimpleCommand, index: number): string | undefined => {
-  const word = words[index]
-  if (word.literal && word.value === 'eval') return words.slice(index + 1).map(({ value }) => value).join(' ')
-  return isShell(word) ? shellCommandScript(words, index) : undefined
-}
-
-/** A shell at the rule start with no script argument reads its script from stdin: a pipe, a here-document. */
-const readsScriptFromInput = (words: SimpleCommand): boolean => {
-  const start = ruleStart(words)
-  const shell = words[start]
-  return shell !== undefined && isShell(shell) && words.slice(start + 1).every(isOption)
-}
-
 /**
  * `HUSKY=0`, `export HUSKY=0`, `local -x HUSKY=0`, `set -a; HUSKY=0`: wherever such an assignment
  * stands, it may reach a later git call of the script, not only the one it precedes.

package/kit/hooks/hooks/merge-guard/approval.ts

@@ -0,0 +1,107 @@
+/**
+ * What the user approved, read from the session transcript. The transcript is written by Claude Code,
+ * not by the agent: a dialog answer sits in it as the tool result of an `AskUserQuestion` call, with
+ * the question the agent put and the label the user picked. Nothing an agent says in a message,
+ * a file or a command counts, so a text cannot stand in for the click.
+ *
+ * The limit: an agent that runs as the user could still write to the transcript file. This guards
+ * against a mistake, not against an agent that sets out to get around it.
+ */
+
+type Record_ = Record<string, unknown>
+
+const MS_PER_MINUTE = 60_000
+const BRANCH_MENTION = /\bBranch `([^`]*)`/g
+
+/** A branch name as git takes it from a shell word: no leading dash, no space, no `..`, no shell character. */
+const BRANCH_NAME = /^(?![-/.])(?!.*(?:\.\.|\/\/|@\{))[A-Za-z0-9._/-]+$/
+
+const isRecord = (value: unknown): value is Record_ => typeof value === 'object' && value !== null && !Array.isArray(value)
+
+const contentOf = (entry: Record_): Record_[] => {
+  const content = isRecord(entry.message) ? entry.message.content : undefined
+  return Array.isArray(content) ? content.filter(isRecord) : []
+}
+
+const isMainThread = (entry: Record_): boolean => entry.isSidechain !== true
+
+/** One JSON value per line; a line that is not JSON is skipped. */
+export const parseTranscript = (text: string): unknown[] =>
+  text.split('\n').flatMap((line) => {
+    try {
+      return line.trim() === '' ? [] : [JSON.parse(line)]
+    } catch {
+      return []
+    }
+  })
+
+/** Whether the question offers `label` as one option among single choices: a multi-select joins its picks into one text. */
+const offersLabel = (question: Record_, label: string): boolean =>
+  question.multiSelect !== true &&
+  Array.isArray(question.options) &&
+  question.options.some((option) => isRecord(option) && option.label === label)
+
+const questionTexts = (input: unknown, label: string): string[] => {
+  if (!isRecord(input) || 'answers' in input || !Array.isArray(input.questions)) return []
+  return input.questions.flatMap((question) =>
+    isRecord(question) && typeof question.question === 'string' && offersLabel(question, label)
+      ? [question.question]
+      : [],
+  )
+}
+
+/**
+ * The questions of each `AskUserQuestion` call that offer `label`, by tool use id. A call that carries its own
+ * `answers` asked nobody.
+ */
+const askedQuestions = (entries: Record_[], label: string): Map<string, string[]> =>
+  new Map(
+    entries
+      .filter(isMainThread)
+      .flatMap(contentOf)
+      .filter((block) => block.type === 'tool_use' && block.name === 'AskUserQuestion' && typeof block.id === 'string')
+      .map((block): [string, string[]] => [block.id as string, questionTexts(block.input, label)]),
+  )
+
+const isFresh = (timestamp: unknown, now: number, windowMinutes: number): boolean => {
+  const answeredAt = typeof timestamp === 'string' ? Date.parse(timestamp) : Number.NaN
+  const age = now - answeredAt
+  return age >= 0 && age <= windowMinutes * MS_PER_MINUTE
+}
+
+/** The one branch a question names as ``Branch `name` ``; a question that names none or several approves none. */
+const namedBranch = (question: string): string | undefined => {
+  const names = new Set([...question.matchAll(BRANCH_MENTION)].map(([, name]) => name))
+  const [only] = names
+  return names.size === 1 && BRANCH_NAME.test(only) ? only : undefined
+}
+
+/** The branches one result entry approves: the questions of its `AskUserQuestion` call that the user answered with `label`. */
+const branchesApprovedIn = (entry: Record_, asked: Map<string, string[]>, label: string): string[] => {
+  const answers = isRecord(entry.toolUseResult) ? entry.toolUseResult.answers : undefined
+  if (!isRecord(answers)) return []
+  return contentOf(entry)
+    .filter((block) => block.type === 'tool_result')
+    .flatMap((block) => asked.get(String(block.tool_use_id)) ?? [])
+    .filter((question) => answers[question] === label)
+    .flatMap((question) => namedBranch(question) ?? [])
+}
+
+export type ApprovalQuery = {
+  entries: unknown[]
+  /** The exact option label that approves a merge. */
+  label: string
+  /** The time of the check, in milliseconds. */
+  now: number
+  /** How long an answer holds, in minutes; an answer from the future does not hold at all. */
+  windowMinutes: number
+}
+
+/** The branches whose question the user answered with `label` within the window. */
+export const approvedBranches = ({ entries, label, now, windowMinutes }: ApprovalQuery): Set<string> => {
+  if (label === '') return new Set()
+  const records = entries.filter(isRecord)
+  const asked = askedQuestions(records, label)
+  const fresh = records.filter((entry) => isMainThread(entry) && isFresh(entry.timestamp, now, windowMinutes))
+  return new Set(fresh.flatMap((entry) => branchesApprovedIn(entry, asked, label)))
+}