@namzu/sdk 44.2.0 → 45.0.0

package/src/tools/builtins/skill.ts

@@ -1,23 +1,27 @@
 import { createHash } from 'node:crypto'
 import { z } from 'zod'
 
+import { parseAllowedTools } from '../../authorization/skill-grant.js'
 import { isInvocableBy, skillInvocation } from '../../types/skills/index.js'
 import { defineTool } from '../defineTool.js'
 
+export { parseAllowedTools }
+
 /**
- * Load a skill's instructions, and adopt whatever it says it needs.
+ * Load a skill's instructions, and apply what its `allowed-tools` grants.
  *
  * The manifest in the system prompt told the model that a SKILL.md exists
  * and to "read the SKILL.md at its <location> before writing code" — which
  * is a filesystem instruction, so a turn with no filesystem tools could see
- * every skill it had and open none of them. The protocol text even admits
- * it: *"when the runtime exposes filesystem or skill-loading tools"*. There
- * was no skill-loading tool.
+ * every skill it had and open none of them. There was no skill-loading tool.
  *
- * `allowed-tools` had the same shape of problem from the other side. It was
- * parsed, carried into `SkillMetadata`, rendered into the prompt as
- * `<allowed_tools>…</allowed_tools>` — and read by nothing. It was advice
- * the model could take or ignore, phrased as a declaration.
+ * `allowed-tools` is a PRE-APPROVAL, as the Agent Skills format defines it:
+ * the listed tools skip the approval prompt for the rest of this turn, and
+ * every other tool stays callable under the turn's ordinary review. It was
+ * read here for a while as a restriction — the listed tools and nothing
+ * else, from the next batch — which inverted what skill authors mean by it
+ * and left a model that loaded `allowed-tools: Read Grep` without `bash`.
+ * See `authorization/skill-grant.ts` for what a grant can and cannot do.
  */
 
 const inputSchema = z.object({
@@ -47,6 +51,8 @@ interface SkillSnapshot {
 	readonly name: string
 	readonly body: string
 	readonly allowedTools: readonly string[] | undefined
+	/** Bound into the cursor because `${CLAUDE_SKILL_DIR}` in a grant expands to it. */
+	readonly skillDirectory: string | undefined
 	readonly invocation: ReturnType<typeof skillInvocation>
 }
 
@@ -76,6 +82,9 @@ function snapshotDigest(snapshot: SkillSnapshot): string {
 				name: snapshot.name,
 				body: snapshot.body,
 				allowedTools: snapshot.allowedTools ?? null,
+				...(snapshot.skillDirectory === undefined
+					? {}
+					: { skillDirectory: snapshot.skillDirectory }),
 				invocation: snapshot.invocation,
 			}),
 		)
