@namzu/sdk 44.3.0 → 45.1.0

package/src/runtime/jobs/registry.ts

@@ -2,6 +2,7 @@ import { spawn } from 'node:child_process'
 
 import { SANDBOX_KILL_GRACE_MS } from '../../constants/sandbox/index.js'
 import { killTree } from '../../process/kill-tree.js'
+import { hostShellSpawn } from '../../tools/command-shell.js'
 import { scrubInheritedEnv } from '../../tools/env-scrub.js'
 import { awaitWithAbort } from '../../utils/await-with-abort.js'
 
@@ -72,8 +73,8 @@ export interface StartJobParams {
 	readonly env?: Readonly<Record<string, string>>
 	/**
 	 * Start the process yourself — a sandbox does, so the job runs inside
-	 * its boundary. Absent, the registry runs `/bin/sh -c command` on the
-	 * host. The process must be the leader of its own group and must not
+	 * its boundary. Absent, the registry runs it on the
+	 * host in the `bash` tool's shell (`tools/command-shell.ts`). The process must be the leader of its own group and must not
 	 * expect stdin.
 	 */
 	readonly spawn?: () => JobProcess
@@ -205,18 +206,25 @@ export class BackgroundJobRegistry {
 		// started it, which makes the leak longer-lived, not smaller.
 		const inherited = scrubInheritedEnv()
 
+		// The same shell as a foreground `bash` call, so the permission
+		// rules' reading of the line holds for the job too.
+		const shell = hostShellSpawn(params.command, { ...inherited.env, ...params.env })
 		const started = params.spawn
 			? params.spawn()
 			: {
-					child: spawn('/bin/sh', ['-c', params.command], {
-						cwd: params.workingDirectory,
-						env: { ...inherited.env, ...params.env },
-						// Leader of its own process group, which is what `killTree` needs
-						// to reach the command and everything it forks rather than only the
-						// wrapping shell. See `process/kill-tree.ts`.
-						detached: process.platform !== 'win32',
-						stdio: ['ignore', 'pipe', 'pipe'],
-					}),
+					child: spawn(
+						shell.file ?? '/bin/sh',
+						shell.file === undefined ? ['-c', params.command] : [...shell.args],
+						{
+							cwd: params.workingDirectory,
+							env: shell.env,
+							// Leader of its own process group, which is what `killTree` needs
+							// to reach the command and everything it forks rather than only the
+							// wrapping shell. See `process/kill-tree.ts`.
+							detached: process.platform !== 'win32',
+							stdio: ['ignore', 'pipe', 'pipe'],
+						},
+					),
 				}
 		const child = started.child
 		// Started, not adopted: this process stays the parent for the job's

package/src/runtime/query/declined.ts

@@ -0,0 +1,12 @@
+/**
+ * What the model is told when a person declines its tool calls and gave no
+ * words of their own.
+ *
+ * "Declined" alone reads to a model as an obstacle to route around: in a live
+ * session an operator refused a browser navigation and the model fetched the
+ * same page through web search instead. The refusal is about the outcome, not
+ * the tool, so the text says so — for every tool, since any of them can be
+ * swapped for another that reaches the same place.
+ */
+export const DECLINED_TOOL_CALL_FEEDBACK =
+	'The user declined this. Do not get the same content or result another way (another tool, another site or address, or a web search) unless you ask the user first and they agree. Say what you wanted to do, or carry on without it.'

package/src/runtime/query/executor.ts

@@ -1,6 +1,7 @@
 import { join } from 'node:path'
 import type { Span } from '@opentelemetry/api'
 import type { AuthorizationGate } from '../../authorization/gate.js'
+import { type SkillGrantSet, compileSkillGrant } from '../../authorization/skill-grant.js'
 import { extractFromToolCall, extractFromToolResult } from '../../compaction/extractor.js'
 import type { WorkingStateManager } from '../../compaction/manager.js'
 import { GENAI, NAMZU } from '../../constants/telemetry/index.js'
@@ -10,7 +11,8 @@ import { ProbeVetoError } from '../../probe/errors.js'
 import { probe as defaultProbeRegistry } from '../../probe/registry.js'
 import type { ProbeEnforcement } from '../../probe/registry.js'
 import type { ActivityStore } from '../../store/activity/memory.js'
-import { SKILL_TOOL_NAME } from '../../tools/builtins/skill.js'
+import { sandboxShellSpawn, withoutBashStartup } from '../../tools/command-shell.js'
+import { isAlwaysDestructive } from '../../tools/defineTool.js'
 import { createFileReadTracker } from '../../tools/file-read-tracker.js'
 import { pathOutsideRoots, toolRoots } from '../../tools/paths.js'
 import type { ToolResultGuardrailSpec } from '../../types/guardrail/index.js'
@@ -33,9 +35,11 @@ import type {
 	FileReadTracker,
 	PreparedToolExecution,
 	RequestToolPause,
+	ShellDialect,
 	SkillRegistryRef,
 	ToolContext,
 	ToolDispatchOptions,
+	ToolHandoff,
 	ToolRegistryContract,
 	ToolResult,
 } from '../../types/tool/index.js'
@@ -449,6 +453,12 @@ export interface ToolExecutorConfig {
 	authorizationGate?: AuthorizationGate
 	/** Durable refusal sink paired with {@link authorizationGate}. */
 	recordAudit?: (input: AuditEventInput) => Promise<unknown>
+	/**
+	 * Where the `skill` tool's `allowed-tools` pre-approvals are recorded for
+	 * this turn. The review phase reads the same set. Absent: a loaded skill
+	 * grants nothing, and its tool says so.
+	 */
+	skillGrants?: SkillGrantSet
 }
 
 /**
@@ -480,6 +490,8 @@ export interface ToolCallOutcome {
 	/** Rich form for the model, when the tool supplied one. */
 	content?: ToolResultContent
 	isError?: boolean
+	/** The tool asked for a person; see `ToolResult.handoff`. */
+	handoff?: ToolHandoff
 }
 
 export interface ToolExecutionBatch {
@@ -692,58 +704,83 @@ export class ToolExecutor {
 	private batchMode?: PermissionMode
 
 	/**
-	 * The tool scope a loaded skill declared, and the batch it applies from.
-	 *
-	 * `allowed-tools` was parsed, stored and rendered into the prompt, and
-	 * read by nothing — advice phrased as a declaration. This is what makes
-	 * it a restriction, on the same line that already enforces the step's
-	 * list, because a narrowing the model can decline is not one.
-	 *
-	 * Two fields rather than one, and the second is the point: a skill
-	 * loaded MID-batch must not retroactively refuse the calls the model
-	 * issued alongside it. The model chose that batch under the old scope,
-	 * and refusing half of it teaches nothing except that tools fail at
-	 * random. `adoptedInBatch` is compared against the batch counter, so the
-	 * scope takes effect from the next one.
+	 * The step's list where it has one; the turn's is the default.
 	 *
-	 * **`adoptedInBatch` is redundant TODAY and kept deliberately**, the same
-	 * bargain `batchMode` above documents. `buildToolContext()` runs once per
-	 * batch, so every call in a batch already shares one `allowedTools` array
-	 * computed before any of them could adopt anything — remove this
-	 * comparison and no test changes, because the guarantee currently comes
-	 * from where the context happens to be built rather than from here.
-	 * Moving the context into the per-call spread is a plausible refactor,
-	 * and it would silently produce a batch whose second half is refused for
-	 * a scope its first half installed. That is precisely the incoherent
-	 * batch this line exists to make impossible.
+	 * A loaded skill no longer narrows this. Its `allowed-tools` used to be
+	 * intersected in here from the next batch on, which read the field as a
+	 * restriction when it is a pre-approval; see `grantSkillTools`.
 	 */
-	private skillScope?: {
-		skill: string
-		allowedTools: readonly string[]
-		adoptedInBatch: number
+	private effectiveAllowedTools(): readonly string[] | undefined {
+		return this.stepAllowedTools ?? this.config.allowedTools
 	}
-	private batchCounter = 0
 
 	/**
-	 * The step's list, narrowed by any skill scope in force.
+	 * Compile a skill's `allowed-tools` into pre-approvals for the rest of the
+	 * turn, say what they would be, and record them only on `commit()`.
 	 *
-	 * An INTERSECTION, never a replacement: a skill cannot hand the model a
-	 * tool the step withheld. Widening has to be unexpressible rather than
-	 * discouraged — the same rule `CreateTaskOptions.toolScope` states for
-	 * delegation, and for the same reason: a skill file is content, and
-	 * content that can grant tools is a privilege-escalation surface wearing
-	 * the word "scope".
+	 * Names resolve against THIS turn's registry, case-insensitively and
+	 * through the Agent Skills aliases (`Read` is `read`, `WebFetch` is
+	 * `web_fetch`), so a grant can only ever name a tool the turn already has.
+	 * An entry that resolves to nothing, or to a tool every call of which is
+	 * destructive (and therefore always reviewed), is reported and grants
+	 * nothing.
 	 *
-	 * The `skill` tool itself always survives. A skill that narrowed the
-	 * model out of reaching for another skill would be a one-way door, and
-	 * the tool reads instructions and changes nothing.
+	 * Two steps because the `skill` tool can still fail after it knows what
+	 * to say — its instructions may not fit the output budget — and a skill
+	 * the model never received must not have approved anything.
 	 */
-	private effectiveAllowedTools(): readonly string[] | undefined {
-		const base = this.stepAllowedTools ?? this.config.allowedTools
-		const scope = this.skillScope
-		if (!scope || scope.adoptedInBatch >= this.batchCounter) return base
-		const narrowed = new Set([...scope.allowedTools, SKILL_TOOL_NAME])
-		return base === undefined ? [...narrowed] : base.filter((name) => narrowed.has(name))
+	private grantSkillTools(grant: {
+		readonly skill: string
+		readonly allowedTools: readonly string[]
+		readonly skillDirectory?: string
+	}): {
+		readonly granted: readonly string[]
+		readonly ignored: readonly {
+			readonly entry: string
+			readonly reason: string
+		}[]
+		readonly commit: () => void
+	} {
+		const grants = this.config.skillGrants
+		if (!grants) return { granted: [], ignored: [], commit: () => {} }
+		const tools = this.config.tools
+		const byLowerName = new Map<string, string>()
+		for (const name of tools.listNames()) byLowerName.set(name.toLowerCase(), name)
+		// A grant can only ever name a tool this turn — or this step — can call.
+		// The registry holds more than that when `allowedTools` withholds some,
+		// and telling the model a withheld tool is pre-approved is a promise the
+		// executor will refuse to keep.
+		const allowed = this.effectiveAllowedTools()
+		const compiled = compileSkillGrant(grant.allowedTools, {
+			resolveTool: (name) => {
+				const registered = byLowerName.get(name.toLowerCase())
+				if (registered === undefined) return undefined
+				const definition = tools.get(registered)
+				const commandArgument = definition?.commandArgument
+				return {
+					name: registered,
+					...(allowed !== undefined && !allowed.includes(registered) ? { unavailable: true } : {}),
+					...(commandArgument === undefined ? {} : { commandArgument }),
+					...(definition && isAlwaysDestructive(definition) ? { alwaysDestructive: true } : {}),
+				}
+			},
+			...(grant.skillDirectory ? { skillDirectory: grant.skillDirectory } : {}),
+		})
+		return {
+			granted: compiled.entries.map((entry) =>
+				entry.pattern === undefined ? entry.tool : entry.declared,
+			),
+			ignored: compiled.ignored,
+			commit: () => {
+				grants.grant(grant.skill, compiled)
+				if (compiled.ignored.length > 0) {
+					this.log.warn('Skill allowed-tools entries were ignored', {
+						'namzu.skill.name': grant.skill,
+						'namzu.skill.ignored': compiled.ignored.map((item) => item.entry),
+					})
+				}
+			},
+		}
 	}
 
 	private resolvePermissionMode(): PermissionMode {
@@ -757,9 +794,20 @@ export class ToolExecutor {
 			toolName,
 			toolInput: input,
 			toolDef: this.config.tools.get(toolName),
+			commandDialect: this.commandDialect(toolName),
 		})
 	}
 
+	/**
+	 * The shell a tool's command line will run in this turn, for the
+	 * permission rules to read it in. A tool that does not say is `sh`, the
+	 * reading that holds for any POSIX shell.
+	 */
+	commandDialect(toolName: string): ShellDialect {
+		const tool = this.config.tools.get(toolName)
+		return tool?.commandDialect?.({ sandboxed: this.config.sandbox !== undefined }) ?? 'sh'
+	}
+
 	/**
 	 * Resolve repairs and pre-tool hooks, then decode each call exactly once.
 	 * The returned projection is what policy and a human review; execution later
@@ -883,8 +931,6 @@ export class ToolExecutor {
 		}
 		assertUniqueToolCallIds(toolCalls)
 
-		this.batchCounter += 1
-
 		// Sampled here, once, and held for every call below. See the note on
 		// `permissionMode` in the config type.
 		this.batchMode = this.resolvePermissionMode()
@@ -1212,6 +1258,7 @@ export class ToolExecutor {
 			toolName: name,
 			toolInput: preparedInput,
 			toolDef: this.config.tools.get(name),
+			commandDialect: this.commandDialect(name),
 		})
 		if (gateResult && gateResult.decision !== 'allow') {
 			const reason =
@@ -1402,9 +1449,16 @@ export class ToolExecutor {
 	}
 
 	private resultPresentation(name: string, input: unknown, result: ToolResult) {
-		if (!result.success) return {}
 		try {
 			const view = this.config.tools.get(name)?.presentResult?.(input, result)
+			// A failed call carries one view only: the person's No on the tool's
+			// own screen, which a host draws as cancelled rather than failed and
+			// cannot tell apart from the result text alone.
+			if (!result.success) {
+				return view?.kind === 'generic' && view.outcome === 'cancelled'
+					? { presentation: { kind: 'generic', label: view.label, outcome: 'cancelled' } as const }
+					: {}
+			}
 			if (view?.kind !== 'diff') return {}
 			const serialized = JSON.stringify(view)
 			if (serialized.length > (this.config.maxToolOutputChars ?? DEFAULT_MAX_TOOL_OUTPUT_CHARS))
@@ -1442,11 +1496,11 @@ export class ToolExecutor {
 			// Same precedence the request already uses when it decides which
 			// schemas to send, so the menu and the kitchen agree.
 			allowedTools: this.effectiveAllowedTools(),
-			// Recorded, not applied here: a skill loaded during this batch
-			// narrows the NEXT one. See `skillScope`.
-			adoptSkillScope: (scope) => {
-				this.skillScope = { ...scope, adoptedInBatch: this.batchCounter }
-			},
+			// A skill loaded during this batch pre-approves calls from the NEXT
+			// review on; this batch was already reviewed. See `grantSkillTools`.
+			...(this.config.skillGrants
+				? { grantSkillTools: (grant) => this.grantSkillTools(grant) }
+				: {}),
 			maxToolOutputChars: this.config.maxToolOutputChars ?? DEFAULT_MAX_TOOL_OUTPUT_CHARS,
 			// The turn's screens, defaulted HERE rather than on the registry: a
 			// host builds the registry and hands it over, so a registry-side
@@ -1498,11 +1552,11 @@ export class ToolExecutor {
 												readonly env?: Record<string, string>
 											}): JobProcess =>
 												(this.config.sandbox as Sandbox).spawnDetached?.(
-													'/bin/sh',
-													['-c', job.command],
+													sandboxShellSpawn(job.command).file,
+													sandboxShellSpawn(job.command).args,
 													{
 														cwd: job.workingDirectory,
-														...(job.env ? { env: job.env } : {}),
+														...(job.env ? { env: withoutBashStartup(job.env) } : {}),
 													},
 												) as JobProcess,
 										}
@@ -1960,6 +2014,12 @@ export class ToolExecutor {
 			// a result whose image is unaffected — and a hook that needs it gone
 			// says so with `content`, which wins over both.
 			...(modelContent !== undefined ? { content: modelContent } : {}),
+			// Carried whatever a post-tool hook did to the text: the request is
+			// the tool's statement about the world, not about its output, and a
+			// hook that redacts a sign-in page has not signed anyone in.
+			...(result.handoff !== undefined && !this.config.abortSignal.aborted
+				? { handoff: result.handoff }
+				: {}),
 		}
 	}
 

package/src/runtime/query/index.ts

@@ -6,6 +6,7 @@ import {
 	assertBudgetEnforceable,
 } from '../../advisory/index.js'
 import { AuthorizationGate } from '../../authorization/gate.js'
+import { SkillGrantSet } from '../../authorization/skill-grant.js'
 import { repairToolMessageHistory, toolHistoryRepairChanged } from '../../compaction/dangling.js'
 import { extractFromUserMessage } from '../../compaction/extractor.js'
 import { WorkingStateManager } from '../../compaction/manager.js'
@@ -1197,8 +1198,13 @@ export async function* query(params: QueryParams): AsyncGenerator<SessionEvent,
 			: undefined
 		awaitedJobs?.attach()
 
+		// Turn-scoped, like `toolGrants` below: what a skill loaded in this turn
+		// pre-approves ends with the turn. Shared by the executor, where the
+		// `skill` tool records a grant, and the review phase, which reads it.
+		const skillGrants = new SkillGrantSet()
 		const toolExecutor = ToolingBootstrap.init(
 			{
+				skillGrants,
 				tools: params.tools,
 				sessionId: ctx.sessionId,
 				turnId: ctx.turnId,
@@ -1456,6 +1462,7 @@ export async function* query(params: QueryParams): AsyncGenerator<SessionEvent,
 			provider: resilientProvider,
 			providerCapabilities: capabilities,
 			strictCapabilities: params.strictCapabilities === true,
+			...(params.parentSessionId !== undefined ? { delegated: true } : {}),
 			servingMember: () => serving.current,
 			turnConfig,
 			...(params.stopWhen ? { stopWhen: params.stopWhen } : {}),
@@ -1496,6 +1503,7 @@ export async function* query(params: QueryParams): AsyncGenerator<SessionEvent,
 			// Turn-scoped. An approval is a statement about this turn's work;
 			// carrying one into a later turn would be reuse nobody agreed to.
 			toolGrants: new ToolGrantSet(),
+			skillGrants,
 			...(params.reviewAllowedCalls ? { reviewAllowedCalls: params.reviewAllowedCalls } : {}),
 			// Turn-scoped for the same reason. A repeat count carried into a later
 			// run is a claim about work nobody repeated, and a module-level map

package/src/runtime/query/iteration/index.ts

@@ -71,6 +71,7 @@ import {
 	relieveOverflow,
 	runCompactionCheck,
 } from './phases/compaction.js'
+import { runHandoffPause } from './phases/handoff.js'
 import type { IterationContext } from './phases/index.js'
 import { runPlanGate } from './phases/plan.js'
 import { runToolReview } from './phases/tool-review.js'
@@ -1421,6 +1422,13 @@ export class IterationOrchestrator {
 						return
 					}
 
+					// A tool asked for a person. The whole batch is committed; the
+					// turn parks here rather than asking the model what to do about
+					// something only the operator can do.
+					if ((yield* runHandoffPause(this.ctx, iterationNum, reviewOutcome.results)) === 'stop') {
+						return
+					}
+
 					if (reviewOutcome.decision === 'rejected') {
 						continue
 					}
@@ -1826,6 +1834,11 @@ export class IterationOrchestrator {
 	private rememberUserMessage(message: Message, arriving = true): void {
 		if (!isOperatorUserMessage(message)) return
 		this.latestUserMessage = message
+		// A skill's `allowed-tools` pre-approves for the request that loaded
+		// it. The operator speaking again — a queued message or steering
+		// delivered into this same `query()` — is a new request, and it starts
+		// with nothing pre-approved, exactly as a new turn would.
+		if (arriving) this.ctx.skillGrants?.clear()
 		// The hook field alone does not reach the model. Preserve arrivals in
 		// the compaction state too, before their original message or attached
 		// tool result can be shed. Initial history was already extracted at seed.

package/src/runtime/query/iteration/phases/context.ts

@@ -1,4 +1,5 @@
 import type { AdvisoryContext } from '../../../../advisory/context.js'
+import type { SkillGrantSet } from '../../../../authorization/skill-grant.js'
 import type { AgentBus } from '../../../../bus/index.js'
 import type { WorkingStateManager } from '../../../../compaction/manager.js'
 import type { ContextReducer } from '../../../../compaction/reducer.js'
@@ -43,6 +44,12 @@ import type { ToolGrantSet } from '../../tool-grants.js'
 
 export interface IterationContext {
 	readonly provider: LLMProvider
+	/**
+	 * The turn runs in a delegated child session. A tool's request for a
+	 * person then fails the turn instead of pausing it: nobody is watching
+	 * a child to resume it, and its parent is waiting on a result.
+	 */
+	readonly delegated?: boolean
 	/** Driver-level request shapes negotiated for this turn. */
 	readonly providerCapabilities?: ResolvedProviderCapabilities
 	/** Refuse a capability mismatch instead of emitting a warning and degrading. */
@@ -166,6 +173,12 @@ export interface IterationContext {
 	 * asked about again. Absent on paths that do not review tools.
 	 */
 	readonly toolGrants?: ToolGrantSet
+	/**
+	 * What skills loaded in this turn pre-approve (`allowed-tools`). Read by
+	 * the review phase to mark covered calls; the review policy decides
+	 * whether a mark skips the prompt. Absent: nothing is marked.
+	 */
+	readonly skillGrants?: SkillGrantSet
 	/** See `QueryParams.reviewAllowedCalls`. Absent: allowed and granted batches skip review. */
 	readonly reviewAllowedCalls?: () => boolean
 	/**

package/src/runtime/query/iteration/phases/handoff.ts

@@ -0,0 +1,74 @@
+import { GENAI, NAMZU } from '../../../../telemetry/attributes.js'
+import { NamzuError } from '../../../../types/errors/index.js'
+import type { SessionEvent } from '../../../../types/session/index.js'
+import type { ToolCallOutcome } from '../../executor.js'
+import type { IterationContext, PhaseSignal } from './context.js'
+
+/**
+ * A tool asked for a person: stop before the next model call.
+ *
+ * Runs after the batch settled, so every result — the one that asked and
+ * its siblings — is already in the transcript and queued for the session
+ * log. The checkpoint written here is taken from that state, which is what
+ * lets a resume continue exactly as it does after a provider pause: the
+ * next step is a model call that sees the results.
+ *
+ * The first request in the batch speaks for it. Two tools that both need a
+ * person need the same thing from the operator — to come and look — and
+ * one pause answers both.
+ *
+ * In a delegated child the turn fails with the reason instead. Nobody
+ * resumes a child's turn: its parent is waiting on a result, and a failed
+ * child with the reason in it is a result the parent's model can act on.
+ */
+export async function* runHandoffPause(
+	ctx: IterationContext,
+	iterationNum: number,
+	results: readonly ToolCallOutcome[],
+): AsyncGenerator<SessionEvent, PhaseSignal> {
+	const requested = results.find((result) => result.handoff !== undefined)
+	const handoff = requested?.handoff
+	if (!requested || !handoff) return 'continue'
+
+	if (ctx.delegated) {
+		ctx.log.info('A tool in a delegated turn needs a person; the turn fails', {
+			[NAMZU.TURN_ID]: ctx.recorder.turnId,
+			[NAMZU.ITERATION]: iterationNum,
+			[GENAI.TOOL_NAME]: requested.toolName,
+		})
+		throw new NamzuError({
+			code: 'tool_error',
+			message: `${requested.toolName} needs a person: ${handoff.reason}`,
+			details: { toolName: requested.toolName, handoff },
+			retryable: false,
+		})
+	}
+
+	const checkpoint = await ctx.checkpointMgr.create(ctx.recorder, iterationNum)
+	await ctx.emitEvent({
+		type: 'checkpoint_created',
+		turnId: ctx.recorder.turnId,
+		checkpointId: checkpoint.id,
+		iteration: iterationNum,
+	})
+	yield* ctx.drainPending()
+
+	await ctx.emitEvent({
+		type: 'turn_paused',
+		budget: ctx.recorder.budget?.summary(),
+		turnId: ctx.recorder.turnId,
+		checkpointId: checkpoint.id,
+		reason: handoff.reason,
+		handoff,
+	})
+	yield* ctx.drainPending()
+	ctx.recorder.setStopReason('paused')
+	ctx.log.info('Turn paused for a person', {
+		[NAMZU.TURN_ID]: ctx.recorder.turnId,
+		[NAMZU.ITERATION]: iterationNum,
+		[GENAI.TOOL_NAME]: requested.toolName,
+		'namzu.checkpoint.id': checkpoint.id,
+		'namzu.runtime.reason': handoff.reason,
+	})
+	return 'stop'
+}

package/src/runtime/query/iteration/phases/index.ts

@@ -6,3 +6,4 @@ export type { ToolReviewOutcome } from './tool-review.js'
 export { runIterationCheckpoint } from './checkpoint.js'
 export { runCompactionCheck } from './compaction.js'
 export { runAdvisoryPhase } from './advisory.js'
+export { runHandoffPause } from './handoff.js'

package/src/runtime/query/iteration/phases/tool-review.ts

@@ -2,6 +2,8 @@ import type { AuthorizationGate } from '../../../../authorization/index.js'
 import type { ToolCallSummary } from '../../../../types/hitl/index.js'
 import type { ChatCompletionResponse } from '../../../../types/provider/index.js'
 import type { SessionEvent } from '../../../../types/session/index.js'
+import type { ShellDialect } from '../../../../types/tool/index.js'
+import { DECLINED_TOOL_CALL_FEEDBACK } from '../../declined.js'
 import type { PreparedToolBatch, ToolCallDenials } from '../../executor.js'
 import {
 	awaitProjectInstructionCallback,
@@ -53,6 +55,17 @@ export async function* runToolReview(
 ): AsyncGenerator<SessionEvent, ToolReviewOutcome> {
 	let executed: readonly import('../../executor.js').ToolCallOutcome[] = []
 	let toolMs = 0
+	// The shell each call's command line will run in, for the rules and the
+	// skill grants to read it the same way. A test double without the method
+	// leaves it unset, which reads the line for any POSIX shell.
+	const dialectFor = (toolName: string): { commandDialect?: ShellDialect } => {
+		const executor = ctx.toolExecutor as {
+			commandDialect?: (name: string) => ShellDialect
+		}
+		return typeof executor.commandDialect === 'function'
+			? { commandDialect: executor.commandDialect(toolName) }
+			: {}
+	}
 
 	const finish = (decision: ToolReviewDecision): ToolReviewOutcome => ({
 		decision,
@@ -255,6 +268,7 @@ export async function* runToolReview(
 				toolName: tc.name,
 				toolInput: tc.input,
 				toolDef: ctx.tools.get(tc.name),
+				...dialectFor(tc.name),
 			}),
 		}))
 		for (const gr of gateResults) {
@@ -331,6 +345,24 @@ export async function* runToolReview(
 		})
 	}
 
+	// A skill's `allowed-tools` pre-approval, marked on the calls it covers
+	// and left for the review policy to honour. Marked, never decided here:
+	// only the policy knows the mode, and `plan` and `strict` must refuse a
+	// call a skill granted exactly as they refuse any other. Nothing stronger
+	// may stand in the way — an operator's deny or explicit ask, a
+	// destructive call, a path outside the roots or a sandbox escape all
+	// leave the call unmarked, so it is reviewed as though no skill had
+	// spoken.
+	if (ctx.skillGrants && ctx.skillGrants.size > 0) {
+		for (const tc of toolCallSummaries) {
+			if (gateDenied.has(tc.id)) continue
+			if (tc.authorization?.decision === 'deny' || tc.authorization?.explicitReview) continue
+			if (tc.isDestructive || tc.escalation !== undefined) continue
+			const skill = ctx.skillGrants.coveringSkill(tc, ctx.tools.get(tc.name), dialectFor(tc.name))
+			if (skill !== undefined) tc.skillGrant = { skill }
+		}
+	}
+
 	// Already approved, at a scope the approver chose — and nothing the
 	// operator's policy denied, because `gateDenied` is checked first.
 	// Re-asking about a call somebody has already said yes to is how an
@@ -419,7 +451,11 @@ export async function* runToolReview(
 			}
 			for (const path of tc.escalation?.outsidePaths ?? []) {
 				await ctx.recorder.recordAudit({
-					what: { action: 'outside_root_access', tool: tc.name, resource: path },
+					what: {
+						action: 'outside_root_access',
+						tool: tc.name,
+						resource: path,
+					},
 					outcome: 'approved',
 					reason: "the turn's review approved this call",
 				})
@@ -436,7 +472,7 @@ export async function* runToolReview(
 			})
 			yield* ctx.drainPending()
 
-			const feedback = reviewDecision.feedback || 'The user rejected this tool call.'
+			const feedback = reviewDecision.feedback || DECLINED_TOOL_CALL_FEEDBACK
 			const denials = new Map(denyAll(feedback))
 			await settleEscalations(denials, undefined)
 			await settle(denials)
@@ -466,7 +502,7 @@ export async function* runToolReview(
 					}
 				}
 				if (mod.action === 'deny' && !denials.has(mod.toolCallId)) {
-					denials.set(mod.toolCallId, 'The user denied this tool call.')
+					denials.set(mod.toolCallId, DECLINED_TOOL_CALL_FEEDBACK)
 				}
 			}
 
@@ -490,6 +526,7 @@ export async function* runToolReview(
 						toolName: summary.name,
 						toolInput: summary.input,
 						toolDef: ctx.tools.get(summary.name),
+						...dialectFor(summary.name),
 					})
 					if (gateResult.decision === 'allow') continue
 					const reason =
@@ -550,6 +587,21 @@ export async function* runToolReview(
 			if (reviewDecision.action === 'approve_tools' && reviewDecision.remember) {
 				ctx.toolGrants?.grant(reviewDecision.remember)
 			}
+			// A call nobody was asked about, approved because a skill said so,
+			// is on the record naming that skill. Only a call that carried the
+			// mark counts: a policy that lists an unmarked id has not been
+			// given a skill's word for it.
+			if (reviewDecision.action === 'approve_tools' && reviewDecision.skillGranted) {
+				const listed = new Set(reviewDecision.skillGranted)
+				for (const tc of toolCallSummaries) {
+					if (!listed.has(tc.id) || !tc.skillGrant || gateDenied.has(tc.id)) continue
+					await ctx.recorder.recordAudit({
+						what: { action: 'tool_call', tool: tc.name },
+						outcome: 'approved',
+						reason: `pre-approved by the allowed-tools of skill "${tc.skillGrant.skill}" for this turn; nobody was asked`,
+					})
+				}
+			}
 
 			await ctx.emitEvent({
 				type: 'tool_review_completed',