salmon-loop 0.2.13 → 0.3.0

package/dist/core/tools/builtin/fs.js

@@ -1,8 +1,12 @@
+import { createHash } from 'crypto';
+import { Buffer } from 'node:buffer';
 import { isAbsolute, relative, resolve } from 'path';
 import { z } from 'zod';
 import { text } from '../../../locales/index.js';
-import { readFile, readdir, stat } from '../../adapters/fs/node-fs.js';
+import { AtomicFileWriter } from '../../adapters/fs/atomic-file-writer.js';
+import { mkdir, readFile, readdir, stat } from '../../adapters/fs/node-fs.js';
 import { Phase } from '../../types/runtime.js';
+import { normalizeRepoRelativePath } from '../../utils/path.js';
 import { pathPrefixResource } from '../parallel/resource-helpers.js';
 const FsListEntryType = z.enum(['file', 'dir', 'symlink', 'other']);
 const fsListInputSchema = z.preprocess((raw) => {
@@ -94,6 +98,7 @@ export const fsReadFileSpec = {
         Phase.CONTEXT,
         Phase.EXPLORE,
         Phase.PLAN,
+        Phase.AUTOPILOT,
         Phase.PATCH,
         Phase.VERIFY,
         Phase.SHRINK,
@@ -154,11 +159,28 @@ export const fsListSpec = {
         Phase.CONTEXT,
         Phase.EXPLORE,
         Phase.PLAN,
+        Phase.AUTOPILOT,
         Phase.PATCH,
         Phase.VERIFY,
         Phase.SHRINK,
     ],
 };
+/**
+ * Spec for the fs.list_directory tool.
+ */
+export const fsListDirectorySpec = {
+    ...fsListSpec,
+    name: 'fs.list_directory',
+    description: text.tools.fsListDirectoryDescription,
+};
+/**
+ * Spec for the fs.list_files tool.
+ */
+export const fsListFilesSpec = {
+    ...fsListSpec,
+    name: 'fs.list_files',
+    description: text.tools.fsListFilesDescription,
+};
 function toRepoRelativeChildPath(dir, name) {
     const normalizedDir = String(dir || '.')
         .replace(/\\/g, '/')
@@ -166,23 +188,49 @@ function toRepoRelativeChildPath(dir, name) {
     const base = normalizedDir === '.' ? '' : normalizedDir.replace(/^\.\/+/, '').replace(/\/+$/, '');
     return base ? `${base}/${name}` : name;
 }
+function assertNotReservedRepoPrefix(relPath) {
+    const normalized = normalizeRepoRelativePath(relPath);
+    if (normalized === '.git' || normalized.startsWith('.git/')) {
+        throw new Error(text.errors.reservedPathPrefix('.git/'));
+    }
+    if (normalized === '.salmonloop' || normalized.startsWith('.salmonloop/')) {
+        throw new Error(text.errors.reservedPathPrefix('.salmonloop/'));
+    }
+}
+function resolveRepoRelativePath(repoRoot, relPath) {
+    if (isAbsolute(relPath)) {
+        throw new Error(text.errors.pathOutsideRepo);
+    }
+    assertNotReservedRepoPrefix(relPath);
+    const absoluteRoot = resolve(repoRoot);
+    const absolutePath = resolve(absoluteRoot, relPath);
+    const computedRelPath = relative(absoluteRoot, absolutePath);
+    if (computedRelPath.startsWith('..') || isAbsolute(computedRelPath)) {
+        throw new Error(text.errors.pathOutsideRepo);
+    }
+    return { absolutePath };
+}
+function shouldIncludeListedEntry(dir, entryName, includeHidden) {
+    if (!includeHidden && entryName.startsWith('.'))
+        return false;
+    const childPath = toRepoRelativeChildPath(dir, entryName);
+    try {
+        assertNotReservedRepoPrefix(childPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Implementation of the fs.list tool.
  */
 export async function executeFsList(input, ctx) {
     const { path: dir, includeHidden, maxEntries } = input;
-    if (isAbsolute(dir)) {
-        throw new Error(text.errors.pathOutsideRepo);
-    }
-    const absoluteRoot = resolve(ctx.repoRoot);
-    const absolutePath = resolve(absoluteRoot, dir);
-    const relPath = relative(absoluteRoot, absolutePath);
-    if (relPath.startsWith('..') || isAbsolute(relPath)) {
-        throw new Error(text.errors.pathOutsideRepo);
-    }
+    const { absolutePath } = resolveRepoRelativePath(ctx.repoRoot, dir);
     try {
         const dirents = await readdir(absolutePath, { withFileTypes: true });
-        const visible = includeHidden ? dirents : dirents.filter((d) => !d.name.startsWith('.'));
+        const visible = dirents.filter((d) => shouldIncludeListedEntry(dir, d.name, includeHidden));
         const entries = visible
             .map((d) => {
             const type = d.isDirectory()
@@ -211,23 +259,208 @@ export async function executeFsList(input, ctx) {
         throw new Error(`Failed to list directory ${dir}: ${e instanceof Error ? e.message : String(e)}`);
     }
 }
+/**
+ * Implementation of the fs.list_directory tool.
+ */
+export async function executeFsListDirectory(input, ctx) {
+    return executeFsList(input, ctx);
+}
+/**
+ * Implementation of the fs.list_files tool.
+ */
+export async function executeFsListFiles(input, ctx) {
+    const { path: dir, includeHidden, maxEntries } = input;
+    const { absolutePath } = resolveRepoRelativePath(ctx.repoRoot, dir);
+    try {
+        const dirents = await readdir(absolutePath, { withFileTypes: true });
+        const visible = dirents.filter((d) => shouldIncludeListedEntry(dir, d.name, includeHidden));
+        const fileEntries = visible
+            .filter((d) => d.isFile())
+            .map((d) => ({
+            name: d.name,
+            path: toRepoRelativeChildPath(dir, d.name),
+            type: 'file',
+        }))
+            .sort((a, b) => a.path.localeCompare(b.path));
+        const totalEntries = fileEntries.length;
+        const sliced = fileEntries.slice(0, maxEntries);
+        return {
+            entries: sliced,
+            truncated: sliced.length < totalEntries,
+            totalEntries,
+        };
+    }
+    catch (e) {
+        throw new Error(`Failed to list files in directory ${dir}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+}
+const fsWriteFileInputSchema = z.preprocess((raw) => {
+    if (typeof raw === 'string') {
+        return { file: raw };
+    }
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return raw;
+    const input = raw;
+    if (typeof input.file === 'string')
+        return input;
+    const alias = input.path ?? input.file_path ?? input.filePath;
+    if (typeof alias !== 'string')
+        return input;
+    return {
+        ...input,
+        file: alias,
+    };
+}, z.object({
+    file: z.string().describe('Relative path to the file from the repository root'),
+    content: z.string().describe('UTF-8 text content to write'),
+    encoding: z
+        .enum(['utf-8'])
+        .optional()
+        .describe('Text encoding (only utf-8 is supported; default: utf-8)'),
+}));
+/**
+ * Spec for the fs.write_file tool.
+ */
+export const fsWriteFileSpec = {
+    name: 'fs.write_file',
+    source: 'builtin',
+    intent: 'WRITE',
+    description: text.tools.fsWriteFileDescription,
+    riskLevel: 'high',
+    sideEffects: ['fs_write'],
+    concurrency: 'serial_only',
+    computeResources: (input, ctx) => [pathPrefixResource(ctx, input.file)],
+    allowedPhases: [Phase.SLASH, Phase.AUTOPILOT],
+    inputSchema: fsWriteFileInputSchema,
+    outputSchema: z.object({
+        ok: z.boolean(),
+        path: z.string(),
+        bytesWritten: z.number().int().nonnegative(),
+    }),
+    summarizeArgsForAuthorization: async (args) => {
+        const encoding = args?.encoding || 'utf-8';
+        const content = String(args?.content ?? '');
+        const bytes = Buffer.byteLength(content, 'utf8');
+        const sha256 = createHash('sha256').update(content, 'utf8').digest('hex');
+        return JSON.stringify({
+            file: args?.file,
+            encoding,
+            bytes,
+            sha256,
+        });
+    },
+};
+export async function executeFsWriteFile(input, ctx) {
+    if (ctx.dryRun) {
+        return { ok: true, path: input.file, bytesWritten: 0 };
+    }
+    const { absolutePath } = resolveRepoRelativePath(ctx.repoRoot, input.file);
+    const writer = new AtomicFileWriter();
+    const contentBytes = Buffer.from(input.content, 'utf8');
+    await writer.writeAtomic(absolutePath, contentBytes);
+    return {
+        ok: true,
+        path: input.file,
+        bytesWritten: contentBytes.length,
+    };
+}
+const fsCreateDirectoryInputSchema = z.preprocess((raw) => {
+    if (typeof raw === 'string')
+        return { path: raw };
+    return raw;
+}, z.object({
+    path: z.string().describe('Relative directory path to create from the repository root'),
+    recursive: z.boolean().default(true).describe('Whether to create parent directories'),
+}));
+/**
+ * Spec for the fs.create_directory tool.
+ */
+export const fsCreateDirectorySpec = {
+    name: 'fs.create_directory',
+    source: 'builtin',
+    intent: 'WRITE',
+    description: text.tools.fsCreateDirectoryDescription,
+    riskLevel: 'high',
+    sideEffects: ['fs_write'],
+    concurrency: 'serial_only',
+    computeResources: (input, ctx) => [pathPrefixResource(ctx, input.path)],
+    allowedPhases: [Phase.SLASH, Phase.AUTOPILOT],
+    inputSchema: fsCreateDirectoryInputSchema,
+    outputSchema: z.object({
+        ok: z.boolean(),
+        path: z.string(),
+    }),
+    summarizeArgsForAuthorization: async (args) => JSON.stringify({ path: args?.path, recursive: args?.recursive }),
+};
+export async function executeFsCreateDirectory(input, ctx) {
+    if (ctx.dryRun) {
+        return { ok: true, path: input.path };
+    }
+    const { absolutePath } = resolveRepoRelativePath(ctx.repoRoot, input.path);
+    await mkdir(absolutePath, { recursive: input.recursive });
+    return { ok: true, path: input.path };
+}
+const fsDeleteFileInputSchema = z.preprocess((raw) => {
+    if (typeof raw === 'string')
+        return { file: raw };
+    return raw;
+}, z.object({
+    file: z.string().describe('Relative path to the file from the repository root'),
+    missingOk: z.boolean().default(true).describe('Whether missing files are treated as success'),
+}));
+/**
+ * Spec for the fs.delete_file tool.
+ */
+export const fsDeleteFileSpec = {
+    name: 'fs.delete_file',
+    source: 'builtin',
+    intent: 'WRITE',
+    description: text.tools.fsDeleteFileDescription,
+    riskLevel: 'high',
+    sideEffects: ['fs_write'],
+    concurrency: 'serial_only',
+    computeResources: (input, ctx) => [pathPrefixResource(ctx, input.file)],
+    allowedPhases: [Phase.SLASH, Phase.AUTOPILOT],
+    inputSchema: fsDeleteFileInputSchema,
+    outputSchema: z.object({
+        ok: z.boolean(),
+        path: z.string(),
+        deleted: z.boolean(),
+    }),
+    summarizeArgsForAuthorization: async (args) => JSON.stringify({ file: args?.file, missingOk: args?.missingOk }),
+};
+export async function executeFsDeleteFile(input, ctx) {
+    if (ctx.dryRun) {
+        return { ok: true, path: input.file, deleted: false };
+    }
+    const { absolutePath } = resolveRepoRelativePath(ctx.repoRoot, input.file);
+    let exists = true;
+    try {
+        await stat(absolutePath);
+    }
+    catch (e) {
+        const code = e && typeof e === 'object' && 'code' in e ? e.code : undefined;
+        if (code === 'ENOENT')
+            exists = false;
+        else
+            throw e;
+    }
+    if (!exists) {
+        if (input.missingOk) {
+            return { ok: true, path: input.file, deleted: false };
+        }
+        throw new Error(text.errors.pathNotFound(input.file));
+    }
+    const writer = new AtomicFileWriter();
+    await writer.deleteAtomic(absolutePath);
+    return { ok: true, path: input.file, deleted: true };
+}
 /**
  * Implementation of the fs.read tool.
  */
 export async function executeFsReadFile(input, ctx) {
     const { file } = input;
-    if (isAbsolute(file)) {
-        throw new Error(text.errors.pathOutsideRepo);
-    }
-    // CRITICAL SAFETY: Path traversal check using relative path resolution
-    // We resolve to absolute paths to handle '.' and '..' correctly
-    const absoluteRoot = resolve(ctx.repoRoot);
-    // use resolve instead of join to handle absolute paths in input correctly
-    const absolutePath = resolve(absoluteRoot, file);
-    const relPath = relative(absoluteRoot, absolutePath);
-    if (relPath.startsWith('..') || isAbsolute(relPath)) {
-        throw new Error(text.errors.pathOutsideRepo);
-    }
+    const { absolutePath } = resolveRepoRelativePath(ctx.repoRoot, file);
     try {
         const fileStat = await stat(absolutePath);
         const content = await readFile(absolutePath, 'utf-8');

package/dist/core/tools/builtin/git.js

@@ -22,7 +22,7 @@ export const gitCatSpec = {
         file: z.string(),
         ref: z.string(),
     }),
-    allowedPhases: [Phase.SLASH, Phase.CONTEXT],
+    allowedPhases: [Phase.SLASH, Phase.CONTEXT, Phase.AUTOPILOT],
     examples: [
         {
             description: 'Read a file from HEAD revision',
@@ -86,7 +86,7 @@ export const gitStatusSpec = {
     outputSchema: z.object({
         status: z.string(),
     }),
-    allowedPhases: [Phase.SLASH, Phase.CONTEXT, Phase.PLAN, Phase.VERIFY],
+    allowedPhases: [Phase.SLASH, Phase.CONTEXT, Phase.PLAN, Phase.AUTOPILOT, Phase.VERIFY],
 };
 /**
  * Builtin tool to check git status

package/dist/core/tools/builtin/index.js

@@ -2,9 +2,10 @@ import { subAgentTaskSpec } from '../../sub-agent/tools/task-spawn.js';
 import { artifactReadSpec, executeArtifactRead } from './artifact.js';
 import { astGrepSpec, executeAstGrep } from './ast-grep.js';
 import { astDefsRefsSpec, executeAstDefsRefs } from './ast.js';
+import { benchmarkReportSpec, executeBenchmarkReport, executeGitApplyCheck, executeGitDiffCheck, executeSweBenchGetReport, executeSweBenchLoadInstance, executeSweBenchSubmitPredictions, executeSweBenchWritePrediction, gitApplyCheckSpec, gitDiffCheckSpec, sweBenchGetReportSpec, sweBenchLoadInstanceSpec, sweBenchSubmitPredictionsSpec, sweBenchWritePredictionSpec, } from './benchmark.js';
 import { codeSearchExecutor } from './code-search/executor.js';
 import { CodeSearchSpec } from './code-search/spec.js';
-import { codeReadSpec, executeFsList, executeFsReadFile, fsListSpec, fsReadFileSpec, } from './fs.js';
+import { codeReadSpec, executeFsCreateDirectory, executeFsList, executeFsListDirectory, executeFsListFiles, executeFsReadFile, executeFsDeleteFile, executeFsWriteFile, fsCreateDirectorySpec, fsDeleteFileSpec, fsListSpec, fsListDirectorySpec, fsListFilesSpec, fsReadFileSpec, fsWriteFileSpec, } from './fs.js';
 import { gitCatSpec, executeGitCat, gitStatusSpec, executeGitStatus } from './git.js';
 import { askUserSpec } from './interaction.js';
 import { updateKnowledgeSpec, executeUpdateKnowledge } from './knowledge.js';
@@ -47,6 +48,34 @@ export function registerAllBuiltins(registry) {
         ...gitStatusSpec,
         executor: executeGitStatus,
     });
+    registry.register({
+        ...gitDiffCheckSpec,
+        executor: executeGitDiffCheck,
+    });
+    registry.register({
+        ...gitApplyCheckSpec,
+        executor: executeGitApplyCheck,
+    });
+    registry.register({
+        ...benchmarkReportSpec,
+        executor: executeBenchmarkReport,
+    });
+    registry.register({
+        ...sweBenchLoadInstanceSpec,
+        executor: executeSweBenchLoadInstance,
+    });
+    registry.register({
+        ...sweBenchWritePredictionSpec,
+        executor: executeSweBenchWritePrediction,
+    });
+    registry.register({
+        ...sweBenchSubmitPredictionsSpec,
+        executor: executeSweBenchSubmitPredictions,
+    });
+    registry.register({
+        ...sweBenchGetReportSpec,
+        executor: executeSweBenchGetReport,
+    });
     registry.register({
         ...fsReadFileSpec,
         executor: executeFsReadFile,
@@ -59,6 +88,14 @@ export function registerAllBuiltins(registry) {
         ...fsListSpec,
         executor: executeFsList,
     });
+    registry.register({
+        ...fsListDirectorySpec,
+        executor: executeFsListDirectory,
+    });
+    registry.register({
+        ...fsListFilesSpec,
+        executor: executeFsListFiles,
+    });
     registry.register({
         ...astGrepSpec,
         executor: executeAstGrep,
@@ -71,10 +108,22 @@ export function registerAllBuiltins(registry) {
         ...shellExecSpec,
         executor: executeShellExec,
     });
+    registry.register({
+        ...fsWriteFileSpec,
+        executor: executeFsWriteFile,
+    });
+    registry.register({
+        ...fsCreateDirectorySpec,
+        executor: executeFsCreateDirectory,
+    });
+    registry.register({
+        ...fsDeleteFileSpec,
+        executor: executeFsDeleteFile,
+    });
     registry.register(planInitSpec);
     registry.register(planReadSpec);
     registry.register(planUpdateSpec);
     registry.register(askUserSpec);
 }
-export { CodeSearchSpec, codeSearchExecutor, astDefsRefsSpec as codeAstSpec, executeAstDefsRefs as executeCodeAst, gitCatSpec, executeGitCat, gitStatusSpec, executeGitStatus, codeReadSpec, fsListSpec, executeFsList, fsReadFileSpec as fsReadSpec, executeFsReadFile as executeFsRead, updateKnowledgeSpec, executeUpdateKnowledge, astGrepSpec as codeSearchAstSpec, executeAstGrep as executeCodeSearchAst, verifyRunSpec as testRunSpec, executeVerifyRun as executeTestRun, };
+export { CodeSearchSpec, codeSearchExecutor, astDefsRefsSpec as codeAstSpec, executeAstDefsRefs as executeCodeAst, gitCatSpec, executeGitCat, gitStatusSpec, executeGitStatus, codeReadSpec, fsListSpec, executeFsList, fsReadFileSpec as fsReadSpec, executeFsReadFile as executeFsRead, updateKnowledgeSpec, executeUpdateKnowledge, astGrepSpec as codeSearchAstSpec, executeAstGrep as executeCodeSearchAst, verifyRunSpec as testRunSpec, executeVerifyRun as executeTestRun, gitDiffCheckSpec, executeGitDiffCheck, gitApplyCheckSpec, executeGitApplyCheck, benchmarkReportSpec, executeBenchmarkReport, sweBenchLoadInstanceSpec, executeSweBenchLoadInstance, sweBenchWritePredictionSpec, executeSweBenchWritePrediction, sweBenchSubmitPredictionsSpec, executeSweBenchSubmitPredictions, sweBenchGetReportSpec, executeSweBenchGetReport, };
 //# sourceMappingURL=index.js.map

package/dist/core/tools/builtin/interaction.js

@@ -63,7 +63,14 @@ export const askUserSpec = {
     riskLevel: 'low',
     sideEffects: ['none'],
     concurrency: 'serial_only',
-    allowedPhases: [Phase.EXPLORE, Phase.PLAN, Phase.PATCH, Phase.VALIDATE, Phase.AST_VALIDATE],
+    allowedPhases: [
+        Phase.EXPLORE,
+        Phase.PLAN,
+        Phase.AUTOPILOT,
+        Phase.PATCH,
+        Phase.VALIDATE,
+        Phase.AST_VALIDATE,
+    ],
     inputSchema: askUserInputSchema,
     outputSchema: askUserOutputSchema,
     executor: async (input, ctx) => {

package/dist/core/tools/builtin/plan.js

@@ -14,6 +14,17 @@ const stepIdSchema = z
     .max(128)
     .regex(/^[a-zA-Z0-9_.:-]+$/)
     .describe('Stable step ID (from <!-- sl:id=... -->).');
+const planUpdatePatchSchema = z
+    .object({
+    status: z.enum(['todo', 'active', 'done', 'failed', 'skipped', 'conflict']).optional(),
+    checkbox: z.enum(['checked', 'unchecked']).optional(),
+    appendSubtasks: z.array(z.string().min(1)).optional(),
+    note: z.string().optional(),
+})
+    .describe('Patch object for plan.update. Provide a JSON object (not a JSON string). Optional keys: status, checkbox, appendSubtasks, note.');
+const planUpdateConflictCodeSchema = z
+    .enum(['BASE_HASH_MISMATCH', 'STEP_NOT_FOUND', 'MALFORMED_METADATA', 'WRITE_DENIED'])
+    .describe('Conflict code returned when ok=false.');
 function planResource(ctx, sessionId) {
     const repoId = ctx.persistenceRoot ?? ctx.repoRoot;
     if (!sessionId)
@@ -29,7 +40,14 @@ export const planInitSpec = {
     sideEffects: ['runtime_write'],
     concurrency: 'mutex_by_resource',
     computeResources: (_args, ctx) => planResource(ctx),
-    allowedPhases: [Phase.EXPLORE, Phase.PLAN, Phase.PATCH, Phase.VERIFY, Phase.SHRINK],
+    allowedPhases: [
+        Phase.EXPLORE,
+        Phase.PLAN,
+        Phase.AUTOPILOT,
+        Phase.PATCH,
+        Phase.VERIFY,
+        Phase.SHRINK,
+    ],
     inputSchema: z.object({
         mission: z.string().min(1),
         objective: z.string().min(1),
@@ -59,7 +77,14 @@ export const planReadSpec = {
     sideEffects: ['fs_read'],
     concurrency: 'parallel_ok',
     computeResources: (args, ctx) => planResource(ctx, args.sessionId),
-    allowedPhases: [Phase.EXPLORE, Phase.PLAN, Phase.PATCH, Phase.VERIFY, Phase.SHRINK],
+    allowedPhases: [
+        Phase.EXPLORE,
+        Phase.PLAN,
+        Phase.AUTOPILOT,
+        Phase.PATCH,
+        Phase.VERIFY,
+        Phase.SHRINK,
+    ],
     inputSchema: z.object({
         sessionId: sessionIdSchema,
     }),
@@ -100,17 +125,19 @@ export const planUpdateSpec = {
     sideEffects: ['runtime_write'],
     concurrency: 'mutex_by_resource',
     computeResources: (args, ctx) => planResource(ctx, args.sessionId),
-    allowedPhases: [Phase.EXPLORE, Phase.PLAN, Phase.PATCH, Phase.VERIFY, Phase.SHRINK],
+    allowedPhases: [
+        Phase.EXPLORE,
+        Phase.PLAN,
+        Phase.AUTOPILOT,
+        Phase.PATCH,
+        Phase.VERIFY,
+        Phase.SHRINK,
+    ],
     inputSchema: z.object({
         sessionId: sessionIdSchema,
         baseHash: z.string().min(8),
         stepId: stepIdSchema,
-        patch: z.object({
-            status: z.enum(['todo', 'active', 'done', 'failed', 'skipped', 'conflict']).optional(),
-            checkbox: z.enum(['checked', 'unchecked']).optional(),
-            appendSubtasks: z.array(z.string().min(1)).optional(),
-            note: z.string().optional(),
-        }),
+        patch: planUpdatePatchSchema,
     }),
     outputSchema: z.union([
         z.object({
@@ -124,12 +151,7 @@ export const planUpdateSpec = {
             sessionId: z.string(),
             baseHash: z.string(),
             conflict: z.object({
-                code: z.enum([
-                    'BASE_HASH_MISMATCH',
-                    'STEP_NOT_FOUND',
-                    'MALFORMED_METADATA',
-                    'WRITE_DENIED',
-                ]),
+                code: planUpdateConflictCodeSchema,
                 message: z.string(),
             }),
         }),

package/dist/core/tools/builtin/shell.js

@@ -13,7 +13,7 @@ export const shellExecSpec = {
     sideEffects: ['process'],
     concurrency: 'isolated',
     computeResources: (_input, ctx) => [repoResource(ctx), processResource(ctx)],
-    allowedPhases: [Phase.SLASH],
+    allowedPhases: [Phase.SLASH, Phase.AUTOPILOT],
     inputSchema: z.object({
         command: z.string().min(1).describe('Shell command to execute'),
     }),

package/dist/core/tools/loader.js

@@ -28,21 +28,6 @@ export async function createStandardToolstack(options) {
     const sanitize = new ToolSanitizer();
     // 2. Register all builtin tools (rg, git, ast, ast-grep)
     registerAllBuiltins(registry);
-    // 3. Load and register Skills as tools
-    const extensions = options.extensions;
-    const skillLoader = new SkillLoader({
-        repoRoot: options.repoRoot,
-        useDefaults: extensions?.skillDiscovery.useDefaults,
-        extraPaths: extensions?.skillDiscovery.paths,
-    });
-    const skills = await skillLoader.initialize();
-    for (const skill of skills) {
-        registry.register(skillToToolSpec(skill));
-    }
-    if (extensions) {
-        await registerMcpTools(registry, extensions.mcpServers);
-        await registerPluginTools(registry, extensions.toolPlugins);
-    }
     const compiledPermissionRules = (() => {
         if (!options.permissionRules)
             return undefined;
@@ -53,6 +38,42 @@ export async function createStandardToolstack(options) {
         }
         return compiled.compiled;
     })();
+    // 3. Register ALL tools (builtins already done above) into the registry,
+    //    then apply allowlist/permission filtering, then create the router.
+    //
+    //    The challenge: skill executors need a ToolRouter reference (to call
+    //    shell.exec through governance), but the router needs the final filtered
+    //    registry. We break this cycle with a RouterBox — a mutable container
+    //    whose .router field is filled after the router is constructed.
+    //
+    //    Order:
+    //      a. Create RouterBox (null initially)
+    //      b. Load skills → register with RouterBox (executor reads lazily)
+    //      c. Register MCP + plugin tools
+    //      d. Apply allowlist/permission filtering → new filtered registry
+    //      e. Create ToolRouter with filtered registry
+    //      f. Fill RouterBox.router — skill executors now have a valid reference
+    const routerBox = { router: null };
+    // 3a. Load skill catalog (Tier 1: lightweight metadata only) and register
+    //     bridge tool specs with lazy activation. Full skill content is loaded
+    //     on demand via SkillLoader.activateSkill() (Tier 2) when the executor
+    //     is actually invoked.
+    // @see https://agentskills.io/specification — Progressive disclosure
+    const extensions = options.extensions;
+    const skillLoader = new SkillLoader({
+        repoRoot: options.repoRoot,
+        extraPaths: extensions?.skillDiscovery.paths,
+    });
+    const catalog = await skillLoader.loadCatalog();
+    for (const entry of catalog) {
+        registry.register(skillToToolSpec({ entry, loader: skillLoader }, routerBox));
+    }
+    // 3b. Register MCP + plugin tools
+    if (extensions) {
+        await registerMcpTools(registry, extensions.mcpServers);
+        await registerPluginTools(registry, extensions.toolPlugins);
+    }
+    // 3c. Apply allowlist / permission-rule filtering — skills are now included
     const allowSets = [];
     if (Array.isArray(options.allowedToolNames) && options.allowedToolNames.length > 0) {
         allowSets.push(new Set(options.allowedToolNames));
@@ -76,8 +97,10 @@ export async function createStandardToolstack(options) {
         }
         registry = filtered;
     }
-    // 4. Create Router (The execution pipeline)
+    // 3d. Create Router with the FINAL (filtered) registry — skills included
     const router = new ToolRouter(registry, policy, budget, audit, sanitize, options.authorizationProvider, { authorizationMode: options.authorizationMode, permissionRules: compiledPermissionRules });
+    // 3e. Fill the RouterBox — skill executors can now resolve the router
+    routerBox.router = router;
     // 4. Create Dispatcher (The high-level coordinator for LLM text)
     const dispatcher = new ToolDispatcher(router, {
         repoRoot: options.repoRoot,

package/dist/core/tools/mapper.js

@@ -1,4 +1,18 @@
 import { z } from 'zod';
+function formatToolExamplesForDescription(spec) {
+    if (!Array.isArray(spec.examples) || spec.examples.length === 0)
+        return '';
+    const examples = spec.examples
+        .map((example) => {
+        const input = JSON.stringify(example.input);
+        return input ? `- ${example.description}: ${input}` : undefined;
+    })
+        .filter((line) => Boolean(line));
+    return examples.length > 0 ? `\n\nExamples:\n${examples.join('\n')}` : '';
+}
+function toolDescriptionForModel(spec) {
+    return `${spec.description}${formatToolExamplesForDescription(spec)}`;
+}
 function unwrapForSchemaGeneration(schema) {
     let current = schema;
     for (let depth = 0; depth < 20; depth++) {
@@ -113,7 +127,7 @@ export function toolToOpenAI(spec) {
         type: 'function',
         function: {
             name: spec.name,
-            description: spec.description,
+            description: toolDescriptionForModel(spec),
             parameters: zodToOpenApi3(spec.inputSchema),
         },
     };
@@ -124,7 +138,7 @@ export function toolToOpenAI(spec) {
 export function toolToAnthropic(spec) {
     return {
         name: spec.name,
-        description: spec.description,
+        description: toolDescriptionForModel(spec),
         input_schema: zodToOpenApi3(spec.inputSchema),
     };
 }
@@ -135,7 +149,7 @@ export function formatToolsForPrompt(specs) {
     return specs
         .map((spec) => {
         const schema = zodToOpenApi3(spec.inputSchema);
-        return `Tool: ${spec.name}\nDescription: ${spec.description}\nSchema: ${JSON.stringify(schema, null, 2)}`;
+        return `Tool: ${spec.name}\nDescription: ${toolDescriptionForModel(spec)}\nSchema: ${JSON.stringify(schema, null, 2)}`;
     })
         .join('\n\n---\n\n');
 }