@namzu/sdk 44.3.0 → 45.0.0

package/src/authorization/skill-grant.ts

@@ -0,0 +1,400 @@
+/**
+ * A skill's `allowed-tools`, as what it is everywhere else: a pre-approval.
+ *
+ * The field comes from the Agent Skills format, and the runtime that made it
+ * popular documents it plainly: the listed tools may be used without asking
+ * for the rest of the turn that loaded the skill, and "it does not restrict
+ * which tools are available: every tool remains callable, and your permission
+ * settings still govern tools that are not listed."
+ *
+ * This kernel read it the other way round, as a RESTRICTION. A skill written
+ * for that ecosystem says `allowed-tools: Read Grep` to mean "these two are
+ * fine without a prompt", and a turn that loaded it here lost `bash` on its
+ * next batch and was told to "restrict yourself to" two tools — so the model
+ * stopped doing the work and tried to do everything through whatever the
+ * skill described. The field was never meant to take anything away.
+ *
+ * What it grants, and what it does not:
+ *
+ * - **Grants**: a call that matches an entry skips the approval PROMPT for the
+ *   rest of the turn, on the same footing as a person answering "allow" for
+ *   the turn. The turn ends, the grant ends; loading the skill again in a
+ *   later turn grants again.
+ * - **Never overrides**: an operator `deny` rule, an operator `ask` rule, plan
+ *   mode, `strict` mode, an escalation (a path argument outside the working
+ *   directory, a sandbox escape), or a call the tool itself declares
+ *   destructive. Those are all statements by the operator or the tool; a
+ *   skill is repository content and cannot outrank either. `bash` has no path
+ *   argument, so a pattern entry refuses output redirection itself (see
+ *   `coveringSkill`); a whole-tool `Bash` entry grants what any line does.
+ * - **Ends early**: when the operator sends another message into the running
+ *   turn, the iteration clears the set.
+ * - **Never adds a tool**: an entry names a tool this turn already has, or it
+ *   is ignored and the model is told so. An unknown name widens nothing.
+ *
+ * Granting is equivalent to the operator trusting that skill's commands,
+ * which is why only a skill the host chose to load can grant anything; see
+ * `docs/` for the CLI's folder-trust story.
+ */
+
+import { MAX_CUSTOM_PATTERN_LENGTH } from '../constants/authorization/index.js'
+import type { ToolDefinition } from '../types/tool/index.js'
+import { writesThroughRedirection } from './command-line.js'
+import { evaluateRule } from './rules.js'
+import type { ShellDialect } from './shell-lexer.js'
+
+/**
+ * Split an `allowed-tools` value into entries.
+ *
+ * Accepts every spelling the format uses: space-separated (`Read Grep Bash`),
+ * comma-separated (`Read, Grep`), and — once the frontmatter reader has turned
+ * a YAML list into one line — the items of a list. Separators inside
+ * parentheses belong to the entry, so `Bash(git add *)` stays one entry.
+ *
+ * `undefined` means the skill declared nothing. An empty array means it
+ * declared the field empty. Neither grants anything, and neither restricts
+ * anything, so the distinction survives only for a host that wants to show
+ * what the author wrote.
+ */
+export function parseAllowedTools(declared: string | undefined): readonly string[] | undefined {
+	if (declared === undefined) return undefined
+	const entries: string[] = []
+	let current = ''
+	let depth = 0
+	const flush = () => {
+		const entry = current.trim()
+		if (entry.length > 0) entries.push(entry)
+		current = ''
+	}
+	for (const char of declared) {
+		if (char === '(') depth += 1
+		if (char === ')' && depth > 0) depth -= 1
+		if (depth === 0 && (char === ',' || /\s/.test(char))) {
+			flush()
+			continue
+		}
+		current += char
+	}
+	flush()
+	return entries
+}
+
+/**
+ * The tool names the Agent Skills ecosystem writes, and what they are here.
+ *
+ * Keyed lower-case: names are matched without regard to case, because a skill
+ * author writes `Read` and this kernel's tool is `read`, and a grant lost to
+ * capitalisation is a prompt nobody can explain.
+ */
+export const SKILL_TOOL_NAME_ALIASES: Readonly<Record<string, string>> = Object.freeze({
+	read: 'read',
+	write: 'write',
+	edit: 'edit',
+	multiedit: 'edit',
+	bash: 'bash',
+	grep: 'grep',
+	glob: 'glob',
+	ls: 'ls',
+	webfetch: 'web_fetch',
+	websearch: 'web_search',
+	skill: 'skill',
+	askuserquestion: 'ask_user_question',
+	task: 'create_task',
+	agent: 'create_task',
+	lsp: 'lsp',
+	toolsearch: 'search_tools',
+	// A background shell's output and its termination are one tool here,
+	// `job`, whatever the ecosystem's release called them. Granting `job`
+	// for `BashOutput` does not grant a kill without review: `job` declares
+	// `kill` destructive, and a destructive call is never skill-approved.
+	bashoutput: 'job',
+	taskoutput: 'job',
+	killshell: 'job',
+	killbash: 'job',
+	taskstop: 'job',
+	taskcreate: 'task_create',
+	taskupdate: 'task_update',
+	tasklist: 'task_list',
+})
+
+/**
+ * How a grant compiler learns what a name means in this turn: the registered
+ * tool a name refers to, or `undefined` for one this turn does not have.
+ * `commandArgument` is what lets a `Bash(<pattern>)` entry be matched against
+ * the command line rather than the serialised input.
+ */
+export type SkillGrantToolResolver = (name: string) =>
+	| {
+			readonly name: string
+			readonly commandArgument?: string
+			/**
+			 * Every call of this tool is destructive, whatever its input (the
+			 * shipped `write` and `run_code`). A destructive call is always
+			 * reviewed, so an entry naming such a tool can grant nothing and is
+			 * reported as ignored rather than listed as pre-approved.
+			 */
+			readonly alwaysDestructive?: boolean
+			/**
+			 * The tool is registered but withheld from this turn or step by
+			 * `allowedTools`. The model cannot call it, so an entry naming it is
+			 * reported as ignored rather than listed as pre-approved.
+			 */
+			readonly unavailable?: boolean
+	  }
+	| undefined
+
+/** One compiled entry: a whole tool, or one tool's command line matching a pattern. */
+export interface SkillGrantEntry {
+	/** The registered tool name. */
+	readonly tool: string
+	/** Present for a pattern entry: the argument holding the command line. */
+	readonly argument?: string
+	/** Present for a pattern entry: an anchored regular-expression source. */
+	readonly pattern?: string
+	/** The entry as the author wrote it, for messages. */
+	readonly declared: string
+}
+
+export interface CompiledSkillGrant {
+	readonly entries: readonly SkillGrantEntry[]
+	/** Entries that granted nothing, with the reason, for the model and the log. */
+	readonly ignored: readonly {
+		readonly entry: string
+		readonly reason: string
+	}[]
+}
+
+/** The two placeholders a pattern may use for the skill's own directory. */
+const SKILL_DIR_PLACEHOLDERS = ['${CLAUDE_SKILL_DIR}', '${NAMZU_SKILL_DIR}'] as const
+
+const ENTRY_SHAPE = /^([A-Za-z0-9_.\-]+)(?:\(([\s\S]*)\))?$/
+
+/**
+ * Turn a permission glob into an anchored regular-expression source.
+ *
+ * The one glob dialect for command permissions, shared with the CLI's
+ * `[permissions]` table so that `Bash(git status *)` in a skill and
+ * `bash = { "git status *" = "allow" }` in config mean the same commands:
+ *
+ * - `*` matches any run of characters, `?` exactly one, everything else is
+ *   literal;
+ * - backslashes become forward slashes, so one pattern works on every platform;
+ * - a pattern ending in `<space>*` also matches the bare command, so
+ *   `git status *` covers `git status` as well as `git status -s`, and does
+ *   not cover `git statusx`.
+ */
+export function permissionPatternToRegExpSource(pattern: string): string {
+	const normalized = pattern.replaceAll('\\', '/')
+	const escaped = normalized
+		.replace(/[.+^${}()|[\]\\]/g, '\\$&')
+		.replace(/\*/g, '.*')
+		.replace(/\?/g, '.')
+	const trailingSpaceStar = escaped.endsWith(' .*') ? `${escaped.slice(0, -3)}( .*)?` : escaped
+	return `^${trailingSpaceStar}$`
+}
+
+/**
+ * Compile a skill's parsed `allowed-tools` into grant entries.
+ *
+ * Pure: the resolver supplies everything the turn knows. An entry that cannot
+ * be honoured exactly is ignored and reported, never approximated — the only
+ * safe approximation of a permission is a narrower one, and "ignored" is the
+ * narrowest.
+ */
+export function compileSkillGrant(
+	declared: readonly string[],
+	options: {
+		readonly resolveTool: SkillGrantToolResolver
+		/** The skill's directory, for `${CLAUDE_SKILL_DIR}` / `${NAMZU_SKILL_DIR}`. */
+		readonly skillDirectory?: string
+	},
+): CompiledSkillGrant {
+	const entries: SkillGrantEntry[] = []
+	const ignored: { entry: string; reason: string }[] = []
+
+	for (const entry of declared) {
+		const shape = ENTRY_SHAPE.exec(entry)
+		if (!shape) {
+			ignored.push({ entry, reason: 'not a tool name or `Tool(pattern)`' })
+			continue
+		}
+		const written = shape[1] ?? ''
+		const specifier = shape[2]?.trim()
+		const alias = SKILL_TOOL_NAME_ALIASES[written.toLowerCase()]
+		const tool = options.resolveTool(alias ?? written)
+		if (!tool) {
+			ignored.push({ entry, reason: 'this turn has no tool by that name' })
+			continue
+		}
+		if (tool.unavailable) {
+			ignored.push({
+				entry,
+				reason: `\`${tool.name}\` is not available in this turn, so nothing was granted for it`,
+			})
+			continue
+		}
+		if (tool.alwaysDestructive) {
+			ignored.push({
+				entry,
+				reason: `every \`${tool.name}\` call is destructive and is always reviewed, so nothing was granted for it`,
+			})
+			continue
+		}
+
+		if (specifier === undefined || specifier === '' || specifier.replaceAll('*', '') === '') {
+			entries.push({ tool: tool.name, declared: entry })
+			continue
+		}
+
+		if (tool.commandArgument === undefined) {
+			ignored.push({
+				entry,
+				reason: `a pattern is honoured only for a tool that takes a command line, and \`${tool.name}\` does not; nothing was granted for it`,
+			})
+			continue
+		}
+
+		let pattern = specifier
+		// The legacy prefix spelling `npm run test:*` means `npm run test *`.
+		if (pattern.endsWith(':*')) pattern = `${pattern.slice(0, -2)} *`
+		if (SKILL_DIR_PLACEHOLDERS.some((placeholder) => pattern.includes(placeholder))) {
+			if (!options.skillDirectory) {
+				ignored.push({
+					entry,
+					reason: "the skill's directory is not known in this turn",
+				})
+				continue
+			}
+			for (const placeholder of SKILL_DIR_PLACEHOLDERS) {
+				pattern = pattern.replaceAll(placeholder, options.skillDirectory)
+			}
+		}
+		const source = permissionPatternToRegExpSource(pattern)
+		if (source.length > MAX_CUSTOM_PATTERN_LENGTH) {
+			ignored.push({ entry, reason: 'the pattern is too long to evaluate' })
+			continue
+		}
+		entries.push({
+			tool: tool.name,
+			argument: tool.commandArgument,
+			pattern: source,
+			declared: entry,
+		})
+	}
+
+	return { entries, ignored }
+}
+
+interface HeldGrant {
+	readonly skill: string
+	readonly entry: SkillGrantEntry
+	readonly compiled?: RegExp
+	readonly names: Set<string>
+}
+
+/**
+ * The skill grants in force for one turn.
+ *
+ * Turn-scoped for the reason `ToolGrantSet` is: a grant is a statement about
+ * this turn's work. It is created with the turn and dropped with it, so it
+ * never reaches the next message, and a delegated child — which runs its own
+ * turn — starts with an empty one of its own rather than its parent's.
+ */
+export class SkillGrantSet {
+	private readonly held: HeldGrant[] = []
+
+	/** Record a skill's compiled entries. Loading the same skill twice is harmless. */
+	grant(skill: string, compiled: CompiledSkillGrant): void {
+		for (const entry of compiled.entries) {
+			const duplicate = this.held.some(
+				(held) =>
+					held.skill === skill &&
+					held.entry.tool === entry.tool &&
+					held.entry.argument === entry.argument &&
+					held.entry.pattern === entry.pattern,
+			)
+			if (duplicate) continue
+			this.held.push({
+				skill,
+				entry,
+				...(entry.pattern !== undefined ? { compiled: new RegExp(entry.pattern) } : {}),
+				names: new Set([entry.tool]),
+			})
+		}
+	}
+
+	/**
+	 * The skill whose grant covers this call, or `undefined`.
+	 *
+	 * A pattern entry is matched the way an operator's `allow` pattern is: per
+	 * command, every command in the line must match, and a line the reader
+	 * cannot see through (a substitution, `eval`, a line that does not parse)
+	 * matches nothing. So
+	 * `Bash(git status *)` covers `git status -s` and not
+	 * `git status && git push`.
+	 *
+	 * A pattern entry also never covers a line that redirects output into a
+	 * file (`git status > ~/.bashrc`). The pattern names a command; where its
+	 * output lands is not part of that command, and the shell's redirection
+	 * writes wherever the line says without the tool reporting a path.
+	 * `/dev/null` and descriptor duplication (`2>&1`) are not writes and stay
+	 * covered. A whole-tool entry (`Bash`) grants the tool as it is, which
+	 * includes redirection.
+	 */
+	coveringSkill(
+		call: { readonly name: string; readonly input: unknown },
+		toolDef?: ToolDefinition,
+		options: { readonly commandDialect?: ShellDialect } = {},
+	): string | undefined {
+		// Read the line for the shell that will run it; unknown is `sh`, the
+		// reading that holds for any POSIX shell.
+		const dialect = options.commandDialect ?? 'sh'
+		for (const held of this.held) {
+			if (held.entry.tool !== call.name) continue
+			if (held.entry.pattern === undefined || held.entry.argument === undefined) return held.skill
+			const line =
+				call.input !== null && typeof call.input === 'object'
+					? (call.input as Record<string, unknown>)[held.entry.argument]
+					: undefined
+			if (typeof line !== 'string' || writesThroughRedirection(line, dialect)) continue
+			const decision = evaluateRule(
+				{
+					type: 'argument_pattern',
+					toolNames: [held.entry.tool],
+					argument: held.entry.argument,
+					pattern: held.entry.pattern,
+					decision: 'allow',
+				},
+				call.name,
+				call.input,
+				toolDef,
+				held.compiled,
+				held.names,
+				{ commandDialect: dialect },
+			)
+			if (decision === 'allow') return held.skill
+		}
+		return undefined
+	}
+
+	/**
+	 * Drop every grant. Called when the operator speaks again inside a running
+	 * turn: the grant belonged to the request that loaded the skill, and a new
+	 * message is a new request, even when it reaches the same `query()`.
+	 */
+	clear(): void {
+		this.held.length = 0
+	}
+
+	get size(): number {
+		return this.held.length
+	}
+
+	/** What is granted, by skill, as the authors wrote it. */
+	list(): { readonly skill: string; readonly entry: string }[] {
+		return this.held.map((held) => ({
+			skill: held.skill,
+			entry: held.entry.declared,
+		}))
+	}
+}

