jackherd 1.3.0 → 1.4.0

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 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.

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` |
 
@@ -1077,6 +1077,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/config.d.ts

@@ -139,6 +139,9 @@ declare const jackherdConfigSchema: z.ZodObject<{
             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

@@ -312,6 +312,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 +391,8 @@ 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 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/herdr-plugin/herdr-plugin.toml

@@ -1,6 +1,6 @@
 id = "crossdelta.jackherd"
 name = "jackherd"
-version = "1.3.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.3.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.json

@@ -1,4 +1,12 @@
 {
+  "ask-hint": {
+    "event": "Stop",
+    "handler": {
+      "type": "command",
+      "command": "cd \"$CLAUDE_PROJECT_DIR\" && bun .claude/hooks/ask-hint/index.ts",
+      "timeout": 10
+    }
+  },
   "format-on-edit": {
     "event": "PostToolUse",
     "matcher": "Edit|Write",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jackherd",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "keywords": [
     "claude-code",
     "coding-agents",

package/schemas/jackherd.schema.json

@@ -486,6 +486,17 @@
       },
       "additionalProperties": false
     },
+    "hints": {
+      "default": {},
+      "type": "object",
+      "properties": {
+        "askUserQuestion": {
+          "default": true,
+          "type": "boolean"
+        }
+      },
+      "additionalProperties": false
+    },
     "check": {
       "type": "object",
       "properties": {

package/src/config/schema.ts

@@ -208,6 +208,11 @@ const guardSchema = z.strictObject({
     .prefault({}),
 })
 
+const hintsSchema = z.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: z.boolean().default(true),
+})
+
 const contextSchema = z
   .strictObject({
     /** Share of the context window from which a lane's fill shows yellow and `/implement` offers a new chat. */
@@ -302,6 +307,8 @@ export const jackherdConfigSchema = z.strictObject({
     .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(),
 })