@open-agent-toolkit/cli 0.3.1 → 0.3.2

package/dist/providers/ceiling/registry.js

@@ -1,6 +1,7 @@
 import { VALID_CLAUDE_DISPATCH_CEILINGS, VALID_CODEX_DISPATCH_CEILINGS, } from '../../config/oat-config.js';
 import { getOwnKey } from '../../config/own-keys.js';
-import { buildCodexMaterializedTargetRoleName } from '../codex/codec/shared.js';
+import { buildClaudeEffortVariantName, CLAUDE_MODEL_ORDER, validateClaudeDispatchCapability, } from '../claude/targets.js';
+import { buildCodexMaterializedTargetRoleName, SUPPORTED_CODEX_ROLE_TARGETS, } from '../codex/codec/shared.js';
 import { findCursorModelPinMapping } from '../cursor/codec/catalog.js';
 import { buildCursorMaterializedRoleName } from '../cursor/codec/shared.js';
 const DIRECT_DISPATCH_ROLE_PATTERN = /^oat-(?:phase-implementer|reviewer)(?:-|$)/;
@@ -11,12 +12,7 @@ export function isDirectDispatchRoleName(value) {
 const CODEX_IMPLEMENTER_ROLE = 'oat-phase-implementer';
 const CODEX_REVIEWER_ROLE = 'oat-reviewer';
 /** Claude tier order, low → high, for above-orchestrator comparison. */
-export const CLAUDE_TIER_ORDER = [
-    'haiku',
-    'sonnet',
-    'opus',
-    'fable',
-];
+export const CLAUDE_TIER_ORDER = [...CLAUDE_MODEL_ORDER];
 const codexAdapter = {
     provider: 'codex',
     supportsCeiling: true,
@@ -24,7 +20,10 @@ const codexAdapter = {
     mechanism: 'pinned-variant',
     selectionAxis: 'model-effort',
     compileToDispatchArgs(value, role, ctx) {
-        if (!VALID_CODEX_DISPATCH_CEILINGS.includes(value)) {
+        if (!VALID_CODEX_DISPATCH_CEILINGS.includes(value) &&
+            !SUPPORTED_CODEX_ROLE_TARGETS.some((candidate) => candidate.model === ctx.target?.model &&
+                candidate.effort === value &&
+                ctx.target?.effort === value)) {
             return null;
         }
         const target = ctx.target;
@@ -65,12 +64,37 @@ const claudeAdapter = {
     validValues: [...VALID_CLAUDE_DISPATCH_CEILINGS],
     mechanism: 'model-arg',
     selectionAxis: 'tier',
-    compileToDispatchArgs(value) {
-        if (isDirectDispatchRoleName(value) ||
+    compileToDispatchArgs(value, role, ctx) {
+        if (isDirectDispatchRoleName(value))
+            return null;
+        const target = ctx.target;
+        if (target?.effort) {
+            const model = target.model ?? value;
+            if (!validateClaudeDispatchCapability({
+                model,
+                effort: target.effort,
+                ...(target.capabilityEvidence
+                    ? { capabilityEvidence: target.capabilityEvidence }
+                    : {}),
+            }, ctx.env).valid) {
+                return null;
+            }
+            return {
+                variant: buildClaudeEffortVariantName({
+                    agentName: role === 'reviewer' ? CODEX_REVIEWER_ROLE : CODEX_IMPLEMENTER_ROLE,
+                    model,
+                    effort: target.effort,
+                }),
+            };
+        }
+        const model = target?.model ?? value;
+        if (!target?.model &&
             !VALID_CLAUDE_DISPATCH_CEILINGS.includes(value)) {
             return null;
         }
-        return { model: value };
+        if (!validateClaudeDispatchCapability({ model }).valid)
+            return null;
+        return { model };
     },
     // Verify only when the request is above the orchestrator tier (upgrade path).
     verifyOnDispatch(value, ctx) {

package/dist/providers/claude/codec/materialize.d.ts

@@ -0,0 +1,33 @@
+import type { CanonicalAgentDocument } from '../../../agents/canonical/index.js';
+import { type ClaudeCapabilityEvidence } from '../targets.js';
+export type ClaudeRoleOwner = 'user-config' | 'project-config';
+export interface ClaudeMaterializationTarget {
+    model: string;
+    effort: string;
+    capabilityEvidence?: ClaudeCapabilityEvidence;
+    owner: ClaudeRoleOwner;
+}
+export interface ClaudeMaterializedAgent {
+    roleName: string;
+    fileName: string;
+    content: string;
+    owner: ClaudeRoleOwner;
+    target: ClaudeMaterializationTarget;
+}
+export declare function readOatManagedClaudeRole(content: string): {
+    roleName: string;
+    owner: ClaudeRoleOwner;
+    capabilityEvidence?: ClaudeCapabilityEvidence;
+} | null;
+export declare function materializeClaudeAgent(options: {
+    agent: CanonicalAgentDocument;
+    target: ClaudeMaterializationTarget;
+    env?: NodeJS.ProcessEnv;
+}): ClaudeMaterializedAgent;
+export declare function materializeClaudeAgents(options: {
+    agents: CanonicalAgentDocument[];
+    targets: ClaudeMaterializationTarget[];
+    env?: NodeJS.ProcessEnv;
+}): ClaudeMaterializedAgent[];
+export declare function assertNoUnmanagedClaudeAgentCollisions(scopeRoot: string, desiredNames: Iterable<string>): Promise<void>;
+//# sourceMappingURL=materialize.d.ts.map

package/dist/providers/claude/codec/materialize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"materialize.d.ts","sourceRoot":"","sources":["../../../../src/providers/claude/codec/materialize.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAIhE,OAAO,EAGL,KAAK,wBAAwB,EAE9B,MAAM,YAAY,CAAC;AAEpB,MAAM,MAAM,eAAe,GAAG,aAAa,GAAG,gBAAgB,CAAC;AAE/D,MAAM,WAAW,2BAA2B;IAC1C,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,kBAAkB,CAAC,EAAE,wBAAwB,CAAC;IAC9C,KAAK,EAAE,eAAe,CAAC;CACxB;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,eAAe,CAAC;IACvB,MAAM,EAAE,2BAA2B,CAAC;CACrC;AAqCD,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,GAAG;IACzD,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,eAAe,CAAC;IACvB,kBAAkB,CAAC,EAAE,wBAAwB,CAAC;CAC/C,GAAG,IAAI,CA8BP;AAED,wBAAgB,sBAAsB,CAAC,OAAO,EAAE;IAC9C,KAAK,EAAE,sBAAsB,CAAC;IAC9B,MAAM,EAAE,2BAA2B,CAAC;IACpC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACzB,GAAG,uBAAuB,CAmC1B;AAED,wBAAgB,uBAAuB,CAAC,OAAO,EAAE;IAC/C,MAAM,EAAE,sBAAsB,EAAE,CAAC;IACjC,OAAO,EAAE,2BAA2B,EAAE,CAAC;IACvC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACzB,GAAG,uBAAuB,EAAE,CAkB5B;AAWD,wBAAsB,sCAAsC,CAC1D,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,GAC7B,OAAO,CAAC,IAAI,CAAC,CAkDf"}

package/dist/providers/claude/codec/materialize.js

@@ -0,0 +1,149 @@
+import { lstat, readFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { CliError } from '../../../errors/index.js';
+import YAML from 'yaml';
+import { buildClaudeEffortVariantName, normalizeClaudeRoleName, validateClaudeDispatchCapability, } from '../targets.js';
+const DISCOVERY_DIRECTORIES = [
+    { path: '.claude/agents', extension: '.md' },
+    { path: '.cursor/agents', extension: '.md' },
+    { path: '.codex/agents', extension: '.toml' },
+];
+function managedComments(roleName, owner, capabilityEvidence) {
+    return [
+        '# oat-managed: true',
+        `# oat-role: ${roleName}`,
+        `# oat-owner: ${owner}`,
+        '# oat-provider: claude',
+        `# oat-capability-evidence: ${JSON.stringify(capabilityEvidence)}`,
+    ];
+}
+function frontmatter(content) {
+    const match = /^---\n([\s\S]*?)\n---(?:\n|$)/.exec(content);
+    if (!match?.[1])
+        return null;
+    try {
+        const value = YAML.parse(match[1]);
+        return value && typeof value === 'object' && !Array.isArray(value)
+            ? { yaml: match[1], value: value }
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function readOatManagedClaudeRole(content) {
+    const parsed = frontmatter(content);
+    if (!parsed)
+        return null;
+    const managed = parsed.yaml.match(/^# oat-managed: true$/gm)?.length === 1;
+    const provider = parsed.yaml.match(/^# oat-provider: claude$/gm)?.length === 1;
+    const role = /^# oat-role: ([a-z0-9]+(?:-[a-z0-9]+)*)$/m.exec(parsed.yaml)?.[1];
+    const owner = /^# oat-owner: (user-config|project-config)$/m.exec(parsed.yaml)?.[1];
+    const evidenceJson = /^# oat-capability-evidence: (\{.+\})$/m.exec(parsed.yaml)?.[1];
+    let capabilityEvidence;
+    if (evidenceJson) {
+        try {
+            capabilityEvidence = JSON.parse(evidenceJson);
+        }
+        catch {
+            // Malformed evidence makes the role stale but does not hide its ownership.
+        }
+    }
+    return managed && provider && role && owner
+        ? {
+            roleName: role,
+            owner,
+            ...(capabilityEvidence ? { capabilityEvidence } : {}),
+        }
+        : null;
+}
+export function materializeClaudeAgent(options) {
+    const validation = validateClaudeDispatchCapability(options.target, options.env);
+    if (!validation.valid)
+        throw new CliError(validation.reason ?? 'Invalid Claude target.');
+    const capabilityEvidence = validation.capabilityEvidence;
+    if (!capabilityEvidence) {
+        throw new CliError('Claude effort target has no validated capability evidence.');
+    }
+    const roleName = buildClaudeEffortVariantName({
+        agentName: options.agent.name,
+        model: options.target.model,
+        effort: options.target.effort,
+    });
+    const description = `${options.agent.description} Claude-native ${options.target.model}/${options.target.effort} effort variant managed by OAT.`;
+    const rendered = YAML.stringify({
+        name: roleName,
+        description,
+        model: options.target.model,
+        effort: options.target.effort,
+        ...(options.agent.tools !== undefined
+            ? { tools: options.agent.tools }
+            : {}),
+    }).trimEnd();
+    return {
+        roleName,
+        fileName: `${roleName}.md`,
+        content: `---\n${managedComments(roleName, options.target.owner, capabilityEvidence).join('\n')}\n${rendered}\n---\n${options.agent.body}`,
+        owner: options.target.owner,
+        target: { ...options.target, capabilityEvidence },
+    };
+}
+export function materializeClaudeAgents(options) {
+    const roles = options.agents.flatMap((agent) => options.targets.map((target) => materializeClaudeAgent({ agent, target, env: options.env })));
+    const names = new Set();
+    for (const role of roles) {
+        if (names.has(role.roleName)) {
+            throw new CliError(`Distinct Claude targets produced the same normalized role name ${role.roleName}. Refusing ambiguous role writes.`);
+        }
+        names.add(role.roleName);
+    }
+    return roles.sort((left, right) => left.roleName.localeCompare(right.roleName));
+}
+async function pathStats(path) {
+    try {
+        return await lstat(path);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+}
+export async function assertNoUnmanagedClaudeAgentCollisions(scopeRoot, desiredNames) {
+    const desired = new Set(desiredNames);
+    for (const { path: directory, extension } of DISCOVERY_DIRECTORIES) {
+        const absoluteDirectory = join(scopeRoot, directory);
+        const stats = await pathStats(absoluteDirectory);
+        if (!stats)
+            continue;
+        if (!stats.isDirectory() || stats.isSymbolicLink()) {
+            throw new CliError(`Claude agent discovery path is unsafe: ${directory}.`);
+        }
+        for (const fileName of await readdir(absoluteDirectory)) {
+            if (!fileName.endsWith(extension))
+                continue;
+            const path = join(absoluteDirectory, fileName);
+            const fileStats = await pathStats(path);
+            if (!fileStats?.isFile() || fileStats.isSymbolicLink()) {
+                if (desired.has(normalizeClaudeRoleName(fileName.slice(0, -extension.length)))) {
+                    throw new CliError(`Claude role collision at ${directory}/${fileName}: symbolic links are not writable targets.`);
+                }
+                continue;
+            }
+            const content = await readFile(path, 'utf8');
+            const parsed = extension === '.md' ? frontmatter(content) : null;
+            const declared = typeof parsed?.value.name === 'string'
+                ? normalizeClaudeRoleName(parsed.value.name)
+                : null;
+            const fileRole = normalizeClaudeRoleName(fileName.slice(0, -extension.length));
+            if (!desired.has(fileRole) && (!declared || !desired.has(declared)))
+                continue;
+            const managed = readOatManagedClaudeRole(content);
+            if (directory !== '.claude/agents' ||
+                !managed ||
+                !desired.has(managed.roleName)) {
+                throw new CliError(`Claude role name collision at ${directory}/${fileName}: existing definition is not the matching OAT-managed Claude variant.`);
+            }
+        }
+    }
+}

package/dist/providers/claude/codec/sync-extension.d.ts

@@ -0,0 +1,24 @@
+import { type CanonicalEntry } from '../../../engine/index.js';
+import { type MaterializationApplyResult, type MaterializationContext, type MaterializationExtension, type MaterializationOperation, type MaterializationPlan, type MaterializationWriteOperation } from '../../shared/index.js';
+import { type ClaudeRoleOwner } from './materialize.js';
+export interface ClaudeMaterializationTargetOptions {
+    userConfigDir?: string;
+    projectPath?: string | null;
+    env?: NodeJS.ProcessEnv;
+    enabled?: boolean;
+}
+export interface ClaudeExtensionPlan extends MaterializationPlan<'claude', 'role', {
+    cleanupOwners: ClaudeRoleOwner[];
+    isPartialSync: boolean;
+}> {
+    operations: (MaterializationWriteOperation<'claude', 'role'> & {
+        roleName?: string;
+    })[];
+}
+export declare function computeClaudeProjectExtensionPlan(scopeRoot: string, canonicalEntries: CanonicalEntry[], allowedCanonicalPaths?: string[], options?: ClaudeMaterializationTargetOptions): Promise<ClaudeExtensionPlan>;
+export declare function applyClaudeProjectExtensionPlan(scopeRoot: string, plan: ClaudeExtensionPlan): Promise<MaterializationApplyResult>;
+export declare function hasClaudeExtensionChanges(plan: ClaudeExtensionPlan): boolean;
+export declare function summarizeClaudeExtension(plan: ClaudeExtensionPlan): import("../../shared/index.js").MaterializationPlanSummary;
+export declare function toClaudeExtensionOperations(plan: ClaudeExtensionPlan): MaterializationOperation[];
+export declare const claudeMaterializationExtension: MaterializationExtension<ClaudeExtensionPlan, MaterializationContext<ClaudeMaterializationTargetOptions>>;
+//# sourceMappingURL=sync-extension.d.ts.map

package/dist/providers/claude/codec/sync-extension.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-extension.d.ts","sourceRoot":"","sources":["../../../../src/providers/claude/codec/sync-extension.ts"],"names":[],"mappings":"AAYA,OAAO,EAEL,KAAK,cAAc,EACpB,MAAM,eAAe,CAAC;AAIvB,OAAO,EAIL,KAAK,0BAA0B,EAC/B,KAAK,sBAAsB,EAC3B,KAAK,wBAAwB,EAC7B,KAAK,wBAAwB,EAC7B,KAAK,mBAAmB,EACxB,KAAK,6BAA6B,EACnC,MAAM,mBAAmB,CAAC;AAI3B,OAAO,EAKL,KAAK,eAAe,EACrB,MAAM,eAAe,CAAC;AAKvB,MAAM,WAAW,kCAAkC;IACjD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,mBAAoB,SAAQ,mBAAmB,CAC9D,QAAQ,EACR,MAAM,EACN;IAAE,aAAa,EAAE,eAAe,EAAE,CAAC;IAAC,aAAa,EAAE,OAAO,CAAA;CAAE,CAC7D;IACC,UAAU,EAAE,CAAC,6BAA6B,CAAC,QAAQ,EAAE,MAAM,CAAC,GAAG;QAC7D,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC,EAAE,CAAC;CACN;AAwLD,wBAAsB,iCAAiC,CACrD,SAAS,EAAE,MAAM,EACjB,gBAAgB,EAAE,cAAc,EAAE,EAClC,qBAAqB,CAAC,EAAE,MAAM,EAAE,EAChC,OAAO,GAAE,kCAAuC,GAC/C,OAAO,CAAC,mBAAmB,CAAC,CAgH9B;AAyCD,wBAAsB,+BAA+B,CACnD,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,mBAAmB,GACxB,OAAO,CAAC,0BAA0B,CAAC,CA+BrC;AAED,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAE5E;AAED,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,mBAAmB,0DAEjE;AAED,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,mBAAmB,GACxB,wBAAwB,EAAE,CAE5B;AAED,eAAO,MAAM,8BAA8B,EAAE,wBAAwB,CACnE,mBAAmB,EACnB,sBAAsB,CAAC,kCAAkC,CAAC,CAY3D,CAAC"}

package/dist/providers/claude/codec/sync-extension.js

@@ -0,0 +1,312 @@
+import { createHash } from 'node:crypto';
+import { lstat, readFile, readdir, rm, writeFile } from 'node:fs/promises';
+import { basename, dirname, join, relative, resolve, sep } from 'node:path';
+import { parseCanonicalAgentFile } from '../../../agents/canonical/index.js';
+import { normalizeDispatchMatrix, walkDispatchMatrix, } from '../../../config/dispatch-matrix.js';
+import { normalizeProjectPath, resolveActiveProject } from '../../../config/oat-config.js';
+import { resolveEffectiveConfig } from '../../../config/resolve.js';
+import { materializationCanonicalPathAllowed, } from '../../../engine/index.js';
+import { CliError } from '../../../errors/index.js';
+import { ensureDir, fileExists } from '../../../fs/io.js';
+import { validateRealPathWithinScope } from '../../../fs/paths.js';
+import { hasMaterializationChanges, summarizeMaterializationPlan, toMaterializationOperations, } from '../../shared/index.js';
+import YAML from 'yaml';
+import { assertNoUnmanagedClaudeAgentCollisions, materializeClaudeAgents, readOatManagedClaudeRole, } from './materialize.js';
+const SUPPORTED_BASE_ROLES = ['oat-phase-implementer', 'oat-reviewer'];
+function hash(content) {
+    return createHash('sha256').update(content).digest('hex');
+}
+function isUserScope(scopeRoot, options) {
+    return Boolean(options.userConfigDir &&
+        resolve(scopeRoot) === resolve(options.userConfigDir, '..'));
+}
+function collectTargets(value, owner, targets) {
+    if (value === undefined || typeof value === 'string')
+        return;
+    for (const ref of walkDispatchMatrix({ claude: value }, {
+        source: owner === 'user-config' ? 'user-config' : 'repo-config',
+        pathPrefix: 'workflow.dispatchCeiling.providers',
+    })) {
+        const target = ref.target;
+        if (!target?.model ||
+            !target.effort ||
+            (target.harness ?? 'claude') !== 'claude') {
+            continue;
+        }
+        targets.set(`${target.model}\0${target.effort}`, {
+            model: target.model,
+            effort: target.effort,
+            owner,
+        });
+    }
+}
+function frontmatter(content) {
+    const match = /^---\n([\s\S]*?)\n---(?:\n|$)/.exec(content);
+    if (!match?.[1])
+        return null;
+    const parsed = YAML.parse(match[1]);
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+        ? parsed
+        : null;
+}
+async function collectProjectStateTargets(scopeRoot, options, targets) {
+    const candidate = options.projectPath === undefined
+        ? (await resolveActiveProject(scopeRoot)).path
+        : options.projectPath;
+    if (!candidate)
+        return;
+    const normalized = normalizeProjectPath(scopeRoot, candidate);
+    if (!normalized)
+        return;
+    let projectRoot;
+    try {
+        projectRoot = (await validateRealPathWithinScope(join(scopeRoot, normalized), scopeRoot)).realPath;
+    }
+    catch {
+        return;
+    }
+    const statePath = join(projectRoot, 'state.md');
+    if (!(await fileExists(statePath)))
+        return;
+    const parsed = frontmatter(await readFile(statePath, 'utf8'));
+    const policy = parsed?.['oat_dispatch_policy'];
+    if (!policy || typeof policy !== 'object' || Array.isArray(policy))
+        return;
+    const matrix = normalizeDispatchMatrix(policy['matrix'], {
+        pathPrefix: 'oat_dispatch_policy.matrix',
+        compatibilityMode: 'project-state',
+    });
+    collectTargets(matrix.providers.claude, 'project-config', targets);
+}
+async function readTargets(scopeRoot, options) {
+    const config = await resolveEffectiveConfig(scopeRoot, options.userConfigDir ?? join(scopeRoot, '.oat', '__no-user-config__'), options.env);
+    const targets = new Map();
+    if (isUserScope(scopeRoot, options)) {
+        collectTargets(config.user.workflow?.dispatchCeiling?.providers?.claude, 'user-config', targets);
+    }
+    else {
+        collectTargets(config.shared.workflow?.dispatchCeiling?.providers?.claude, 'project-config', targets);
+        collectTargets(config.local.workflow?.dispatchCeiling?.providers?.claude, 'project-config', targets);
+        await collectProjectStateTargets(scopeRoot, options, targets);
+    }
+    return [...targets.values()].sort((left, right) => `${left.model}/${left.effort}`.localeCompare(`${right.model}/${right.effort}`));
+}
+async function optionalFile(path) {
+    return (await fileExists(path)) ? readFile(path, 'utf8') : null;
+}
+async function staleRoles(scopeRoot, desired, owners, baseRoles) {
+    let files = [];
+    try {
+        files = await readdir(join(scopeRoot, '.claude', 'agents'));
+    }
+    catch {
+        // The managed directory does not exist before the first materialization.
+    }
+    const stale = [];
+    for (const file of files) {
+        if (!file.endsWith('.md'))
+            continue;
+        const roleName = basename(file, '.md');
+        if (desired.has(roleName))
+            continue;
+        const content = await optionalFile(join(scopeRoot, '.claude', 'agents', file));
+        const managed = content ? readOatManagedClaudeRole(content) : null;
+        const matchesBaseRole = !baseRoles ||
+            [...baseRoles].some((baseRole) => roleName.startsWith(`${baseRole}-claude-`));
+        if (matchesBaseRole &&
+            managed?.roleName === roleName &&
+            owners.includes(managed.owner))
+            stale.push(roleName);
+    }
+    return stale.sort();
+}
+function removedSupportedBaseRoles(entries, allowedCanonicalPaths) {
+    if (!allowedCanonicalPaths?.length)
+        return new Set();
+    const present = new Set(entries
+        .filter((entry) => entry.type === 'agent' && entry.isFile)
+        .map((entry) => entry.name.replace(/\.md$/, '')));
+    return new Set(SUPPORTED_BASE_ROLES.filter((role) => allowedCanonicalPaths.includes(`.agents/agents/${role}.md`) &&
+        !present.has(role)));
+}
+export async function computeClaudeProjectExtensionPlan(scopeRoot, canonicalEntries, allowedCanonicalPaths, options = {}) {
+    const partial = Boolean(allowedCanonicalPaths?.length);
+    const cleanupOwners = isUserScope(scopeRoot, options)
+        ? ['user-config']
+        : ['project-config'];
+    const empty = () => ({
+        provider: 'claude',
+        operations: [],
+        managedEntries: [],
+        aggregateHash: hash(''),
+        metadata: { cleanupOwners, isPartialSync: partial },
+    });
+    if (options.enabled === false)
+        return empty();
+    const entries = canonicalEntries.filter((entry) => materializationCanonicalPathAllowed(scopeRoot, entry, allowedCanonicalPaths));
+    const removedBaseRoles = removedSupportedBaseRoles(entries, allowedCanonicalPaths);
+    if (partial && entries.length === 0 && removedBaseRoles.size === 0)
+        return empty();
+    const targets = await readTargets(scopeRoot, options);
+    const agents = [];
+    for (const entry of entries) {
+        if (entry.type !== 'agent' || !entry.isFile || !entry.name.endsWith('.md'))
+            continue;
+        const agent = await parseCanonicalAgentFile(entry.canonicalPath);
+        if (SUPPORTED_BASE_ROLES.includes(agent.name))
+            agents.push(agent);
+    }
+    if (!partial && isUserScope(scopeRoot, options) && targets.length > 0) {
+        const present = new Set(agents.map(({ name }) => name));
+        const missing = SUPPORTED_BASE_ROLES.filter((name) => !present.has(name));
+        if (missing.length > 0) {
+            throw new CliError(`Bundled managed Claude role definitions are unavailable for user sync: ${missing.join(', ')}. Refusing stale user-role cleanup.`);
+        }
+    }
+    const roles = materializeClaudeAgents({
+        agents,
+        targets,
+        env: options.env,
+    });
+    const desired = new Set(roles.map(({ roleName }) => roleName));
+    await assertNoUnmanagedClaudeAgentCollisions(scopeRoot, desired);
+    const stale = partial
+        ? await staleRoles(scopeRoot, desired, cleanupOwners, removedBaseRoles)
+        : await staleRoles(scopeRoot, desired, cleanupOwners);
+    const operations = [];
+    for (const role of roles) {
+        const relativePath = `.claude/agents/${role.fileName}`;
+        const existing = await optionalFile(join(scopeRoot, relativePath));
+        if (existing === null) {
+            operations.push({
+                provider: 'claude',
+                action: 'create',
+                target: 'role',
+                path: relativePath,
+                reason: 'managed Claude effort variant missing',
+                entryName: role.roleName,
+                roleName: role.roleName,
+                content: role.content,
+            });
+            continue;
+        }
+        const managed = readOatManagedClaudeRole(existing);
+        if (!managed ||
+            managed.roleName !== role.roleName ||
+            !cleanupOwners.includes(managed.owner)) {
+            throw new CliError(`Refusing to update Claude role ${role.roleName}: existing file is unmanaged or has incompatible ownership.`);
+        }
+        const current = existing.trimEnd() === role.content.trimEnd();
+        operations.push({
+            provider: 'claude',
+            action: current ? 'skip' : 'update',
+            target: 'role',
+            path: relativePath,
+            reason: current
+                ? 'managed Claude effort variant already in sync'
+                : 'managed Claude effort variant differs from desired state',
+            entryName: role.roleName,
+            roleName: role.roleName,
+            ...(current ? {} : { content: role.content }),
+        });
+    }
+    for (const roleName of stale) {
+        operations.push({
+            provider: 'claude',
+            action: 'remove',
+            target: 'role',
+            path: `.claude/agents/${roleName}.md`,
+            reason: 'stale managed Claude effort variant removed',
+            entryName: roleName,
+            roleName,
+        });
+    }
+    return {
+        provider: 'claude',
+        operations,
+        managedEntries: [...desired, ...stale],
+        aggregateHash: hash(roles.map(({ content }) => content).join('\0')),
+        metadata: { cleanupOwners, isPartialSync: partial },
+    };
+}
+async function stats(path) {
+    try {
+        return await lstat(path);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+}
+async function assertSafePath(scopeRoot, path) {
+    const root = resolve(scopeRoot);
+    const rel = relative(root, path);
+    if (rel === '..' ||
+        rel.startsWith(`..${sep}`) ||
+        resolve(root, rel) !== path) {
+        throw new CliError(`Claude materialization path escapes the sync scope: ${path}`);
+    }
+    let current = root;
+    for (const part of rel.replaceAll('\\', '/').split('/').slice(0, -1)) {
+        current = join(current, part);
+        const value = await stats(current);
+        if (!value)
+            break;
+        if (value.isSymbolicLink() || !value.isDirectory()) {
+            throw new CliError(`Claude materialization parent is unsafe: ${relative(root, current)}`);
+        }
+    }
+    if ((await stats(path))?.isSymbolicLink()) {
+        throw new CliError(`Claude materialization target is a symbolic link: ${rel}`);
+    }
+}
+export async function applyClaudeProjectExtensionPlan(scopeRoot, plan) {
+    const operations = [];
+    for (const operation of plan.operations) {
+        if (operation.action === 'skip') {
+            operations.push({ ...operation, status: 'current' });
+            continue;
+        }
+        const path = resolve(scopeRoot, operation.path);
+        try {
+            await assertSafePath(scopeRoot, path);
+            if (operation.action === 'remove')
+                await rm(path, { force: true });
+            else {
+                await ensureDir(dirname(path));
+                await writeFile(path, operation.content ?? '', 'utf8');
+            }
+            operations.push({ ...operation, status: 'changed' });
+        }
+        catch {
+            operations.push({
+                ...operation,
+                status: 'failed',
+                failure: 'Materialization failed; inspect local verbose diagnostics and retry sync.',
+            });
+        }
+    }
+    return {
+        applied: operations.filter(({ status }) => status === 'changed').length,
+        failed: operations.filter(({ status }) => status === 'failed').length,
+        skipped: operations.filter(({ status }) => status === 'current').length,
+        operations,
+    };
+}
+export function hasClaudeExtensionChanges(plan) {
+    return hasMaterializationChanges(plan);
+}
+export function summarizeClaudeExtension(plan) {
+    return summarizeMaterializationPlan(plan);
+}
+export function toClaudeExtensionOperations(plan) {
+    return toMaterializationOperations(plan);
+}
+export const claudeMaterializationExtension = {
+    provider: 'claude',
+    computePlan(context) {
+        return computeClaudeProjectExtensionPlan(context.scopeRoot, context.canonicalEntries, context.allowedCanonicalPaths, context.options);
+    },
+    applyPlan: applyClaudeProjectExtensionPlan,
+};

package/dist/providers/claude/dispatch-envelope.d.ts

@@ -0,0 +1,34 @@
+import { type GenericDispatchRecord } from '../identity/generic-dispatch-record.js';
+import { type ClaudeCapabilityEvidence } from './targets.js';
+export interface AcceptedClaudeLaunchEnvelope {
+    schemaVersion: 1;
+    provider: 'claude';
+    resolverRole: 'implementer' | 'reviewer';
+    baseRole: 'oat-phase-implementer' | 'oat-reviewer';
+    variant: string;
+    model: string;
+    capabilityEvidence: ClaudeCapabilityEvidence;
+    effort: string;
+    policy: string;
+    ceiling: string;
+    payload: {
+        variant: string;
+        model?: string;
+    };
+}
+/**
+ * Validate the managed resolver result against the generated provider role and
+ * the exact payload that will be launched. This is the production boundary
+ * used by the project dispatch-record producer for managed Claude dispatches.
+ */
+export declare function acceptClaudeLaunchEnvelope(input: {
+    resolution: unknown;
+    definition: string;
+    launch: unknown;
+}): AcceptedClaudeLaunchEnvelope;
+/** Build configured invocation evidence only from an accepted launch envelope. */
+export declare function buildClaudeDispatchRecord(input: {
+    envelope: AcceptedClaudeLaunchEnvelope;
+    recordBase: unknown;
+}): GenericDispatchRecord;
+//# sourceMappingURL=dispatch-envelope.d.ts.map

package/dist/providers/claude/dispatch-envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch-envelope.d.ts","sourceRoot":"","sources":["../../../src/providers/claude/dispatch-envelope.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,qBAAqB,EAC3B,MAAM,6CAA6C,CAAC;AAKrD,OAAO,EAEL,KAAK,wBAAwB,EAE9B,MAAM,WAAW,CAAC;AA4FnB,MAAM,WAAW,4BAA4B;IAC3C,aAAa,EAAE,CAAC,CAAC;IACjB,QAAQ,EAAE,QAAQ,CAAC;IACnB,YAAY,EAAE,aAAa,GAAG,UAAU,CAAC;IACzC,QAAQ,EAAE,uBAAuB,GAAG,cAAc,CAAC;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,kBAAkB,EAAE,wBAAwB,CAAC;IAC7C,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE;QACP,OAAO,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;CACH;AAsCD;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE;IAChD,UAAU,EAAE,OAAO,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,OAAO,CAAC;CACjB,GAAG,4BAA4B,CA6F/B;AAmBD,kFAAkF;AAClF,wBAAgB,yBAAyB,CAAC,KAAK,EAAE;IAC/C,QAAQ,EAAE,4BAA4B,CAAC;IACvC,UAAU,EAAE,OAAO,CAAC;CACrB,GAAG,qBAAqB,CAoDxB"}