@joshuafolkken/kit 1.1471.0 → 1.1514.0

package/scripts/hooks/pretool-guard.ts

@@ -3,11 +3,11 @@ import { investigation_outcome } from '#scripts/delegation/investigation-guard'
 import { issue_watch_hook } from '#scripts/issue/issue-watch-hook'
 import { hook_decision, type GuardOutcome } from '#scripts/josh/hook-decision'
 import { lane_phase } from '#scripts/lane/lane-phase'
-import { json_value } from '#scripts/lib/json-value'
 import { delivered_rules } from '#scripts/rules/delivered-rules'
 import { lane_background } from '#scripts/rules/lane-background'
-import { piped_verification } from '#scripts/rules/piped-verification'
+import { rule_rewrite, type RuleRewrite } from '#scripts/rules/rule-rewrite'
 import { run_parent_cut_hook } from '#scripts/run/run-parent-cut-hook'
+import { run_poll_hook } from '#scripts/run/run-poll-hook'
 import { run_watcher_hook } from '#scripts/run/run-watcher-hook'
 import type { GuardedCall } from '#scripts/time-runtime/time-batch-guard'
 import { batch_outcome } from './batch-guard'
@@ -22,11 +22,12 @@ import { step_zero_notice } from './step-zero-notice'
 //
 // **The verdict is identical to running the three in turn**, and that is the whole point. Each guard
 // self-gates on the tool name inside its own `is_candidate` / trigger, so running all three on the
-// union matcher (`Bash|Edit|Read|Write|AskUserQuestion`) refuses exactly what the three separate
-// entries did — `AskUserQuestion` is matched for the rule guard's lane-child interactive-ask row,
-// and the batching and investigation guards self-gate away from it. A
-// refusal from any guard wins first; only when none refuses is a guard's non-blocking notice or fault
-// (the whole-file-write notice, a lane child's investigation notice) emitted. Each guard still honours its own
+// union matcher (`Bash|Edit|Read|Write|AskUserQuestion|Agent|Task`) refuses exactly what the three
+// separate entries did — `AskUserQuestion` is matched for the rule guard's lane-child interactive-ask
+// row and `Agent|Task` for its `agent-model` row, and the batching and investigation guards self-gate
+// away from both. A refusal from any guard wins first; only when none refuses is a guard's non-blocking
+// notice or fault (the whole-file-write notice, a lane child's duplicate-read notice) emitted. Each
+// guard still honours its own
 // switch (`JOSH_BATCH_GUARD` / `JOSH_INVESTIGATION_GUARD` / `JOSH_RULE_GUARD`) internally, so this
 // process needs no switch of its own.
 
