open-agents-ai 0.187.489 → 0.187.491

package/dist/index.js

@@ -1199,6 +1199,219 @@ var init_tool_executor = __esm({
   }
 });
 
+// packages/execution/dist/tools/security-classifier.js
+function classifyTool(name10) {
+  for (const rule of RULES) {
+    const hit = typeof rule.match === "function" ? rule.match(name10) : rule.match.test(name10);
+    if (hit)
+      return applyOverrides(name10, rule.info);
+  }
+  return applyOverrides(name10, UNKNOWN_DEFAULT);
+}
+function applyOverrides(name10, base3) {
+  const raw = process.env["OA_TOOL_OVERRIDES"];
+  if (!raw)
+    return base3;
+  try {
+    const overrides = JSON.parse(raw);
+    const o2 = overrides[name10];
+    if (!o2)
+      return base3;
+    return { ...base3, ...o2 };
+  } catch {
+    return base3;
+  }
+}
+function canInvokeTool(args) {
+  const info = classifyTool(args.toolName);
+  const order = ["read", "run", "admin"];
+  if (order.indexOf(args.scope) < order.indexOf(info.requires_scope)) {
+    return {
+      status: 403,
+      reason: `Tool '${args.toolName}' requires '${info.requires_scope}' scope; caller has '${args.scope}'.`
+    };
+  }
+  if (args.origin === "remote" && !info.off_device_allowed && args.scope !== "admin") {
+    return {
+      status: 403,
+      reason: `Tool '${args.toolName}' is loopback-only (off_device_allowed=false). Remote callers must have 'admin' scope.`
+    };
+  }
+  return null;
+}
+var CRITICAL_SENSITIVE, HARDWARE_DEVICE, AGENT_SPAWN, SHELL_EXEC, SANDBOXED_EXEC, NETWORK_OUTBOUND, NETWORK_BROWSER, LOCAL_WRITE, LOCAL_READ, NETWORK_READ, MEMORY_READ, MEMORY_WRITE, TASK_CONTROL, SCHEDULER_REMINDER, TASK_COMPLETE_NEUTRAL, RULES, UNKNOWN_DEFAULT;
+var init_security_classifier = __esm({
+  "packages/execution/dist/tools/security-classifier.js"() {
+    "use strict";
+    CRITICAL_SENSITIVE = {
+      categories: ["sensitive"],
+      risk: "critical",
+      requires_scope: "admin",
+      off_device_allowed: false,
+      rationale: "Modifies tool registry, identity, or sponsorship — admin only, loopback only."
+    };
+    HARDWARE_DEVICE = {
+      categories: ["hardware"],
+      risk: "high",
+      requires_scope: "admin",
+      off_device_allowed: false,
+      rationale: "Hardware peripheral access (camera/mic/wifi/BT/SDR/desktop). Loopback-only by default."
+    };
+    AGENT_SPAWN = {
+      categories: ["agent"],
+      risk: "high",
+      requires_scope: "admin",
+      off_device_allowed: false,
+      rationale: "Spawns sub-agents or sends inter-agent messages. Multiplies blast radius."
+    };
+    SHELL_EXEC = {
+      categories: ["exec"],
+      risk: "critical",
+      requires_scope: "run",
+      off_device_allowed: false,
+      rationale: "Executes arbitrary shell commands. Loopback-only — remote callers need admin scope."
+    };
+    SANDBOXED_EXEC = {
+      categories: ["exec"],
+      risk: "high",
+      requires_scope: "run",
+      off_device_allowed: true,
+      rationale: "Sandboxed code execution — bounded blast radius, OK for off-device with auth."
+    };
+    NETWORK_OUTBOUND = {
+      categories: ["network"],
+      risk: "medium",
+      requires_scope: "run",
+      off_device_allowed: true,
+      rationale: "Outbound network call. Off-device callers may invoke with run scope."
+    };
+    NETWORK_BROWSER = {
+      categories: ["network", "exec"],
+      risk: "high",
+      requires_scope: "run",
+      off_device_allowed: false,
+      rationale: "Headless browser — broad network + cookie / session access. Loopback-only."
+    };
+    LOCAL_WRITE = {
+      categories: ["write"],
+      risk: "medium",
+      requires_scope: "run",
+      off_device_allowed: true,
+      rationale: "Local filesystem mutation. Run scope required."
+    };
+    LOCAL_READ = {
+      categories: ["read"],
+      risk: "low",
+      requires_scope: "read",
+      off_device_allowed: true,
+      rationale: "Read-only inspection of local state."
+    };
+    NETWORK_READ = {
+      categories: ["read", "network"],
+      risk: "low",
+      requires_scope: "read",
+      off_device_allowed: true,
+      rationale: "Network read (search/fetch). Safe to expose."
+    };
+    MEMORY_READ = {
+      categories: ["read"],
+      risk: "low",
+      requires_scope: "read",
+      off_device_allowed: true,
+      rationale: "Reads associative memory (no mutation)."
+    };
+    MEMORY_WRITE = {
+      categories: ["write"],
+      risk: "medium",
+      requires_scope: "run",
+      off_device_allowed: true,
+      rationale: "Mutates associative memory store."
+    };
+    TASK_CONTROL = {
+      categories: ["exec"],
+      risk: "medium",
+      requires_scope: "run",
+      off_device_allowed: true,
+      rationale: "Controls background task lifecycle (start/stop/inspect)."
+    };
+    SCHEDULER_REMINDER = {
+      categories: ["write"],
+      risk: "medium",
+      requires_scope: "run",
+      off_device_allowed: true,
+      rationale: "Schedules deferred actions or reminders."
+    };
+    TASK_COMPLETE_NEUTRAL = {
+      categories: ["read"],
+      risk: "low",
+      requires_scope: "read",
+      off_device_allowed: true,
+      rationale: "Signals task completion. No side effects."
+    };
+    RULES = [
+      // ── Critical sensitive: tool registry / identity / worktree / sponsorship
+      { match: /^(create_tool|manage_tools|skill_build|tool_creator)$/, info: CRITICAL_SENSITIVE },
+      { match: /^(identity_kernel|reflection_integrity|cohere_constraints)$/, info: CRITICAL_SENSITIVE },
+      { match: /^(enter_worktree|exit_worktree)$/, info: CRITICAL_SENSITIVE },
+      { match: /^(aiwg_setup|aiwg_health|aiwg_workflow)$/, info: CRITICAL_SENSITIVE },
+      { match: /^(expose|sponsor|nexus_register)/, info: CRITICAL_SENSITIVE },
+      // ── Hardware peripherals
+      { match: /^(camera_capture|audio_capture|audio_playback|audio_analyze|asr_listen)$/, info: HARDWARE_DEVICE },
+      { match: /^(wifi_control|bluetooth_scan|sdr_scan|flipper_zero|meshtastic|gps_location)$/, info: HARDWARE_DEVICE },
+      { match: /^(desktop_click|desktop_describe|screenshot)$/, info: HARDWARE_DEVICE },
+      { match: /^(jibberlink)$/, info: HARDWARE_DEVICE },
+      // audio modem
+      // ── Agent spawning + inter-agent messaging + P2P
+      { match: /^(full_sub_agent|sub_agent|agent|send_message)$/, info: AGENT_SPAWN },
+      { match: /^(factory|opencode|cron_agent|autoresearch)$/, info: AGENT_SPAWN },
+      { match: /^nexus$/, info: AGENT_SPAWN },
+      // P2P invocation
+      { match: /^debate$/, info: AGENT_SPAWN },
+      // multi-agent debate
+      { match: /^replay_with_intervention$/, info: AGENT_SPAWN },
+      // ── Shell + REPL (high risk exec, loopback only)
+      { match: /^shell$/, info: SHELL_EXEC },
+      { match: /^(repl|repl_exec|background_run)$/, info: SHELL_EXEC },
+      // ── Sandboxed exec (OK for remote with auth)
+      { match: /^(code_sandbox|cohere_sandbox)$/, info: SANDBOXED_EXEC },
+      // ── Browser automation
+      { match: /^(browser_action|playwright_browser|web_crawl)$/, info: NETWORK_BROWSER },
+      // ── Network reads (safe)
+      { match: /^(web_search|web_fetch)$/, info: NETWORK_READ },
+      // ── Network outbound (mutating or remote inference)
+      { match: /^(image_generate|vision|video_understand)$/, info: NETWORK_OUTBOUND },
+      { match: /^(transcribe_file|transcribe_url|youtube_download)$/, info: NETWORK_OUTBOUND },
+      { match: /^(fortemi_bridge)$/, info: NETWORK_OUTBOUND },
+      // ── Memory tools
+      { match: /^(memory_read|memory_search)$/, info: MEMORY_READ },
+      { match: /^(memory_write|memory_metabolism|multimodal_memory|visual_memory|embedding_store)$/, info: MEMORY_WRITE },
+      // ── Local writes (fs mutation)
+      { match: /^(file_write|file_edit|file_patch|batch_edit|notebook_edit|structured_file|image_resize)$/, info: LOCAL_WRITE },
+      { match: /^(working_notes|todo_write)$/, info: LOCAL_WRITE },
+      { match: /^(scheduler|reminder|agenda)$/, info: SCHEDULER_REMINDER },
+      { match: /^(exploration_culture)$/, info: LOCAL_WRITE },
+      // ── Task control
+      { match: /^(task_status|task_output|task_stop)$/, info: TASK_CONTROL },
+      // ── Local reads (inspection)
+      { match: /^(file_read|file_explore|list_directory|grep_search|glob_find)$/, info: LOCAL_READ },
+      { match: /^(image_read|ocr|ocr_pdf|ocr_image_advanced|pdf_to_text|structured_read)$/, info: LOCAL_READ },
+      { match: /^(symbol_search|impact_analysis|code_neighbors|repo_map|codebase_map|semantic_map|import_graph)$/, info: LOCAL_READ },
+      { match: /^(diagnostic|git_info|environment_snapshot|process_health|todo_read|explore_tools)$/, info: LOCAL_READ },
+      { match: /^(log_explore|log_packet|change_log|phase_recall|code_graph)$/, info: LOCAL_READ },
+      { match: /^skill_(list|execute|read)$/, info: LOCAL_READ },
+      // ── Task completion (neutral signal)
+      { match: /^task_complete$/, info: TASK_COMPLETE_NEUTRAL }
+    ];
+    UNKNOWN_DEFAULT = {
+      categories: ["sensitive"],
+      risk: "high",
+      requires_scope: "admin",
+      off_device_allowed: false,
+      rationale: "Unrecognized tool — defaulting to admin-only, loopback-only. Operators may override via OA_TOOL_OVERRIDES."
+    };
+  }
+});
+
 // packages/execution/dist/process-kill.js
 import { execSync } from "node:child_process";
 function killProcessTree(pid, signal = "SIGKILL") {
@@ -510207,8 +510420,10 @@ __export(dist_exports, {
   buildMcpToolName: () => buildMcpToolName,
   buildSkillsSummary: () => buildSkillsSummary,
   buildSubProcessArgs: () => buildSubProcessArgs,
+  canInvokeTool: () => canInvokeTool,
   checkConstraints: () => checkConstraints,
   checkDesktopDeps: () => checkDesktopDeps,
+  classifyTool: () => classifyTool,
   clearExploreNotes: () => clearExploreNotes,
   clearImportGraphCache: () => clearImportGraphCache,
   clearWorkingNotes: () => clearWorkingNotes,
@@ -510321,6 +510536,7 @@ var init_dist5 = __esm({
   "packages/execution/dist/index.js"() {
     "use strict";
     init_tool_executor();
+    init_security_classifier();
     init_shell();
     init_debate();
     init_replay_with_intervention();
@@ -576578,6 +576794,23 @@ async function tryRouteV1(ctx3) {
   if (pathname === "/v1/tools" && method === "GET") {
     return handleListTools(ctx3);
   }
+  {
+    const m2 = /^\/v1\/tools\/([^/]+)(\/call)?$/.exec(pathname);
+    if (m2) {
+      const toolName = decodeURIComponent(m2[1]);
+      const isCall = !!m2[2];
+      if (isCall && method === "POST") return handleCallTool(ctx3, toolName);
+      if (!isCall && method === "GET") return handleGetTool(ctx3, toolName);
+      sendProblem(ctx3.res, problemDetails({
+        type: P.methodNotAllowed,
+        status: 405,
+        title: `Method ${method} not allowed for ${pathname}`,
+        detail: isCall ? "POST /v1/tools/{name}/call to execute the tool." : "GET /v1/tools/{name} to fetch its schema.",
+        instance: ctx3.requestId
+      }));
+      return true;
+    }
+  }
   if (pathname === "/v1/hooks" && method === "GET") {
     return handleListHooks(ctx3);
   }
@@ -577621,26 +577854,47 @@ async function handleListTools(ctx3) {
       sendJson(res, 200, { data: [], pagination: { limit: 50, offset: 0, total: 0, has_more: false } });
       return true;
     }
+    const classify = mod2.classifyTool;
     const tools = [];
     for (const [key, value2] of Object.entries(mod2)) {
       if (typeof value2 !== "function") continue;
       const proto = value2.prototype;
       if (!proto || typeof proto.execute !== "function") continue;
+      let inst = null;
       try {
-        const inst = new value2();
-        if (typeof inst.name === "string") {
-          tools.push({
-            name: inst.name,
-            class: key,
-            description: inst.description ?? "",
-            parameters: inst.parameters ?? null
-          });
-        }
+        inst = new value2();
       } catch {
+        try {
+          inst = new value2(process.cwd());
+        } catch {
+          inst = null;
+        }
       }
+      if (!inst || typeof inst.name !== "string") continue;
+      const name10 = inst.name;
+      const security = classify ? classify(name10) : null;
+      tools.push({
+        name: name10,
+        class: key,
+        description: inst.description ?? "",
+        parameters: inst.parameters ?? null,
+        security: security ?? void 0,
+        endpoints: {
+          call: `/v1/tools/${encodeURIComponent(name10)}/call`,
+          schema: `/v1/tools/${encodeURIComponent(name10)}`
+        }
+      });
     }
+    tools.sort((a2, b) => a2.name.localeCompare(b.name));
+    const filterCat = url.searchParams.get("category");
+    const filterScope = url.searchParams.get("scope");
+    const filterRisk = url.searchParams.get("risk");
+    let filtered = tools;
+    if (filterCat) filtered = filtered.filter((t2) => t2.security?.categories?.includes(filterCat));
+    if (filterScope) filtered = filtered.filter((t2) => t2.security?.requires_scope === filterScope);
+    if (filterRisk) filtered = filtered.filter((t2) => t2.security?.risk === filterRisk);
     const page2 = parsePagination(url.searchParams);
-    const envelope = paginated(tools, page2);
+    const envelope = paginated(filtered, page2);
     const etag = computeEtag(envelope);
     if (checkNotModified(req2, res, etag)) return true;
     sendJson(res, 200, envelope, { etag, cacheControl: "private, max-age=60" });
@@ -577656,6 +577910,199 @@ async function handleListTools(ctx3) {
     return true;
   }
 }
+async function handleGetTool(ctx3, name10) {
+  const { req: req2, res, requestId } = ctx3;
+  try {
+    const mod2 = await Promise.resolve().then(() => (init_dist5(), dist_exports)).catch(() => null);
+    if (!mod2) {
+      sendProblem(res, problemDetails({
+        type: P.notFound,
+        status: 404,
+        title: "Tool registry unavailable",
+        detail: "@open-agents/execution module failed to load.",
+        instance: requestId
+      }));
+      return true;
+    }
+    const classify = mod2.classifyTool;
+    let found = null;
+    for (const [key, value2] of Object.entries(mod2)) {
+      if (typeof value2 !== "function") continue;
+      const proto = value2.prototype;
+      if (!proto || typeof proto.execute !== "function") continue;
+      let inst2 = null;
+      try {
+        inst2 = new value2();
+      } catch {
+        try {
+          inst2 = new value2(process.cwd());
+        } catch {
+          inst2 = null;
+        }
+      }
+      if (!inst2 || inst2.name !== name10) continue;
+      found = { instance: inst2, className: key };
+      break;
+    }
+    if (!found) {
+      sendProblem(res, problemDetails({
+        type: P.notFound,
+        status: 404,
+        title: `Tool '${name10}' not found`,
+        detail: "No tool with that name is registered in @open-agents/execution.",
+        instance: requestId
+      }));
+      return true;
+    }
+    const inst = found.instance;
+    const security = classify ? classify(name10) : null;
+    const body = {
+      name: name10,
+      class: found.className,
+      description: inst.description ?? "",
+      parameters: inst.parameters ?? null,
+      security: security ?? void 0,
+      endpoints: {
+        call: `/v1/tools/${encodeURIComponent(name10)}/call`,
+        schema: `/v1/tools/${encodeURIComponent(name10)}`
+      }
+    };
+    const etag = computeEtag(body);
+    if (checkNotModified(req2, res, etag)) return true;
+    sendJson(res, 200, body, { etag, cacheControl: "private, max-age=60" });
+    return true;
+  } catch (err) {
+    sendProblem(res, problemDetails({
+      type: P.internalError,
+      status: 500,
+      title: "Tool schema fetch failed",
+      detail: err instanceof Error ? err.message : String(err),
+      instance: requestId
+    }));
+    return true;
+  }
+}
+async function handleCallTool(ctx3, name10) {
+  const { req: req2, res, requestId } = ctx3;
+  try {
+    const mod2 = await Promise.resolve().then(() => (init_dist5(), dist_exports)).catch(() => null);
+    if (!mod2) {
+      sendProblem(res, problemDetails({
+        type: P.notFound,
+        status: 404,
+        title: "Tool registry unavailable",
+        detail: "@open-agents/execution module failed to load.",
+        instance: requestId
+      }));
+      return true;
+    }
+    let ToolClass = null;
+    let className = "";
+    for (const [key, value2] of Object.entries(mod2)) {
+      if (typeof value2 !== "function") continue;
+      const proto = value2.prototype;
+      if (!proto || typeof proto.execute !== "function") continue;
+      let probe = null;
+      try {
+        probe = new value2();
+      } catch {
+        try {
+          probe = new value2(process.cwd());
+        } catch {
+          probe = null;
+        }
+      }
+      if (probe?.name === name10) {
+        ToolClass = value2;
+        className = key;
+        break;
+      }
+    }
+    if (!ToolClass) {
+      sendProblem(res, problemDetails({
+        type: P.notFound,
+        status: 404,
+        title: `Tool '${name10}' not found`,
+        detail: "Use GET /v1/tools to list available tools.",
+        instance: requestId
+      }));
+      return true;
+    }
+    const remoteIp = (req2.socket?.remoteAddress || "").replace(/^::ffff:/, "");
+    const origin = /^(127\.\d+\.\d+\.\d+|::1|localhost)$/.test(remoteIp) ? "loopback" : "remote";
+    const reqAuth = req2;
+    const scope = reqAuth._authScope ?? (origin === "loopback" ? "admin" : "read");
+    const canInvoke = mod2.canInvokeTool;
+    const denial = canInvoke ? canInvoke({ toolName: name10, origin, scope }) : null;
+    if (denial) {
+      sendProblem(res, problemDetails({
+        type: P.forbidden,
+        status: denial.status,
+        title: "Tool invocation denied",
+        detail: denial.reason,
+        instance: requestId
+      }));
+      return true;
+    }
+    const body = await parseJsonBodyStrict(req2).catch(() => null);
+    if (body !== null && typeof body !== "object") {
+      sendProblem(res, problemDetails({
+        type: P.invalidRequest,
+        status: 400,
+        title: "Body must be JSON object",
+        detail: "POST {args: {...}, working_dir?: string}",
+        instance: requestId
+      }));
+      return true;
+    }
+    const args = body?.args ?? {};
+    const workingDir = typeof body?.working_dir === "string" ? body.working_dir : process.cwd();
+    let tool = null;
+    try {
+      tool = new ToolClass(workingDir);
+    } catch {
+      try {
+        tool = new ToolClass();
+      } catch {
+        tool = null;
+      }
+    }
+    if (!tool) {
+      sendProblem(res, problemDetails({
+        type: P.internalError,
+        status: 500,
+        title: "Tool instantiation failed",
+        detail: `Could not construct ${className}. Some tools require additional adapters (debate, replay) — use /v1/run for those.`,
+        instance: requestId
+      }));
+      return true;
+    }
+    const result = await tool.execute(args).catch((e2) => ({
+      success: false,
+      output: "",
+      error: e2 instanceof Error ? e2.message : String(e2),
+      durationMs: 0
+    }));
+    sendJson(res, 200, {
+      tool: name10,
+      class: className,
+      result,
+      security: mod2.classifyTool ? mod2.classifyTool(name10) : void 0,
+      origin,
+      scope
+    });
+    return true;
+  } catch (err) {
+    sendProblem(res, problemDetails({
+      type: P.internalError,
+      status: 500,
+      title: "Tool call failed",
+      detail: err instanceof Error ? err.message : String(err),
+      instance: requestId
+    }));
+    return true;
+  }
+}
 async function handleListHooks(ctx3) {
   const { res } = ctx3;
   sendJson(res, 200, {
@@ -578303,7 +578750,8 @@ var init_routes_v1 = __esm({
       internalError: `${PROBLEM_BASE}/internal-error`,
       payloadTooLarge: `${PROBLEM_BASE}/payload-too-large`,
       notImplemented: `${PROBLEM_BASE}/not-implemented`,
-      aimsViolation: `${PROBLEM_BASE}/aims-violation`
+      aimsViolation: `${PROBLEM_BASE}/aims-violation`,
+      methodNotAllowed: `${PROBLEM_BASE}/method-not-allowed`
     };
     mcpManagerCache = /* @__PURE__ */ new Map();
     memoryStoresCache = null;
@@ -585527,7 +585975,39 @@ function getOpenApiSpec() {
       "/v1/evaluate": { post: { summary: "Evaluate a run by ID", tags: ["Agentic"], responses: { 200: { description: "Evaluation metrics" }, 404: { description: "Run not found" } } } },
       "/v1/index": { post: { summary: "Trigger repository indexing", tags: ["Agentic"], responses: { 202: { description: "Indexing started" } } } },
       // ───── P2: Tools / Hooks / Agents / Engines ─────
-      "/v1/tools": { get: { summary: "List agentic tool registry", tags: ["Tools"], responses: { 200: { description: "Paginated tools" } } } },
+      "/v1/tools": {
+        get: {
+          summary: "List agentic tool registry with security metadata",
+          tags: ["Tools"],
+          description: "Returns each tool's name, class, description, JSON-schema parameters, security policy {categories, risk, requires_scope, off_device_allowed, rationale}, and per-tool endpoint hrefs. Filters: ?category=read|write|exec|network|hardware|agent|sensitive · ?scope=read|run|admin · ?risk=low|medium|high|critical. Pagination via ?limit=N&offset=N (default limit=50; pass limit=200 to see all).",
+          responses: { 200: { description: "Paginated tools with security metadata" } }
+        }
+      },
+      "/v1/tools/{name}": {
+        get: {
+          summary: "Single tool schema + security policy",
+          tags: ["Tools"],
+          parameters: [{ name: "name", in: "path", required: true, schema: { type: "string" }, description: "Tool name (snake_case, e.g. file_read)" }],
+          responses: {
+            200: { description: "Tool entry with security info" },
+            404: { description: "Unknown tool name" }
+          }
+        }
+      },
+      "/v1/tools/{name}/call": {
+        post: {
+          summary: "Execute a single tool directly (MCP-style, no agent loop)",
+          tags: ["Tools"],
+          description: "Body: {args: object, working_dir?: string}. Returns the tool's ToolResult {success, output, llmContent?, error?, durationMs} plus security metadata. Auth gating: request scope (read/run/admin) must satisfy tool.requires_scope; non-loopback callers need admin scope unless tool.off_device_allowed=true. Anonymous loopback callers default to admin scope; anonymous remote callers default to read scope.",
+          parameters: [{ name: "name", in: "path", required: true, schema: { type: "string" } }],
+          responses: {
+            200: { description: "Tool result envelope" },
+            403: { description: "Forbidden — scope insufficient or off-device gate" },
+            404: { description: "Unknown tool" },
+            500: { description: "Tool execution failed" }
+          }
+        }
+      },
       "/v1/hooks": { get: { summary: "List hook types and counts", tags: ["Tools"], responses: { 200: { description: "Hook registry" } } } },
       "/v1/agents": { get: { summary: "List agent types", tags: ["Tools"], responses: { 200: { description: "Agent type registry" } } } },
       "/v1/engines": { get: { summary: "List long-running engines", tags: ["Engines"], responses: { 200: { description: "Engine status + state files" } } } },
@@ -587573,13 +588053,25 @@ function handleHelp(req2, res) {
         "DELETE /v1/runs/:id": "Cancel a running task"
       },
       tools_and_skills: {
-        "GET /v1/tools": "List available agentic tools",
+        "GET /v1/tools": "List agentic tools w/ security metadata. Filters: ?category=read|write|exec|network|hardware|agent|sensitive ?scope=read|run|admin ?risk=low|medium|high|critical ?limit=N&offset=N",
+        "GET /v1/tools/:name": "Get a single tool's schema + security policy (categories, risk, requires_scope, off_device_allowed)",
+        "POST /v1/tools/:name/call": "Execute a single tool directly (MCP-style). Body: {args: object, working_dir?: string}. Auth-gated by per-tool scope; off-device callers need admin scope unless tool.off_device_allowed=true",
         "GET /v1/skills": "List available skills (slash commands)",
         "GET /v1/skills/:name": "Get skill details and content",
         "GET /v1/commands": "List slash commands",
         "POST /v1/commands/:cmd": "Execute a slash command",
         "GET /v1/agents": "List available agent types"
       },
+      tool_security_model: {
+        scopes: {
+          read: "Pure inspection (file_read, web_search, list_directory, memory_read, ...)",
+          run: "Local mutations + network outbound (file_write, shell, web_fetch, image_generate, ...)",
+          admin: "Hardware peripherals, agent spawning, identity, tool registry mutations"
+        },
+        off_device_policy: "Tools with off_device_allowed=false are loopback-only; remote callers need admin scope to bypass.",
+        anonymous_default: "Loopback callers default to admin scope. Remote callers default to read scope until authenticated.",
+        override: "Operators can override per-tool classification via OA_TOOL_OVERRIDES env var (JSON map of name → partial security info)."
+      },
       mcp: {
         "GET /v1/mcps": "List connected MCP (Model Context Protocol) servers",
         "GET /v1/mcps/:name": "Get MCP server details and available tools",
@@ -589567,7 +590059,9 @@ async function handleRequest(req2, res, ollamaUrl, verbose) {
           agentic: {
             run: { href: `${baseUrl}/v1/run`, description: "Submit autonomous task." },
             runs: { href: `${baseUrl}/v1/runs`, description: "List runs." },
-            tools: { href: `${baseUrl}/v1/tools`, description: "Agentic tool registry." },
+            tools: { href: `${baseUrl}/v1/tools`, description: "Agentic tool registry with security metadata. Filters: ?category=, ?scope=, ?risk=." },
+            tool_schema: { href: `${baseUrl}/v1/tools/{name}`, description: "Single-tool schema + security policy." },
+            tool_call: { href: `${baseUrl}/v1/tools/{name}/call`, description: "Execute a single tool directly (MCP-style). POST {args: object, working_dir?: string}. Auth-gated per-tool." },
             mcps: { href: `${baseUrl}/v1/mcps`, description: "MCP server registry." }
           },
           memory: {

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "open-agents-ai",
-  "version": "0.187.489",
+  "version": "0.187.491",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "open-agents-ai",
-      "version": "0.187.489",
+      "version": "0.187.491",
       "hasInstallScript": true,
       "license": "CC-BY-NC-4.0",
       "dependencies": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "open-agents-ai",
-  "version": "0.187.489",
+  "version": "0.187.491",
   "description": "AI coding agent powered by open-source models (Ollama/vLLM) — interactive TUI with agentic tool-calling loop",
   "type": "module",
   "main": "./dist/index.js",