@joshuafolkken/kit 1.872.0

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

@@ -0,0 +1,329 @@
+import { agent_session_environment } from '#scripts/josh/agent-session-environment'
+import { z } from 'zod'
+
+const FIRST_PRINTABLE_CODE = 0x20
+const DELETE_CODE = 0x7f
+const FIRST_CODE_POINT = 0
+const EMPTY_LENGTH = 0
+const MAX_VALUE_LENGTH = 4096
+
+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 (joshuafolkken/kit#2382). 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
+// and the phase this table is keyed on cannot drift. A phase-less call resolves the role default, which
+// is what keeps every existing caller unchanged.
+const PHASE_SCHEMA = z.enum(['implementation', 'pre-gate'])
+const PROFILE_SCHEMA = z.object({
+	provider: PROVIDER_SCHEMA.default('anthropic'),
+	role: ROLE_SCHEMA,
+	model: z.string(),
+	effort: EFFORT_SCHEMA,
+})
+
+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 EffortResult = Rejected | { kind: 'effort'; effort: AgentEffort }
+type ProviderResult = Rejected | { kind: 'provider'; provider: AgentProvider }
+
+const SCHEDULER: AgentRole = 'scheduler'
+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** (joshuafolkken/kit#2415). 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).
+const OPENAI_MODEL = 'gpt-6-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' },
+}
+
+const PROVIDER_PROFILES = { anthropic: DEFAULT_PROFILES, openai: OPENAI_PROFILES }
+
+// **Effort as a function of the run phase, not the role alone** (joshuafolkken/kit#2382). For the first
+// 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 SKILL.md §2b 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
+// 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> = {
+	worker: { [PRE_GATE_PHASE]: SHIP_EFFORT },
+}
+
+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' },
+	reviewer: { model: 'JOSH_REVIEWER_MODEL', effort: 'JOSH_REVIEWER_EFFORT' },
+}
+
+const LEGACY_WORKER_KEYS = { model: 'JOSH_LANE_MODEL', effort: 'JOSH_LANE_EFFORT' }
+
+function is_control_character(character: string): boolean {
+	const code = character.codePointAt(FIRST_CODE_POINT) ?? FIRST_PRINTABLE_CODE
+
+	return code < FIRST_PRINTABLE_CODE || code === DELETE_CODE
+}
+
+function is_safe_value(value: string): boolean {
+	if (value.length === EMPTY_LENGTH || value.length > MAX_VALUE_LENGTH) return false
+
+	for (const character of value) if (is_control_character(character)) return false
+
+	return true
+}
+
+function trimmed(value: string | undefined): string | undefined {
+	const result = value?.trim()
+
+	return result === undefined || result.length === EMPTY_LENGTH ? undefined : result
+}
+
+function override_value(
+	role: AgentRole,
+	field: 'model' | 'effort',
+	environment: AgentEnvironment,
+): { key: string; value: string | undefined } {
+	const key = ENV_KEYS[role][field]
+	const value = trimmed(environment[key])
+	if (value !== undefined) return { key, value }
+	if (role !== WORKER) return { key, value: undefined }
+
+	const legacy = LEGACY_WORKER_KEYS[field]
+	const legacy_value = trimmed(environment[legacy])
+
+	return legacy_value === undefined
+		? { key, value: undefined }
+		: { key: legacy, value: legacy_value }
+}
+
+function model_override(
+	role: AgentRole,
+	environment: AgentEnvironment,
+	provider: AgentProvider,
+): { key: string; value: string | undefined } {
+	const key = ENV_KEYS[role].model
+
+	return provider === OPENAI_PROVIDER
+		? { key, value: undefined }
+		: override_value(role, 'model', environment)
+}
+
+function rejection(key: string, value: string, expected: string): Rejected {
+	return { kind: 'rejected', note: `${key}=${value} ${expected}, so the agent was not started` }
+}
+
+function resolved_effort(
+	override: { key: string; value: string | undefined },
+	fallback: AgentEffort,
+): EffortResult {
+	const parsed = EFFORT_SCHEMA.safeParse(override.value ?? fallback)
+
+	return parsed.success
+		? { kind: 'effort', effort: parsed.data }
+		: 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)
+}
+
+function session_rejection(is_conflicting: boolean): Rejected {
+	const note = is_conflicting
+		? 'both Codex and Claude Code sessions were detected'
+		: 'no Codex or Claude Code session was detected'
+
+	return { kind: 'rejected', note }
+}
+
+// The provider a detached launcher hands a process that is not itself an agent session
+// (joshuafolkken/kit#2456). `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'
+
+function handed_provider(environment: AgentEnvironment): ProviderResult {
+	const value = trimmed(environment[HANDED_PROVIDER_KEY])
+	if (value === undefined) return session_rejection(false)
+	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 ? session_rejection(true) : 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 mark a detached launch sets on its child: the provider this session resolved, or nothing when it
+// resolved none — 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')
+	}
+
+	return { kind: 'profile', profile }
+}
+
+// The effort a phase resolves to before any env override: the phase's own value where the table names
+// one, otherwise the fallback (joshuafolkken/kit#2382). A phase-less or unrecognized call returns the
+// fallback unchanged, which is what keeps every existing caller reading the current default.
+function phase_effort(
+	role: AgentRole,
+	phase: string | undefined,
+	fallback: AgentEffort,
+): AgentEffort {
+	const parsed = PHASE_SCHEMA.safeParse(phase)
+	if (!parsed.success) return fallback
+
+	return PHASE_EFFORT[role]?.[parsed.data] ?? fallback
+}
+
+// The effort a stored profile takes in a phase: an env override wins, then the phase value, then the
+// profile's own effort (joshuafolkken/kit#2382). A cut relaunch that keeps a lane's stored model resolves
+// the effort through this so a person's `JOSH_WORKER_EFFORT` is never overwritten by the phase value.
+function overridden_effort(
+	profile: AgentProfile,
+	phase: string,
+	environment: AgentEnvironment,
+): AgentEffort {
+	const parsed = EFFORT_SCHEMA.safeParse(override_value(profile.role, 'effort', environment).value)
+
+	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 (joshuafolkken/kit#2382).
+function with_phase_effort(
+	profile: AgentProfile,
+	phase: string,
+	environment: AgentEnvironment = process.env,
+): AgentProfile {
+	return { ...profile, effort: overridden_effort(profile, phase, environment) }
+}
+
+function resolve(
+	role: AgentRole,
+	environment: AgentEnvironment = process.env,
+	phase?: string,
+): ProfileResult {
+	const selected = resolve_provider(environment)
+	if (selected.kind === 'rejected') return selected
+	const defaults = PROVIDER_PROFILES[selected.provider][role]
+	const model = model_override(role, environment, selected.provider)
+	const effort = override_value(role, 'effort', environment)
+	const resolved = resolved_effort(effort, phase_effort(role, phase, defaults.effort))
+
+	if (resolved.kind === 'rejected') return resolved
+
+	const profile: AgentProfile = {
+		provider: selected.provider,
+		role,
+		model: model.value ?? defaults.model,
+		effort: resolved.effort,
+	}
+
+	return validate(profile, model.key)
+}
+
+function describe(profile: AgentProfile): string {
+	return `provider=${profile.provider} role=${profile.role} model=${profile.model} effort=${profile.effort}`
+}
+
+function parse(value: unknown): AgentProfile | undefined {
+	const parsed = PROFILE_SCHEMA.safeParse(value)
+
+	return parsed.success && is_safe_value(parsed.data.model) ? parsed.data : undefined
+}
+
+const agent_role_profile = {
+	DEFAULT_PROFILES,
+	EFFORT_SCHEMA,
+	ENV_KEYS,
+	HANDED_PROVIDER_KEY,
+	IMPLEMENTATION_PHASE,
+	LEGACY_WORKER_KEYS,
+	MAX_VALUE_LENGTH,
+	OPENAI_PROFILES,
+	PHASE_EFFORT,
+	PHASE_SCHEMA,
+	PRE_GATE_PHASE,
+	PROVIDER_SCHEMA,
+	PROFILE_SCHEMA,
+	REVIEWER,
+	SCHEDULER,
+	WORKER,
+	describe,
+	handoff_environment,
+	is_safe_value,
+	parse,
+	phase_effort,
+	resolve,
+	resolve_provider,
+	with_phase_effort,
+}
+
+export type {
+	AgentEffort,
+	AgentEnvironment,
+	AgentPhase,
+	AgentProfile,
+	AgentProvider,
+	AgentRole,
+	ProfileResult,
+}
+export { agent_role_profile }

package/scripts/agent/api-outage.ts

@@ -0,0 +1,51 @@
+import type { ClaudeResultEvent } from './claude-result-event'
+
+// Whether a dispatched lane child's exit record is an API-connection outage rather than a child that
+// stopped mid-implementation on its own (joshuafolkken/kit#2240). Measured twice: on 2026-09-15 four
+// children ended `The socket connection was closed unexpectedly`, and on 2026-09-21 a child spent all
+// ten connection retries on `Unable to connect to API (ConnectionRefused)`. The parent read both as
+// ordinary failures — `in-progress` stripped, `needs-decision` applied, counted against the
+// consecutive-failure guard — when the child never reached the API at all.
+//
+// **The read is mechanical, never a similarity judgement.** A terminal `result` event that ends in
+// error carries the harness's own error text in `reason`; an outage is that text containing one of a
+// fixed set of transport-failure signatures. `is_error` is required — a child that finished a turn
+// cleanly is not an outage however its prose reads — so the test is the error flag AND a known marker,
+// not the marker alone.
+
+// The transport-failure signatures a `reason` is matched against, lower-cased. Each is a stable
+// substring the Anthropic client or the socket layer emits when the API could not be reached — the two
+// observed on the issue plus the Node-level spellings the same failures surface as. Retry exhaustion
+// needs no marker of its own: the client re-raises the underlying connection error after the last
+// attempt, so the exhausted case ends in one of these exactly as a single attempt does.
+const OUTAGE_MARKERS: ReadonlyArray<string> = [
+	'unable to connect to api',
+	'connectionrefused',
+	'econnrefused',
+	'connection refused',
+	'the socket connection was closed',
+	'socket hang up',
+]
+
+function matched_marker(reason: string): string | undefined {
+	const lower = reason.toLowerCase()
+
+	return OUTAGE_MARKERS.find((marker) => lower.includes(marker))
+}
+
+// The marker an exit record matched, or `undefined` when it is not an outage. A record that did not
+// end in error, or carries no reason text, is never an outage — the marker is read only off an errored
+// record's `reason`.
+function outage_marker(record: ClaudeResultEvent | undefined): string | undefined {
+	if (record === undefined || !record.is_error || record.reason === undefined) return undefined
+
+	return matched_marker(record.reason)
+}
+
+function is_outage(record: ClaudeResultEvent | undefined): boolean {
+	return outage_marker(record) !== undefined
+}
+
+const api_outage = { is_outage, outage_marker }
+
+export { api_outage, OUTAGE_MARKERS }

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

@@ -0,0 +1,151 @@
+import { existsSync } from 'node:fs'
+import path from 'node:path'
+import {
+	agent_role_profile,
+	type AgentEnvironment,
+	type AgentProfile,
+	type AgentRole,
+} from './agent-role-profile'
+
+const AGENT_COMMAND = 'claude'
+const AGENT_FLAGS: ReadonlyArray<string> = ['-p', '--verbose', '--output-format', 'stream-json']
+const MODEL_FLAG = '--model'
+const EFFORT_FLAG = '--effort'
+// Resumes a stored session by id (joshuafolkken/kit#2317). An `outage` re-dispatch passes the
+// disconnected child's `session_id` so the relaunched process continues that conversation — its
+// accumulated context intact — rather than reading everything from scratch.
+const RESUME_FLAG = '--resume'
+// Forces a fresh session's id rather than resuming one (joshuafolkken/kit#2407). The wake supervisor
+// generates the id, so it knows without asking the child which transcript that session will write —
+// `<session-id>.jsonl` — and can later attribute a whiff to a session it actually started rather than
+// to any transcript that happened to move while it was alive.
+const SESSION_ID_FLAG = '--session-id'
+// **A launched child carries only the tools a lane has ever used** (joshuafolkken/kit#2435). Every
+// 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.
+const LAUNCHED_TOOLS: ReadonlyArray<string> = [
+	'Bash',
+	'Read',
+	'Edit',
+	'Write',
+	'Agent',
+	'Skill',
+	'ToolSearch',
+	'SendMessage',
+	'TaskStop',
+	'Monitor',
+	'TodoWrite',
+	'WebSearch',
+	'WebFetch',
+]
+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
+// what the project declared, and it is the same connector-free preamble.
+const STRICT_MCP_FLAG = '--strict-mcp-config'
+const MCP_CONFIG_FLAG = '--mcp-config'
+const PROJECT_MCP_FILE = '.mcp.json'
+
+interface ClaudeArgv {
+	command: string
+	args: ReadonlyArray<string>
+}
+
+type ClaudeArgvResult =
+	{ kind: 'argv'; argv: ClaudeArgv; profile: AgentProfile } | { kind: 'rejected'; note: string }
+
+// **`session_id` is optional, so the id-forcing is additive.** Every existing caller composes the same
+// vector it did before; only a caller that hands a forced id — the wake supervisor — gets the
+// `--session-id` pair, sitting ahead of the model flags exactly where `--resume` sits in `build_resume`.
+function session_id_flags(session_id: string | undefined): ReadonlyArray<string> {
+	return session_id === undefined ? [] : [SESSION_ID_FLAG, session_id]
+}
+
+// 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> {
+	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]
+}
+
+function build(
+	invocation: string,
+	profile: AgentProfile,
+	session_id?: string,
+	cwd?: string,
+): ClaudeArgv {
+	return {
+		command: AGENT_COMMAND,
+		args: [
+			...AGENT_FLAGS,
+			...tool_flags(cwd),
+			...session_id_flags(session_id),
+			MODEL_FLAG,
+			profile.model,
+			EFFORT_FLAG,
+			profile.effort,
+			invocation,
+		],
+	}
+}
+
+// The resume counterpart: the same vector with `--resume <session_id>` ahead of the model flags, so the
+// relaunched child continues the stored session rather than opening a new one (joshuafolkken/kit#2317).
+function build_resume(
+	invocation: string,
+	profile: AgentProfile,
+	session_id: string,
+	cwd?: string,
+): ClaudeArgv {
+	return {
+		command: AGENT_COMMAND,
+		args: [
+			...AGENT_FLAGS,
+			...tool_flags(cwd),
+			RESUME_FLAG,
+			session_id,
+			MODEL_FLAG,
+			profile.model,
+			EFFORT_FLAG,
+			profile.effort,
+			invocation,
+		],
+	}
+}
+
+function with_profile(invocation: string, profile: AgentProfile): ClaudeArgvResult {
+	return { kind: 'argv', argv: build(invocation, profile), profile }
+}
+
+function resolve(
+	invocation: string,
+	role: AgentRole,
+	environment: AgentEnvironment = process.env,
+): ClaudeArgvResult {
+	const result = agent_role_profile.resolve(role, environment)
+
+	if (result.kind === 'rejected') return result
+
+	return with_profile(invocation, result.profile)
+}
+
+const claude_agent_argv = {
+	AGENT_COMMAND,
+	AGENT_FLAGS,
+	LAUNCHED_TOOLS,
+	build,
+	build_resume,
+	resolve,
+	tool_flags,
+	with_profile,
+}
+
+export type { ClaudeArgv, ClaudeArgvResult }
+export { claude_agent_argv }

