@narumitw/pi-subagents 3.0.2 → 3.1.0

package/dist/index.ts

@@ -1,16 +1,34 @@
 // @generated by scripts/build-runtime.mjs; do not edit.
 // @ts-nocheck -- generated entries use .ts extensions for Pi's Jiti loader.
 import {
-  BROKER_CREDENTIAL_FD,
   CHILD_COMMUNICATION_TOOL_NAMES,
+  prepareTimeoutArguments,
+  resolveTimeoutMs
+} from "./chunks/chunk-ZOAFWLDJ.ts";
+import {
+  addAttachmentIgnoreRules,
+  isAbortError,
+  isRecord,
+  isWithin,
+  realpath,
+  throwIfAttachmentAborted,
+  toPosixPath,
+  toolSourceId
+} from "./chunks/chunk-3FCHXUKZ.ts";
+import {
+  BROKER_CREDENTIAL_FD,
+  CHILD_READINESS_FD,
+  CHILD_READINESS_FD_ENV,
   MAX_IDENTIFIER_LENGTH,
   MAX_MESSAGE_BYTES,
+  MAX_READINESS_FRAME_BYTES,
   MessageBroker,
-  brokerCredentialEnvironment,
+  assertChildBootstrapCapacity,
+  childBootstrapEnvironment,
   sanitizeTerminalText,
-  serializeBrokerCredentials,
+  serializeChildBootstrap,
   validateMessage
-} from "./chunks/chunk-7JQOB375.ts";
+} from "./chunks/chunk-YMVSJ5GE.ts";
 
 // src/completion-renderer.ts
 import { getMarkdownTheme, keyText } from "@earendil-works/pi-coding-agent";
@@ -102,34 +120,26 @@ import { StringDecoder } from "node:string_decoder";
 import { fileURLToPath } from "node:url";
 import { getPackageDir } from "@earendil-works/pi-coding-agent";
 var CORE_PACKAGE_NAME = "@earendil-works/pi-coding-agent";
-var MAX_TIMEOUT_MS = 2147483647;
-var MAX_TIMEOUT_SECONDS = MAX_TIMEOUT_MS / 1e3;
 var MAX_OUTPUT_BYTES = 32 * 1024;
 var MAX_ERROR_BYTES = 8 * 1024;
 var MAX_EVENT_LINE_BYTES = 256 * 1024;
 var RPC_RESPONSE_TIMEOUT_MS = 3e4;
 var KILL_GRACE_MS = 1e3;
-function resolveTimeoutMs(timeout) {
-  if (timeout === void 0) return void 0;
-  if (!Number.isFinite(timeout) || timeout <= 0) {
-    throw new Error("Invalid timeout: must be a finite number of seconds");
-  }
-  const timeoutMs = timeout * 1e3;
-  if (timeoutMs > MAX_TIMEOUT_MS) {
-    throw new Error(`Invalid timeout: maximum is ${MAX_TIMEOUT_SECONDS} seconds`);
-  }
-  return timeoutMs;
-}
+var MAX_WINDOWS_COMMAND_LINE_CODE_UNITS = 32767;
 async function runChild(request) {
   if (request.signal.aborted) return cancelledResult();
   try {
+    assertChildCommandCapacity(request);
     const invocation = resolvePiInvocation(buildPiArgs(request));
     return await executeProcess(invocation, request);
   } catch (error) {
     if (request.signal.aborted) return cancelledResult();
     return {
       state: "failed",
-      error: truncateText(error instanceof Error ? error.message : String(error), MAX_ERROR_BYTES).text,
+      error: truncateText(
+        redactAttachmentPaths(error instanceof Error ? error.message : String(error), request),
+        MAX_ERROR_BYTES
+      ).text,
       limitations: [],
       truncated: false
     };
@@ -144,31 +154,106 @@ function buildPiArgs(request) {
     "--no-skills",
     "--no-prompt-templates",
     "-e",
-    childCommunicationBridgePath(),
+    childCommunicationBridgePath()
+  ];
+  for (const extension of request.extensions) args.push("-e", extension.path);
+  if (requiresReadinessAttestation(request)) args.push("-e", childReadinessProbePath());
+  for (const skill of request.skills) args.push("--skill", skill);
+  args.push(
     "--model",
     request.model,
     "--thinking",
     request.thinkingLevel,
     request.projectTrusted ? "--approve" : "--no-approve"
-  ];
-  const tools = [.../* @__PURE__ */ new Set([...request.tools, ...CHILD_COMMUNICATION_TOOL_NAMES])];
-  args.push("--tools", tools.join(","));
+  );
+  args.push("--tools", selectedChildTools(request).join(","));
   return args;
 }
