@joshuafolkken/kit 1.2116.0 → 1.3041.0

package/scripts/josh/durable-state-root.ts

@@ -0,0 +1,60 @@
+import path from 'node:path'
+import { PLATFORM_TEMP_ROOT, platform_temporary } from '#scripts/josh/platform-temporary'
+
+// **Where the durable records live and what they are called, with nothing that asks git** — the part of
+// `durable-state.ts` a reader that may not spawn `git rev-parse` or import its modules shares: the
+// vitest config counts the open lanes from their lane-state records at load (`unit-run-marker.ts`,
+// joshuafolkken/kit#6916). The common git directory is the caller's to supply.
+
+// josh's own per-clone state inside the common git directory, in one entry of it so nothing josh writes
+// sits at its root beside git's own files.
+const STATE_DIRECTORY = 'josh'
+const RUN_STATE_DIRECTORY = 'run-state'
+const OVERRIDE_STATE_DIRECTORY = 'josh-state'
+
+// **The common git directory is asked only when no override stands**: asking it is a `git rev-parse`
+// of the checkout, and under the unit suite's override every record lookup paid that probe for an
+// answer it then discarded — what timed a suite out under gate load (joshuafolkken/kit#6177).
+function state_root(override: string | undefined, read_common: () => string | undefined): string {
+	if (override !== undefined && override !== '') {
+		return path.join(override, OVERRIDE_STATE_DIRECTORY)
+	}
+
+	const common = read_common()
+
+	if (common === undefined) return PLATFORM_TEMP_ROOT
+
+	return path.join(common, STATE_DIRECTORY, RUN_STATE_DIRECTORY)
+}
+
+// Read once at import, as `PLATFORM_TEMP_ROOT` is, so both roots answer for the same override.
+const STATE_ROOT_OVERRIDE = process.env[platform_temporary.TEMP_ROOT_KEY]
+
+// Every record kept here, by the prefix of its file name — the list the one-time copy from `/tmp`
+// walks, so a record added here is carried over with the rest.
+const PREFIX = {
+	CARRY: 'josh-run-carry-',
+	ENDED: 'josh-run-ended-',
+	EVENTS: 'josh-run-events-',
+	LANE_STATE: 'josh-lane-state-',
+	LANE_LEDGER: 'josh-lane-ledger-',
+	WAKE_LOG: 'josh-run-wake-log-',
+	BACKLOGRUN_LAUNCH: 'josh-backlogrun-launch-',
+	BACKLOGRUN_LOG: 'josh-backlogrun-log-',
+	HANDOFF_LOG: 'josh-run-handoff-log-',
+	SHIP_LOG: 'josh-ship-log-',
+	SHIP_RESULT: 'josh-ship-result-',
+	LANE_DISPATCH: 'josh-lane-dispatch-',
+	LANE_PLAN: 'josh-lane-plan-',
+	INVESTIGATION: 'josh-investigation-record-',
+	GH_USAGE: 'josh-gh-usage-',
+} as const
+
+const durable_state_root = {
+	PREFIX,
+	STATE_DIRECTORY,
+	STATE_ROOT_OVERRIDE,
+	state_root,
+}
+
+export { durable_state_root }

package/scripts/josh/durable-state.ts

@@ -2,7 +2,8 @@ import { mkdirSync } from 'node:fs'
 import path from 'node:path'
 import { git_common_directory } from '#scripts/git/git-common-directory'
 import { durable_state_migrate } from '#scripts/josh/durable-state-migrate'
-import { PLATFORM_TEMP_ROOT, platform_temporary } from '#scripts/josh/platform-temporary'
+import { durable_state_root } from '#scripts/josh/durable-state-root'
+import { PLATFORM_TEMP_ROOT } from '#scripts/josh/platform-temporary'
 import { stamp_file } from '#scripts/josh/stamp-file'
 
 // **Which record goes where — the one place this is decided.** A record a run has to read again after
