@dsh-cc/claude-code-agents 0.5.0

package/lib/index.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Load Claude Code's `.claude/agents` sub-agent definitions as dsh agent
+ * presets: a pure, filesystem-backed translation that discovers the user and
+ * project layers, parses and validates every `.md`/`.json` agent file, and
+ * returns one {@link AgentDefinition} per agent — ready to be mounted by a
+ * preset row or subagent driver.
+ *
+ * The loader is deliberately integration-free on purpose it is CLI-domain pure:
+ * it produces typed definitions and leaves their consumption (scoped tool
+ * restriction, request rewriting, permission selection) to the caller, so the
+ * model-facing parts can be reused by a Claude Code plugin loader elsewhere
+ * without dragging in the harness runtime.
+ *
+ * @module @dsh-cc/claude-code-agents
+ */
+import type { AgentDefinition } from './types.ts';
+/** Options controlling where the loader discovers agent definitions from. */
+export interface LoadOptions {
+    /**
+     * The user `.claude/agents` directory. Defaults to the OS home's
+     * `.claude/agents`; passing your own makes the loader hermetic in tests and
+     * lets a harness with a non-default home point it at the right layer.
+     */
+    readonly userDir?: string;
+}
+/**
+ * Load every Claude Code agent definition visible from a project root.
+ *
+ * The project layer is the nearest `.claude/agents` directory found by walking
+ * up from `root`; it shadows the user layer on a name collision. A discovered
+ * agent file that fails to parse throws with its path, so a broken agent is
+ * reported, not skipped.
+ * @param root - the project directory the project layer resolves from.
+ * @param options - explicit user-layer override.
+ * @returns the merged agent definitions, project shadowing user.
+ * @throws when a discovered agent file cannot be read or parsed.
+ */
+export declare function loadClaudeCodeAgents(root: string, options?: LoadOptions): Promise<AgentDefinition[]>;
+export * from './types.ts';
+export { discoverBundledAgents } from './bundled/index.ts';
+export { loadAgentsDir, findProjectAgentsDir, discoverAgents, AGENTS_DIR, CLAUDE_DIR } from './discovery.ts';
+export { parseAgentMarkdown, parseAgentJson, splitFrontmatter } from './parse.ts';
+export type { ParsedMarkdown } from './parse.ts';
+export { resolveToolRestriction, normalizeModel } from './restrict.ts';
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEjD,6EAA6E;AAC7E,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAC1B;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,eAAe,EAAE,CAAC,CAG5B;AAED,cAAc,YAAY,CAAA;AAC1B,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAA;AAC1D,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,cAAc,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAC5G,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AACjF,YAAY,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAChD,OAAO,EAAE,sBAAsB,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA"}

package/lib/index.js

@@ -0,0 +1,40 @@
+/**
+ * Load Claude Code's `.claude/agents` sub-agent definitions as dsh agent
+ * presets: a pure, filesystem-backed translation that discovers the user and
+ * project layers, parses and validates every `.md`/`.json` agent file, and
+ * returns one {@link AgentDefinition} per agent — ready to be mounted by a
+ * preset row or subagent driver.
+ *
+ * The loader is deliberately integration-free on purpose it is CLI-domain pure:
+ * it produces typed definitions and leaves their consumption (scoped tool
+ * restriction, request rewriting, permission selection) to the caller, so the
+ * model-facing parts can be reused by a Claude Code plugin loader elsewhere
+ * without dragging in the harness runtime.
+ *
+ * @module @dsh-cc/claude-code-agents
+ */
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { discoverAgents } from "./discovery.js";
+/**
+ * Load every Claude Code agent definition visible from a project root.
+ *
+ * The project layer is the nearest `.claude/agents` directory found by walking
+ * up from `root`; it shadows the user layer on a name collision. A discovered
+ * agent file that fails to parse throws with its path, so a broken agent is
+ * reported, not skipped.
+ * @param root - the project directory the project layer resolves from.
+ * @param options - explicit user-layer override.
+ * @returns the merged agent definitions, project shadowing user.
+ * @throws when a discovered agent file cannot be read or parsed.
+ */
+export async function loadClaudeCodeAgents(root, options = {}) {
+    const userDir = options.userDir ?? join(homedir(), '.claude', 'agents');
+    return await discoverAgents(root, userDir);
+}
+export * from "./types.js";
+export { discoverBundledAgents } from "./bundled/index.js";
+export { loadAgentsDir, findProjectAgentsDir, discoverAgents, AGENTS_DIR, CLAUDE_DIR } from "./discovery.js";
+export { parseAgentMarkdown, parseAgentJson, splitFrontmatter } from "./parse.js";
+export { resolveToolRestriction, normalizeModel } from "./restrict.js";
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAA;AACjC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAChC,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAa/C;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,IAAY,EACZ,UAAuB,EAAE;IAEzB,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,IAAI,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAA;IACvE,OAAO,MAAM,cAAc,CAAC,IAAI,EAAE,OAAO,CAAC,CAAA;AAC5C,CAAC;AAED,cAAc,YAAY,CAAA;AAC1B,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAA;AAC1D,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,cAAc,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAC5G,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAEjF,OAAO,EAAE,sBAAsB,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA"}

