Add path-based permissions for agents

Author: justyns

assets/tool-approval-modal.html

@@ -285,4 +285,4 @@ <h4>Arguments</h4>
       Approve <span class="keyboard-hint">(Enter)</span>
     </button>
   </div>
-</div>
+</div>

docs/Agents.md

@@ -107,6 +107,28 @@ aiagent:
 
 This agent restricts tools to only the built-in read-only tools, preventing any page modifications.
 
+### Sandboxed Agent with Path Restrictions
+
+An agent that can only operate on pages within a specific folder:
+
+```yaml
+---
+tags: meta/template/aiAgent
+aiagent:
+  name: "Sandbox Agent"
+  description: "Can only access pages under Sandbox/"
+  systemPrompt: |
+    You help the user with notes in the Sandbox folder.
+    You cannot access or modify pages outside this area.
+  allowedReadPaths: ["Sandbox/"]
+  allowedWritePaths: ["Sandbox/"]
+---
+```
+
+This agent can read and write pages under `Sandbox/` but will get an error if it tries to access other pages via tools that support path permissions.
+
+> **Note:** Path permissions only apply to tools that declare `readPathParam` or `writePathParam`. Tools like `eval_lua` can bypass these restrictions. For a true sandbox, combine path permissions with a tool whitelist.
+
 ### Writing Assistant with Context
 
 An agent with additional context embedded from wiki-links:
@@ -186,6 +208,8 @@ aiagent:
 | `tools` | string[] | Whitelist - only these tools are available |
 | `toolsExclude` | string[] | Blacklist - these tools are removed |
 | `inheritBasePrompt` | boolean | Prepend base system prompt (default: true) |
+| `allowedReadPaths` | string[] | Path prefixes tools can read from (e.g., `["Journal/", "Notes/"]`) |
+| `allowedWritePaths` | string[] | Path prefixes tools can write to (e.g., `["Journal/"]`) |
 
 ### Base Prompt Inheritance
 
@@ -199,6 +223,38 @@ By default, agents inherit the base system prompt which includes SilverBullet ma
 
 **Tip:** Use `tools` (whitelist) for restrictive agents that should only have specific capabilities. Use `toolsExclude` (blacklist) when you want most tools but need to block a few dangerous ones like `eval_lua`.
 
+### Path Permissions
+
+Restrict which pages an agent can read from or write to using path prefixes:
+
+```yaml
+---
+tags: meta/template/aiAgent
+aiagent:
+  name: "Journal Assistant"
+  description: "Helps with journal entries only"
+  allowedReadPaths: ["Journal/", "Daily/"]
+  allowedWritePaths: ["Journal/"]
+---
+```
+
+Or in Lua:
+
+```lua
+ai.agents.journal = {
+  name = "Journal Assistant",
+  allowedReadPaths = {"Journal/", "Daily/"},
+  allowedWritePaths = {"Journal/"}
+}
+```
+
+**How it works:**
+- If `allowedReadPaths` is set, tools with `readPathParam` can only read pages starting with those prefixes
+- If `allowedWritePaths` is set, tools with `writePathParam` can only write to pages starting with those prefixes
+- If not set, no path restrictions apply
+
+This is useful for creating restricted agents that can only operate on specific areas of your space.
+
 ## Usage
 
 1. **Select Agent**: Run `AI: Select Agent` command

docs/Changelog.md

@@ -7,6 +7,7 @@ This page is a brief overview of each version.
 - Embeddings now include page title and section headers
 - Benchmark command now shows progress
 - Reuse SB's theming where possible so that the UI is more consistent
+- Add path-based permissions for agents (`allowedReadPaths`, `allowedWritePaths`) to restrict tool access to specific folders
 
 ## 0.6.2 (2025-01-05)
 

docs/Tools.md

@@ -85,6 +85,8 @@ Each tool needs:
 - `parameters` - JSON Schema defining input parameters
 - `handler` - Function that receives `args` and returns a string result
 - `requiresApproval` - (optional) If `true`, user must confirm before the tool executes
+- `readPathParam` - (optional) Parameter name(s) containing page paths for read operations. Can be a string or array of strings. (used with agent path permissions)
+- `writePathParam` - (optional) Parameter name(s) containing page paths for write operations. Can be a string or array of strings. (used with agent path permissions)
 
 ## Requiring Approval
 
@@ -137,4 +139,53 @@ The `ai.writePage` function:
 
 All built-in editing tools (`update_note`, `update_frontmatter`, `create_note`, etc.) use `ai.writePage` internally to provide diff previews.
 
-There's nothing stopping you from bypassing this, so please be careful when making custom tools.
+There's nothing stopping you from bypassing this, so please be careful when making custom tools.
+
+## Path Permissions
+
+Tools can declare which parameter contains a page path for permission validation. When an agent has `allowedReadPaths` or `allowedWritePaths` configured, tools will be blocked from accessing pages outside those paths.
+
+### Declaring Path Parameters
+
+```lua
+ai.tools.my_reader = {
+  description = "Read data from a page",
+  readPathParam = "page",  -- This param will be validated against allowedReadPaths
+  parameters = {
+    type = "object",
+    properties = {
+      page = {type = "string", description = "The page to read"}
+    },
+    required = {"page"}
+  },
+  handler = function(args)
+    return space.readPage(args.page)
+  end
+}
+
+ai.tools.my_writer = {
+  description = "Write data to a page",
+  writePathParam = "page",  -- This param will be validated against allowedWritePaths
+  requiresApproval = true,
+  parameters = {
+    type = "object",
+    properties = {
+      page = {type = "string", description = "The page to write"}
+    },
+    required = {"page"}
+  },
+  handler = function(args)
+    ai.writePage(args.page, "content")
+    return "Written"
+  end
+}
+```
+
+### How It Works
+
+1. Agent defines `allowedReadPaths` and/or `allowedWritePaths` (see [[Agents]])
+2. When a tool is called, the validation checks if the path parameter starts with any allowed prefix
+3. If the path is not allowed, the tool returns an error instead of executing
+4. Write operations require **both** read and write access (since tools typically read content before modifying it)
+
+All built-in tools declare their path parameters, so they work with agent path permissions automatically.

