@crewhaus/tool-task 0.1.3 → 0.1.5

package/dist/index.d.ts

@@ -0,0 +1,38 @@
+import type { SubAgentDefinition } from "@crewhaus/agent-context-isolation";
+import { CrewhausError } from "@crewhaus/errors";
+import type { RegisteredTool } from "@crewhaus/tool-catalog";
+import { z } from "zod";
+export declare class SubAgentResolutionError extends CrewhausError {
+    readonly name = "SubAgentResolutionError";
+    constructor(message: string, cause?: unknown);
+}
+export declare const BUILTIN_GENERAL_PURPOSE: SubAgentDefinition;
+declare const taskInputSchema: z.ZodObject<{
+    description: z.ZodString;
+    prompt: z.ZodString;
+    subagent_type: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    description: string;
+    prompt: string;
+    subagent_type?: string | undefined;
+}, {
+    description: string;
+    prompt: string;
+    subagent_type?: string | undefined;
+}>;
+export type TaskInput = z.infer<typeof taskInputSchema>;
+/**
+ * Parse a `<dir>/<name>.md` sub-agent file. Same shape as SKILL.md: a
+ * leading `---` frontmatter block; the body is the agent instructions.
+ */
+export declare function parseSubAgentFile(content: string, fallbackName?: string): SubAgentDefinition;
+export type CreateTaskToolOptions = {
+    /** Inline spec-supplied sub-agent definitions (highest priority). */
+    readonly subAgents?: ReadonlyMap<string, SubAgentDefinition>;
+    /** Filesystem fallback dir. Defaults to `<cwd>/.crewhaus/sub-agents`. */
+    readonly subAgentDir?: string;
+};
+/** Resolve a sub-agent name to a definition using the documented order. */
+export declare function resolveSubAgentDefinition(name: string | undefined, opts: CreateTaskToolOptions): SubAgentDefinition;
+export declare function createTaskTool(opts?: CreateTaskToolOptions): RegisteredTool;
+export {};

package/dist/index.js