package/lib/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@dsh-cc/claude-code-agents`.
+ * @module @dsh-cc/claude-code-agents/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "claude-code-agents-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/invariant.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invariant.d.ts","sourceRoot":"","sources":["../src/invariant.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAKlD,oCAAoC;AACpC,eAAO,MAAM,IAAI,iCAAiC,CAAA;AAClD,2EAA2E;AAC3E,eAAO,MAAM,MAAM,UAAiB,CAAA;AAQpC;;;;GAIG;AACH,eAAO,MAAM,KAAK,GAAI,KAAK,OAAO,KAAG,OAAO,CAAC,MAAM,IAAI,CACU,CAAA"}

package/lib/invariant.js

@@ -0,0 +1,22 @@
+/**
+ * Package-owned invariant companion for `@dsh-cc/claude-code-agents`.
+ * @module @dsh-cc/claude-code-agents/invariant
+ */
+const PACKAGE_NAME = '@dsh-cc/claude-code-agents';
+/** Cordis companion plugin name. */
+export const name = 'claude-code-agents-invariant';
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants'];
+/**
+ * No runtime invariant: the loader is a pure filesystem translation owning no
+ * session or event stream; parse/discovery/restrict unit tests cover it.
+ */
+const install = () => { };
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+/* jscpd:ignore-end */
+//# sourceMappingURL=invariant.js.map

package/lib/invariant.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"invariant.js","sourceRoot":"","sources":["../src/invariant.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,MAAM,YAAY,GAAG,4BAA4B,CAAA;AAEjD,oCAAoC;AACpC,MAAM,CAAC,MAAM,IAAI,GAAG,8BAA8B,CAAA;AAClD,2EAA2E;AAC3E,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,YAAY,CAAC,CAAA;AAEpC;;;GAGG;AACH,MAAM,OAAO,GAAuB,GAAG,EAAE,GAAE,CAAC,CAAA;AAE5C;;;;GAIG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,CAAC,GAAY,EAAuB,EAAE,CACzD,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC,CAAA;AACjE,sBAAsB"}

package/lib/parse.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Parse one Claude Code agent file (`.md` frontmatter + markdown body, or
+ * `.json`) into an {@link AgentDefinition}. Every bad known-frontmatter value
+ * throws at load time with the file path and the field name, so a broken agent
+ * surfaces loud instead of silently degrading; unknown fields are ignored.
+ *
+ * Discovery reads the file by name, so this module parses from an in-memory
+ * string: it stays synchronous, dependency-light, and unit-testable, and the
+ * caller owns reading the bytes.
+ *
+ * @module @dsh-cc/claude-code-agents/parse
+ */
+import type { AgentDefinition, AgentSource } from './types.ts';
+/** A `frontmatter` split out of a raw markdown string. */
+export interface ParsedMarkdown {
+    /** The YAML metadata block, decoded; empty when the file had none. */
+    readonly frontmatter: Readonly<Record<string, unknown>>;
+    /** The markdown body after the closing `---`, without leading blank lines. */
+    readonly content: string;
+}
+/**
+ * Split the leading YAML frontmatter block out of a markdown string.
+ * A `---`-delimited block at the very start is metadata; anything else (no
+ * leading delimiter, or no closing one) means the whole text is body.
+ * @param text - the file's full markdown text.
+ * @returns the frontmatter record and the trailing body.
+ * @throws when the leading block is delimited but not valid YAML.
+ */
+export declare function splitFrontmatter(text: string): ParsedMarkdown;
+/**
+ * Parse one `.md` agent: the frontmatter supplies the fields and the markdown
+ * body (or the `prompt` override) supplies the system prompt.
+ * @param filePath - the agent file path; its basename becomes `agentType`.
+ * @param text - the full markdown text.
+ * @param source - the layer the file was discovered under.
+ * @returns the parsed, validated agent definition.
+ * @throws when required fields are missing or a known field has a bad value.
+ */
+export declare function parseAgentMarkdown(filePath: string, text: string, source: AgentSource): AgentDefinition;
+/**
+ * Parse one `.json` agent: a single object whose keys are frontmatter fields
+ * and whose optional `prompt` supplies the system prompt.
+ * @param filePath - the agent file path; its basename becomes `agentType`.
+ * @param text - the raw JSON text.
+ * @param source - the layer the file was discovered under.
+ * @returns the parsed, validated agent definition.
+ * @throws when JSON is malformed, required fields are missing, or a known field
+ *   has a bad value.
+ */
+export declare function parseAgentJson(filePath: string, text: string, source: AgentSource): AgentDefinition;
+//# sourceMappingURL=parse.d.ts.map

package/lib/parse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../src/parse.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAWH,OAAO,KAAK,EACV,eAAe,EACf,WAAW,EAEZ,MAAM,YAAY,CAAA;AAEnB,0DAA0D;AAC1D,MAAM,WAAW,cAAc;IAC7B,sEAAsE;IACtE,QAAQ,CAAC,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;IACvD,8EAA8E;IAC9E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,CAiB7D;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,eAAe,CAIvG;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,eAAe,CAcnG"}

package/lib/parse.js

@@ -0,0 +1,236 @@
+/**
+ * Parse one Claude Code agent file (`.md` frontmatter + markdown body, or
+ * `.json`) into an {@link AgentDefinition}. Every bad known-frontmatter value
+ * throws at load time with the file path and the field name, so a broken agent
+ * surfaces loud instead of silently degrading; unknown fields are ignored.
+ *
+ * Discovery reads the file by name, so this module parses from an in-memory
+ * string: it stays synchronous, dependency-light, and unit-testable, and the
+ * caller owns reading the bytes.
+ *
+ * @module @dsh-cc/claude-code-agents/parse
+ */
+import { load as loadYaml } from 'js-yaml';
+import { basename, dirname, extname } from 'node:path';
+import { normalizeModel, resolveToolRestriction } from "./restrict.js";
+import { EFFORT_LEVELS, ISOLATION_MODES, MEMORY_SCOPES, PERMISSION_MODES, } from "./types.js";
+/**
+ * Split the leading YAML frontmatter block out of a markdown string.
+ * A `---`-delimited block at the very start is metadata; anything else (no
+ * leading delimiter, or no closing one) means the whole text is body.
+ * @param text - the file's full markdown text.
+ * @returns the frontmatter record and the trailing body.
+ * @throws when the leading block is delimited but not valid YAML.
+ */
+export function splitFrontmatter(text) {
+    if (!text.startsWith('---'))
+        return { frontmatter: {}, content: text.trim() };
+    const end = text.indexOf('\n---', 3);
+    if (end === -1)
+        return { frontmatter: {}, content: text.trim() };
+    const raw = text.slice(3, end);
+    const content = text.slice(end + 4).replace(/^\s*\n/, '').trim();
+    let frontmatter;
+    try {
+        frontmatter = loadYaml(raw);
+    }
+    catch (error) {
+        throw new Error(`invalid YAML frontmatter: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (frontmatter === undefined)
+        return { frontmatter: {}, content };
+    if (typeof frontmatter !== 'object' || Array.isArray(frontmatter) || frontmatter === null) {
+        throw new Error('frontmatter must be a YAML object, not a scalar or list');
+    }
+    return { frontmatter: frontmatter, content };
+}
+/**
+ * Parse one `.md` agent: the frontmatter supplies the fields and the markdown
+ * body (or the `prompt` override) supplies the system prompt.
+ * @param filePath - the agent file path; its basename becomes `agentType`.
+ * @param text - the full markdown text.
+ * @param source - the layer the file was discovered under.
+ * @returns the parsed, validated agent definition.
+ * @throws when required fields are missing or a known field has a bad value.
+ */
+export function parseAgentMarkdown(filePath, text, source) {
+    const agentType = basename(filePath, '.md');
+    const { frontmatter, content } = splitFrontmatter(text);
+    return buildAgent(filePath, agentType, frontmatter, content, source);
+}
+/**
+ * Parse one `.json` agent: a single object whose keys are frontmatter fields
+ * and whose optional `prompt` supplies the system prompt.
+ * @param filePath - the agent file path; its basename becomes `agentType`.
+ * @param text - the raw JSON text.
+ * @param source - the layer the file was discovered under.
+ * @returns the parsed, validated agent definition.
+ * @throws when JSON is malformed, required fields are missing, or a known field
+ *   has a bad value.
+ */
+export function parseAgentJson(filePath, text, source) {
+    const agentType = basename(filePath, '.json');
+    let decoded;
+    try {
+        decoded = JSON.parse(text);
+    }
+    catch (error) {
+        throw new Error(`${filePath}: invalid JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (typeof decoded !== 'object' || decoded === null || Array.isArray(decoded)) {
+        throw new Error(`${filePath}: agent JSON must be an object`);
+    }
+    const frontmatter = decoded;
+    const content = requireString(filePath, 'prompt', frontmatter['prompt']);
+    return buildAgent(filePath, agentType, frontmatter, content, source, true);
+}
+/**
+ * Validate required metadata and translate the split frontmatter fields into
+ * one {@link AgentDefinition}. The `prompt` key is consumed as the prompt
+ * override for `.md` and forwarded through for `.json` via `fromJson`.
+ * @param filePath - origin path for errors and the fallback agent name.
+ * @param agentType - the resolved agent type name.
+ * @param frontmatter - the decoded frontmatter record.
+ * @param promptDefault - the markdown body (or the JSON `prompt`, pre-resolved).
+ * @param source - the discovery layer.
+ * @param promptIsOverride - whether `prompt` was taken from frontmatter.
+ * @returns the validated agent definition.
+ * @throws on missing description, missing prompt, or any bad known field.
+ */
+function buildAgent(filePath, agentType, frontmatter, promptDefault, source, promptIsOverride = false) {
+    const whenToUse = requireString(filePath, 'description', frontmatter['description']);
+    const display = frontmatter['name'];
+    if (display !== undefined && typeof display !== 'string') {
+        throw new Error(`${filePath}: name must be a string`);
+    }
+    const tools = optionalToolList(filePath, 'tools', frontmatter['tools']);
+    const disallowedTools = optionalToolList(filePath, 'disallowedTools', frontmatter['disallowedTools']);
+    const toolRestriction = resolveToolRestriction(tools, disallowedTools);
+    const model = normalizeModel(frontmatter['model']);
+    const effort = parseEffort(filePath, frontmatter['effort']);
+    const permissionMode = parseEnum(filePath, 'permissionMode', frontmatter['permissionMode'], PERMISSION_MODES);
+    const maxTurns = parsePositiveInt(filePath, 'maxTurns', frontmatter['maxTurns']);
+    const memory = parseEnum(filePath, 'memory', frontmatter['memory'], MEMORY_SCOPES);
+    const isolation = parseEnum(filePath, 'isolation', frontmatter['isolation'], ISOLATION_MODES);
+    const prompt = promptIsOverride ? undefined : optionalString(filePath, 'prompt', frontmatter['prompt']);
+    const initialPrompt = optionalString(filePath, 'initialPrompt', frontmatter['initialPrompt']);
+    const background = optionalBoolean(filePath, 'background', frontmatter['background']);
+    const systemPrompt = prompt ?? promptDefault;
+    const definition = {
+        agentType,
+        whenToUse,
+        systemPrompt,
+        source,
+        baseDir: dirname(filePath),
+        filename: basename(filePath, extname(filePath)),
+        ...toolRestriction !== undefined ? { toolRestriction } : {},
+    };
+    addOptional(definition, 'skills', optionalStringArray(filePath, 'skills', frontmatter['skills']));
+    addOptional(definition, 'mcpServers', optionalStringArray(filePath, 'mcpServers', frontmatter['mcpServers']));
+    addOptional(definition, 'hooks', optionalRecordArray(filePath, 'hooks', frontmatter['hooks']));
+    addOptional(definition, 'model', model);
+    addOptional(definition, 'effort', effort);
+    addOptional(definition, 'permissionMode', permissionMode);
+    addOptional(definition, 'maxTurns', maxTurns);
+    addOptional(definition, 'initialPrompt', initialPrompt);
+    addOptional(definition, 'background', background);
+    addOptional(definition, 'memory', memory);
+    addOptional(definition, 'isolation', isolation);
+    return definition;
+}
+/** Assign `value` onto `target[key]` unless it is undefined. */
+function addOptional(target, key, value) {
+    if (value !== undefined)
+        target[key] = value;
+}
+// ── field readers ───────────────────────────────────────────────────────────
+/** Read a required string field, throwing with the file path when absent. */
+function requireString(filePath, key, value) {
+    if (typeof value !== 'string' || value.trim().length === 0) {
+        throw new Error(`${filePath}: missing required "${key}" (a non-empty string)`);
+    }
+    return value;
+}
+/** Read an optional string field. */
+function optionalString(filePath, key, value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string' || value.trim().length === 0) {
+        throw new Error(`${filePath}: ${key} must be a non-empty string`);
+    }
+    return value;
+}
+/** Read an optional boolean field. */
+function optionalBoolean(filePath, key, value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'boolean') {
+        throw new Error(`${filePath}: ${key} must be a boolean`);
+    }
+    return value;
+}
+/** Read an optional array of strings. */
+function optionalStringArray(filePath, key, value) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value)) {
+        throw new Error(`${filePath}: ${key} must be an array of strings`);
+    }
+    for (const item of value) {
+        if (typeof item !== 'string') {
+            throw new Error(`${filePath}: ${key} must name strings, got ${String(item)}`);
+        }
+    }
+    return value;
+}
+/**
+ * Read an optional tool list: a comma-separated string (Claude Code's
+ * frontmatter shorthand, e.g. `tools: Bash, Read`) or an array of strings.
+ * String entries are split on commas and trimmed; empty entries are dropped.
+ */
+function optionalToolList(filePath, key, value) {
+    if (typeof value === 'string') {
+        return value.split(',').map(item => item.trim()).filter(item => item.length > 0);
+    }
+    return optionalStringArray(filePath, key, value);
+}
+/** Read an optional record of arbitrary values (hooks). */
+function optionalRecordArray(filePath, key, value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new Error(`${filePath}: ${key} must be an object`);
+    }
+    return value;
+}
+/** Read an optional positive integer (maxTurns). */
+function parsePositiveInt(filePath, key, value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'number' || !Number.isInteger(value) || value <= 0) {
+        throw new Error(`${filePath}: ${key} must be a positive integer`);
+    }
+    return value;
+}
+/** Read an optional effort: a named level or a positive integer. */
+function parseEffort(filePath, value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value === 'string' && EFFORT_LEVELS.includes(value)) {
+        return value;
+    }
+    if (typeof value === 'number' && Number.isInteger(value) && value > 0) {
+        return value;
+    }
+    throw new Error(`${filePath}: effort must be one of ${EFFORT_LEVELS.join(', ')} or a positive integer`);
+}
+/** Read an optional enum value from a closed tuple. */
+function parseEnum(filePath, key, value, allowed) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string' || !allowed.includes(value)) {
+        throw new Error(`${filePath}: ${key} must be one of ${allowed.join(', ')}`);
+    }
+    return value;
+}
+//# sourceMappingURL=parse.js.map

package/lib/parse.js.map

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

package/lib/restrict.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Effective tool restriction from Claude Code's `tools` allow-list and
+ * `disallowedTools` deny-list, and the `model: inherit` normalization.
+ *
+ * A Claude Code agent's `tools` narrows the visible global tool set while its
+ * `disallowedTools` removes specific members — including members the `tools`
+ * list names. In harness terms both compile to one scoped
+ * {@link ToolRestriction} (`allow` from `tools`, `deny` from
+ * `disallowedTools`) passed to a scoped `ctx.tools.restrict()`. Because
+ * restrictions INTERSECT with every sibling and inherited restriction, a name
+ * in both `allow` and `deny` is denied: the agent sees only tools its `allow`
+ * admits that no `deny` removes.
+ *
+ * Claude Code tool names are translated to harness tool names at this
+ * boundary via `translateToolNames`. The mapping is one-to-many (e.g. `Read`
+ * → `read` + `read_image`, so denying `Read` denies both). Unknown names pass
+ * through verbatim so `tools.restrict()` fails loudly at agent-load time with
+ * its own clear error rather than silently dropping a typo.
+ *
+ * @module @dsh-cc/claude-code-agents/restrict
+ */
+import type { ToolRestriction } from './types.ts';
+/**
+ * Combine a sorted unique tool allow/deny pair into one effective restriction.
+ * `deny` wins over `allow` when a name appears in both (restrictions
+ * intersect). Omission of both yields no restriction (`undefined`).
+ * @param tools - the `tools`/`disallowedTools` normalize root this came from.
+ *   Absent when neither key was declared.
+ * @returns the effective restriction, or `undefined` when neither key existed.
+ * @throws when `tools` or `disallowedTools` held an element that is not a string.
+ */
+export declare function resolveToolRestriction(tools: readonly string[] | undefined, disallowedTools: readonly string[] | undefined): ToolRestriction | undefined;
+/**
+ * Normalize a `model` frontmatter value: trim it and lowercase the sentinel so
+ * `Inherit`, `INHERIT`, and `inherit` all mean the same thing, exactly as
+ * Claude Code does.
+ * @param model - the raw `model` value, or `undefined`.
+ * @returns the normalized model, or `undefined` when absent or blank.
+ * @throws when `model` is present but not a string.
+ */
+export declare function normalizeModel(model: unknown): string | undefined;
+//# sourceMappingURL=restrict.d.ts.map

package/lib/restrict.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"restrict.d.ts","sourceRoot":"","sources":["../src/restrict.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEjD;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,EACpC,eAAe,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,GAC7C,eAAe,GAAG,SAAS,CAU7B;AAkBD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAOjE"}

package/lib/restrict.js

@@ -0,0 +1,78 @@
+/**
+ * Effective tool restriction from Claude Code's `tools` allow-list and
+ * `disallowedTools` deny-list, and the `model: inherit` normalization.
+ *
+ * A Claude Code agent's `tools` narrows the visible global tool set while its
+ * `disallowedTools` removes specific members — including members the `tools`
+ * list names. In harness terms both compile to one scoped
+ * {@link ToolRestriction} (`allow` from `tools`, `deny` from
+ * `disallowedTools`) passed to a scoped `ctx.tools.restrict()`. Because
+ * restrictions INTERSECT with every sibling and inherited restriction, a name
+ * in both `allow` and `deny` is denied: the agent sees only tools its `allow`
+ * admits that no `deny` removes.
+ *
+ * Claude Code tool names are translated to harness tool names at this
+ * boundary via `translateToolNames`. The mapping is one-to-many (e.g. `Read`
+ * → `read` + `read_image`, so denying `Read` denies both). Unknown names pass
+ * through verbatim so `tools.restrict()` fails loudly at agent-load time with
+ * its own clear error rather than silently dropping a typo.
+ *
+ * @module @dsh-cc/claude-code-agents/restrict
+ */
+import { translateToolNames } from '@dsh-cc/tools';
+/**
+ * Combine a sorted unique tool allow/deny pair into one effective restriction.
+ * `deny` wins over `allow` when a name appears in both (restrictions
+ * intersect). Omission of both yields no restriction (`undefined`).
+ * @param tools - the `tools`/`disallowedTools` normalize root this came from.
+ *   Absent when neither key was declared.
+ * @returns the effective restriction, or `undefined` when neither key existed.
+ * @throws when `tools` or `disallowedTools` held an element that is not a string.
+ */
+export function resolveToolRestriction(tools, disallowedTools) {
+    if (tools === undefined && disallowedTools === undefined)
+        return undefined;
+    if (tools !== undefined)
+        assertStringArray(tools, 'tools');
+    if (disallowedTools !== undefined)
+        assertStringArray(disallowedTools, 'disallowedTools');
+    const allow = tools !== undefined ? translateToolNames(tools, 'strict') : undefined;
+    const deny = disallowedTools !== undefined ? translateToolNames(disallowedTools, 'strict') : undefined;
+    return {
+        ...allow !== undefined ? { allow } : {},
+        ...deny !== undefined ? { deny } : {},
+    };
+}
+/**
+ * Assert a tool name array is non-empty when present, so an agent that claims
+ * a restriction actually names one — a materialized-empty config almost always
+ * hides an authoring mistake, and an empty split-set equals no restriction.
+ * @param names - the array to validate.
+ * @param key - the frontmatter key the array came from, for the error.
+ * @throws when the array holds a non-string element.
+ */
+function assertStringArray(names, key) {
+    for (const name of names) {
+        if (typeof name !== 'string') {
+            throw new Error(`${key} must name tools as strings, got ${String(name)}`);
+        }
+    }
+}
+/**
+ * Normalize a `model` frontmatter value: trim it and lowercase the sentinel so
+ * `Inherit`, `INHERIT`, and `inherit` all mean the same thing, exactly as
+ * Claude Code does.
+ * @param model - the raw `model` value, or `undefined`.
+ * @returns the normalized model, or `undefined` when absent or blank.
+ * @throws when `model` is present but not a string.
+ */
+export function normalizeModel(model) {
+    if (model === undefined)
+        return undefined;
+    if (typeof model !== 'string' || model.trim().length === 0) {
+        throw new Error('model must be a non-empty string');
+    }
+    const trimmed = model.trim();
+    return trimmed.toLowerCase() === 'inherit' ? 'inherit' : trimmed;
+}
+//# sourceMappingURL=restrict.js.map

package/lib/restrict.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"restrict.js","sourceRoot":"","sources":["../src/restrict.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAA;AAGlD;;;;;;;;GAQG;AACH,MAAM,UAAU,sBAAsB,CACpC,KAAoC,EACpC,eAA8C;IAE9C,IAAI,KAAK,KAAK,SAAS,IAAI,eAAe,KAAK,SAAS;QAAE,OAAO,SAAS,CAAA;IAC1E,IAAI,KAAK,KAAK,SAAS;QAAE,iBAAiB,CAAC,KAAK,EAAE,OAAO,CAAC,CAAA;IAC1D,IAAI,eAAe,KAAK,SAAS;QAAE,iBAAiB,CAAC,eAAe,EAAE,iBAAiB,CAAC,CAAA;IACxF,MAAM,KAAK,GAAG,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,kBAAkB,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,SAAS,CAAA;IACnF,MAAM,IAAI,GAAG,eAAe,KAAK,SAAS,CAAC,CAAC,CAAC,kBAAkB,CAAC,eAAe,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,SAAS,CAAA;IACtG,OAAO;QACL,GAAG,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE;QACvC,GAAG,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE;KACtC,CAAA;AACH,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,iBAAiB,CAAC,KAAwB,EAAE,GAAW;IAC9D,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC7B,MAAM,IAAI,KAAK,CAAC,GAAG,GAAG,oCAAoC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;QAC3E,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAC,KAAc;IAC3C,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,SAAS,CAAA;IACzC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC3D,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAA;IACrD,CAAC;IACD,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAA;IAC5B,OAAO,OAAO,CAAC,WAAW,EAAE,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAA;AAClE,CAAC"}