package/src/persona/assembler.ts

@@ -67,8 +67,11 @@ export function renderSkillsSection(skills?: Skill[]): string | null {
 			if (s.metadata.license) {
 				lines.push(`<license>${s.metadata.license}</license>`)
 			}
+			// Named for what it does. Rendered as `<allowed_tools>` it read as a
+			// whitelist, and a model that took it that way stopped reaching for
+			// tools the skill did not list — the reverse of the field's meaning.
 			if (s.metadata.allowedTools) {
-				lines.push(`<allowed_tools>${s.metadata.allowedTools}</allowed_tools>`)
+				lines.push(`<pre_approved_tools>${s.metadata.allowedTools}</pre_approved_tools>`)
 			}
 			lines.push('</skill>')
 			return lines.join('\n')
@@ -81,7 +84,7 @@ export function renderSkillsSection(skills?: Skill[]): string | null {
 	// instructions and no listing that would let it reason about them.
 	const loadedSkills = forModel.filter((s) => s.body)
 	const sections = [
-		`## Available Skills\nThe following block is a manifest, not the full skill content. Skill metadata is always visible; SKILL.md bodies are loaded only when the user's task matches the skill description.\n\n<available_skills>\n${available}\n</available_skills>\n\nSkill usage protocol:\n- Plain questions do not require a skill.\n- When a matching skill is already listed under Loaded Skills, apply its loaded instructions.\n- When a matching skill is not loaded and the runtime exposes filesystem or skill-loading tools, read the SKILL.md at its <location> before writing code, creating files, running shell commands for that workflow, or calling mutation tools guided by the skill.\n- Do not claim to have read a SKILL.md until its content is actually present in the prompt or returned by a tool.\n- Tool schemas and runtime permissions remain authoritative; skills provide guidance, not hidden tools.`,
+		`## Available Skills\nThe following block is a manifest, not the full skill content. Skill metadata is always visible; SKILL.md bodies are loaded only when the user's task matches the skill description.\n\n<available_skills>\n${available}\n</available_skills>\n\nSkill usage protocol:\n- Plain questions do not require a skill.\n- When a matching skill is already listed under Loaded Skills, apply its loaded instructions.\n- When a matching skill is not loaded and the runtime exposes filesystem or skill-loading tools, read the SKILL.md at its <location> before writing code, creating files, running shell commands for that workflow, or calling mutation tools guided by the skill.\n- Do not claim to have read a SKILL.md until its content is actually present in the prompt or returned by a tool.\n- Tool schemas and runtime permissions remain authoritative; skills provide guidance, not hidden tools.\n- <pre_approved_tools> lists tools a skill lets run without an approval prompt once it is loaded. It never limits which tools you may use: every tool stays available.`,
 	]
 
 	if (loadedSkills.length > 0) {

package/src/public-runtime.ts

@@ -318,6 +318,15 @@ export { deriveTurnStatus } from './types/session/derive-status.js'
 // wide their yes is, instead of choosing between 'this one call' and
 // 'everything for the session'.
 export { ToolGrantSet, toolGrantKeys } from './runtime/query/tool-grants.js'
+// A skill's `allowed-tools` as a turn-scoped pre-approval: the parser, the
+// compiler a host can run against its own registry, the per-turn set, and
+// the one permission-glob dialect the CLI's `[permissions]` table shares.
+export {
+	SKILL_TOOL_NAME_ALIASES,
+	SkillGrantSet,
+	compileSkillGrant,
+	permissionPatternToRegExpSource,
+} from './authorization/skill-grant.js'
 export type { ToolGrantKeys } from './runtime/query/tool-grants.js'
 // `toWireTurnStatus` comes through `./contracts/session/index.js`.
 // Durable turn state: the snapshot a different process picks a turn up from.

package/src/public-tools.ts

@@ -61,7 +61,8 @@ export { JobTool } from './tools/builtins/job.js'
 // the same reason `job` does: a job with nothing that can block on it is
 // the same unbacked suggestion `job` itself exists to fix.
 export { WaitForJobTool } from './tools/builtins/wait-for-job.js'
-// Loads a skill's instructions, and adopts the tool scope it declares.
+// Loads a skill's instructions, and pre-approves what its `allowed-tools`
+// names for the rest of the turn (never narrowing the tool set).
 // NOT in the default builtin set: a turn with no skills has nothing for it
 // to do, and offering a tool that can only refuse is worse than not
 // offering it. Hosts register it alongside a skills registry.

package/src/public-types.ts

@@ -113,9 +113,15 @@ export type { CacheRates, ModelPricing } from './utils/cost.js'
 export type { VendorRates } from './pricing/index.js'
 export type { PricingSubject } from './manager/session/turn-recorder.js'
 export type {
+	FrontmatterOptions,
 	FrontmatterValue,
 	ParsedFrontmatter,
 } from './utils/frontmatter.js'
+export type {
+	CompiledSkillGrant,
+	SkillGrantEntry,
+	SkillGrantToolResolver,
+} from './authorization/skill-grant.js'
 export type { Logger } from './utils/logger.js'
 export type {
 	LevelFilter,
@@ -255,6 +261,7 @@ export type { AgentBusConfig } from './bus/index.js'
 
 export type { ToolCallContext } from './authorization/index.js'
 export type { PermissionPreset } from './authorization/index.js'
+export type { EvaluateRuleOptions } from './authorization/rules.js'
 
 export type {
 	DiskSessionStoreConfig,

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