@joshuafolkken/kit 1.1784.0 → 1.2114.0

package/scripts/agent/agent-role-profile.ts

@@ -1,11 +1,28 @@
-import { agent_session_environment } from '#scripts/josh/agent-session-environment'
 import { z } from 'zod'
+import {
+	agent_provider,
+	type AgentEnvironment,
+	type AgentProvider,
+	type Rejected,
+} from './agent-provider'
 import { agent_safe_text } from './agent-safe-text'
 
-const EMPTY_LENGTH = 0
+const {
+	ANTHROPIC_PROVIDER,
+	CODEX_SESSION_KEY,
+	HANDED_PROVIDER_KEY,
+	OPENAI_PROVIDER,
+	PROVIDER_SCHEMA,
+	default_notice,
+	handoff_environment,
+	has_completion_callback,
+	rejection,
+	resolve_provider,
+	trimmed,
+	warn_of_default,
+} = agent_provider
 
 const ROLE_SCHEMA = z.enum(['scheduler', 'worker', 'reviewer'])
-const PROVIDER_SCHEMA = z.enum(['anthropic', 'openai'])
 const EFFORT_SCHEMA = z.enum(['low', 'medium', 'high', 'xhigh', 'max'])
 // The run phases effort may vary by. They are the cut boundaries a lane child
 // resumes across — `run-cut.ts` imports these names for its own cut record, so the phase a run passes
@@ -20,15 +37,11 @@ const PROFILE_SCHEMA = z.object({
 })
 
 type AgentRole = z.infer<typeof ROLE_SCHEMA>
-type AgentProvider = z.infer<typeof PROVIDER_SCHEMA>
 type AgentEffort = z.infer<typeof EFFORT_SCHEMA>
 type AgentPhase = z.infer<typeof PHASE_SCHEMA>
 type AgentProfile = z.infer<typeof PROFILE_SCHEMA>
-type AgentEnvironment = Readonly<Record<string, string | undefined>>
-type ProfileResult = { kind: 'profile'; profile: AgentProfile } | { kind: 'rejected'; note: string }
-type Rejected = Extract<ProfileResult, { kind: 'rejected' }>
+type ProfileResult = Rejected | { kind: 'profile'; profile: AgentProfile }
 type EffortResult = Rejected | { kind: 'effort'; effort: AgentEffort }
