@namzu/sdk 7.0.0 → 9.0.0

package/src/types/agent/gateway.ts

@@ -1,5 +1,5 @@
 import type { TaskId } from '../ids/index.js'
-import type { AgentRuntimeContext, BaseAgentResult } from './base.js'
+import type { AgentRuntimeContext, BaseAgentConfig, BaseAgentResult } from './base.js'
 import type { AgentTaskState } from './task.js'
 
 export interface TaskHandle {
@@ -40,7 +40,24 @@ export interface CreateTaskOptions {
 
 	runtimeContext?: AgentRuntimeContext
 
-	configOverrides?: Record<string, unknown>
+	/**
+	 * Config the spawned run should be built with, overriding what the
+	 * agent's own definition supplies — the model it runs on, its iteration
+	 * ceiling, its thinking or effort settings.
+	 *
+	 * **This was accepted and dropped.** `LocalTaskGateway.createTask` built
+	 * its own `configOverrides` object out of `parentSpan` alone and never
+	 * read this field, so a caller pinning a delegated run to a cheaper model
+	 * got the agent's default model and no indication otherwise. It is
+	 * forwarded now, with the dedicated {@link parentSpan} option winning if
+	 * both name a span, since that one is the specific field for the job.
+	 *
+	 * Typed as `Partial<BaseAgentConfig>` rather than
+	 * `Record<string, unknown>`: this lands on `SendMessageOptions`, which is
+	 * already that shape, and the loose type let a misspelled key type-check
+	 * and then do nothing — the same silence this field was already producing.
+	 */
+	configOverrides?: Partial<BaseAgentConfig>
 }
 
 export interface TaskGateway {
@@ -52,6 +69,24 @@ export interface TaskGateway {
 
 	cancelTask(taskId: TaskId): void
 
+	/**
+	 * The task's current state, or `undefined` if this gateway does not know
+	 * about it.
+	 *
+	 * **A task that has just settled should still be findable here.** The
+	 * kernel uses this to recover one specific race: `createTask` resolves a
+	 * microtask before its caller can record whose the task is, so a worker
+	 * that finishes inside that window is announced to a listener that cannot
+	 * yet place it. `CompletionInbox` buffers the announcement AND asks this
+	 * method, and the second is what covers the case the buffer could not
+	 * hold.
+	 *
+	 * This is a request, not a requirement, and the cost of not meeting it is
+	 * yours: a gateway that forgets a task the instant it completes still
+	 * works, but under a burst large enough to overflow the buffer a fast
+	 * worker's result can go unannounced. `LocalTaskGateway` meets it for as
+	 * long as the manager holds the record.
+	 */
 	getTask(taskId: TaskId): TaskHandle | undefined
 
 	listTasks(): TaskHandle[]

package/src/types/agent/supervisor.ts

@@ -10,7 +10,7 @@ import type { ToolRegistryContract } from '../tool/index.js'
 import type { VerificationGateConfig } from '../verification/index.js'
 import type { BaseAgentConfig, BaseAgentResult } from './base.js'
 import type { AgentFactoryOptions } from './factory.js'
-import type { TaskGateway } from './gateway.js'
+import type { SiblingFailurePolicy, TaskGateway } from './gateway.js'
 import type { AgentManagerContract } from './manager.js'
 import type { WorkingMemoryProvider } from './working-memory.js'
 
@@ -72,6 +72,45 @@ export interface SupervisorAgentConfig extends BaseAgentConfig {
 	 */
 	maxDepth?: number
 
+	/**
+	 * How many tools may execute at once in one turn — which, for a
+	 * supervisor, is how wide a fan-out actually runs.
+	 *
+	 * The kernel has honoured this all along and `ReactiveAgent` forwards it.
+	 * It was missing here, so the agent whose entire job is delegation could
+	 * not set the gate that bounds delegation, while the agent that does not
+	 * delegate could. A host wanting a narrower fan-out had to reach past the
+	 * supervisor to `drainQuery`.
+	 *
+	 * Absent leaves the kernel default. Note what it does and does not bound:
+	 * it limits how many delegated children run CONCURRENTLY, not how many a
+	 * turn may launch — a model that emits twenty `create_task` blocks still
+	 * launches twenty, and they queue.
+	 */
+	maxToolConcurrency?: number
+
+	/**
+	 * What a failed child means for the siblings still running. Defaults to
+	 * `'continue'`.
+	 *
+	 * `LocalTaskGateway` has honoured this since it was written, and the
+	 * cancellation machinery behind `'cancel-siblings'` is complete — but the
+	 * policy was a constructor argument on a gateway the supervisor builds
+	 * itself, and the supervisor passed nothing. So every host in existence
+	 * ran `'continue'`, and the only way to reach the other value was to
+	 * construct the gateway by hand and hand it in. A policy nobody can select
+	 * is not a policy.
+	 *
+	 * `'continue'` stays the default deliberately: partial results are usually
+	 * worth having, and tearing down healthy siblings on any failure lets one
+	 * flaky child waste four good ones. `'cancel-siblings'` is for a fan-out
+	 * whose parts only mean something together — if one leg of a comparison
+	 * dies, the others are spending budget on an answer nobody can use.
+	 *
+	 * Ignored when the host supplies its own `gateway`, which owns its policy.
+	 */
+	siblingFailurePolicy?: SiblingFailurePolicy
+
 	taskRouter?: TaskRouterConfig
 
 	factoryOptions?: AgentFactoryOptions

package/src/types/plan/index.ts

@@ -18,7 +18,36 @@ export interface PlanStep {
 	id: string
 	description: string
 	toolName?: string
+
+	/**
+	 * Which agent this step is to be delegated to, when it is delegated at all.
+	 *
+	 * `approve_plan` invites the model to name an agent per step, and that
+	 * answer was reduced to a boolean: the step got `toolName: 'create_task'`
+	 * if any agent was named and nothing if not. So the human approving the
+	 * plan was shown THAT a step delegates and never TO WHOM — while the model
+	 * had said, and the approval is the one moment where the difference can
+	 * still be acted on. Approving "delegate this" is not approving "delegate
+	 * this to the agent with shell access".
+	 *
+	 * Typed rather than folded into {@link estimatedInput}, which is `unknown`:
+	 * an approval gate's whole job is being readable, and a field a host has to
+	 * cast before it can render is one a host renders wrong or not at all.
+	 *
+	 * Absent means the step is the orchestrator's own work, which is what
+	 * omitting `agent_id` in `approve_plan` says.
+	 */
+	agentId?: string
+
+	/**
+	 * **No producer and no reader.** Nothing in the SDK writes this and
+	 * nothing reads it; it is declared here and that is all. Noted rather
+	 * than removed because it is on the published typings — see
+	 * {@link agentId}, which is the field the plan approval path actually
+	 * needed and did not have.
+	 */
 	estimatedInput?: unknown
+
 	dependsOn: string[]
 	status: 'pending' | 'running' | 'completed' | 'skipped' | 'failed'
 	error?: string

package/src/types/provider/interface.ts

@@ -49,4 +49,43 @@ export interface LLMProvider {
 	 * so the doctor doesn't mark them as failing — see ses_007 Q6.4.
 	 */
 	doctorCheck?(): Promise<DoctorCheckResult>
+
+	/**
+	 * Which {@link ChatCompletionParams.effort} levels this model accepts,
+	 * under the thinking configuration you intend to send with it.
+	 *
+	 * Asked rather than assumed because effort is **refused, not clamped**:
+	 * a level a model does not have makes the vendor reject the request, so a
+	 * caller offering a choice it cannot honour produces a run that fails at
+	 * the start rather than a quieter one. Building that choice needs the
+	 * answer BEFORE the request exists.
+	 *
+	 * There are three states and they mean different things:
+	 *
+	 * - **method absent** — this driver has no effort concept at all. Setting
+	 *   `effort` on a run using it is refused, not ignored, so a caller should
+	 *   offer no control rather than a disabled one.
+	 * - **empty array** — the driver implements effort and THIS model has no
+	 *   levels. A real answer, not a missing one.
+	 * - **non-empty** — offer exactly these, and nothing else.
+	 *
+	 * `thinking` is a parameter rather than the caller reading two sibling
+	 * arrays, and that is the whole reason this is a function. At least one
+	 * model family accepts a narrower set of levels while thinking is
+	 * disabled than while it is on, so an API returning both sets invites a
+	 * caller to render a picker from one and then send the other — a
+	 * combination the vendor rejects, on exactly one family, discovered in
+	 * production. Passing the configuration you are actually going to send
+	 * makes that mistake unspellable: there is one answer and it is the one
+	 * for your request.
+	 *
+	 * The levels are not stable across models and have moved twice already,
+	 * so a caller must not copy the answer into its own table. A copy goes
+	 * stale on the next model release and goes stale SILENTLY — surfacing as
+	 * a vendor rejection rather than a failing build.
+	 */
+	effortLevelsFor?(
+		model: string,
+		thinking?: import('./chat.js').ThinkingConfig,
+	): readonly import('./chat.js').ReasoningEffort[]
 }

package/src/types/run/entity.ts

@@ -59,6 +59,23 @@ export interface Run {
 	 */
 	structuredOutput?: unknown
 
+	/**
+	 * Delegated tasks that were still running when this run ended.
+	 *
+	 * A run can settle while a worker it launched is still going — the model
+	 * answered, a terminal tool decided the result, a `stopWhen` fired. The
+	 * worker is NOT cancelled: giving up on a wait is a statement about the
+	 * waiter, not about the work, and killing a child that may be mid-write
+	 * because its parent finished early is a policy only the host can judge.
+	 * A host that wants them stopped has `cancel_task` and the run controller.
+	 *
+	 * What the kernel owes instead is not pretending the results arrived.
+	 * These ids are the honest form of that: the run says which work it walked
+	 * away from, so a host can reconcile, cancel, or wait on them itself.
+	 * Absent when a run ended with nothing outstanding.
+	 */
+	abandonedTaskIds?: readonly string[]
+
 	parentRunId?: RunId
 
 	depth?: number

package/src/types/run/events.ts

@@ -85,6 +85,48 @@ type CoreRunEvent =
 			 */
 			reachedResetThreshold?: boolean
 	  }
+	/**
+	 * A compaction pass ran and shed nothing, so the history is unchanged.
+	 *
+	 * A shed that did not happen is exactly as consequential as one that did,
+	 * and until this existed only one of them was on the wire. The three
+	 * decline paths all reached a log line — and a host that silences its
+	 * logger, which every command-line entry point does, made a failed
+	 * compaction invisible to the user, to the host AND to the model. The run
+	 * then continued at full context toward a provider rejection several turns
+	 * later that named none of this.
+	 *
+	 * The history is guaranteed untouched on every one of these: the reducer's
+	 * result is installed whole or not at all, so there is no partial state to
+	 * reason about. That is the property that makes reporting sufficient and a
+	 * repair unnecessary.
+	 */
+	| {
+			type: 'compaction_failed'
+			runId: RunId
+			iteration: number
+			/**
+			 * Which decline path was taken. These want different responses, so
+			 * a single "it failed" would put the reader back where the silence
+			 * did:
+			 *
+			 * - `reducer_threw` — the reducer raised. Usually a bug or a failed
+			 *   model call inside a summarising reducer; the next pass may work.
+			 * - `shed_nothing` — it returned no fewer messages than it was
+			 *   given. The history is already at its floor, or the reducer's
+			 *   own threshold disagrees with the trigger's, and every later
+			 *   pass will decline identically.
+			 * - `split_tool_pair` — its result separated a `tool_use` from its
+			 *   `tool_result`, so it was refused wholesale rather than sent to
+			 *   a provider that rejects the pairing. A reducer bug, and one
+			 *   `findSafeTrimIndex` exists to prevent.
+			 */
+			cause: 'reducer_threw' | 'shed_nothing' | 'split_tool_pair'
+			/** Unchanged, and stated so a reader need not infer it. */
+			messages: number
+			/** Present only for `reducer_threw`. */
+			error?: string
+	  }
 	| {
 			type: 'tool_executing'
 			runId: RunId
@@ -321,6 +363,39 @@ type CoreRunEvent =
 			runId: RunId
 			usage: TokenUsage
 			cost: CostInfo
+			/**
+			 * How large the CONTEXT is right now, and how large it may get.
+			 *
+			 * These are a different quantity from `usage` beside them and the
+			 * distinction is the whole reason they are named this explicitly.
+			 * `usage` is CUMULATIVE SPEND over the run: prompt plus completion
+			 * tokens summed across every turn, monotonically increasing, and
+			 * untouched by compaction. `contextTokens` is the size of the
+			 * conversation being sent right now, which falls when a compaction
+			 * sheds.
+			 *
+			 * Dividing the first by a context window is a category error, and
+			 * it is one this estate shipped: a host did exactly that, so its
+			 * indicator climbed toward full on any long run no matter how much
+			 * room the conversation actually had — most wrong precisely when
+			 * someone needed it most. The numbers are here so nobody has to
+			 * reach for the wrong one, and named so reaching for it is a
+			 * visible mistake rather than a plausible guess.
+			 *
+			 * `contextMeasuredBy` says whether the provider counted the prompt
+			 * or we estimated it, and `windowSource` where the ceiling came
+			 * from. A fraction of two numbers is only as honest as the weaker
+			 * of them, and a surface rendering these owes a reader the same
+			 * distinction rather than presenting an estimate as a measurement.
+			 *
+			 * Absent when the run has no compaction configuration, because
+			 * nothing then resolves a window and inventing one would be the
+			 * guess this exists to replace.
+			 */
+			contextTokens?: number
+			contextMeasuredBy?: 'provider' | 'estimate'
+			contextWindowTokens?: number
+			windowSource?: 'config' | 'model-table' | 'default'
 	  }
 	| {
 			type: 'activity_created'
@@ -386,6 +461,21 @@ type CoreRunEvent =
 			taskId: TaskId
 			subject: string
 			status: TaskStatus
+			/**
+			 * What this unit waits on, and who claims it.
+			 *
+			 * The store maintains a full dependency graph — `blocks` and
+			 * `blockedBy` are mirrored on both ends, written under a lock, and
+			 * deadlock-avoided — and none of it reached the wire. So a host
+			 * could show a flat list of units and nothing about their order,
+			 * while the model was already maintaining the order.
+			 *
+			 * Absent rather than empty when the unit depends on nothing, so a
+			 * reader can tell "no dependencies" from an emitter that predates
+			 * these fields.
+			 */
+			blockedBy?: readonly TaskId[]
+			owner?: string
 	  }
 	| {
 			type: 'task_updated'
@@ -394,6 +484,8 @@ type CoreRunEvent =
 			subject: string
 			status: TaskStatus
 			owner?: string
+			/** See `task_created`. Carried on updates because an edge can be added later. */
+			blockedBy?: readonly TaskId[]
 	  }
 	| {
 			type: 'plugin_hook_executing'

package/src/types/run/prepare-step.ts

@@ -44,8 +44,23 @@ export interface PrepareStepResult {
 	/**
 	 * Restrict which tools the model may call this step, by name. Names
 	 * that are not registered are dropped with a warning rather than
-	 * failing the run — a phase list that outlives a tool rename should
-	 * narrow the surface, not kill the agent mid-run.
+	 * failing the run.
+	 *
+	 * **Dropping every name leaves the step able to call nothing**, and that
+	 * is deliberate rather than an accident of the filter. This list means
+	 * "only these": if a rename outlives a phase list, the only set
+	 * satisfying "only the tools that no longer exist" is the empty one, and
+	 * widening back to the run's list would grant precisely what the caller
+	 * did not ask for. The step is constrained, not crashed — the model
+	 * answers from what it has and the run continues.
+	 *
+	 * This changed meaning when the list started bounding what may RUN
+	 * rather than only what the model is shown. Before, an aged-out list hid
+	 * every tool from the model while leaving all of them callable, which
+	 * was neither reading.
+	 *
+	 * The warning is the part to watch: it goes to the logger, and a host
+	 * that silences its logger sees a phase quietly stop doing anything.
 	 *
 	 * **This costs a prompt-cache prefix.** Tools render at position 0, so
 	 * changing the set between steps invalidates the cached prefix for that

package/src/types/task/index.ts

@@ -1,9 +1,27 @@
 import type { RunId, TaskId, TenantId } from '../ids/index.js'
 
-export type TaskStatus = 'pending' | 'in_progress' | 'completed'
-
+/**
+ * `failed` exists because a unit that did not succeed had nowhere to say so.
+ *
+ * Delegation wrote a failed worker's task as `completed` with the failure
+ * encoded as prose in `description` — so a reader scanning statuses saw work
+ * that had been done, and only a reader of every description saw otherwise. A
+ * status nobody can set is a status nobody can act on: a dependent unit cannot
+ * decide whether to wait or give up, and a plan cannot report that it did not
+ * finish.
+ */
+export type TaskStatus = 'pending' | 'in_progress' | 'completed' | 'failed'
+
+/**
+ * Terminal means "will not change on its own", not "succeeded".
+ *
+ * `failed` is terminal for the same reason `completed` is: nothing downstream
+ * should wait on it. That matters most to the blocker check in the task
+ * listing — a dependent unit blocked on something that failed would otherwise
+ * wait forever for a status that will never arrive.
+ */
 export function isTerminalTaskStatus(status: TaskStatus): boolean {
-	return status === 'completed'
+	return status === 'completed' || status === 'failed'
 }
 
 export function assertTaskStatus(status: TaskStatus): void {
@@ -11,6 +29,7 @@ export function assertTaskStatus(status: TaskStatus): void {
 		case 'pending':
 		case 'in_progress':
 		case 'completed':
+		case 'failed':
 			return
 		default: {
 			const _exhaustive: never = status

package/src/types/verification/index.ts

@@ -16,11 +16,62 @@ export type VerificationRule =
 	| { type: 'allow_by_name'; toolNames: string[] }
 	| { type: 'deny_by_name'; toolNames: string[] }
 	| {
+			/**
+			 * Match a regular expression against the tool's NAME, the
+			 * serialised arguments, or both concatenated.
+			 *
+			 * Read `target: 'args'` carefully before writing one: it tests
+			 * `JSON.stringify(toolInput)`, so the subject is the JSON TEXT of
+			 * the whole argument object — `{"command":"git push origin main"}`
+			 * — and not any single argument. The name suggests otherwise, and
+			 * that is what makes it a trap: an anchored pattern like
+			 * `^git push.*$` is a natural thing to write and can never match,
+			 * so the rule silently decides nothing. `'both'` PREFIXES the tool
+			 * name to that text rather than requiring it, so it is not a scope
+			 * either — a rule written with `bash` in mind still sees every
+			 * other tool's arguments.
+			 *
+			 * When you mean "this tool, this argument", use
+			 * {@link VerificationRule} `argument_pattern` instead. This one
+			 * stays for the case it is actually good at: matching anywhere in
+			 * the serialised input without caring where.
+			 */
 			type: 'custom_pattern'
 			pattern: string
 			target: 'name' | 'args' | 'both'
 			decision: 'allow' | 'deny'
 	  }
+	| {
+			/**
+			 * Match a regular expression against ONE named argument of ONE
+			 * named set of tools.
+			 *
+			 * This exists because `custom_pattern` could express neither half.
+			 * It carries no tool scope, so a rule an operator wrote about
+			 * `bash` decided `edit` calls too; and its argument target tests
+			 * the serialised object, so pinning the tool cost the ability to
+			 * anchor and anchoring cost the tool scope. Every pattern rule was
+			 * therefore one of those two wrong things.
+			 *
+			 * The subject here is the argument's own VALUE, so `^git push`
+			 * means what it looks like it means.
+			 *
+			 * A rule whose tool is not called, or whose argument is absent,
+			 * decides nothing — the rule's precondition simply is not met. So
+			 * does one whose argument holds an object or an array: a pattern
+			 * cannot say anything true about a structured value, and pretending
+			 * otherwise by matching its serialisation would reintroduce exactly
+			 * the confusion this rule was added to remove. If you need to
+			 * refuse a tool over the SHAPE of its input rather than a string in
+			 * it, deny it by name.
+			 */
+			type: 'argument_pattern'
+			toolNames: string[]
+			/** The argument key, at the top level of the tool's input. */
+			argument: string
+			pattern: string
+			decision: 'allow' | 'deny'
+	  }
 	| { type: 'allow_by_tier'; tiers: string[] }
 
 const AllowReadOnlySchema = z.object({ type: z.literal('allow_read_only') })
@@ -43,6 +94,15 @@ const CustomPatternSchema = z.object({
 	target: z.enum(['name', 'args', 'both']),
 	decision: z.enum(['allow', 'deny']),
 })
+const ArgumentPatternSchema = z.object({
+	type: z.literal('argument_pattern'),
+	toolNames: z.array(z.string()).min(1),
+	// A rule that names no argument would silently apply to none, which is the
+	// fail-open shape this rule type exists to remove.
+	argument: z.string().min(1),
+	pattern: z.string().max(MAX_CUSTOM_PATTERN_LENGTH),
+	decision: z.enum(['allow', 'deny']),
+})
 const AllowByTierSchema = z.object({
 	type: z.literal('allow_by_tier'),
 	tiers: z.array(z.string()),
@@ -55,6 +115,7 @@ export const VerificationRuleSchema = z.discriminatedUnion('type', [
 	AllowByNameSchema,
 	DenyByNameSchema,
 	CustomPatternSchema,
+	ArgumentPatternSchema,
 	AllowByTierSchema,
 ])
 

package/src/verification/__tests__/argument-pattern.test.ts

@@ -0,0 +1,158 @@
+import { describe, expect, it } from 'vitest'
+
+import type { ToolDefinition } from '../../types/tool/index.js'
+import type { VerificationGateConfig, VerificationRule } from '../../types/verification/index.js'
+import { getRootLogger } from '../../utils/logger.js'
+import { VerificationGate } from '../gate.js'
+
+/**
+ * Every pattern rule an operator could write was one of two wrong things.
+ *
+ * `custom_pattern` carries no tool scope, so a rule written about `bash`
+ * decided `edit` calls as well. And `target: 'args'` tests
+ * `JSON.stringify(toolInput)`, so the subject is the JSON TEXT of the whole
+ * argument object — meaning the natural, anchored thing to write
+ * (`^git push.*$`) can never match, and the rule silently decides nothing.
+ * Pinning the tool cost the anchor; anchoring cost the tool scope.
+ */
+
+function gate(rules: VerificationGateConfig['rules']): VerificationGate {
+	return new VerificationGate(
+		{
+			enabled: true,
+			rules,
+			allowReadOnlyTools: false,
+			denyDangerousPatterns: false,
+			logDecisions: false,
+		} as VerificationGateConfig,
+		getRootLogger(),
+	)
+}
+
+/** Only the fields the gate reads. */
+function toolDef(name: string): ToolDefinition {
+	return { name, isReadOnly: () => false } as unknown as ToolDefinition
+}
+
+const PUSH_RULE: VerificationRule = {
+	type: 'argument_pattern',
+	toolNames: ['bash'],
+	argument: 'command',
+	pattern: '^git push',
+	decision: 'deny',
+}
+
+function evaluate(
+	rules: VerificationGateConfig['rules'],
+	toolName: string,
+	toolInput: unknown,
+): ReturnType<VerificationGate['evaluate']> {
+	return gate(rules).evaluate({ toolName, toolInput, toolDef: toolDef(toolName) })
+}
+
+describe('a rule can name one tool and one argument at once', () => {
+	it('denies the call it was written about', () => {
+		const result = evaluate([PUSH_RULE], 'bash', { command: 'git push origin main' })
+		expect(result.decision).toBe('deny')
+	})
+
+	it('anchors against the value, which is what the old rule could not do', () => {
+		// The whole defect in one assertion: this same pattern under
+		// `custom_pattern` with `target: 'args'` is tested against
+		// `{"command":"git push origin main"}`, where `^git push` cannot match
+		// because the string does not start there.
+		const viaOldRule = evaluate(
+			[{ type: 'custom_pattern', pattern: '^git push', target: 'args', decision: 'deny' }],
+			'bash',
+			{ command: 'git push origin main' },
+		)
+		expect(viaOldRule.decision, 'the old rule silently decided nothing').not.toBe('deny')
+
+		expect(evaluate([PUSH_RULE], 'bash', { command: 'git push origin main' }).decision).toBe('deny')
+	})
+
+	it('leaves a different tool alone', () => {
+		// The other half: a rule about `bash` used to decide `edit` too,
+		// because the pattern was matched against a serialisation that has no
+		// idea which tool produced it.
+		const result = evaluate([PUSH_RULE], 'edit', { command: 'git push origin main' })
+		expect(result.decision).not.toBe('deny')
+	})
+
+	it('leaves a different argument alone', () => {
+		const result = evaluate([PUSH_RULE], 'bash', { description: 'git push origin main' })
+		expect(result.decision).not.toBe('deny')
+	})
+
+	it('says which argument decided, so a model knows whether to reword', () => {
+		const result = evaluate([PUSH_RULE], 'bash', { command: 'git push origin main' })
+
+		expect(result.reason).toContain('command')
+		expect(result.reason).toContain('^git push')
+		expect(result.reason).toContain('bash')
+	})
+})
+
+describe('what it deliberately does not decide', () => {
+	it('decides nothing when the argument is absent', () => {
+		const result = evaluate([PUSH_RULE], 'bash', {})
+		expect(result.decision).not.toBe('deny')
+	})
+
+	it('decides nothing about a structured argument', () => {
+		// No string a pattern could match says anything true about an object,
+		// and serialising it to try would put this rule back where
+		// `custom_pattern` already is. An operator who needs to refuse a tool
+		// over the SHAPE of its input wants deny_by_name.
+		const rule: VerificationRule = { ...PUSH_RULE, argument: 'env', pattern: 'PROD' }
+		const result = evaluate([rule], 'bash', { env: { NODE_ENV: 'PROD' } })
+
+		expect(result.decision).not.toBe('deny')
+	})
+
+	it('reads a number or a boolean rather than skipping it', () => {
+		// These render unambiguously, so skipping them would be a fail-open
+		// with no upside: a rule about a numeric argument is a rule someone
+		// can reasonably write.
+		const rule: VerificationRule = {
+			type: 'argument_pattern',
+			toolNames: ['sleep'],
+			argument: 'seconds',
+			pattern: '^[0-9]{4,}$',
+			decision: 'deny',
+		}
+
+		expect(evaluate([rule], 'sleep', { seconds: 86400 }).decision).toBe('deny')
+		expect(evaluate([rule], 'sleep', { seconds: 5 }).decision).not.toBe('deny')
+	})
+})
+
+describe('a rule that cannot be compiled decides nothing at all', () => {
+	it('does not widen into a rule about the whole tool', () => {
+		// The failure this forbids: a typo'd regex turning "deny bash when its
+		// command matches X" into "deny bash" — a far larger authorization than
+		// anybody wrote, granted by a mistake nobody would notice.
+		//
+		// What actually secures it is the missing-pattern check at the top of
+		// `evaluateRule`, which returns before the tool name is consulted. The
+		// gate's construction order (compile first, only then record the names)
+		// is defence in depth and NOT the mechanism: reversing those two lines
+		// fails nothing, which was measured rather than assumed. So this test
+		// pins the OUTCOME and the comment in the gate says which line to keep.
+		const broken: VerificationRule = { ...PUSH_RULE, pattern: '([unclosed' }
+		const result = evaluate([broken], 'bash', { command: 'ls' })
+
+		expect(result.decision).not.toBe('deny')
+	})
+
+	it('is secured by the pattern check, not by the construction order', () => {
+		// The honest version of the mutation: remove the check that actually
+		// holds and this fails. A rule whose pattern never compiled has no
+		// pattern to test, so it must decide nothing even for a tool it names.
+		const broken: VerificationRule = { ...PUSH_RULE, pattern: '([unclosed' }
+
+		expect(evaluate([broken], 'bash', { command: 'git push origin main' }).decision).not.toBe(
+			'deny',
+		)
+	})
+})