vigiles 39.1.0 → 39.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -166,11 +166,16 @@ exports.claudeCodeDialect = {
166
166
  // aliased to the compiler's RENDERABLE_SKILL_FRONTMATTER_KEYS: that constant is
167
167
  // "what vigiles can write", this list is "what Claude Code reads", and a new
168
168
  // renderable key must not silently become a claim about the vendor.
169
+ // `agent` and `model`: code.claude.com/docs/en/skills, frontmatter table —
170
+ // "Which subagent type to use when `context: fork` is set" and "With
171
+ // `context: fork`, the value sets the forked subagent's model instead" (#401).
169
172
  skillFrontmatterKeys: [
170
173
  "name",
171
174
  "description",
172
175
  "disable-model-invocation",
173
176
  "context",
177
+ "agent",
178
+ "model",
174
179
  "argument-hint",
175
180
  "allowed-tools",
176
181
  "disallowed-tools",
@@ -16,7 +16,7 @@
16
16
  * That is not cosmetic, because audit's flags govern what LEAVES THE MACHINE:
17
17
  * `--no-html`, `--no-json`, `--out=<dir>`, `--serve`. `--no-htlm` writes the HTML
18
18
  * report while the author believes they suppressed it. For a tool whose thesis is
19
- * "prose isn't policy", accepting an argument it did not understand and carrying
19
+ * that a stated rule is not an enforced one, accepting an argument it did not understand and carrying
20
20
  * on is the same class of error it names elsewhere: the argument is PRESENT, so
21
21
  * the property is assumed enforced.
22
22
  *
@@ -17,7 +17,7 @@
17
17
  * That is not cosmetic, because audit's flags govern what LEAVES THE MACHINE:
18
18
  * `--no-html`, `--no-json`, `--out=<dir>`, `--serve`. `--no-htlm` writes the HTML
19
19
  * report while the author believes they suppressed it. For a tool whose thesis is
20
- * "prose isn't policy", accepting an argument it did not understand and carrying
20
+ * that a stated rule is not an enforced one, accepting an argument it did not understand and carrying
21
21
  * on is the same class of error it names elsewhere: the argument is PRESENT, so
22
22
  * the property is assumed enforced.
23
23
  *
package/dist/cli-main.js CHANGED
@@ -4281,7 +4281,7 @@ function untestedRules(config, rules) {
4281
4281
  include: opts.include,
4282
4282
  // Without this the `testExtension` documented on TestCoverageOptions was a
4283
4283
  // config key nothing read: a TypeScript-shaped repo got `.ts` suggestions
4284
- // however the author configured it. Prose isn't policy, in our own CLI.
4284
+ // however the author configured it. A documented key must be a read key, in our own CLI too.
4285
4285
  testExtension: opts.testExtension,
4286
4286
  },
4287
4287
  };
@@ -360,6 +360,8 @@ const SKILL_KNOWN_KEYS = new Set([
360
360
  "disable-model-invocation",
361
361
  "argument-hint",
362
362
  "context",
363
+ "agent",
364
+ "model",
363
365
  ]);
364
366
  const AGENT_KNOWN_KEYS = new Set([
365
367
  "name",
@@ -407,6 +409,33 @@ function unmappedNote(kind, keys) {
407
409
  }
408
410
  const SURFACE_HEADER = (from) => `// Adopted from ${from} by \`vigiles init\` — body verbatim, standard\n` +
409
411
  `// frontmatter mapped; no rules inferred. Review the diff, then \`compile\`.\n`;
412
+ /**
413
+ * Where a SKILL.md says it runs — `context`, `agent`, `model` — as spec fields and
414
+ * as the spec-source lines that write them, in compile's render order.
415
+ *
416
+ * `context: fork` is a supported skill key (a forked skill runs as a subagent);
417
+ * `"fork"` is the only valid value. Previously it was in SKILL_KNOWN_KEYS but
418
+ * never read, so an existing SKILL.md's `context: fork` was silently dropped on
419
+ * adopt with NO unmapped-key warning (the key was falsely marked "known"). (#107)
420
+ * `agent` and `model` are plain strings (#401).
421
+ */
422
+ function adoptExecutionKeys(fm) {
423
+ const isFork = (0, frontmatter_read_js_1.frontmatterScalar)(fm, "context") === "fork";
424
+ const found = ["agent", "model"].flatMap((key) => {
425
+ const value = (0, frontmatter_read_js_1.frontmatterScalar)(fm, key);
426
+ return value ? [{ key, value }] : [];
427
+ });
428
+ return {
429
+ fields: {
430
+ ...(isFork ? { context: "fork" } : {}),
431
+ ...Object.fromEntries(found.map(({ key, value }) => [key, value])),
432
+ },
433
+ lines: [
434
+ ...(isFork ? [` context: "fork",`] : []),
435
+ ...found.map(({ key, value }) => ` ${key}: ${JSON.stringify(value)},`),
436
+ ],
437
+ };
438
+ }
410
439
  /**
411
440
  * Adopt an existing SKILL.md into an `experimental_skill()` spec. The body is carried verbatim
412
441
  * (skills are freeform markdown — `##` headings stay in the body), so a clean
@@ -423,11 +452,7 @@ function adoptSkill(markdown, dirName) {
423
452
  const tools = (0, frontmatter_read_js_1.frontmatterList)(fm, "allowed-tools") ?? (0, frontmatter_read_js_1.frontmatterList)(fm, "tools");
424
453
  const argumentHint = (0, frontmatter_read_js_1.frontmatterScalar)(fm, "argument-hint");
425
454
  const disableModelInvocation = (0, frontmatter_read_js_1.frontmatterScalar)(fm, "disable-model-invocation") === "true";
426
- // `context: fork` is a supported skill key (a forked skill runs as a subagent);
427
- // `"fork"` is the only valid value. Previously it was in SKILL_KNOWN_KEYS but
428
- // never read, so an existing SKILL.md's `context: fork` was silently dropped on
429
- // adopt with NO unmapped-key warning (the key was falsely marked "known"). (#107)
430
- const isFork = (0, frontmatter_read_js_1.frontmatterScalar)(fm, "context") === "fork";
455
+ const execution = adoptExecutionKeys(fm);
431
456
  const unmappedKeys = unmappedFrontmatterKeys(fm, SKILL_KNOWN_KEYS);
432
457
  const lines = [
433
458
  ` name: ${JSON.stringify(name)},`,
@@ -435,8 +460,7 @@ function adoptSkill(markdown, dirName) {
435
460
  ];
436
461
  if (argumentHint)
437
462
  lines.push(` argumentHint: ${JSON.stringify(argumentHint)},`);
438
- if (isFork)
439
- lines.push(` context: "fork",`);
463
+ lines.push(...execution.lines);
440
464
  if (disableModelInvocation)
441
465
  lines.push(` disableModelInvocation: true,`);
442
466
  if (tools && tools.length > 0)
@@ -448,7 +472,7 @@ function adoptSkill(markdown, dirName) {
448
472
  name,
449
473
  description,
450
474
  ...(argumentHint ? { argumentHint } : {}),
451
- ...(isFork ? { context: "fork" } : {}),
475
+ ...execution.fields,
452
476
  ...(disableModelInvocation ? { disableModelInvocation: true } : {}),
453
477
  ...(tools && tools.length > 0 ? { tools } : {}),
454
478
  ...(trimmedBody ? { body: trimmedBody } : {}),
@@ -56,7 +56,7 @@ export declare function verifyHash(content: string): {
56
56
  */
57
57
  /** @internal */ export declare function estimateTokens(text: string): number;
58
58
  export interface CompileError {
59
- type: "stale-file" | "stale-command" | "stale-ref" | "invalid-rule" | "budget-exceeded" | "section-too-long" | "section-has-header" | "reserved-section-key" | "spec-name-mismatch" | "unknown-tool" | "invalid-railway" | "purity-violation" | "output-without-fork" | "effect-in-skill" | "inline-code-too-long" | "entry-too-long" | "section-too-large" | "rules-too-large";
59
+ type: "stale-file" | "stale-command" | "stale-ref" | "invalid-rule" | "budget-exceeded" | "section-too-long" | "section-has-header" | "reserved-section-key" | "spec-name-mismatch" | "unknown-tool" | "invalid-railway" | "purity-violation" | "output-without-fork" | "agent-without-fork" | "effect-in-skill" | "inline-code-too-long" | "entry-too-long" | "section-too-large" | "rules-too-large";
60
60
  message: string;
61
61
  path?: string;
62
62
  }
@@ -1062,6 +1062,19 @@ function yamlScalar(value) {
1062
1062
  * exactly what a key set says. A harness that reads four of the seven now gets
1063
1063
  * four, instead of falling into whichever of two buckets someone picked for it.
1064
1064
  */
1065
+ /**
1066
+ * The frontmatter lines that say WHERE a skill runs, in render order: `context`,
1067
+ * then the subagent type and the model a fork starts (`agent`, `model`, #401).
1068
+ * Only keys the dialect reads (`emits`) and the spec sets.
1069
+ */
1070
+ function executionFrontmatter(spec, emits) {
1071
+ const set = [
1072
+ ["context", spec.context],
1073
+ ["agent", spec.agent === undefined ? undefined : yamlScalar(spec.agent)],
1074
+ ["model", spec.model === undefined ? undefined : yamlScalar(spec.model)],
1075
+ ];
1076
+ return set.flatMap(([key, value]) => emits(key) && value !== undefined ? [`${key}: ${value}`] : []);
1077
+ }
1065
1078
  function renderSkillFrontmatter(spec, keys = dialect_js_1.RENDERABLE_SKILL_FRONTMATTER_KEYS) {
1066
1079
  const emits = (key) => keys.includes(key);
1067
1080
  const fm = ["---"];
@@ -1074,9 +1087,7 @@ function renderSkillFrontmatter(spec, keys = dialect_js_1.RENDERABLE_SKILL_FRONT
1074
1087
  spec.disableModelInvocation !== undefined) {
1075
1088
  fm.push(`disable-model-invocation: ${String(spec.disableModelInvocation)}`);
1076
1089
  }
1077
- if (emits("context") && spec.context !== undefined) {
1078
- fm.push(`context: ${spec.context}`);
1079
- }
1090
+ fm.push(...executionFrontmatter(spec, emits));
1080
1091
  const argHint = spec.inputs && spec.inputs.length > 0
1081
1092
  ? renderArgumentHint(spec.inputs)
1082
1093
  : spec.argumentHint;
@@ -1164,6 +1175,38 @@ function checkInlineCode(markdown, max) {
1164
1175
  }
1165
1176
  return warns;
1166
1177
  }
1178
+ /**
1179
+ * Fields that mean something only for a FORKED skill, reported when the skill is
1180
+ * inline. `output`: an inline skill has no call→return boundary, so a typed
1181
+ * outcome there is a category error (see research/spec-syntax-and-railway-scope.md).
1182
+ * `agent`: the subagent type a fork starts — inline, no subagent starts (#401).
1183
+ * `model` is NOT here: inline it sets the turn's model, which is a real meaning.
1184
+ */
1185
+ function forkOnlyErrors(spec) {
1186
+ if (spec.context === "fork")
1187
+ return [];
1188
+ const output = spec.output
1189
+ ? [
1190
+ {
1191
+ type: "output-without-fork",
1192
+ message: 'A skill `output` (result() contract) requires `context: "fork"` — an ' +
1193
+ "inline skill has no return value to type. Add context:'fork' to run it " +
1194
+ "as a subagent, or drop `output`.",
1195
+ },
1196
+ ]
1197
+ : [];
1198
+ const agent = spec.agent === undefined
1199
+ ? []
1200
+ : [
1201
+ {
1202
+ type: "agent-without-fork",
1203
+ message: `A skill \`agent\` ("${spec.agent}") requires \`context: "fork"\` — it ` +
1204
+ "names the subagent a forked skill starts, and an inline skill starts " +
1205
+ "none. Add context:'fork', or drop `agent`.",
1206
+ },
1207
+ ];
1208
+ return [...output, ...agent];
1209
+ }
1167
1210
  /**
1168
1211
  * Compile a SkillSpec into SKILL.md markdown with YAML frontmatter.
1169
1212
  */
@@ -1197,17 +1240,7 @@ async function compileSkill(spec, options) {
1197
1240
  }
1198
1241
  }
1199
1242
  errors.push(...(await validateRefs(collectSkillRefs(spec), basePath)));
1200
- // A typed `output` Result contract is valid ONLY for a forked skill: an inline
1201
- // skill has no call→return boundary, so a typed outcome there is a category
1202
- // error (see research/spec-syntax-and-railway-scope.md). Enforce it at compile.
1203
- if (spec.output && spec.context !== "fork") {
1204
- errors.push({
1205
- type: "output-without-fork",
1206
- message: 'A skill `output` (result() contract) requires `context: "fork"` — an ' +
1207
- "inline skill has no return value to type. Add context:'fork' to run it " +
1208
- "as a subagent, or drop `output`.",
1209
- });
1210
- }
1243
+ errors.push(...forkOnlyErrors(spec));
1211
1244
  // effect() is a SUBAGENT primitive. A deterministic effect REGION needs a
1212
1245
  // structural call→return bracket to scope it; a default skill is spliced into
1213
1246
  // the main conversation and has none (the dogfood that proved the model-emitted
@@ -35,7 +35,7 @@ import type { InstructionBudget } from "./instruction-weight.js";
35
35
  * membership test over key names, which are facts about a FILE FORMAT and carry
36
36
  * no harness in them.
37
37
  */
38
- export declare const RENDERABLE_SKILL_FRONTMATTER_KEYS: readonly ["name", "description", "disable-model-invocation", "context", "argument-hint", "allowed-tools", "disallowed-tools"];
38
+ export declare const RENDERABLE_SKILL_FRONTMATTER_KEYS: readonly ["name", "description", "disable-model-invocation", "context", "agent", "model", "argument-hint", "allowed-tools", "disallowed-tools"];
39
39
  /**
40
40
  * The instruction filenames vigiles recognizes when NO dialect is injected, in
41
41
  * precedence order — `[0]` is what a spec compiles into when it names no target.
@@ -20,6 +20,8 @@ exports.RENDERABLE_SKILL_FRONTMATTER_KEYS = [
20
20
  "description",
21
21
  "disable-model-invocation",
22
22
  "context",
23
+ "agent",
24
+ "model",
23
25
  "argument-hint",
24
26
  "allowed-tools",
25
27
  "disallowed-tools",
@@ -495,6 +495,23 @@ export interface SkillSpec {
495
495
  * for the default inline execution.
496
496
  */
497
497
  readonly context?: "fork";
498
+ /**
499
+ * The subagent type a forked skill starts (`agent` frontmatter): a built-in
500
+ * type (`Explore`, `Plan`, `general-purpose`) or a custom one from the
501
+ * harness's agents directory. Requires `context: "fork"` — without a fork
502
+ * there is no subagent to pick (compile error `agent-without-fork`). Omitted,
503
+ * the harness uses `general-purpose`.
504
+ */
505
+ readonly agent?: string;
506
+ /**
507
+ * The model the skill runs on (`model` frontmatter): an alias (`sonnet`,
508
+ * `opus`, `haiku`, `fable`), a full model id, or `inherit`. With
509
+ * `context: "fork"` it sets the forked subagent's model; inline, it overrides
510
+ * the model for the rest of the current turn. Omitted on a forked skill, the
511
+ * subagent resolves to the main conversation's model — which is the costly
512
+ * default this field exists to override.
513
+ */
514
+ readonly model?: string;
498
515
  /**
499
516
  * The allowed-tools contract for this skill. Each entry must be a known
500
517
  * built-in tool or an MCP tool (`mcp__server__tool`). Omit to inherit all
@@ -7,8 +7,8 @@
7
7
  * that must obey it — "always pass `curl -g`, or bracketed params glob and the
8
8
  * request fails SILENTLY"; "every `psql` needs `--single-transaction`". The rule
9
9
  * and its violation live **in the same file**, three paragraphs apart, and
10
- * nothing compares them. It is `prose isn't policy` turned on the author's own
11
- * document, and it is the smallest possible instance of it.
10
+ * nothing compares them. It is a rule nobody checks, turned on the author's own
11
+ * document, and it is the smallest possible instance of one.
12
12
  *
13
13
  * vigiles cannot INFER such a rule — no tool reads "always use -g" and derives
14
14
  * which flag is mandatory. What was missing is not cleverness but a cheap way to
@@ -23,7 +23,9 @@ import type { SkillSpec } from "./core/spec.js";
23
23
  * `disallowed-tools` are also droppable and are not listed here. That is the
24
24
  * pre-existing scope of this warning, carried over unchanged when the profile
25
25
  * enum became a key set — widening it is a behaviour change to argue
26
- * separately, not a side effect of the rename.
26
+ * separately, not a side effect of the rename. `agent` and `model` are in
27
+ * because they arrived after that scope was set (#401): no existing spec sets
28
+ * them, so listing them warns no one who was not warned before.
27
29
  */
28
30
  export declare function optionalFrontmatterKeys(spec: SkillSpec): string[];
29
31
  /**
@@ -12,7 +12,9 @@ const adapter_registry_js_1 = require("./adapter-registry.js");
12
12
  * `disallowed-tools` are also droppable and are not listed here. That is the
13
13
  * pre-existing scope of this warning, carried over unchanged when the profile
14
14
  * enum became a key set — widening it is a behaviour change to argue
15
- * separately, not a side effect of the rename.
15
+ * separately, not a side effect of the rename. `agent` and `model` are in
16
+ * because they arrived after that scope was set (#401): no existing spec sets
17
+ * them, so listing them warns no one who was not warned before.
16
18
  */
17
19
  function optionalFrontmatterKeys(spec) {
18
20
  const keys = [];
@@ -22,7 +24,8 @@ function optionalFrontmatterKeys(spec) {
22
24
  if (spec.argumentHint || (spec.inputs && spec.inputs.length > 0)) {
23
25
  keys.push("argument-hint");
24
26
  }
25
- return keys;
27
+ const execution = ["agent", "model"].filter((key) => spec[key] !== undefined);
28
+ return [...keys, ...execution];
26
29
  }
27
30
  /**
28
31
  * Warn for each declared harness that would DROP frontmatter keys this skill
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "vigiles",
3
- "version": "39.1.0",
3
+ "version": "39.2.0",
4
4
  "description": "Audit, test and measure the harness your AI agent runs on — grade your CLAUDE.md / AGENTS.md, skills, subagents and hooks, run them against a scripted model, and measure whether they actually fire.",
5
5
  "keywords": [
6
6
  "claude-code",