jackherd 1.2.0 → 1.4.0

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 What changed for people who use jackherd, newest first.
 
+## 1.4.0
+
+- **A question in running text gets a hint.** The new `Stop` hook `ask-hint` tells you when the last message of a turn ends in `?` and no `AskUserQuestion` dialog was used. It only hints; the turn ends as before. A lane session stays silent, because a lane asks its coordinator as a text block. Switch it off with `"hints": { "askUserQuestion": false }` in `.jackherd/config.json`. `jh sync` brings the hook to a project install; a global install ships none.
+
+## 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.

package/README.md

@@ -170,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`, `ask-hint`, `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` |
 
@@ -499,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.
 
@@ -508,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.
 
@@ -1053,6 +1076,8 @@ 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)).
+  - `ask-hint` (event `Stop`) tells you when a turn ends in a question asked as running text and used no `AskUserQuestion` dialog. It only hints, never blocks, and stays silent in a lane session, which asks as a text block. Switch it off with `"hints": { "askUserQuestion": false }` in `.jackherd/config.json`.
   - `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,16 @@ 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>>;
+    hints: z.ZodPrefault<z.ZodObject<{
+        askUserQuestion: z.ZodDefault<z.ZodBoolean>;
+    }, 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,24 @@ 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 hintsSchema = z2.strictObject({
+  /** Whether the `ask-hint` hook points out a last message that ends in a question while the turn used no `AskUserQuestion`; a lane session is never hinted. */
+  askUserQuestion: z2.boolean().default(true)
+});
 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 +389,10 @@ 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 the `ask-hint` hook. */
+  hints: hintsSchema.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.2.0"
+version = "1.4.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.2.0}"
+JACKHERD_VERSION="${JACKHERD_VERSION:-1.4.0}"
 
 JACKHERD_PACKAGE='jackherd'
 # Test seam: the terminal the wizard asks its questions on.

package/kit/hooks/hooks/ask-hint/decision.ts

