@poncho-ai/harness 0.7.0 → 0.7.2

package/dist/index.js

@@ -7,8 +7,6 @@ import YAML from "yaml";
 
 // src/tool-policy.ts
 var MCP_PATTERN = /^[^/*\s]+\/(\*|[^/*\s]+)$/;
-var MCP_TOOL_PATTERN = /^(\*|[^/*\s]+)$/;
-var SCRIPT_PATTERN = /^[^/*\s]+\/(\*|[^*\s]+)$/;
 var validateMcpPattern = (pattern, path) => {
   if (!MCP_PATTERN.test(pattern)) {
     throw new Error(
@@ -16,19 +14,35 @@ var validateMcpPattern = (pattern, path) => {
     );
   }
 };
-var validateMcpToolPattern = (pattern, path) => {
-  if (!MCP_TOOL_PATTERN.test(pattern)) {
+var normalizeRelativeScriptPattern = (value, path) => {
+  const trimmed = value.trim();
+  if (trimmed.length === 0) {
+    throw new Error(`Invalid script pattern at ${path}: value cannot be empty.`);
+  }
+  const withoutDotPrefix = trimmed.startsWith("./") ? trimmed.slice(2) : trimmed;
+  const normalized = withoutDotPrefix.replaceAll("\\", "/");
+  if (normalized.startsWith("/") || normalized === ".." || normalized.startsWith("../")) {
     throw new Error(
-      `Invalid MCP tool pattern at ${path}: "${pattern}". Expected "tool" or "*".`
+      `Invalid script pattern at ${path}: "${value}". Expected a relative path.`
     );
   }
-};
-var validateScriptPattern = (pattern, path) => {
-  if (!SCRIPT_PATTERN.test(pattern)) {
+  const segments = normalized.split("/");
+  if (segments.some((segment) => segment === "" || segment === "." || segment === "..")) {
     throw new Error(
-      `Invalid script pattern at ${path}: "${pattern}". Expected "skill/script-path" or "skill/*".`
+      `Invalid script pattern at ${path}: "${value}". Expected a normalized relative path.`
     );
   }
+  return `./${segments.join("/")}`;
+};
+var isSiblingScriptsPattern = (pattern) => pattern === "./scripts" || pattern.startsWith("./scripts/");
+var escapeRegex = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+var matchesRelativeScriptPattern = (value, pattern) => {
+  const normalizedValue = normalizeRelativeScriptPattern(value, "value");
+  const normalizedPattern = normalizeRelativeScriptPattern(pattern, "pattern");
+  const regex = new RegExp(
+    `^${escapeRegex(normalizedPattern).replaceAll("\\*", ".*")}$`
+  );
+  return regex.test(normalizedValue);
 };
 var splitPattern = (pattern) => {
   const slash = pattern.indexOf("/");
@@ -48,48 +62,6 @@ var matchesSlashPattern = (value, pattern) => {
   }
   return targetName === patternName;
 };
-var mergePolicyForEnvironment = (policy, environment) => {
-  const base = {
-    mode: policy?.mode,
-    include: [...policy?.include ?? []],
-    exclude: [...policy?.exclude ?? []]
-  };
-  const env = policy?.byEnvironment?.[environment];
-  if (!env) {
-    return base;
-  }
-  return {
-    mode: env.mode ?? base.mode,
-    include: env.include ? [...env.include] : base.include,
-    exclude: env.exclude ? [...env.exclude] : base.exclude
-  };
-};
-var applyToolPolicy = (values, policy) => {
-  const mode = policy?.mode ?? "all";
-  const include = policy?.include ?? [];
-  const exclude = policy?.exclude ?? [];
-  const allowed = [];
-  const filteredOut = [];
-  for (const value of values) {
-    const inInclude = include.some((pattern) => matchesSlashPattern(value, pattern));
-    const inExclude = exclude.some((pattern) => matchesSlashPattern(value, pattern));
-    let keep = true;
-    if (mode === "allowlist") {
-      keep = inInclude;
-    } else if (mode === "denylist") {
-      keep = !inExclude;
-    }
-    if (mode === "all" && exclude.length > 0) {
-      keep = !inExclude;
-    }
-    if (keep) {
-      allowed.push(value);
-    } else {
-      filteredOut.push(value);
-    }
-  }
-  return { allowed, filteredOut };
-};
 
 // src/agent-parser.ts
 var FRONTMATTER_PATTERN = /^---\s*\n([\s\S]*?)\n---\s*\n?([\s\S]*)$/;
@@ -109,17 +81,46 @@ var parseAgentMarkdown = (content) => {
   }
   const modelValue = asRecord(parsed.model);
   const limitsValue = asRecord(parsed.limits);
-  const allowedToolsList = Array.isArray(parsed["allowed-tools"]) ? parsed["allowed-tools"].filter((item) => typeof item === "string") : [];
-  const mcpTools = [];
-  const scriptTools = [];
-  for (const [index, tool] of allowedToolsList.entries()) {
-    if (tool.startsWith("mcp:")) {
-      const withoutPrefix = tool.slice(4);
-      mcpTools.push(withoutPrefix);
-      validateMcpPattern(withoutPrefix, `AGENT.md frontmatter allowed-tools[${index}]`);
-    } else if (tool.includes("/scripts/")) {
-      scriptTools.push(tool);
-      validateScriptPattern(tool, `AGENT.md frontmatter allowed-tools[${index}]`);
+  const parseTools = (key) => {
+    const entries = Array.isArray(parsed[key]) ? parsed[key].filter((item) => typeof item === "string") : [];
+    const mcp = [];
+    const scripts = [];
+    for (const [index, entry] of entries.entries()) {
+      if (entry.startsWith("mcp:")) {
+        const withoutPrefix = entry.slice(4);
+        validateMcpPattern(withoutPrefix, `AGENT.md frontmatter ${key}[${index}]`);
+        mcp.push(withoutPrefix);
+        continue;
+      }
+      scripts.push(
+        normalizeRelativeScriptPattern(entry, `AGENT.md frontmatter ${key}[${index}]`)
+      );
+    }
+    return { mcp, scripts };
+  };
+  const allowedTools = parseTools("allowed-tools");
+  const approvalRequired = parseTools("approval-required");
+  for (const pattern of approvalRequired.mcp) {
+    const matchesAllowed = allowedTools.mcp.some(
+      (allowedPattern) => matchesSlashPattern(pattern, allowedPattern)
+    );
+    if (!matchesAllowed) {
+      throw new Error(
+        `Invalid AGENT.md frontmatter approval-required: MCP pattern "${pattern}" must be included in allowed-tools.`
+      );
+    }
+  }
+  for (const pattern of approvalRequired.scripts) {
+    if (pattern.startsWith("./scripts/")) {
+      continue;
+    }
+    const matchesAllowed = allowedTools.scripts.some(
+      (allowedPattern) => matchesRelativeScriptPattern(pattern, allowedPattern)
+    );
+    if (!matchesAllowed) {
+      throw new Error(
+        `Invalid AGENT.md frontmatter approval-required: script pattern "${pattern}" must be included in allowed-tools when outside ./scripts/.`
+      );
     }
   }
   const frontmatter = {
@@ -135,9 +136,13 @@ var parseAgentMarkdown = (content) => {
       maxSteps: asNumberOrUndefined(limitsValue.maxSteps),
       timeout: asNumberOrUndefined(limitsValue.timeout)
     } : void 0,
-    allowedTools: mcpTools.length > 0 || scriptTools.length > 0 ? {
-      mcp: mcpTools.length > 0 ? mcpTools : void 0,
-      scripts: scriptTools.length > 0 ? scriptTools : void 0
+    allowedTools: allowedTools.mcp.length > 0 || allowedTools.scripts.length > 0 ? {
+      mcp: allowedTools.mcp.length > 0 ? allowedTools.mcp : void 0,
+      scripts: allowedTools.scripts.length > 0 ? allowedTools.scripts : void 0
+    } : void 0,
+    approvalRequired: approvalRequired.mcp.length > 0 || approvalRequired.scripts.length > 0 ? {
+      mcp: approvalRequired.mcp.length > 0 ? approvalRequired.mcp : void 0,
+      scripts: approvalRequired.scripts.length > 0 ? approvalRequired.scripts : void 0
     } : void 0
   };
   return {
@@ -1058,43 +1063,8 @@ var LocalMcpBridge = class {
           `Invalid MCP auth config for "${name}": auth.type "bearer" requires auth.tokenEnv.`
         );
       }
-      this.validatePolicy(server, name);
     }
   }
-  validatePolicy(server, serverName) {
-    const policy = server.tools;
-    const validateList = (values, path) => {
-      for (const [index, value] of (values ?? []).entries()) {
-        validateMcpToolPattern(value, `${path}[${index}]`);
-      }
-    };
-    validateList(policy?.include, `mcp.${serverName}.tools.include`);
-    validateList(policy?.exclude, `mcp.${serverName}.tools.exclude`);
-    validateList(
-      policy?.byEnvironment?.development?.include,
-      `mcp.${serverName}.tools.byEnvironment.development.include`
-    );
-    validateList(
-      policy?.byEnvironment?.development?.exclude,
-      `mcp.${serverName}.tools.byEnvironment.development.exclude`
-    );
-    validateList(
-      policy?.byEnvironment?.staging?.include,
-      `mcp.${serverName}.tools.byEnvironment.staging.include`
-    );
-    validateList(
-      policy?.byEnvironment?.staging?.exclude,
-      `mcp.${serverName}.tools.byEnvironment.staging.exclude`
-    );
-    validateList(
-      policy?.byEnvironment?.production?.include,
-      `mcp.${serverName}.tools.byEnvironment.production.include`
-    );
-    validateList(
-      policy?.byEnvironment?.production?.exclude,
-      `mcp.${serverName}.tools.byEnvironment.production.exclude`
-    );
-  }
   getServerName(server) {
     return server.name ?? server.url;
   }
@@ -1219,7 +1189,7 @@ var LocalMcpBridge = class {
     }
     return output.sort();
   }
-  async loadTools(requestedPatterns, environment = "development") {
+  async loadTools(requestedPatterns) {
     for (const [index, pattern] of requestedPatterns.entries()) {
       validateMcpPattern(pattern, `requestedPatterns[${index}]`);
     }
@@ -1227,7 +1197,6 @@ var LocalMcpBridge = class {
     if (requestedPatterns.length === 0) {
       return tools;
     }
-    const filteredByPolicy = [];
     const filteredByIntent = [];
     for (const server of this.remoteServers) {
       const serverName = this.getServerName(server);
@@ -1237,20 +1206,12 @@ var LocalMcpBridge = class {
       }
       const discovered = this.toolCatalog.get(serverName) ?? [];
       const fullNames = discovered.map((tool) => `${serverName}/${tool.name}`);
-      const effectivePolicy = mergePolicyForEnvironment(server.tools, environment);
-      const fullPatternPolicy = effectivePolicy ? {
-        ...effectivePolicy,
-        include: effectivePolicy.include?.map((p) => `${serverName}/${p}`),
-        exclude: effectivePolicy.exclude?.map((p) => `${serverName}/${p}`)
-      } : effectivePolicy;
-      const policyDecision = applyToolPolicy(fullNames, fullPatternPolicy);
-      filteredByPolicy.push(...policyDecision.filteredOut);
-      const selectedFullNames = policyDecision.allowed.filter(
+      const selectedFullNames = fullNames.filter(
         (toolName) => requestedPatterns.some((pattern) => matchesSlashPattern(toolName, pattern))
       );
-      for (const allowedTool of policyDecision.allowed) {
-        if (!selectedFullNames.includes(allowedTool)) {
-          filteredByIntent.push(allowedTool);
+      for (const discoveredTool of fullNames) {
+        if (!selectedFullNames.includes(discoveredTool)) {
+          filteredByIntent.push(discoveredTool);
         }
       }
       const selectedRawNames = new Set(
@@ -1264,7 +1225,7 @@ var LocalMcpBridge = class {
     this.log("info", "tools.selected", {
       requestedPatternCount: requestedPatterns.length,
       registeredCount: tools.length,
-      filteredByPolicyCount: filteredByPolicy.length,
+      filteredByPolicyCount: 0,
       filteredByIntentCount: filteredByIntent.length
     });
     return tools;
@@ -1322,7 +1283,7 @@ var createModelProvider = (provider) => {
 };
 
 // src/skill-context.ts
-import { readFile as readFile4, readdir as readdir2 } from "fs/promises";
+import { readFile as readFile4, readdir as readdir2, stat } from "fs/promises";
 import { dirname as dirname3, resolve as resolve5, normalize } from "path";
 import YAML2 from "yaml";
 var DEFAULT_SKILL_DIRS = ["skills"];
@@ -1351,26 +1312,53 @@ var parseSkillFrontmatter = (content) => {
     return void 0;
   }
   const description = typeof parsed.description === "string" ? parsed.description.trim() : "";
-  const allowedToolsList = Array.isArray(parsed["allowed-tools"]) ? parsed["allowed-tools"].filter((item) => typeof item === "string") : [];
-  const mcpTools = [];
-  const scriptTools = [];
-  for (const [index, tool] of allowedToolsList.entries()) {
-    if (tool.startsWith("mcp:")) {
-      const withoutPrefix = tool.slice(4);
-      mcpTools.push(withoutPrefix);
-      validateMcpPattern(withoutPrefix, `SKILL.md frontmatter allowed-tools[${index}]`);
-    } else if (tool.includes("/scripts/")) {
-      scriptTools.push(tool);
-      validateScriptPattern(tool, `SKILL.md frontmatter allowed-tools[${index}]`);
+  const parseTools = (key) => {
+    const entries = Array.isArray(parsed[key]) ? parsed[key].filter((item) => typeof item === "string") : [];
+    const mcp = [];
+    const scripts = [];
+    for (const [index, entry] of entries.entries()) {
+      if (entry.startsWith("mcp:")) {
+        const withoutPrefix = entry.slice(4);
+        validateMcpPattern(withoutPrefix, `SKILL.md frontmatter ${key}[${index}]`);
+        mcp.push(withoutPrefix);
+        continue;
+      }
+      scripts.push(
+        normalizeRelativeScriptPattern(entry, `SKILL.md frontmatter ${key}[${index}]`)
+      );
+    }
+    return { mcp, scripts };
+  };
+  const allowedTools = parseTools("allowed-tools");
+  const approvalRequired = parseTools("approval-required");
+  for (const pattern of approvalRequired.mcp) {
+    const matchesAllowed = allowedTools.mcp.some(
+      (allowedPattern) => matchesSlashPattern(pattern, allowedPattern)
+    );
+    if (!matchesAllowed) {
+      throw new Error(
+        `Invalid SKILL.md frontmatter approval-required: MCP pattern "${pattern}" must be included in allowed-tools.`
+      );
+    }
+  }
+  for (const pattern of approvalRequired.scripts) {
+    if (isSiblingScriptsPattern(pattern)) {
+      continue;
+    }
+    const matchesAllowed = allowedTools.scripts.some(
+      (allowedPattern) => matchesRelativeScriptPattern(pattern, allowedPattern)
+    );
+    if (!matchesAllowed) {
+      throw new Error(
+        `Invalid SKILL.md frontmatter approval-required: script pattern "${pattern}" must be included in allowed-tools when outside ./scripts/.`
+      );
     }
   }
   return {
     name,
     description,
-    allowedTools: {
-      mcp: mcpTools,
-      scripts: scriptTools
-    }
+    allowedTools,
+    approvalRequired
   };
 };
 var collectSkillManifests = async (directory) => {
@@ -1378,11 +1366,22 @@ var collectSkillManifests = async (directory) => {
   const files = [];
   for (const entry of entries) {
     const fullPath = resolve5(directory, entry.name);
-    if (entry.isDirectory()) {
+    let isDir = entry.isDirectory();
+    let isFile = entry.isFile();
+    if (entry.isSymbolicLink()) {
+      try {
+        const s = await stat(fullPath);
+        isDir = s.isDirectory();
+        isFile = s.isFile();
+      } catch {
+        continue;
+      }
+    }
+    if (isDir) {
       files.push(...await collectSkillManifests(fullPath));
       continue;
     }
-    if (entry.isFile() && entry.name.toLowerCase() === "skill.md") {
+    if (isFile && entry.name.toLowerCase() === "skill.md") {
       files.push(fullPath);
     }
   }
@@ -1416,6 +1415,9 @@ var loadSkillMetadata = async (workingDir, extraSkillPaths) => {
       if (message.startsWith("Invalid MCP tool pattern") || message.startsWith("Invalid script pattern")) {
         throw new Error(`Invalid SKILL.md frontmatter at ${manifest}: ${message}`);
       }
+      if (message.startsWith("Invalid SKILL.md frontmatter approval-required")) {
+        throw new Error(`Invalid SKILL.md frontmatter at ${manifest}: ${message}`);
+      }
     }
   }
   return skills;
@@ -1546,16 +1548,13 @@ function convertSchema(schema) {
 
 // src/skill-tools.ts
 import { defineTool as defineTool3 } from "@poncho-ai/sdk";
-import { access as access2, readdir as readdir3 } from "fs/promises";
+import { access as access2, readdir as readdir3, stat as stat2 } from "fs/promises";
 import { extname, normalize as normalize2, resolve as resolve6, sep as sep2 } from "path";
 import { pathToFileURL } from "url";
 import { createJiti } from "jiti";
 var createSkillTools = (skills, options) => {
-  if (skills.length === 0) {
-    return [];
-  }
   const skillsByName = new Map(skills.map((skill) => [skill.name, skill]));
-  const knownNames = skills.map((skill) => skill.name).join(", ");
+  const knownNames = skills.length > 0 ? skills.map((skill) => skill.name).join(", ") : "(none)";
   return [
     defineTool3({
       name: "activate_skill",
@@ -1677,7 +1676,7 @@ var createSkillTools = (skills, options) => {
     }),
     defineTool3({
       name: "list_skill_scripts",
-      description: `List JavaScript/TypeScript script files available under a skill's scripts directory. Available skills: ${knownNames}`,
+      description: `List JavaScript/TypeScript script files available under a skill directory (recursive). Available skills: ${knownNames}`,
       inputSchema: {
         type: "object",
         properties: {
@@ -1712,62 +1711,81 @@ var createSkillTools = (skills, options) => {
     }),
     defineTool3({
       name: "run_skill_script",
-      description: `Run a JavaScript/TypeScript module in a skill's scripts directory. Uses default export function or named run/main/handler function. Available skills: ${knownNames}`,
+      description: `Run a JavaScript/TypeScript module in a skill or project directory. Uses default export function or named run/main/handler function. Available skills: ${knownNames}`,
       inputSchema: {
         type: "object",
         properties: {
           skill: {
             type: "string",
-            description: "Name of the skill"
+            description: "Optional skill name. Omit to run a project-level script relative to AGENT.md directory."
           },
           script: {
             type: "string",
-            description: "Relative path under scripts/ (e.g. scripts/summarize.ts or summarize.ts)"
+            description: "Relative script path from the skill/project root (e.g. ./fetch-page.ts, scripts/summarize.ts, tools/multiply.ts)"
           },
           input: {
             type: "object",
             description: "Optional JSON input payload passed to the script function"
           }
         },
-        required: ["skill", "script"],
+        required: ["script"],
         additionalProperties: false
       },
       handler: async (input) => {
         const name = typeof input.skill === "string" ? input.skill.trim() : "";
         const script = typeof input.script === "string" ? input.script.trim() : "";
         const payload = typeof input.input === "object" && input.input !== null ? input.input : {};
-        const skill = skillsByName.get(name);
-        if (!skill) {
-          return {
-            error: `Unknown skill: "${name}". Available skills: ${knownNames}`
-          };
-        }
         if (!script) {
           return { error: "Script path is required" };
         }
         try {
-          const scriptPath = resolveSkillScriptPath(skill, script);
-          const relativeScript = `scripts/${scriptPath.slice(resolve6(skill.skillDir, "scripts").length + 1).split(sep2).join("/")}`;
-          if (options?.isScriptAllowed && !options.isScriptAllowed(name, relativeScript)) {
+          if (name) {
+            const skill = skillsByName.get(name);
+            if (!skill) {
+              return {
+                error: `Unknown skill: "${name}". Available skills: ${knownNames}`
+              };
+            }
+            const resolved2 = resolveScriptPath(skill.skillDir, script);
+            if (options?.isScriptAllowed && !options.isScriptAllowed(name, resolved2.relativePath)) {
+              return {
+                error: `Script "${resolved2.relativePath}" for skill "${name}" is not allowed by policy.`
+              };
+            }
+            await access2(resolved2.fullPath);
+            const fn2 = await loadRunnableScriptFunction(resolved2.fullPath);
+            const output2 = await fn2(payload, {
+              scope: "skill",
+              skill: name,
+              scriptPath: resolved2.fullPath
+            });
             return {
-              error: `Script "${relativeScript}" for skill "${name}" is not allowed by policy.`
+              skill: name,
+              script: resolved2.relativePath,
+              output: output2
             };
           }
-          await access2(scriptPath);
-          const fn = await loadRunnableScriptFunction(scriptPath);
+          const baseDir = options?.workingDir ?? process.cwd();
+          const resolved = resolveScriptPath(baseDir, script);
+          if (options?.isRootScriptAllowed && !options.isRootScriptAllowed(resolved.relativePath)) {
+            return {
+              error: `Script "${resolved.relativePath}" is not allowed by policy.`
+            };
+          }
+          await access2(resolved.fullPath);
+          const fn = await loadRunnableScriptFunction(resolved.fullPath);
           const output = await fn(payload, {
-            skill: name,
-            skillDir: skill.skillDir,
-            scriptPath
+            scope: "agent",
+            scriptPath: resolved.fullPath
           });
           return {
-            skill: name,
-            script,
+            skill: null,
+            script: resolved.relativePath,
             output
           };
         } catch (err) {
           return {
-            error: `Failed to run script "${script}" in skill "${name}": ${err instanceof Error ? err.message : String(err)}`
+            error: name ? `Failed to run script "${script}" in skill "${name}": ${err instanceof Error ? err.message : String(err)}` : `Failed to run script "${script}" from AGENT scope: ${err instanceof Error ? err.message : String(err)}`
           };
         }
       }
@@ -1776,25 +1794,35 @@ var createSkillTools = (skills, options) => {
 };
 var SCRIPT_EXTENSIONS = /* @__PURE__ */ new Set([".js", ".mjs", ".cjs", ".ts", ".mts", ".cts"]);
 var listSkillScripts = async (skill, isScriptAllowed) => {
-  const scriptsRoot = resolve6(skill.skillDir, "scripts");
-  try {
-    await access2(scriptsRoot);
-  } catch {
-    return [];
-  }
-  const scripts = await collectScriptFiles(scriptsRoot);
-  return scripts.map((fullPath) => `scripts/${fullPath.slice(scriptsRoot.length + 1).split(sep2).join("/")}`).filter((path) => isScriptAllowed ? isScriptAllowed(skill.name, path) : true).sort();
+  const scripts = await collectScriptFiles(skill.skillDir);
+  return scripts.map((fullPath) => fullPath.slice(skill.skillDir.length + 1).split(sep2).join("/")).filter((relativePath) => relativePath.toLowerCase() !== "skill.md").map(
+    (relativePath) => relativePath.includes("/") ? relativePath : `./${relativePath}`
+  ).filter((path) => isScriptAllowed ? isScriptAllowed(skill.name, path) : true).sort();
 };
 var collectScriptFiles = async (directory) => {
   const entries = await readdir3(directory, { withFileTypes: true });
   const files = [];
   for (const entry of entries) {
+    if (entry.name === "node_modules") {
+      continue;
+    }
     const fullPath = resolve6(directory, entry.name);
-    if (entry.isDirectory()) {
+    let isDir = entry.isDirectory();
+    let isFile = entry.isFile();
+    if (entry.isSymbolicLink()) {
+      try {
+        const s = await stat2(fullPath);
+        isDir = s.isDirectory();
+        isFile = s.isFile();
+      } catch {
+        continue;
+      }
+    }
+    if (isDir) {
       files.push(...await collectScriptFiles(fullPath));
       continue;
     }
-    if (entry.isFile()) {
+    if (isFile) {
       const extension = extname(fullPath).toLowerCase();
       if (SCRIPT_EXTENSIONS.has(extension)) {
         files.push(fullPath);
@@ -1803,16 +1831,23 @@ var collectScriptFiles = async (directory) => {
   }
   return files;
 };
-var resolveSkillScriptPath = (skill, relativePath) => {
-  const normalized = normalize2(relativePath);
+var normalizeScriptPolicyPath = (relativePath) => {
+  const trimmed = relativePath.trim();
+  const normalized = normalize2(trimmed).split(sep2).join("/");
   if (normalized.startsWith("..") || normalized.startsWith("/")) {
-    throw new Error("Script path must be relative and within the skill directory");
+    throw new Error("Script path must be relative and within the allowed directory");
+  }
+  const withoutDotPrefix = normalized.startsWith("./") ? normalized.slice(2) : normalized;
+  if (withoutDotPrefix.length === 0 || withoutDotPrefix === ".") {
+    throw new Error("Script path must point to a file");
   }
-  const normalizedWithPrefix = normalized.startsWith("scripts/") ? normalized : `scripts/${normalized}`;
-  const fullPath = resolve6(skill.skillDir, normalizedWithPrefix);
-  const scriptsRoot = resolve6(skill.skillDir, "scripts");
-  if (!fullPath.startsWith(`${scriptsRoot}${sep2}`) && fullPath !== scriptsRoot) {
-    throw new Error("Script path must stay inside the scripts directory");
+  return withoutDotPrefix;
+};
+var resolveScriptPath = (baseDir, relativePath) => {
+  const normalized = normalizeScriptPolicyPath(relativePath);
+  const fullPath = resolve6(baseDir, normalized);
+  if (!fullPath.startsWith(`${resolve6(baseDir)}${sep2}`) && fullPath !== resolve6(baseDir)) {
+    throw new Error("Script path must stay inside the allowed directory");
   }
   const extension = extname(fullPath).toLowerCase();
   if (!SCRIPT_EXTENSIONS.has(extension)) {
@@ -1820,7 +1855,10 @@ var resolveSkillScriptPath = (skill, relativePath) => {
       `Unsupported script extension "${extension || "(none)"}". Allowed: ${[...SCRIPT_EXTENSIONS].join(", ")}`
     );
   }
-  return fullPath;
+  return {
+    fullPath,
+    relativePath: `./${normalized}`
+  };
 };
 var loadRunnableScriptFunction = async (scriptPath) => {
   const loaded = await loadScriptModule(scriptPath);
@@ -1979,26 +2017,38 @@ You are running locally in development mode. Treat this as an editable agent wor
 
 You can extend your own capabilities by creating custom JavaScript/TypeScript scripts:
 
-- Create scripts under \`skills/<skill-name>/scripts/\` to add new functionality
+- Create scripts under \`skills/<skill-name>/\` (recursive) to add new functionality
 - Scripts can perform any Node.js operations: API calls, file processing, data transformations, web scraping, etc.
 - Use the \`run_skill_script\` tool to execute these scripts and integrate results into your workflow
 - This allows you to dynamically add custom tools and capabilities as users need them, without requiring external dependencies or MCP servers
 
+## Skill Authoring Guardrails
+
+- Every \`SKILL.md\` must include YAML frontmatter between \`---\` markers.
+- Required frontmatter fields for discovery: \`name\` (non-empty string). Add \`description\` whenever possible.
+- \`allowed-tools\` and \`approval-required\` belong in SKILL frontmatter (not in script files).
+- MCP entries in frontmatter must use \`mcp:server/tool\` or \`mcp:server/*\`.
+- Script entries in frontmatter must be relative paths (for example \`./scripts/fetch.ts\`, \`./tools/audit.ts\`, \`./fetch-page.ts\`).
+- \`approval-required\` should be a stricter subset of allowed access:
+  - MCP entries must also appear in \`allowed-tools\`.
+  - Script entries outside \`./scripts/\` must also appear in \`allowed-tools\`.
+- Keep MCP server connection details (\`url\`, auth env vars) in \`poncho.config.js\` only.
+
 ## When users ask about customization:
 
 - Explain and edit \`poncho.config.js\` for model/provider, storage+memory, auth, telemetry, and MCP settings.
 - Help create or update local skills under \`skills/<skill-name>/SKILL.md\`.
-- For executable skills, add JavaScript/TypeScript scripts under \`skills/<skill-name>/scripts/\` and run them via \`run_skill_script\`.
-- For MCP setup, default to direct \`poncho.config.js\` edits (\`mcp\` entries with URL, bearer token env, and tool policy).
-- Keep MCP server connection details in \`poncho.config.js\` only (name/url/auth/tools policy). Do not move server definitions into \`SKILL.md\`.
-- In \`AGENT.md\`/\`SKILL.md\` frontmatter, declare MCP tools in \`allowed-tools\` array as \`mcp:server/pattern\` (for example \`mcp:linear/*\` or \`mcp:linear/list_issues\`).
+- For executable scripts, use a sibling \`scripts/\` directory next to \`AGENT.md\` or \`SKILL.md\`; run via \`run_skill_script\`.
+- To use a custom script folder (for example \`tools/\`), declare it in \`allowed-tools\` and gate sensitive paths with \`approval-required\` in frontmatter.
+- For MCP setup, default to direct \`poncho.config.js\` edits (\`mcp\` entries with URL and bearer token env).
+- Keep MCP server connection details in \`poncho.config.js\` only (name/url/auth). Do not move server definitions into \`SKILL.md\`.
+- In \`AGENT.md\`/\`SKILL.md\` frontmatter, declare MCP tools in \`allowed-tools\` array as \`mcp:server/pattern\` (for example \`mcp:linear/*\` or \`mcp:linear/list_issues\`), and use \`approval-required\` for human-gated calls.
 - Never use nested MCP objects in skill frontmatter (for example \`mcp: [{ name, url, auth }]\`).
-- To scope tools to a skill: keep server config in \`poncho.config.js\`, add desired \`allowed-tools\` patterns in that skill's \`SKILL.md\`, and remove global \`AGENT.md\` patterns if you do not want global availability.
+- To scope tools to a skill: keep server config in \`poncho.config.js\`, add desired \`allowed-tools\`/ \`approval-required\` patterns in that skill's \`SKILL.md\`, and remove global \`AGENT.md\` patterns if you do not want global availability.
 - Do not invent unsupported top-level config keys (for example \`model\` in \`poncho.config.js\`). Keep existing config structure unless README/spec explicitly says otherwise.
-- In \`poncho.config.js\`, MCP tool patterns are scoped within each server object, so use just the tool name (for example \`include: ["*"]\` or \`include: ["list_issues"]\`), not the full \`server/tool\` format.
 - Keep \`poncho.config.js\` valid JavaScript and preserve existing imports/types/comments. If there is a JSDoc type import, do not rewrite it to a different package name.
 - Preferred MCP config shape in \`poncho.config.js\`:
-  \`mcp: [{ name: "linear", url: "https://mcp.linear.app/mcp", auth: { type: "bearer", tokenEnv: "LINEAR_TOKEN" }, tools: { mode: "allowlist", include: ["*"] } }]\`
+  \`mcp: [{ name: "linear", url: "https://mcp.linear.app/mcp", auth: { type: "bearer", tokenEnv: "LINEAR_TOKEN" } }]\`
 - If shell/CLI access exists, you can use \`poncho mcp add --url ... --name ... --auth-bearer-env ...\`, then \`poncho mcp tools list <server>\` and \`poncho mcp tools select <server>\`.
 - If shell/CLI access is unavailable, ask the user to run needed commands and provide exact copy-paste commands.
 - For setup, skills, MCP, auth, storage, telemetry, or "how do I..." questions, proactively read \`README.md\` with \`read_file\` before answering.
@@ -2076,9 +2126,6 @@ var AgentHarness = class {
       this.dispatcher.registerMany(options.toolDefinitions);
     }
   }
-  runtimeEnvironment() {
-    return this.environment ?? "development";
-  }
   listActiveSkills() {
     return [...this.activeSkillNames].sort();
   }
@@ -2088,6 +2135,12 @@ var AgentHarness = class {
   getAgentScriptIntent() {
     return this.parsedAgent?.frontmatter.allowedTools?.scripts ?? [];
   }
+  getAgentMcpApprovalPatterns() {
+    return this.parsedAgent?.frontmatter.approvalRequired?.mcp ?? [];
+  }
+  getAgentScriptApprovalPatterns() {
+    return this.parsedAgent?.frontmatter.approvalRequired?.scripts ?? [];
+  }
   getRequestedMcpPatterns() {
     const skillPatterns = /* @__PURE__ */ new Set();
     for (const skillName of this.activeSkillNames) {
@@ -2105,34 +2158,96 @@ var AgentHarness = class {
     return this.getAgentMcpIntent();
   }
   getRequestedScriptPatterns() {
-    const skillPatterns = /* @__PURE__ */ new Set();
+    const patterns = new Set(this.getAgentScriptIntent());
     for (const skillName of this.activeSkillNames) {
       const skill = this.loadedSkills.find((entry) => entry.name === skillName);
       if (!skill) {
         continue;
       }
       for (const pattern of skill.allowedTools.scripts) {
+        patterns.add(pattern);
+      }
+    }
+    return [...patterns];
+  }
+  getRequestedMcpApprovalPatterns() {
+    const skillPatterns = /* @__PURE__ */ new Set();
+    for (const skillName of this.activeSkillNames) {
+      const skill = this.loadedSkills.find((entry) => entry.name === skillName);
+      if (!skill) {
+        continue;
+      }
+      for (const pattern of skill.approvalRequired.mcp) {
         skillPatterns.add(pattern);
       }
     }
     if (skillPatterns.size > 0) {
       return [...skillPatterns];
     }
-    return this.getAgentScriptIntent();
+    return this.getAgentMcpApprovalPatterns();
+  }
+  getRequestedScriptApprovalPatterns() {
+    const patterns = new Set(this.getAgentScriptApprovalPatterns());
+    for (const skillName of this.activeSkillNames) {
+      const skill = this.loadedSkills.find((entry) => entry.name === skillName);
+      if (!skill) {
+        continue;
+      }
+      for (const pattern of skill.approvalRequired.scripts) {
+        patterns.add(pattern);
+      }
+    }
+    return [...patterns];
   }
   isScriptAllowedByPolicy(skill, scriptPath) {
-    const identifier = `${skill}/${scriptPath}`;
-    const intentPatterns = this.getRequestedScriptPatterns();
-    const matchedIntent = intentPatterns.length === 0 ? true : intentPatterns.some((pattern) => matchesSlashPattern(identifier, pattern));
-    if (!matchedIntent) {
-      return false;
+    const normalizedScriptPath = normalizeRelativeScriptPattern(
+      scriptPath,
+      "run_skill_script input.script"
+    );
+    const isSkillRootScript = normalizedScriptPath.startsWith("./") && !normalizedScriptPath.slice(2).includes("/");
+    if (isSiblingScriptsPattern(normalizedScriptPath) || isSkillRootScript) {
+      return true;
+    }
+    const skillPatterns = this.loadedSkills.find((entry) => entry.name === skill)?.allowedTools.scripts ?? [];
+    const intentPatterns = /* @__PURE__ */ new Set([
+      ...this.getAgentScriptIntent(),
+      ...skillPatterns,
+      ...this.getRequestedScriptPatterns()
+    ]);
+    return [...intentPatterns].some(
+      (pattern) => matchesRelativeScriptPattern(normalizedScriptPath, pattern)
+    );
+  }
+  isRootScriptAllowedByPolicy(scriptPath) {
+    const normalizedScriptPath = normalizeRelativeScriptPattern(
+      scriptPath,
+      "run_skill_script input.script"
+    );
+    if (isSiblingScriptsPattern(normalizedScriptPath)) {
+      return true;
     }
-    const policy = mergePolicyForEnvironment(
-      this.loadedConfig?.scripts,
-      this.runtimeEnvironment()
+    const patterns = this.getAgentScriptIntent();
+    return patterns.some(
+      (pattern) => matchesRelativeScriptPattern(normalizedScriptPath, pattern)
     );
-    const decision = applyToolPolicy([identifier], policy);
-    return decision.allowed.length > 0;
+  }
+  requiresApprovalForToolCall(toolName, input) {
+    if (toolName === "run_skill_script") {
+      const rawScript = typeof input.script === "string" ? input.script.trim() : "";
+      if (!rawScript) {
+        return false;
+      }
+      const canonicalPath = normalizeRelativeScriptPattern(
+        `./${normalizeScriptPolicyPath(rawScript)}`,
+        "run_skill_script input.script"
+      );
+      const scriptPatterns = this.getRequestedScriptApprovalPatterns();
+      return scriptPatterns.some(
+        (pattern) => matchesRelativeScriptPattern(canonicalPath, pattern)
+      );
+    }
+    const mcpPatterns = this.getRequestedMcpApprovalPatterns();
+    return mcpPatterns.some((pattern) => matchesSlashPattern(toolName, pattern));
   }
   async refreshMcpTools(reason) {
     if (!this.mcpBridge) {
@@ -2147,10 +2262,7 @@ var AgentHarness = class {
       );
       return;
     }
-    const tools = await this.mcpBridge.loadTools(
-      requestedPatterns,
-      this.runtimeEnvironment()
-    );
+    const tools = await this.mcpBridge.loadTools(requestedPatterns);
     this.dispatcher.registerMany(tools);
     for (const tool of tools) {
       this.registeredMcpToolNames.add(tool.name);
@@ -2165,43 +2277,9 @@ var AgentHarness = class {
       })}`
     );
   }
-  validateScriptPolicyConfig(config) {
-    const check = (values, path) => {
-      for (const [index, value] of (values ?? []).entries()) {
-        validateScriptPattern(value, `${path}[${index}]`);
-      }
-    };
-    check(config?.scripts?.include, "poncho.config.js scripts.include");
-    check(config?.scripts?.exclude, "poncho.config.js scripts.exclude");
-    check(
-      config?.scripts?.byEnvironment?.development?.include,
-      "poncho.config.js scripts.byEnvironment.development.include"
-    );
-    check(
-      config?.scripts?.byEnvironment?.development?.exclude,
-      "poncho.config.js scripts.byEnvironment.development.exclude"
-    );
-    check(
-      config?.scripts?.byEnvironment?.staging?.include,
-      "poncho.config.js scripts.byEnvironment.staging.include"
-    );
-    check(
-      config?.scripts?.byEnvironment?.staging?.exclude,
-      "poncho.config.js scripts.byEnvironment.staging.exclude"
-    );
-    check(
-      config?.scripts?.byEnvironment?.production?.include,
-      "poncho.config.js scripts.byEnvironment.production.include"
-    );
-    check(
-      config?.scripts?.byEnvironment?.production?.exclude,
-      "poncho.config.js scripts.byEnvironment.production.exclude"
-    );
-  }
   async initialize() {
     this.parsedAgent = await parseAgentFile(this.workingDir);
     const config = await loadPonchoConfig(this.workingDir);
-    this.validateScriptPolicyConfig(config);
     this.loadedConfig = config;
     this.registerConfiguredBuiltInTools(config);
     const provider = this.parsedAgent.frontmatter.model?.provider ?? "anthropic";
@@ -2228,7 +2306,9 @@ var AgentHarness = class {
           return this.listActiveSkills();
         },
         onListActiveSkills: () => this.listActiveSkills(),
-        isScriptAllowed: (skill, scriptPath) => this.isScriptAllowedByPolicy(skill, scriptPath)
+        isScriptAllowed: (skill, scriptPath) => this.isScriptAllowedByPolicy(skill, scriptPath),
+        isRootScriptAllowed: (scriptPath) => this.isRootScriptAllowedByPolicy(scriptPath),
+        workingDir: this.workingDir
       })
     );
     if (memoryConfig?.enabled) {
@@ -2454,7 +2534,7 @@ ${boundedMainMemory.trim()}` : "";
         });
         const modelName = agent.frontmatter.model?.name ?? "claude-opus-4-5";
         const temperature = agent.frontmatter.model?.temperature ?? 0.2;
-        const maxTokens = agent.frontmatter.model?.maxTokens ?? 1024;
+        const maxTokens = agent.frontmatter.model?.maxTokens;
         const telemetryEnabled = this.loadedConfig?.telemetry?.enabled !== false;
         const latitudeApiKey = this.loadedConfig?.telemetry?.latitude?.apiKey;
         const result = await streamText({
@@ -2463,7 +2543,7 @@ ${boundedMainMemory.trim()}` : "";
           messages: coreMessages,
           tools,
           temperature,
-          maxTokens,
+          ...typeof maxTokens === "number" ? { maxTokens } : {},
           experimental_telemetry: {
             isEnabled: telemetryEnabled && !!latitudeApiKey
           }
@@ -2526,8 +2606,11 @@ ${boundedMainMemory.trim()}` : "";
         for (const call of toolCalls) {
           const runtimeToolName = exposedToolNames.get(call.name) ?? call.name;
           yield pushEvent({ type: "tool:started", tool: runtimeToolName, input: call.input });
-          const definition = this.dispatcher.get(runtimeToolName);
-          if (definition?.requiresApproval) {
+          const requiresApproval = this.requiresApprovalForToolCall(
+            runtimeToolName,
+            call.input
+          );
+          if (requiresApproval) {
             const approvalId = `approval_${randomUUID2()}`;
             yield pushEvent({
               type: "tool:approval:required",
@@ -3597,6 +3680,7 @@ export {
   loadSkillContext,
   loadSkillInstructions,
   loadSkillMetadata,
+  normalizeScriptPolicyPath,
   parseAgentFile,
   parseAgentMarkdown,
   readSkillResource,