@joshuafolkken/kit 1.2116.0 → 1.3000.0

package/scripts/rules/bash-triggers.ts

@@ -2,6 +2,7 @@ import { cost_blocks } from '#scripts/cost-runtime/cost-blocks'
 import type { GuardedCall } from '#scripts/time-runtime/time-batch-guard'
 import { time_shell } from '#scripts/time-runtime/time-shell'
 import { git_argv } from './git-argv'
+import { interpreter_options } from './interpreter-options'
 import { shell_segments } from './shell-segments'
 
 // The trigger helpers the enumeration in `delivered-rules.ts` is built from, held here so a rule
@@ -14,11 +15,14 @@ import { shell_segments } from './shell-segments'
 // not. Every rule delivered by the enumeration is therefore one whose binding moment is a shell call —
 // so the tool-name guard belongs here rather than to each row, and a row states only what it looks for
 // in the command.
-function on_bash_command(is_match: (command: string) => boolean): (call: GuardedCall) => boolean {
-	return function is_trigger(call: GuardedCall): boolean {
+// The arguments after the call (the hook call's context) are handed on to the command test.
+function on_bash_command<Rest extends ReadonlyArray<unknown>>(
+	is_match: (command: string, ...rest: Rest) => boolean,
+): (call: GuardedCall, ...rest: Rest) => boolean {
+	return function is_trigger(call: GuardedCall, ...rest: Rest): boolean {
 		if (call.name !== cost_blocks.BASH_TOOL) return false
 
-		return is_match(time_shell.bash_command(call.input))
+		return is_match(time_shell.bash_command(call.input), ...rest)
 	}
 }
 
@@ -57,7 +61,6 @@ function spoken_line(command: string): string {
 }
 
 const LEADING_SHELL_SCRIPT_RUNNER = new RegExp(`^${SHELL_SCRIPT_RUNNER.source}`, 'u')
-const QUOTE_MARK = /["']/gu
 
 // The quoted script a segment's shell runs, as a line of its own: `sh -c 'pnpm exec eslint .'` reads
 // as `pnpm exec eslint .`, so a caller cutting it into commands reads the programs the script
@@ -65,15 +68,14 @@ const QUOTE_MARK = /["']/gu
 // `undefined` when the segment runs no shell script.
 function shell_script_of(segment: string): string | undefined {
 	const call = git_argv.program_of(segment)
-
 	if (call === undefined) return undefined
-
 	const spoken = [call.name, ...call.args].join(' ')
-	const runner = LEADING_SHELL_SCRIPT_RUNNER.exec(spoken)
+	if (!LEADING_SHELL_SCRIPT_RUNNER.test(spoken)) return undefined
 
-	if (runner === null) return undefined
+	const index = interpreter_options.shell_script_index(call)
+	const script = call.name === 'eval' ? call.args.join(' ') : (call.args[index + 1] ?? '')
 
-	return spoken.slice(runner[0].length).replaceAll(QUOTE_MARK, '').trim()
+	return script.replace(/^(["'])([\s\S]*)\1$/u, '$2')
 }
 
 function is_direct_filing(command: string): boolean {
@@ -89,12 +91,21 @@ function is_direct_filing(command: string): boolean {
 // spelling quoted inside another command's body is not read as a filing.
 const FILING_NAMES: ReadonlySet<string> = new Set(['issue:file'])
 
+// One segment of a command line, for a reader that also judges the segment's own flags.
+function is_issue_filing_segment(segment: string): boolean {
+	return shell_segments.is_josh_command(segment, FILING_NAMES)
+}
+
 function is_issue_filing(command: string): boolean {
-	return shell_segments
-		.segments_of(command)
-		.some((segment) => shell_segments.is_josh_command(segment, FILING_NAMES))
+	return shell_segments.segments_of(command).some((segment) => is_issue_filing_segment(segment))
 }
 
-const bash_triggers = { is_direct_filing, is_issue_filing, on_bash_command, shell_script_of }
+const bash_triggers = {
+	is_direct_filing,
+	is_issue_filing,
+	is_issue_filing_segment,
+	on_bash_command,
+	shell_script_of,
+}
 
 export { bash_triggers }

package/scripts/rules/broad-investigation-shell.ts

@@ -0,0 +1,183 @@
+import { readFileSync, statSync } from 'node:fs'
+import path from 'node:path'
+import { time_josh_names } from '#scripts/time-runtime/time-josh-names'
+import { shell_segments } from './shell-segments'
+
+// Which shell commands are broad investigation (joshuafolkken/kit#5351): a search over a tree, a
+// read past the line cap, an aggregation script. A narrow check — a bounded range of one file, a
+// search of one file — is not, so a consultation main line can still verify a cited line itself.
+
+// **The cap on one narrow read**, shared by `Read`'s `limit` and the shell readers' ranges.
+const READ_LINE_CAP = 200
+const DEFAULT_HEAD_LINES = 10
+const SHORT_FLAGS = /^-[a-zA-Z]+$/u
+const RECURSIVE_LETTERS = /[rR]/u
+const LONG_RECURSIVE: ReadonlySet<string> = new Set(['--recursive', '--dereference-recursive'])
+const SED_RANGE = /^(?<first>\d+),(?<last>\d+)p$/u
+const SED_TO_END = /^\d+,\$p$/u
+const LINE_COUNT_PREFIXES = ['--lines=', '-n', '-']
+const DIGITS = /^\d+$/u
+const FROM_LINE = /^\+\d+$/u
+const QUOTES = /^['"]|['"]$/gu
+const WHITESPACE = /\s+/u
+const ASSIGNMENT = /^\w+=/u
+const ALWAYS_BROAD: ReadonlySet<string> = new Set(['find', 'for', 'node', 'python', 'python3'])
+const ANALYSIS_PREFIX = 'josh cost:'
+const FLAG_PREFIX = '-'
+const HEREDOC = '<<'
+
+// `is_piped`: the command is a later stage of a pipeline, so a reader naming no file reads the pipe.
+type CommandTest = (
+	operands: ReadonlyArray<string>,
+	flags: ReadonlyArray<string>,
+	is_piped: boolean,
+) => boolean
+
+function resolved(file: string): string {
+	return path.resolve(process.env['JOSH_HOOK_CWD'] ?? process.cwd(), file)
+}
+
+function is_file(file: string): boolean {
+	return statSync(resolved(file), { throwIfNoEntry: false })?.isFile() === true
+}
+
+function is_directory(file: string): boolean {
+	return statSync(resolved(file), { throwIfNoEntry: false })?.isDirectory() === true
+}
+
+// A final newline ends the last line rather than starting another.
+function line_count(file: string): number {
+	if (!is_file(file)) return 0
+	const text = readFileSync(resolved(file), 'utf8')
+
+	return text.split('\n').length - (text.endsWith('\n') ? 1 : 0)
+}
+
+function is_recursive_flag(flag: string): boolean {
+	return LONG_RECURSIVE.has(flag) || (SHORT_FLAGS.test(flag) && RECURSIVE_LETTERS.test(flag))
+}
+
+// A search names one file at most past its pattern; any directory is a tree.
+function searches_tree(operands: ReadonlyArray<string>, flags: ReadonlyArray<string>): boolean {
+	if (flags.some((flag) => is_recursive_flag(flag))) return true
+
+	return operands.slice(1).some((operand) => is_directory(operand))
+}
+
+// `rg` recurses by default, so naming no path at all searches the tree — unless it reads a pipe.
+function rg_searches_tree(
+	operands: ReadonlyArray<string>,
+	_flags: ReadonlyArray<string>,
+	is_piped: boolean,
+): boolean {
+	const paths = operands.slice(1)
+	if (paths.length === 0) return !is_piped
+
+	return paths.some((operand) => !is_file(operand))
+}
+
+function sed_span(script: string): number {
+	const groups = SED_RANGE.exec(script)?.groups
+
+	return groups === undefined ? 0 : Number(groups['last']) - Number(groups['first']) + 1
+}
+
+// Only a `-n` print range is a read; one past the cap, or to the end of the file, is broad.
+function sed_reads_past_cap(
+	operands: ReadonlyArray<string>,
+	flags: ReadonlyArray<string>,
+): boolean {
+	if (!flags.includes('-n')) return false
+	const [script = ''] = operands
+
+	return SED_TO_END.test(script) || sed_span(script) > READ_LINE_CAP
+}
+
+function number_of(word = ''): number | undefined {
+	return DIGITS.test(word) ? Number(word) : undefined
+}
+
+// `-nN`, `-N` or `--lines=N`; `undefined` for a word that is none of them.
+function count_of(word: string): number | undefined {
+	const prefix = LINE_COUNT_PREFIXES.find((candidate) => word.startsWith(candidate))
+	const rest = prefix === undefined ? '' : word.slice(prefix.length)
+
+	return number_of(rest)
+}
+
+// A bare `-n` takes its count as a word of its own: the first operand, wherever the flags sit.
+function counted_lines(operands: ReadonlyArray<string>, flags: ReadonlyArray<string>): number {
+	const inline = flags.map((flag) => count_of(flag)).find((count) => count !== undefined)
+	const separate = flags.includes('-n') ? number_of(operands[0]) : undefined
+
+	return inline ?? separate ?? DEFAULT_HEAD_LINES
+}
+
+// `head` / `tail` read past the cap by count, or to the end from a `+N` start.
+function ends_past_cap(operands: ReadonlyArray<string>, flags: ReadonlyArray<string>): boolean {
+	if (operands.some((word) => FROM_LINE.test(word))) return true
+
+	return counted_lines(operands, flags) > READ_LINE_CAP
+}
+
+// A whole-file read of this file runs past the cap; a missing file reads nothing.
+function is_past_cap(file: string): boolean {
+	return line_count(file) > READ_LINE_CAP
+}
+
+function cat_reads_past_cap(operands: ReadonlyArray<string>): boolean {
+	return operands.some((operand) => is_past_cap(operand))
+}
+
+const COMMAND_TESTS: ReadonlyMap<string, CommandTest> = new Map([
+	['grep', searches_tree],
+	['rg', rg_searches_tree],
+	['sed', sed_reads_past_cap],
+	['head', ends_past_cap],
+	['tail', ends_past_cap],
+	['cat', cat_reads_past_cap],
+])
+
+function words_of(segment: string): Array<string> {
+	const words = segment.split(WHITESPACE).map((word) => word.replaceAll(QUOTES, ''))
+	const start = words.findIndex((word) => !ASSIGNMENT.test(word))
+
+	return start === -1 ? [] : words.slice(start)
+}
+
+// A reader whose input is a heredoc reads nothing from disk.
+function reads_past_cap(
+	segment: string,
+	name: string,
+	rest: ReadonlyArray<string>,
+	is_piped: boolean,
+): boolean {
+	const test = COMMAND_TESTS.get(name)
+	if (test === undefined || segment.includes(HEREDOC)) return false
+	const flags = rest.filter((word) => word.startsWith(FLAG_PREFIX))
+	const operands = rest.filter((word) => !word.startsWith(FLAG_PREFIX))
+
+	return test(operands, flags, is_piped)
+}
+
+function is_broad_segment(segment: string, is_piped: boolean): boolean {
+	if (time_josh_names.josh_command_of(segment).startsWith(ANALYSIS_PREFIX)) return true
+	const [name = '', ...rest] = words_of(segment)
+
+	return ALWAYS_BROAD.has(name) || reads_past_cap(segment, name, rest, is_piped)
+}
+
+// Every stage past a pipeline's first reads the stage before it.
+function is_broad_pipeline(pipeline: string): boolean {
+	return shell_segments
+		.quote_aware_commands_of(pipeline)
+		.some((stage, index) => is_broad_segment(stage, index > 0))
+}
+
+function is_broad_command(command: string): boolean {
+	return shell_segments.segments_of(command).some((pipeline) => is_broad_pipeline(pipeline))
+}
+
+const broad_investigation_shell = { READ_LINE_CAP, is_broad_command, is_file, is_past_cap }
+
+export { broad_investigation_shell }

package/scripts/rules/broad-investigation.ts

@@ -0,0 +1,116 @@
+import { readFileSync } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { agent_consultation_model } from '#scripts/agent/agent-consultation-model'
+import { find_package_directory } from '#scripts/josh/package-directory'
+import { json_value } from '#scripts/lib/json-value'
+import type { GuardedCall } from '#scripts/time-runtime/time-batch-guard'
+import { time_shell } from '#scripts/time-runtime/time-shell'
+import { agent_model } from './agent-model'
+import { broad_investigation_shell } from './broad-investigation-shell'
+
+// Which tool calls are broad investigation (joshuafolkken/kit#5351) — the reading a consultation main
+// line hands to a subagent instead of paying its own rate for. The shell half is
+// `broad-investigation-shell.ts`.
+
+const { READ_LINE_CAP, is_broad_command, is_file, is_past_cap } = broad_investigation_shell
+
+const ALWAYS_BROAD: ReadonlySet<string> = new Set(['Glob', 'WebFetch'])
+const GENERAL_PURPOSE = 'general-purpose'
+// The dispatches that investigate: the read-only unit and the two catch-all types.
+const INVESTIGATION_AGENTS: ReadonlySet<string> = new Set([
+	'investigator',
+	'Explore',
+	GENERAL_PURPOSE,
+])
+const FRONTMATTER_MODEL = /^model:\s*(?<model>\S+)\s*$/mu
+const PACKAGE_DIRECTORY = find_package_directory(path.dirname(fileURLToPath(import.meta.url)))
+
+function field(call: GuardedCall, key: string): unknown {
+	return json_value.is_record(call.input) ? call.input[key] : undefined
+}
+
+// A `Read` with no `limit` reads the whole file, so it is broad only when the file runs past the cap.
+function is_broad_read(call: GuardedCall): boolean {
+	const limit = field(call, 'limit')
+	if (typeof limit === 'number') return limit > READ_LINE_CAP
+	const file = field(call, 'file_path')
+
+	return typeof file !== 'string' || is_past_cap(file)
+}
+
+// A `Grep` is narrow only when its `path` is one file.
+function is_broad_grep(call: GuardedCall): boolean {
+	const target = field(call, 'path')
+
+	return typeof target !== 'string' || !is_file(target)
+}
+
+// The model an agent definition names, read from the kit's own `.claude/agents/` (`kit:investigator`
+// in a consumer is the same file); `undefined` for a built-in type, which inherits.
+function definition_model(name: string): string | undefined {
+	const file = path.join(PACKAGE_DIRECTORY, '.claude', 'agents', `${name}.md`)
+	const body = is_file(file) ? readFileSync(file, 'utf8') : ''
+
+	return FRONTMATTER_MODEL.exec(body)?.groups?.['model']
+}
+
+// The dispatched type without its plugin prefix (`kit:investigator` → `investigator`).
+function agent_name(call: GuardedCall): string {
+	const type = field(call, 'subagent_type')
+	if (typeof type !== 'string') return GENERAL_PURPOSE
+
+	return type.split(':').at(-1) ?? type
+}
+
+function effective_model(call: GuardedCall, name: string): string | undefined {
+	const named = field(call, 'model')
+
+	return typeof named === 'string' && named.length > 0 ? named : definition_model(name)
+}
+
+// An investigation dispatch's effective model — its `model`, else its definition's; `undefined` for
+// a non-investigation call or one inheriting the main line's own.
+function dispatched_model(call: GuardedCall): string | undefined {
+	return effective_model(call, agent_name(call))
+}
+
+function is_investigation_dispatch(call: GuardedCall): boolean {
+	return agent_model.SUBAGENT_TOOLS.has(call.name) && INVESTIGATION_AGENTS.has(agent_name(call))
+}
+
+function is_consultation(model: string | undefined): boolean {
+	return model === undefined || agent_consultation_model.consultation_provider(model) !== undefined
+}
+
+// An investigation dispatch whose effective model would be the consultation model.
+function inherits_consultation(call: GuardedCall): boolean {
+	if (!INVESTIGATION_AGENTS.has(agent_name(call))) return false
+
+	return is_consultation(dispatched_model(call))
+}
+
+// The kept form: the investigation handed to a unit on a model other than the consultation one.
+function is_delegated_investigation(call: GuardedCall): boolean {
+	return is_investigation_dispatch(call) && !is_consultation(dispatched_model(call))
+}
+
+const TOOL_TESTS: ReadonlyMap<string, (call: GuardedCall) => boolean> = new Map([
+	['Read', is_broad_read],
+	['Grep', is_broad_grep],
+	['Bash', (call: GuardedCall): boolean => is_broad_command(time_shell.bash_command(call.input))],
+	...[...agent_model.SUBAGENT_TOOLS].map((name): [string, (call: GuardedCall) => boolean] => [
+		name,
+		inherits_consultation,
+	]),
+])
+
+function is_broad_investigation(call: GuardedCall): boolean {
+	if (ALWAYS_BROAD.has(call.name)) return true
+
+	return TOOL_TESTS.get(call.name)?.(call) === true
+}
+
+const broad_investigation = { READ_LINE_CAP, is_broad_investigation, is_delegated_investigation }
+
+export { broad_investigation }

package/scripts/rules/consultation-handoff.ts

@@ -0,0 +1,81 @@
+import { agent_consultation_model } from '#scripts/agent/agent-consultation-model'
+import type { GuardRun } from '#scripts/josh/hook-decision'
+import { lane_child_marker } from '#scripts/lane/lane-child-marker'
+import { bash_triggers } from './bash-triggers'
+import type { DeliveredRule } from './delivered-rules'
+import { main_model_reader } from './main-model'
+import { shell_segments } from './shell-segments'
+
+// A consultation main line hands a workflow keyword to a child session (joshuafolkken/kit#5616).
+//
+// **The entry is the boundary.** A main line on the consultation model (Fable, Codex Astra) files and
+// operates, but a run it entered itself would implement at that model's rate, so the claim of the tree
+// — `run:entry`, `run:hold` — is refused and `run:handoff` starts the run on the role profile's model.
+// Filing and operating (`issue:file`, `issue:plan`, `epic`) are never refused.
+//
+// **It fires on every occurrence**: the remedy is one command, so a refusal never wedges the run. The
+// handed child runs on the role profile's model, so it enters through `run:entry` untouched.
+
+const HANDOFF_DOC = '`docs/josh-commands-board.md` → "josh run:handoff"'
+
+const REASON =
+	'⛔ consultation handoff: a consultation-model main line does not enter a run itself. Run ' +
+	'`pnpm josh run:handoff <keyword> … --brief-file <brief>` instead of `run:entry` / `run:hold`; ' +
+	`filing and operating (\`issue:file\`, \`issue:plan\`, \`epic\`) stay here. Fires on every occurrence (${HANDOFF_DOC}).`
+
+function josh_call_of(names: ReadonlyArray<string>): (command: string) => boolean {
+	const name_set: ReadonlySet<string> = new Set(names)
+
+	return function is_josh_call(command: string): boolean {
+		return shell_segments
+			.segments_of(command)
+			.some((segment) => shell_segments.is_josh_command(segment, name_set))
+	}
+}
+
+const is_entry_call = josh_call_of(['run:entry', 'run:hold'])
+const is_handoff_call = josh_call_of(['run:handoff'])
+
+// An unnamed model stays silent rather than guessing. The `session-lang` prompt hook asks it too.
+function is_consultation_main(
+	tail: string,
+	payload_model: string | undefined,
+	recorded_model?: string,
+): boolean {
+	const model = main_model_reader.main_model(tail, payload_model, recorded_model)
+
+	return model !== undefined && agent_consultation_model.consultation_provider(model) !== undefined
+}
+
+// A delegated unit enters no run.
+function is_not_consultation_main(tail: string, _call: unknown, run: GuardRun): boolean {
+	if (lane_child_marker.is_child_of(run.context.cwd, run.context.env)) return true
+
+	return run.is_unit === true || !is_consultation_main(tail, run.model)
+}
+
+const ROW: DeliveredRule = {
+	id: 'consultation-handoff',
+	is_trigger: bash_triggers.on_bash_command(is_entry_call),
+	reason: REASON,
+	already_satisfied: is_not_consultation_main,
+	decide: (): boolean => true,
+	keeps: bash_triggers.on_bash_command(is_handoff_call),
+	about: {
+		title: 'Consultation main line hands a run to run:handoff',
+		topic: HANDOFF_DOC,
+		fires: '`pnpm josh run:entry` / `run:hold` on Fable or Codex Astra. Every occurrence',
+		quiet:
+			'a lane child, a main line on any other model, an unnamed model, a delegated unit, or filing and operating (`issue:file`, `issue:plan`, `epic`)',
+	},
+}
+
+const consultation_handoff = {
+	HANDOFF_DOC,
+	ROW,
+	is_consultation_main,
+	is_entry_call,
+	is_handoff_call,
+}
+
+export { consultation_handoff }

package/scripts/rules/consultation-investigation.ts

@@ -0,0 +1,99 @@
+import { agent_consultation_model } from '#scripts/agent/agent-consultation-model'
+import { agent_provider, type AgentProvider } from '#scripts/agent/agent-provider'
+import { agent_role_profile } from '#scripts/agent/agent-role-profile'
+import { agent_session_role } from '#scripts/agent/agent-session-role'
+import type { GuardRun } from '#scripts/josh/hook-decision'
+import type { GuardedCall } from '#scripts/time-runtime/time-batch-guard'
+import { broad_investigation } from './broad-investigation'
+import type { DeliveredRule, RuleAbout } from './delivered-rules'
+import { main_model_reader } from './main-model'
+
+// A consultation main line refuses its own broad investigation (joshuafolkken/kit#5351).
+//
+// **The rate is the cost, not the reading.** The consultation main line (Opus by default, Fable or
+// Codex Astra where a person picks one) pays its rate for every byte it reads, so a survey, a tree
+// search or a long read goes to a subagent on the provider's investigation model. A narrow check of
+// one cited line stays in the main line, so it can still verify what the unit returned.
+//
+// **It fires on every occurrence**: the remedy is the same reading through a unit, so a refusal costs
+// one round trip and never wedges the run. A launched session is never refused.
+
+const { ANTHROPIC_PROVIDER, OPENAI_PROVIDER } = agent_provider
+const { READ_LINE_CAP, is_broad_investigation, is_delegated_investigation } = broad_investigation
+const DELEGATION = '.claude/skills/workflow-commands/delegation.md'
+const TOPIC = `\`${DELEGATION}\` → "A consultation main line hands its investigation to a unit"`
+const NARROW_EXAMPLE = `\`Read\` of a file or an \`offset\` / \`limit\` range <= ${String(READ_LINE_CAP)} lines, \`grep -n <pattern> <one file>\``
+
+const QUIET = `a launched session (lane, reviewer, scheduler), a delegated unit, a main line at or below the investigation rate (Sonnet, Haiku, Sol), on another provider's or an unnamed model, or a narrow check (${NARROW_EXAMPLE})`
+
+type Satisfied = (tail: string, call: GuardedCall, run: GuardRun) => boolean
+
+function reason(provider: AgentProvider, dispatch: string): string {
+	const model = agent_role_profile.investigation_model(provider)
+
+	return (
+		// The dispatch opens the reason, so the Claude and Codex rows keep distinct signatures.
+		`⛔ consultation investigation → ${dispatch} on \`${model}\`: the consultation main line hands ` +
+		`broad investigation to it, and it returns \`file:line\` citations. ` +
+		`Keep only a narrow check here — ${NARROW_EXAMPLE}. It fires on every occurrence (\`${DELEGATION}\`).`
+	)
+}
+
+// The consultation main line is the session no kit launcher started (joshuafolkken/kit#6901), told
+// apart by its launch, not its model: it runs on Opus, the same model a lane does. A launched session
+// has its reading budgeted by its own guards, and a delegated unit — the Fable `design-consultant`
+// among them — has no `Agent` tool to hand the reading to. A main line on another provider's model
+// is the other row's, and one at or below the investigation rate has nothing cheaper to hand to; an
+// unnamed model stays silent rather than guessing.
+function is_handed_on(provider: AgentProvider, model: string | undefined): boolean {
+	return model !== undefined && agent_consultation_model.rated_provider(model) === provider
+}
+
+function not_consulted_on(provider: AgentProvider): Satisfied {
+	return function not_consulted(tail: string, _call: GuardedCall, run: GuardRun): boolean {
+		if (run.is_unit === true || agent_session_role.is_launched(run.context.env)) return true
+
+		return !is_handed_on(provider, main_model_reader.main_model(tail, run.model))
+	}
+}
+
+function row(
+	id: string,
+	provider: AgentProvider,
+	dispatch: string,
+	about: RuleAbout,
+): DeliveredRule {
+	return {
+		id,
+		is_trigger: is_broad_investigation,
+		// Read at delivery, not import: the hook loads `.env`, which may name the investigation model,
+		// only after the rows are imported.
+		get reason(): string {
+			return reason(provider, dispatch)
+		},
+		already_satisfied: not_consulted_on(provider),
+		decide: (): boolean => true,
+		keeps: is_delegated_investigation,
+		about,
+	}
+}
+
+const ROW = row('consultation-investigation', ANTHROPIC_PROVIDER, 'an `investigator`', {
+	title: 'Consultation main line delegates investigation (Claude)',
+	topic: TOPIC,
+	fires:
+		'a broad investigation call — `Glob`, `WebFetch`, a `Read` past the line cap, a tree `Grep` or shell search, an investigation dispatch inheriting the model — on the consultation main line on Opus or Fable. Every occurrence',
+	quiet: QUIET,
+})
+
+const CODEX_ROW = row('consultation-investigation-codex', OPENAI_PROVIDER, 'a Codex subagent', {
+	title: 'Consultation main line delegates investigation (Codex)',
+	topic: TOPIC,
+	fires:
+		'a broad shell investigation on the consultation main line on Codex Astra. Every occurrence',
+	quiet: QUIET,
+})
+
+const consultation_investigation = { CODEX_ROW, ROW }
+
+export { consultation_investigation }

package/scripts/rules/decision-oracle.ts

@@ -208,7 +208,7 @@ const DECISION_ORACLES: ReadonlyArray<DecisionOracle> = [
 			'Whether each in-progress issue holds a live lane, and the two-directional difference',
 		args: '',
 		vocabulary: [LIVE, STOPPED, UNKNOWN],
-		single_source: 'docs/josh-commands-run.md → The `in-progress` / lane difference',
+		single_source: 'docs/josh-commands-lane.md → The `in-progress` / lane difference',
 	},
 	RUN_ENTRY_ORACLE,
 ]

package/scripts/rules/delivered-rules-guard.ts

@@ -0,0 +1,94 @@
+import { will_refuse as will_batch_refuse } from '#scripts/hooks/batch-guard'
+import {
+	hook_decision,
+	type GuardRun,
+	type TranscriptGuard,
+	type TranscriptGuardSpec,
+} from '#scripts/josh/hook-decision'
+import { time_batch_guard, type GuardedCall } from '#scripts/time-runtime/time-batch-guard'
+import type { DeliveredRule } from './delivered-rules'
+
+// The transcript guard each delivered row runs as (`delivered-rules.ts`). The row reads the cwd and
+// environment of the call it judges from the guard's context, never the process's; a `call_only` row
+// reads neither.
+
+// The escape hatch, on by default like the other two guards.
+const SWITCH_ENV_KEY = 'JOSH_RULE_GUARD'
+
+const STAMP_PREFIX = 'josh-rule-guard-'
+
+// Once per run, so a run that obeyed is never wedged. A call the batching guard may refuse is stepped
+// aside from: only one hook's reason surfaces per call, and a stamp written for a lost reason would
+// silence the rule for the run. The rule delivers on the reissue instead.
+const BATCH_STAMP = hook_decision.create_refusal_stamp(time_batch_guard.STAMP_PREFIX)
+
+// The two hooks race on one event and the stamp is written before the reason, so a record this young
+// is the batching guard speaking about the call in hand.
+const BATCH_REFUSAL_WINDOW_MS = 10_000
+
+// Asked with its real record, not `NEVER_MS`: that guard never refuses one sequence twice.
+function will_batch_guard_refuse(tail: string, call: GuardedCall, run: GuardRun): boolean {
+	const refused_at_ms = BATCH_STAMP.last_ms(BATCH_STAMP.path(run.transcript))
+
+	if (run.now_ms - refused_at_ms < BATCH_REFUSAL_WINDOW_MS) return true
+
+	return will_batch_refuse(tail, call, run)
+}
+
+function is_first_delivery(
+	tail: string,
+	call: GuardedCall,
+	delivered_at_ms: number,
+	run: GuardRun,
+): boolean {
+	return delivered_at_ms === hook_decision.NEVER_MS && !will_batch_guard_refuse(tail, call, run)
+}
+
+// `decide` and `already_satisfied` each replace `is_first_delivery`. A recurring row is always asked;
+// the stand-aside reaches it as `can_record`, since what must not happen is recording a refused act.
+// An `already_satisfied` row refuses every call until the satisfying act is on the tail.
+function delivery_decision(rule: DeliveredRule): TranscriptGuardSpec['should_block'] {
+	const { decide, already_satisfied } = rule
+
+	if (decide === undefined && already_satisfied === undefined) return is_first_delivery
+
+	return function should_block(
+		tail: string,
+		call: GuardedCall,
+		delivered_at_ms: number,
+		run: GuardRun,
+	): boolean {
+		if (already_satisfied?.(tail, call, run) === true) return false
+		if (decide === undefined) return true
+
+		return decide(call, run, !will_batch_guard_refuse(tail, call, run), delivered_at_ms)
+	}
+}
+
+type CallTrigger = (call: GuardedCall) => boolean
+
+// A row whose trigger takes its own seam as the second argument, not the call's context, and reads no
+// cwd or environment: the row is asked with the call alone, so the seam keeps its default.
+function call_only<Row extends { is_trigger: CallTrigger }>(
+	row: Row,
+): Omit<Row, 'is_trigger'> & { is_trigger: CallTrigger } {
+	return { ...row, is_trigger: (call: GuardedCall): boolean => row.is_trigger(call) }
+}
+
+function prefix_of(rule_id: string): string {
+	return `${STAMP_PREFIX}${rule_id}-`
+}
+
+function guard_of(rule: DeliveredRule): TranscriptGuard {
+	return hook_decision.create_transcript_guard({
+		prefix: prefix_of(rule.id),
+		switch_key: SWITCH_ENV_KEY,
+		is_candidate: (call, context) => rule.is_trigger(call, context),
+		should_block: delivery_decision(rule),
+		reason: rule.reason,
+	})
+}
+
+const delivered_rules_guard = { SWITCH_ENV_KEY, call_only, guard_of, prefix_of }
+
+export { delivered_rules_guard }