@namzu/sdk 6.2.0 → 8.0.0

package/dist/types/verification/index.d.ts

@@ -19,10 +19,60 @@ export type VerificationRule = {
     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[];
@@ -81,6 +131,24 @@ export declare const VerificationRuleSchema: z.ZodDiscriminatedUnion<"type", [z.
     target: "name" | "args" | "both";
     pattern: string;
     decision: "deny" | "allow";
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"argument_pattern">;
+    toolNames: z.ZodArray<z.ZodString, "many">;
+    argument: z.ZodString;
+    pattern: z.ZodString;
+    decision: z.ZodEnum<["allow", "deny"]>;
+}, "strip", z.ZodTypeAny, {
+    type: "argument_pattern";
+    pattern: string;
+    toolNames: string[];
+    decision: "deny" | "allow";
+    argument: string;
+}, {
+    type: "argument_pattern";
+    pattern: string;
+    toolNames: string[];
+    decision: "deny" | "allow";
+    argument: string;
 }>, z.ZodObject<{
     type: z.ZodLiteral<"allow_by_tier">;
     tiers: z.ZodArray<z.ZodString, "many">;
@@ -147,6 +215,24 @@ export declare const VerificationGateConfigSchema: z.ZodObject<{
         target: "name" | "args" | "both";
         pattern: string;
         decision: "deny" | "allow";
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"argument_pattern">;
+        toolNames: z.ZodArray<z.ZodString, "many">;
+        argument: z.ZodString;
+        pattern: z.ZodString;
+        decision: z.ZodEnum<["allow", "deny"]>;
+    }, "strip", z.ZodTypeAny, {
+        type: "argument_pattern";
+        pattern: string;
+        toolNames: string[];
+        decision: "deny" | "allow";
+        argument: string;
+    }, {
+        type: "argument_pattern";
+        pattern: string;
+        toolNames: string[];
+        decision: "deny" | "allow";
+        argument: string;
     }>, z.ZodObject<{
         type: z.ZodLiteral<"allow_by_tier">;
         tiers: z.ZodArray<z.ZodString, "many">;
@@ -180,6 +266,12 @@ export declare const VerificationGateConfigSchema: z.ZodObject<{
         target: "name" | "args" | "both";
         pattern: string;
         decision: "deny" | "allow";
+    } | {
+        type: "argument_pattern";
+        pattern: string;
+        toolNames: string[];
+        decision: "deny" | "allow";
+        argument: string;
     } | {
         type: "allow_by_tier";
         tiers: string[];
@@ -207,6 +299,12 @@ export declare const VerificationGateConfigSchema: z.ZodObject<{
         target: "name" | "args" | "both";
         pattern: string;
         decision: "deny" | "allow";
+    } | {
+        type: "argument_pattern";
+        pattern: string;
+        toolNames: string[];
+        decision: "deny" | "allow";
+        argument: string;
     } | {
         type: "allow_by_tier";
         tiers: string[];

package/dist/types/verification/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/types/verification/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAGvB,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,MAAM,GAAG,QAAQ,CAAA;AAEtD,MAAM,WAAW,oBAAoB;IACpC,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAA;IAC/B,QAAQ,CAAC,WAAW,EAAE,gBAAgB,GAAG,IAAI,CAAA;IAC7C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACvB;AAED,MAAM,MAAM,gBAAgB,GACzB;IAAE,IAAI,EAAE,iBAAiB,CAAA;CAAE,GAC3B;IAAE,IAAI,EAAE,yBAAyB,CAAA;CAAE,GACnC;IAAE,IAAI,EAAE,mBAAmB,CAAC;IAAC,UAAU,EAAE,MAAM,EAAE,CAAA;CAAE,GACnD;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,SAAS,EAAE,MAAM,EAAE,CAAA;CAAE,GAC9C;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,SAAS,EAAE,MAAM,EAAE,CAAA;CAAE,GAC7C;IACA,IAAI,EAAE,gBAAgB,CAAA;IACtB,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAA;IAChC,QAAQ,EAAE,OAAO,GAAG,MAAM,CAAA;CACzB,GACD;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,CAAA;AA2B7C,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAQjC,CAAA;AAEF,eAAO,MAAM,4BAA4B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAMvC,CAAA;AAEF,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/types/verification/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAGvB,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,MAAM,GAAG,QAAQ,CAAA;AAEtD,MAAM,WAAW,oBAAoB;IACpC,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAA;IAC/B,QAAQ,CAAC,WAAW,EAAE,gBAAgB,GAAG,IAAI,CAAA;IAC7C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACvB;AAED,MAAM,MAAM,gBAAgB,GACzB;IAAE,IAAI,EAAE,iBAAiB,CAAA;CAAE,GAC3B;IAAE,IAAI,EAAE,yBAAyB,CAAA;CAAE,GACnC;IAAE,IAAI,EAAE,mBAAmB,CAAC;IAAC,UAAU,EAAE,MAAM,EAAE,CAAA;CAAE,GACnD;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,SAAS,EAAE,MAAM,EAAE,CAAA;CAAE,GAC9C;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,SAAS,EAAE,MAAM,EAAE,CAAA;CAAE,GAC7C;IACA;;;;;;;;;;;;;;;;;;;OAmBG;IACH,IAAI,EAAE,gBAAgB,CAAA;IACtB,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAA;IAChC,QAAQ,EAAE,OAAO,GAAG,MAAM,CAAA;CACzB,GACD;IACA;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,IAAI,EAAE,kBAAkB,CAAA;IACxB,SAAS,EAAE,MAAM,EAAE,CAAA;IACnB,8DAA8D;IAC9D,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,OAAO,GAAG,MAAM,CAAA;CACzB,GACD;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,CAAA;AAoC7C,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IASjC,CAAA;AAEF,eAAO,MAAM,4BAA4B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAMvC,CAAA;AAEF,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAA"}

package/dist/types/verification/index.js

@@ -20,6 +20,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()),
@@ -31,6 +40,7 @@ export const VerificationRuleSchema = z.discriminatedUnion('type', [
     AllowByNameSchema,
     DenyByNameSchema,
     CustomPatternSchema,
+    ArgumentPatternSchema,
     AllowByTierSchema,
 ]);
 export const VerificationGateConfigSchema = z.object({

package/dist/types/verification/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/types/verification/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,EAAE,yBAAyB,EAAE,MAAM,uCAAuC,CAAA;AAwBjF,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,iBAAiB,CAAC,EAAE,CAAC,CAAA;AAC5E,MAAM,2BAA2B,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,yBAAyB,CAAC,EAAE,CAAC,CAAA;AAC5F,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IACtC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,mBAAmB,CAAC;IACpC,UAAU,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;CAC/B,CAAC,CAAA;AACF,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,eAAe,CAAC;IAChC,SAAS,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;CAC9B,CAAC,CAAA;AACF,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC;IACjC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,cAAc,CAAC;IAC/B,SAAS,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;CAC9B,CAAC,CAAA;AACF,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC;IACpC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,gBAAgB,CAAC;IACjC,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,yBAAyB,CAAC;IAClD,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,QAAQ,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;CACnC,CAAC,CAAA;AACF,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,eAAe,CAAC;IAChC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;CAC1B,CAAC,CAAA;AAEF,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC,kBAAkB,CAAC,MAAM,EAAE;IAClE,mBAAmB;IACnB,2BAA2B;IAC3B,qBAAqB;IACrB,iBAAiB;IACjB,gBAAgB;IAChB,mBAAmB;IACnB,iBAAiB;CACjB,CAAC,CAAA;AAEF,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAAC,CAAC,MAAM,CAAC;IACpD,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;IACnC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,sBAAsB,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;IAClD,kBAAkB,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;IAC9C,qBAAqB,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;IACjD,YAAY,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC;CACvC,CAAC,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/types/verification/index.ts"],"names":[],"mappings":"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"}

package/dist/utils/__tests__/abort-reason.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=abort-reason.test.d.ts.map

package/dist/utils/__tests__/abort-reason.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"abort-reason.test.d.ts","sourceRoot":"","sources":["../../../src/utils/__tests__/abort-reason.test.ts"],"names":[],"mappings":""}

package/dist/utils/__tests__/abort-reason.test.js

@@ -0,0 +1,48 @@
+import { describe, expect, it } from 'vitest';
+import { abortReasonText } from '../abort.js';
+/**
+ * A cancellation and a deadline arrive by the same mechanism and mean opposite
+ * things to whoever reads the result. The distinction only survives if the
+ * words a caller attached travel with the abort — and only if the words the
+ * platform invents on a caller's behalf do NOT, because a fabricated
+ * explanation is worse than an honest silence.
+ */
+describe('a stop carries the words its caller gave it', () => {
+    it('reports a reason someone wrote', () => {
+        expect(abortReasonText(new Error('deployment window closed'))).toBe('deployment window closed');
+    });
+    it('reports a named deadline, which is the case this exists for', () => {
+        const reason = new Error('run budget of 30000ms exhausted');
+        expect(abortReasonText(reason)).toBe('run budget of 30000ms exhausted');
+    });
+});
+describe('a stop with nothing to say stays silent', () => {
+    it('says nothing for a bare abort()', () => {
+        // `abort()` with no argument fills `reason` with a DOMException named
+        // AbortError. Nobody wrote that word; it is the platform's way of
+        // saying the caller gave no reason, and rendering it would turn "we
+        // do not know" into what looks like an answer.
+        const controller = new AbortController();
+        controller.abort();
+        expect(controller.signal.reason).toBeInstanceOf(Error);
+        expect(controller.signal.reason.name).toBe('AbortError');
+        expect(abortReasonText(controller.signal.reason)).toBeUndefined();
+    });
+    it('says nothing for a platform timeout', () => {
+        const timeout = new Error('The operation was aborted due to timeout');
+        timeout.name = 'TimeoutError';
+        expect(abortReasonText(timeout)).toBeUndefined();
+    });
+    it('says nothing for a non-Error reason', () => {
+        // The agent manager aborts a child with the bare string 'canceled'.
+        // Rendering it produces "was cancelled: canceled" — noise wearing the
+        // shape of information.
+        expect(abortReasonText('canceled')).toBeUndefined();
+        expect(abortReasonText(undefined)).toBeUndefined();
+        expect(abortReasonText({ message: 'not an Error' })).toBeUndefined();
+    });
+    it('says nothing for an Error whose message is empty', () => {
+        expect(abortReasonText(new Error('   '))).toBeUndefined();
+    });
+});
+//# sourceMappingURL=abort-reason.test.js.map

package/dist/utils/__tests__/abort-reason.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"abort-reason.test.js","sourceRoot":"","sources":["../../../src/utils/__tests__/abort-reason.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAA;AAE7C,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAE7C;;;;;;GAMG;AAEH,QAAQ,CAAC,6CAA6C,EAAE,GAAG,EAAE;IAC5D,EAAE,CAAC,gCAAgC,EAAE,GAAG,EAAE;QACzC,MAAM,CAAC,eAAe,CAAC,IAAI,KAAK,CAAC,0BAA0B,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,0BAA0B,CAAC,CAAA;IAChG,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,6DAA6D,EAAE,GAAG,EAAE;QACtE,MAAM,MAAM,GAAG,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAA;QAC3D,MAAM,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,iCAAiC,CAAC,CAAA;IACxE,CAAC,CAAC,CAAA;AACH,CAAC,CAAC,CAAA;AAEF,QAAQ,CAAC,yCAAyC,EAAE,GAAG,EAAE;IACxD,EAAE,CAAC,iCAAiC,EAAE,GAAG,EAAE;QAC1C,sEAAsE;QACtE,kEAAkE;QAClE,oEAAoE;QACpE,+CAA+C;QAC/C,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAA;QACxC,UAAU,CAAC,KAAK,EAAE,CAAA;QAElB,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,cAAc,CAAC,KAAK,CAAC,CAAA;QACtD,MAAM,CAAE,UAAU,CAAC,MAAM,CAAC,MAAgB,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,YAAY,CAAC,CAAA;QACnE,MAAM,CAAC,eAAe,CAAC,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,aAAa,EAAE,CAAA;IAClE,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,qCAAqC,EAAE,GAAG,EAAE;QAC9C,MAAM,OAAO,GAAG,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAA;QACrE,OAAO,CAAC,IAAI,GAAG,cAAc,CAAA;QAC7B,MAAM,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC,CAAC,aAAa,EAAE,CAAA;IACjD,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,qCAAqC,EAAE,GAAG,EAAE;QAC9C,oEAAoE;QACpE,sEAAsE;QACtE,wBAAwB;QACxB,MAAM,CAAC,eAAe,CAAC,UAAU,CAAC,CAAC,CAAC,aAAa,EAAE,CAAA;QACnD,MAAM,CAAC,eAAe,CAAC,SAAS,CAAC,CAAC,CAAC,aAAa,EAAE,CAAA;QAClD,MAAM,CAAC,eAAe,CAAC,EAAE,OAAO,EAAE,cAAc,EAAE,CAAC,CAAC,CAAC,aAAa,EAAE,CAAA;IACrE,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,kDAAkD,EAAE,GAAG,EAAE;QAC3D,MAAM,CAAC,eAAe,CAAC,IAAI,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,aAAa,EAAE,CAAA;IAC1D,CAAC,CAAC,CAAA;AACH,CAAC,CAAC,CAAA"}

package/dist/utils/abort.d.ts

@@ -1,2 +1,28 @@
+/**
+ * The words a caller attached to a stop, or nothing when there were none.
+ *
+ * A cancellation and a deadline arrive by the same mechanism and mean opposite
+ * things to whoever reads the result. "Was cancelled" tells a model that
+ * something outside it decided, and nothing about what — so a tool result
+ * could not distinguish an operator pressing stop from a budget running out
+ * from a parent abandoning a child, and every one of those wants a different
+ * next move.
+ *
+ * Two kinds of reason are deliberately reported as no reason:
+ *
+ * - `AbortError` and `TimeoutError`. `abort()` with no argument fills `reason`
+ *   with a DOMException named `AbortError`, so it is not a message anybody
+ *   wrote; it is the platform's word for "someone stopped and said nothing".
+ *   Rendering it would turn today's honest silence into a fake explanation.
+ * - Anything that is not an `Error`. The agent manager aborts a child with the
+ *   bare string `'canceled'`, which would otherwise render as "was cancelled:
+ *   canceled" — noise wearing the shape of information.
+ *
+ * Name-checked rather than checked by class, because a reason can cross a
+ * package boundary where `instanceof` stops holding across duplicate copies.
+ * That is the same answer this codebase already settled on for provider
+ * errors.
+ */
+export declare function abortReasonText(reason: unknown): string | undefined;
 export declare function createChildAbortController(parent: AbortController): AbortController;
 //# sourceMappingURL=abort.d.ts.map

package/dist/utils/abort.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"abort.d.ts","sourceRoot":"","sources":["../../src/utils/abort.ts"],"names":[],"mappings":"AAAA,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,eAAe,GAAG,eAAe,CA4BnF"}
+{"version":3,"file":"abort.d.ts","sourceRoot":"","sources":["../../src/utils/abort.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAKnE;AAED,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,eAAe,GAAG,eAAe,CA4BnF"}

package/dist/utils/abort.js

@@ -1,3 +1,37 @@
+import { toErrorMessage } from './error.js';
+/**
+ * The words a caller attached to a stop, or nothing when there were none.
+ *
+ * A cancellation and a deadline arrive by the same mechanism and mean opposite
+ * things to whoever reads the result. "Was cancelled" tells a model that
+ * something outside it decided, and nothing about what — so a tool result
+ * could not distinguish an operator pressing stop from a budget running out
+ * from a parent abandoning a child, and every one of those wants a different
+ * next move.
+ *
+ * Two kinds of reason are deliberately reported as no reason:
+ *
+ * - `AbortError` and `TimeoutError`. `abort()` with no argument fills `reason`
+ *   with a DOMException named `AbortError`, so it is not a message anybody
+ *   wrote; it is the platform's word for "someone stopped and said nothing".
+ *   Rendering it would turn today's honest silence into a fake explanation.
+ * - Anything that is not an `Error`. The agent manager aborts a child with the
+ *   bare string `'canceled'`, which would otherwise render as "was cancelled:
+ *   canceled" — noise wearing the shape of information.
+ *
+ * Name-checked rather than checked by class, because a reason can cross a
+ * package boundary where `instanceof` stops holding across duplicate copies.
+ * That is the same answer this codebase already settled on for provider
+ * errors.
+ */
+export function abortReasonText(reason) {
+    if (!(reason instanceof Error))
+        return undefined;
+    if (reason.name === 'AbortError' || reason.name === 'TimeoutError')
+        return undefined;
+    const text = toErrorMessage(reason).trim();
+    return text.length > 0 ? text : undefined;
+}
 export function createChildAbortController(parent) {
     const child = new AbortController();
     if (parent.signal.aborted) {

package/dist/utils/abort.js.map

@@ -1 +1 @@
-{"version":3,"file":"abort.js","sourceRoot":"","sources":["../../src/utils/abort.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,0BAA0B,CAAC,MAAuB;IACjE,MAAM,KAAK,GAAG,IAAI,eAAe,EAAE,CAAA;IAEnC,IAAI,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QAC3B,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;QACjC,OAAO,KAAK,CAAA;IACb,CAAC;IAED,MAAM,SAAS,GAAG,IAAI,OAAO,CAAC,KAAK,CAAC,CAAA;IAEpC,MAAM,aAAa,GAAG,GAAS,EAAE;QAChC,MAAM,GAAG,GAAG,SAAS,CAAC,KAAK,EAAE,CAAA;QAC7B,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YAChC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;QAChC,CAAC;IACF,CAAC,CAAA;IAED,MAAM,CAAC,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,aAAa,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAA;IAEtE,KAAK,CAAC,MAAM,CAAC,gBAAgB,CAC5B,OAAO,EACP,GAAG,EAAE;QACJ,MAAM,CAAC,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,aAAa,CAAC,CAAA;IAC1D,CAAC,EACD,EAAE,IAAI,EAAE,IAAI,EAAE,CACd,CAAA;IAED,OAAO,KAAK,CAAA;AACb,CAAC"}
+{"version":3,"file":"abort.js","sourceRoot":"","sources":["../../src/utils/abort.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAE3C;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,eAAe,CAAC,MAAe;IAC9C,IAAI,CAAC,CAAC,MAAM,YAAY,KAAK,CAAC;QAAE,OAAO,SAAS,CAAA;IAChD,IAAI,MAAM,CAAC,IAAI,KAAK,YAAY,IAAI,MAAM,CAAC,IAAI,KAAK,cAAc;QAAE,OAAO,SAAS,CAAA;IACpF,MAAM,IAAI,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAA;IAC1C,OAAO,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAA;AAC1C,CAAC;AAED,MAAM,UAAU,0BAA0B,CAAC,MAAuB;IACjE,MAAM,KAAK,GAAG,IAAI,eAAe,EAAE,CAAA;IAEnC,IAAI,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QAC3B,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;QACjC,OAAO,KAAK,CAAA;IACb,CAAC;IAED,MAAM,SAAS,GAAG,IAAI,OAAO,CAAC,KAAK,CAAC,CAAA;IAEpC,MAAM,aAAa,GAAG,GAAS,EAAE;QAChC,MAAM,GAAG,GAAG,SAAS,CAAC,KAAK,EAAE,CAAA;QAC7B,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YAChC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;QAChC,CAAC;IACF,CAAC,CAAA;IAED,MAAM,CAAC,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,aAAa,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAA;IAEtE,KAAK,CAAC,MAAM,CAAC,gBAAgB,CAC5B,OAAO,EACP,GAAG,EAAE;QACJ,MAAM,CAAC,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,aAAa,CAAC,CAAA;IAC1D,CAAC,EACD,EAAE,IAAI,EAAE,IAAI,EAAE,CACd,CAAA;IAED,OAAO,KAAK,CAAA;AACb,CAAC"}

package/dist/verification/__tests__/argument-pattern.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=argument-pattern.test.d.ts.map

package/dist/verification/__tests__/argument-pattern.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"argument-pattern.test.d.ts","sourceRoot":"","sources":["../../../src/verification/__tests__/argument-pattern.test.ts"],"names":[],"mappings":""}

package/dist/verification/__tests__/argument-pattern.test.js

@@ -0,0 +1,122 @@
+import { describe, expect, it } from 'vitest';
+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) {
+    return new VerificationGate({
+        enabled: true,
+        rules,
+        allowReadOnlyTools: false,
+        denyDangerousPatterns: false,
+        logDecisions: false,
+    }, getRootLogger());
+}
+/** Only the fields the gate reads. */
+function toolDef(name) {
+    return { name, isReadOnly: () => false };
+}
+const PUSH_RULE = {
+    type: 'argument_pattern',
+    toolNames: ['bash'],
+    argument: 'command',
+    pattern: '^git push',
+    decision: 'deny',
+};
+function evaluate(rules, toolName, toolInput) {
+    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 = { ...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 = {
+            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 = { ...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 = { ...PUSH_RULE, pattern: '([unclosed' };
+        expect(evaluate([broken], 'bash', { command: 'git push origin main' }).decision).not.toBe('deny');
+    });
+});
+//# sourceMappingURL=argument-pattern.test.js.map

package/dist/verification/__tests__/argument-pattern.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"argument-pattern.test.js","sourceRoot":"","sources":["../../../src/verification/__tests__/argument-pattern.test.ts"],"names":[],"mappings":"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"}

package/dist/verification/__tests__/rule-order-and-reason.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=rule-order-and-reason.test.d.ts.map

package/dist/verification/__tests__/rule-order-and-reason.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rule-order-and-reason.test.d.ts","sourceRoot":"","sources":["../../../src/verification/__tests__/rule-order-and-reason.test.ts"],"names":[],"mappings":""}

package/dist/verification/__tests__/rule-order-and-reason.test.js

@@ -0,0 +1,126 @@
+import { describe, expect, it } from 'vitest';
+import { getRootLogger } from '../../utils/logger.js';
+import { VerificationGate, describeRule } from '../gate.js';
+/**
+ * Two things an operator has to be able to trust about a policy gate: that a
+ * rule they wrote is consulted, and that a refusal says enough to act on.
+ *
+ * Neither held. `allowReadOnlyTools` was expanded into a rule AHEAD of the
+ * operator's own, and the gate stops at the first match — so "prompt me before
+ * every read" was not rejected, not warned about, just never reached. And a
+ * denial arrived as the rule's TYPE NAME, which tells a model that a rule
+ * matched and nothing whatever about what it said.
+ */
+function gate(config) {
+    return new VerificationGate({
+        enabled: true,
+        rules: [],
+        allowReadOnlyTools: false,
+        denyDangerousPatterns: false,
+        logDecisions: false,
+        ...config,
+    }, getRootLogger());
+}
+/** Only the fields the gate reads. */
+function toolDef(name, readOnly) {
+    return { name, isReadOnly: () => readOnly };
+}
+describe('an operator rule outranks the read-only convenience', () => {
+    it('lets a rule make a read-only tool prompt', () => {
+        // The case that was silently unreachable: `read` observes only, the
+        // convenience is on, and the operator has asked to be consulted anyway.
+        const result = gate({
+            allowReadOnlyTools: true,
+            rules: [{ type: 'deny_by_name', toolNames: ['read'] }],
+        }).evaluate({
+            toolName: 'read',
+            toolInput: { path: 'notes.txt' },
+            toolDef: toolDef('read', true),
+        });
+        expect(result.decision, 'the operator rule was never consulted').toBe('deny');
+    });
+    it('still allows a read-only tool nobody wrote a rule about', () => {
+        // The convenience keeps doing its job as a DEFAULT, which is what it
+        // always was in substance.
+        const result = gate({
+            allowReadOnlyTools: true,
+            rules: [{ type: 'deny_by_name', toolNames: ['write'] }],
+        }).evaluate({
+            toolName: 'grep',
+            toolInput: { pattern: 'x' },
+            toolDef: toolDef('grep', true),
+        });
+        expect(result.decision).toBe('allow');
+    });
+});
+describe('the safety floor still outranks everything', () => {
+    it('refuses a dangerous pattern even when a rule would allow the tool', () => {
+        // The denial goes first and stays there. An operator rule must not be
+        // able to open what it closes.
+        const result = gate({
+            denyDangerousPatterns: true,
+            rules: [{ type: 'allow_by_name', toolNames: ['bash'] }],
+        }).evaluate({
+            toolName: 'bash',
+            toolInput: { command: 'rm -rf /' },
+            toolDef: toolDef('bash', false),
+        });
+        expect(result.decision).toBe('deny');
+    });
+});
+describe('a refusal says what the rule said', () => {
+    it('names the pattern rather than the rule type', () => {
+        // "Matched rule: custom_pattern" tells a model a rule matched and
+        // nothing about it, so it rewords the same call and tries again. The
+        // pattern is what makes the retry visibly pointless.
+        const reason = describeRule({
+            type: 'custom_pattern',
+            pattern: 'git push*',
+            target: 'args',
+            decision: 'deny',
+        });
+        expect(reason).toContain('git push*');
+        expect(reason).toContain('denied');
+        expect(reason).not.toContain('custom_pattern');
+    });
+    it('says a by-name denial is about the tool, not the input', () => {
+        // The distinction that decides the next move: reworded arguments will
+        // not help, so the model should stop rather than iterate.
+        const reason = describeRule({ type: 'deny_by_name', toolNames: ['bash', 'write'] });
+        expect(reason).toContain('bash');
+        expect(reason).toContain('a different input will not change it');
+    });
+    it('says a dangerous-pattern refusal is not worth rewording', () => {
+        expect(describeRule({ type: 'deny_dangerous_patterns' })).toContain('will not help');
+    });
+    it('reaches the model through the gate result, not just the helper', () => {
+        const result = gate({ rules: [{ type: 'deny_by_name', toolNames: ['bash'] }] }).evaluate({
+            toolName: 'bash',
+            toolInput: { command: 'ls' },
+            toolDef: toolDef('bash', false),
+        });
+        expect(result.reason).toContain('bash');
+        expect(result.reason).not.toMatch(/^Matched rule:/);
+    });
+    it('is reachable by a caller driving the rules without the gate', async () => {
+        // `evaluateRule` is public and answers only WHETHER a rule matched. A
+        // caller holding that verdict and no describer is back to switching on
+        // the rule's type for its wording — the same defect the gate carried,
+        // one layer up. So the two travel together, and this asserts the
+        // PAIRING rather than either one alone.
+        //
+        // Asserted at this barrel rather than the package barrel on purpose.
+        // Importing `../../index.js` costs ~4s of module-graph load — measured,
+        // on an idle machine, against a default 5s test budget — so the version
+        // of this test that looked stronger was one busy CI runner away from
+        // failing for a reason that has nothing to do with verification. The
+        // package half is gated better elsewhere anyway: the public-surface
+        // baseline resolves `dist/index.d.ts` through the checker and reports a
+        // REGRESSION naming any symbol that leaves the surface.
+        const barrel = await import('../index.js');
+        expect(typeof barrel.evaluateRule).toBe('function');
+        expect(typeof barrel.describeRule).toBe('function');
+        expect(barrel.describeRule({ type: 'deny_by_name', toolNames: ['bash'] })).toContain('bash');
+    });
+});
+//# sourceMappingURL=rule-order-and-reason.test.js.map

package/dist/verification/__tests__/rule-order-and-reason.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rule-order-and-reason.test.js","sourceRoot":"","sources":["../../../src/verification/__tests__/rule-order-and-reason.test.ts"],"names":[],"mappings":"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"}

package/dist/verification/gate.d.ts

@@ -1,11 +1,27 @@
 import type { ToolDefinition } from '../types/tool/index.js';
-import type { GateEvaluationResult, VerificationGateConfig } from '../types/verification/index.js';
+import type { GateEvaluationResult, VerificationGateConfig, VerificationRule } from '../types/verification/index.js';
 import type { Logger } from '../utils/logger.js';
 export interface ToolCallContext {
     readonly toolName: string;
     readonly toolInput: unknown;
     readonly toolDef: ToolDefinition | undefined;
 }
+/**
+ * What the rule actually said, in words a model can act on.
+ *
+ * This used to be the rule TYPE and nothing else, so a denial reached the
+ * model as "Blocked by the verification gate: Matched rule: deny_by_name" —
+ * naming the kind of rule and nothing about it. Not which tool, not which
+ * pattern, not whether a different input would fare better.
+ *
+ * The difference is behavioural rather than cosmetic. Told only that it was
+ * denied, a model rewords the same call and tries again, because nothing in
+ * the message says a retry is pointless. Told that a pattern rule denies
+ * `git push*`, it can stop, say so, and do something else. A refusal that
+ * cannot be reasoned about produces thrashing; one that can produces a route
+ * around it.
+ */
+export declare function describeRule(rule: VerificationRule): string;
 export declare class VerificationGate {
     private readonly rules;
     private readonly compiledPatterns;