@@ -13,9 +14,8 @@ import { stamp_file } from '#scripts/josh/stamp-file'
 // unreadable. Everything that means nothing past the process that wrote it — a lock, a pid, a socket,
 // a per-process cache — stays in `PLATFORM_TEMP_ROOT`, where a reboot clearing it is the right answer.
 //
-// **The common git directory rather than the home directory**, because a Codex lane's sandbox reads
-// `$HOME` but may write the common git directory (`codex-agent-argv.ts`), and every lane of one
-// repository shares it. A repository's own clone is also where `review-stops.jsonl` already lives.
+// **The common git directory rather than the home directory**, because every lane of one repository
+// shares it. A repository's own clone is also where `review-stops.jsonl` already lives.
 // Outside a repository there is no such directory, and the record falls back to the temp root.
 //
 // **Records a run left in `/tmp` are copied in once per directory, and a log not written for two
@@ -23,49 +23,16 @@ import { stamp_file } from '#scripts/josh/stamp-file'
 //
 // **`JOSH_TEMP_ROOT` moves this root too**, into a directory of its own beneath the override, so the unit
 // suite's network guard keeps every record of a test run out of the live one exactly as before.
-const RUN_STATE_DIRECTORY = 'run-state'
-const OVERRIDE_STATE_DIRECTORY = 'josh-state'
+//
+// **The root and the record names are `durable-state-root.ts`'s**, kept apart so a reader that may not
+// ask git can share them; this module adds the git lookup and the upkeep.
 const STATE_DIRECTORY_MODE = 0o700
-
-function state_root(override: string | undefined, common: string | undefined): string {
-	if (override !== undefined && override !== '') {
-		return path.join(override, OVERRIDE_STATE_DIRECTORY)
-	}
-
-	if (common === undefined) return PLATFORM_TEMP_ROOT
-
-	return path.join(common, git_common_directory.STATE_DIRECTORY, RUN_STATE_DIRECTORY)
-}
-
-// Read once at import, as `PLATFORM_TEMP_ROOT` is, so both roots answer for the same override.
-const STATE_ROOT_OVERRIDE = process.env[platform_temporary.TEMP_ROOT_KEY]
-
-// The root for a named common git directory — what a launcher grants a sandboxed child before it runs.
-function root_for(common: string | undefined): string {
-	return state_root(STATE_ROOT_OVERRIDE, common)
-}
+const { PREFIX, STATE_ROOT_OVERRIDE, state_root } = durable_state_root
 
 function root(): string {
-	return root_for(git_common_directory.repository())
+	return state_root(STATE_ROOT_OVERRIDE, git_common_directory.repository)
 }
 
-// Every record kept here, by the prefix of its file name — the list the one-time copy from `/tmp`
-// walks, so a record added here is carried over with the rest.
-const PREFIX = {
-	CARRY: 'josh-run-carry-',
-	ENDED: 'josh-run-ended-',
-	EVENTS: 'josh-run-events-',
-	LANE_STATE: 'josh-lane-state-',
-	LANE_LEDGER: 'josh-lane-ledger-',
-	WAKE_LOG: 'josh-run-wake-log-',
-	BACKLOGRUN_LAUNCH: 'josh-backlogrun-launch-',
-	BACKLOGRUN_LOG: 'josh-backlogrun-log-',
-	SHIP_LOG: 'josh-ship-log-',
-	SHIP_RESULT: 'josh-ship-result-',
-	LANE_DISPATCH: 'josh-lane-dispatch-',
-	LANE_PLAN: 'josh-lane-plan-',
-} as const
-
 const PREFIXES: ReadonlyArray<string> = Object.values(PREFIX)
 
 // Directories this process has already made ready, so the upkeep runs once rather than per lookup.
@@ -101,11 +68,9 @@ function durable_path(prefix: string, key_root: string, suffix?: string): string
 
 const durable_state = {
 	PREFIX,
-	STATE_DIRECTORY_MODE,
 	ensure,
 	path: durable_path,
 	root,
-	root_for,
 	state_root,
 }
 