@@ -0,0 +1,28 @@
+export type HintInput = {
+  message: string
+  tools: string[]
+  lane: boolean
+  stopHookActive: boolean
+  enabled: boolean
+}
+
+export type HintDecision = { kind: 'silent' } | { kind: 'hint'; message: string }
+
+const ASK_TOOL = 'AskUserQuestion'
+
+/** A lane prompt names the lane in its first line; a lane started from a hand-over file reads the file first. */
+const LANE_PROMPT = /^\s*(<pasted_content[^>]*>\s*)?(Du bist die Spur|You are the lane|Read `\.claude\/handover\/)/i
+
+const HINT =
+  'Claude\'s last reply ends in a question, but no AskUserQuestion dialog was used. For choices with fixed answers, ask Claude to use the dialog. Turn this notice off with {"hints": {"askUserQuestion": false}} in .jackherd/config.json.'
+
+/** The last character that counts is a `?`; closing emphasis, quotes and brackets after it do not hide it. */
+export const endsWithQuestion = (message: string): boolean => /[?？][\s*_"')\]“”’»«]*$/.test(message)
+
+export const isLanePrompt = (firstPrompt: string): boolean => LANE_PROMPT.test(firstPrompt)
+
+export const decideHint = (input: HintInput): HintDecision => {
+  if (!input.enabled || input.stopHookActive || input.lane) return { kind: 'silent' }
+  if (!endsWithQuestion(input.message) || input.tools.includes(ASK_TOOL)) return { kind: 'silent' }
+  return { kind: 'hint', message: HINT }
+}

package/kit/hooks/hooks/ask-hint/index.ts

@@ -0,0 +1,44 @@
+// Stop hook, shipped by jackherd. Points out, once per turn, a last message that ends in a question while the turn used
+// no AskUserQuestion dialog. It only hints (a `systemMessage` for the user, exit 0) and never blocks the stop. Any failure
+// inside the hook is silent (a module that does not load or a missing `bun` is not caught here): a hint must not fail a turn. The Stop input carries `last_assistant_message`, `prompt_id` and
+// `transcript_path`; the tools of the turn and the lane prompt come from the transcript, read only when the message is a question.
+import { readFileSync } from 'node:fs'
+import { decideHint, endsWithQuestion, isLanePrompt } from './decision'
+import { isHintEnabled } from './settings'
+import { readTurn } from './transcript'
+
+type StopInput = {
+  last_assistant_message?: unknown
+  prompt_id?: unknown
+  transcript_path?: unknown
+  stop_hook_active?: unknown
+}
+
+const hintFor = (input: StopInput) => {
+  if (typeof input.last_assistant_message !== 'string' || !endsWithQuestion(input.last_assistant_message)) return undefined
+  if (typeof input.transcript_path !== 'string' || input.stop_hook_active === true) return undefined
+  const projectDirectory = process.env.CLAUDE_PROJECT_DIR ?? process.cwd()
+  if (!isHintEnabled(projectDirectory)) return undefined
+  const promptId = typeof input.prompt_id === 'string' ? input.prompt_id : undefined
+  const turn = readTurn(readFileSync(input.transcript_path, 'utf8'), promptId)
+  return decideHint({
+    message: input.last_assistant_message,
+    tools: turn.tools,
+    lane: isLanePrompt(turn.firstPrompt),
+    stopHookActive: false,
+    enabled: true,
+  })
+}
+
+const decide = async () => {
+  try {
+    return hintFor(JSON.parse(await Bun.stdin.text()) as StopInput)
+  } catch {
+    return undefined
+  }
+}
+
+const decision = await decide()
+
+if (decision?.kind === 'hint') console.log(JSON.stringify({ systemMessage: decision.message }))
+process.exit(0)

package/kit/hooks/hooks/ask-hint/settings.ts

@@ -0,0 +1,21 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value)
+
+const readHintsSection = (directories: string[]): Record<string, unknown> => {
+  const path = directories.map((directory) => join(directory, '.jackherd', 'config.json')).find((candidate) => existsSync(candidate))
+  if (!path) return {}
+  try {
+    const config: unknown = JSON.parse(readFileSync(path, 'utf8'))
+    return isRecord(config) && isRecord(config.hints) ? config.hints : {}
+  } catch {
+    return {}
+  }
+}
+
+/** On unless the first config that exists says `hints.askUserQuestion: false`; a malformed value keeps the hint on. */
+export const isHintEnabled = (projectDirectory: string, home: string = homedir()): boolean =>
+  readHintsSection([projectDirectory, home]).askUserQuestion !== false

package/kit/hooks/hooks/ask-hint/transcript.ts

@@ -0,0 +1,55 @@
+export type Turn = { firstPrompt: string; tools: string[] }
+
+type Entry = {
+  type?: unknown
+  isMeta?: unknown
+  promptId?: unknown
+  message?: { content?: unknown }
+}
+
+type Block = { type?: unknown; text?: unknown; name?: unknown }
+
+const parseEntries = (jsonl: string): Entry[] =>
+  jsonl.split('\n').flatMap((line) => {
+    try {
+      const entry: unknown = JSON.parse(line)
+      return typeof entry === 'object' && entry !== null ? [entry as Entry] : []
+    } catch {
+      return []
+    }
+  })
+
+const blocks = (entry: Entry): Block[] => {
+  const content = entry.message?.content
+  return Array.isArray(content) ? (content as Block[]) : []
+}
+
+/** The text a person typed: a string, or text parts. A tool result and the harness's own skill text are no prompt. */
+const promptText = (entry: Entry): string | undefined => {
+  if (entry.type !== 'user' || entry.isMeta === true) return undefined
+  const content = entry.message?.content
+  if (typeof content === 'string') return content
+  const texts = blocks(entry).flatMap((block) => (block.type === 'text' && typeof block.text === 'string' ? [block.text] : []))
+  return texts.length > 0 ? texts.join('\n') : undefined
+}
+
+const toolNames = (entry: Entry): string[] =>
+  entry.type === 'assistant'
+    ? blocks(entry).flatMap((block) => (block.type === 'tool_use' && typeof block.name === 'string' ? [block.name] : []))
+    : []
+
+/**
+ * The first prompt of the session and the tools the current turn used. The turn starts at the last prompt carrying
+ * `promptId` (the Stop input's `prompt_id`), else at the last prompt of the transcript.
+ */
+export const readTurn = (jsonl: string, promptId: string | undefined): Turn => {
+  const entries = parseEntries(jsonl)
+  const prompts = entries.flatMap((entry, index) => (promptText(entry) === undefined ? [] : [index]))
+  const ofTurn = prompts.filter((index) => promptId !== undefined && entries[index].promptId === promptId)
+  const start = (ofTurn.length > 0 ? ofTurn : prompts).at(-1) ?? entries.length
+  const first = prompts[0]
+  return {
+    firstPrompt: first === undefined ? '' : (promptText(entries[first]) ?? ''),
+    tools: entries.slice(start).flatMap(toolNames),
+  }
+}

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)))
+}