jackherd 1.3.0 → 1.5.0

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 What changed for people who use jackherd, newest first.
 
+## 1.5.0
+
+- **The plans view lists only the lanes that still have something to do.** Before, every lane without an agent was listed (56 of 61 on one board, nearly all of them finished). Now a lane marked cleaned up, and a lane without a worktree whose named phases are all ticked, are not shown. A lane without a worktree that still has an open phase, or no plan and a "starts after" other than "now", is listed under `· waiting` with what it waits for. A worktree without an agent stays under `· no agent`. The board needs no change. The watcher is unchanged.
+- **Documents merge without waiting for checks.** The new setting `merge.withoutChecks` (default empty) lists path patterns such as `docs/**/*.md`. When every file of a pull request matches, `/orchestrate` merges at once instead of `gh pr checks --watch`, and the merge guard does not ask for a plain `gh pr merge <number>`: it checks the file list on GitHub itself and asks as before on any doubt. Pattern rules are in the README.
+- **The heartbeat shows progress.** In a stream, a `working` lane whose phase count moved since the last heartbeat becomes `<lane> working: P12 7/12`; a lane that did not move adds nothing. The heartbeat line stays short.
+- **Source scripts are TypeScript.** The `follow` skill now writes a source's script as `scripts/sources/<name>.ts`, started with `["bun", "scripts/sources/<name>.ts"]` (Bun must be installed). The token goes from `process.env` into the request header, and a failure is an exit code, not an empty list. The README recipes for Jira with `acli`, Linear and Sentry are replaced, and a test compiles each one. The watcher reads `bun` as a source's program to mean the Bun that runs it, so Bun need not be on the `PATH`. Existing `watch.sources` entries keep working; recipes without a script stay direct commands.
+
+## 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.

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`, `merge-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` |
 
@@ -531,6 +531,16 @@ A merge or a release is the step nobody takes back. In a project install the `me
 - `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.
 
+**Merging without checks.** A pull request that only changes documents rarely needs its checks. List the paths in `merge.withoutChecks` (default empty, so every merge waits for the checks as before):
+
+```json
+{
+  "merge": { "withoutChecks": ["docs/**/*.md"] }
+}
+```
+
+A pattern is made of path words with `*` and `**`: no `..`, not absolute, no braces or negation, and at least one whole path segment without a wildcard, so `docs/**/*.md` is fine and `**`, `**/*.md` and `**/*.*` are refused. Keep the folder in the pattern: a `.md` file elsewhere can be an agent instruction (`CLAUDE.md`, a skill) that ships with a package and deserves its checks. With the list set, `/orchestrate` lists a pull request's files with `gh pr diff <number> --name-only` before it waits for checks and merges at once when every file matches. The merge guard checks the same itself: for a plain `gh pr merge <number>` it asks GitHub for the pull request and then for its files in that repository (`gh api …/pulls/<number>/files`, which also names the old path of a renamed file) and does not ask you when the pull request is open, from this repository, GitHub lists as many files as the pull request changes (fewer than 3000) and every one matches a pattern. This works without a self-merge answer, also when `guard.selfMerge.offer` is `false`. No file, one file outside, a count that differs, a failed `gh` call or a pattern list it cannot read means it asks as before. Limit: a push between its look and the merge is not seen.
+
 **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.
@@ -580,7 +590,7 @@ coordinator coordinator no value (no agent named coordinator)
 gh unavailable since 11:24:31
 ```
 