-type ProviderResult = Rejected | { kind: 'provider'; provider: AgentProvider; is_default?: true }
 type OverrideField = 'model' | 'effort'
 
 interface Override {
@@ -36,6 +49,13 @@ interface Override {
 	value: string | undefined
 }
 
+interface PhaseModel {
+	key: string
+	value: string
+}
+
+type PhaseTable<Value> = Readonly<Partial<Record<AgentRole, Partial<Record<AgentPhase, Value>>>>>
+
 // What a resolution is keyed on beyond the role: the run phase (effort) and the review round (profile).
 interface AgentStage {
 	phase?: string | undefined
@@ -47,38 +67,33 @@ const WORKER: AgentRole = 'worker'
 const REVIEWER: AgentRole = 'reviewer'
 const IMPLEMENTATION_PHASE: AgentPhase = 'implementation'
 const PRE_GATE_PHASE: AgentPhase = 'pre-gate'
-const ANTHROPIC_PROVIDER: AgentProvider = 'anthropic'
-const OPENAI_PROVIDER: AgentProvider = 'openai'
 // **Pinned model ids, never a floating alias**. An alias such as `opus` moves
 // whenever the CLI moves it, so a run log could not say which model produced it and a model migration
 // could not be measured apart from everything else. A new lane records the id it resolved; a lane
-// created before a migration keeps the model it recorded (`with_phase_effort` leaves it untouched).
+// created before a migration keeps the model it recorded (`with_phase` moves it only by a phase key).
 const OPENAI_MODEL = 'gpt-6.1-sol'
 const ANTHROPIC_MODEL = 'claude-opus-5-5'
-const CODEX_SESSION_KEY = 'CODEX_THREAD_ID'
-
-const DEFAULT_PROFILES: Readonly<Record<AgentRole, AgentProfile>> = {
-	scheduler: {
-		provider: ANTHROPIC_PROVIDER,
-		role: SCHEDULER,
-		model: ANTHROPIC_MODEL,
-		effort: 'medium',
-	},
-	worker: { provider: ANTHROPIC_PROVIDER, role: WORKER, model: ANTHROPIC_MODEL, effort: 'medium' },
-	reviewer: {
-		provider: ANTHROPIC_PROVIDER,
-		role: REVIEWER,
-		model: ANTHROPIC_MODEL,
-		effort: 'high',
-	},
-}
 
-const OPENAI_PROFILES: Readonly<Record<AgentRole, AgentProfile>> = {
-	scheduler: { provider: OPENAI_PROVIDER, role: SCHEDULER, model: OPENAI_MODEL, effort: 'medium' },
-	worker: { provider: OPENAI_PROVIDER, role: WORKER, model: OPENAI_MODEL, effort: 'medium' },
-	reviewer: { provider: OPENAI_PROVIDER, role: REVIEWER, model: OPENAI_MODEL, effort: 'high' },
+// **Round 1 reviews at `medium`** (joshuafolkken/kit#5106): it ended clean on 88% of diffs while its
+// `high` run sat on the lane's critical path; the verification pass below keeps `high`.
+const REVIEW_EFFORT: AgentEffort = 'medium'
+const VERIFICATION_EFFORT: AgentEffort = 'high'
+
+// Every provider runs each role at the same effort; only the model differs.
+function role_profiles(
+	provider: AgentProvider,
+	model: string,
+): Readonly<Record<AgentRole, AgentProfile>> {
+	return {
+		scheduler: { provider, role: SCHEDULER, model, effort: 'medium' },
+		worker: { provider, role: WORKER, model, effort: 'medium' },
+		reviewer: { provider, role: REVIEWER, model, effort: REVIEW_EFFORT },
+	}
 }
 
+const DEFAULT_PROFILES = role_profiles(ANTHROPIC_PROVIDER, ANTHROPIC_MODEL)
+const OPENAI_PROFILES = role_profiles(OPENAI_PROVIDER, OPENAI_MODEL)
+
 const PROVIDER_PROFILES = { anthropic: DEFAULT_PROFILES, openai: OPENAI_PROFILES }
 
 // **The verification pass resolves a profile of its own** (joshuafolkken/kit#3926). A round after the
@@ -89,8 +104,12 @@ const FIRST_REVIEW_ROUND = 1
 // pass/fail equals Opus's (100% agreement), and Opus passes all 4.
 const VERIFICATION_MODEL = 'claude-sonnet-5-5'
 const VERIFICATION_PROFILES: Readonly<Record<AgentProvider, AgentProfile>> = {
-	anthropic: { ...DEFAULT_PROFILES.reviewer, model: VERIFICATION_MODEL },
-	openai: OPENAI_PROFILES.reviewer,
+	anthropic: {
+		...DEFAULT_PROFILES.reviewer,
+		model: VERIFICATION_MODEL,
+		effort: VERIFICATION_EFFORT,
+	},
+	openai: { ...OPENAI_PROFILES.reviewer, effort: VERIFICATION_EFFORT },
 }
 const VERIFICATION_KEYS = {
 	model: 'JOSH_REVIEWER_VERIFICATION_MODEL',
@@ -101,15 +120,21 @@ const VERIFICATION_KEYS = {
 // merge only the mechanical ship/bookkeeping region is lowered: the pre-gate resume drives the gate,
 // commit, PR and merge, applying fixes the gate has already named — work delegation.md calls the opposite
 // of judgement. The design-judgment implementation phases keep the role default, as does any role/phase
-// with no entry, and the review's own judgement is the reviewer role's (`high`), untouched by lowering
+// with no entry, and the review's own judgement is the reviewer role's, untouched by lowering
 // the worker here. The investigation phase — highest output density — is left for a later merge, once
 // the delegation half of this Issue has moved its reading out.
 const SHIP_EFFORT: AgentEffort = 'low'
-type PhaseEffortTable = Partial<Record<AgentRole, Partial<Record<AgentPhase, AgentEffort>>>>
-const PHASE_EFFORT: Readonly<PhaseEffortTable> = {
+const PHASE_EFFORT: PhaseTable<AgentEffort> = {
 	worker: { [PRE_GATE_PHASE]: SHIP_EFFORT },
 }
 
+// **The ship phase may run on a model of its own** (joshuafolkken/kit#5343), read from its key ahead of
+// the role's and applied on the same cut relaunch as `SHIP_EFFORT`. Unset, the phase keeps the role's
+// model, so the default is unchanged.
+const PHASE_MODEL_KEYS: PhaseTable<string> = {
+	worker: { [PRE_GATE_PHASE]: 'JOSH_WORKER_SHIP_MODEL' },
+}
+
 const ENV_KEYS: Readonly<Record<AgentRole, { model: string; effort: string }>> = {
 	scheduler: { model: 'JOSH_SCHEDULER_MODEL', effort: 'JOSH_SCHEDULER_EFFORT' },
 	worker: { model: 'JOSH_WORKER_MODEL', effort: 'JOSH_WORKER_EFFORT' },
@@ -120,12 +145,6 @@ const LEGACY_WORKER_KEYS = { model: 'JOSH_LANE_MODEL', effort: 'JOSH_LANE_EFFORT
 
 const { MAX_VALUE_LENGTH, is_safe_prompt, is_safe_value, printable } = agent_safe_text
 
-function trimmed(value: string | undefined): string | undefined {
-	const result = value?.trim()
-
-	return result === undefined || result.length === EMPTY_LENGTH ? undefined : result
-}
-
 function is_verification(role: AgentRole, round: number | undefined): boolean {
 	return role === REVIEWER && round !== undefined && round > FIRST_REVIEW_ROUND
 }
@@ -157,19 +176,44 @@ function override_value(
 		: { key, value: trimmed(environment[key]) }
 }
 
+// A role's entry in a phase table; `undefined` for a phase-less or unrecognized phase, or no entry.
+function phase_entry<Value>(
+	table: PhaseTable<Value>,
+	role: AgentRole,
+	phase: string | undefined,
+): Value | undefined {
+	const parsed = PHASE_SCHEMA.safeParse(phase)
+
+	return parsed.success ? table[role]?.[parsed.data] : undefined
+}
+
+// The phase's own model key when it is set; `undefined` for a phase with no key, an unset key, or an
+// OpenAI session, whose model is never read from env.
+function phase_model(
+	role: AgentRole,
+	provider: AgentProvider,
+	phase: string | undefined,
+	environment: AgentEnvironment,
+): PhaseModel | undefined {
+	const key = provider === OPENAI_PROVIDER ? undefined : phase_entry(PHASE_MODEL_KEYS, role, phase)
+	if (key === undefined) return undefined
+	const value = trimmed(environment[key])
+
+	return value === undefined ? undefined : { key, value }
+}
+
 function model_override(
 	role: AgentRole,
 	environment: AgentEnvironment,
 	provider: AgentProvider,
-	round: number | undefined,
+	stage: AgentStage,
 ): Override {
+	const phased = phase_model(role, provider, stage.phase, environment)
+	if (phased !== undefined) return phased
+
 	return provider === OPENAI_PROVIDER
 		? { key: ENV_KEYS[role].model, value: undefined }
-		: override_value(role, 'model', environment, round)
-}
-
-function rejection(key: string, value: string, expected: string): Rejected {
-	return { kind: 'rejected', note: `${key}=${value} ${expected}, so the agent was not started` }
+		: override_value(role, 'model', environment, stage.round)
 }
 
 function resolved_effort(override: Override, fallback: AgentEffort): EffortResult {
@@ -180,93 +224,6 @@ function resolved_effort(override: Override, fallback: AgentEffort): EffortResul
 		: rejection(override.key, override.value ?? '', 'is not an allowed effort')
 }
 
-function has_session(environment: AgentEnvironment, keys: ReadonlyArray<string>): boolean {
-	return keys.some((key) => trimmed(environment[key]) !== undefined)
-}
-
-const CONFLICTING_SESSIONS: Rejected = {
-	kind: 'rejected',
-	note: 'both Codex and Claude Code sessions were detected',
-}
-
-// The provider a detached launcher hands a process that is not itself an agent session.
-// `detached_launch` strips the parent-session keys — the very keys the
-// detection below reads — so a `josh ship --detach --review` supervisor could never resolve its reviewer.
-// **It is a fallback, read only when no session is detected**: the mark is inherited by everything the
-// supervisor starts, and a real session's own keys must keep deciding for that session.
-const HANDED_PROVIDER_KEY = 'JOSH_AGENT_PROVIDER'
-
-// **Nothing named a provider, so Claude Code is the default** — a person typing `josh lane:launch` in a
-// plain terminal has no session and no mark. Only silence defaults: two detected sessions and a mark
-// naming no allowed provider still refuse. `is_default` lets a launch say so, and lets `josh cost` keep
-// reading "no session of its own" rather than pricing another session's transcript.
-const DEFAULT_PROVIDER: ProviderResult = {
-	kind: 'provider',
-	provider: ANTHROPIC_PROVIDER,
-	is_default: true,
-}
-const DEFAULT_NOTICE = ` No agent session or ${HANDED_PROVIDER_KEY} was found, so the provider defaulted to ${ANTHROPIC_PROVIDER} (Claude Code).`
-
-function handed_provider(environment: AgentEnvironment): ProviderResult {
-	const value = trimmed(environment[HANDED_PROVIDER_KEY])
-	if (value === undefined) return DEFAULT_PROVIDER
-	const parsed = PROVIDER_SCHEMA.safeParse(value)
-
-	return parsed.success
-		? { kind: 'provider', provider: parsed.data }
-		: rejection(HANDED_PROVIDER_KEY, value, 'is not an allowed provider')
-}
-
-// The session this process runs in, read from its own keys: `undefined` when none is detected.
-function detected_provider(environment: AgentEnvironment): ProviderResult | undefined {
-	const has_codex = has_session(environment, [CODEX_SESSION_KEY])
-	const has_claude = has_session(environment, agent_session_environment.PARENT_SESSION_KEYS)
-
-	if (has_codex === has_claude) return has_codex ? CONFLICTING_SESSIONS : undefined
-
-	return { kind: 'provider', provider: has_codex ? OPENAI_PROVIDER : ANTHROPIC_PROVIDER }
-}
-
-function resolve_provider(environment: AgentEnvironment = process.env): ProviderResult {
-	return detected_provider(environment) ?? handed_provider(environment)
-}
-
-// The sentence a launch appends when it ran on the default, so falling back is never silent; empty when
-// a session or a mark decided.
-function default_notice(environment: AgentEnvironment = process.env): string {
-	const selected = resolve_provider(environment)
-
-	return selected.kind === 'provider' && selected.is_default === true ? DEFAULT_NOTICE : ''
-}
-
-// The same sentence on stderr, for a launcher whose own line is a verdict or a brief another process
-// reads: `run:wake --start`, `review:brief` and `ship --detach` default exactly as a dispatch does.
-function warn_of_default(environment: AgentEnvironment = process.env): void {
-	const notice = default_notice(environment).trim()
-
-	if (notice !== '') console.error(notice)
-}
-
-// Whether this session is woken when a background command it started completes.
-// Claude Code re-invokes the session at the completion; a Codex session is not
-// re-invoked, so a parent there can only wait by polling, each poll a model call over its whole context.
-// Only a resolved Codex session answers no — a defaulted or conflicting one keeps the callback.
-function has_completion_callback(environment: AgentEnvironment = process.env): boolean {
-	const selected = resolve_provider(environment)
-
-	return selected.kind !== 'provider' || selected.provider !== OPENAI_PROVIDER
-}
-
-// The mark a detached launch sets on its child: the provider this session resolved, the default
-// included, or nothing when it was refused — the child then fails the same way this session would have.
-function handoff_environment(
-	environment: AgentEnvironment = process.env,
-): Readonly<Record<string, string>> {
-	const selected = resolve_provider(environment)
-
-	return selected.kind === 'provider' ? { [HANDED_PROVIDER_KEY]: selected.provider } : {}
-}
-
 function validate(profile: AgentProfile, model_key: string): ProfileResult {
 	if (!is_safe_value(profile.model)) {
 		return rejection(model_key, profile.model, 'is not a safe model')
@@ -283,10 +240,7 @@ function phase_effort(
 	phase: string | undefined,
 	fallback: AgentEffort,
 ): AgentEffort {
-	const parsed = PHASE_SCHEMA.safeParse(phase)
-	if (!parsed.success) return fallback
-
-	return PHASE_EFFORT[role]?.[parsed.data] ?? fallback
+	return phase_entry(PHASE_EFFORT, role, phase) ?? fallback
 }
 
 // The effort a stored profile takes in a phase: an env override wins, then the phase value, then the
@@ -302,14 +256,18 @@ function overridden_effort(
 	return parsed.success ? parsed.data : phase_effort(profile.role, phase, profile.effort)
 }
 
-// A stored profile with its effort resolved for the phase the run is entering, its model and provider
-// left as they were.
-function with_phase_effort(
+// A stored profile resolved for the phase the run is entering: its effort, and its model only where the
+// phase's own model key is set — the role's model key never moves a lane off the model it recorded.
+function with_phase(
 	profile: AgentProfile,
 	phase: string,
 	environment: AgentEnvironment = process.env,
-): AgentProfile {
-	return { ...profile, effort: overridden_effort(profile, phase, environment) }
+): ProfileResult {
+	const effort = overridden_effort(profile, phase, environment)
+	const model = phase_model(profile.role, profile.provider, phase, environment)
+	if (model === undefined) return { kind: 'profile', profile: { ...profile, effort } }
+
+	return validate({ ...profile, model: model.value, effort }, model.key)
 }
 
 function stage_defaults(
@@ -330,7 +288,7 @@ function resolve_stage(
 	const selected = resolve_provider(environment)
 	if (selected.kind === 'rejected') return selected
 	const defaults = stage_defaults(selected.provider, role, stage.round)
-	const model = model_override(role, environment, selected.provider, stage.round)
+	const model = model_override(role, environment, selected.provider, stage)
 	const effort = override_value(role, 'effort', environment, stage.round)
 	const resolved = resolved_effort(effort, phase_effort(role, stage.phase, defaults.effort))
 
@@ -401,16 +359,10 @@ const agent_role_profile = {
 	resolve_provider,
 	resolve_review,
 	warn_of_default,
-	with_phase_effort,
+	with_phase,
 }
 
-export type {
-	AgentEffort,
-	AgentEnvironment,
-	AgentPhase,
-	AgentProfile,
-	AgentProvider,
-	AgentRole,
-	ProfileResult,
-}
+export type { AgentEffort, AgentPhase, AgentProfile, AgentRole, ProfileResult }
 export { agent_role_profile }
+
+export { type AgentEnvironment, type AgentProvider } from './agent-provider'

package/scripts/agent/agent-safe-text.ts

@@ -6,6 +6,11 @@ const DELETE_CODE = 0x7f
 const FIRST_CODE_POINT = 0
 const EMPTY_LENGTH = 0
 const MAX_VALUE_LENGTH = 4096
+// A prompt is prose that grows with its instructions, so it gets a cap of its own rather than a
+// value's: an overrun investigation's prompt grew past 4096 and its launch was refused
+// (joshuafolkken/kit#4930). 64 Ki UTF-16 units of mostly ASCII text stay under Linux's 128 KiB
+// `MAX_ARG_STRLEN` per element; a launch the system still refuses fails as a noted launch failure.
+const MAX_PROMPT_LENGTH = 65_536
 const LINE_FEED = '\n'
 const SPACE = ' '
 
@@ -27,8 +32,12 @@ function is_refused(character: string, is_allowed: (character: string) => boolea
 	return is_control_character(character) && !is_allowed(character)
 }
 
-function is_safe_text(value: string, is_allowed: (character: string) => boolean): boolean {
-	if (value.length === EMPTY_LENGTH || value.length > MAX_VALUE_LENGTH) return false
+function is_safe_text(
+	value: string,
+	is_allowed: (character: string) => boolean,
+	max_length: number,
+): boolean {
+	if (value.length === EMPTY_LENGTH || value.length > max_length) return false
 
 	for (const character of value) if (is_refused(character, is_allowed)) return false
 
@@ -36,13 +45,13 @@ function is_safe_text(value: string, is_allowed: (character: string) => boolean)
 }
 
 function is_safe_value(value: string): boolean {
-	return is_safe_text(value, is_never_allowed)
+	return is_safe_text(value, is_never_allowed, MAX_VALUE_LENGTH)
 }
 
 // **An agent's prompt is the one value a line break belongs in.** A ship-stop prompt carries the failed
 // output's lines (joshuafolkken/kit#3964); every other control character is refused as in any value.
 function is_safe_prompt(value: string): boolean {
-	return is_safe_text(value, is_line_feed)
+	return is_safe_text(value, is_line_feed, MAX_PROMPT_LENGTH)
 }
 
 function printable_character(character: string): string {
@@ -55,6 +64,12 @@ function printable(text: string): string {
 	return Array.from(text, printable_character).join('')
 }
 
-const agent_safe_text = { MAX_VALUE_LENGTH, is_safe_prompt, is_safe_value, printable }
+const agent_safe_text = {
+	MAX_PROMPT_LENGTH,
+	MAX_VALUE_LENGTH,
+	is_safe_prompt,
+	is_safe_value,
+	printable,
+}
 
 export { agent_safe_text }

package/scripts/agent/api-usage-limit.ts

@@ -0,0 +1,65 @@
+import { agent_exit_record } from './agent-exit-record'
+import type { ClaudeResultEvent } from './claude-result-event'
+import { usage_limit_reset } from './usage-limit-reset'
+
+// Whether a Claude session's exit record is a usage-limit stop, and when it may run again — observed on
+// 2026-10-23, when four lane children ended `You've hit your weekly limit · resets 10am (...)` at once
+// and the parent parked each as a child that stopped on its own (joshuafolkken/kit#4745).
+//
+// **Kept apart from `api-outage.ts` and `api-auth.ts`**: an outage clears within minutes and an
+// authentication failure needs a person, but a usage limit clears at a time the record itself names, so
+// the run waits for that time and resumes. The read is the same mechanical one — the error flag AND a
+// fixed marker in the harness's own `reason`, never the marker alone.
+
+// The limit sentences' stable parts, lower-cased: the current `You've hit your [weekly|session] limit`
+// and the older `Claude AI usage limit reached|<epoch>`.
+const LIMIT_PATTERN = /hit your (?:\w+ )?limit|usage limit reached/u
+// How long a stop whose reset time could not be read waits before one child tries again.
+const RECHECK_MS = 1_800_000
+
+// The record's `reason` when it is a usage limit, else `undefined`.
+function limit_reason(record: ClaudeResultEvent | undefined): string | undefined {
+	if (record === undefined || !record.is_error || record.reason === undefined) return undefined
+
+	return LIMIT_PATTERN.test(record.reason.toLowerCase()) ? record.reason : undefined
+}
+
+function is_usage_limit(record: ClaudeResultEvent | undefined): boolean {
+	return limit_reason(record) !== undefined
+}
+
+// A reset the record does not state readably — or one already past — is re-checked `RECHECK_MS` on.
+function or_recheck(reset_ms: number | undefined, now_ms: number): number {
+	return reset_ms === undefined || reset_ms <= now_ms ? now_ms + RECHECK_MS : reset_ms
+}
+
+// When a run stopped by this record may dispatch again, in epoch milliseconds, or `undefined` when the
+// record is no usage limit. The sentence's wall clock is read from `stopped_ms`, when the record was
+// written: read later, a reset already past would roll to the next day.
+function resume_ms(
+	record: ClaudeResultEvent | undefined,
+	now_ms: number,
+	stopped_ms = now_ms,
+): number | undefined {
+	const reason = limit_reason(record)
+
+	if (reason === undefined) return undefined
+
+	return or_recheck(usage_limit_reset.reset_ms(reason, stopped_ms), now_ms)
+}
+
+// The same read over a whole stream-json transcript, read only when it ends on an exit record — the
+// lane's log is appended across launches (`api_auth.is_auth_failed_transcript`).
+function transcript_resume_ms(
+	log: string | undefined,
+	now_ms: number,
+	stopped_ms = now_ms,
+): number | undefined {
+	if (log === undefined || !agent_exit_record.ends_on_exit_record(log)) return undefined
+
+	return resume_ms(agent_exit_record.read_exit_record(log), now_ms, stopped_ms)
+}
+
+const api_usage_limit = { RECHECK_MS, is_usage_limit, resume_ms, transcript_resume_ms }
+
+export { api_usage_limit }

package/scripts/agent/claude-agent-argv.ts

@@ -12,8 +12,8 @@ const AGENT_COMMAND = 'claude'
 // **The permission mode is passed, not left to the checkout's `.claude/settings.json`.** Claude Code
 // ignores a project's `defaultMode: bypassPermissions` (since v2.1.257) and its `permissions.allow` in
 // a workspace whose trust dialog was never accepted — every fresh clone and every new lane worktree — so
-// a headless child stopped on approvals nobody could give. The flag sets the mode that file declares;
-// its `deny` list stays in effect (#3796).
+// a headless child stopped on approvals nobody could give, so kit ships no `defaultMode` (#4997) and
+// the flag sets the mode; the file's `deny` list stays in effect (#3796).
 const PERMISSION_FLAGS: ReadonlyArray<string> = ['--permission-mode', 'bypassPermissions']
 const AGENT_FLAGS: ReadonlyArray<string> = [
 	'-p',
@@ -37,7 +37,9 @@ const SESSION_ID_FLAG = '--session-id'
 // tool definition and every user-side claude.ai connector rides on each request's cached preamble, and
 // across the lanes measured none of Artifact, Workflow or a connector was ever called, while
 // AskUserQuestion has nobody to answer it in an unattended lane. Narrowing them cut the preamble by
-// about 16,000 tokens per request. This list is the one place the set is kept.
+// about 16,000 tokens per request. **No web tool is launched**: no role runs with a person at the keyboard, and a
+// fetched page enters the context with no trust label, past the Issue trust filter (#4664). This list
+// is the one place the set is kept.
 const LAUNCHED_TOOLS: ReadonlyArray<string> = [
 	'Bash',
 	'Read',
@@ -50,9 +52,11 @@ const LAUNCHED_TOOLS: ReadonlyArray<string> = [
 	'TaskStop',
 	'Monitor',
 	'TodoWrite',
-	'WebSearch',
-	'WebFetch',
 ]
+// **A reviewer is the review, not a launcher of one** (joshuafolkken/kit#4715): with `Skill` it ran
+// `/code-review`, which forked a second agent that read the same diff and brief again. Without the two
+// tools that open a nested agent, the review stays in the one session.
+const NESTING_TOOLS: ReadonlySet<string> = new Set(['Agent', 'Skill'])
 const TOOLS_FLAG = '--tools'
 // **Only the project's own MCP servers load** — the user's connectors are what the strict flag drops.
 // A project with no `.mcp.json` gets the strict flag alone, which loads no server at all: that is
@@ -77,16 +81,22 @@ function session_id_flags(session_id: string | undefined): ReadonlyArray<string>
 	return session_id === undefined ? [] : [SESSION_ID_FLAG, session_id]
 }
 
+function launched_tools(role: AgentRole): ReadonlyArray<string> {
+	if (role !== agent_role_profile.REVIEWER) return LAUNCHED_TOOLS
+
+	return LAUNCHED_TOOLS.filter((tool) => !NESTING_TOOLS.has(tool))
+}
+
 // The config is named by absolute path, resolved against the directory the child is launched in, so
 // the flag means the same file whatever the child's own working directory turns out to be. The pair
 // sits ahead of the model flags: `--mcp-config` takes several values, and the next flag is what ends it.
-function tool_flags(cwd: string = process.cwd()): ReadonlyArray<string> {
+function tool_flags(role: AgentRole, cwd: string = process.cwd()): ReadonlyArray<string> {
 	const mcp_config = path.join(cwd, PROJECT_MCP_FILE)
 	const mcp_flags = existsSync(mcp_config)
 		? [STRICT_MCP_FLAG, MCP_CONFIG_FLAG, mcp_config]
 		: [STRICT_MCP_FLAG]
 
-	return [TOOLS_FLAG, LAUNCHED_TOOLS.join(','), ...mcp_flags]
+	return [TOOLS_FLAG, launched_tools(role).join(','), ...mcp_flags]
 }
 
 // **A lane child and a review session start from the lane instruction set** (`lane-instructions.ts`);
@@ -107,7 +117,7 @@ function build(
 		command: AGENT_COMMAND,
 		args: [
 			...AGENT_FLAGS,
-			...tool_flags(cwd),
+			...tool_flags(profile.role, cwd),
 			...instruction_flags(profile, cwd),
 			...session_id_flags(session_id),
 			MODEL_FLAG,
@@ -132,7 +142,7 @@ function build_resume(
 		command: AGENT_COMMAND,
 		args: [
 			...AGENT_FLAGS,
-			...tool_flags(cwd),
+			...tool_flags(profile.role, cwd),
 			...instruction_flags(profile, cwd),
 			RESUME_FLAG,
 			session_id,