@@ -0,0 +1,232 @@
+/**
+ * Catalog R4 `tool-task` — Section 13.
+ *
+ * The `Task(description, prompt, subagent_type?)` tool. When invoked, it
+ * resolves the named sub-agent definition, builds the child's tool catalog,
+ * resolves child permissions, and dispatches `bridge.spawnSubAgent`.
+ * Returns the child's final assistant text as the tool result so the parent
+ * model can react to the child's verdict.
+ *
+ * Resolution order for `subagent_type`:
+ *   1. `opts.subAgents.get(name)` — inline spec map (codegen-supplied).
+ *   2. `<opts.subAgentDir or cwd/.crewhaus/sub-agents>/<name>.md` — frontmatter
+ *      file on disk. Format mirrors SKILL.md: leading `---` YAML block, body
+ *      becomes `instructions`.
+ *   3. Built-in `general-purpose` fallback.
+ *
+ * Concurrency: marked `concurrencySafe: true` because parallel sub-agents
+ * are independent — each gets its own IsolatedContext. T7 in
+ * sub-agent-spawner exercises 10-way parallelism end-to-end.
+ *
+ * The bridge is opaque from `tool-catalog`'s perspective; we cast inside
+ * `execute` so ordinary tools (which never touch `ctx.bridge`) keep their
+ * unchanged shape. If the bridge is missing the `Task` tool returns a
+ * clean error result rather than crashing the turn — that case only
+ * occurs when callers wire `Task` into a `runChatLoop` invocation that
+ * doesn't pass `spawnSubAgent`.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { CrewhausError } from "@crewhaus/errors";
+import { resolveChildPermissions } from "@crewhaus/sub-agent-permission-inheritance";
+import { buildTool } from "@crewhaus/tool-builder";
+import { parse as parseYaml } from "yaml";
+import { z } from "zod";
+export class SubAgentResolutionError extends CrewhausError {
+    name = "SubAgentResolutionError";
+    constructor(message, cause) {
+        super("config", message, cause);
+    }
+}
+export const BUILTIN_GENERAL_PURPOSE = {
+    name: "general-purpose",
+    description: "General-purpose sub-agent. Pass it a task and it will use the parent's tools (filtered by inherited permissions) to complete it and return a single summary.",
+    instructions: "You are a sub-agent invoked by another agent via the Task tool. Complete the user's task using whatever tools you have. When you have an answer, respond with a single concise final message — your reply is what the parent agent will see.",
+    // Tools list undefined → child inherits parent's full tool catalog (subject to permissions).
+    permissions: "inherit",
+};
+const taskInputSchema = z.object({
+    description: z
+        .string()
+        .min(1)
+        .describe("Short label for the sub-task (e.g. 'review the auth flow')."),
+    prompt: z.string().min(1).describe("Full instructions/context the sub-agent should act on."),
+    subagent_type: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Name of the sub-agent definition to spawn. Falls back to 'general-purpose' if omitted."),
+});
+const FRONTMATTER_SCHEMA = z.object({
+    name: z.string().min(1),
+    description: z.string().min(1),
+    tools: z.array(z.string().min(1)).optional(),
+    model: z.string().min(1).optional(),
+    permissions: z
+        .union([
+        z.enum(["inherit", "scoped"]),
+        z.object({ allow: z.array(z.string()), deny: z.array(z.string()) }).strict(),
+    ])
+        .optional(),
+    inherit_bypass: z.boolean().optional(),
+});
+/**
+ * Parse a `<dir>/<name>.md` sub-agent file. Same shape as SKILL.md: a
+ * leading `---` frontmatter block; the body is the agent instructions.
+ */
+export function parseSubAgentFile(content, fallbackName) {
+    const trimmed = content.replace(/^/, "");
+    if (!trimmed.startsWith("---")) {
+        throw new SubAgentResolutionError("sub-agent file must start with `---` frontmatter delimiter");
+    }
+    const firstNl = trimmed.indexOf("\n");
+    if (firstNl === -1) {
+        throw new SubAgentResolutionError("sub-agent file frontmatter never terminated");
+    }
+    const closer = trimmed.indexOf("\n---", firstNl);
+    if (closer === -1) {
+        throw new SubAgentResolutionError("sub-agent file frontmatter never terminated");
+    }
+    const fmRaw = trimmed.slice(firstNl + 1, closer).trimEnd();
+    const bodyStart = trimmed.indexOf("\n", closer + 4);
+    const body = bodyStart === -1 ? "" : trimmed.slice(bodyStart + 1).trim();
+    let parsedYaml;
+    try {
+        parsedYaml = parseYaml(fmRaw);
+    }
+    catch (err) {
+        throw new SubAgentResolutionError(`sub-agent frontmatter is not valid YAML: ${err.message}`);
+    }
+    const parsed = FRONTMATTER_SCHEMA.safeParse(parsedYaml);
+    if (!parsed.success) {
+        const issue = parsed.error.issues[0];
+        const path = issue && issue.path.length > 0 ? issue.path.join(".") : "(root)";
+        const message = issue ? issue.message : "validation failed";
+        throw new SubAgentResolutionError(`sub-agent frontmatter ${path}: ${message}`);
+    }
+    if (body.length === 0) {
+        throw new SubAgentResolutionError("sub-agent file has empty body — instructions required");
+    }
+    const def = {
+        name: parsed.data.name || fallbackName || "(unnamed)",
+        description: parsed.data.description,
+        instructions: body,
+        ...(parsed.data.tools !== undefined ? { tools: parsed.data.tools } : {}),
+        ...(parsed.data.model !== undefined ? { model: parsed.data.model } : {}),
+        ...(parsed.data.permissions !== undefined ? { permissions: parsed.data.permissions } : {}),
+        ...(parsed.data.inherit_bypass !== undefined
+            ? { inherit_bypass: parsed.data.inherit_bypass }
+            : {}),
+    };
+    return def;
+}
+function loadSubAgentFromDisk(name, dir) {
+    const filePath = join(dir, `${name}.md`);
+    if (!existsSync(filePath))
+        return null;
+    const content = readFileSync(filePath, "utf-8");
+    return parseSubAgentFile(content, name);
+}
+/**
+ * `subagent_type` is a model-filled tool argument and model output is
+ * attacker-steerable (via any untrusted input). It becomes a filesystem path
+ * segment in `loadSubAgentFromDisk` (`join(dir, `${name}.md`)`), and `join`
+ * resolves `..` and path separators — so an unsanitized name like
+ * `../../../tmp/evil` reads an arbitrary `.md` on the host and loads it as a
+ * sub-agent definition. Reject anything that isn't a single safe path
+ * component before it reaches the disk lookup. Inline spec-supplied names are
+ * exact-key map lookups that never touch the filesystem, so they are resolved
+ * first (above) and are unaffected.
+ */
+function isUnsafeSubAgentName(name) {
+    return (name.includes("/") ||
+        name.includes("\\") ||
+        name.includes("\0") ||
+        name === "." ||
+        name === "..");
+}
+/** Resolve a sub-agent name to a definition using the documented order. */
+export function resolveSubAgentDefinition(name, opts) {
+    const resolveName = name ?? "general-purpose";
+    if (opts.subAgents !== undefined) {
+        const inline = opts.subAgents.get(resolveName);
+        if (inline !== undefined)
+            return inline;
+    }
+    // Guard the disk lookup against path traversal (the inline map above is an
+    // exact-key lookup and is intentionally not gated).
+    if (isUnsafeSubAgentName(resolveName)) {
+        throw new SubAgentResolutionError(`invalid subagent_type "${resolveName}" — must not contain path separators, "..", ".", or NUL bytes`);
+    }
+    const dir = opts.subAgentDir ?? join(process.cwd(), ".crewhaus", "sub-agents");
+    const onDisk = loadSubAgentFromDisk(resolveName, dir);
+    if (onDisk !== null)
+        return onDisk;
+    if (resolveName === "general-purpose")
+        return BUILTIN_GENERAL_PURPOSE;
+    throw new SubAgentResolutionError(`unknown subagent_type "${resolveName}" — not in spec sub_agents map, not on disk at ${dir}, and no built-in by that name`);
+}
+/**
+ * Build the child catalog by filtering the parent catalog to the
+ * tool-name allowlist on the definition. Undefined `def.tools` (with
+ * `permissions: "inherit"`) → the child inherits the parent's full
+ * catalog. Undefined `def.tools` with any other permission mode → empty
+ * child catalog (the user has implicitly opted out).
+ */
+function buildChildCatalog(parentTools, def) {
+    const allowed = def.tools;
+    if (allowed === undefined) {
+        return def.permissions === undefined || def.permissions === "inherit" ? parentTools : [];
+    }
+    const allowlist = new Set(allowed);
+    return parentTools.filter((t) => allowlist.has(t.name));
+}
+export function createTaskTool(opts = {}) {
+    const knownNames = opts.subAgents !== undefined ? [...opts.subAgents.keys()] : [];
+    const description = knownNames.length === 0
+        ? "Spawn a sub-agent to handle a delegated task. Pass a `description` (label) and a `prompt` (the task instructions). The sub-agent runs in an isolated context and returns a single final message."
+        : `Spawn a sub-agent to handle a delegated task. Pass a \`description\` (label), a \`prompt\` (the task instructions), and optionally a \`subagent_type\` to pick a specialist. Available subagent_type values: ${knownNames.join(", ")}. The sub-agent runs in an isolated context and returns a single final message.`;
+    return buildTool({
+        name: "Task",
+        description,
+        inputSchema: taskInputSchema,
+        concurrencySafe: true,
+        readOnly: false,
+        destructive: false,
+        execute: async (input, ctx) => {
+            const bridge = ctx?.bridge;
+            if (bridge === undefined || bridge.spawnSubAgent === undefined) {
+                return "[Task error] runtime bridge is not available — Task can only be invoked from runChatLoop with sub-agent support enabled.";
+            }
+            const spawnSubAgent = bridge.spawnSubAgent;
+            let def;
+            try {
+                def = resolveSubAgentDefinition(input.subagent_type, opts);
+            }
+            catch (err) {
+                return `[Task error] ${err.message}`;
+            }
+            const childTools = buildChildCatalog(bridge.tools, def);
+            const childPerms = resolveChildPermissions({ mode: bridge.permissionMode, rules: bridge.permissionRules }, def);
+            const parentHandle = {
+                runContext: bridge.runContext,
+                eventLog: bridge.eventLog,
+                permissionMode: bridge.permissionMode,
+                permissionRules: bridge.permissionRules,
+                tools: bridge.tools,
+                model: bridge.model,
+                maxTokens: bridge.maxTokens,
+                ...(bridge.sessionRootDir !== undefined ? { sessionRootDir: bridge.sessionRootDir } : {}),
+            };
+            const result = await spawnSubAgent(parentHandle, {
+                def,
+                prompt: input.prompt,
+                permissionMode: childPerms.mode,
+                permissionRules: childPerms.rules,
+                childTools,
+                ...(bridge.sessionRootDir !== undefined ? { sessionRootDir: bridge.sessionRootDir } : {}),
+            });
+            return result.finalMessage;
+        },
+    });
+}