@@ -96,12 +97,14 @@ async function mark_phase(outcome: GuardOutcome): Promise<void> {
 // **The parent hand-off guard is the second asynchronous rule, asked after the watcher's**.
 // It reads the carry record to tell the `backlogrun` parent apart, so it sits
 // beside the watcher rather than among the synchronous rows; a stale watcher is the cheaper fix and is
-// surfaced first.
+// surfaced first. **The poll guard is third**: it reads the same carry record, and only for a call that
+// repeats a state read, so the hand-off still wins over it.
 async function async_reason(raw_payload: string): Promise<string | undefined> {
 	const watcher = await run_watcher_hook.watcher_hook_reason(raw_payload)
 	const cut = watcher ?? (await run_parent_cut_hook.parent_cut_reason(raw_payload))
+	const poll = cut ?? (await run_poll_hook.safe_poll_reason(raw_payload))
 
-	return cut ?? (await issue_watch_hook.watch_reason())
+	return poll ?? (await issue_watch_hook.watch_reason())
 }
 
 async function pretool_outcome_async(raw_payload: string): Promise<GuardOutcome> {
@@ -159,59 +162,32 @@ function foreground_rewrite(
 	)
 }
 
-interface PipefailRewrite {
-	payload: string
-	input: Record<string, unknown>
-}
-
-// A piped josh check the hook runs under `set -o pipefail` instead of refusing it:
-// the rewritten input, and the payload that carries it. The rewrite is the
-// rule guard's delivery, so the rule guard's switch turns it off too.
-function pipefail_rewrite(raw_payload: string): PipefailRewrite | undefined {
-	if (!delivered_rules.is_enabled()) return undefined
-
-	const call = guarded_call(raw_payload)
-	const input = call === undefined ? undefined : piped_verification.pipefail_input(call)
-	const payload = json_value.parse_or_undefined(raw_payload)
-
-	if (input === undefined || !json_value.is_record(payload)) return undefined
-
-	return { payload: JSON.stringify({ ...payload, tool_input: input }), input }
-}
-
-function pipefail_envelope(
+// The rows' rewrite carries no permission decision: whatever else the line runs meets its own prompt.
+function rule_envelope(
 	outcome: GuardOutcome,
-	input: Record<string, unknown> | undefined,
+	rewrite: RuleRewrite | undefined,
 ): string | undefined {
-	if (input === undefined || outcome.reason !== undefined) return undefined
+	if (rewrite === undefined || outcome.reason !== undefined) return undefined
 
-	return hook_decision.flow_rewrite_envelope(
-		input,
-		rewrite_context(piped_verification.PIPEFAIL_NOTE, outcome),
-	)
+	return hook_decision.flow_rewrite_envelope(rewrite.input, rewrite_context(rewrite.note, outcome))
 }
 
 // The hook's one write: a rewrite where one applies, the outcome's own envelope otherwise.
-function emit(
-	raw_payload: string,
-	outcome: GuardOutcome,
-	pipefail_input?: Record<string, unknown>,
-): void {
-	const rewrite =
-		pipefail_envelope(outcome, pipefail_input) ?? foreground_rewrite(outcome, raw_payload)
+function emit(raw_payload: string, outcome: GuardOutcome, rewrite?: RuleRewrite): void {
+	const envelope = rule_envelope(outcome, rewrite) ?? foreground_rewrite(outcome, raw_payload)
 
-	if (rewrite === undefined) hook_decision.emit_outcome(outcome)
-	else process.stdout.write(`${rewrite}\n`)
+	if (envelope === undefined) hook_decision.emit_outcome(outcome)
+	else process.stdout.write(`${envelope}\n`)
 }
 
-// **The guards judge the call that will run.** A rewritable piped check reaches every guard already
-// prefixed, so the piped-verification row stays quiet on it while any other guard's refusal still wins
-// over the rewrite. The Codex adapter cannot rewrite a call, so it goes on judging the call as typed.
+// **The guards judge the call that will run.** A rewritten call reaches every guard already made
+// right, so the rewriting row stays quiet on it while any other guard's refusal still wins over the
+// rewrite. The Codex adapter cannot rewrite a call, so it goes on judging the call as typed.
 async function respond(raw_payload: string): Promise<void> {
-	const pipefail = pipefail_rewrite(raw_payload)
-	const judged = pipefail?.payload ?? raw_payload
+	const rewrite = rule_rewrite.rewrite(raw_payload)
+	const judged = rewrite?.payload ?? raw_payload
 
-	emit(judged, await pretool_outcome_async(judged), pipefail?.input)
+	emit(judged, await pretool_outcome_async(judged), rewrite)
 }
 
 const pretool_guard = {
@@ -219,7 +195,6 @@ const pretool_guard = {
 	emit,
 	foreground_rewrite,
 	mark_phase,
-	pipefail_rewrite,
 	pretool_outcome,
 	respond,
 }

package/scripts/hooks/reserved-run.ts

@@ -78,6 +78,7 @@ async function run_reserved(argv: ReadonlyArray<string>): Promise<number> {
 	return await core_budget.with_core_reservation(
 		parsed.weight,
 		async () => await run_command(parsed.command),
+		{ command: parsed.command.join(' ') },
 	)
 }
 

package/scripts/hooks/run-hook.sh

@@ -5,9 +5,8 @@
 # A hook command in `.claude/settings.json` / `.codex/hooks.json` only moves to the project root
 # (`scripts/init/hook-launch.ts`) and calls this script, so everything every hook shares lives here once:
 #
-# - The git location variables a git hook exports are cleared when the root resolves without them, so
-#   the hook's own git calls act on the checkout it stands in. They are kept when the checkout needs
-#   them — git metadata outside the work tree.
+# - The root prefix has already cleared the git location variables a git hook exports, or kept them
+#   when the checkout needs them; this script starts no `git` of its own (joshuafolkken/kit#3946).
 # - The pre-built bundle `dist/hooks/<name>.js` runs once its gate passes; otherwise the live source
 #   runs through josh, whose command is the name with its first `-` turned into `:`
 #   (`pretool-guard` → `pretool:guard`).
@@ -16,27 +15,26 @@
 #   starts node once (joshuafolkken/kit#3327). In an installed package it is a presence check: the
 #   published bundles cannot be stale against a source the consumer never edits, and Node strips no
 #   types under `node_modules`.
+# - Nothing is spawned that the shell can do itself: the directory is a parameter expansion rather than
+#   `dirname`, and `node` replaces this shell through `exec` rather than running beside it.
 # - An `if`/`else`, never `&&`/`||`: a guard's refusal is a non-zero exit, and a chain would read it as
 #   a missing bundle and run the hook twice.
 
-location_variables='GIT_ALTERNATE_OBJECT_DIRECTORIES GIT_COMMON_DIR GIT_DIR GIT_INDEX_FILE GIT_NAMESPACE GIT_OBJECT_DIRECTORY GIT_WORK_TREE'
-unset_options=''
-for variable in $location_variables; do unset_options="$unset_options -u $variable"; done
-# shellcheck disable=SC2086
-if env $unset_options git rev-parse --show-toplevel >/dev/null 2>&1; then unset $location_variables; fi
-
 hook_name=$1
 shift
-hooks_dir=$(dirname "$0")
+case $0 in
+*/*) hooks_dir=${0%/*} ;;
+*) hooks_dir=. ;;
+esac
 package_dir="$hooks_dir/../.."
 bundle="$package_dir/dist/hooks/$hook_name.js"
 josh_command="${hook_name%%-*}:${hook_name#*-}"
 
 case $0 in
 *node_modules/*)
-	if [ -d "$package_dir/dist/hooks" ]; then node "$bundle" "$@"; else node "$package_dir/dist/josh.js" "$josh_command" "$@"; fi
+	if [ -d "$package_dir/dist/hooks" ]; then exec node "$bundle" "$@"; else exec node "$package_dir/dist/josh.js" "$josh_command" "$@"; fi
 	;;
 *)
-	node --disable-warning=ExperimentalWarning "$hooks_dir/hook-bundle-ready.ts" "$hook_name" "$josh_command" "$@"
+	exec node --disable-warning=ExperimentalWarning "$hooks_dir/hook-bundle-ready.ts" "$hook_name" "$josh_command" "$@"
 	;;
 esac

package/scripts/hooks/stop-actions.ts

@@ -0,0 +1,204 @@
+import { git_gh_repo } from '#scripts/gh/git-gh-repo'
+import { issue_cite } from '#scripts/issue/issue-cite'
+import { issue_cite_cli } from '#scripts/issue/issue-cite-cli'
+import { session_cite } from '#scripts/issue/session-cite'
+import { bounded_pool } from '#scripts/lib/bounded-pool'
+import { telegram_test } from '#scripts/notify/telegram-test'
+import type { CliValues } from '#scripts/notify/telegram-test-logic'
+import { issue_citation } from '#scripts/rules/issue-citation'
+import { stop_rules, type StopAction, type StopOutcome } from '#scripts/rules/stop-rules'
+import { run_hold } from '#scripts/run/hold/run-hold'
+import { run_hold_cli } from '#scripts/run/hold/run-hold-cli'
+import { run_hold_session } from '#scripts/run/hold/run-hold-session'
+
+type NotifyAction = Extract<StopAction, { kind: 'notify' }>
+
+// The `Stop` hook running the operations whose answer is fixed (joshuafolkken/kit#3919): the
+// `confirmation` notify, the hold release and the citation lines, through the very calls
+// `josh notify`, `josh run:release` and `josh issue:cite` make — in process, since three `pnpm`
+// launches would spend most of the hook's 20-second budget. What each did reaches the person as a
+// `systemMessage`; one that did not take falls back to the refusal it replaced (`stop_rules.fallback_reason`).
+
+const SUCCESS_EXIT_CODE = 0
+const NOTICE_SEPARATOR = '\n'
+// The reply is the stop's reason, but a Telegram is read at a glance — its opening is enough.
+const SUMMARY_CHARS = 600
+// A `#N`, `owner/repo#N` or URL is a run of printable ASCII; a cut inside one would link the wrong Issue.
+const TOKEN_CHAR = /^[!-~]$/u
+const EMPTY_SUMMARY = 'The run stopped and is waiting for you.'
+
+interface Settled {
+	notices: ReadonlyArray<string>
+	failure: string | undefined
+}
+
+// One action at a time — the order is the rule order.
+const SEQUENTIAL = 1
+
+// Where the run of token characters `text` ends with starts.
+function token_start(text: string): number {
+	let index = text.length
+
+	while (index > 0 && TOKEN_CHAR.test(text.charAt(index - 1))) index -= 1
+
+	return index
+}
+
+// Cut before linking, on a boundary that keeps every reference whole: the character past the cut shows
+// whether the last token ran on, and a token that did is dropped rather than halved.
+function summary_of(message: string): string {
+	const trimmed = message.trim()
+	if (trimmed === '') return EMPTY_SUMMARY
+	if (trimmed.length <= SUMMARY_CHARS) return trimmed
+
+	const overshoot = trimmed.slice(0, SUMMARY_CHARS + 1)
+	const cut = overshoot.slice(0, Math.min(token_start(overshoot), SUMMARY_CHARS))
+
+	return cut === '' ? trimmed.slice(0, SUMMARY_CHARS) : cut
+}
+
+// The held Issue's URL, or `undefined` for a `new` entry or a repository that cannot be read.
+async function issue_url_of(issue: string): Promise<string | undefined> {
+	if (issue === run_hold.UNNUMBERED_ISSUE) return undefined
+
+	const slug = await git_gh_repo.repo_get_name_with_owner()
+
+	return slug === undefined ? undefined : issue_cite.issue_url(slug, issue)
+}
+
+// The body is the reply's opening copied into a Telegram, so its bare `#N` are linked (`issue-citation.md`).
+// The choices are the reply's own decision lines (joshuafolkken/kit#3961).
+function notify_values(issue_url: string | undefined, action: NotifyAction): CliValues {
+	const { recommended, alternative } = action.decision
+	const values: CliValues = {
+		'task-type': 'confirmation',
+		body: session_cite.text(summary_of(action.message)),
+		recommended,
+		...(alternative !== undefined && { alternative: [alternative] }),
+	}
+
+	return issue_url === undefined ? values : { ...values, 'issue-url': issue_url }
+}
+
+// The send is stamped on the hold, so a later stop of the same pause does not announce it again. A
+// stamp that fails does not fail the send: the Telegram is out, and a refused stop would send it twice.
+async function mark_notified(): Promise<void> {
+	try {
+		const directory = await run_hold.worktree_directory()
+
+		if (directory !== undefined) run_hold_session.mark_notified(run_hold.hold_path(directory))
+	} catch (error) {
+		console.warn(`stop:guard could not stamp the notify on the hold: ${String(error)}`)
+	}
+}
+
+async function notify(action: NotifyAction): Promise<string> {
+	const issue_url = await issue_url_of(action.issue)
+
+	await telegram_test.send_values(notify_values(issue_url, action))
+	await mark_notified()
+
+	return `📱 stop:guard sent the confirmation notify (${issue_url ?? action.issue}).`
+}
+
+async function release(issue: string): Promise<string | undefined> {
+	const argv = issue === run_hold.UNNUMBERED_ISSUE ? ['--release'] : ['--release', issue]
+	const code = await run_hold_cli.run(argv)
+
+	return code === SUCCESS_EXIT_CODE ? '🔓 stop:guard released the run:hold record.' : undefined
+}
+
+// Every line or none: a citation with a number missing is the half-fix the refusal exists to avoid.
+async function cite(references: ReadonlyArray<string>): Promise<string | undefined> {
+	const cited = await issue_cite_cli.cite(issue_citation.cite_arguments(references))
+	if (cited === undefined || cited.failures.length > 0) return undefined
+
+	return ['Issue citations:', ...cited.lines].join(NOTICE_SEPARATOR)
+}
+
+// An action's line for the person, or `undefined` when it did not take.
+async function run_action(action: StopAction): Promise<string | undefined> {
+	if (action.kind === 'notify') return await notify(action)
+	if (action.kind === 'release') return await release(action.issue)
+
+	return await cite(action.references)
+}
+
+// **The hook's stdout is the decision envelope, so nothing else may reach it**: the reused calls report
+// on stdout (`josh run:release`'s verdict token, the notify's sent line) and are sent to stderr instead.
+type StreamWrite = typeof process.stdout.write
+
+function set_stdout_write(stream_write: StreamWrite): void {
+	process.stdout.write = stream_write
+}
+
+async function on_stderr<T>(work: () => Promise<T>): Promise<T> {
+	const saved = { write: process.stdout.write.bind(process.stdout) }
+
+	set_stdout_write(process.stderr.write.bind(process.stderr))
+
+	try {
+		return await work()
+	} finally {
+		set_stdout_write(saved.write)
+	}
+}
+
+// A throw is an action that did not take, the same as one that answered it had failed.
+async function attempt(action: StopAction): Promise<string | undefined> {
+	try {
+		return await run_action(action)
+	} catch {
+		return undefined
+	}
+}
+
+function is_notice(notice: string | undefined): notice is string {
+	return notice !== undefined
+}
+
+// In order, one at a time: the notify reports the hold the release then ends. The first failure is the
+// one refused with, as the rule order put it first.
+async function settle(actions: ReadonlyArray<StopAction>): Promise<Settled> {
+	const notices = await on_stderr(
+		async () => await bounded_pool.bounded_map(actions, SEQUENTIAL, attempt),
+	)
+	const failed = actions.find((_action, index) => notices[index] === undefined)
+
+	return {
+		notices: notices.filter((notice) => is_notice(notice)),
+		failure: failed === undefined ? undefined : stop_rules.fallback_reason(failed),
+	}
+}
+
+function joined(notices: ReadonlyArray<string>): string | undefined {
+	return notices.length === 0 ? undefined : notices.join(NOTICE_SEPARATOR)
+}
+
+// A failure refuses only where the outcome allows it — never past the loop-breaker.
+function settled_envelope(
+	settled: Settled,
+	is_blocking: boolean,
+	lang: string,
+): string | undefined {
+	const notice = joined(settled.notices)
+
+	if (is_blocking && settled.failure !== undefined) {
+		return stop_rules.block_envelope(settled.failure, lang, notice)
+	}
+
+	return notice === undefined ? undefined : stop_rules.notice_envelope(notice)
+}
+
+// What the hook writes for one stop's outcome, or `undefined` for a stop that writes nothing.
+async function envelope_of(outcome: StopOutcome, lang: string): Promise<string | undefined> {
+	if (outcome.reason !== undefined) return stop_rules.block_envelope(outcome.reason, lang)
+
+	const settled = await settle(outcome.actions)
+
+	return settled_envelope(settled, outcome.blocks_on_failure, lang)
+}
+
+const stop_actions = { envelope_of, summary_of }
+
+export { stop_actions }

package/scripts/hooks/stop-guard.ts

@@ -5,6 +5,7 @@ import { agent_headless } from '#scripts/agent/agent-headless'
 import { backlog_ready } from '#scripts/backlog/backlog-ready'
 import { backlog_stalled_detect } from '#scripts/backlog/backlog-stalled-detect'
 import { repo_party } from '#scripts/discovery/repo-party'
+import { stop_actions } from '#scripts/hooks/stop-actions'
 import { hook_decision } from '#scripts/josh/hook-decision'
 import { session_language } from '#scripts/josh/session-language'
 import { lane_child_marker } from '#scripts/lane/lane-child-marker'
@@ -13,37 +14,64 @@ import { filing_cap } from '#scripts/rules/filing-cap'
 import { lane_background } from '#scripts/rules/lane-background'
 import { lane_park } from '#scripts/rules/lane-park'
 import { last_prompt } from '#scripts/rules/last-prompt'
+import { pre_gate_cut } from '#scripts/rules/pre-gate-cut'
+import { stop_decision } from '#scripts/rules/stop-decision'
 import { stop_rules, type StopContext, type StopOutcome } from '#scripts/rules/stop-rules'
+import { tail_commands } from '#scripts/rules/tail-commands'
 import { run_carry } from '#scripts/run/carry/run-carry'
 import { run_cut } from '#scripts/run/cut/run-cut'
-import { run_hold } from '#scripts/run/hold/run-hold'
+import { run_cut_report } from '#scripts/run/cut/run-cut-report'
+import { run_hold, type RunHold } from '#scripts/run/hold/run-hold'
+import { run_hold_session } from '#scripts/run/hold/run-hold-session'
 import { run_halfrun_resume } from '#scripts/run/run-halfrun-resume'
 import { run_headless } from '#scripts/run/run-headless'
 import { run_stranded_detect } from '#scripts/run/run-stranded-detect'
 import { time_density_hook } from '#scripts/time-runtime/time-density-hook'
 import { time_hook_transcript } from '#scripts/time-runtime/time-hook-transcript'
 
-// The `Stop` hook entry: one process that delivers the three stop-time rules.
+// The `Stop` hook entry: one process that delivers the stop-time rules, running the fixed ones itself
+// (`stop-actions.ts`).
 // It is the stop-time counterpart of `pretool-guard.ts` — a second entry on the same `hook_decision`
 // foundation, not a second copy of it.
 //
 // **Every failure allows the stop.** A missing transcript, an unreadable hold record, a git status
 // that will not read — each ends as "no block", for the same reason the PreToolUse guard fails open:
-// a hook that failed closed would wedge a run over its own plumbing. The block rules are self-
-// resolving (send the notify, release the hold) and `stop_hook_active` is the backstop, so failing
+// a hook that failed closed would wedge a run over its own plumbing. The hook runs the fixed
+// operations itself (send the notify, release the hold) and `stop_hook_active` is the backstop, so failing
 // open here costs at most a missed nudge, never a stuck run.
 
-// The hold record for this working tree is still in place, and whether it is a `prrun` stop's.
-// `unreadable` reads as absent: the safe direction for a stop guard is not to
-// block, and an unreadable record is not proof a run is holding.
-async function hold_facts(): Promise<Pick<StopContext, 'hold_present' | 'prrun_stopped'>> {
+// The hold record for this working tree. `unreadable` reads as absent: the safe direction for a stop
+// guard is not to act, and an unreadable record is not proof a run is holding.
+async function held_record(): Promise<RunHold | undefined> {
 	const directory = await run_hold.worktree_directory()
-	const hold =
-		directory === undefined
-			? undefined
-			: run_halfrun_resume.hold_of(run_hold.read_hold(run_hold.hold_path(directory)))
+	if (directory === undefined) return undefined
 
-	return { hold_present: hold !== undefined, prrun_stopped: hold?.prrun_stop_head !== undefined }
+	return run_halfrun_resume.hold_of(run_hold.read_hold(run_hold.hold_path(directory)))
+}
+
+// The pause was announced: by a `josh notify` on the tail, or by this hook's own send, recorded on the
+// hold since the pause began (joshuafolkken/kit#3961).
+function was_notified(hold: RunHold | undefined, tail: string): boolean {
+	if (lane_park.mentions_confirmation_notify(tail)) return true
+
+	return (
+		hold !== undefined && run_hold_session.is_notified_since(hold, last_prompt.pause_start(tail))
+	)
+}
+
+// The Issue the hold names, whether it is a `prrun` stop's and this session's own, and whether its
+// pause was already announced.
+async function hold_facts(
+	tail: string,
+): Promise<Pick<StopContext, 'hold_issue' | 'hold_owned' | 'notified' | 'prrun_stopped'>> {
+	const hold = await held_record()
+
+	return {
+		hold_issue: hold?.issue,
+		hold_owned: hold === undefined || run_hold_session.is_session_hold(hold),
+		notified: was_notified(hold, tail),
+		prrun_stopped: hold?.prrun_stop_head !== undefined,
+	}
 }
 
 // A `confirmation` notify sits on this run's transcript tail. The tail is derived exactly as the
@@ -60,6 +88,19 @@ function was_filed(tail: string): boolean {
 	return filing_cap.turn_filing_count(tail) > 0
 }
 
+// This turn ended at a cut — a record still `carried`, or this turn's `run:cut` relaunching a successor.
+// The second covers the successor's resume clearing the record before this stop (joshuafolkken/kit#3936);
+// the held cut outside a lane prints no marker, so its person is still notified.
+function is_cut_stop(tail: string): boolean {
+	if (run_cut.carried_cut_sync() !== undefined) return true
+
+	return tail_commands.answered(
+		filing_cap.current_turn(tail),
+		pre_gate_cut.takes_the_cut,
+		run_cut_report.RELAUNCHED_CUT_MARKER,
+	)
+}
+
 // The session language the refusal is written for — `write_stop_decision` has already loaded the `.env`.
 function session_lang(): string {
 	return session_language.resolve_session_lang().lang
@@ -85,13 +126,13 @@ async function build_context(
 	const tail = transcript_tail(transcript_path)
 
 	return {
-		...(await hold_facts()),
+		...(await hold_facts(tail)),
 		tree_clean: !(await run_hold.is_tree_dirty()),
-		notified: lane_park.mentions_confirmation_notify(tail),
 		message: payload_tail.message,
 		prompt: last_prompt.prompt_text(tail),
+		answers_question: stop_decision.is_question(last_prompt.turn_prompt(tail)),
 		stop_hook_active: payload_tail.stop_hook_active,
-		cut_pending: run_cut.carried_cut_sync() !== undefined,
+		cut_pending: is_cut_stop(tail),
 		filed: was_filed(tail),
 		session_owner: repo_party.current_owner(),
 		...(await session_role_facts()),
@@ -167,17 +208,17 @@ async function run_report_checks(): Promise<void> {
 	await run_stranded_detect.run_stranded_check()
 }
 
-// Nothing reaches stdout on an ordinary stop, so what the harness parses stays empty unless the stop
-// is being held — all three rules block, so a bare `#N` is reported the same way.
+// Nothing reaches stdout on an ordinary stop, so what the harness parses stays empty unless the stop is
+// held or the hook acted on it (`stop-actions.ts`).
 async function write_stop_decision(raw_payload: string): Promise<void> {
 	hook_decision.load_environment_file()
 	await run_report_checks()
 
-	const { reason } = await outcome_of(raw_payload)
+	const envelope = await stop_actions.envelope_of(await outcome_of(raw_payload), session_lang())
 
-	if (reason === undefined) return
+	if (envelope === undefined) return
 
-	process.stdout.write(`${stop_rules.block_envelope(reason, session_lang())}\n`)
+	process.stdout.write(`${envelope}\n`)
 }
 
 const stop_guard = { outcome_of, stop_outcome_for_payload }

package/scripts/init/hook-launch.ts

@@ -9,18 +9,23 @@ import { GIT_LOCATION_VARIABLES } from '#scripts/git/git-location-environment'
 // Every path after the prefix is relative, so a hook fired from a
 // subdirectory would otherwise miss its script. The root is git's, resolved with the location
 // variables a git hook exports cleared first, and resolved with them only when that fails — git
-// metadata outside the work tree. The consumer rewrite (`hook-command-rewrite.ts`) keeps this prefix,
-// so both sides stay one mechanism for Claude Code and Codex alike.
+// metadata outside the work tree. When the cleared lookup succeeds the variables are cleared for the
+// hook too, so its own git calls act on the checkout it stands in. The consumer rewrite
+// (`hook-command-rewrite.ts`) keeps this prefix, so both sides stay one mechanism for Claude Code and
+// Codex alike.
 //
-// **Everything after the root is one script** (`scripts/hooks/run-hook.sh`):
-// clearing the location variables for the hook itself, the bundle-ready gate and the live-source
-// fallback live there once, so each hook command names only its hook.
+// **A hook runs on every tool call, so its launch spawns as little as it can** (joshuafolkken/kit#3946):
+// the shell's own `unset` clears the variables rather than an `env` process, and that one lookup
+// both finds the root and decides whether the variables stay — `git` starts once.
+//
+// **Everything after the root is one script** (`scripts/hooks/run-hook.sh`): the bundle-ready gate and
+// the live-source fallback live there once, so each hook command names only its hook.
 
 const HOOK_DIST_DIR = 'dist/hooks'
 const RUN_HOOK_SCRIPT = 'scripts/hooks/run-hook.sh'
-const UNSET_OPTIONS = GIT_LOCATION_VARIABLES.map((name) => `-u ${name}`).join(' ')
+const LOCATION_VARIABLES = GIT_LOCATION_VARIABLES.join(' ')
 const ROOT_LOOKUP = 'git rev-parse --show-toplevel'
-const PROJECT_ROOT_PREFIX = `project_root="$(env ${UNSET_OPTIONS} ${ROOT_LOOKUP} 2>/dev/null || ${ROOT_LOOKUP})" && cd "$project_root" && `
+const PROJECT_ROOT_PREFIX = `if project_root="$(unset ${LOCATION_VARIABLES}; ${ROOT_LOOKUP} 2>/dev/null)"; then unset ${LOCATION_VARIABLES}; else project_root="$(${ROOT_LOOKUP})"; fi && cd "$project_root" && `
 
 // `name` is the hook's bundle under `dist/hooks` without `.js` (e.g. `pretool-guard`), followed by any
 // arguments it takes (e.g. `codex-hook-adapter pretool`).

package/scripts/issue/expected-effect-lint.ts

@@ -0,0 +1,59 @@
+import { markdown_section } from './markdown-section'
+
+// joshuafolkken/kit#3909: a run-time-shortening proposal was filed and implemented on a criterion that
+// never weighed how often the speed-up applies against what it costs when it does not. An Issue that
+// declares that aim must therefore state its expected effect — the hit rate, the gain per hit, the loss
+// per miss and where each number came from — before `issue:lint` and `issue:file` accept it. The
+// declaration, the heading and the item labels are the template's, pinned by the document test.
+
+const DECLARATION_LINE = '- 目的: 時間短縮'
+const BACKGROUND_HEADING = '## 背景'
+const HEADING = '## 期待効果'
+const ITEM_LABELS: ReadonlyArray<string> = ['効く率', '1 回あたりの得', '外れたときの損', '出典']
+// A template placeholder value — the `<...>` guidance a filed Issue replaces. It is not an estimate, but a
+// value that only opens with `<` (an upper bound such as `<1 min`) is one, so the placeholder must close with `>` too.
+const PLACEHOLDER = /^<.*>$/u
+
+// Whether the body declares a run-time-shortening aim under its background heading.
+function is_target(body: string): boolean {
+	const background = markdown_section.section_lines(body, BACKGROUND_HEADING).join('\n')
+
+	return markdown_section.has_unfenced_line(background, DECLARATION_LINE)
+}
+
+function item_value(line: string, label: string): string | undefined {
+	const prefix = `- ${label}:`
+
+	if (!line.startsWith(prefix)) return undefined
+
+	return line.slice(prefix.length).trim()
+}
+
+function has_item(lines: ReadonlyArray<string>, label: string): boolean {
+	return lines.some((line) => {
+		const value = item_value(line.trim(), label)
+
+		return value !== undefined && value.length > 0 && !PLACEHOLDER.test(value)
+	})
+}
+
+// Every expected-effect problem a body has, or an empty array. A body without the declaration has none.
+function problems(body: string): ReadonlyArray<string> {
+	if (!is_target(body)) return []
+	if (!markdown_section.has_line(body, HEADING)) return [`missing heading: ${HEADING}`]
+	const section = markdown_section.section_lines(body, HEADING).join('\n')
+	const lines = markdown_section.unfenced_lines(section)
+
+	return ITEM_LABELS.filter((label) => !has_item(lines, label)).map(
+		(label) => `missing expected-effect item: - ${label}: <value>`,
+	)
+}
+
+const expected_effect_lint = {
+	DECLARATION_LINE,
+	HEADING,
+	ITEM_LABELS,
+	problems,
+}
+
+export { expected_effect_lint }