silverbullet-ai/Space Lua/AI Tools.md

@@ -88,6 +88,7 @@ end
 
 ai.tools.read_note = {
   description = "Read the content of a note. Optionally read only a specific section.",
+  readPathParam = "page",
   parameters = {
     type = "object",
     properties = {
@@ -152,6 +153,7 @@ ai.tools.read_note = {
 
 ai.tools.list_pages = {
   description = "List pages in the space. Pages ending with / have subpages (e.g., 'Projects/' has children).",
+  readPathParam = "path",
   parameters = {
     type = "object",
     properties = {
@@ -232,6 +234,7 @@ ai.tools.list_pages = {
 
 ai.tools.get_page_info = {
   description = "Get metadata about a page including tags, last modified date, size, and subpage count",
+  readPathParam = "page",
   parameters = {
     type = "object",
     properties = {
@@ -271,6 +274,7 @@ ai.tools.get_page_info = {
 
 ai.tools.update_note = {
   description = "Update a note's content. Can update the whole page, a specific section, or append/prepend to a section.",
+  writePathParam = "page",
   parameters = {
     type = "object",
     properties = {
@@ -353,6 +357,7 @@ ai.tools.update_note = {
 
 ai.tools.search_replace = {
   description = "Find and replace text in a note. Use for targeted edits when you know the exact text to change.",
+  writePathParam = "page",
   parameters = {
     type = "object",
     properties = {
@@ -451,6 +456,7 @@ ai.tools.search_replace = {
 
 ai.tools.create_note = {
   description = "Create a new note. Fails if the page already exists.",
+  writePathParam = "page",
   parameters = {
     type = "object",
     properties = {
@@ -470,6 +476,7 @@ ai.tools.create_note = {
 
 ai.tools.navigate = {
   description = "Navigate to a page or position. Use to open pages for the user or jump to specific locations.",
+  readPathParam = "ref",
   parameters = {
     type = "object",
     properties = {
@@ -512,6 +519,7 @@ ai.tools.eval_lua = {
 ai.tools.update_frontmatter = {
   description = "Update frontmatter (YAML metadata) on a page. Can set or delete individual keys without affecting the rest of the page content.",
   requiresApproval = true,
+  writePathParam = "page",
   parameters = {
     type = "object",
     properties = {
@@ -576,6 +584,7 @@ ai.tools.update_frontmatter = {
 ai.tools.rename_note = {
   description = "Rename a page to a new name. This also updates all backlinks across the space to point to the new name.",
   requiresApproval = true,
+  writePathParam = {"oldPage", "newPage"},
   parameters = {
     type = "object",
     properties = {

src/agents.ts

@@ -22,6 +22,8 @@ export async function discoverAgents(): Promise<AIAgentTemplate[]> {
         tools?: string[];
         toolsExclude?: string[];
         inheritBasePrompt?: boolean;
+        allowedReadPaths?: string[];
+        allowedWritePaths?: string[];
       }
     >;
 
@@ -36,6 +38,8 @@ export async function discoverAgents(): Promise<AIAgentTemplate[]> {
             tools: agent.tools,
             toolsExclude: agent.toolsExclude,
             inheritBasePrompt: agent.inheritBasePrompt,
+            allowedReadPaths: agent.allowedReadPaths,
+            allowedWritePaths: agent.allowedWritePaths,
           },
         });
       }

src/benchmark.ts

@@ -3,7 +3,7 @@ import { aiSettings, configureSelectedModel, initializeOpenAI, parseDefaultModel
 import { getAllAvailableModels } from "./model-discovery.ts";
 import { convertToOpenAITools, discoverTools, runAgenticChat } from "./tools.ts";
 import type { ToolExecutionResult } from "./tools.ts";
-import type { ModelConfig, Tool } from "./types.ts";
+import type { ModelConfig, PathPermissions, Tool } from "./types.ts";
 import type { ProviderInterface } from "./interfaces/Provider.ts";
 import { showProgressModal } from "./utils.ts";
 
@@ -19,6 +19,10 @@ const BENCHMARK_ALLOWED_TOOLS = [
   "search_replace",
   "create_note",
 ];
+const BENCHMARK_PERMISSIONS: PathPermissions = {
+  allowedReadPaths: [`${BENCHMARK_PAGE}/`],
+  allowedWritePaths: [`${BENCHMARK_PAGE}/`],
+};
 
 function withTimeout<T>(promise: Promise<T>, ms: number, operation: string): Promise<T> {
   return new Promise((resolve, reject) => {
@@ -389,6 +393,7 @@ async function runExecutionTest(
     onToolCall: (name, args, execResult) => {
       toolCalls.push({ name, args, result: execResult });
     },
+    permissions: BENCHMARK_PERMISSIONS,
   });
 
   const passed = await test.verify(toolCalls, result.finalResponse);

src/chat-panel.ts

@@ -298,6 +298,12 @@ async function runToolLoop(
     onToolCall: (_toolName, _args, _result) => {
       // Tool calls are already formatted in toolCallsText and used below
     },
+    permissions: currentChatAgent?.aiagent
+      ? {
+        allowedReadPaths: currentChatAgent.aiagent.allowedReadPaths,
+        allowedWritePaths: currentChatAgent.aiagent.allowedWritePaths,
+      }
+      : undefined,
   });
 
   // Update usage to reflect current context size (not cumulative)