@@ -231,27 +240,6 @@ function pageSkillBody(input: {
 	return undefined
 }
 
-/**
- * `allowed-tools` as a list.
- *
- * Comma-separated in the frontmatter because that is what authors write and
- * what the field has always accepted. Split here rather than at parse so
- * the stored metadata keeps the author's own string — the same reasoning
- * `invocation` uses for not defaulting at parse.
- */
-export function parseAllowedTools(declared: string | undefined): readonly string[] | undefined {
-	if (declared === undefined) return undefined
-	const names = declared
-		.split(',')
-		.map((name) => name.trim())
-		.filter((name) => name.length > 0)
-	// An empty result from a non-empty declaration is a real answer and not
-	// the same as "declared nothing": `allowed-tools: ""` is an author
-	// saying this skill needs no tools, and collapsing it to `undefined`
-	// would silently widen that to everything.
-	return names
-}
-
 export const SKILL_TOOL_NAME = 'skill'
 
 export const SkillTool = defineTool({
@@ -261,9 +249,9 @@ export const SkillTool = defineTool({
 	inputSchema,
 	category: 'analysis',
 	permissions: [],
-	// Reads instructions and changes nothing. It is the one tool whose
-	// availability a narrowed skill scope must never remove, or a model
-	// inside one skill could not reach for another.
+	// Reads instructions and changes nothing on disk. What it does change is
+	// the turn's approvals, through `grantSkillTools`, and only ever towards
+	// fewer prompts for calls the operator's policy already leaves to review.
 	readOnly: true,
 	destructive: false,
 	concurrencySafe: true,
@@ -382,6 +370,7 @@ export const SkillTool = defineTool({
 			name: input.name,
 			body: skill.body ?? '(this skill has no body)',
 			allowedTools: allowed,
+			skillDirectory: skill.dirPath,
 			invocation,
 		}
 		const digest = snapshotDigest(snapshot)
@@ -403,10 +392,20 @@ export const SkillTool = defineTool({
 			start = parsed.offset
 		}
 
-		const notice =
-			allowed === undefined
-				? ''
-				: `\n\n[While following this skill, restrict yourself to: ${allowed.length > 0 ? allowed.join(', ') : '(no tools)'}. This takes effect from your next turn.]`
+		// Compiled before paging so the notice can say what the grant is, and
+		// committed only after paging succeeded: a load that fails here gave
+		// the model no instructions, so it must not have approved anything.
+		// Idempotent: a continuation call grants the same entries again, and
+		// the turn's set keeps one copy.
+		let grant: ReturnType<NonNullable<typeof context.grantSkillTools>> | undefined
+		if (allowed !== undefined && allowed.length > 0 && context.grantSkillTools) {
+			grant = context.grantSkillTools({
+				skill: skill.metadata.name,
+				allowedTools: allowed,
+				...(snapshot.skillDirectory ? { skillDirectory: snapshot.skillDirectory } : {}),
+			})
+		}
+		const notice = grantNotice(allowed, grant, context.grantSkillTools !== undefined)
 		const page = pageSkillBody({
 			snapshot,
 			digest,
@@ -421,23 +420,7 @@ export const SkillTool = defineTool({
 				error: `The model-visible tool-output budget is too small to read "${input.name}" safely. Increase maxToolOutputChars and retry.`,
 			}
 		}
-
-		// Cursor and policy validation must finish before this mutation. A
-		// continuation is bound to the body AND its effective authorization
-		// metadata, so an edit to allowed-tools or invocation cannot widen the
-		// next batch under an old cursor.
-		if (allowed !== undefined) {
-			// Adopted, not merely announced. The notice below tells the model
-			// what happened; this is what makes it true whether or not the
-			// model reads it — the difference between the field as it was and
-			// the field as a declaration.
-			//
-			// Absent `adoptSkillScope`, the notice still goes out and is all
-			// there is: a host driving this tool outside a turn has no executor
-			// to enforce anything, and saying nothing would be worse than
-			// advice.
-			context.adoptSkillScope?.({ skill: skill.metadata.name, allowedTools: allowed })
-		}
+		grant?.commit()
 
 		return {
 			success: true,
@@ -445,8 +428,46 @@ export const SkillTool = defineTool({
 			data: {
 				skill: skill.metadata.name,
 				...(allowed === undefined ? {} : { allowedTools: allowed }),
+				...(grant ? { granted: grant.granted, ignored: grant.ignored } : {}),
 				...(page.nextCursor === undefined ? {} : { nextCursor: page.nextCursor }),
 			},
 		}
 	},
 })
+
+/**
+ * What the model is told about `allowed-tools`.
+ *
+ * The sentence that matters most is the second one. The old notice said
+ * "restrict yourself to", and a model told that does exactly what the owner
+ * reported: it stops using `bash` and tries to do the work through the skill.
+ * So the notice says, every time, that nothing was taken away.
+ */
+function grantNotice(
+	allowed: readonly string[] | undefined,
+	grant:
+		| {
+				granted: readonly string[]
+				ignored: readonly { entry: string; reason: string }[]
+		  }
+		| undefined,
+	canGrant: boolean,
+): string {
+	if (allowed === undefined || allowed.length === 0) return ''
+	const unchanged =
+		'Every other tool remains available and is reviewed as usual; this skill does not limit which tools you may use.'
+	if (!canGrant || !grant) {
+		return `\n\n[This skill lists allowed-tools (${allowed.join(', ')}), but this host applies no pre-approval, so those calls are reviewed as usual. ${unchanged}]`
+	}
+	const lines: string[] = []
+	lines.push(
+		grant.granted.length > 0
+			? `Pre-approved for the rest of this turn: ${grant.granted.join(', ')}. Deny and ask rules, plan and strict mode, and review of destructive calls still apply.`
+			: 'Nothing in allowed-tools could be pre-approved.',
+	)
+	for (const { entry, reason } of grant.ignored) {
+		lines.push(`Ignored allowed-tools entry "${entry}": ${reason}.`)
+	}
+	lines.push(unchanged)
+	return `\n\n[${lines.join(' ')}]`
+}

package/src/tools/command-shell.ts

@@ -0,0 +1,166 @@
+/**
+ * Which shell runs a `bash` tool command, and in what dialect it must be read.
+ *
+ * ## Why this is one decision
+ *
+ * The permission rules read a command line before it runs
+ * (`authorization/shell-lexer.ts`), and a reading is only as good as its
+ * match with the shell that runs the line afterwards. The tool is called
+ * `bash` and its description says bash, but it used to spawn `/bin/sh -c`:
+ * bash on some hosts, `dash` on Debian and Ubuntu, `busybox sh` in small
+ * images. `$'\x3b'`, `|&`, `&>` and `<<<` mean different things in those,
+ * so a line the rules read as bash could run as something else.
+ *
+ * So the host path now runs bash wherever bash exists, and the reading
+ * follows what was actually chosen:
+ *
+ * - bash found (or named by `NAMZU_BASH_SHELL`) → `bash -c`, read in the
+ *   `bash` dialect;
+ * - no bash → `/bin/sh -c`, read in the conservative `sh` dialect, in which
+ *   every construct whose meaning differs between bash and a POSIX shell
+ *   makes a line opaque;
+ * - inside a sandbox the guest image decides, and the rules cannot see it,
+ *   so a small launcher runs bash when the guest has it and `/bin/sh`
+ *   otherwise, and the line is always read in the `sh` dialect, which is
+ *   right for either.
+ *
+ * ## Equivalent to what ran before
+ *
+ * `/bin/sh -c` read no startup file. `bash -c` reads none either, except
+ * the file `BASH_ENV` names, and it imports shell functions (`BASH_FUNC_*`)
+ * and parser options (`SHELLOPTS`, `BASHOPTS`) from its environment. Any of
+ * those would change what a command line means after the rules read it, so
+ * they are removed from the environment of the spawned bash.
+ * `NAMZU_BASH_SHELL=/bin/sh` restores the old shell exactly.
+ */
+
+import { constants, accessSync } from 'node:fs'
+import { delimiter, join } from 'node:path'
+
+import type { ShellDialect } from '../types/tool/index.js'
+
+/** The shell a host-side command runs in. */
+export interface CommandShell {
+	/** The executable, run as `<path> -c <command>`. Undefined: Node's platform shell (Windows). */
+	readonly path: string | undefined
+	/** How the permission rules read a line this shell runs. */
+	readonly dialect: ShellDialect
+	/** Where the choice came from, for diagnostics. */
+	readonly source: 'override' | 'bash' | 'sh' | 'platform'
+}
+
+/** What resolution looks at. Injected by tests to simulate a host without bash. */
+export interface CommandShellProbe {
+	readonly env: NodeJS.ProcessEnv
+	readonly platform: NodeJS.Platform
+	readonly isExecutable: (path: string) => boolean
+}
+
+const WELL_KNOWN_BASH = ['/bin/bash', '/usr/bin/bash']
+
+/** Environment variables that change what a bash command line means. */
+const BASH_STARTUP_VARIABLES = new Set(['BASH_ENV', 'ENV', 'SHELLOPTS', 'BASHOPTS'])
+
+export function findCommandShell(probe: CommandShellProbe): CommandShell {
+	const override = probe.env.NAMZU_BASH_SHELL
+	if (override !== undefined && override !== '') {
+		// Read as bash only when it is bash; anything else gets the reading
+		// that holds for every POSIX shell.
+		const name = override.slice(override.lastIndexOf('/') + 1)
+		return { path: override, dialect: name === 'bash' ? 'bash' : 'sh', source: 'override' }
+	}
+	// Windows keeps Node's platform shell. Looking `bash` up on its PATH can
+	// find WSL's launcher, which runs the command in another system.
+	if (probe.platform === 'win32') return { path: undefined, dialect: 'sh', source: 'platform' }
+	for (const directory of (probe.env.PATH ?? '').split(delimiter)) {
+		if (directory === '' || !directory.startsWith('/')) continue
+		const candidate = join(directory, 'bash')
+		if (probe.isExecutable(candidate)) return { path: candidate, dialect: 'bash', source: 'bash' }
+	}
+	for (const candidate of WELL_KNOWN_BASH) {
+		if (probe.isExecutable(candidate)) return { path: candidate, dialect: 'bash', source: 'bash' }
+	}
+	return { path: '/bin/sh', dialect: 'sh', source: 'sh' }
+}
+
+function isExecutable(path: string): boolean {
+	try {
+		accessSync(path, constants.X_OK)
+		return true
+	} catch {
+		return false
+	}
+}
+
+let resolved: CommandShell | undefined
+
+/**
+ * The host's command shell, resolved once per process. The same value serves
+ * the permission rules and the spawn, so the two cannot disagree.
+ */
+export function hostCommandShell(): CommandShell {
+	if (resolved === undefined) {
+		resolved = findCommandShell({ env: process.env, platform: process.platform, isExecutable })
+	}
+	return resolved
+}
+
+/** Replace the resolved host shell; `undefined` resolves again on next use. For tests. */
+export function setHostCommandShellForTesting(shell: CommandShell | undefined): void {
+	resolved = shell
+}
+
+/**
+ * The spawn for one command on the host: executable, arguments, environment.
+ * For bash, the variables that would change the line's meaning are dropped.
+ */
+export function hostShellSpawn(
+	command: string,
+	env: NodeJS.ProcessEnv,
+	shell: CommandShell = hostCommandShell(),
+): {
+	readonly file: string | undefined
+	readonly args: readonly string[]
+	readonly env: NodeJS.ProcessEnv
+} {
+	if (shell.path === undefined) return { file: undefined, args: [command], env }
+	if (shell.dialect !== 'bash') return { file: shell.path, args: ['-c', command], env }
+	return { file: shell.path, args: ['-c', command], env: withoutBashStartup(env) }
+}
+
+export function withoutBashStartup<T extends Readonly<Record<string, string | undefined>>>(
+	env: T,
+): T {
+	const out: Record<string, string | undefined> = {}
+	for (const [name, value] of Object.entries(env)) {
+		if (BASH_STARTUP_VARIABLES.has(name) || name.startsWith('BASH_FUNC_')) continue
+		out[name] = value
+	}
+	return out as T
+}
+
+/**
+ * The command a sandbox runs for one command line: bash when the guest has
+ * it, `/bin/sh` otherwise. The rules read a sandboxed line in the `sh`
+ * dialect, which holds for both. The command is passed as an argument, never
+ * spliced into the launcher's text.
+ *
+ * The launcher does not `unset` the startup variables: where `/bin/sh` is
+ * bash, `SHELLOPTS` arriving in the environment is readonly and `unset`
+ * fails. The guest's environment is an allowlist plus the host's `env`, so
+ * callers drop them from that `env` with {@link withoutBashStartup}.
+ */
+export const SANDBOX_SHELL_LAUNCHER =
+	'if command -v bash >/dev/null 2>&1; then exec bash -c "$1"; fi; exec /bin/sh -c "$1"'
+
+export function sandboxShellSpawn(command: string): {
+	readonly file: string
+	readonly args: string[]
+} {
+	return { file: '/bin/sh', args: ['-c', SANDBOX_SHELL_LAUNCHER, 'sh', command] }
+}
+
+/** The dialect a `bash` tool command is read in. */
+export function bashToolDialect(context: { readonly sandboxed: boolean }): ShellDialect {
+	return context.sandboxed ? 'sh' : hostCommandShell().dialect
+}

package/src/tools/defineTool.ts

@@ -61,6 +61,8 @@ export interface DefineToolOptions<S extends z.ZodType> {
 	 * hand-written definitions can use.
 	 */
 	commandArgument?: string
+	/** The shell the command argument runs in; see {@link ToolDefinition.commandDialect}. */
+	commandDialect?: ToolDefinition['commandDialect']
 	/** The argument holding a filesystem path; see {@link ToolDefinition.pathArgument}. */
 	pathArgument?: string
 	/** The argument asking to leave the sandbox; see {@link ToolDefinition.sandboxEscapeArgument}. */
@@ -68,6 +70,35 @@ export interface DefineToolOptions<S extends z.ZodType> {
 	execute(input: z.infer<S>, context: ToolContext): Promise<ToolResult>
 }
 
+/**
+ * The `isDestructive` functions built from a literal `destructive: true`.
+ *
+ * Such a tool is destructive for EVERY input, so no call of it can ever be
+ * approved without review — and a grant that names it (a skill's
+ * `allowed-tools: Write`) would be a promise the review phase never keeps.
+ * Kept here rather than as a field on the definition so the public
+ * `ToolDefinition` shape does not change; see {@link isAlwaysDestructive}.
+ */
+const ALWAYS_DESTRUCTIVE = new WeakSet<object>()
+
+/**
+ * Whether a tool declares every call destructive, whatever the input.
+ *
+ * Known only for a tool built by {@link defineTool} with `destructive: true`.
+ * A hand-written definition, or one whose flag depends on the input, answers
+ * `false`: its calls are still judged one by one, so nothing is lost but an
+ * early warning.
+ */
+export function isAlwaysDestructive(tool: Pick<ToolDefinition, 'isDestructive'>): boolean {
+	return tool.isDestructive !== undefined && ALWAYS_DESTRUCTIVE.has(tool.isDestructive)
+}
+
+function constantDestructive(value: boolean): () => boolean {
+	const fn = () => value
+	if (value) ALWAYS_DESTRUCTIVE.add(fn)
+	return fn
+}
+
 export function defineTool<S extends z.ZodType>(
 	options: DefineToolOptions<S>,
 ): ToolDefinition<z.infer<S>> {
@@ -84,6 +115,7 @@ export function defineTool<S extends z.ZodType>(
 		...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
 		...(options.maxRetries !== undefined ? { maxRetries: options.maxRetries } : {}),
 		...(options.commandArgument !== undefined ? { commandArgument: options.commandArgument } : {}),
+		...(options.commandDialect !== undefined ? { commandDialect: options.commandDialect } : {}),
 		...(options.pathArgument !== undefined ? { pathArgument: options.pathArgument } : {}),
 		...(options.sandboxEscapeArgument !== undefined
 			? { sandboxEscapeArgument: options.sandboxEscapeArgument }
@@ -102,7 +134,7 @@ export function defineTool<S extends z.ZodType>(
 		isDestructive:
 			typeof options.destructive === 'function'
 				? options.destructive
-				: () => options.destructive as boolean,
+				: constantDestructive(options.destructive as boolean),
 		isConcurrencySafe: () => options.concurrencySafe,
 
 		async execute(input: TInput, context: ToolContext): Promise<ToolResult> {

package/src/types/hitl/index.ts

@@ -40,6 +40,15 @@ export type HITLResumeDecision =
 			 * person said yes to a batch that showed the escape.
 			 */
 			confirmedEscalations?: readonly string[]
+			/**
+			 * Ids of calls approved on the strength of a skill's `allowed-tools`
+			 * grant ({@link ToolCallSummary.skillGrant}), with nobody asked.
+			 *
+			 * The kernel writes each one to the session's audit trail naming the
+			 * skill, and only for a call that actually carried the grant — an id
+			 * listed here for an unmarked call is ignored rather than trusted.
+			 */
+			skillGranted?: readonly string[]
 	  }
 	| {
 			action: 'modify_tools'
@@ -126,6 +135,18 @@ export interface ToolCallSummary {
 	 * approve it on their own. A `deny` rule still refuses it outright.
 	 */
 	escalation?: ToolCallEscalation
+	/**
+	 * Present when a skill loaded earlier in this turn pre-approved this call
+	 * through its `allowed-tools`, and nothing stronger stands in the way.
+	 *
+	 * Marked only on a call the operator's policy left to review (no `deny`,
+	 * no explicit `ask` rule), that is not destructive and that carries no
+	 * {@link escalation}. The review policy decides what the mark is worth:
+	 * `createReviewHandler` approves a batch without asking when every call
+	 * it would have asked about carries one, and still refuses under `plan`
+	 * and `strict`. A host's own handler may ignore it.
+	 */
+	skillGrant?: { readonly skill: string }
 }
 
 /** See {@link ToolCallSummary.escalation}. */

package/src/types/provider/stream.ts

@@ -16,6 +16,16 @@ export interface StreamChunk {
 			id: string
 			name: 'web_search'
 			status: 'running' | 'completed' | 'failed'
+			/**
+			 * What the provider searched for, when it says. Often absent on
+			 * `running` and present on the terminal chunk: a provider may decide
+			 * the query while the call is already under way.
+			 */
+			query?: string
+			/** The page the provider opened or searched within, for a page action rather than a query. */
+			url?: string
+			/** How many sources the provider reported for this call. Absent means unknown, not zero. */
+			results?: number
 		}
 
 		content?: string

package/src/types/tool/index.ts

@@ -77,6 +77,8 @@ export interface SkillRegistryRef {
 						invocation?: 'model' | 'operator' | 'both'
 					}
 					body?: string
+					/** The skill's directory, which `${CLAUDE_SKILL_DIR}` in `allowed-tools` names. */
+					dirPath?: string
 				}
 		  }
 		| undefined
@@ -473,18 +475,56 @@ export interface ToolContext {
 	}
 
 	/**
-	 * Adopt the tool scope a skill declared.
+	 * Formerly: narrow the turn's tools to what a skill's `allowed-tools`
+	 * named. That reading was backwards — the field pre-approves, it never
+	 * restricts — and the kernel no longer supplies this member, so a tool
+	 * that calls it through `?.` does nothing.
 	 *
-	 * Called by the `skill` tool when a loaded skill names `allowed-tools`.
-	 * The scope INTERSECTS what the turn already allows and takes effect from
-	 * the next batch — a skill loaded alongside other calls must not
-	 * retroactively refuse them.
+	 * @deprecated Never supplied by the kernel since `allowed-tools` became a
+	 * pre-approval. Use {@link ToolContext.grantSkillTools}. Removed in the
+	 * next major.
 	 */
 	adoptSkillScope?: (scope: {
 		skill: string
 		allowedTools: readonly string[]
 	}) => void
 
+	/**
+	 * Pre-approve what a loaded skill's `allowed-tools` names, for the rest of
+	 * this turn.
+	 *
+	 * Called by the `skill` tool. It never narrows anything: every tool the
+	 * turn had stays callable, and a call the grant does not cover is reviewed
+	 * exactly as before. A covered call skips the approval prompt, but not an
+	 * operator `deny` or `ask` rule, plan mode, `strict` mode, a destructive
+	 * call or one that reaches outside the turn's roots or sandbox. Each call
+	 * approved this way is written to the session's audit trail naming the
+	 * skill.
+	 *
+	 * Returns what would be granted and what was ignored (an unknown tool
+	 * name, a pattern on a tool without a command line, a tool every call of
+	 * which is destructive), so the tool can tell the model. Nothing is
+	 * recorded until `commit()` is called: the caller commits only once the
+	 * skill's instructions have actually been delivered, so a load that fails
+	 * afterwards leaves no approval behind. Absent outside a turn, where
+	 * there is nothing to grant into.
+	 */
+	grantSkillTools?: (grant: {
+		readonly skill: string
+		/** The parsed entries, as `parseAllowedTools` returns them. */
+		readonly allowedTools: readonly string[]
+		/** The skill's directory, for `${CLAUDE_SKILL_DIR}` / `${NAMZU_SKILL_DIR}`. */
+		readonly skillDirectory?: string
+	}) => {
+		readonly granted: readonly string[]
+		readonly ignored: readonly {
+			readonly entry: string
+			readonly reason: string
+		}[]
+		/** Record the grant in the turn. Idempotent. */
+		readonly commit: () => void
+	}
+
 	/**
 	 * Effective model-visible character cap for this tool result.
 	 *
@@ -677,6 +717,14 @@ export interface ToolResult {
 	workingState?: readonly import('../../compaction/types.js').WorkingStatePin[]
 }
 
+/**
+ * The shell a command line will run in, as the permission rules read it.
+ * `bash` reads it as bash does. `sh` reads it for a shell that may be bash or
+ * a POSIX shell such as `dash`: every construct the two read differently
+ * makes the line opaque, so a line that is not opaque means the same in both.
+ */
+export type ShellDialect = 'bash' | 'sh'
+
 export interface ToolDefinition<TInput = unknown> extends ToolPresentation<TInput> {
 	name: string
 	description: string
@@ -737,6 +785,20 @@ export interface ToolDefinition<TInput = unknown> extends ToolPresentation<TInpu
 	 * chaining — has nothing to decompose and must not claim otherwise.
 	 */
 	commandArgument?: string
+	/**
+	 * The shell {@link commandArgument} runs in, as the dialect the permission
+	 * rules must read it in.
+	 *
+	 * A rule reads a command line before it runs, and the reading is only
+	 * right for the shell that runs it: `$'\x3b'`, `|&` and `&>` mean one
+	 * thing to bash and another to `dash`. `bash` reads the line as bash
+	 * does. `sh`, the default when this is absent, reads it for a shell that
+	 * may be bash or a POSIX shell, and every construct the two read
+	 * differently makes the line opaque, so no allow rule approves it. The
+	 * shipped `bash` tool answers `bash` when it will spawn bash on the host
+	 * and `sh` inside a sandbox, whose guest may not have bash.
+	 */
+	commandDialect?: (context: { readonly sandboxed: boolean }) => ShellDialect
 	/**
 	 * The argument that holds a filesystem path the tool resolves against the
 	 * turn's roots (the working directory and the added directories).