@joshuafolkken/kit 1.1514.0 → 1.2114.0

package/scripts/hooks/reserved-run.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
+import { command_memory } from '#scripts/gate/command-memory'
 import { core_budget } from '#scripts/gate/core-budget'
 import { unit_worker_share } from '#scripts/test/unit-worker-share'
 import { execa } from 'execa'
@@ -18,6 +19,11 @@ import { execa } from 'execa'
 // being rewritten around it — and a second copy of the claim-run-release dance is the clone
 // `CLAUDE.md` prohibits. The weight is the caller's, passed on the command line beside the command, so
 // the reservation these two conservative numbers stand for lives at the one place a person reads them.
+//
+// **The memory is read off the command, not left at zero** (joshuafolkken/kit#4582): a lane wrapped a
+// four-worker typed eslint here and the 12 GB it held was admitted beside four other lanes. The
+// wrapped command's tool and worker count give its `MEMORY_MB` (`command-memory.ts`); `--memory <MB>`
+// overrides that estimate.
 
 // `process.argv` is [runner, script, ...arguments].
 const FIRST_ARGUMENT_INDEX = 2
@@ -30,24 +36,83 @@ const FAIL_EXIT_CODE = 1
 // cumulative sum and let a later reservation admit past the budget the ledger exists to hold.
 const MIN_WEIGHT = 1
 
+const MEMORY_FLAG = '--memory'
+// `--memory <MB>`: the flag and its value.
+const MEMORY_OPTION_LENGTH = 2
+// An explicit `--memory` claims at least one MB; zero is the absence the estimate already stands for.
+const MIN_MEMORY_MB = 1
+// An argument that is one shell word with no quoting.
+const PLAIN_WORD = /^[\w./=:@%+,-]+$/u
+// A single quote inside a single-quoted word: close, escaped quote, reopen.
+const ESCAPED_QUOTE = String.raw`'\''`
+
 interface ReservedCommand {
 	weight: number
+	// The explicit `--memory <MB>`, which overrides the estimate read off the command.
+	memory_mb: number | undefined
 	command: ReadonlyArray<string>
 }
 
-// `<weight> -- <command> [args...]`. `undefined` is a usage error: a missing separator, a weight that
-// is not an integer of at least one core, or nothing to run.
+function is_integer_from(value: number, floor: number): boolean {
+	return Number.isSafeInteger(value) && value >= floor
+}
+
+// The options between the weight and the separator: none, or `--memory <MB>` with a positive integer.
+// `undefined` is a usage error.
+function parse_memory(
+	options: ReadonlyArray<string>,
+): { memory_mb: number | undefined } | undefined {
+	if (options.length === 0) return { memory_mb: undefined }
+
+	const memory_mb = Number(options[1])
+	const is_memory_option = options.length === MEMORY_OPTION_LENGTH && options[0] === MEMORY_FLAG
+
+	return is_memory_option && is_integer_from(memory_mb, MIN_MEMORY_MB) ? { memory_mb } : undefined
+}
+
+// `<weight> [--memory <MB>] -- <command> [args...]`. `undefined` is a usage error: a missing
+// separator, a weight that is not an integer of at least one core, a malformed `--memory`, or nothing
+// to run.
 function parse_arguments(argv: ReadonlyArray<string>): ReservedCommand | undefined {
 	const NOT_FOUND = -1
 	const separator = argv.indexOf(COMMAND_SEPARATOR)
 	const weight = Number(argv[WEIGHT_INDEX])
-	const is_valid_weight = Number.isSafeInteger(weight) && weight >= MIN_WEIGHT
+	const memory = parse_memory(argv.slice(WEIGHT_INDEX + 1, Math.max(separator, 0)))
+	const command = argv.slice(separator + 1)
 
-	if (separator === NOT_FOUND || !is_valid_weight) return undefined
+	if (separator === NOT_FOUND || !is_integer_from(weight, MIN_WEIGHT)) return undefined
 
-	const command = argv.slice(separator + 1)
+	return memory !== undefined && command.length > 0 ? { weight, ...memory, command } : undefined
+}
+
+// An argument as one shell word: a plain one as written, anything else single-quoted. **The estimate
+// re-reads the command as a shell line**, so `git commit -m "a; eslint ."` joined bare would be cut at
+// the `;` and reserved as an eslint run.
+function shell_word(argument: string): string {
+	if (PLAIN_WORD.test(argument)) return argument
+
+	return `'${argument.split("'").join(ESCAPED_QUOTE)}'`
+}
+
+// What the claim carries to the ledger: the command named on the waiting line, and the memory it
+// holds — the explicit `--memory`, else the estimate read off the command (`command-memory.ts`), else
+// none, the 0 MB a command the table does not know counted before.
+function reservation_options(parsed: ReservedCommand): {
+	command: string
+	memory_mb: number | undefined
+} {
+	const command = parsed.command.map((argument) => shell_word(argument)).join(' ')
+
+	return { command, memory_mb: parsed.memory_mb ?? command_memory.estimated_memory_mb(command) }
+}
+
+// The directory the caller typed the command in. **`pnpm josh` runs from the package root**, so without
+// this a wrapped `eslint rules/a.ts` typed in `scripts/` would lint from the root and match nothing;
+// pnpm records the caller's directory in `INIT_CWD` (joshuafolkken/kit#5147).
+function command_directory(): string {
+	const initial = process.env['INIT_CWD']
 
-	return command.length > 0 ? { weight, command } : undefined
+	return initial === undefined || initial === '' ? process.cwd() : initial
 }
 
 // `stdio: 'inherit'` so the command's own progress reaches the push, and `reject: false` so a failing
