zora-agent 0.10.0 → 0.10.2

package/dist/tools/planning-tool.d.ts

@@ -0,0 +1,95 @@
+/**
+ * PlanningTool — Exposes TLCI's buildExecutionPlan as a callable LLM tool.
+ *
+ * The LLM can call plan_workflow to decompose a multi-step task into TLCI tiers,
+ * see the cost estimate, and optionally execute it. Makes TLCI self-driving.
+ *
+ * Usage by the LLM:
+ *   plan_workflow({ steps: [{id:"1", description:"fetch user data from API"},...] })
+ *   → returns plan summary + estimated cost
+ *   plan_workflow({ steps: [...], execute: true })
+ *   → returns plan + executes it via submitWorkflow
+ */
+import type { DispatchResult } from '../orchestrator/tlci-dispatcher.js';
+import type { WorkflowStep } from '../orchestrator/step-classifier.js';
+import type { CustomToolDefinition } from '../orchestrator/execution-loop.js';
+export declare const PLAN_WORKFLOW_TOOL_NAME = "plan_workflow";
+export declare const PLAN_WORKFLOW_TOOL_DEFINITION: {
+    name: string;
+    description: string;
+    input_schema: {
+        type: "object";
+        properties: {
+            steps: {
+                type: string;
+                description: string;
+                items: {
+                    type: string;
+                    properties: {
+                        id: {
+                            type: string;
+                            description: string;
+                        };
+                        description: {
+                            type: string;
+                            description: string;
+                        };
+                        inputType: {
+                            type: string;
+                            description: string;
+                        };
+                        outputType: {
+                            type: string;
+                            description: string;
+                        };
+                    };
+                    required: string[];
+                };
+                minItems: number;
+            };
+            execute: {
+                type: string;
+                description: string;
+                default: boolean;
+            };
+            budgetLimitUSD: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export interface PlanWorkflowArgs {
+    steps: WorkflowStep[];
+    execute?: boolean;
+    budgetLimitUSD?: number;
+}
+export interface PlanWorkflowResult {
+    planId: string;
+    planHash: string;
+    summary: string;
+    approvalView: string;
+    tierBreakdown: {
+        code: number;
+        slm: number;
+        frontier: number;
+    };
+    estimatedCostUSD: number;
+    savingsPct: number;
+    executed: boolean;
+    dispatchResult?: unknown;
+}
+export type SubmitWorkflowFn = (steps: WorkflowStep[], opts?: {
+    budgetLimitUSD?: number;
+}) => Promise<DispatchResult>;
+export declare function handlePlanWorkflow(args: PlanWorkflowArgs, submitWorkflow: SubmitWorkflowFn): Promise<PlanWorkflowResult>;
+/**
+ * Create a plan_workflow CustomToolDefinition bound to the given submitWorkflow function.
+ * Pass this into ExecutionLoop's customTools array (via _createCustomTools).
+ *
+ * If submitWorkflow is not provided (plan-only mode), execution requests will
+ * throw a clear error instead of silently failing.
+ */
+export declare function createPlanWorkflowTool(submitWorkflow?: SubmitWorkflowFn): CustomToolDefinition;
+//# sourceMappingURL=planning-tool.d.ts.map

package/dist/tools/planning-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"planning-tool.d.ts","sourceRoot":"","sources":["../../src/tools/planning-tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AACzE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAC;AACvE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AAO9E,eAAO,MAAM,uBAAuB,kBAAkB,CAAC;AAIvD,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsCzC,CAAC;AAIF,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/D,gBAAgB,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,OAAO,CAAC;IAClB,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAID,MAAM,MAAM,gBAAgB,GAAG,CAC7B,KAAK,EAAE,YAAY,EAAE,EACrB,IAAI,CAAC,EAAE;IAAE,cAAc,CAAC,EAAE,MAAM,CAAA;CAAE,KAC/B,OAAO,CAAC,cAAc,CAAC,CAAC;AAI7B,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,gBAAgB,EACtB,cAAc,EAAE,gBAAgB,GAC/B,OAAO,CAAC,kBAAkB,CAAC,CAwC7B;AAID;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,cAAc,CAAC,EAAE,gBAAgB,GAChC,oBAAoB,CAgBtB"}

package/dist/tools/planning-tool.js

@@ -0,0 +1,117 @@
+/**
+ * PlanningTool — Exposes TLCI's buildExecutionPlan as a callable LLM tool.
+ *
+ * The LLM can call plan_workflow to decompose a multi-step task into TLCI tiers,
+ * see the cost estimate, and optionally execute it. Makes TLCI self-driving.
+ *
+ * Usage by the LLM:
+ *   plan_workflow({ steps: [{id:"1", description:"fetch user data from API"},...] })
+ *   → returns plan summary + estimated cost
+ *   plan_workflow({ steps: [...], execute: true })
+ *   → returns plan + executes it via submitWorkflow
+ */
+import { buildExecutionPlan, formatPlanSummary, formatPlanForApproval } from '../orchestrator/execution-planner.js';
+import { createLogger } from '../utils/logger.js';
+const log = createLogger('planning-tool');
+// ─── Tool Name ────────────────────────────────────────────────────────────────
+export const PLAN_WORKFLOW_TOOL_NAME = 'plan_workflow';
+// ─── Tool Definition (JSON Schema for the LLM) ────────────────────────────────
+export const PLAN_WORKFLOW_TOOL_DEFINITION = {
+    name: PLAN_WORKFLOW_TOOL_NAME,
+    description: [
+        'Decompose the current task into discrete workflow steps for cost-efficient execution.',
+        'Use when the task involves multiple operations (fetch → transform → classify → summarize → send).',
+        'Returns an execution plan showing which steps run as code tools (free), local SLM ($0.0001/step),',
+        'or frontier LLM ($0.003/step), with total estimated cost vs running everything through a frontier LLM.',
+    ].join(' '),
+    input_schema: {
+        type: 'object',
+        properties: {
+            steps: {
+                type: 'array',
+                description: 'Ordered workflow steps. Earlier steps may feed context to later ones.',
+                items: {
+                    type: 'object',
+                    properties: {
+                        id: { type: 'string', description: 'Unique step identifier (e.g. "1", "fetch")' },
+                        description: { type: 'string', description: 'Natural language description of this step' },
+                        inputType: { type: 'string', description: 'Optional: url | json | text | fileList' },
+                        outputType: { type: 'string', description: 'Optional: json | text | boolean | void' },
+                    },
+                    required: ['id', 'description'],
+                },
+                minItems: 1,
+            },
+            execute: {
+                type: 'boolean',
+                description: 'If true, execute the plan immediately. If false (default), return plan for review.',
+                default: false,
+            },
+            budgetLimitUSD: {
+                type: 'number',
+                description: 'Optional: abort if estimated cost exceeds this amount.',
+            },
+        },
+        required: ['steps'],
+    },
+};
+// ─── Handler ──────────────────────────────────────────────────────────────────
+export async function handlePlanWorkflow(args, submitWorkflow) {
+    const { steps, execute = false, budgetLimitUSD } = args;
+    log.info({ steps: steps.length, execute, budgetLimitUSD }, 'plan_workflow called');
+    // Always build plan first to show cost/tier breakdown
+    const plan = buildExecutionPlan(steps);
+    const summary = formatPlanSummary(plan);
+    const approvalView = formatPlanForApproval(plan);
+    if (!execute) {
+        return {
+            planId: plan.planId,
+            planHash: plan.planHash,
+            summary,
+            approvalView,
+            tierBreakdown: plan.tierBreakdown,
+            estimatedCostUSD: plan.costComparison.tlciEstimate,
+            savingsPct: plan.costComparison.savingsPct,
+            executed: false,
+        };
+    }
+    // Execute via orchestrator's submitWorkflow.
+    // The dispatcher uses the plan cache, so the same steps will reuse the preview plan's
+    // hash. Use the DispatchResult's planId/planHash as the authoritative IDs to avoid
+    // exposing a preview planId that differs from the executed plan's ID.
+    const dispatchResult = await submitWorkflow(steps, { budgetLimitUSD });
+    return {
+        planId: dispatchResult.planId,
+        planHash: dispatchResult.planHash,
+        summary,
+        approvalView,
+        tierBreakdown: dispatchResult.tierBreakdown,
+        estimatedCostUSD: plan.costComparison.tlciEstimate,
+        savingsPct: plan.costComparison.savingsPct,
+        executed: true,
+        dispatchResult,
+    };
+}
+// ─── Factory: build a CustomToolDefinition wired to a submitWorkflow callback ─
+/**
+ * Create a plan_workflow CustomToolDefinition bound to the given submitWorkflow function.
+ * Pass this into ExecutionLoop's customTools array (via _createCustomTools).
+ *
+ * If submitWorkflow is not provided (plan-only mode), execution requests will
+ * throw a clear error instead of silently failing.
+ */
+export function createPlanWorkflowTool(submitWorkflow) {
+    const noopOrReal = submitWorkflow ?? (async (_steps, _opts) => {
+        throw new Error('plan_workflow: submitWorkflow not available — boot the orchestrator first or set execute:false');
+    });
+    return {
+        name: PLAN_WORKFLOW_TOOL_DEFINITION.name,
+        description: PLAN_WORKFLOW_TOOL_DEFINITION.description,
+        input_schema: PLAN_WORKFLOW_TOOL_DEFINITION.input_schema,
+        handler: async (input) => {
+            const args = input;
+            return handlePlanWorkflow(args, noopOrReal);
+        },
+    };
+}
+//# sourceMappingURL=planning-tool.js.map

package/dist/tools/planning-tool.js.map

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

package/dist/tools/skill-tool.d.ts

@@ -0,0 +1,94 @@
+/**
+ * SkillTool — Exposes the Claude Code skill library to running Zora agents.
+ *
+ * list_skills: discover available skills in ~/.claude/skills/
+ * invoke_skill: load and return a skill's content for injection into context
+ *
+ * Security: invoke_skill checks PolicyEngine.validatePath before loading any
+ * skill content. Skills must exist on disk — no remote loading.
+ *
+ * Usage: call createSkillTools(policyEngine) and spread the result into
+ * _createCustomTools() in the Orchestrator.
+ */
+import type { CustomToolDefinition } from '../orchestrator/execution-loop.js';
+import type { PolicyEngine } from '../security/policy-engine.js';
+export declare const LIST_SKILLS_TOOL_NAME = "list_skills";
+export declare const INVOKE_SKILL_TOOL_NAME = "invoke_skill";
+export declare const LIST_SKILLS_TOOL_DEFINITION: {
+    name: string;
+    description: string;
+    input_schema: {
+        type: "object";
+        properties: {
+            filter: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare const INVOKE_SKILL_TOOL_DEFINITION: {
+    name: string;
+    description: string;
+    input_schema: {
+        type: "object";
+        properties: {
+            name: {
+                type: string;
+                description: string;
+            };
+            context: {
+                type: string;
+                description: string;
+                additionalProperties: {
+                    type: string;
+                };
+            };
+        };
+        required: string[];
+    };
+};
+export interface ListSkillsArgs {
+    filter?: string;
+}
+export interface ListSkillsResult {
+    skills: Array<{
+        name: string;
+        description: string;
+    }>;
+    count: number;
+    skillsDir: string;
+    denied?: boolean;
+}
+export interface InvokeSkillArgs {
+    name: string;
+    context?: Record<string, string>;
+}
+export interface InvokeSkillResult {
+    skillName: string;
+    content: string;
+    path: string;
+}
+/**
+ * Lists available skills, optionally filtered by name substring.
+ * If checkPolicy is provided and denies access to the skills directory,
+ * returns an empty list with denied: true rather than throwing.
+ */
+export declare function handleListSkills(args: ListSkillsArgs, skillsDir?: string, checkPolicy?: (path: string) => Promise<boolean>): Promise<ListSkillsResult>;
+/**
+ * Loads a skill by name and returns its content.
+ * The checkPolicy callback is called before loading — throw or return false to deny.
+ * It is called twice: once for the tool gate, and again for the resolved skill path.
+ */
+export declare function handleInvokeSkill(args: InvokeSkillArgs, checkPolicy: (pathOrTool: string, args?: Record<string, unknown>) => Promise<boolean>, skillsDir?: string): Promise<InvokeSkillResult>;
+/**
+ * Creates list_skills and invoke_skill tool definitions wired to a PolicyEngine.
+ *
+ * The policyEngine is used to validate the skill path before loading content.
+ * If policyEngine is null (e.g. in tests), all invocations are allowed.
+ *
+ * @returns Two CustomToolDefinition entries for the Orchestrator's _createCustomTools()
+ */
+export declare function createSkillTools(policyEngine: PolicyEngine | null): CustomToolDefinition[];
+//# sourceMappingURL=skill-tool.d.ts.map

package/dist/tools/skill-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-tool.d.ts","sourceRoot":"","sources":["../../src/tools/skill-tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AAG9E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAMjE,eAAO,MAAM,qBAAqB,gBAAgB,CAAC;AACnD,eAAO,MAAM,sBAAsB,iBAAiB,CAAC;AAIrD,eAAO,MAAM,2BAA2B;;;;;;;;;;;kBAapB,MAAM,EAAE;;CAE3B,CAAC;AAEF,eAAO,MAAM,4BAA4B;;;;;;;;;;;;;;;;;;kBAsBf,MAAM,EAAE;;CAEjC,CAAC;AAIF,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACrD,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CACd;AAMD;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,cAAc,EACpB,SAAS,SAAa,EACtB,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,GAC/C,OAAO,CAAC,gBAAgB,CAAC,CAmC3B;AAED;;;;GAIG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,eAAe,EACrB,WAAW,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,EACrF,SAAS,SAAa,GACrB,OAAO,CAAC,iBAAiB,CAAC,CAuD5B;AAID;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,YAAY,EAAE,YAAY,GAAG,IAAI,GAChC,oBAAoB,EAAE,CAoDxB"}

package/dist/tools/skill-tool.js

@@ -0,0 +1,202 @@
+/**
+ * SkillTool — Exposes the Claude Code skill library to running Zora agents.
+ *
+ * list_skills: discover available skills in ~/.claude/skills/
+ * invoke_skill: load and return a skill's content for injection into context
+ *
+ * Security: invoke_skill checks PolicyEngine.validatePath before loading any
+ * skill content. Skills must exist on disk — no remote loading.
+ *
+ * Usage: call createSkillTools(policyEngine) and spread the result into
+ * _createCustomTools() in the Orchestrator.
+ */
+import os from 'node:os';
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { loadSkills } from '../skills/skill-loader.js';
+import { createLogger } from '../utils/logger.js';
+const log = createLogger('skill-tool');
+// ─── Tool Names ────────────────────────────────────────────────────────────────
+export const LIST_SKILLS_TOOL_NAME = 'list_skills';
+export const INVOKE_SKILL_TOOL_NAME = 'invoke_skill';
+// ─── Tool Definitions (for documentation/testing) ─────────────────────────────
+export const LIST_SKILLS_TOOL_DEFINITION = {
+    name: LIST_SKILLS_TOOL_NAME,
+    description: 'List all available Claude Code skills from ~/.claude/skills/. ' +
+        'Call this before invoke_skill to confirm the skill exists.',
+    input_schema: {
+        type: 'object',
+        properties: {
+            filter: {
+                type: 'string',
+                description: 'Optional: filter skills by name substring',
+            },
+        },
+        required: [],
+    },
+};
+export const INVOKE_SKILL_TOOL_DEFINITION = {
+    name: INVOKE_SKILL_TOOL_NAME,
+    description: [
+        'Load and return a Claude Code skill by name.',
+        'Skills are reusable prompt templates in ~/.claude/skills/<name>/SKILL.md.',
+        'The skill content is returned as text for injection into your context.',
+        'Call list_skills first to see available skills.',
+    ].join(' '),
+    input_schema: {
+        type: 'object',
+        properties: {
+            name: {
+                type: 'string',
+                description: 'Exact skill name (directory name in ~/.claude/skills/)',
+            },
+            context: {
+                type: 'object',
+                description: 'Optional: key-value pairs for template variable substitution in the skill',
+                additionalProperties: { type: 'string' },
+            },
+        },
+        required: ['name'],
+    },
+};
+// ─── Pure Handlers (testable without PolicyEngine) ────────────────────────────
+const SKILLS_DIR = path.join(os.homedir(), '.claude', 'skills');
+/**
+ * Lists available skills, optionally filtered by name substring.
+ * If checkPolicy is provided and denies access to the skills directory,
+ * returns an empty list with denied: true rather than throwing.
+ */
+export async function handleListSkills(args, skillsDir = SKILLS_DIR, checkPolicy) {
+    if (checkPolicy) {
+        const allowed = await checkPolicy(skillsDir);
+        if (!allowed) {
+            return { skills: [], count: 0, skillsDir, denied: true };
+        }
+    }
+    const all = await loadSkills(skillsDir);
+    // Validate each skill's real path stays within skillsDir (catches symlinks in the dir)
+    const resolvedSkillsDir = await fs.realpath(skillsDir).catch(() => path.resolve(skillsDir));
+    const safe = await Promise.all(all.map(async (s) => {
+        try {
+            const real = await fs.realpath(s.path).catch(() => path.resolve(s.path));
+            return real.startsWith(resolvedSkillsDir + path.sep) ? s : null;
+        }
+        catch {
+            return null;
+        }
+    }));
+    const valid = safe.filter((s) => s !== null);
+    const skills = args.filter
+        ? valid.filter(s => s.name.toLowerCase().includes(args.filter.toLowerCase()))
+        : valid;
+    log.debug({ total: all.length, safe: valid.length, filtered: skills.length }, 'list_skills called');
+    return {
+        skills: skills.map(s => ({ name: s.name, description: s.description })),
+        count: skills.length,
+        skillsDir,
+    };
+}
+/**
+ * Loads a skill by name and returns its content.
+ * The checkPolicy callback is called before loading — throw or return false to deny.
+ * It is called twice: once for the tool gate, and again for the resolved skill path.
+ */
+export async function handleInvokeSkill(args, checkPolicy, skillsDir = SKILLS_DIR) {
+    const { name, context = {} } = args;
+    // Policy check before loading any skill content
+    if (!(await checkPolicy(INVOKE_SKILL_TOOL_NAME, { name }))) {
+        throw new Error(`Policy denied: invoke_skill("${name}")`);
+    }
+    const all = await loadSkills(skillsDir);
+    const skill = all.find(s => s.name === name);
+    if (!skill) {
+        const names = all.map(s => s.name).join(', ');
+        throw new Error(`Skill "${name}" not found. Available: ${names || 'none'}`);
+    }
+    // Use fs.realpath() (not path.resolve) to follow symlinks before checking boundaries.
+    // path.resolve() only normalizes segments; a SKILL.md that is a symlink to /etc/passwd
+    // would pass a path.resolve() check but fail here.
+    // Falls back to path.resolve() when the path doesn't yet exist (e.g. tests with mocks)
+    // — symlinks to non-existent targets can't be exploited since readFile will also fail.
+    let resolvedSkillPath;
+    try {
+        resolvedSkillPath = await fs.realpath(skill.path);
+    }
+    catch {
+        resolvedSkillPath = path.resolve(skill.path);
+    }
+    const resolvedSkillsDir = await fs.realpath(skillsDir).catch(() => path.resolve(skillsDir));
+    if (!resolvedSkillPath.startsWith(resolvedSkillsDir + path.sep) &&
+        resolvedSkillPath !== resolvedSkillsDir) {
+        throw new Error(`Skill path "${resolvedSkillPath}" is outside the skills directory (symlink traversal blocked)`);
+    }
+    // Per-skill policy check on the resolved path
+    const pathAllowed = await checkPolicy(resolvedSkillPath);
+    if (!pathAllowed) {
+        throw new Error(`Access to skill at "${resolvedSkillPath}" denied by policy`);
+    }
+    let content = await fs.readFile(resolvedSkillPath, 'utf-8');
+    // Simple template substitution: {{key}} → value
+    for (const [key, value] of Object.entries(context)) {
+        content = content.replaceAll(`{{${key}}}`, value);
+    }
+    log.info({ skillName: name, contentLength: content.length }, 'skill invoked by agent');
+    return { skillName: name, content, path: skill.path };
+}
+// ─── Factory ───────────────────────────────────────────────────────────────────
+/**
+ * Creates list_skills and invoke_skill tool definitions wired to a PolicyEngine.
+ *
+ * The policyEngine is used to validate the skill path before loading content.
+ * If policyEngine is null (e.g. in tests), all invocations are allowed.
+ *
+ * @returns Two CustomToolDefinition entries for the Orchestrator's _createCustomTools()
+ */
+export function createSkillTools(policyEngine) {
+    // Build a policy check function from the engine.
+    // invoke_skill loads a file from disk — use validatePath to ensure the
+    // skill path is within the policy's allowed filesystem boundaries.
+    // The function accepts either a tool name (with optional args) or a resolved
+    // filesystem path, and returns a Promise<boolean> in both cases.
+    const checkPolicy = async (pathOrTool, _args) => {
+        if (!policyEngine)
+            return true; // no engine → allow (safe default for tests)
+        // For any call, validate the path or skills directory via validatePath.
+        // When called with a tool name, we validate the skills directory root.
+        // When called with a resolved skill path, we validate that specific path.
+        const pathToCheck = pathOrTool === INVOKE_SKILL_TOOL_NAME ? SKILLS_DIR : pathOrTool;
+        const result = policyEngine.validatePath(pathToCheck);
+        if (!result.allowed) {
+            log.warn({ path: pathToCheck, reason: result.reason }, 'skill access blocked by policy');
+            return false;
+        }
+        return true;
+    };
+    const listSkillsTool = {
+        name: LIST_SKILLS_TOOL_NAME,
+        description: LIST_SKILLS_TOOL_DEFINITION.description,
+        input_schema: LIST_SKILLS_TOOL_DEFINITION.input_schema,
+        handler: async (input) => {
+            const args = {
+                filter: input['filter'],
+            };
+            return handleListSkills(args, SKILLS_DIR, checkPolicy);
+        },
+    };
+    const invokeSkillTool = {
+        name: INVOKE_SKILL_TOOL_NAME,
+        description: INVOKE_SKILL_TOOL_DEFINITION.description,
+        input_schema: INVOKE_SKILL_TOOL_DEFINITION.input_schema,
+        handler: async (input) => {
+            const args = {
+                name: input['name'],
+                context: input['context'],
+            };
+            const result = await handleInvokeSkill(args, checkPolicy);
+            // Return a structured object with skillName, content, and path fields
+            return { skillName: result.skillName, content: result.content, path: result.path };
+        },
+    };
+    return [listSkillsTool, invokeSkillTool];
+}
+//# sourceMappingURL=skill-tool.js.map

package/dist/tools/skill-tool.js.map

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

package/dist/tools/subagent-tool.d.ts

@@ -0,0 +1,11 @@
+/**
+ * SubagentTool — delegate_to_subagent custom tool.
+ *
+ * Loads subagent definitions from .zora/subagents/<name>/SUBAGENT.md
+ * and exposes a delegate_to_subagent tool for the LLM to use.
+ */
+import type { CustomToolDefinition } from '../orchestrator/execution-loop.js';
+export declare function createSubagentTools(submitTask: (opts: {
+    prompt: string;
+}) => Promise<string>): CustomToolDefinition[];
+//# sourceMappingURL=subagent-tool.d.ts.map

package/dist/tools/subagent-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagent-tool.d.ts","sourceRoot":"","sources":["../../src/tools/subagent-tool.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AAK9E,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,CAAC,IAAI,EAAE;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,KAAK,OAAO,CAAC,MAAM,CAAC,GACxD,oBAAoB,EAAE,CAmFxB"}

package/dist/tools/subagent-tool.js

@@ -0,0 +1,87 @@
+/**
+ * SubagentTool — delegate_to_subagent custom tool.
+ *
+ * Loads subagent definitions from .zora/subagents/<name>/SUBAGENT.md
+ * and exposes a delegate_to_subagent tool for the LLM to use.
+ */
+import { loadSubagents } from '../skills/subagent-loader.js';
+import { createLogger } from '../utils/logger.js';
+const log = createLogger('subagent-tool');
+export function createSubagentTools(submitTask) {
+    const listSubagentsTool = {
+        name: 'list_subagents',
+        description: 'List available subagents that can be delegated tasks. Each subagent has a specific role and restricted tool access.',
+        input_schema: {
+            type: 'object',
+            properties: {},
+        },
+        handler: async () => {
+            const subagents = await loadSubagents();
+            if (subagents.length === 0) {
+                return { subagents: [], message: 'No subagents defined. Create .zora/subagents/<name>/SUBAGENT.md to define one.' };
+            }
+            return {
+                subagents: subagents.map(s => ({
+                    name: s.name,
+                    description: s.description,
+                    layer: s.layer,
+                    allowedTools: s.allowedTools,
+                })),
+                count: subagents.length,
+            };
+        },
+    };
+    const delegateToSubagentTool = {
+        name: 'delegate_to_subagent',
+        description: 'Delegate a self-contained task to a named subagent. The subagent runs with its declared system prompt and restricted tool subset. Cannot spawn further subagents. Use list_subagents to see available subagents.',
+        input_schema: {
+            type: 'object',
+            properties: {
+                subagent_name: {
+                    type: 'string',
+                    description: 'Name of the subagent (matches the directory name in .zora/subagents/<name>/)',
+                },
+                task: {
+                    type: 'string',
+                    description: 'The specific task to delegate. Be precise — the subagent has no conversation history.',
+                },
+            },
+            required: ['subagent_name', 'task'],
+        },
+        handler: async (input) => {
+            const name = input['subagent_name'];
+            const task = input['task'];
+            if (!name || !task) {
+                return { error: 'subagent_name and task are required' };
+            }
+            const subagents = await loadSubagents();
+            const subagent = subagents.find(s => s.name === name);
+            if (!subagent) {
+                const available = subagents.map(s => s.name);
+                return {
+                    error: `Subagent '${name}' not found.`,
+                    available: available.length > 0 ? available : 'none defined',
+                };
+            }
+            log.info({ subagent: name, taskLength: task.length }, 'Delegating to subagent');
+            try {
+                // NOTE: SubmitTaskOptions does not yet support systemPrompt override.
+                // As a workaround, we prepend the subagent's system prompt as context
+                // in the task prompt. Full systemPrompt threading is tracked as a
+                // follow-up (requires SubmitTaskOptions.systemPrompt field).
+                const augmentedPrompt = subagent.systemPrompt
+                    ? `[Subagent context — follow these instructions throughout this task]\n${subagent.systemPrompt}\n\n[Task]\n${task}`
+                    : task;
+                const result = await submitTask({ prompt: augmentedPrompt });
+                return { result, subagent: name };
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                log.error({ subagent: name, err: msg }, 'Subagent delegation failed');
+                return { error: `Subagent '${name}' failed: ${msg}` };
+            }
+        },
+    };
+    return [listSubagentsTool, delegateToSubagentTool];
+}
+//# sourceMappingURL=subagent-tool.js.map

package/dist/tools/subagent-tool.js.map

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