-As a stream (`--stream`) it keeps running, and the heartbeat is one line:
+As a stream (`--stream`) it keeps running, and the heartbeat is one line. A working lane shows its plan progress, `<lane> working: P12 7/12` (the lane's current phase and its ticked checkboxes, counted as the plans view counts them), but only when the count moved since the last heartbeat; a lane that stays on one number says nothing, and you look for yourself. The plans are read only when a lane works:
 
 ```text
 armed: search=no agent board docs/plans/board-search/board.md
@@ -710,36 +720,70 @@ Three limits stand: the watcher cannot make a command read only, so name only co
 
 ##### Recipes
 
-Each recipe is one `watch.sources` entry; put in your key, project or query, then try it with `--dry-run` (and `--raw` where the shape differs from what is shown). A token never goes into an argument: an argument shows in the process list. Where a tool keeps its own login, it is used; where a token sits in an environment variable, a small script hands it to `curl` on stdin (`-H @-`), because the watcher passes `$VARIABLE` in an argument on as it is.
-
-**Jira with the Atlassian CLI.** Login: `acli jira auth login`, kept by `acli`. `acli jira workitem search` cannot return `updated` or `comment`, so a script searches for the keys and reads each one with `view`, a few at a time to stay well under the 30 seconds a source may run. It joins the text and mention nodes of the comment's document tree into plain text. The script, for example `scripts/sources/jira.sh`, with your project in the query and `<host>` your `<site>.atlassian.net`:
+Each recipe is one `watch.sources` entry; put in your key, project or query, then try it with `--dry-run` (and `--raw` where the shape differs from what is shown). A token never goes into an argument: an argument shows in the process list. Where a tool keeps its own login, it is used; where a token sits in an environment variable, a small TypeScript script run by Bun (which runs wherever `jh` does) puts it from `process.env` straight into the request header. A script fails with an exit code, never with an empty answer the watcher would take for a source with nothing new, and it prints neither the token nor the body of a failed answer. The closing `export {}` makes the file a module, so the type check accepts top-level `await` and the names do not clash between scripts. A recipe that needs no script (`gh …`, `curl` on a public page, `curl --netrc`) stays a direct command. The watcher starts a source without a shell and reads `bun` as the first word to mean the Bun that runs the watcher itself, so the entry needs no absolute path, which would differ from machine to machine, even when Bun is not on the `PATH` (installed in `~/.bun/bin` only, say).
+
+**Jira with the Atlassian CLI.** Login: `acli jira auth login`, kept by `acli`. `acli jira workitem search` cannot return `updated` or `comment`, so a script searches for the keys and reads each one with `view`, a few at a time to stay well under the 30 seconds a source may run. `plainText` joins the text and mention nodes of the comment's document tree into plain text; it is a pure function, so you can test it on its own. The script, for example `scripts/sources/jira.ts`, with your project in the query and `<host>` your `<site>.atlassian.net`:
+
+```ts
+// scripts/sources/jira.ts
+const jql = 'project = PROJ AND assignee = currentUser() AND statusCategory != Done'
+const host = '<host>'
+const parallel = 6
+
+type DocumentNode = { type?: string; text?: string; attrs?: { text?: string }; content?: DocumentNode[] }
+type IssueComment = { author?: { displayName?: string }; body?: DocumentNode }
+type Issue = { key: string; fields: { updated: string; summary: string; comment?: { comments: IssueComment[] } } }
+
+const plainText = (node: DocumentNode): string =>
+  node.type === 'text' || node.type === 'mention'
+    ? (node.text ?? node.attrs?.text ?? '')
+    : (node.content ?? []).map(plainText).join('')
+
+const acli = async (args: string[]): Promise<unknown> => {
+  const child = Bun.spawn(['acli', ...args], { stdout: 'pipe', stderr: 'ignore', signal: AbortSignal.timeout(20_000) })
+  const output = await new Response(child.stdout).text()
+  if ((await child.exited) !== 0) process.exit(1)
+  try {
+    return JSON.parse(output)
+  } catch {
+    return process.exit(1)
+  }
+}
 
-```bash
-#!/usr/bin/env bash
-set -euo pipefail
-jql='project = PROJ AND assignee = currentUser() AND statusCategory != Done'
-acli jira workitem search --jql "$jql" --limit 100 --json |
-  jq -r '.[].key' |
-  xargs -r -P 6 -I{} acli jira workitem view {} --fields summary,updated,comment --json |
-  jq -s 'map({
+const entryOf = ({ key, fields }: Issue) => {
+  const latest = fields.comment?.comments.at(-1)
+  return {
     key,
-    url: ("https://<host>/browse/" + .key),
-    updated: .fields.updated,
-    summary: .fields.summary,
-    author: (.fields.comment.comments[-1].author.displayName // null),
-    body: (.fields.comment.comments[-1].body
-      | if . == null then null
-        else [.. | objects | select(.type == "text" or .type == "mention") | (.text // .attrs.text)] | join("")
-        end)
-  })'
+    url: `https://${host}/browse/${key}`,
+    updated: fields.updated,
+    summary: fields.summary,
+    author: latest?.author?.displayName ?? null,
+    body: latest?.body ? plainText(latest.body) : null,
+  }
+}
+
+const keys = ((await acli(['jira', 'workitem', 'search', '--jql', jql, '--limit', '100', '--json'])) as { key: string }[]).map(
+  ({ key }) => key,
+)
+const entries = []
+for (let start = 0; start < keys.length; start += parallel) {
+  const batch = keys.slice(start, start + parallel)
+  const issues = await Promise.all(
+    batch.map((key) => acli(['jira', 'workitem', 'view', key, '--fields', 'summary,updated,comment', '--json'])),
+  )
+  entries.push(...(issues as Issue[]).map(entryOf))
+}
+console.log(JSON.stringify(entries))
+
+export {}
 ```
 
-`set -euo pipefail` is what makes a failed `acli` call arrive as an error: without it the pipe ends in an empty list, and the watcher would take a lost login for a source with nothing new.
+A failed `acli` call ends the script with exit code 1, which the watcher reports as a failing source; nothing is printed that it could take for an empty list.
 
 ```json
 {
   "name": "tickets-decisions",
-  "command": ["bash", "scripts/sources/jira.sh"],
+  "command": ["bun", "scripts/sources/jira.ts"],
   "map": {
     "id": ".key",
     "updatedAt": ".updated",
@@ -768,19 +812,34 @@ acli jira workitem search --jql "$jql" --limit 100 --json |
 }
 ```
 
-**Linear over GraphQL.** Token: a personal API key in `LINEAR_API_KEY`, sent as `Authorization: <key>` without `Bearer`. The script, for example `scripts/sources/linear.sh`, with `<host>` the API host `api.linear.app`:
+**Linear over GraphQL.** Token: a personal API key in `LINEAR_API_KEY`, sent as `Authorization: <key>` without `Bearer`. The script, for example `scripts/sources/linear.ts`, with `<host>` the API host `api.linear.app`. Linear answers a bad key or query with HTTP 200 and an `errors` list, so the script checks for it as well:
 
-```sh
-#!/bin/sh
-query='{"query":"{ issues(filter: { team: { key: { eq: \"ENG\" } }, number: { eq: 123 } }) { nodes { identifier title url updatedAt comments { nodes { body user { name } } } } } }"}'
-printf 'Authorization: %s\n' "$LINEAR_API_KEY" |
-  curl -fsS --max-time 20 -H @- -H 'Content-Type: application/json' --data "$query" "https://<host>/graphql"
+```ts
+// scripts/sources/linear.ts
+const token = process.env.LINEAR_API_KEY
+if (!token) process.exit(1)
+
+const query = `{ issues(filter: { team: { key: { eq: "ENG" } }, number: { eq: 123 } }) {
+  nodes { identifier title url updatedAt comments { nodes { body user { name } } } } } }`
+
+const response = await fetch('https://<host>/graphql', {
+  method: 'POST',
+  headers: { Authorization: token, 'Content-Type': 'application/json' },
+  body: JSON.stringify({ query }),
+  signal: AbortSignal.timeout(20_000),
+})
+if (!response.ok) process.exit(1)
+const answer = (await response.json()) as { errors?: unknown }
+if (answer.errors) process.exit(1)
+console.log(JSON.stringify(answer))
+
+export {}
 ```
 
 ```json
 {
   "name": "linear-eng-123",
-  "command": ["sh", "scripts/sources/linear.sh"],
+  "command": ["bun", "scripts/sources/linear.ts"],
   "items": ".data.issues.nodes",
   "map": {
     "id": ".identifier",
@@ -813,19 +872,28 @@ Check with `--raw` which end of `comments.nodes` holds the newest comment; `[0]`
 }
 ```
 
-**Sentry.** Token: an auth token with `event:read` in `SENTRY_AUTH_TOKEN`; `<host>` is `sentry.io` or your own. The script, for example `scripts/sources/sentry.sh`:
+**Sentry.** Token: an auth token with `event:read` in `SENTRY_AUTH_TOKEN`; `<host>` is `sentry.io` or your own. The script, for example `scripts/sources/sentry.ts`:
+
+```ts
+// scripts/sources/sentry.ts
+const token = process.env.SENTRY_AUTH_TOKEN
+if (!token) process.exit(1)
+
+const response = await fetch(
+  'https://<host>/api/0/projects/<org>/<project>/issues/?query=is:unresolved&statsPeriod=24h',
+  { headers: { Authorization: `Bearer ${token}` }, signal: AbortSignal.timeout(20_000) },
+)
+if (!response.ok) process.exit(1)
+console.log(JSON.stringify(await response.json()))
 
-```sh
-#!/bin/sh
-printf 'Authorization: Bearer %s\n' "$SENTRY_AUTH_TOKEN" |
-  curl -fsS --max-time 20 -H @- "https://<host>/api/0/projects/<org>/<project>/issues/?query=is:unresolved&statsPeriod=24h"
+export {}
 ```
 
 ```json
 {
   "name": "errors",
   "every": 10,
-  "command": ["sh", "scripts/sources/sentry.sh"],
+  "command": ["bun", "scripts/sources/sentry.ts"],
   "map": { "id": ".id", "updatedAt": ".lastSeen", "title": ".title", "url": ".permalink", "body": ".culprit" }
 }
 ```
@@ -887,6 +955,7 @@ The herdr plugin `zerodice0.worktree-bootstrap`, when enabled and configured in
 One block per lane of the chosen board, lanes that wait on you first:
 
 - the agent's state: `❓ blocked` (waits for you), `📨 done` (the agent finished its answer, not the lane), `⏸ idle`, `⚡ working`, or `·` no agent
+- which lanes are listed at all. A lane with an agent or an open pull request is drawn in full. A lane with a worktree but no agent is listed under `· no agent`. A lane without a worktree is listed under `· waiting`, with what it starts after, when a phase it names is still open in its plan or, if it names no plan, when its "starts after" cell says something other than "now" (`sofort`); otherwise it is finished and not shown. A lane whose name cell carries the cleaned-up mark (`abgeräumt`) is finished whatever its plan says. The board needs no extra column for this
 - how full the agent's context is, and a bar with the lane's ticked tasks
 - the branch, commits ahead and uncommitted files
 - the lane's open pull request with its checks
@@ -1077,6 +1146,7 @@ What usually stays to configure is what no file in the repository says, for exam
   - `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-UI3AZNZF.js → chunk-HQAONP4W.js}