@@ -55,7 +120,11 @@ function parse_arguments(argv: ReadonlyArray<string>): ReservedCommand | undefin
 // `with_core_reservation`'s `finally` on either path.
 async function run_command(command: ReadonlyArray<string>): Promise<number> {
 	const [file = '', ...args] = command
-	const result = await execa(file, args, { stdio: 'inherit', reject: false })
+	const result = await execa(file, args, {
+		cwd: command_directory(),
+		stdio: 'inherit',
+		reject: false,
+	})
 
 	return result.exitCode ?? FAIL_EXIT_CODE
 }
@@ -64,7 +133,9 @@ async function run_reserved(argv: ReadonlyArray<string>): Promise<number> {
 	const parsed = parse_arguments(argv)
 
 	if (parsed === undefined) {
-		process.stderr.write('reserved-run: usage: reserved-run <weight> -- <command> [args...]\n')
+		process.stderr.write(
+			'reserved-run: usage: reserved-run <weight> [--memory <MB>] -- <command> [args...]\n',
+		)
 
 		return FAIL_EXIT_CODE
 	}
@@ -78,7 +149,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(' ') },
+		reservation_options(parsed),
 	)
 }
 
@@ -86,6 +157,6 @@ if (process.argv[1] === fileURLToPath(import.meta.url)) {
 	process.exitCode = await run_reserved(process.argv.slice(FIRST_ARGUMENT_INDEX))
 }
 
-const reserved_run = { parse_arguments, run_reserved }
+const reserved_run = { parse_arguments, reservation_options, run_reserved }
 
 export { reserved_run }

package/scripts/hooks/run-hook.sh

@@ -5,12 +5,15 @@
 # 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 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 git location variables a git hook exports are cleared when the checkout resolves without
+#   them, so the hook's own git calls act on the checkout it stands in, and kept when the git metadata
+#   lives outside the work tree. `git` starts only when one of them is set — a hook runs on every tool
+#   call (joshuafolkken/kit#3946, joshuafolkken/kit#4187). The list is `GIT_LOCATION_VARIABLES`
+#   (`scripts/git/git-location-environment.ts`), held to it by `run-hook.test.ts`.
 # - 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`).
-# - In kit's own checkout the gate is `hook-bundle-ready.ts`, which rebuilds stale bundles
+# - In kit's own checkout the gate is the kit-only `tools/hooks/hook-bundle-ready.ts`, which rebuilds stale bundles
 #   (joshuafolkken/kit#2984) and then runs the bundle — or the josh fallback — itself, so a hook call
 #   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
@@ -19,22 +22,43 @@
 #   `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.
+# - A hook launched inside one of Claude Code's own worktrees (`EnterWorktree`, an
+#   `isolation: "worktree"` subagent) runs in that worktree. Claude Code keeps `CLAUDE_PROJECT_DIR` on
+#   the main checkout there, so the prefix lands on it and hands over where the hook was launched in
+#   `JOSH_HOOK_CWD` (joshuafolkken/kit#4617). The code still comes from the project root — a fresh
+#   worktree has no install and no bundles — so only the working directory moves.
 
 hook_name=$1
 shift
 case $0 in
