@joshuafolkken/kit 1.872.0

package/scripts/rules/shell-body-trigger.ts

@@ -0,0 +1,204 @@
+// The `shell-body` row's trigger, in a module of its own rather than inside the enumeration
+// (joshuafolkken/kit#1198). Every other row's trigger is already shaped that way — `time_batch_guard`
+// and `cost_blocks` each hold their own reading of a call — and this one needs a small model of what
+// zsh does inside double quotes, which is more than an enumeration row should carry. The split also
+// gives that model a suite of its own, so a regex change is read beside the cases it has to keep.
+
+// A body handed to a command as an inline double-quoted argument, in the spellings a run reaches for:
+// `gh`'s field flags (`-f` / `-F` / `--field` / `--raw-field` with `body=`), `gh`'s own `--body`, and
+// `josh`'s `--body` and `--notify-message`. The value is captured so the decision can be made on what
+// the body actually contains rather than on the flag alone.
+//
+// **`-b` is deliberately absent.** It is `gh`'s short `--body`, but it is also `git checkout -b`, and
+// a branch name is not a body — covering it would refuse calls where nothing is wrong. The `*-file`
+// spellings end in `-` where this pattern needs whitespace or `=`, so `--body-file <path>` and
+// `--notify-message-file <path>` cannot match it.
+const FIELD_FLAGS = '(?:-f|-F|--field|--raw-field)'
+const MESSAGE_FLAGS = '(?:--body|--notify-message)'
+
+// **The opening quote sits on either side of `body=`, and both spellings are the same command.** zsh
+// strips the quotes before `gh` is started, so `-f body="… \`pnpm josh ms\` …"` and
+// `-f "body=… \`pnpm josh ms\` …"` hand `gh` one identical argument and execute one identical
+// backtick. A pattern that knew only the first fired on half of the calls it was written for.
+//
+// **They are two alternatives rather than one optional quote on each side.** An optional quote after
+// `body=` would also match `--field body=@$HOME/b.md`, capture the unquoted path up to some later
+// quote, find the `$` in it and refuse the very file form this rule asks callers to use.
+//
+// **The separator is `=` as readily as whitespace**, because `gh` accepts `--field=body="…"` for the
+// same reason `--body=…` works — which `MESSAGE_OPENING` below has always allowed. A pattern that
+// only knew the space stayed silent on a call that executes the backtick.
+const FIELD_OPENING = String.raw`${FIELD_FLAGS}[\s=]*(?:'?body="|"body=)`
+const MESSAGE_OPENING = String.raw`${MESSAGE_FLAGS}[\s=]+"`
+
+// One command substitution nested inside another — the `$(pwd)` of `$(cat "$(pwd)/x.md")`. One level
+// is every spelling a run composes; deeper nesting stops matching and is read as ordinary text.
+const NESTED_SUBSTITUTION = String.raw`\$\([^()]*\)`
+
+// A whole command substitution, the quotes inside it included. **It belongs to the value pattern and
+// not only to the exemption below**: `"` is legal inside `$( … )`, so a value that stopped at the
+// first one truncated `$(cat "$(pwd)/x.md")` to `$(cat `, found the `$` and refused a caller who was
+// already passing the body by path — spending the run's one delivery on a call that kept the rule.
+//
+// The branches are kept disjoint — `[^()$]` excludes the `$` the other two start with — so the match
+// is linear rather than a nested quantifier that backtracks.
+const SUBSTITUTION = String.raw`\$\((?:[^()$]|\$(?!\()|${NESTED_SUBSTITUTION})*\)`
+
+// The text between the opening quote and the closing one: ordinary characters, a backslash escape, a
+// lone `$`, or a whole substitution consumed in one piece so its inner quotes do not end the value.
+const QUOTED_VALUE = String.raw`(?:[^"\\$]|\\.|\$(?!\()|${SUBSTITUTION})*`
+
+const INLINE_BODY_VALUE = new RegExp(
+	`(?:${FIELD_OPENING}|${MESSAGE_OPENING})(${QUOTED_VALUE})"`,
+	'gu',
+)
+
+// **What zsh evaluates inside double quotes, measured in this harness rather than assumed**
+// (joshuafolkken/kit#1198): a backtick runs as command substitution and a `$` expands. `!` does
+// **not** — history expansion is off in a non-interactive zsh, and `"hello!world"` survives intact —
+// so it is deliberately absent: a rule that fired on every exclamation mark would be firing on turns
+// where nothing is wrong, which `prompts/collaboration-workflow/rule-delivery.md` names as worse than
+// no hook at all.
+const SHELL_EVALUATED = /[`$]/u
+
+// **The one exemption: a body that is *entirely* one command substitution.** `body="$(cat <path>)"`
+// is the rule already being kept — the substitution's output is not re-scanned by the shell, so a
+// body full of backticks reaches the command byte for byte, and refusing it would spend the run's one
+// delivery on a caller who had already moved the body into a file.
+//
+// **It is anchored to the whole value, not to the `$(` alone.** Excusing `$(` anywhere would let
+// `body="Result: run $(git log -1) to confirm"` through, and that one really is evaluated: the
+// substitution replaces the text and the command runs.
+const WHOLE_VALUE_SUBSTITUTION = new RegExp(`^${SUBSTITUTION}$`, 'u')
+
+// **A backtick inside the substitution voids the exemption.** The exemption's reason is that the
+// *output* is not re-scanned — but the substitution's own command is shell text, and a backtick in it
+// runs exactly as an inline one does. `body="$(echo \`date\`)"` executes `date`, which is the damage
+// joshuafolkken/kit#1198 was filed over, merely written one level in. A nested `$( … )` is the safe
+// spelling of the same composition and stays exempt.
+const BACKTICK = '`'
+
+// **The other spelling of "already in a file": `body=@<path>`.** The unquoted `--field body=@<path>`
+// never reaches the pattern at all, and `--field "body=@$HOME/body.md"` is that same call with the
+// quote moved one character left — so it is excused for the same reason, and by the same shape of
+// test as the substitution above: the *whole* value is the reference. A body that merely opens with
+// an `@mention` is not one, so it carries a space and still fires.
+const WHOLE_VALUE_FILE_REFERENCE = /^@\S+$/u
+
+// A backslash escape makes the next character literal inside double quotes, so `\$` and `` \` `` are
+// safe. They are dropped before the test rather than excluded from it, which is the same thing in one
+// pass and keeps `SHELL_EVALUATED` readable.
+const ESCAPED_PAIR = /\\./gu
+
+function is_whole_value_substitution(literal: string): boolean {
+	return WHOLE_VALUE_SUBSTITUTION.test(literal) && !literal.includes(BACKTICK)
+}
+
+function is_body_already_in_a_file(literal: string): boolean {
+	return WHOLE_VALUE_FILE_REFERENCE.test(literal) || is_whole_value_substitution(literal)
+}
+
+function is_evaluated_value(raw_value: string): boolean {
+	const literal = raw_value.replaceAll(ESCAPED_PAIR, '')
+
+	if (is_body_already_in_a_file(literal)) return false
+
+	return SHELL_EVALUATED.test(literal)
+}
+
+// **The trigger is the body's content, not the flag.** Every worked example in this repository's
+// prompts passes a placeholder (`-f body="<plan>"`), which is inert; the moment a real body carrying
+// a backtick is substituted in, the call becomes the one that executes text. Keying on the flag would
+// refuse the inert examples too — firing on turns where the rule is already being kept.
+function is_shell_evaluated_body(command: string): boolean {
+	for (const match of command.matchAll(INLINE_BODY_VALUE)) {
+		if (is_evaluated_value(match[1] ?? '')) return true
+	}
+
+	return false
+}
+
+// **The safe spellings, which is what keeping this rule looks like** (joshuafolkken/kit#1643). They
+// are the ones the refusal hands back: the `*-file` flags, a field whose value is a file reference,
+// and `$'…'` quoting. The `*-file` flags cannot reach `INLINE_BODY_VALUE` at all — the note at the top
+// of this file records why — so they are read straight off the command rather than out of a value.
+const FILE_FLAG = /(?:--body-file|--notify-message-file)(?:[\s=]|$)/u
+const FIELD_FILE_REFERENCE = new RegExp(String.raw`${FIELD_FLAGS}[\s=]*body=@\S`, 'u')
+// **`$'…'` is the other form the refusal sanctions**, because zsh expands neither a backtick nor a `$`
+// inside it. Only the **double**-quoted spans are blanked before it is read: blanking the single-quoted
+// span is exactly what would hide the form itself, while leaving the double-quoted ones would credit
+// `grep -rn "--body=$'" scripts/rules` — a run reading this repository — as one that passed a body.
+const ANSI_C_BODY = /(?:(?:--body|--notify-message)[\s=]+|body=)\$'/u
+const DOUBLE_QUOTED_SPAN = /"[^"]*"/gu
+
+// **Any spelling that hands a command a body, whatever the quoting.** The trigger above reads double
+// quotes alone, because those are the ones the shell evaluates; the occasion the rule governs is
+// wider, and leaving a `$'…'` or single-quoted body out of it would drop from the denominator exactly
+// the compliant runs this predicate was added to keep in it.
+const BODY_FLAG = new RegExp(
+	String.raw`${FIELD_FLAGS}[\s=]*'?"?body=|${MESSAGE_FLAGS}[\s=]|--body-file[\s=]|--notify-message-file[\s=]`,
+	'u',
+)
+
+// **A flag is only a flag outside the quotes**, the same reading `run-tail.ts` takes of a pull-request
+// title. This repository's own refusal text names `--body-file <path>`, so a `grep` or an `echo`
+// quoting it would otherwise be scored as a run that passed a body by path. The quoted spellings of
+// the same thing are not lost by blanking: `--field "body=@<path>"` is a whole-value file reference,
+// which the literal branch below reads.
+const QUOTED_SPAN = /"[^"]*"|'[^']*'/gu
+
+function inline_body_literals(command: string): Array<string> {
+	return Array.from(command.matchAll(INLINE_BODY_VALUE), (match) =>
+		(match[1] ?? '').replaceAll(ESCAPED_PAIR, ''),
+	)
+}
+
+function is_safe_body_form(command: string): boolean {
+	if (ANSI_C_BODY.test(command.replaceAll(DOUBLE_QUOTED_SPAN, ' '))) return true
+
+	const flags = command.replaceAll(QUOTED_SPAN, ' ')
+
+	if (FILE_FLAG.test(flags) || FIELD_FILE_REFERENCE.test(flags)) return true
+
+	return inline_body_literals(command).some((literal) => is_body_already_in_a_file(literal))
+}
+
+// **A call that passes its body safely and executes none inline.** The measurement asks a call whether
+// it kept the rule before it asks whether it broke it, so a call doing both would be credited for the
+// half it got right; requiring the absence of an evaluated body is what stops that.
+function keeps_body_safe(command: string): boolean {
+	return is_safe_body_form(command) && !is_shell_evaluated_body(command)
+}
+
+// **The occasion this rule governs: a body handed to a command at all**, in every spelling. It is the
+// denominator `rule-value.ts` reads, and it exists because this rule's trigger fires only on the
+// violation — a run that passed every body safely would otherwise never appear in the reading.
+function carries_a_body(command: string): boolean {
+	if (BODY_FLAG.test(command.replaceAll(QUOTED_SPAN, ' '))) return true
+
+	return inline_body_literals(command).length > 0
+}
+
+// The instruction in the shape a refusal can carry: what the shell is about to do, the safe
+// spellings, and the reissue sentence every delivery needs. The damage is named because it is the
+// half that reads as unbelievable — the substituted text is *executed*, not discarded. It lives here
+// beside its trigger rather than inline in the enumeration, the shape every newer row's reason takes
+// (`git-force.ts`, `lane-carry-conflict.ts`).
+const SHELL_BODY_REASON =
+	'⛔ shell-evaluated body: this command carries a body inline in double quotes, and that body ' +
+	'contains a backtick or a `$`, so the shell runs it — the text is executed rather than merely ' +
+	'mangled (joshuafolkken/kit#1198). Write the body to a file and pass it by path: `pnpm josh ' +
+	'issue:comment <N> --body-file <path>`, `pnpm josh followup --notify-message-file <path>`, or ' +
+	"`--body-file <path>` wherever offered. `$'…'` quoting is the other safe form; the rule and the " +
+	"trigger's blind spots are in `prompts/collaboration-workflow/shell-body.md`. Reissue this call " +
+	'once the body is in a file — it fires once per run and cannot repeat on the call in hand.'
+
+const shell_body_trigger = {
+	SHELL_BODY_REASON,
+	carries_a_body,
+	is_safe_body_form,
+	is_shell_evaluated_body,
+	keeps_body_safe,
+}
+
+export { shell_body_trigger }

package/scripts/rules/shell-segments.ts

@@ -0,0 +1,45 @@
+import { time_shell } from '#scripts/time-runtime/time-shell'
+
+// **A shell line carries several commands, and each has to be judged on its own.** Every trigger in
+// this directory that reads a command string needs the same cut, so the cut lives here rather than
+// beside whichever trigger needed it first — the clone `CLAUDE.md` prohibits is two copies of a
+// pattern that would then have to be corrected twice.
+//
+// **A bare `|` is deliberately not a separator.** It appears inside a `--jq` filter far more often
+// than between two commands, and cutting there would split one call into fragments neither of which
+// is command-shaped. The rule that *is* about a pipe reads the whole line instead
+// (`piped-verification.ts`).
+//
+// **`early-heartbeat.ts` keeps its own separator on purpose** and is not a caller here: it adds `&`,
+// because `sleep 1200 &` is an armed timer sent to the background and has to be seen as one. That is
+// a different question about a different character, not a second copy of this answer.
+const SEGMENT_SEPARATOR = /&&|\|\||;|\n/u
+
+/** The line's commands, trimmed. Empty segments are kept: a caller anchoring at `^` rejects them. */
+function segments_of(command: string): Array<string> {
+	return command.split(SEGMENT_SEPARATOR).map((segment) => segment.trim())
+}
+
+// **Both spellings still match, and the expansion is no longer this file's** (joshuafolkken/kit#1643
+// for the reading, joshuafolkken/kit#1789 for where it now happens). A `josh_names` here used to widen
+// each caller's set with every alias standing for one of its names; `josh_command_of` expands the
+// alias in the command it reads, so `pnpm josh ga` arrives as `josh gate` and a caller's canonical set
+// matches it as it is. Widening as well would be a second copy of one rule, and the caller that
+// forgot it would be the one that stops seeing `pnpm josh ga` at all — which is why each caller's own
+// suite names a call in its alias spelling.
+/** Whether this segment invokes one of the named josh subcommands, in either spelling. */
+function is_josh_command(segment: string, names: ReadonlySet<string>): boolean {
+	const named = time_shell.josh_command_of(segment)
+
+	if (!named.startsWith(time_shell.JOSH_PREFIX)) return false
+
+	return names.has(named.slice(time_shell.JOSH_PREFIX.length))
+}
+
+const shell_segments = {
+	SEGMENT_SEPARATOR,
+	is_josh_command,
+	segments_of,
+}
+
+export { shell_segments }

package/scripts/rules/stop-rules.ts

@@ -0,0 +1,329 @@
+import { hook_decision } from '#scripts/josh/hook-decision'
+import { z } from 'zod'
+import { filing_offer } from './filing-offer'
+import { issue_citation } from './issue-citation'
+import { reply_language } from './reply-language'
+
+// The stop-time rules, delivered on the `Stop` hook (joshuafolkken/kit#2121, joshuafolkken/kit#2422,
+// joshuafolkken/kit#2445).
+//
+// **It exists because `.claude/settings.json` wired no `Stop` event.** The four events it did wire
+// (`SessionStart` / `UserPromptSubmit` / `PreToolUse` / `PostToolUse`) can catch the moment a call is
+// about to run, but not the moment a run *stops* or *reports* — so three rules whose inputs are all
+// mechanically readable could not be enforced structurally (`prompts/collaboration-workflow/rule-delivery.md`).
+//
+// **No second decision engine.** This loads on the same `hook_decision` foundation the PreToolUse
+// guards share — the `.env` load and the switch — and reuses `lane-park`'s stop-notification judgement
+// and `run:hold`'s record read rather than re-deriving either. What differs is only the event: a
+// `Stop` payload has no tool call, and it blocks with `{"decision":"block"}` rather than a PreToolUse
+// permission envelope. The stop guard is a second *entry* on the one foundation, exactly as
+// `pretool-guard` is one — not a second copy of the plumbing.
+//
+// **Every rule refuses** (joshuafolkken/kit#2247). Missing the stop notification or leaving a hold
+// on a clean tree costs a person a silent wait or a trampled tree; a bare `#N` in the reply reaches
+// the person watching but not the model that could fix it, so it too blocks — `{"decision":"block"}`
+// is the one channel a `Stop` hook has to the model, and `stop_hook_active` caps a false positive at a
+// single wasted turn. The detection is tightened to match (`issue-citation.ts`, `filing-offer.ts`).
+
+const SWITCH_ENV_KEY = 'JOSH_STOP_GUARD'
+const BLOCK_DECISION = 'block'
+
+// Only the fields the stop rules read. `last_assistant_message` is the turn's session-facing text —
+// Claude Code hands it directly so the transcript's async lag is never in the citation path.
+const stop_payload_schema = z.object({
+	transcript_path: z.string().min(1),
+	stop_hook_active: z.boolean().nullish(),
+	last_assistant_message: z.string().nullish(),
+})
+
+type StopPayload = z.infer<typeof stop_payload_schema>
+
+// What one stop looks like to the rules, computed once by the CLI from the payload and the world.
+interface StopContext {
+	// The `run:hold` record for this working tree is still in place (`held` or `stale`).
+	hold_present: boolean
+	// `git status --porcelain` came back empty.
+	tree_clean: boolean
+	// A `confirmation` notify is on this run's transcript tail.
+	notified: boolean
+	// The turn's session-facing reply text.
+	message: string
+	// This stop already forced a continuation earlier in the prompt — the loop-breaker Claude Code
+	// documents, so a run that will not comply is not blocked forever.
+	stop_hook_active: boolean
+	// A pre-gate cut record is in place for this work tree. A dispatched lane child ends its turn at
+	// the cut holding the tree by design and hands off to a fresh process (`pre-gate-cut.md`), so that
+	// turn-end is an automatic continuation, not the person-waiting pause the block rules are for.
+	cut_pending: boolean
+	// An Issue filing no guard refused is on this run's transcript tail — `filing_cap`'s count.
+	filed: boolean
+	// The owner of the repository the session runs in, or `undefined` when it cannot be read.
+	session_owner: string | undefined
+	// This session is a headless `backlogrun` parent with lanes still in flight and no cut handed its
+	// record off — `run-headless.ts` → `must_keep_waiting` (joshuafolkken/kit#2437).
+	headless_waiting: boolean
+	// How many headless-wait refusals sit on this run's transcript tail — the spin bound below.
+	headless_refusals: number
+	// This session is a dispatched lane child for this checkout — `lane_child_marker.is_child_of`.
+	lane_child: boolean
+	// The resolved `JOSH_SESSION_LANG` — `session_language.resolve_session_lang` (joshuafolkken/kit#2470).
+	session_lang: string
+}
+
+interface StopOutcome {
+	reason: string | undefined
+}
+
+const NO_OUTCOME: StopOutcome = { reason: undefined }
+
+// **A mid-workflow stop is announced off-screen before it happens.** `CLAUDE.md` → "Mid-workflow stop
+// notification" requires the `confirmation` Telegram before any pause; the hold is what says a run is
+// mid-workflow, and the transcript is what says the notify was sent.
+const STOP_NOTIFY_REASON =
+	'⛔ mid-workflow stop notification: this working tree is still held by a run and no `confirmation` ' +
+	'Telegram was sent this turn, so a person is being left to wait off-screen without knowing the run ' +
+	'paused. `CLAUDE.md` → "Mid-workflow stop notification" requires ' +
+	'`pnpm josh notify --task-type confirmation --issue-url "<url>" --body=$\'<reason>\'` before any ' +
+	'mid-workflow pause. Send it, then end with a one-line confirmation that it was sent — do not repeat ' +
+	'your previous reply. This fires only while the hold is held and no notify is on the transcript, and ' +
+	'`stop_hook_active` lets a second stop through so a run is never wedged.'
+
+// **A clean tree that still holds is a tree the next run will trample.** `SKILL.md` → §2f: a stop that
+// leaves the tree clean releases the hold; a `halfrun` pre-commit stop and a `needs-human-review` stop
+// keep it because their tree is dirty, which is why this row is silent whenever the tree is not clean.
+const HOLD_RELEASE_REASON =
+	'⛔ working-tree hold not released: this working tree is clean but its `run:hold` record is still in ' +
+	'place, so the next run here runs `git switch main && git pull` believing the tree is free while ' +
+	'you hold it. `.claude/skills/workflow-commands/SKILL.md` → §2f: a stop that leaves the tree clean ' +
+	'releases the hold with `pnpm josh run:release <N>` (bare for a `new` entry). A `halfrun` ' +
+	'pre-commit stop and a `needs-human-review` stop keep the hold because their tree is dirty — this ' +
+	'row is silent there. Release it, then end with a one-line confirmation that it was released — do ' +
+	'not repeat your previous reply.'
+
+// **A refusal that corrects rather than advises** (joshuafolkken/kit#2247). The bare `#N` is already
+// on screen and the hook cannot unsay it, so the reason does the one thing that helps the *next* reply:
+// it names the numbers it detected and hands over the exact `issue:cite` call that prints the
+// paste-ready lines, then asks for the corrected citation lines alone — not the whole reply reissued
+// (joshuafolkken/kit#2329). Reprinting the whole reply is what made the correction read as a duplicate;
+// the bare copy already scrolled past stays, and the fix follows it as a short correction. The rule
+// itself is not restated — it is resident in `CLAUDE.md` — only pointed at.
+const ISSUE_CITATION_REASON =
+	'Session-facing output cites an Issue as a number-link so the reader can click through and see ' +
+	'which repository it is (`CLAUDE.md`, `prompts/collaboration-workflow/issue-citation.md`).'
+
+function build_citation_reason(references: ReadonlyArray<string>): string {
+	const numbers = references.join(', ')
+	const command = `pnpm josh issue:cite ${issue_citation.cite_arguments(references).join(' ')}`
+
+	return (
+		`⛔ issue citation: your reply names an Issue as a bare \`#N\` (${numbers}). Run \`${command}\` ` +
+		`to print the paste-ready citation lines, then print the corrected citation lines alone — do not ` +
+		`repeat your previous reply. ${ISSUE_CITATION_REASON}`
+	)
+}
+
+// **An offer to file is a Tier A filing deferred to the user** (joshuafolkken/kit#2422). The judgement
+// is already made, so the reason hands over the filing chain rather than a question; the rule itself
+// is resident in `SKILL.md` → §2i and only pointed at.
+const FILING_OFFER_REASON =
+	'⛔ filing offer: your reply offers to file an Issue instead of filing it. Filing into a ' +
+	'first-party repository is Tier A — the trigger is the judgement that it is worth filing, not the ' +
+	"run's progress (`.claude/skills/workflow-commands/SKILL.md` → §2i, `observation-filing.md`). Run " +
+	'`pnpm josh issue:scout "<title>"`, file it, run `pnpm josh epic:bundle <new>`, then end with the ' +
+	'one-line citation of what was filed — do not repeat your previous reply. If it is not worth filing ' +
+	'after all, say so in one line instead.'
+
+// **A headless parent's turn-end is its process's end** (joshuafolkken/kit#2437). Under `claude -p` the
+// background waits die with the turn, so the lanes lose their parent and nothing re-invokes it. The
+// reason hands over the foreground wait rather than a question, because there is nobody to answer one.
+// The refusal's opening, which the transcript tail is counted by.
+const HEADLESS_WAIT_MARKER = '⛔ headless parent:'
+
+// Refusals with no foreground wait between them before the loop-breaker is honoured again. A parent
+// that obeys runs a wait after each refusal, which resets the count; one that only re-stops piles them
+// up. The bound lets that one end when "in flight" is a kept lane no child is working in
+// (`backlogrun-park.md`), rather than spinning until the carry record expires.
+const HEADLESS_REFUSAL_CAP = 3
+
+// The foreground waits as they appear in a transcript's tool-call input — the JSON `command` field, so
+// the refusal's own prose, which names the same commands, never matches.
+const HEADLESS_WAIT_CALLS = ['"command":"pnpm josh lane:await', '"command":"pnpm josh run:progress']
+
+const HEADLESS_WAIT_BODY =
+	' this is a `claude -p` `backlogrun` parent (`JOSH_RUN_HEADLESS`) with lanes still ' +
+	'in flight, and ending this turn ends the process — its background waits are killed with it and the ' +
+	'lanes are left without a parent. Wait in the foreground instead: run `pnpm josh lane:await <N...>` ' +
+	'for the in-flight lanes (and `pnpm josh run:progress --wait` for the heartbeat) as foreground ' +
+	'commands within the tool timeout, act on what they report, and continue the loop. End the turn only ' +
+	'after `pnpm josh run:carry --cut` or `--end` (`backlogrun-progress.md` → "The parent keeps no clock ' +
+	'of its own").'
+
+const HEADLESS_WAIT_REASON = `${HEADLESS_WAIT_MARKER}${HEADLESS_WAIT_BODY}`
+
+// **A lane child never asks a person for the index** (joshuafolkken/kit#2445). The index rule protects
+// a person's own staging, and a lane is a per-run work tree with none to protect; the sanctioned commit
+// flow is already authorized, so the reason hands it over instead of letting the run wait on a person.
+// Both halves must appear — an index command and a request for permission — so a report that merely
+// names `git add` is not refused.
+const INDEX_COMMAND_PATTERN = /git (?:add|stage|rm --cached|restore --staged|restore -S)\b/u
+const PERMISSION_PATTERN = /許可|承認|permission|approve|approval|authorization/iu
+
+const LANE_INDEX_REASON =
+	'⛔ lane index permission: this is a dispatched lane child (`JOSH_LANE_CHILD`) and your reply asks ' +
+	"a person for permission to change the git index. A lane is a per-run work tree with no person's " +
+	'staging to protect, and the sanctioned commit flow is already authorized: remove any conflict ' +
+	'markers, then run `pnpm josh git -y`, which stages and commits them — a conflicted merge included. ' +
+	'This is Tier A (`.claude/skills/workflow-commands/chain-rule.md` → "origin/main is merged in before ' +
+	'the gate"). Do it and continue the run — do not repeat your previous reply.'
+
+function asks_index_permission(message: string): boolean {
+	return INDEX_COMMAND_PATTERN.test(message) && PERMISSION_PATTERN.test(message)
+}
+
+function needs_index_route(context: StopContext): boolean {
+	return context.lane_child && asks_index_permission(context.message)
+}
+
+// **A refusal is the turn's only input, so it names the language the answer is written in**
+// (joshuafolkken/kit#2470). The session-language line reaches a turn only through `UserPromptSubmit`;
+// a turn this hook continues has no prompt, and an English refusal read alone was answered in English.
+function language_note(lang: string): string {
+	return (
+		`Write your reply in the session language (JOSH_SESSION_LANG: ${lang}); code, commands and ` +
+		'identifiers stay as they are.'
+	)
+}
+
+// **A reply that drifted out of the session language is sent back once to be rewritten**
+// (joshuafolkken/kit#2470). The drift persists — each turn matches the language of the one before — so
+// the rewrite has to happen on the turn it starts; `stop_hook_active` bounds it to one.
+function build_language_reason(lang: string): string {
+	return (
+		`⛔ session language: your reply is not written in the session language (JOSH_SESSION_LANG: ` +
+		`${lang}). Rewrite it in that language and keep writing in it on the turns that follow, whatever ` +
+		'language a notification, tool output or hook message was in (`CLAUDE.md` → "Output language").'
+	)
+}
+
+function language_reason(context: StopContext): string | undefined {
+	if (!reply_language.is_mismatch(context.message, context.session_lang)) return undefined
+
+	return build_language_reason(context.session_lang)
+}
+
+function needs_filing(context: StopContext): boolean {
+	if (context.filed || !filing_offer.offers_filing(context.message)) return false
+
+	return filing_offer.is_first_party_target(context.message, context.session_owner)
+}
+
+function needs_notify(context: StopContext): boolean {
+	return context.hold_present && !context.notified
+}
+
+function needs_release(context: StopContext): boolean {
+	return context.hold_present && context.tree_clean
+}
+
+function citation_reason(message: string): string | undefined {
+	const references = issue_citation.bare_references(message)
+	if (references.length === 0) return undefined
+
+	return build_citation_reason(references)
+}
+
+// The three rules that read the reply itself, filing offer first and the language last. A drifted reply
+// refused for another reason is not rewritten, but the drift still ends: `block_envelope` appends the
+// session-language note to every refusal, so the turn it continues is written in the session language.
+function reply_reason(context: StopContext): string | undefined {
+	if (needs_filing(context)) return FILING_OFFER_REASON
+
+	return citation_reason(context.message) ?? language_reason(context)
+}
+
+// The headless wait holds past the loop-breaker until the spin bound is reached.
+function is_headless_held(context: StopContext): boolean {
+	if (!context.headless_waiting) return false
+
+	return !context.stop_hook_active || context.headless_refusals < HEADLESS_REFUSAL_CAP
+}
+
+// The headless-wait refusals on a transcript tail since the last foreground wait the parent ran — a
+// wait is progress, so only refusals with none between them count toward the spin bound.
+function count_headless_refusals(tail: string): number {
+	const last_wait = Math.max(...HEADLESS_WAIT_CALLS.map((call) => tail.lastIndexOf(call)))
+
+	return tail.slice(Math.max(last_wait, 0)).split(HEADLESS_WAIT_MARKER).length - 1
+}
+
+// The two hold rules, notify ahead of release — behind the lane index route (joshuafolkken/kit#2445),
+// since the notify they would ask for announces a pause the run has no reason to take.
+function hold_reason(context: StopContext): string | undefined {
+	if (needs_index_route(context)) return LANE_INDEX_REASON
+	if (needs_notify(context)) return STOP_NOTIFY_REASON
+	if (needs_release(context)) return HOLD_RELEASE_REASON
+
+	return undefined
+}
+
+// First-wins across every rule. Two things stand every rule down: `stop_hook_active` (the
+// loop-breaker, so a run that already got one continuation this prompt may stop) and a pre-gate cut in
+// flight (a lane child's automatic turn-end, not a person-waiting pause). The two hold rules keep their
+// order ahead of the reply rules, so a stop that both still owes its notify and holds a bare `#N` still
+// reports the notify first; the filing offer goes ahead of the citation, since the filing it forces
+// produces the citation the reply then needs.
+//
+// **The headless wait comes first and outlasts `stop_hook_active` up to its spin bound** (joshuafolkken/kit#2437).
+// The loop-breaker exists so a person is not wedged behind a rule the run will not satisfy; a headless
+// parent has no person, and letting its second stop through is exactly the silent end the rule is for.
+// Each continuation it forces is a foreground wait of minutes, and the rule falls silent by itself once
+// the lanes finish or a cut hands the record off; refusals with no wait between them are bounded.
+function block_reason(context: StopContext): string | undefined {
+	if (is_headless_held(context)) return HEADLESS_WAIT_REASON
+	if (context.stop_hook_active || context.cut_pending) return undefined
+
+	return hold_reason(context) ?? reply_reason(context)
+}
+
+function stop_outcome(context: StopContext): StopOutcome {
+	return { reason: block_reason(context) }
+}
+
+// The documented shape a `Stop` hook blocks with: `reason` is fed back to Claude, which then continues
+// instead of stopping. Plain stdout is not it — only this envelope holds the stop. Every reason leaves
+// with the session-language note, so no rule can hand the model an English-only turn.
+function block_envelope(reason: string, lang: string): string {
+	return JSON.stringify({ decision: BLOCK_DECISION, reason: `${reason} ${language_note(lang)}` })
+}
+
+function parse_stop_payload(raw_payload: string): StopPayload | undefined {
+	const parsed = stop_payload_schema.safeParse(JSON.parse(raw_payload))
+
+	return parsed.success ? parsed.data : undefined
+}
+
+function is_enabled(): boolean {
+	return hook_decision.is_switch_enabled(SWITCH_ENV_KEY)
+}
+
+const stop_rules = {
+	FILING_OFFER_REASON,
+	HEADLESS_REFUSAL_CAP,
+	HEADLESS_WAIT_REASON,
+	HOLD_RELEASE_REASON,
+	ISSUE_CITATION_REASON,
+	LANE_INDEX_REASON,
+	NO_OUTCOME,
+	STOP_NOTIFY_REASON,
+	SWITCH_ENV_KEY,
+	block_envelope,
+	block_reason,
+	build_language_reason,
+	count_headless_refusals,
+	is_enabled,
+	parse_stop_payload,
+	stop_outcome,
+}
+
+export type { StopContext, StopOutcome }
+export { stop_rules }

package/scripts/rules/tail-commands.ts

@@ -0,0 +1,35 @@
+import { cost_blocks } from '#scripts/cost-runtime/cost-blocks'
+import { time_shell } from '#scripts/time-runtime/time-shell'
+import { time_transcript_line, type Block } from '#scripts/time-runtime/time-transcript-line'
+
+// The `Bash` commands a run's transcript tail already issued, parsed once here rather than in each
+// rule that needs them (joshuafolkken/kit#2119). `prior-comment-read.ts` had this reading first; the
+// scout gate needs the same "what did the run already run" question, so a second copy would be the
+// clone `CLAUDE.md` prohibits. The delivery path sees only the raw tail — `delivered-rules.ts` names
+// the reason a run's own calls are not handed to it — so the earlier calls are recovered by parsing
+// that tail the same way `time-batch-guard.ts` does.
+
+// A `tool_use` block that ran a shell command.
+function is_bash_use(block: Block): boolean {
+	return block.type === cost_blocks.TOOL_USE_TYPE && block.name === cost_blocks.BASH_TOOL
+}
+
+// The Bash commands one transcript line issued, empty for a line that parses to none.
+function bash_commands_of(line: string): ReadonlyArray<string> {
+	const parsed = time_transcript_line.parse_line(line)
+
+	if (parsed === undefined) return []
+
+	return parsed.blocks
+		.filter((block) => is_bash_use(block))
+		.map((block) => time_shell.bash_command(block.input))
+}
+
+// Every Bash command the tail holds, in the order they were issued.
+function prior_bash_commands(tail: string): ReadonlyArray<string> {
+	return tail.split('\n').flatMap((line) => bash_commands_of(line))
+}
+
+const tail_commands = { bash_commands_of, is_bash_use, prior_bash_commands }
+
+export { tail_commands }