+function assertChildCommandCapacity(request, platform = process.platform) {
+  if (platform !== "win32") return;
+  const invocation = resolvePiInvocation(buildPiArgs(request));
+  const commandLineLength = [invocation.command, ...invocation.args].map(quoteWindowsArgument).join(" ").length;
+  if (commandLineLength + 1 > MAX_WINDOWS_COMMAND_LINE_CODE_UNITS) {
+    throw new Error("Subagent child command line exceeds the Windows process limit.");
+  }
+}
+function quoteWindowsArgument(value) {
+  if (value.length > 0 && !/[\s"]/u.test(value)) return value;
+  let quoted = '"';
+  let backslashes = 0;
+  for (const character of value) {
+    if (character === "\\") {
+      backslashes++;
+      continue;
+    }
+    if (character === '"') {
+      quoted += `${"\\".repeat(backslashes * 2 + 1)}"`;
+    } else {
+      quoted += `${"\\".repeat(backslashes)}${character}`;
+    }
+    backslashes = 0;
+  }
+  return `${quoted}${"\\".repeat(backslashes * 2)}"`;
+}
 function childCommunicationBridgePath() {
   return fileURLToPath(new URL("./child-communication-bridge.ts", import.meta.url));
 }
+function childReadinessProbePath() {
+  return fileURLToPath(new URL("./child-readiness-probe.ts", import.meta.url));
+}
+function requiresReadinessAttestation(request) {
+  return request.extensions.length > 0;
+}
+function selectedChildTools(request) {
+  return [
+    .../* @__PURE__ */ new Set([
+      ...request.tools,
+      ...CHILD_COMMUNICATION_TOOL_NAMES,
+      ...request.extensions.flatMap((extension) => extension.tools)
+    ])
+  ];
+}
 async function executeProcess(invocation, request) {
   const timeoutMs = resolveTimeoutMs(request.timeout);
+  const expectedTools = selectedChildTools(request);
+  const expectReadiness = requiresReadinessAttestation(request);
+  if (expectReadiness) assertChildBootstrapCapacity(expectedTools);
   let latestOutput = "";
   let terminalOutput;
   let terminalStopReason;
   let errorMessage = "";
   let assistantFailed = false;
   let stderr = "";
+  let stderrRedactionCarry = "";
+  const stderrDecoder = new StringDecoder("utf8");
+  const diagnosticAttachmentPaths = attachmentPathVariants(request);
   let truncated = false;
+  const appendStderr = (value) => {
+    if (!value) return;
+    const limited = truncateTail(`${stderr}${value}`, MAX_ERROR_BYTES);
+    stderr = limited.text;
+    truncated ||= limited.truncated;
+  };
+  const pushStderr = (chunk) => {
+    const combined = `${stderrRedactionCarry}${typeof chunk === "string" ? chunk : stderrDecoder.write(chunk)}`;
+    const carryLength = attachmentPathCarryLength(combined, diagnosticAttachmentPaths);
+    const boundary = combined.length - carryLength;
+    appendStderr(redactAttachmentPathVariants(combined.slice(0, boundary), diagnosticAttachmentPaths));
+    stderrRedactionCarry = combined.slice(boundary);
+  };
+  const flushStderr = () => {
+    const combined = `${stderrRedactionCarry}${stderrDecoder.end()}`;
+    const carryLength = attachmentPathCarryLength(combined, diagnosticAttachmentPaths);
+    const boundary = combined.length - carryLength;
+    appendStderr(
+      `${redactAttachmentPathVariants(combined.slice(0, boundary), diagnosticAttachmentPaths)}${carryLength > 0 ? "[attachment path]" : ""}`
+    );
+    stderrRedactionCarry = "";
+  };
   let malformedEvents = 0;
   let rpcCounter = 0;
+  let attachmentStartupPending = expectReadiness;
+  let attachmentStartupError;
   const pendingCommands = /* @__PURE__ */ new Map();
   let rpcInputError;
   let sendCommand = () => Promise.reject(new Error("Subagent RPC process is unavailable."));
@@ -189,11 +274,11 @@ async function executeProcess(invocation, request) {
   const rejectPendingCommands = (error2) => {
     for (const id of [...pendingCommands.keys()]) rejectPendingCommand(id, error2);
   };
-  const resolvePendingCommand = (id) => {
+  const resolvePendingCommand = (id, response) => {
     const pending = takePendingCommand(id);
     if (!pending) return;
     try {
-      pending.onAccepted?.();
+      pending.onAccepted?.(response);
       pending.resolve();
     } catch (error2) {
       pending.reject(error2 instanceof Error ? error2 : new Error(String(error2)));
@@ -206,16 +291,21 @@ async function executeProcess(invocation, request) {
   const decoder = new JsonLineDecoder(
     (value) => {
       const event = value;
+      if (expectReadiness && event.type === "extension_error" && (event.event === "session_start" || event.event === "resources_discover") && !attachmentStartupError) {
+        const detail = typeof event.error === "string" && event.error ? redactAttachmentPaths(sanitizeTerminalText(event.error), request) : "Unknown error.";
+        attachmentStartupError = `Subagent attachment startup failed during ${event.event}: ${detail}`;
+        return;
+      }
       if (event.type === "response" && typeof event.id === "string") {
         const pending = pendingCommands.get(event.id);
         if (!pending) return;
         if (event.success === true) {
-          resolvePendingCommand(event.id);
+          resolvePendingCommand(event.id, event);
         } else {
           rejectPendingCommand(
             event.id,
             new Error(
-              typeof event.error === "string" ? event.error : `Subagent RPC ${pending.command} command failed.`
+              pending.command === "get_commands" ? "Subagent child resource attestation failed." : typeof event.error === "string" ? event.error : `Subagent RPC ${pending.command} command failed.`
             )
           );
         }
@@ -240,7 +330,7 @@ async function executeProcess(invocation, request) {
           assistantFailed = true;
         }
         if (event.message.errorMessage) {
-          const limited = truncateText(event.message.errorMessage, MAX_ERROR_BYTES);
+          const limited = truncateText(redactAttachmentPaths(event.message.errorMessage, request), MAX_ERROR_BYTES);
           errorMessage = limited.text;
           truncated ||= limited.truncated;
         }
@@ -248,9 +338,12 @@ async function executeProcess(invocation, request) {
     },
     () => {
       malformedEvents++;
+      if (attachmentStartupPending && !attachmentStartupError) {
+        attachmentStartupError = "Subagent attachment startup emitted malformed or oversized RPC output.";
+      }
     }
   );
-  const settlement = await new Promise((resolve2) => {
+  const settlement = await new Promise((resolve4) => {
     let process2;
     let settled = false;
     let finishRequested = false;
@@ -260,6 +353,9 @@ async function executeProcess(invocation, request) {
     let timedOut = false;
     let completed = false;
     let ready = false;
+    let attachmentReady = !expectReadiness;
+    let promptStarted = false;
+    let readinessPipe;
     let deadline;
     let forceClose;
     let escalation;
@@ -274,8 +370,10 @@ async function executeProcess(invocation, request) {
         if (forceClose) clearTimeout(forceClose);
         if (escalation) clearTimeout(escalation);
         request.signal.removeEventListener("abort", onAbort);
+        readinessPipe?.removeAllListeners();
+        readinessPipe?.destroy();
         rejectPendingCommands(new Error("Subagent RPC process closed."));
-        resolve2({ code, cancelled, timedOut, completed, launchError });
+        resolve4({ code, cancelled, timedOut, completed, launchError });
       };
       if (termination) void termination.then(complete, complete);
       else complete();
@@ -299,6 +397,7 @@ async function executeProcess(invocation, request) {
         process2.stdin?.destroy();
         process2.stdout?.destroy();
         process2.stderr?.destroy();
+        readinessPipe?.destroy();
         finish(code);
       }, KILL_GRACE_MS * 2);
       forceClose.unref();
@@ -315,16 +414,18 @@ async function executeProcess(invocation, request) {
     };
     onAgentSettled = completeNormally;
     try {
+      const environment = {
+        ...globalThis.process.env,
+        ...childBootstrapEnvironment(expectReadiness),
+        PI_SUBAGENT_DEPTH: String((Number.parseInt(globalThis.process.env.PI_SUBAGENT_DEPTH ?? "0", 10) || 0) + 1)
+      };
+      if (!expectReadiness) delete environment[CHILD_READINESS_FD_ENV];
       process2 = spawn(invocation.command, invocation.args, {
         cwd: request.cwd,
         detached: globalThis.process.platform !== "win32",
         shell: false,
-        stdio: ["pipe", "pipe", "pipe", "pipe"],
-        env: {
-          ...globalThis.process.env,
-          ...brokerCredentialEnvironment(),
-          PI_SUBAGENT_DEPTH: String((Number.parseInt(globalThis.process.env.PI_SUBAGENT_DEPTH ?? "0", 10) || 0) + 1)
-        }
+        stdio: expectReadiness ? ["pipe", "pipe", "pipe", "pipe", "pipe"] : ["pipe", "pipe", "pipe", "pipe"],
+        env: environment
       });
     } catch (error2) {
       finish(1, error2 instanceof Error ? error2.message : String(error2));
@@ -379,11 +480,9 @@ async function executeProcess(invocation, request) {
         }
       });
     };
-    request.signal.addEventListener("abort", onAbort, { once: true });
-    if (request.signal.aborted) onAbort();
-    process2.once("spawn", () => {
-      spawned = true;
-      if (settled || cancelled) return;
+    const startPrompt = () => {
+      if (!spawned || !attachmentReady || promptStarted || settled || cancelled || terminating) return;
+      promptStarted = true;
       void sendCommand(
         { type: "prompt", message: `Task: ${request.task}` },
         () => {
@@ -411,22 +510,105 @@ async function executeProcess(invocation, request) {
         request.signal
       ).catch((error2) => {
         if (settled || terminating) return;
-        errorMessage = truncateText(error2 instanceof Error ? error2.message : String(error2), MAX_ERROR_BYTES).text;
+        errorMessage = truncateText(
+          redactAttachmentPaths(error2 instanceof Error ? error2.message : String(error2), request),
+          MAX_ERROR_BYTES
+        ).text;
         terminate(1);
       });
+    };
+    const failReadiness = (message) => {
+      if (settled || terminating || attachmentReady) return;
+      errorMessage = truncateText(redactAttachmentPaths(message, request), MAX_ERROR_BYTES).text;
+      terminate(1);
+    };
+    const confirmAttachmentStartup = () => {
+      void sendCommand({ type: "get_state" }, void 0, request.signal).then(async () => {
+        if (attachmentStartupError) throw new Error(attachmentStartupError);
+        if (!request.projectTrusted) {
+          await sendCommand(
+            { type: "get_commands" },
+            (response) => assertTrustedChildResources(response.data, request.cwd),
+            request.signal
+          );
+        }
+        if (attachmentStartupError) throw new Error(attachmentStartupError);
+        attachmentStartupPending = false;
+        attachmentReady = true;
+        startPrompt();
+      }).catch((error2) => {
+        failReadiness(error2 instanceof Error ? error2.message : String(error2));
+      });
+    };
+    request.signal.addEventListener("abort", onAbort, { once: true });
+    if (request.signal.aborted) onAbort();
+    process2.once("spawn", () => {
+      spawned = true;
+      startPrompt();
     });
+    if (expectReadiness) {
+      const candidate = process2.stdio[CHILD_READINESS_FD];
+      if (!candidate || !("on" in candidate)) {
+        errorMessage = "Subagent readiness pipe is unavailable.";
+        terminate(1);
+      } else {
+        readinessPipe = candidate;
+        let buffer = Buffer.alloc(0);
+        let readinessSettled = false;
+        readinessPipe.on("data", (chunk) => {
+          if (readinessSettled || terminating) return;
+          buffer = Buffer.concat([buffer, Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)]);
+          if (buffer.byteLength > MAX_READINESS_FRAME_BYTES) {
+            readinessSettled = true;
+            failReadiness("Subagent readiness frame exceeded its size limit.");
+          }
+        });
+        readinessPipe.once("end", () => {
+          if (readinessSettled || terminating) return;
+          readinessSettled = true;
+          let frame;
+          try {
+            frame = parseReadinessFrame(buffer, expectedTools.length);
+          } catch (error2) {
+            failReadiness(error2 instanceof Error ? error2.message : String(error2));
+            return;
+          }
+          if (!frame.ok) {
+            failReadiness(frame.error);
+            return;
+          }
+          for (const extension of request.extensions) {
+            for (const tool of extension.tools) {
+              const source = frame.sources[expectedTools.indexOf(tool)];
+              if (!source || !Object.hasOwn(request.toolSources, tool) || !request.toolSources[tool]?.includes(source)) {
+                failReadiness(`Subagent extension tool ${tool} was not provided by its requested attachment.`);
+                return;
+              }
+            }
+          }
+          confirmAttachmentStartup();
+        });
+        readinessPipe.once("error", () => {
+          if (readinessSettled || terminating) return;
+          readinessSettled = true;
+          failReadiness("Subagent readiness transfer failed.");
+        });
+        readinessPipe.once("close", () => {
+          if (readinessSettled || terminating) return;
+          readinessSettled = true;
+          failReadiness("Subagent readiness pipe closed without a result.");
+        });
+      }
+    }
     process2.stdout?.on("data", (chunk) => decoder.push(chunk));
-    process2.stderr?.on("data", (chunk) => {
-      const limited = truncateTail(`${stderr}${chunk.toString()}`, MAX_ERROR_BYTES);
-      stderr = limited.text;
-      truncated ||= limited.truncated;
-    });
+    process2.stderr?.on("data", (chunk) => pushStderr(chunk));
     process2.once("close", (code) => {
+      flushStderr();
       decoder.finish();
       finish(cancelled ? 130 : timedOut ? 124 : completed ? 0 : code ?? 1);
     });
     process2.once("error", (error2) => {
-      const limited = truncateText(error2.message, MAX_ERROR_BYTES);
+      const limited = truncateText(redactAttachmentPaths(error2.message, request), MAX_ERROR_BYTES);
       errorMessage = limited.text;
       truncated ||= limited.truncated;
       if (spawned) terminate(1);
@@ -449,7 +631,12 @@ async function executeProcess(invocation, request) {
       credentialPipe.on("error", onCredentialError);
       credentialPipe.once("close", removeCredentialListeners);
       try {
-        credentialPipe.end(serializeBrokerCredentials(request.communication));
+        credentialPipe.end(
+          serializeChildBootstrap({
+            communication: request.communication,
+            expectedTools: expectReadiness ? expectedTools : []
+          })
+        );
       } catch {
         onCredentialError();
       }
@@ -471,7 +658,17 @@ async function executeProcess(invocation, request) {
       truncated
     };
   }
-  const error = settlement.launchError || errorMessage || stderr.trim();
+  const redactedStderr = truncateTail(redactAttachmentPaths(stderr.trim(), request), MAX_ERROR_BYTES);
+  const combinedError = combineErrors(
+    redactAttachmentPaths(settlement.launchError ?? "", request),
+    redactAttachmentPaths(errorMessage, request),
+    redactedStderr.text
+  );
+  const error = combinedError.text;
+  if ((combinedError.truncated || redactedStderr.truncated) && !truncated) {
+    limitations.push("Child output was truncated to runtime limits.");
+  }
+  truncated ||= combinedError.truncated || redactedStderr.truncated;
   if (settlement.completed && terminalStopReason === "stop" && !assistantFailed && !errorMessage) {
     return {
       state: "completed",
@@ -510,8 +707,8 @@ function resolvePiInvocation(args) {
     return { command: globalThis.process.execPath, args };
   }
   const cliPath = fs.realpathSync(path.resolve(packageDirectory, declared));
-  const relative2 = path.relative(packageDirectory, cliPath);
-  if (relative2 === ".." || relative2.startsWith(`..${path.sep}`) || path.isAbsolute(relative2)) {
+  const relative4 = path.relative(packageDirectory, cliPath);
+  if (relative4 === ".." || relative4.startsWith(`..${path.sep}`) || path.isAbsolute(relative4)) {
     throw new Error("Pi core bin.pi escapes its package directory.");
   }
   if (!fs.statSync(cliPath).isFile()) throw new Error("Pi core bin.pi is not a file.");
@@ -535,7 +732,7 @@ function terminateWindowsProcessTree(process2, spawnProcess = spawn, taskkillPat
     killImmediateChild(process2);
     return Promise.resolve();
   }
-  return new Promise((resolve2) => {
+  return new Promise((resolve4) => {
     let settled = false;
     let treeKiller;
     let deadline;
@@ -549,7 +746,7 @@ function terminateWindowsProcessTree(process2, spawnProcess = spawn, taskkillPat
       treeKiller.removeListener("close", onClose);
       if (terminateHelper) killImmediateChild(treeKiller);
       if (fallback) killImmediateChild(process2);
-      resolve2();
+      resolve4();
     };
     try {
       treeKiller = spawnProcess(taskkillPath, ["/PID", String(process2.pid), "/T", "/F"], {
@@ -558,7 +755,7 @@ function terminateWindowsProcessTree(process2, spawnProcess = spawn, taskkillPat
       });
     } catch {
       killImmediateChild(process2);
-      resolve2();
+      resolve4();
       return;
     }
     treeKiller.once("error", onError);
@@ -578,6 +775,97 @@ function killImmediateChild(process2) {
   } catch {
   }
 }
+function assertTrustedChildResources(value, cwd) {
+  const invalid = () => new Error("Subagent child resource attestation returned invalid commands.");
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw invalid();
+  const commands = value.commands;
+  if (!Array.isArray(commands)) throw invalid();
+  let canonicalCwd;
+  try {
+    canonicalCwd = fs.realpathSync(cwd);
+  } catch {
+    throw invalid();
+  }
+  for (const command of commands) {
+    if (!command || typeof command !== "object" || Array.isArray(command)) throw invalid();
+    const entry = command;
+    if (entry.source !== "skill" && entry.source !== "prompt") continue;
+    const resourcePath = entry.sourceInfo?.path;
+    if (typeof resourcePath !== "string" || !resourcePath) throw invalid();
+    const lexicalPath = path.resolve(cwd, resourcePath);
+    let canonicalPath;
+    try {
+      canonicalPath = fs.realpathSync(lexicalPath);
+    } catch {
+      throw invalid();
+    }
+    if (isWithin(cwd, lexicalPath) || isWithin(canonicalCwd, canonicalPath)) {
+      throw new Error("Subagent child cannot load project resources because the project is not trusted.");
+    }
+  }
+}
+function parseReadinessFrame(buffer, expectedToolCount) {
+  if (buffer.byteLength === 0) {
+    throw new Error("Subagent readiness pipe closed without a result.");
+  }
+  const text = buffer.toString("utf8");
+  const newline = text.indexOf("\n");
+  if (newline < 0 || newline !== text.length - 1) {
+    throw new Error("Subagent readiness pipe returned an invalid frame.");
+  }
+  let value;
+  try {
+    value = JSON.parse(text.slice(0, newline));
+  } catch {
+    throw new Error("Subagent readiness pipe returned malformed JSON.");
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("Subagent readiness pipe returned an invalid result.");
+  }
+  const record = value;
+  if (record.ok === true && Object.keys(record).length === 2 && Array.isArray(record.sources) && record.sources.length === expectedToolCount && record.sources.every((source) => typeof source === "string" && /^[a-f0-9]{64}$/u.test(source))) {
+    return { ok: true, sources: record.sources };
+  }
+  if (record.ok === false && Object.keys(record).length === 2 && typeof record.error === "string" && record.error.length > 0 && Buffer.byteLength(record.error, "utf8") <= MAX_ERROR_BYTES) {
+    return { ok: false, error: sanitizeTerminalText(record.error) };
+  }
+  throw new Error("Subagent readiness pipe returned an invalid result.");
+}
+function redactAttachmentPaths(value, request) {
+  return redactAttachmentPathVariants(value, attachmentPathVariants(request));
+}
+function redactAttachmentPathVariants(value, candidates) {
+  let redacted = value;
+  for (const candidate of candidates) redacted = redacted.replaceAll(candidate, "[attachment path]");
+  return redacted;
+}
+function attachmentPathCarryLength(value, candidates) {
+  const maximum = Math.min(
+    value.length,
+    candidates.reduce((length, candidate) => Math.max(length, candidate.length - 1), 0)
+  );
+  for (let length = maximum; length > 0; length--) {
+    const suffix = value.slice(-length);
+    if (candidates.some((candidate) => candidate.length > length && candidate.startsWith(suffix))) return length;
+  }
+  return 0;
+}
+function attachmentPathVariants(request) {
+  const variants = /* @__PURE__ */ new Set();
+  const paths = [...request.skills, ...request.extensions.map((extension) => extension.path)];
+  for (const resourcePath of paths) {
+    for (const spelling of [resourcePath, resourcePath.replaceAll("\\", "/"), resourcePath.replaceAll("/", "\\")]) {
+      if (!spelling) continue;
+      variants.add(spelling);
+      variants.add(JSON.stringify(spelling).slice(1, -1));
+    }
+  }
+  return [...variants].sort((left, right) => right.length - left.length);
+}
+function combineErrors(...messages) {
+  const unique = [...new Set(messages.filter((message) => Boolean(message)))];
+  return truncateText(unique.join("\n"), MAX_ERROR_BYTES);
+}
 function abortError(message) {
   const error = new Error(message);
   error.name = "AbortError";
@@ -663,6 +951,247 @@ var JsonLineDecoder = class {
   }
 };
 
+// src/resource-attachments.ts
+import { existsSync, statSync as statSync3 } from "node:fs";
+import {
+  opendir as opendirAsync2,
+  readFile as readFileAsync,
+  realpath as realpathAsync2,
+  stat as statAsync2
+} from "node:fs/promises";
+import * as path3 from "node:path";
+import { DefaultPackageManager, SettingsManager } from "@earendil-works/pi-coding-agent";
+import ignore2 from "ignore";
+
+// src/skill-attachments.ts
+import { statSync as statSync2 } from "node:fs";
+import { opendir as opendirAsync, realpath as realpathAsync, stat as statAsync } from "node:fs/promises";
+import * as path2 from "node:path";
+import { loadSkills } from "@earendil-works/pi-coding-agent";
+import ignore from "ignore";
+var MAX_SKILL_SCAN_DEPTH = 32;
+var MAX_SKILL_SCAN_ENTRIES = 4096;
+var MAX_SKILL_SCAN_BYTES = 4 * 1024 * 1024;
+var MAX_SKILL_IGNORE_BYTES = 1024 * 1024;
+async function assertLoadableSkills(skillPaths, cwd, canonicalCwd, projectTrusted, signal) {
+  const scanState = {
+    entries: 0,
+    skillBytes: 0,
+    ignoreBytes: 0,
+    ancestors: /* @__PURE__ */ new Set(),
+    signal
+  };
+  for (const skillPath of skillPaths) {
+    throwIfAttachmentAborted(signal);
+    const candidates = await collectBoundedSkillCandidates(skillPath, scanState);
+    throwIfAttachmentAborted(signal);
+    const result = loadExplicitSkills([skillPath], cwd);
+    if (result.skills.length === 0) {
+      throw new Error("Subagent skill path must contain at least one loadable Pi skill.");
+    }
+    assertNoUntrustedProjectSkills(result, cwd, canonicalCwd, projectTrusted);
+    assertNoOmittedSkillDiagnostics(result);
+    assertNoSkillNameCollisions(result.diagnostics);
+    await assertNoSilentlyOmittedSkills(skillPath, cwd, result, canonicalCwd, projectTrusted, candidates, signal);
+  }
+  if (skillPaths.length > 1) {
+    throwIfAttachmentAborted(signal);
+    const result = loadExplicitSkills(skillPaths, cwd);
+    assertNoUntrustedProjectSkills(result, cwd, canonicalCwd, projectTrusted);
+    assertNoSkillNameCollisions(result.diagnostics);
+  }
+  return scanState;
+}
+function loadExplicitSkills(skillPaths, cwd) {
+  return loadSkills({ cwd, agentDir: cwd, skillPaths, includeDefaults: false });
+}
+function assertNoOmittedSkillDiagnostics(result) {
+  const loadedPaths = new Set(result.skills.map((skill) => skill.filePath));
+  const omitted = result.diagnostics.some(
+    (diagnostic) => diagnostic.type === "error" || diagnostic.type === "warning" && (!diagnostic.path || !loadedPaths.has(diagnostic.path))
+  );
+  if (omitted) {
+    throw new Error("Subagent skill attachment must not contain an invalid or unreadable declared skill.");
+  }
+}
+function assertNoSkillNameCollisions(diagnostics) {
+  if (diagnostics.some((diagnostic) => diagnostic.type === "collision" && diagnostic.collision?.resourceType === "skill")) {
+    throw new Error("Subagent skill attachments must not contain duplicate skill names.");
+  }
+}
+function assertNoUntrustedProjectSkills(result, cwd, canonicalCwd, projectTrusted) {
+  if (projectTrusted) return;
+  for (const skill of result.skills) {
+    const lexicalPath = path2.resolve(skill.filePath);
+    const canonicalPath = realpath(skill.filePath, "Loaded subagent skill");
+    if (isWithin(cwd, lexicalPath) || isWithin(canonicalCwd, canonicalPath)) {
+      throw new Error("Subagent skill cannot load a project path because the project is not trusted.");
+    }
+  }
+}
+async function assertNoSilentlyOmittedSkills(skillPath, cwd, result, canonicalCwd, projectTrusted, candidates, signal) {
+  if (!statSync2(skillPath).isDirectory()) return;
+  const loadedPaths = new Set(result.skills.map((skill) => realpath(skill.filePath, "Loaded subagent skill")));
+  for (const [index, candidate] of candidates.entries()) {
+    if (index > 0 && index % 64 === 0) await new Promise((resolve4) => setImmediate(resolve4));
+    throwIfAttachmentAborted(signal);
+    const candidateResult = loadExplicitSkills([candidate], cwd);
+    assertNoUntrustedProjectSkills(candidateResult, cwd, canonicalCwd, projectTrusted);
+    if (candidateResult.skills.length === 0) {
+      if (path2.basename(candidate) === "SKILL.md") throwInvalidDeclaredSkill();
+      continue;
+    }
+    const loaded = candidateResult.skills.some(
+      (skill) => loadedPaths.has(realpath(skill.filePath, "Loaded subagent skill"))
+    );
+    if (!loaded) throwInvalidDeclaredSkill();
+  }
+}
+async function collectBoundedSkillCandidates(skillPath, state) {
+  throwIfAttachmentAborted(state.signal);
+  const stats = await statAsync(skillPath);
+  throwIfAttachmentAborted(state.signal);
+  if (!stats.isDirectory()) {
+    if (stats.isFile() && skillPath.endsWith(".md")) addSkillBytes(state, stats.size);
+    return [];
+  }
+  return collectSkillCandidates(skillPath, true, ignore(), skillPath, 0, state);
+}
+async function collectSkillCandidates(directory, includeRootMarkdown, ignoreMatcher, rootDirectory, depth, state) {
+  throwIfAttachmentAborted(state.signal);
+  if (depth > MAX_SKILL_SCAN_DEPTH) throwSkillScanLimit();
+  let canonicalDirectory;
+  try {
+    canonicalDirectory = await realpathAsync(directory);
+  } catch {
+    throwInvalidDeclaredSkill();
+  }
+  throwIfAttachmentAborted(state.signal);
+  if (state.ancestors.has(canonicalDirectory)) {
+    throw new Error("Subagent skill attachment must not contain a recursive directory link.");
+  }
+  state.ancestors.add(canonicalDirectory);
+  try {
+    await addAttachmentIgnoreRules(ignoreMatcher, directory, rootDirectory, state.signal, (_ignorePath, bytes) => {
+      state.ignoreBytes += bytes;
+      if (state.ignoreBytes > MAX_SKILL_IGNORE_BYTES) throwSkillScanLimit();
+    });
+    let directoryHandle;
+    try {
+      directoryHandle = await opendirAsync(directory);
+    } catch {
+      throwInvalidDeclaredSkill();
+    }
+    const entries = [];
+    try {
+      for await (const entry of directoryHandle) {
+        throwIfAttachmentAborted(state.signal);
+        state.entries++;
+        if (state.entries > MAX_SKILL_SCAN_ENTRIES) throwSkillScanLimit();
+        entries.push(entry);
+      }
+    } catch (error) {
+      if (isAbortError(error) || isSkillScanLimitError(error)) throw error;
+      throwInvalidDeclaredSkill();
+    }
+    const rootSkill = entries.find((entry) => entry.name === "SKILL.md");
+    if (rootSkill) {
+      const rootPath = path2.join(directory, rootSkill.name);
+      const relativePath = toPosixPath(path2.relative(rootDirectory, rootPath));
+      if (!ignoreMatcher.ignores(relativePath)) {
+        let rootStats;
+        try {
+          rootStats = await statAsync(rootPath);
+        } catch (error) {
+          if (isAbortError(error)) throw error;
+          throwInvalidDeclaredSkill();
+        }
+        throwIfAttachmentAborted(state.signal);
+        if (rootStats.isFile()) {
+          addSkillBytes(state, rootStats.size);
+          return [rootPath];
+        }
+      }
+    }
+    const candidates = [];
+    for (const entry of entries) {
+      throwIfAttachmentAborted(state.signal);
+      if (entry.name.startsWith(".") || entry.name === "node_modules") continue;
+      const candidate = path2.join(directory, entry.name);
+      const relativePath = toPosixPath(path2.relative(rootDirectory, candidate));
+      let candidateStats;
+      try {
+        candidateStats = await statAsync(candidate);
+      } catch (error) {
+        if (isAbortError(error)) throw error;
+        throwIfAttachmentAborted(state.signal);
+        if (!ignoreMatcher.ignores(relativePath) && (entry.name === "SKILL.md" || includeRootMarkdown && entry.name.endsWith(".md"))) {
+          throwInvalidDeclaredSkill();
+        }
+        continue;
+      }
+      throwIfAttachmentAborted(state.signal);
+      if (ignoreMatcher.ignores(candidateStats.isDirectory() ? `${relativePath}/` : relativePath)) continue;
+      if (candidateStats.isDirectory()) {
+        candidates.push(
+          ...await collectSkillCandidates(candidate, false, ignoreMatcher, rootDirectory, depth + 1, state)
+        );
+      } else if (candidateStats.isFile() && (entry.name === "SKILL.md" || includeRootMarkdown && entry.name.endsWith(".md"))) {
+        addSkillBytes(state, candidateStats.size);
+        candidates.push(candidate);
+      }
+    }
+    return candidates;
+  } finally {
+    state.ancestors.delete(canonicalDirectory);
+  }
+}
+function addSkillBytes(state, bytes) {
+  state.skillBytes += bytes;
+  if (state.skillBytes > MAX_SKILL_SCAN_BYTES) throwSkillScanLimit();
+}
+function isSkillScanLimitError(error) {
+  return error instanceof Error && error.name === "SkillScanLimitError";
+}
+function throwSkillScanLimit() {
+  const error = new Error(
+    `Subagent skill attachment exceeds traversal limits (${MAX_SKILL_SCAN_ENTRIES} entries, depth ${MAX_SKILL_SCAN_DEPTH}, ${MAX_SKILL_SCAN_BYTES} skill bytes, or ${MAX_SKILL_IGNORE_BYTES} ignore bytes).`
+  );
+  error.name = "SkillScanLimitError";
+  throw error;
+}
+function throwInvalidDeclaredSkill() {
+  throw new Error("Subagent skill attachment must not contain an invalid or unreadable declared skill.");
+}
+async function assertLoadablePackageSkills(packageSkillPaths, explicitSkillPaths, cwd, scanState) {
+  const uniquePackageSkillPaths = deduplicatePackageSkillPaths(packageSkillPaths, explicitSkillPaths);
+  for (const [index, skillPath] of uniquePackageSkillPaths.entries()) {
+    if (index > 0 && index % 64 === 0) await new Promise((resolve4) => setImmediate(resolve4));
+    throwIfAttachmentAborted(scanState.signal);
+    await collectBoundedSkillCandidates(skillPath, scanState);
+  }
+  for (const [index, skillPath] of uniquePackageSkillPaths.entries()) {
+    if (index > 0 && index % 64 === 0) await new Promise((resolve4) => setImmediate(resolve4));
+    throwIfAttachmentAborted(scanState.signal);
+    const result = loadExplicitSkills([skillPath], cwd);
+    if (result.skills.length === 0) throwInvalidDeclaredSkill();
+    assertNoOmittedSkillDiagnostics(result);
+  }
+  throwIfAttachmentAborted(scanState.signal);
+  assertNoSkillNameCollisions(loadExplicitSkills([...uniquePackageSkillPaths, ...explicitSkillPaths], cwd).diagnostics);
+}
+function deduplicatePackageSkillPaths(packageSkillPaths, explicitSkillPaths) {
+  const seenPaths = new Set(explicitSkillPaths.map((skillPath) => realpath(skillPath, "Loaded subagent skill")));
+  const uniquePaths = [];
+  for (const skillPath of packageSkillPaths) {
+    const canonicalPath = realpath(skillPath, "Loaded subagent package skill");
+    if (seenPaths.has(canonicalPath)) continue;
+    seenPaths.add(canonicalPath);
+    uniquePaths.push(skillPath);
+  }
+  return uniquePaths;
+}
+
 // src/types.ts
 var TERMINAL_JOB_STATES = /* @__PURE__ */ new Set([
   "completed",
@@ -683,6 +1212,514 @@ var SUBAGENT_THINKING_LEVELS = [
   "max"
 ];
 
+// src/resource-attachments.ts
+var MAX_ATTACHED_SKILLS = 16;
+var MAX_ATTACHED_EXTENSIONS = 16;
+var MAX_SELECTED_TOOLS = 64;
+var MAX_RESOURCE_PATH_BYTES = 4 * 1024;
+var MAX_EXTENSION_TOOL_NAME_LENGTH = 128;
+var MAX_EXTENSION_SCAN_DEPTH = 32;
+var MAX_EXTENSION_SCAN_ENTRIES = 4096;
+var MAX_EXTENSION_METADATA_BYTES = 1024 * 1024;
+var RESERVED_CHILD_TOOL_NAMES = /* @__PURE__ */ new Set([...CHILD_CORE_TOOL_NAMES, ...CHILD_COMMUNICATION_TOOL_NAMES]);
+async function resolveResourceAttachments(input, options) {
+  const cwd = path3.resolve(options.cwd);
+  const canonicalCwd = realpath(cwd, "Subagent working directory");
+  const skillInputs = optionalArray(input.skills, "skills", MAX_ATTACHED_SKILLS);
+  const extensionInputs = optionalArray(input.extensions, "extensions", MAX_ATTACHED_EXTENSIONS);
+  const skills = [];
+  const seenSkills = /* @__PURE__ */ new Set();
+  for (const candidate of skillInputs) {
+    const resolved = resolveResourcePath(candidate, "skill", cwd, canonicalCwd, options.projectTrusted);
+    if (!seenSkills.has(resolved)) {
+      seenSkills.add(resolved);
+      skills.push(resolved);
+    }
+  }
+  const skillScanState = await assertLoadableSkills(skills, cwd, canonicalCwd, options.projectTrusted, options.signal);
+  const extensions = [];
+  const extensionsByPath = /* @__PURE__ */ new Map();
+  const entrypointsByPath = /* @__PURE__ */ new Map();
+  const packageSkillPaths = [];
+  for (const candidate of extensionInputs) {
+    if (!isRecord(candidate) || Object.keys(candidate).some((key) => key !== "path" && key !== "tools")) {
+      throw new Error("Each subagent extension must contain only path and tools.");
+    }
+    const resolved = resolveResourcePath(candidate.path, "extension", cwd, canonicalCwd, options.projectTrusted);
+    const toolInputs = optionalArray(candidate.tools, "extension tools", MAX_SELECTED_TOOLS, false);
+    const tools = toolInputs.map(resolveExtensionToolName);
+    for (const tool of tools) {
+      if (RESERVED_CHILD_TOOL_NAMES.has(tool)) {
+        throw new Error(`Subagent extension tool name conflicts with the built-in ${tool} tool.`);
+      }
+    }
+    let attachment = extensionsByPath.get(resolved);
+    if (!attachment) {
+      const resources = await assertResolvableExtensionAttachment(
+        resolved,
+        cwd,
+        canonicalCwd,
+        options.projectTrusted,
+        options.signal
+      );
+      packageSkillPaths.push(...resources.skills);
+      entrypointsByPath.set(resolved, resources.entrypoints);
+      attachment = { path: resolved, tools: [] };
+      extensionsByPath.set(resolved, attachment);
+      extensions.push(attachment);
+    }
+    for (const tool of tools) {
+      if (!attachment.tools.includes(tool)) attachment.tools.push(tool);
+    }
+  }
+  if (packageSkillPaths.length > 0) {
+    await assertLoadablePackageSkills(packageSkillPaths, skills, cwd, skillScanState);
+  }
+  const effectiveTools = [.../* @__PURE__ */ new Set([...options.coreTools, ...extensions.flatMap((extension) => extension.tools)])];
+  if (effectiveTools.length > MAX_SELECTED_TOOLS) {
+    throw new Error(`Subagent jobs may select at most ${MAX_SELECTED_TOOLS} total tools.`);
+  }
+  const toolSources = /* @__PURE__ */ new Map();
+  const firstSourceIdByCanonicalPath = /* @__PURE__ */ new Map();
+  for (const extension of extensions) {
+    const sourceIds = (entrypointsByPath.get(extension.path) ?? []).map((entrypoint) => {
+      const canonicalPath = realpath(entrypoint, "Subagent extension entrypoint");
+      const sourceId = firstSourceIdByCanonicalPath.get(canonicalPath) ?? toolSourceId(entrypoint);
+      firstSourceIdByCanonicalPath.set(canonicalPath, sourceId);
+      return sourceId;
+    });
+    for (const tool of extension.tools) {
+      if (toolSources.has(tool)) {
+        throw new Error(`Subagent extension tool ${tool} is requested by multiple attachments.`);
+      }
+      toolSources.set(tool, sourceIds);
+    }
+  }
+  return { skills, extensions, effectiveTools, toolSources: Object.fromEntries(toolSources) };
+}
+function optionalArray(value, field, maxItems, optional = true) {
+  if (value === void 0 && optional) return [];
+  if (!Array.isArray(value)) throw new Error(`Subagent ${field} must be an array.`);
+  if (value.length > maxItems) throw new Error(`Subagent ${field} may contain at most ${maxItems} entries.`);
+  return value;
+}
+function resolveResourcePath(value, kind, cwd, canonicalCwd, projectTrusted) {
+  if (typeof value !== "string" || !value.trim()) throw new Error(`Subagent ${kind} path is required.`);
+  const resourcePath = value.trim();
+  if (hasControlCharacter(resourcePath)) throw new Error(`Subagent ${kind} path must not contain control characters.`);
+  if (Buffer.byteLength(resourcePath, "utf8") > MAX_RESOURCE_PATH_BYTES) {
+    throw new Error(`Subagent ${kind} path must be at most ${MAX_RESOURCE_PATH_BYTES} UTF-8 bytes.`);
+  }
+  if (!isLocalPath(resourcePath)) throw new Error(`Subagent ${kind} must use a local path.`);
+  const lexicalPath = path3.resolve(cwd, resourcePath);
+  const canonicalPath = realpath(lexicalPath, `Subagent ${kind}`);
+  const stats = statSync3(canonicalPath);
+  if (!stats.isFile() && !stats.isDirectory()) {
+    throw new Error(`Subagent ${kind} path must reference a file or directory.`);
+  }
+  if (!projectTrusted && (isWithin(cwd, lexicalPath) || isWithin(canonicalCwd, canonicalPath))) {
+    throw new Error(`Subagent ${kind} cannot load a project path because the project is not trusted.`);
+  }
+  return canonicalPath;
+}
+async function assertResolvableExtensionAttachment(extensionPath, cwd, canonicalCwd, projectTrusted, signal) {
+  await inspectExtensionAttachment(extensionPath, cwd, canonicalCwd, projectTrusted, signal);
+  throwIfAttachmentAborted(signal);
+  const resolved = await resolveAttachedExtensionResources(extensionPath, cwd);
+  throwIfAttachmentAborted(signal);
+  const entrypoints = enabledResourcePaths(resolved.extensions);
+  if (entrypoints.length === 0) {
+    throw new Error("Subagent extension directory must contain at least one loadable Pi extension entrypoint.");
+  }
+  const loadPaths = entrypoints.flatMap(resolveDirectExtensionLoadPaths);
+  for (const entrypoint of loadPaths) {
+    assertTrustedResolvedPath(entrypoint, "extension entrypoint", cwd, canonicalCwd, projectTrusted);
+  }
+  const packageSkills = enabledResourcePaths(resolved.skills);
+  const packageResources = [
+    packageSkills,
+    enabledResourcePaths(resolved.prompts),
+    enabledResourcePaths(resolved.themes)
+  ].flat();
+  for (const resource of packageResources) {
+    assertTrustedResolvedPath(resource, "extension package resource", cwd, canonicalCwd, projectTrusted);
+  }
+  return { skills: packageSkills, entrypoints: loadPaths };
+}
+function resolveDirectExtensionLoadPaths(entrypoint) {
+  if (!statSync3(entrypoint).isDirectory()) return [entrypoint];
+  for (const filename of ["index.ts", "index.js"]) {
+    const indexPath = path3.join(entrypoint, filename);
+    if (existsSync(indexPath) && statSync3(indexPath).isFile()) return [entrypoint, indexPath];
+  }
+  throwUnresolvableExtensionEntrypoint();
+}
+async function resolveAttachedExtensionResources(extensionPath, cwd) {
+  const packageManager = new DefaultPackageManager({
+    cwd,
+    agentDir: cwd,
+    settingsManager: SettingsManager.inMemory()
+  });
+  return packageManager.resolveExtensionSources([extensionPath], { temporary: true });
+}
+function enabledResourcePaths(resources) {
+  return resources.filter((resource) => resource.enabled).map((resource) => resource.path);
+}
+function assertTrustedResolvedPath(resourcePath, label, cwd, canonicalCwd, projectTrusted) {
+  const canonicalPath = realpath(resourcePath, `Subagent ${label}`);
+  const stats = statSync3(canonicalPath);
+  if (!stats.isFile() && !stats.isDirectory()) {
+    throw new Error(`Subagent ${label} must reference a file or directory.`);
+  }
+  assertProjectPathTrusted(resourcePath, canonicalPath, label, cwd, canonicalCwd, projectTrusted);
+}
+function assertProjectPathTrusted(lexicalPath, canonicalPath, label, cwd, canonicalCwd, projectTrusted) {
+  if (!projectTrusted && (isWithin(cwd, path3.resolve(lexicalPath)) || isWithin(canonicalCwd, canonicalPath))) {
+    throw new Error(`Subagent ${label} cannot load a project path because the project is not trusted.`);
+  }
+}
+async function inspectExtensionAttachment(extensionPath, cwd, canonicalCwd, projectTrusted, signal) {
+  if (!statSync3(extensionPath).isDirectory()) return;
+  const state = {
+    entries: 0,
+    metadataBytes: 0,
+    ancestors: /* @__PURE__ */ new Set(),
+    cwd,
+    canonicalCwd,
+    projectTrusted,
+    signal
+  };
+  const inspected = await inspectPiManifest(extensionPath, state);
+  if (inspected.hasPiManifest) {
+    await inspectDeclaredExtensionEntries(extensionPath, inspected.manifest?.extensions, true, state);
+    for (const resourceType of ["skills", "prompts", "themes"]) {
+      await inspectDeclaredPackageResourceEntries(
+        extensionPath,
+        inspected.manifest?.[resourceType],
+        resourceType,
+        state
+      );
+    }
+    return;
+  }
+  const resourceDirectories = ["extensions", "skills", "prompts", "themes"].map(
+    (name) => path3.join(extensionPath, name)
+  );
+  const resourceStats = await Promise.all(resourceDirectories.map((directory) => statIfPresent(directory)));
+  if (resourceStats.some((stats) => stats?.isDirectory())) {
+    if (resourceStats[0]?.isDirectory()) await inspectAutoExtensionDirectory(resourceDirectories[0], true, state);
+    for (const [index, resourceType] of ["skills", "prompts", "themes"].entries()) {
+      if (resourceStats[index + 1]?.isDirectory()) {
+        await inspectPackageResourceDirectory(resourceDirectories[index + 1], resourceType, state);
+      }
+    }
+    return;
+  }
+  await inspectAutoExtensionDirectory(extensionPath, true, state);
+}
+async function inspectAutoExtensionDirectory(directory, discoverContents, state, enforceTrust = true) {
+  throwIfAttachmentAborted(state.signal);
+  if (enforceTrust) assertExtensionPackagePathTrusted(directory, "extension entrypoint", state);
+  const inspected = await inspectPiManifest(directory, state, enforceTrust);
+  const sourceEntries = inspected.manifest?.extensions?.filter((entrypoint) => !isExtensionOverridePattern(entrypoint));
+  if (sourceEntries && sourceEntries.length > 0) {
+    await inspectDeclaredExtensionEntries(directory, inspected.manifest?.extensions, false, state);
+    return true;
+  }
+  if (await hasRegularExtensionIndex(directory, state, enforceTrust)) return true;
+  if (!discoverContents) return false;
+  const ignoreMatcher = ignore2();
+  await addPackageIgnoreRules(ignoreMatcher, directory, directory, state, enforceTrust);
+  const entries = await readBoundedPackageEntries(directory, state, "reject");
+  let found = false;
+  for (const entry of entries) {
+    throwIfAttachmentAborted(state.signal);
+    if (entry.name.startsWith(".") || entry.name === "node_modules") continue;
+    const entryPath = path3.join(directory, entry.name);
+    const entryStats = await statIfPresent(entryPath);
+    if (!entryStats) continue;
+    const relativePath = toPosixPath(path3.relative(directory, entryPath));
+    if (ignoreMatcher.ignores(entryStats.isDirectory() ? `${relativePath}/` : relativePath)) continue;
+    if (entryStats.isFile()) {
+      if (!entry.name.endsWith(".ts") && !entry.name.endsWith(".js")) continue;
+      if (enforceTrust) assertExtensionPackagePathTrusted(entryPath, "extension entrypoint", state);
+      found = true;
+    } else if (entryStats.isDirectory()) {
+      if (enforceTrust) assertExtensionPackagePathTrusted(entryPath, "extension entrypoint", state);
+      if (await inspectAutoExtensionDirectory(entryPath, false, state, enforceTrust)) found = true;
+    }
+  }
+  return found;
+}
+async function inspectDeclaredExtensionEntries(directory, entries, expandDirectories, state) {
+  if (!entries) return;
+  for (const entrypoint of entries) {
+    throwIfAttachmentAborted(state.signal);
+    state.entries++;
+    if (state.entries > MAX_EXTENSION_SCAN_ENTRIES) throwExtensionScanLimit();
+    if (isExtensionOverridePattern(entrypoint)) continue;
+    if (hasExtensionGlob(entrypoint)) {
+      throw new Error("Subagent extension package must not contain glob entrypoint declarations.");
+    }
+    const resolved = path3.resolve(directory, entrypoint);
+    const resolvedStats = await statIfPresent(resolved);
+    if (!resolvedStats) throwUnresolvableExtensionEntrypoint();
+    if (resolvedStats.isFile()) continue;
+    if (!resolvedStats.isDirectory()) throwUnresolvableExtensionEntrypoint();
+    if (expandDirectories) {
+      if (!await inspectAutoExtensionDirectory(resolved, true, state, false)) throwUnresolvableExtensionEntrypoint();
+    } else if (!await hasRegularExtensionIndex(resolved, state, false)) {
+      throwUnresolvableExtensionEntrypoint();
+    }
+  }
+}
+async function inspectDeclaredPackageResourceEntries(directory, entries, resourceType, state) {
+  if (!entries) return;
+  for (const entrypoint of entries) {
+    throwIfAttachmentAborted(state.signal);
+    state.entries++;
+    if (state.entries > MAX_EXTENSION_SCAN_ENTRIES) throwExtensionScanLimit();
+    if (isExtensionOverridePattern(entrypoint)) continue;
+    if (hasExtensionGlob(entrypoint)) {
+      throw new Error("Subagent extension package must not contain glob resource declarations.");
+    }
+    const resolved = path3.resolve(directory, entrypoint);
+    const resolvedStats = await statIfPresent(resolved);
+    throwIfAttachmentAborted(state.signal);
+    if (resourceType === "skills" && (!resolvedStats || !resolvedStats.isFile() && !resolvedStats.isDirectory())) {
+      throw new Error("Subagent extension package must not contain a missing or unreadable declared skill.");
+    }
+    if (resolvedStats?.isDirectory()) await inspectPackageResourceDirectory(resolved, resourceType, state, false);
+  }
+}
+async function inspectPackageResourceDirectory(directory, resourceType, state, enforceTrust = true) {
+  await inspectPackageResourceTree(directory, resourceType, ignore2(), directory, 0, state, enforceTrust);
+}
+async function inspectPackageResourceTree(directory, resourceType, ignoreMatcher, rootDirectory, depth, state, enforceTrust) {
+  const canonicalDirectory = await enterPackageResourceDirectory(directory, resourceType, depth, state, enforceTrust);
+  if (!canonicalDirectory) return;
+  try {
+    await addPackageIgnoreRules(ignoreMatcher, directory, rootDirectory, state, enforceTrust);
+    const entries = await readBoundedPackageEntries(
+      directory,
+      state,
+      resourceType === "skills" ? "reject-skill" : "skip"
+    );
+    if (resourceType === "skills") {
+      const rootSkill = entries.find((entry) => entry.name === "SKILL.md");
+      if (rootSkill) {
+        const skillPath = path3.join(directory, rootSkill.name);
+        const skillStats = await statIfPresent(skillPath);
+        const relativePath = toPosixPath(path3.relative(rootDirectory, skillPath));
+        if (skillStats?.isFile() && !ignoreMatcher.ignores(relativePath)) {
+          if (enforceTrust) assertExtensionPackagePathTrusted(skillPath, "extension package resource", state);
+          return;
+        }
+      }
+    }
+    for (const entry of entries) {
+      throwIfAttachmentAborted(state.signal);
+      if (entry.name.startsWith(".") || entry.name === "node_modules") continue;
+      const entryPath = path3.join(directory, entry.name);
+      const relativePath = toPosixPath(path3.relative(rootDirectory, entryPath));
+      const entryStats = await statIfPresent(entryPath);
+      throwIfAttachmentAborted(state.signal);
+      const isSkillCandidate = resourceType === "skills" && (entry.name === "SKILL.md" || directory === rootDirectory && entry.name.endsWith(".md"));
+      if (isSkillCandidate && (!entryStats || !entryStats.isFile() && !entryStats.isDirectory()) && !ignoreMatcher.ignores(relativePath) && !ignoreMatcher.ignores(`${relativePath}/`)) {
+        throw new Error("Subagent extension package must not contain an invalid or unreadable declared skill.");
+      }
+      if (!entryStats) continue;
+      if (ignoreMatcher.ignores(entryStats.isDirectory() ? `${relativePath}/` : relativePath)) continue;
+      if (entryStats.isFile()) {
+        const isResourceFile = entry.name.endsWith(resourceType === "themes" ? ".json" : ".md") && (resourceType !== "skills" || directory === rootDirectory);
+        if (enforceTrust && isResourceFile) {
+          assertExtensionPackagePathTrusted(entryPath, "extension package resource", state);
+        }
+        continue;
+      }
+      if (!entryStats.isDirectory()) continue;
+      if (enforceTrust) assertExtensionPackagePathTrusted(entryPath, "extension package resource", state);
+      await inspectPackageResourceTree(
+        entryPath,
+        resourceType,
+        ignoreMatcher,
+        rootDirectory,
+        depth + 1,
+        state,
+        enforceTrust
+      );
+    }
+  } finally {
+    state.ancestors.delete(canonicalDirectory);
+  }
+}
+async function enterPackageResourceDirectory(directory, resourceType, depth, state, enforceTrust) {
+  throwIfAttachmentAborted(state.signal);
+  if (depth > MAX_EXTENSION_SCAN_DEPTH) throwExtensionScanLimit();
+  let canonicalDirectory;
+  try {
+    canonicalDirectory = await realpathAsync2(directory);
+  } catch {
+    throwIfAttachmentAborted(state.signal);
+    if (resourceType === "skills") throwUnreadablePackageSkillDirectory();
+    return void 0;
+  }
+  throwIfAttachmentAborted(state.signal);
+  if (enforceTrust) {
+    assertProjectPathTrusted(
+      directory,
+      canonicalDirectory,
+      "extension package resource",
+      state.cwd,
+      state.canonicalCwd,
+      state.projectTrusted
+    );
+  }
+  if (state.ancestors.has(canonicalDirectory)) {
+    throw new Error("Subagent extension package must not contain a recursive resource directory link.");
+  }
+  state.ancestors.add(canonicalDirectory);
+  return canonicalDirectory;
+}
+async function inspectPiManifest(directory, state, enforceTrust = true) {
+  const manifestPath = path3.join(directory, "package.json");
+  const manifestStats = await statIfPresent(manifestPath);
+  if (!manifestStats) return { hasPiManifest: false };
+  if (!manifestStats.isFile()) {
+    throw new Error("Subagent extension package manifest must be a regular file.");
+  }
+  if (enforceTrust) assertExtensionPackagePathTrusted(manifestPath, "extension package resource", state);
+  state.metadataBytes += manifestStats.size;
+  if (state.metadataBytes > MAX_EXTENSION_METADATA_BYTES) throwExtensionScanLimit();
+  let document;
+  try {
+    document = JSON.parse(
+      (await readFileAsync(manifestPath, { encoding: "utf8", signal: state.signal })).replace(/^\uFEFF/u, "")
+    );
+  } catch (error) {
+    if (isAbortError(error)) throw error;
+    throwIfAttachmentAborted(state.signal);
+    return { hasPiManifest: false };
+  }
+  if (!isRecord(document) || !isRecord(document.pi)) return { hasPiManifest: false };
+  return {
+    hasPiManifest: true,
+    manifest: {
+      extensions: readManifestEntries(document.pi, "extensions"),
+      skills: readManifestEntries(document.pi, "skills"),
+      prompts: readManifestEntries(document.pi, "prompts"),
+      themes: readManifestEntries(document.pi, "themes")
+    }
+  };
+}
+function readManifestEntries(manifest, resourceType) {
+  const entries = manifest[resourceType];
+  return Array.isArray(entries) && entries.every((entrypoint) => typeof entrypoint === "string") ? entries : void 0;
+}
+async function addPackageIgnoreRules(ignoreMatcher, directory, rootDirectory, state, enforceTrust) {
+  await addAttachmentIgnoreRules(ignoreMatcher, directory, rootDirectory, state.signal, (ignorePath, bytes) => {
+    if (enforceTrust) assertExtensionPackagePathTrusted(ignorePath, "extension package resource", state);
+    state.metadataBytes += bytes;
+    if (state.metadataBytes > MAX_EXTENSION_METADATA_BYTES) throwExtensionScanLimit();
+  });
+}
+async function readBoundedPackageEntries(directory, state, onFailure) {
+  let directoryHandle;
+  try {
+    directoryHandle = await opendirAsync2(directory);
+  } catch (error) {
+    if (isAbortError(error)) throw error;
+    throwIfAttachmentAborted(state.signal);
+    return failedPackageDirectoryRead(onFailure);
+  }
+  const entries = [];
+  try {
+    for await (const entry of directoryHandle) {
+      throwIfAttachmentAborted(state.signal);
+      state.entries++;
+      if (state.entries > MAX_EXTENSION_SCAN_ENTRIES) throwExtensionScanLimit();
+      entries.push(entry);
+    }
+  } catch (error) {
+    if (isAbortError(error) || isExtensionScanLimitError(error)) throw error;
+    throwIfAttachmentAborted(state.signal);
+    return failedPackageDirectoryRead(onFailure);
+  }
+  throwIfAttachmentAborted(state.signal);
+  return entries;
+}
+function failedPackageDirectoryRead(onFailure) {
+  if (onFailure === "reject") throwUnresolvableExtensionEntrypoint();
+  if (onFailure === "reject-skill") throwUnreadablePackageSkillDirectory();
+  return [];
+}
+function throwUnreadablePackageSkillDirectory() {
+  throw new Error("Subagent extension package must not contain an unreadable declared skill directory.");
+}
+async function hasRegularExtensionIndex(directory, state, enforceTrust = true) {
+  for (const filename of ["index.ts", "index.js"]) {
+    const indexPath = path3.join(directory, filename);
+    const stats = await statIfPresent(indexPath);
+    if (stats) {
+      if (enforceTrust) assertExtensionPackagePathTrusted(indexPath, "extension entrypoint", state);
+      return stats.isFile();
+    }
+  }
+  return false;
+}
+function assertExtensionPackagePathTrusted(resourcePath, label, state) {
+  if (state.projectTrusted) return;
+  const canonicalPath = realpath(resourcePath, `Subagent ${label}`);
+  assertProjectPathTrusted(resourcePath, canonicalPath, label, state.cwd, state.canonicalCwd, state.projectTrusted);
+}
+async function statIfPresent(value) {
+  try {
+    return await statAsync2(value);
+  } catch {
+    return void 0;
+  }
+}
+function throwUnresolvableExtensionEntrypoint() {
+  throw new Error("Subagent extension package must not contain a missing or unresolvable declared entrypoint.");
+}
+function isExtensionScanLimitError(error) {
+  return error instanceof Error && error.name === "ExtensionScanLimitError";
+}
+function throwExtensionScanLimit() {
+  const error = new Error(
+    `Subagent extension attachment exceeds preflight limits (${MAX_EXTENSION_SCAN_ENTRIES} entries, depth ${MAX_EXTENSION_SCAN_DEPTH}, or ${MAX_EXTENSION_METADATA_BYTES} metadata bytes).`
+  );
+  error.name = "ExtensionScanLimitError";
+  throw error;
+}
+function isExtensionOverridePattern(value) {
+  return value.startsWith("!") || value.startsWith("+") || value.startsWith("-");
+}
+function hasExtensionGlob(value) {
+  return value.includes("*") || value.includes("?");
+}
+function resolveExtensionToolName(value) {
+  if (typeof value !== "string" || !value.trim()) throw new Error("Subagent extension tool name is required.");
+  const name = value.trim();
+  if (name.length > MAX_EXTENSION_TOOL_NAME_LENGTH || name.includes(",") || hasControlCharacter(name)) {
+    throw new Error(
+      `Subagent extension tool name must be at most ${MAX_EXTENSION_TOOL_NAME_LENGTH} characters without commas or control characters.`
+    );
+  }
+  return name;
+}
+function isLocalPath(value) {
+  if (value.startsWith("//") || value.startsWith("\\\\")) return false;
+  if (path3.isAbsolute(value) || path3.win32.isAbsolute(value)) return true;
+  return !/^[a-z][a-z0-9+.-]*:/iu.test(value);
+}
+function hasControlCharacter(value) {
+  return [...value].some((character) => {
+    const codePoint = character.codePointAt(0) ?? 0;
+    return codePoint <= 31 || codePoint >= 127 && codePoint <= 159;
+  });
+}
+
 // src/runtime.ts
 var MAX_ACTIVE_JOBS = 8;
 var MAX_RETAINED_TERMINAL_JOBS = 32;
@@ -714,6 +1751,9 @@ var SubagentRuntime = class {
     this.sessionActive = true;
     this.notifyJobsChanged();
   }
+  getSessionGeneration() {
+    return this.generation;
+  }
   subscribeJobs(listener) {
     this.jobListeners.add(listener);
     return () => this.jobListeners.delete(listener);
@@ -744,24 +1784,25 @@ var SubagentRuntime = class {
       generation: this.generation
     });
     let resolveTerminal;
-    const terminal = new Promise((resolve2) => {
-      resolveTerminal = resolve2;
+    const terminal = new Promise((resolve4) => {
+      resolveTerminal = resolve4;
     });
     let resolveControl;
     let rejectControl;
-    const controlReady = new Promise((resolve2, reject) => {
-      resolveControl = resolve2;
+    const controlReady = new Promise((resolve4, reject) => {
+      resolveControl = resolve4;
       rejectControl = reject;
     });
     void controlReady.catch(() => void 0);
     const controller = new AbortController();
+    const effectiveTools = [.../* @__PURE__ */ new Set([...input.tools, ...input.extensions.flatMap((extension) => extension.tools)])];
     const job = {
       jobId,
       state: "queued",
       createdAt: this.now(),
       ...input.timeout !== void 0 ? { timeout: input.timeout } : {},
       controller,
-      tools: [...input.tools],
+      tools: effectiveTools,
       terminal,
       resolveTerminal,
       controlReady,
@@ -788,6 +1829,14 @@ var SubagentRuntime = class {
         child = await this.runChild({
           task: input.task,
           tools: [...input.tools],
+          skills: [...input.skills],
+          extensions: input.extensions.map((extension) => ({
+            path: extension.path,
+            tools: [...extension.tools]
+          })),
+          toolSources: Object.fromEntries(
+            Object.entries(input.toolSources).map(([tool, sources]) => [tool, [...sources]])
+          ),
           model: input.model,
           thinkingLevel: input.thinkingLevel,
           cwd: input.cwd,
@@ -893,21 +1942,21 @@ var SubagentRuntime = class {
     let timeout;
     let onAbort;
     let unsubscribeMessage = () => void 0;
-    const message = new Promise((resolve2) => {
-      unsubscribeMessage = this.broker.subscribeInboundMessage(() => resolve2("message"));
+    const message = new Promise((resolve4) => {
+      unsubscribeMessage = this.broker.subscribeInboundMessage(() => resolve4("message"));
     });
     const outcome = await Promise.race([
       job.terminal.then(() => "terminal"),
       message,
       ...timeoutMs !== void 0 ? [
-        new Promise((resolve2) => {
-          timeout = setTimeout(() => resolve2("timeout"), timeoutMs);
+        new Promise((resolve4) => {
+          timeout = setTimeout(() => resolve4("timeout"), timeoutMs);
           timeout.unref();
         })
       ] : [],
       ...signal ? [
-        new Promise((resolve2) => {
-          onAbort = () => resolve2("aborted");
+        new Promise((resolve4) => {
+          onAbort = () => resolve4("aborted");
           signal.addEventListener("abort", onAbort, { once: true });
         })
       ] : []
@@ -1089,7 +2138,7 @@ function abortError2(message) {
 
 // src/tools.ts
 var MAX_TASK_BYTES = 50 * 1024;
-var MAX_TOOLS = 64;
+var MAX_TOOLS = MAX_SELECTED_TOOLS;
 var MESSAGE_TYPE = "pi-subagents-message";
 var CHILD_CORE_TOOL_SET = new Set(CHILD_CORE_TOOL_NAMES);
 var THINKING_LEVEL_SET = new Set(SUBAGENT_THINKING_LEVELS);
@@ -1110,6 +2159,48 @@ var SpawnParameters = Type.Object(
         }
       )
     ),
+    skills: Type.Optional(
+      Type.Array(
+        Type.String({
+          description: "Local Markdown skill file or directory whose declared Pi skills all load and have names unique across attachments, resolved from the child working directory.",
+          minLength: 1,
+          maxLength: MAX_RESOURCE_PATH_BYTES
+        }),
+        {
+          description: "Explicit local skills available to the child. Automatic skill discovery stays disabled.",
+          maxItems: MAX_ATTACHED_SKILLS
+        }
+      )
+    ),
+    extensions: Type.Optional(
+      Type.Array(
+        Type.Object(
+          {
+            path: Type.String({
+              description: "Local extension file or directory path, resolved from the child working directory.",
+              minLength: 1,
+              maxLength: MAX_RESOURCE_PATH_BYTES
+            }),
+            tools: Type.Array(
+              Type.String({
+                description: "Exact extension-specific tool name to activate initially; built-in names are rejected.",
+                minLength: 1,
+                maxLength: MAX_EXTENSION_TOOL_NAME_LENGTH
+              }),
+              {
+                description: "Extension tools to activate. Use an empty list for lifecycle or provider behavior only. All child tool names share a 16 KiB startup bootstrap.",
+                maxItems: MAX_SELECTED_TOOLS
+              }
+            )
+          },
+          { additionalProperties: false }
+        ),
+        {
+          description: "Explicit trusted local extensions loaded in the isolated child process.",
+          maxItems: MAX_ATTACHED_EXTENSIONS
+        }
+      )
+    ),
     thinkingLevel: Type.Optional(
       StringEnum(SUBAGENT_THINKING_LEVELS, {
         description: "Child thinking level. Defaults to the main agent's effective level."
@@ -1168,7 +2259,7 @@ function registerSubagentTools(pi, dependencies = {}) {
   pi.registerTool({
     name: "subagent_spawn",
     label: "Subagent \xB7 Spawn",
-    description: "Use subagent_spawn to start one Pi subagent job and return its jobId immediately. The task defines the child's specialization, and the selected tools define its capabilities. The job may ask the main agent questions and publishes one asynchronous completion when terminal.",
+    description: "Use subagent_spawn to start one Pi subagent job and return its jobId immediately. The task defines the child's specialization; selected core tools and explicit trusted local skills or extensions define its initial capabilities. The job may ask the main agent questions and publishes one asynchronous completion when terminal.",
     promptSnippet: "Use subagent_spawn to start one Pi subagent job",
     parameters: SpawnParameters,
     prepareArguments: prepareSpawnArguments,
@@ -1177,18 +2268,50 @@ function registerSubagentTools(pi, dependencies = {}) {
       assertNotNested();
       const task = validateTask(params.task, "subagent_spawn");
       const tools = resolveTools(params.tools);
-      const model = resolveChildModel(ctx);
+      const cwd = ctx.cwd;
+      const projectTrusted = ctx.isProjectTrusted();
+      const sessionGeneration = runtime.getSessionGeneration();
+      const attachments = await resolveResourceAttachments(
+        { skills: params.skills, extensions: params.extensions },
+        { cwd, projectTrusted, coreTools: tools, signal }
+      );
+      throwIfAborted2(signal, "Subagent spawn was cancelled");
+      if (runtime.getSessionGeneration() !== sessionGeneration) {
+        throw new Error("Subagent spawn session changed during attachment validation; retry the request.");
+      }
+      if (ctx.cwd !== cwd || ctx.isProjectTrusted() !== projectTrusted) {
+        throw new Error("Subagent spawn context changed during attachment validation; retry the request.");
+      }
+      if (attachments.extensions.length > 0) {
+        assertChildBootstrapCapacity([.../* @__PURE__ */ new Set([...attachments.effectiveTools, ...CHILD_COMMUNICATION_TOOL_NAMES])]);
+      }
+      const model = resolveChildModel(ctx, attachments.extensions.length > 0);
       const thinkingLevel = resolveThinkingLevel(params.thinkingLevel ?? ctx.thinkingLevel ?? pi.getThinkingLevel());
       resolveTimeoutMs(params.timeout);
+      assertChildCommandCapacity(
+        {
+          tools,
+          skills: attachments.skills,
+          extensions: attachments.extensions,
+          model,
+          thinkingLevel,
+          projectTrusted
+        },
+        dependencies.platform
+      );
+      throwIfAborted2(signal, "Subagent spawn was cancelled");
       return toolResult(
         runtime.start({
           task,
           tools,
+          skills: attachments.skills,
+          extensions: attachments.extensions,
+          toolSources: attachments.toolSources,
           model,
           thinkingLevel,
-          cwd: ctx.cwd,
+          cwd,
           timeout: params.timeout,
-          projectTrusted: ctx.isProjectTrusted()
+          projectTrusted
         })
       );
     }
@@ -1322,11 +2445,11 @@ function resolveTools(value) {
   }
   return tools;
 }
-function resolveChildModel(ctx) {
+function resolveChildModel(ctx, hasAttachedExtensions) {
   const model = ctx.model;
   if (!model) throw new Error("Subagent model is unavailable because no main-agent model is selected.");
   const provider = sanitizeTerminalText(model.provider).slice(0, 128);
-  if (ctx.modelRegistry.getRegisteredProviderIds().includes(model.provider)) {
+  if (!hasAttachedExtensions && ctx.modelRegistry.getRegisteredProviderIds().includes(model.provider)) {
     throw new Error(`Subagent model provider ${provider} is unavailable because children disable parent extensions.`);
   }
   if (ctx.modelRegistry.getProviderAuthStatus(model.provider).source === "runtime") {
@@ -1348,15 +2471,6 @@ function prepareSpawnArguments(args) {
 function prepareWaitArguments(args) {
   return prepareTimeoutArguments(args);
 }
-function prepareTimeoutArguments(args) {
-  if (!args || typeof args !== "object") return args;
-  if (!Object.hasOwn(args, "timeoutMs")) return args;
-  const record = args;
-  if (typeof record.timeoutMs !== "number") return record;
-  const { timeoutMs, ...prepared } = record;
-  if (prepared.timeout === void 0) return { ...prepared, timeout: timeoutMs / 1e3 };
-  return prepared;
-}
 function resolveMainSendArguments(params) {
   validateMessage(params.message, "Subagent message");
   const recipient = optionalIdentifier(params.recipient, "recipient");