package/package.json

@@ -1,29 +1,32 @@
 {
   "name": "@crewhaus/tool-task",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "type": "module",
   "description": "Task(description, prompt, subagent_type?) tool — spawns a sub-agent and returns its final message (Section 13)",
-  "main": "src/index.ts",
-  "types": "src/index.ts",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "exports": {
-    ".": "./src/index.ts"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
   },
   "scripts": {
     "test": "bun test src"
   },
   "dependencies": {
-    "@crewhaus/agent-context-isolation": "0.1.3",
-    "@crewhaus/errors": "0.1.3",
-    "@crewhaus/sub-agent-permission-inheritance": "0.1.3",
-    "@crewhaus/tool-builder": "0.1.3",
-    "@crewhaus/tool-catalog": "0.1.3",
+    "@crewhaus/agent-context-isolation": "0.1.5",
+    "@crewhaus/errors": "0.1.5",
+    "@crewhaus/sub-agent-permission-inheritance": "0.1.5",
+    "@crewhaus/tool-builder": "0.1.5",
+    "@crewhaus/tool-catalog": "0.1.5",
     "yaml": "^2.6.0",
     "zod": "^3.23.8"
   },
   "devDependencies": {
-    "@crewhaus/event-log": "0.1.3",
-    "@crewhaus/permission-engine": "0.1.3",
-    "@crewhaus/run-context": "0.1.3"
+    "@crewhaus/event-log": "0.1.5",
+    "@crewhaus/permission-engine": "0.1.5",
+    "@crewhaus/run-context": "0.1.5"
   },
   "license": "Apache-2.0",
   "author": {
@@ -43,5 +46,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "files": ["src", "README.md", "LICENSE", "NOTICE"]
+  "files": ["dist", "README.md", "LICENSE", "NOTICE"]
 }

package/src/index.test.ts

@@ -1,373 +0,0 @@
-import { describe, expect, mock, test } from "bun:test";
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import type {
-  ParentRunHandle,
-  RuntimeBridge,
-  SpawnSubAgentFn,
-  SpawnSubAgentOptions,
-  SubAgentDefinition,
-  SubAgentResult,
-} from "@crewhaus/agent-context-isolation";
-import { type EventLog, openEventLog } from "@crewhaus/event-log";
-import { emptyRuleSet } from "@crewhaus/permission-engine";
-import { createRunContext } from "@crewhaus/run-context";
-import { buildTool } from "@crewhaus/tool-builder";
-import type { RegisteredTool } from "@crewhaus/tool-catalog";
-import { z } from "zod";
-import {
-  BUILTIN_GENERAL_PURPOSE,
-  createTaskTool,
-  parseSubAgentFile,
-  resolveSubAgentDefinition,
-} from "./index.js";
-
-function newTempDir(): string {
-  return mkdtempSync(join(tmpdir(), "tool-task-"));
-}
-
-function makeReadTool(): RegisteredTool {
-  return buildTool({
-    name: "Read",
-    description: "read",
-    inputSchema: z.object({}),
-    execute: async () => "ok",
-    readOnly: true,
-    concurrencySafe: true,
-  });
-}
-
-function makeBashTool(): RegisteredTool {
-  return buildTool({
-    name: "Bash",
-    description: "shell",
-    inputSchema: z.object({}),
-    execute: async () => "ok",
-    destructive: true,
-  });
-}
-
-async function makeBridge(
-  rootDir: string,
-  spawn: SpawnSubAgentFn,
-  parentTools: ReadonlyArray<RegisteredTool>,
-): Promise<{ bridge: RuntimeBridge; close: () => Promise<void> }> {
-  const ac = new AbortController();
-  const runContext = createRunContext({ abortSignal: ac.signal });
-  const eventLog: EventLog = await openEventLog(runContext.sessionId, { rootDir });
-  const parent: ParentRunHandle = {
-    runContext,
-    eventLog,
-    permissionMode: "default",
-    permissionRules: { ...emptyRuleSet },
-    tools: parentTools,
-    model: "test-model",
-    maxTokens: 1024,
-    sessionRootDir: rootDir,
-  };
-  const bridge: RuntimeBridge = {
-    ...parent,
-    hooks: [],
-    spawnSubAgent: spawn,
-  };
-  return {
-    bridge,
-    close: async () => {
-      await eventLog.close();
-    },
-  };
-}
-
-describe("parseSubAgentFile", () => {
-  test("extracts frontmatter and body", () => {
-    const content = `---
-name: code-reviewer
-description: reviews code thoroughly
-tools:
-  - Read
-  - Grep
----
-You are a code reviewer.`;
-    const def = parseSubAgentFile(content);
-    expect(def.name).toBe("code-reviewer");
-    expect(def.description).toBe("reviews code thoroughly");
-    expect(def.tools).toEqual(["Read", "Grep"]);
-    expect(def.instructions).toBe("You are a code reviewer.");
-  });
-
-  test("rejects missing frontmatter", () => {
-    expect(() => parseSubAgentFile("just body, no fm")).toThrow(/frontmatter delimiter/);
-  });
-
-  test("rejects unterminated frontmatter", () => {
-    expect(() => parseSubAgentFile("---\nname: x\ndescription: y")).toThrow(/never terminated/);
-  });
-
-  test("rejects empty body", () => {
-    expect(() =>
-      parseSubAgentFile(`---
-name: x
-description: y
----
-`),
-    ).toThrow(/empty body/);
-  });
-
-  test("falls back to file name when name is omitted from frontmatter", () => {
-    // The schema requires name explicitly so this raises a validation error;
-    // confirm the error path is hit cleanly.
-    expect(() =>
-      parseSubAgentFile(
-        `---
-description: missing name
----
-body`,
-        "fallback",
-      ),
-    ).toThrow(/name/);
-  });
-});
-
-describe("resolveSubAgentDefinition", () => {
-  test("inline map wins over disk + builtin", () => {
-    const inline: SubAgentDefinition = {
-      name: "summarizer",
-      description: "inline def",
-      instructions: "summarize.",
-      tools: [],
-    };
-    const out = resolveSubAgentDefinition("summarizer", {
-      subAgents: new Map([["summarizer", inline]]),
-    });
-    expect(out).toBe(inline);
-  });
-
-  test("falls back to disk when not in inline map", () => {
-    const dir = newTempDir();
-    try {
-      writeFileSync(
-        join(dir, "ondisk.md"),
-        `---
-name: ondisk
-description: from disk
----
-disk instructions`,
-      );
-      const out = resolveSubAgentDefinition("ondisk", { subAgentDir: dir });
-      expect(out.name).toBe("ondisk");
-      expect(out.instructions).toBe("disk instructions");
-    } finally {
-      rmSync(dir, { recursive: true, force: true });
-    }
-  });
-
-  test("falls back to general-purpose for that exact name", () => {
-    const out = resolveSubAgentDefinition("general-purpose", {});
-    expect(out).toBe(BUILTIN_GENERAL_PURPOSE);
-  });
-
-  test("undefined subagent_type → general-purpose", () => {
-    const out = resolveSubAgentDefinition(undefined, {});
-    expect(out.name).toBe("general-purpose");
-  });
-
-  test("unknown name with no inline + no disk + not general-purpose → throws", () => {
-    expect(() =>
-      resolveSubAgentDefinition("nonexistent", { subAgentDir: "/tmp/does-not-exist-xyz" }),
-    ).toThrow(/unknown subagent_type/);
-  });
-
-  // SECURITY: subagent_type is model-filled and becomes `join(dir, name+".md")`,
-  // so an unsanitized `..`/separator escapes the sub-agent dir and loads an
-  // arbitrary host .md as a sub-agent definition. Must be rejected.
-  test.each([
-    "../../../../etc/passwd",
-    "../sibling",
-    "foo/bar",
-    "foo\\bar",
-    "..",
-    ".",
-    "a/../../b",
-  ])("rejects path-traversal subagent_type %p", (evil) => {
-    expect(() =>
-      resolveSubAgentDefinition(evil, { subAgentDir: "/tmp/does-not-exist-xyz" }),
-    ).toThrow(/invalid subagent_type/);
-  });
-
-  test("path-traversal is rejected even when an inline map is present (disk path is the sink)", () => {
-    expect(() =>
-      resolveSubAgentDefinition("../../tmp/evil", {
-        subAgents: new Map(),
-        subAgentDir: "/tmp/does-not-exist-xyz",
-      }),
-    ).toThrow(/invalid subagent_type/);
-  });
-
-  test("ordinary names with dots that are not traversal still resolve via disk", () => {
-    const dir = newTempDir();
-    try {
-      writeFileSync(
-        join(dir, "my.agent.md"),
-        "---\nname: my.agent\ndescription: d\n---\ndo the thing\n",
-      );
-      const out = resolveSubAgentDefinition("my.agent", { subAgentDir: dir });
-      expect(out.name).toBe("my.agent");
-    } finally {
-      rmSync(dir, { recursive: true, force: true });
-    }
-  });
-});
-
-describe("createTaskTool — execute round-trip", () => {
-  test("calls bridge.spawnSubAgent with resolved def + filtered tools, returns finalMessage", async () => {
-    const root = newTempDir();
-    try {
-      const calls: SpawnSubAgentOptions[] = [];
-      const spawn: SpawnSubAgentFn = mock(async (_parent, opts) => {
-        calls.push(opts);
-        return {
-          finalMessage: `child saw: ${opts.prompt}`,
-          transcript: [],
-          toolCalls: [],
-          usage: { input_tokens: 0, output_tokens: 0 },
-        } satisfies SubAgentResult;
-      });
-      const parentTools = [makeReadTool(), makeBashTool()];
-      const { bridge, close } = await makeBridge(root, spawn, parentTools);
-
-      const inline: SubAgentDefinition = {
-        name: "code-reviewer",
-        description: "scoped reviewer",
-        instructions: "review",
-        tools: ["Read"],
-        permissions: "scoped",
-      };
-      const tool = createTaskTool({ subAgents: new Map([["code-reviewer", inline]]) });
-
-      const result = await tool.execute(
-        { description: "review", prompt: "look at this", subagent_type: "code-reviewer" },
-        { bridge },
-      );
-
-      expect(result).toBe("child saw: look at this");
-      expect(calls).toHaveLength(1);
-      const called = calls[0];
-      expect(called?.def).toBe(inline);
-      expect(called?.permissionMode).toBe("default");
-      // Bash filtered out, only Read survives.
-      expect(called?.childTools.map((t) => t.name)).toEqual(["Read"]);
-      await close();
-    } finally {
-      rmSync(root, { recursive: true, force: true });
-    }
-  });
-
-  test("returns clean error when bridge is missing", async () => {
-    const tool = createTaskTool({});
-    const result = await tool.execute({ description: "x", prompt: "y" }, { signal: undefined });
-    expect(result).toContain("[Task error]");
-    expect(result).toContain("runtime bridge");
-  });
-
-  test("returns error result on unknown subagent_type", async () => {
-    const root = newTempDir();
-    try {
-      const spawn: SpawnSubAgentFn = mock(async () => {
-        throw new Error("should not be called");
-      });
-      const { bridge, close } = await makeBridge(root, spawn, []);
-      const tool = createTaskTool({ subAgentDir: "/tmp/nope-xyz-doesntexist" });
-      const result = await tool.execute(
-        { description: "x", prompt: "y", subagent_type: "ghost" },
-        { bridge },
-      );
-      expect(result).toContain("[Task error]");
-      expect(result).toContain("ghost");
-      await close();
-    } finally {
-      rmSync(root, { recursive: true, force: true });
-    }
-  });
-
-  test("filesystem fallback resolves a sub-agent definition from .crewhaus/sub-agents", async () => {
-    const root = newTempDir();
-    const subAgentDir = join(root, "subs");
-    mkdirSync(subAgentDir, { recursive: true });
-    writeFileSync(
-      join(subAgentDir, "fooagent.md"),
-      `---
-name: fooagent
-description: hello
-tools:
-  - Read
-permissions: scoped
----
-Be brief.`,
-    );
-    try {
-      let captured: SubAgentDefinition | undefined;
-      const spawn: SpawnSubAgentFn = mock(async (_p, opts) => {
-        captured = opts.def;
-        return {
-          finalMessage: "ok",
-          transcript: [],
-          toolCalls: [],
-          usage: { input_tokens: 0, output_tokens: 0 },
-        };
-      });
-      const { bridge, close } = await makeBridge(root, spawn, [makeReadTool()]);
-      const tool = createTaskTool({ subAgentDir });
-      const result = await tool.execute(
-        { description: "x", prompt: "y", subagent_type: "fooagent" },
-        { bridge },
-      );
-      expect(result).toBe("ok");
-      expect(captured?.name).toBe("fooagent");
-      expect(captured?.instructions).toBe("Be brief.");
-      expect(captured?.tools).toEqual(["Read"]);
-      await close();
-    } finally {
-      rmSync(root, { recursive: true, force: true });
-    }
-  });
-
-  test("def.tools=[] yields empty child catalog (full permission isolation)", async () => {
-    const root = newTempDir();
-    try {
-      let captured: ReadonlyArray<RegisteredTool> | undefined;
-      const spawn: SpawnSubAgentFn = mock(async (_p, opts) => {
-        captured = opts.childTools;
-        return {
-          finalMessage: "denied",
-          transcript: [],
-          toolCalls: [],
-          usage: { input_tokens: 0, output_tokens: 0 },
-        };
-      });
-      const parentTools = [makeReadTool(), makeBashTool()];
-      const { bridge, close } = await makeBridge(root, spawn, parentTools);
-      const inline: SubAgentDefinition = {
-        name: "no-tools",
-        description: "no tools",
-        instructions: "x",
-        tools: [],
-        permissions: "scoped",
-      };
-      const tool = createTaskTool({ subAgents: new Map([["no-tools", inline]]) });
-      await tool.execute({ description: "x", prompt: "y", subagent_type: "no-tools" }, { bridge });
-      expect(captured).toEqual([]);
-      await close();
-    } finally {
-      rmSync(root, { recursive: true, force: true });
-    }
-  });
-
-  test("metadata: concurrencySafe=true, readOnly=false, destructive=false", () => {
-    const tool = createTaskTool();
-    expect(tool.name).toBe("Task");
-    expect(tool.concurrencySafe).toBe(true);
-    expect(tool.readOnly).toBe(false);
-    expect(tool.destructive).toBe(false);
-  });
-});

package/src/index.ts

@@ -1,275 +0,0 @@
-/**
- * Catalog R4 `tool-task` — Section 13.
- *
- * The `Task(description, prompt, subagent_type?)` tool. When invoked, it
- * resolves the named sub-agent definition, builds the child's tool catalog,
- * resolves child permissions, and dispatches `bridge.spawnSubAgent`.
- * Returns the child's final assistant text as the tool result so the parent
- * model can react to the child's verdict.
- *
- * Resolution order for `subagent_type`:
- *   1. `opts.subAgents.get(name)` — inline spec map (codegen-supplied).
- *   2. `<opts.subAgentDir or cwd/.crewhaus/sub-agents>/<name>.md` — frontmatter
- *      file on disk. Format mirrors SKILL.md: leading `---` YAML block, body
- *      becomes `instructions`.
- *   3. Built-in `general-purpose` fallback.
- *
- * Concurrency: marked `concurrencySafe: true` because parallel sub-agents
- * are independent — each gets its own IsolatedContext. T7 in
- * sub-agent-spawner exercises 10-way parallelism end-to-end.
- *
- * The bridge is opaque from `tool-catalog`'s perspective; we cast inside
- * `execute` so ordinary tools (which never touch `ctx.bridge`) keep their
- * unchanged shape. If the bridge is missing the `Task` tool returns a
- * clean error result rather than crashing the turn — that case only
- * occurs when callers wire `Task` into a `runChatLoop` invocation that
- * doesn't pass `spawnSubAgent`.
- */
-import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
-import type { RuntimeBridge, SubAgentDefinition } from "@crewhaus/agent-context-isolation";
-import { CrewhausError } from "@crewhaus/errors";
-import { resolveChildPermissions } from "@crewhaus/sub-agent-permission-inheritance";
-import { buildTool } from "@crewhaus/tool-builder";
-import type { RegisteredTool } from "@crewhaus/tool-catalog";
-import { parse as parseYaml } from "yaml";
-import { z } from "zod";
-
-export class SubAgentResolutionError extends CrewhausError {
-  override readonly name = "SubAgentResolutionError";
-  constructor(message: string, cause?: unknown) {
-    super("config", message, cause);
-  }
-}
-
-export const BUILTIN_GENERAL_PURPOSE: SubAgentDefinition = {
-  name: "general-purpose",
-  description:
-    "General-purpose sub-agent. Pass it a task and it will use the parent's tools (filtered by inherited permissions) to complete it and return a single summary.",
-  instructions:
-    "You are a sub-agent invoked by another agent via the Task tool. Complete the user's task using whatever tools you have. When you have an answer, respond with a single concise final message — your reply is what the parent agent will see.",
-  // Tools list undefined → child inherits parent's full tool catalog (subject to permissions).
-  permissions: "inherit",
-};
-
-const taskInputSchema = z.object({
-  description: z
-    .string()
-    .min(1)
-    .describe("Short label for the sub-task (e.g. 'review the auth flow')."),
-  prompt: z.string().min(1).describe("Full instructions/context the sub-agent should act on."),
-  subagent_type: z
-    .string()
-    .min(1)
-    .optional()
-    .describe(
-      "Name of the sub-agent definition to spawn. Falls back to 'general-purpose' if omitted.",
-    ),
-});
-
-export type TaskInput = z.infer<typeof taskInputSchema>;
-
-const FRONTMATTER_SCHEMA = z.object({
-  name: z.string().min(1),
-  description: z.string().min(1),
-  tools: z.array(z.string().min(1)).optional(),
-  model: z.string().min(1).optional(),
-  permissions: z
-    .union([
-      z.enum(["inherit", "scoped"]),
-      z.object({ allow: z.array(z.string()), deny: z.array(z.string()) }).strict(),
-    ])
-    .optional(),
-  inherit_bypass: z.boolean().optional(),
-});
-
-/**
- * Parse a `<dir>/<name>.md` sub-agent file. Same shape as SKILL.md: a
- * leading `---` frontmatter block; the body is the agent instructions.
- */
-export function parseSubAgentFile(content: string, fallbackName?: string): SubAgentDefinition {
-  const trimmed = content.replace(/^/, "");
-  if (!trimmed.startsWith("---")) {
-    throw new SubAgentResolutionError("sub-agent file must start with `---` frontmatter delimiter");
-  }
-  const firstNl = trimmed.indexOf("\n");
-  if (firstNl === -1) {
-    throw new SubAgentResolutionError("sub-agent file frontmatter never terminated");
-  }
-  const closer = trimmed.indexOf("\n---", firstNl);
-  if (closer === -1) {
-    throw new SubAgentResolutionError("sub-agent file frontmatter never terminated");
-  }
-  const fmRaw = trimmed.slice(firstNl + 1, closer).trimEnd();
-  const bodyStart = trimmed.indexOf("\n", closer + 4);
-  const body = bodyStart === -1 ? "" : trimmed.slice(bodyStart + 1).trim();
-
-  let parsedYaml: unknown;
-  try {
-    parsedYaml = parseYaml(fmRaw);
-  } catch (err) {
-    throw new SubAgentResolutionError(
-      `sub-agent frontmatter is not valid YAML: ${(err as Error).message}`,
-    );
-  }
-  const parsed = FRONTMATTER_SCHEMA.safeParse(parsedYaml);
-  if (!parsed.success) {
-    const issue = parsed.error.issues[0];
-    const path = issue && issue.path.length > 0 ? issue.path.join(".") : "(root)";
-    const message = issue ? issue.message : "validation failed";
-    throw new SubAgentResolutionError(`sub-agent frontmatter ${path}: ${message}`);
-  }
-  if (body.length === 0) {
-    throw new SubAgentResolutionError("sub-agent file has empty body — instructions required");
-  }
-  const def: SubAgentDefinition = {
-    name: parsed.data.name || fallbackName || "(unnamed)",
-    description: parsed.data.description,
-    instructions: body,
-    ...(parsed.data.tools !== undefined ? { tools: parsed.data.tools } : {}),
-    ...(parsed.data.model !== undefined ? { model: parsed.data.model } : {}),
-    ...(parsed.data.permissions !== undefined ? { permissions: parsed.data.permissions } : {}),
-    ...(parsed.data.inherit_bypass !== undefined
-      ? { inherit_bypass: parsed.data.inherit_bypass }
-      : {}),
-  };
-  return def;
-}
-
-function loadSubAgentFromDisk(name: string, dir: string): SubAgentDefinition | null {
-  const filePath = join(dir, `${name}.md`);
-  if (!existsSync(filePath)) return null;
-  const content = readFileSync(filePath, "utf-8");
-  return parseSubAgentFile(content, name);
-}
-
-/**
- * `subagent_type` is a model-filled tool argument and model output is
- * attacker-steerable (via any untrusted input). It becomes a filesystem path
- * segment in `loadSubAgentFromDisk` (`join(dir, `${name}.md`)`), and `join`
- * resolves `..` and path separators — so an unsanitized name like
- * `../../../tmp/evil` reads an arbitrary `.md` on the host and loads it as a
- * sub-agent definition. Reject anything that isn't a single safe path
- * component before it reaches the disk lookup. Inline spec-supplied names are
- * exact-key map lookups that never touch the filesystem, so they are resolved
- * first (above) and are unaffected.
- */
-function isUnsafeSubAgentName(name: string): boolean {
-  return (
-    name.includes("/") ||
-    name.includes("\\") ||
-    name.includes("\0") ||
-    name === "." ||
-    name === ".."
-  );
-}
-
-export type CreateTaskToolOptions = {
-  /** Inline spec-supplied sub-agent definitions (highest priority). */
-  readonly subAgents?: ReadonlyMap<string, SubAgentDefinition>;
-  /** Filesystem fallback dir. Defaults to `<cwd>/.crewhaus/sub-agents`. */
-  readonly subAgentDir?: string;
-};
-
-/** Resolve a sub-agent name to a definition using the documented order. */
-export function resolveSubAgentDefinition(
-  name: string | undefined,
-  opts: CreateTaskToolOptions,
-): SubAgentDefinition {
-  const resolveName = name ?? "general-purpose";
-  if (opts.subAgents !== undefined) {
-    const inline = opts.subAgents.get(resolveName);
-    if (inline !== undefined) return inline;
-  }
-  // Guard the disk lookup against path traversal (the inline map above is an
-  // exact-key lookup and is intentionally not gated).
-  if (isUnsafeSubAgentName(resolveName)) {
-    throw new SubAgentResolutionError(
-      `invalid subagent_type "${resolveName}" — must not contain path separators, "..", ".", or NUL bytes`,
-    );
-  }
-  const dir = opts.subAgentDir ?? join(process.cwd(), ".crewhaus", "sub-agents");
-  const onDisk = loadSubAgentFromDisk(resolveName, dir);
-  if (onDisk !== null) return onDisk;
-  if (resolveName === "general-purpose") return BUILTIN_GENERAL_PURPOSE;
-  throw new SubAgentResolutionError(
-    `unknown subagent_type "${resolveName}" — not in spec sub_agents map, not on disk at ${dir}, and no built-in by that name`,
-  );
-}
-
-/**
- * Build the child catalog by filtering the parent catalog to the
- * tool-name allowlist on the definition. Undefined `def.tools` (with
- * `permissions: "inherit"`) → the child inherits the parent's full
- * catalog. Undefined `def.tools` with any other permission mode → empty
- * child catalog (the user has implicitly opted out).
- */
-function buildChildCatalog(
-  parentTools: ReadonlyArray<RegisteredTool>,
-  def: SubAgentDefinition,
-): ReadonlyArray<RegisteredTool> {
-  const allowed = def.tools;
-  if (allowed === undefined) {
-    return def.permissions === undefined || def.permissions === "inherit" ? parentTools : [];
-  }
-  const allowlist = new Set(allowed);
-  return parentTools.filter((t) => allowlist.has(t.name));
-}
-
-export function createTaskTool(opts: CreateTaskToolOptions = {}): RegisteredTool {
-  const knownNames = opts.subAgents !== undefined ? [...opts.subAgents.keys()] : [];
-  const description =
-    knownNames.length === 0
-      ? "Spawn a sub-agent to handle a delegated task. Pass a `description` (label) and a `prompt` (the task instructions). The sub-agent runs in an isolated context and returns a single final message."
-      : `Spawn a sub-agent to handle a delegated task. Pass a \`description\` (label), a \`prompt\` (the task instructions), and optionally a \`subagent_type\` to pick a specialist. Available subagent_type values: ${knownNames.join(", ")}. The sub-agent runs in an isolated context and returns a single final message.`;
-
-  return buildTool({
-    name: "Task",
-    description,
-    inputSchema: taskInputSchema,
-    concurrencySafe: true,
-    readOnly: false,
-    destructive: false,
-    execute: async (input, ctx) => {
-      const bridge = ctx?.bridge as RuntimeBridge | undefined;
-      if (bridge === undefined || bridge.spawnSubAgent === undefined) {
-        return "[Task error] runtime bridge is not available — Task can only be invoked from runChatLoop with sub-agent support enabled.";
-      }
-      const spawnSubAgent = bridge.spawnSubAgent;
-      let def: SubAgentDefinition;
-      try {
-        def = resolveSubAgentDefinition(input.subagent_type, opts);
-      } catch (err) {
-        return `[Task error] ${(err as Error).message}`;
-      }
-
-      const childTools = buildChildCatalog(bridge.tools, def);
-      const childPerms = resolveChildPermissions(
-        { mode: bridge.permissionMode, rules: bridge.permissionRules },
-        def,
-      );
-
-      const parentHandle = {
-        runContext: bridge.runContext,
-        eventLog: bridge.eventLog,
-        permissionMode: bridge.permissionMode,
-        permissionRules: bridge.permissionRules,
-        tools: bridge.tools,
-        model: bridge.model,
-        maxTokens: bridge.maxTokens,
-        ...(bridge.sessionRootDir !== undefined ? { sessionRootDir: bridge.sessionRootDir } : {}),
-      };
-
-      const result = await spawnSubAgent(parentHandle, {
-        def,
-        prompt: input.prompt,
-        permissionMode: childPerms.mode,
-        permissionRules: childPerms.rules,
-        childTools,
-        ...(bridge.sessionRootDir !== undefined ? { sessionRootDir: bridge.sessionRootDir } : {}),
-      });
-
-      return result.finalMessage;
-    },
-  });
-}