@@ -35,6 +35,7 @@ var PLAN_VOCABULARY = {
     phase: "Phase",
     noReviewGate: "Kein Review-Gate",
     laneClosed: "abger\xE4umt",
+    startsNow: ["sofort"],
     phaseConnectors: ["danach", "und", "dann", "sowie"],
     statusWords: {
       done: { label: "Done", leading: ["done"], anywhere: ["abgeschlossen"] },
@@ -62,6 +63,7 @@ var PLAN_VOCABULARY = {
     phase: "Phase",
     noReviewGate: "No review gate",
     laneClosed: "cleaned up",
+    startsNow: ["now", "immediately"],
     phaseConnectors: ["then", "and", "after"],
     statusWords: {
       done: { label: "Done", leading: ["done"], anywhere: ["completed"] },

package/dist/config.d.ts

@@ -139,6 +139,12 @@ declare const jackherdConfigSchema: z.ZodObject<{
             approvalMinutes: z.ZodDefault<z.ZodNumber>;
         }, z.core.$strict>>;
     }, z.core.$strict>>;
+    merge: z.ZodPrefault<z.ZodObject<{
+        withoutChecks: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, 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-UI3AZNZF.js";
+} from "./chunk-HQAONP4W.js";
 
 // src/config/json-schema.ts
 import { z as z3 } from "zod";
@@ -299,6 +299,20 @@ var coordinatorSchema = z2.strictObject({
   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 checkFreePattern = z2.string().regex(/^[A-Za-z0-9_.*/-]+$/, "path words with * and ** only, such as docs/**/*.md").refine(
+  (pattern) => !pattern.startsWith("/") && !pattern.split("/").includes(".."),
+  "a relative path that stays inside the repository"
+).refine(
+  (pattern) => pattern.split("/").some((segment) => /^[A-Za-z0-9][A-Za-z0-9_.-]*$/.test(segment)),
+  "a pattern with a whole path segment that is no wildcard, such as docs/**/*.md"
+);
+var mergeSchema = z2.strictObject({
+  /**
+   * Paths of pull requests that are merged without waiting for checks: when every file of the pull request matches one
+   * of them, `/orchestrate` merges at once and the merge guard does not ask. Empty means every merge waits for checks.
+   */
+  withoutChecks: z2.array(checkFreePattern).default([])
+});
 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,
@@ -312,6 +326,10 @@ var guardSchema = z2.strictObject({
     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),
@@ -387,6 +405,10 @@ var jackherdConfigSchema = z2.strictObject({
   }).prefault({}),
   /** Read by the merge guard hook, which asks before the listed commands run, and by `/orchestrate`. */
   guard: guardSchema.prefault({}),
+  /** Read by `/orchestrate` and by the merge guard hook. */
+  merge: mergeSchema.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

@@ -55,6 +55,8 @@ type PlanVocabulary = {
     noReviewGate: string;
     /** Marks a lane as closed when its name cell contains it. */
     laneClosed: string;
+    /** Words a starts-after cell begins with when the lane may start at once. */
+    startsNow: readonly string[];
     /** Words that may stand between two phases of one entry (`P1 Rule und P2 Monitor`). */
     phaseConnectors: readonly string[];
     statusWords: Record<PlanStatus, StatusWord>;

package/dist/plan-format.js

@@ -8,7 +8,7 @@ import {
   isPlanLanguage,
   phaseHeading,
   sectionHeading
-} from "./chunk-UI3AZNZF.js";
+} from "./chunk-HQAONP4W.js";
 
 // src/plan-format/terminal-text.ts
 var UNSAFE_RANGES = [

package/herdr-plugin/herdr-plugin.toml

@@ -1,6 +1,6 @@
 id = "crossdelta.jackherd"
 name = "jackherd"
-version = "1.3.0"
+version = "1.5.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.3.0}"
+JACKHERD_VERSION="${JACKHERD_VERSION:-1.5.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/merge-guard/check-free.ts

@@ -0,0 +1,70 @@
+/**
+ * Whether a pull request changes nothing but files the project merges without waiting for checks
+ * (`merge.withoutChecks`). The file list comes from GitHub, never from an agent's text. Every doubt answers
+ * "no", so the guard asks as before.
+ */
+
+import { runGh } from './gh'
+import type { RepositoryFacts } from './pull-request'
+
+/** What GitHub lists per file: the name, and the old name of a renamed file. */
+const FILE_ENTRY_QUERY = '.[] | [.filename, .previous_filename] | @json'
+
+/** GitHub lists at most this many files of a pull request and says nothing when it stops there. */
+export const MAX_LISTED_FILES = 3000
+
+const isControlCharacter = (character: string): boolean => {
+  const code = character.charCodeAt(0)
+  return code < 0x20 || code === 0x7f
+}
+
+/** A repository path as GitHub lists it: relative, no empty, `.` or `..` segment, no backslash, no control character. */
+const isPlainPath = (file: string): boolean =>
+  file !== '' &&
+  !file.startsWith('/') &&
+  !file.includes('\\') &&
+  ![...file].some(isControlCharacter) &&
+  !file.split('/').some((segment) => segment === '' || segment === '.' || segment === '..')
+
+const isNameOrNull = (value: unknown): value is string | null => value === null || typeof value === 'string'
+
+/**
+ * The names a listing carries, the old name of a rename too, from one `[filename, previous]` JSON pair per line.
+ * The pairs must be exactly as many as the pull request changes files, and fewer than GitHub's cap: a list that
+ * was cut short would hide the files that are not in it. Anything else answers nothing.
+ */
+export const parseFileEntries = (stdout: string, changedFiles: number): string[] | undefined => {
+  if (changedFiles >= MAX_LISTED_FILES) return undefined
+  try {
+    const entries = stdout
+      .split('\n')
+      .filter((line) => line !== '')
+      .map((line): unknown => JSON.parse(line))
+    const pairs = entries.filter(
+      (entry): entry is [string, string | null] =>
+        Array.isArray(entry) && entry.length === 2 && typeof entry[0] === 'string' && isNameOrNull(entry[1]),
+    )
+    if (pairs.length !== entries.length || pairs.length !== changedFiles) return undefined
+    return pairs.flatMap(([filename, previous]) => (previous === null ? [filename] : [filename, previous]))
+  } catch {
+    return undefined
+  }
+}
+
+/** True only for at least one file, at least one pattern, and every file a plain path that matches a pattern. */
+export const allFilesMatch = (files: readonly string[], patterns: readonly string[]): boolean => {
+  if (files.length === 0 || patterns.length === 0) return false
+  const globs = patterns.map((pattern) => new Bun.Glob(pattern))
+  return files.every((file) => isPlainPath(file) && globs.some((glob) => glob.match(file)))
+}
+
+/**
+ * Asks `gh api` for the files of pull request <number> of `facts.repository`, named in full; any failure answers nothing.
+ */
+export const changedFilesOf = (pullRequest: number, directory: string, facts: RepositoryFacts): string[] | undefined => {
+  const listing = runGh(
+    ['api', `repos/${facts.repository}/pulls/${pullRequest}/files?per_page=100`, '--paginate', '--jq', FILE_ENTRY_QUERY],
+    directory,
+  )
+  return listing === undefined ? undefined : parseFileEntries(listing, facts.changedFiles)
+}

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

@@ -13,7 +13,8 @@ export type GuardPolicy = {
   /** The guarded commands as words: a program and the plain words after it, such as `gh pr merge`. */
   commands: readonly string[]
   /**
-   * Whether the user approved the merge of this pull request; asked only for a plain `gh pr merge <number>`.
+   * Whether the merge of this pull request may pass without a question: the user approved it, or every file of it
+   * matches `merge.withoutChecks`. Asked only for a plain `gh pr merge <number>`.
    * A throw counts as not approved.
    */
   isMergeApproved: (pullRequest: number) => boolean

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

@@ -0,0 +1,12 @@
+const LOOKUP_TIMEOUT_MS = 4000
+
+/** Runs `gh` with these arguments in `directory`, without a shell; stdout on success, nothing on any failure or timeout. */
+export const runGh = (args: readonly string[], directory: string): string | undefined => {
+  const result = Bun.spawnSync(['gh', ...args], {
+    cwd: directory,
+    timeout: LOOKUP_TIMEOUT_MS,
+    stdout: 'pipe',
+    stderr: 'ignore',
+  })
+  return result.exitCode === 0 ? result.stdout.toString() : undefined
+}