-*/*) hooks_dir=${0%/*} ;;
-*) hooks_dir=. ;;
+/*) hooks_dir=${0%/*} ;;
+*/*) hooks_dir=$PWD/${0%/*} ;;
+*) hooks_dir=$PWD ;;
 esac
 package_dir="$hooks_dir/../.."
 bundle="$package_dir/dist/hooks/$hook_name.js"
 josh_command="${hook_name%%-*}:${hook_name#*-}"
 
+worktrees_dir=$PWD/.claude/worktrees/
+case $JOSH_HOOK_CWD in
+"$worktrees_dir"?*)
+	worktree_path=${JOSH_HOOK_CWD#"$worktrees_dir"}
+	cd "$worktrees_dir${worktree_path%%/*}" || exit
+	;;
+*) ;;
+esac
+
+location_variables='GIT_ALTERNATE_OBJECT_DIRECTORIES GIT_COMMON_DIR GIT_DIR GIT_INDEX_FILE GIT_NAMESPACE GIT_OBJECT_DIRECTORY GIT_WORK_TREE'
+if [ -n "$GIT_ALTERNATE_OBJECT_DIRECTORIES$GIT_COMMON_DIR$GIT_DIR$GIT_INDEX_FILE$GIT_NAMESPACE$GIT_OBJECT_DIRECTORY$GIT_WORK_TREE" ] &&
+	(unset $location_variables && git rev-parse --show-toplevel >/dev/null 2>&1); then
+	unset $location_variables
+fi
+
 case $0 in
 *node_modules/*)
 	if [ -d "$package_dir/dist/hooks" ]; then exec node "$bundle" "$@"; else exec node "$package_dir/dist/josh.js" "$josh_command" "$@"; fi
 	;;
 *)
-	exec node --disable-warning=ExperimentalWarning "$hooks_dir/hook-bundle-ready.ts" "$hook_name" "$josh_command" "$@"
+	exec node --disable-warning=ExperimentalWarning "$package_dir/tools/hooks/hook-bundle-ready.ts" "$hook_name" "$josh_command" "$@"
 	;;
 esac

package/scripts/hooks/shell-rules-notice.ts

@@ -0,0 +1,37 @@
+import { cost_blocks } from '#scripts/cost-runtime/cost-blocks'
+import { hook_decision } from '#scripts/josh/hook-decision'
+
+// The two most-refused Bash rows, `file-body` and `piped-verification`, delivered ahead of the call
+// that would break them. A refusal teaches the rule only after the call was composed, and each
+// refusal is a round trip spent rewriting it (joshuafolkken/kit#3996). The first Bash call of a
+// session comes before any of those, so the hook that sees it carries the two rules as a notice.
+//
+// **The rows themselves are unchanged.** They still refuse on every occurrence; this only puts their
+// text in front of the first call, the way `step-zero-notice.ts` delivers Step 0 at the first edit.
+//
+// **Once per session**, on a stamp keyed by the transcript. A stamp that cannot be written stays
+// silent rather than repeating the notice on every call.
+const STAMP_PREFIX = 'josh-shell-rules-notice-'
+
+const NOTICE =
+	'Shell rules: change an existing file with Edit or Write, never a script or heredoc that writes it (file-edits.md); run a josh check with no pipe or under `set -o pipefail`, never `| head` (output-bounds.md).'
+
+const STAMP = hook_decision.create_refusal_stamp(STAMP_PREFIX)
+
+function notice(raw_payload: string): string | undefined {
+	const payload = hook_decision.parse_hook_payload(raw_payload)
+
+	if (payload?.tool_name !== cost_blocks.BASH_TOOL) return undefined
+
+	const target = STAMP.path(payload.transcript_path)
+
+	if (STAMP.last_ms(target) !== hook_decision.NEVER_MS || !STAMP.record(target, Date.now())) {
+		return undefined
+	}
+
+	return NOTICE
+}
+
+const shell_rules_notice = { NOTICE, notice, stamp_path: STAMP.path }
+
+export { shell_rules_notice }

package/scripts/hooks/step-zero-notice.ts

@@ -58,6 +58,11 @@ function is_candidate(raw_payload: string, root: string): string | undefined {
 	return has_runtime_file ? payload.transcript_path : undefined
 }
 
+// Whether the payload edits a runtime file under `root` — the edit Step 0 and the lane plan precede.
+function is_runtime_edit(raw_payload: string, root: string = process.cwd()): boolean {
+	return is_candidate(raw_payload, root) !== undefined
+}
+
 function notice(raw_payload: string, root: string = process.cwd()): string | undefined {
 	const transcript = is_candidate(raw_payload, root)
 
@@ -72,6 +77,6 @@ function notice(raw_payload: string, root: string = process.cwd()): string | und
 	return NOTICE
 }
 
-const step_zero_notice = { NOTICE, notice, stamp_path: STAMP.path }
+const step_zero_notice = { NOTICE, is_runtime_edit, notice, stamp_path: STAMP.path }
 
 export { step_zero_notice }

package/scripts/hooks/stop-actions.ts

@@ -1,11 +1,10 @@
 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 { stdout_on_stderr } from '#scripts/lib/stdout-on-stderr'
 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'
@@ -14,9 +13,8 @@ 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
+// `confirmation` notify and the hold release, through the very calls `josh notify` and
+// `josh run:release` make — in process, since two `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
@@ -108,40 +106,11 @@ async function release(issue: string): Promise<string | undefined> {
 	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)
-	}
+	return await release(action.issue)
 }
 
 // A throw is an action that did not take, the same as one that answered it had failed.
@@ -160,7 +129,7 @@ function is_notice(notice: string | undefined): notice is string {
 // 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(
+	const notices = await stdout_on_stderr.run(
 		async () => await bounded_pool.bounded_map(actions, SEQUENTIAL, attempt),
 	)
 	const failed = actions.find((_action, index) => notices[index] === undefined)

package/scripts/hooks/stop-guard.ts

@@ -1,5 +1,4 @@
 #!/usr/bin/env tsx
-import { text } from 'node:stream/consumers'
 import { fileURLToPath } from 'node:url'
 import { agent_headless } from '#scripts/agent/agent-headless'
 import { backlog_ready } from '#scripts/backlog/backlog-ready'
@@ -10,7 +9,7 @@ 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'
 import { lane_handoff } from '#scripts/lane/lane-handoff'
-import { filing_cap } from '#scripts/rules/filing-cap'
+import { stdout_on_stderr } from '#scripts/lib/stdout-on-stderr'
 import { lane_background } from '#scripts/rules/lane-background'
 import { lane_park } from '#scripts/rules/lane-park'
 import { last_prompt } from '#scripts/rules/last-prompt'
@@ -18,6 +17,7 @@ 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 { turn_filings } from '#scripts/rules/turn-filings'
 import { run_carry } from '#scripts/run/carry/run-carry'
 import { run_cut } from '#scripts/run/cut/run-cut'
 import { run_cut_report } from '#scripts/run/cut/run-cut-report'
@@ -82,10 +82,10 @@ function transcript_tail(transcript_path: string): string {
 	return time_density_hook.read_tail(transcript)
 }
 
-// An Issue was filed on this turn — the tail from the last prompt on. The count is `filing_cap`'s, so a
-// filing a guard refused is not counted, and one an earlier turn made does not stand this turn down.
+// An Issue was filed on this turn — the tail from the last prompt on. The count is `turn_filings`', so
+// a filing a guard refused is not counted, and one an earlier turn made does not stand this turn down.
 function was_filed(tail: string): boolean {
-	return filing_cap.turn_filing_count(tail) > 0
+	return turn_filings.turn_filing_count(tail) > 0
 }
 
 // This turn ended at a cut — a record still `carried`, or this turn's `run:cut` relaunching a successor.
@@ -95,13 +95,13 @@ 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),
+		turn_filings.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`.
+// The session language the refusal is written for — `respond_from_stdin` has already loaded the `.env`.
 function session_lang(): string {
 	return session_language.resolve_session_lang().lang
 }
@@ -129,7 +129,7 @@ async function build_context(
 		...(await hold_facts(tail)),
 		tree_clean: !(await run_hold.is_tree_dirty()),
 		message: payload_tail.message,
-		prompt: last_prompt.prompt_text(tail),
+		prompt: last_prompt.person_prompt(tail),
 		answers_question: stop_decision.is_question(last_prompt.turn_prompt(tail)),
 		stop_hook_active: payload_tail.stop_hook_active,
 		cut_pending: is_cut_stop(tail),
@@ -139,6 +139,7 @@ async function build_context(
 		headless_refusals: stop_rules.count_headless_refusals(tail),
 		background_pending: lane_background.pending_background_ids(tail).length > 0,
 		agent_pending: lane_background.pending_agent_ids(tail).length > 0,
+		command_pending: lane_background.pending_command_ids(tail).length > 0,
 		handed_off: lane_handoff.is_handed_off(process.cwd()),
 		session_lang: session_lang(),
 	}
@@ -208,13 +209,18 @@ 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
-// 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()
+async function decided_envelope(raw_payload: string): Promise<string | undefined> {
 	await run_report_checks()
 
-	const envelope = await stop_actions.envelope_of(await outcome_of(raw_payload), session_lang())
+	return await stop_actions.envelope_of(await outcome_of(raw_payload), session_lang())
+}
+
+// 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`). The report checks print too — a strand's skipped
+// notify line — and text ahead of the envelope makes the harness drop the refusal, as the #4091 child's
+// lane-background block was (joshuafolkken/kit#4101), so everything before the write goes to stderr.
+async function write_stop_decision(raw_payload: string): Promise<void> {
+	const envelope = await stdout_on_stderr.run(async () => await decided_envelope(raw_payload))
 
 	if (envelope === undefined) return
 
@@ -224,8 +230,7 @@ async function write_stop_decision(raw_payload: string): Promise<void> {
 const stop_guard = { outcome_of, stop_outcome_for_payload }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) {
-	if (process.stdin.isTTY) hook_decision.report_no_payload('stop:guard')
-	else await write_stop_decision(await text(process.stdin))
+	await hook_decision.respond_from_stdin('stop:guard', write_stop_decision)
 }
 
 export { stop_guard, write_stop_decision }

package/scripts/init/distributed-paths.ts

@@ -124,6 +124,7 @@ const distributed_paths = {
 	ensure_claude_md_import,
 	remove_claude_md_import,
 	CLAUDE_MD_IMPORT_LINE,
+	KIT_PACKAGE_PATH_PREFIX,
 }
 
 export { distributed_paths }

package/scripts/init/hook-command-rewrite.ts

@@ -49,8 +49,23 @@ const PLAIN_KIT_COMMANDS: ReadonlySet<string> = new Set(
 		'session:lang',
 	].map((command) => `${PNPM_JOSH_PREFIX}${command}`),
 )
-// The values below are matched inside raw JSON text, so the root prefix is taken in its escaped form.
-const PROJECT_ROOT_PREFIX = JSON.stringify(hook_launch.PROJECT_ROOT_PREFIX).slice(1, -1)
+// The root prefix kit wrote until joshuafolkken/kit#4187 moved the git location variables into the
+// launcher. A consumer's file still carries it until its next sync, which replaces it with the current
+// one. History, never edited; removable from kit 2.0.0.
+const LOCATION_VARIABLES =
+	'GIT_ALTERNATE_OBJECT_DIRECTORIES GIT_COMMON_DIR GIT_DIR GIT_INDEX_FILE GIT_NAMESPACE GIT_OBJECT_DIRECTORY GIT_WORK_TREE'
+const ROOT_LOOKUP = 'git rev-parse --show-toplevel'
+const LEGACY_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" && `
+// The root prefix kit wrote until joshuafolkken/kit#4617 exported the launch directory for a worktree.
+// History, never edited; removable from kit 2.0.0.
+const PRE_WORKTREE_ROOT_PREFIX = `project_root="\${CLAUDE_PROJECT_DIR:-$( (unset ${LOCATION_VARIABLES}; ${ROOT_LOOKUP} 2>/dev/null) || ${ROOT_LOOKUP})}" && cd "$project_root" && `
+// The values below are matched inside raw JSON text, so each root prefix is taken in its escaped form.
+const ROOT_PREFIXES: ReadonlyArray<string> = [
+	hook_launch.PROJECT_ROOT_PREFIX,
+	PRE_WORKTREE_ROOT_PREFIX,
+	LEGACY_ROOT_PREFIX,
+].map((prefix) => JSON.stringify(prefix).slice(1, -1))
+const [PROJECT_ROOT_PREFIX = ''] = ROOT_PREFIXES
 // Capture the value of every `"command"` field, escapes and all, so the rewrites below touch command
 // values alone — never an echo reminder's prose or a `"description"` that merely mentions the string.
 const COMMAND_FIELD = /("command":\s*")((?:[^"\\]|\\.)*)(")/gu
@@ -76,10 +91,13 @@ function rewrite_command_value(value: string): string {
 }
 
 // kit's own commands already start from the root (`hook-launch.ts`), and so does an already-rewritten
-// value. The prefix is taken off before the rewrite and put back after it, so the install guard sits
-// behind the `cd` it depends on and a second pass never doubles the prefix.
+// value. The prefix — the current one or an earlier one — is taken off before the rewrite and the
+// current one put back after it, so the install guard sits behind the `cd` it depends on and a second
+// pass never doubles the prefix.
 function without_root_prefix(value: string): string {
-	return value.startsWith(PROJECT_ROOT_PREFIX) ? value.slice(PROJECT_ROOT_PREFIX.length) : value
+	const prefix = ROOT_PREFIXES.find((candidate) => value.startsWith(candidate)) ?? ''
+
+	return value.slice(prefix.length)
 }
 
 function rewrite_hook_commands(content: string, is_codex = false): string {

package/scripts/init/hook-launch.ts

@@ -1,31 +1,31 @@
-import { GIT_LOCATION_VARIABLES } from '#scripts/git/git-location-environment'
-
 // The shell command a Claude Code hook is launched with, so it starts without a `pnpm` wrapper — and,
 // for a consumer, without the `dist/josh.js` dispatcher re-spawning `tsx` for the hook's `.ts`.
 // Each hook is pre-built to its own `dist/hooks/<name>.js`
 // (`scripts/build/build-hooks.ts`) and launched directly with `node`.
 //
 // **The command starts from the project root, never from wherever the session happens to be**.
-// 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. 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.
-//
-// **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.
+// Every path after the prefix is relative, so a hook fired from a subdirectory would otherwise miss its
+// script. Claude Code names the root in `CLAUDE_PROJECT_DIR`, so its hooks start no `git` to find it;
+// Codex runs a hook in the session's directory and names no root, so there the root is git's — asked
+// first without the git location variables a git hook leaks, since a relative or bare `GIT_DIR` read
+// from a subdirectory names the wrong work tree, and with them only when the checkout does not resolve
+// without them (its metadata lives outside the work tree). A lookup that fails ends the command before
+// the launcher (joshuafolkken/kit#4187). Inside one of Claude Code's own worktrees `CLAUDE_PROJECT_DIR`
+// still names the main checkout, so the prefix exports where the hook was launched as `JOSH_HOOK_CWD`
+// and the launcher moves the hook's working directory into that worktree (joshuafolkken/kit#4617).
 //
-// **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.
+// **Everything after the root is one script** (`scripts/hooks/run-hook.sh`): the git location
+// variables a git hook exports, the bundle-ready gate and the live-source fallback live there once, so
+// each hook command names only its hook. The consumer rewrite (`hook-command-rewrite.ts`) keeps this
+// prefix, so both sides stay one mechanism for Claude Code and Codex alike.
+
+import { GIT_LOCATION_VARIABLES } from '#scripts/git/git-location-environment'
 
 const HOOK_DIST_DIR = 'dist/hooks'
 const RUN_HOOK_SCRIPT = 'scripts/hooks/run-hook.sh'
-const LOCATION_VARIABLES = GIT_LOCATION_VARIABLES.join(' ')
 const ROOT_LOOKUP = 'git rev-parse --show-toplevel'
-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" && `
+const CODEX_ROOT = `$( (unset ${GIT_LOCATION_VARIABLES.join(' ')}; ${ROOT_LOOKUP} 2>/dev/null) || ${ROOT_LOOKUP})`
+const PROJECT_ROOT_PREFIX = `export JOSH_HOOK_CWD="$PWD" && project_root="\${CLAUDE_PROJECT_DIR:-${CODEX_ROOT}}" && 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/init/init-actions.ts

@@ -2,7 +2,6 @@ import { readFileSync } from 'node:fs'
 import path from 'node:path'
 import { json_format } from '#scripts/config-merge/json-format'
 import { string_array_schema, vscode_settings_schema } from '#scripts/lib/schemas'
-import { basic_path_migration } from './basic-path-migration'
 import { init_logic } from './init-logic'
 import { package_path, PROJECT_ROOT } from './init-paths'
 import type { ProjectShape } from './project-profile'
@@ -20,9 +19,6 @@ interface FileAction {
 	dest: string
 	create: () => string
 	merge?: (existing: string) => string
-	// A merge that only migrates a kit-written line, for a file kit otherwise leaves to the project:
-	// when it changes nothing, the file is reported with the sample to add, as one with no merge is.
-	should_show_sample_when_unchanged?: boolean
 }
 
 function read_package_file(relative_path: string): string {
@@ -215,8 +211,6 @@ function build_basic_actions(shape: ProjectShape): ReadonlyArray<FileAction> {
 			dest: BASIC_PRETTIER_CONFIG,
 			create: () =>
 				"import { config } from '@joshuafolkken/kit/prettier/basic'\n\nexport default config\n",
-			merge: (existing) => basic_path_migration.migrate_basic_paths(existing),
-			should_show_sample_when_unchanged: true,
 		})
 	}