package/scripts/agent/claude-result-event.ts

@@ -0,0 +1,98 @@
+import { z } from 'zod'
+import { interactive_ask } from './interactive-ask'
+
+const RESULT_EVENT_SCHEMA = z.looseObject({
+	type: z.literal('result'),
+	is_error: z.unknown().optional(),
+	subtype: z.unknown().optional(),
+	num_turns: z.unknown().optional(),
+	permission_denials: z.unknown().optional(),
+	result: z.unknown().optional(),
+	session_id: z.unknown().optional(),
+	usage: z.unknown().optional(),
+})
+const USAGE_SCHEMA = z.looseObject({
+	input_tokens: z.unknown().optional(),
+	cache_read_input_tokens: z.unknown().optional(),
+	output_tokens: z.unknown().optional(),
+})
+
+interface ClaudeResultEvent {
+	is_error: boolean
+	// The exit-record fields a supervisor classifies a dispatched lane child's ending from
+	// (joshuafolkken/kit#2139). `subtype` and `num_turns` describe how the turn ended, and
+	// `permission_denials` is the count of tool calls the harness refused — the direct cause of a child
+	// that stopped mid-implementation without parking, so a classifier can name it in the park comment.
+	subtype: string | undefined
+	num_turns: number | undefined
+	permission_denials: number
+	// The refused interactive ask lifted out of `permission_denials` (joshuafolkken/kit#2201). Where a
+	// child reached for `AskUserQuestion` and was refused, its question and options are stranded in the
+	// exit record; `run:ending` puts them into the park comment so a person can answer, instead of the
+	// parent opening the JSONL by hand. Undefined when no denial was an interactive ask.
+	refused_ask: string | undefined
+	reason: string | undefined
+	// The Claude Code session identifier the `-p --output-format stream-json` run wrote on its result
+	// event (joshuafolkken/kit#2317). An `outage` re-dispatch reads it to resume the disconnected child's
+	// stored session — recovering its accumulated context — rather than starting a fresh `fullrun`.
+	// Undefined when the event carried none, which sends the re-dispatch down the fresh fallback.
+	session_id: string | undefined
+	usage:
+		| {
+				input_tokens?: number | undefined
+				cached_input_tokens?: number | undefined
+				output_tokens?: number | undefined
+		  }
+		| undefined
+}
+
+function usable_reason(value: unknown): string | undefined {
+	return typeof value === 'string' && value.trim() !== '' ? value : undefined
+}
+
+function numeric_value(value: unknown): number | undefined {
+	return typeof value === 'number' ? value : undefined
+}
+
+// A missing or malformed `permission_denials` counts as zero refusals rather than an unknown, so the
+// classifier reads "no denials" the same way whether the harness omitted the field or wrote an empty
+// array. It is the array's length, never its contents — the count is what the park comment carries.
+function denial_count(value: unknown): number {
+	return Array.isArray(value) ? value.length : 0
+}
+
+function usage_of(value: unknown): ClaudeResultEvent['usage'] {
+	const parsed = USAGE_SCHEMA.safeParse(value)
+	if (!parsed.success) return undefined
+	const usage = {
+		input_tokens: numeric_value(parsed.data.input_tokens),
+		cached_input_tokens: numeric_value(parsed.data.cache_read_input_tokens),
+		output_tokens: numeric_value(parsed.data.output_tokens),
+	}
+
+	return Object.values(usage).some((count) => count !== undefined) ? usage : undefined
+}
+
+function decode(value: unknown): ClaudeResultEvent | undefined {
+	const parsed = RESULT_EVENT_SCHEMA.safeParse(value)
+	if (!parsed.success) return undefined
+	const is_error = parsed.data.is_error === true
+
+	return {
+		is_error,
+		subtype: usable_reason(parsed.data.subtype),
+		num_turns: numeric_value(parsed.data.num_turns),
+		permission_denials: denial_count(parsed.data.permission_denials),
+		refused_ask: interactive_ask.refused_ask_of(parsed.data.permission_denials),
+		reason: is_error
+			? (usable_reason(parsed.data.result) ?? usable_reason(parsed.data.subtype))
+			: undefined,
+		session_id: usable_reason(parsed.data.session_id),
+		usage: usage_of(parsed.data.usage),
+	}
+}
+
+const claude_result_event = { decode }
+
+export type { ClaudeResultEvent }
+export { claude_result_event }