package/scripts/josh/hook-decision.ts

@@ -1,10 +1,14 @@
 import { text } from 'node:stream/consumers'
+import { hook_context, type HookContext } from '#scripts/hooks/hook-context'
 import { json_value } from '#scripts/lib/json-value'
 import { file_reader } from '#scripts/lib/read-file'
 import type { GuardedCall } from '#scripts/time-runtime/time-batch-guard'
-import { time_density_hook } from '#scripts/time-runtime/time-density-hook'
 import { time_hook_transcript } from '#scripts/time-runtime/time-hook-transcript'
+import { transcript_tail } from '#scripts/time-runtime/transcript-tail'
 import { z } from 'zod'
+import { hook_envelope } from './hook-envelope'
+import { hook_payload_capture } from './hook-payload-capture'
+import { hook_tool_payload } from './hook-tool-payload'
 import { josh_environment_file } from './josh-environment-file'
 import { stamp_file } from './stamp-file'
 
@@ -26,22 +30,20 @@ import { stamp_file } from './stamp-file'
 // **`agent_id` is what makes a delegated unit answerable with its own file**.
 // The path in the payload is the *parent* session's whichever agent issued the call, so without this
 // field a guard judges the parent's frozen timeline and refuses nothing at all inside a fork.
-const payload_schema = z.object({
+const payload_schema = hook_tool_payload.schema.extend({
 	transcript_path: z.string().min(1),
 	// **`nullish`, not `optional`.** A payload spelling the absent agent as `null` has to read as "no
 	// fork"; rejected, it would fail `safeParse` for the whole payload and take the guard off every
 	// call of the main line, in silence — the failure every other path here is written to avoid.
 	agent_id: z.string().nullish(),
-	tool_name: z.string().min(1),
-	tool_input: z.unknown(),
+	// The session's model where the harness hands it over (a Codex payload); Claude Code names it on
+	// the transcript's assistant entries instead (`scripts/rules/main-model.ts`).
+	model: z.string().nullish(),
 })
 const refusal_schema = z.object({ refused_at_ms: z.number() })
 
 type HookPayload = z.infer<typeof payload_schema>
 
-const HOOK_EVENT_NAME = 'PreToolUse'
-const DENY_DECISION = 'deny'
-const ALLOW_DECISION = 'allow'
 // No record means nothing has been refused yet, and every span began after instant zero — which is
 // the answer wanted: the first qualifying accumulation of a run is refused.
 const NEVER_MS = 0
@@ -52,9 +54,10 @@ const NEVER_MS = 0
 const DISABLED_VALUES: ReadonlyArray<string> = ['off', '0', 'false', 'no']
 
 // **Read at call time, never cached at module load.** A suite that switches the variable between
-// cases — and both hooks' suites do — sees a cached answer as the guard ignoring the switch.
-function is_switch_enabled(key: string): boolean {
-	return !DISABLED_VALUES.includes((process.env[key] ?? '').trim().toLowerCase())
+// cases — and both hooks' suites do — sees a cached answer as the guard ignoring the switch. A
+// guard reads the call's own environment (`HookContext.env`); a caller with none reads the process's.
+function is_switch_enabled(key: string, environment: HookContext['env'] = process.env): boolean {
+	return !DISABLED_VALUES.includes((environment[key] ?? '').trim().toLowerCase())
 }
 
 // The opt-in counterpart of `DISABLED_VALUES`: an unset variable stays off, and only one of these
@@ -73,57 +76,7 @@ function parse_hook_payload(raw_payload: string): HookPayload | undefined {
 	return json_value.parse_with(raw_payload, payload_schema)
 }
 
-// The documented shape a `PreToolUse` hook answers with. Plain stdout is not it — only this envelope
-// stops the call, and only `permissionDecisionReason` reaches the model.
-function deny_envelope(reason: string): string {
-	return JSON.stringify({
-		hookSpecificOutput: {
-			hookEventName: HOOK_EVENT_NAME,
-			permissionDecision: DENY_DECISION,
-			permissionDecisionReason: reason,
-		},
-	})
-}
-
-// **A rewrite, not a refusal**: the call proceeds with `updated_input` merged
-// over its own and is allowed past the permission prompt; a settings `deny` rule still wins over it.
-// Where the line may carry commands the hook did not write, `flow_rewrite_envelope` is the one to use.
-function rewrite_envelope(updated_input: Record<string, unknown>, context: string): string {
-	return JSON.stringify({
-		systemMessage: context,
-		hookSpecificOutput: {
-			hookEventName: HOOK_EVENT_NAME,
-			permissionDecision: ALLOW_DECISION,
-			updatedInput: updated_input,
-			additionalContext: context,
-		},
-	})
-}
-
-// **A rewrite that leaves the permission to the harness.** No `permissionDecision`, so the rewritten
-// call meets the same permission flow the typed one would have — whatever else rides the line beside
-// the rewritten part is prompted for, or not, exactly as before (joshuafolkken/kit#3875).
-function flow_rewrite_envelope(updated_input: Record<string, unknown>, context: string): string {
-	return JSON.stringify({
-		systemMessage: context,
-		hookSpecificOutput: {
-			hookEventName: HOOK_EVENT_NAME,
-			updatedInput: updated_input,
-			additionalContext: context,
-		},
-	})
-}
-
-// **A notice, not a decision.** It carries no `permissionDecision`, so the call proceeds exactly as it
-// would have; `additionalContext` is what reaches the model, and `systemMessage` is what the person
-// watching sees. Both are filled because either channel alone leaves one of the two blind — and the
-// whole point of this envelope is that a guard which cannot look stops being invisible.
-function notice_envelope(notice: string): string {
-	return JSON.stringify({
-		systemMessage: notice,
-		hookSpecificOutput: { hookEventName: HOOK_EVENT_NAME, additionalContext: notice },
-	})
-}
+const { deny_envelope, flow_rewrite_envelope, notice_envelope, rewrite_envelope } = hook_envelope
 
 // Named after the guard that raised it rather than after any one of them: `create_transcript_guard` is
 // the shell three hooks are built from, and a fault that announced the wrong origin would send whoever
@@ -200,11 +153,9 @@ function create_refusal_stamp(prefix: string): RefusalStamp {
 	return { path, last_ms: last_refusal_ms, record: record_refusal }
 }
 
-// **`.env` is loaded here rather than through the dispatcher's `tsx_arguments`**, and the reason —
-// declaring any `tsx_arguments` disqualifies a command from in-process dispatch — is now shared with
-// every other command that has to stay in-process, so the loader lives in `josh-environment-file.ts` rather
-// than here. Re-exported under this namespace because that is where the
-// hooks reach for it.
+// **`.env` is loaded here rather than through the dispatcher's `tsx_arguments`**; the loader lives in
+// `josh-environment-file.ts`, shared with the other commands that read the file themselves.
+// Re-exported under this namespace because that is where the hooks reach for it.
 //
 // **Call it only on the real hook path**, never inside the pure refusal function, so a developer's
 // own `.env` cannot decide what the unit tests see.
@@ -218,6 +169,12 @@ const { load_environment_file } = josh_environment_file
 interface GuardRun {
 	transcript: string
 	now_ms: number
+	// The payload's own model, where the harness names one.
+	model?: string | undefined
+	// The call comes from a delegated unit (the payload names its `agent_id`), not the main line.
+	is_unit?: boolean
+	// The call's own cwd and environment, which a rule reads in place of the process's.
+	context: HookContext
 }
 
 // The notice half of a guard's rule, kept optional so a guard that only refuses supplies nothing and is
@@ -247,7 +204,7 @@ interface TranscriptGuardSpec {
 	// Whether this call is one the hook may refuse at all, judged **before** the transcript is read:
 	// most of a run's calls are ones the hook could never refuse, and a quarter-megabyte tail read for
 	// each of them would be paid inside a hook that is holding the call.
-	is_candidate: (call: GuardedCall) => boolean
+	is_candidate: (call: GuardedCall, context: HookContext) => boolean
 	// This hook's own rule, over the tail. `run` carries what a rule may need about the *run* rather
 	// than about the call — the transcript the stamps are keyed on, and the instant this decision is
 	// being made — because a rule may have to ask what **another** hook has already recorded, and
@@ -278,10 +235,10 @@ interface GuardOutcome {
 const NO_OUTCOME: GuardOutcome = { reason: undefined, notice: undefined, fault: undefined }
 
 interface TranscriptGuard {
-	is_enabled: () => boolean
+	is_enabled: (environment?: HookContext['env']) => boolean
 	refusal_path: (transcript_path: string) => string
-	refusal: (raw_payload: string, now_ms?: number) => string | undefined
-	outcome: (raw_payload: string, now_ms?: number) => GuardOutcome
+	refusal: (raw_payload: string, now_ms?: number, context?: HookContext) => string | undefined
+	outcome: (raw_payload: string, now_ms?: number, context?: HookContext) => GuardOutcome
 }
 
 interface FireResult {
@@ -365,16 +322,19 @@ function guard_reason_for_payload(
 	parts: GuardParts,
 	payload: HookPayload,
 	now_ms: number,
+	hook: HookContext,
 ): GuardOutcome {
 	const call = { name: payload.tool_name, input: payload.tool_input }
 
-	if (!parts.spec.is_candidate(call)) return NO_OUTCOME
+	if (!parts.spec.is_candidate(call, hook)) return NO_OUTCOME
 
 	// A hook firing inside a delegated unit is handed the *parent's* path, so the fork's own file is
 	// derived here rather than judged from the parent's frozen timeline.
 	const transcript = time_hook_transcript.transcript_of(payload.transcript_path, payload.agent_id)
-	const tail = time_density_hook.read_tail(transcript)
-	const context = { ...parts, tail, call, run: { transcript, now_ms } }
+	const tail = transcript_tail.read_tail(transcript)
+	const is_unit = typeof payload.agent_id === 'string' && payload.agent_id.length > 0
+	const run = { transcript, now_ms, model: payload.model ?? undefined, is_unit, context: hook }
+	const context = { ...parts, tail, call, run }
 
 	// The block path decides first, and the notice is asked only where it stayed clear. The two never
 	// both fire — a refusable call never notifies and a whole-file write never blocks — so this ordering
@@ -386,12 +346,19 @@ function guard_reason_for_payload(
 	return notify_outcome(context)
 }
 
-function guard_outcome(parts: GuardParts, raw_payload: string, now_ms: number): GuardOutcome {
+function guard_outcome(
+	parts: GuardParts,
+	raw_payload: string,
+	now_ms: number,
+	hook: HookContext,
+): GuardOutcome {
 	const payload = parse_hook_payload(raw_payload)
 
-	if (payload === undefined || !is_switch_enabled(parts.spec.switch_key)) return NO_OUTCOME
+	if (payload === undefined || !is_switch_enabled(parts.spec.switch_key, hook.env)) {
+		return NO_OUTCOME
+	}
 
-	return guard_reason_for_payload(parts, payload, now_ms)
+	return guard_reason_for_payload(parts, payload, now_ms, hook)
 }
 
 function create_transcript_guard(spec: TranscriptGuardSpec): TranscriptGuard {
@@ -401,12 +368,8 @@ function create_transcript_guard(spec: TranscriptGuardSpec): TranscriptGuard {
 	const notify_stamp = spec.notify ? create_refusal_stamp(spec.notify.prefix) : undefined
 	const parts = { spec, stamp, notify_stamp }
 
-	function is_enabled(): boolean {
-		return is_switch_enabled(spec.switch_key)
-	}
-
-	function refusal_path(transcript_path: string): string {
-		return stamp.path(transcript_path)
+	function is_enabled(environment: HookContext['env'] = process.env): boolean {
+		return is_switch_enabled(spec.switch_key, environment)
 	}
 
 	// **Every failure allows the call.** An unreadable transcript, a half-written tail, a temp directory
@@ -418,19 +381,23 @@ function create_transcript_guard(spec: TranscriptGuardSpec): TranscriptGuard {
 	// goes through — failing open is the right call and is not being revisited — but the fault comes
 	// back as text the run can see, so "the guard said nothing" and "the guard could not look" stop
 	// being the same observation.
-	function outcome(raw_payload: string, now_ms: number = Date.now()): GuardOutcome {
+	function outcome(
+		raw_payload: string,
+		now_ms: number = Date.now(),
+		hook: HookContext = hook_context.from_process(),
+	): GuardOutcome {
 		try {
-			return guard_outcome(parts, raw_payload, now_ms)
+			return guard_outcome(parts, raw_payload, now_ms, hook)
 		} catch (error) {
 			return { reason: undefined, notice: undefined, fault: fault_notice(spec.switch_key, error) }
 		}
 	}
 
-	function refusal(raw_payload: string, now_ms: number = Date.now()): string | undefined {
-		return outcome(raw_payload, now_ms).reason
+	function refusal(...call: Parameters<typeof outcome>): string | undefined {
+		return outcome(...call).reason
 	}
 
-	return { is_enabled, outcome, refusal, refusal_path }
+	return { is_enabled, outcome, refusal, refusal_path: stamp.path }
 }
 
 // Write one already-resolved outcome, so a caller that has to await its rule (the watcher guard reads
@@ -445,28 +412,6 @@ function emit_outcome(outcome: GuardOutcome): void {
 	else if (fault !== undefined) process.stdout.write(`${notice_envelope(fault)}\n`)
 }
 
-// The synchronous path: load `.env`, run the rule, emit. A wrapper around `emit_outcome` so both paths
-// write the same envelopes.
-function write_outcome(raw_payload: string, outcome: (raw: string) => GuardOutcome): void {
-	load_environment_file()
-
-	emit_outcome(outcome(raw_payload))
-}
-
-// The refusal-only shape, kept so the guards not yet moved across keep working unchanged. It is a
-// wrapper rather than a second implementation, so both paths write the same envelopes.
-//
-// **A guard still calling this discards any fault it raised** — `investigation-guard.ts` is the one
-// that does, so a stamp it could not write there is still silent — the gap the batching guard no
-// longer has. Moving another hook across belongs with its own test.
-function write_decision(raw_payload: string, refusal: (raw: string) => string | undefined): void {
-	write_outcome(raw_payload, (raw) => ({
-		reason: refusal(raw),
-		notice: undefined,
-		fault: undefined,
-	}))
-}
-
 // Run from a terminal there is no payload coming, and waiting for one looks like a hang.
 function report_no_payload(command: string): void {
 	process.stderr.write(
@@ -489,6 +434,7 @@ async function respond_from_stdin(
 	const raw_payload = await text(process.stdin)
 
 	load_environment_file()
+	hook_payload_capture.capture(command, raw_payload)
 	await respond(raw_payload)
 }
 
@@ -500,19 +446,15 @@ const hook_decision = {
 	create_transcript_guard,
 	deny_envelope,
 	emit_outcome,
-	fault_notice,
 	flow_rewrite_envelope,
 	is_switch_enabled,
 	is_switch_opt_in,
 	load_environment_file,
 	notice_envelope,
 	parse_hook_payload,
-	report_no_payload,
 	respond_from_stdin,
 	rewrite_envelope,
 	stamp_fault,
-	write_decision,
-	write_outcome,
 }
 
 export type { GuardOutcome, GuardRun, TranscriptGuard, TranscriptGuardSpec }

package/scripts/josh/hook-envelope.ts

@@ -0,0 +1,62 @@
+// The JSON envelopes a `PreToolUse` hook answers with, held apart from `hook-decision.ts` (which
+// re-exports them under its namespace) because each is a pure function of its arguments.
+
+const HOOK_EVENT_NAME = 'PreToolUse'
+const DENY_DECISION = 'deny'
+const ALLOW_DECISION = 'allow'
+
+// The documented shape a `PreToolUse` hook answers with. Plain stdout is not it — only this envelope
+// stops the call, and only `permissionDecisionReason` reaches the model.
+function deny_envelope(reason: string): string {
+	return JSON.stringify({
+		hookSpecificOutput: {
+			hookEventName: HOOK_EVENT_NAME,
+			permissionDecision: DENY_DECISION,
+			permissionDecisionReason: reason,
+		},
+	})
+}
+
+// **A rewrite, not a refusal**: the call proceeds with `updated_input` merged
+// over its own and is allowed past the permission prompt; a settings `deny` rule still wins over it.
+// Where the line may carry commands the hook did not write, `flow_rewrite_envelope` is the one to use.
+function rewrite_envelope(updated_input: Record<string, unknown>, context: string): string {
+	return JSON.stringify({
+		systemMessage: context,
+		hookSpecificOutput: {
+			hookEventName: HOOK_EVENT_NAME,
+			permissionDecision: ALLOW_DECISION,
+			updatedInput: updated_input,
+			additionalContext: context,
+		},
+	})
+}
+
+// **A rewrite that leaves the permission to the harness.** No `permissionDecision`, so the rewritten
+// call meets the same permission flow the typed one would have — whatever else rides the line beside
+// the rewritten part is prompted for, or not, exactly as before (joshuafolkken/kit#3875).
+function flow_rewrite_envelope(updated_input: Record<string, unknown>, context: string): string {
+	return JSON.stringify({
+		systemMessage: context,
+		hookSpecificOutput: {
+			hookEventName: HOOK_EVENT_NAME,
+			updatedInput: updated_input,
+			additionalContext: context,
+		},
+	})
+}
+
+// **A notice, not a decision.** It carries no `permissionDecision`, so the call proceeds exactly as it
+// would have; `additionalContext` is what reaches the model, and `systemMessage` is what the person
+// watching sees. Both are filled because either channel alone leaves one of the two blind — and the
+// whole point of this envelope is that a guard which cannot look stops being invisible.
+function notice_envelope(notice: string): string {
+	return JSON.stringify({
+		systemMessage: notice,
+		hookSpecificOutput: { hookEventName: HOOK_EVENT_NAME, additionalContext: notice },
+	})
+}
+
+const hook_envelope = { deny_envelope, flow_rewrite_envelope, notice_envelope, rewrite_envelope }
+
+export { hook_envelope }

package/scripts/josh/hook-payload-capture.ts

@@ -0,0 +1,78 @@
+import { mkdirSync, readdirSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+import { json_value } from '#scripts/lib/json-value'
+import { z } from 'zod'
+
+// The raw stdin payload a hook was handed, kept on disk when `JOSH_HOOK_CAPTURE_DIR` names a directory
+// (joshuafolkken/kit#6588). Claude Code and Codex hand the same hook differently shaped payloads, and
+// the replay test (`scripts/hooks/hook-payload-replay.test.ts`) runs the fixtures captured this way
+// through the guards, so a provider's real input is pinned before a review lane meets it.
+//
+// **Capturing never decides the call.** A directory that cannot be written leaves the hook exactly as
+// it was without the variable.
+
+const CAPTURE_DIR_KEY = 'JOSH_HOOK_CAPTURE_DIR'
+const NO_TOOL = 'none'
+const FILE_EXTENSION = '.json'
+const UNSAFE_NAME_CHARACTERS = /[^\w.-]/gu
+// More parallel calls than one turn issues, so a collision never runs out of indexes.
+const MAX_ATTEMPTS = 32
+
+const tool_schema = z.looseObject({ tool_name: z.string().min(1) })
+
+function safe_name(name: string): string {
+	return name.replaceAll(UNSAFE_NAME_CHARACTERS, '-')
+}
+
+function tool_label(raw_payload: string): string {
+	return safe_name(json_value.parse_with(raw_payload, tool_schema)?.tool_name ?? NO_TOOL)
+}
+
+function write_new(file: string, raw_payload: string): boolean {
+	try {
+		writeFileSync(file, raw_payload, { flag: 'wx' })
+
+		return true
+	} catch {
+		return false
+	}
+}
+
+// `<hook>-<tool>-<n>.json`, `n` counted from one past the captures of that hook and tool already in
+// `directory`. Parallel tool calls run their hooks at once and a moved capture leaves a gap, so a
+// taken `n` moves on to the next rather than dropping the payload.
+function write_capture(directory: string, hook: string, raw_payload: string): string | undefined {
+	const prefix = `${safe_name(hook)}-${tool_label(raw_payload)}-`
+	const first = readdirSync(directory).filter((name) => name.startsWith(prefix)).length + 1
+
+	for (let index = first; index < first + MAX_ATTEMPTS; index += 1) {
+		const file = path.join(directory, `${prefix}${String(index)}${FILE_EXTENSION}`)
+
+		if (write_new(file, raw_payload)) return file
+	}
+
+	return undefined
+}
+
+// The file written, or undefined when capture is off or the directory could not take it.
+function capture(
+	hook: string,
+	raw_payload: string,
+	environment: NodeJS.ProcessEnv = process.env,
+): string | undefined {
+	const directory = environment[CAPTURE_DIR_KEY]
+	if (directory === undefined || directory === '') return undefined
+
+	try {
+		mkdirSync(directory, { recursive: true })
+
+		return write_capture(directory, hook, raw_payload)
+	} catch {
+		// A directory that cannot be made or listed: the call goes on uncaptured.
+		return undefined
+	}
+}
+
+const hook_payload_capture = { CAPTURE_DIR_KEY, capture }
+
+export { hook_payload_capture }

package/scripts/josh/hook-tool-payload.ts

@@ -0,0 +1,15 @@
+import { json_value } from '#scripts/lib/json-value'
+import { z } from 'zod'
+
+const schema = z.object({
+	tool_name: z.string().min(1),
+	tool_input: z.unknown(),
+})
+
+function parse(raw_payload: string): z.infer<typeof schema> | undefined {
+	return json_value.parse_with(raw_payload, schema)
+}
+
+const hook_tool_payload = { parse, schema }
+
+export { hook_tool_payload }

package/scripts/josh/josh-aliases.ts

@@ -9,6 +9,7 @@ const ALIASES: Record<string, string> = {
 	ga: 'gate',
 	l: 'lint',
 	lr: 'lint:related',
+	lrr: 'lint:rule',
 	cr: 'check:related',
 	ln: 'lines',
 	by: 'bytes',
@@ -35,6 +36,7 @@ const ALIASES: Record<string, string> = {
 	gp: 'pr',
 	ms: 'main:sync',
 	mm: 'main:merge',
+	ckf: 'checks:failed',
 	bp: 'bump',
 	re: 'release',
 	v: 'version',
@@ -54,9 +56,12 @@ const ALIASES: Record<string, string> = {
 	tmd: 'time:density',
 	rtr: 'retrospective',
 	ca: 'cost:audit',
+	cit: 'ci:timing',
+	ghu: 'gh:usage',
 	rvf: 'review:findings',
 	rvs: 'review:stops',
 	ruv: 'rule:value',
+	hkl: 'hook:ledger',
 	ev: 'eval',
 	fr: 'fresh:run',
 	as: 'auth:setup',
@@ -65,9 +70,11 @@ const ALIASES: Record<string, string> = {
 	lva: 'lane:value',
 	lnt: 'lane:net',
 	lbd: 'lane:breakdown',
+	lwy: 'lane:why',
 	lli: 'lane:limit',
 	lrs: 'lane:restart',
 	lwd: 'lane:withdraw',
+	lrv: 'lane:resolve',
 	lps: 'lane:pause',
 	lru: 'lane:resume',
 	lad: 'lane:adopt',