wip: permissions

packages/web/src/content/docs/docs/config.mdx

@@ -15,7 +15,7 @@ opencode supports both JSON and JSONC (JSON with Comments) formats. You can use
   // Theme configuration
   "theme": "opencode",
   "model": "anthropic/claude-sonnet-4-20250514",
-  "autoupdate": true
+  "autoupdate": true,
 }
 ```
 
@@ -215,10 +215,10 @@ You can configure specialized agents for specific tasks through the `agent` opti
       "tools": {
         // Disable file modification tools for review-only agent
         "write": false,
-        "edit": false
-      }
-    }
-  }
+        "edit": false,
+      },
+    },
+  },
 }
 ```
 
@@ -245,6 +245,29 @@ The `disabled_providers` option accepts an array of provider IDs. When a provide
 
 ---
 
+### Permissions
+
+You can configure permissions to control what AI agents can do in your codebase through the `permission` option.
+
+```json title="opencode.json"
+{
+  "$schema": "https://opencode.ai/config.json",
+  "permission": {
+    "edit": "ask",
+    "bash": "ask"
+  }
+}
+```
+
+The permissions system allows you to configure explicit approval requirements for sensitive operations:
+
+- `edit` - Controls whether file editing operations require user approval (`"ask"` or `"allow"`)
+- `bash` - Controls whether bash commands require user approval (can be `"ask"`/`"allow"` or a pattern map)
+
+[Learn more about permissions here](/docs/permissions).
+
+---
+
 ## Variables
 
 You can use variable substitution in your config files to reference environment variables and file contents.

packages/web/src/content/docs/docs/permissions.mdx

@@ -0,0 +1,144 @@
+---
+title: Permissions
+description: Control what AI agents can do in your codebase.
+---
+
+The opencode permissions system provides granular control over what actions AI agents can perform in your codebase. It allows you to configure explicit approval requirements for sensitive operations like file editing, bash commands, and more.
+
+## How it works
+
+The permissions system works by intercepting tool calls and checking if user approval is required before executing potentially sensitive operations. When a tool requests permission, it creates a permission request that must be approved by the user.
+
+```typescript
+// Example of how a tool requests permission
+await Permission.ask({
+  type: "edit",
+  sessionID: ctx.sessionID,
+  messageID: ctx.messageID,
+  callID: ctx.callID,
+  title: "Edit this file: " + filePath,
+  metadata: {
+    filePath,
+    diff,
+  },
+})
+```
+
+When a permission is requested, the system checks the configuration to determine if approval is needed. If approval is required, the user is prompted to allow or deny the action.
+
+## Configuration
+
+Permissions are configured in your `opencode.json` file under the `permission` key. Here are the available options:
+
+### permission.edit
+
+Controls whether file editing operations require user approval.
+
+```json title="opencode.json"
+{
+  "permission": {
+    "edit": "ask"
+  }
+}
+```
+
+- `"ask"` - Prompt user for approval before editing files
+- `"allow"` - Allow all file editing operations without approval
+
+### permission.bash
+
+Controls whether bash commands require user approval. This can be configured globally or with specific patterns.
+
+```json title="opencode.json"
+{
+  "permission": {
+    "bash": "ask"
+  }
+}
+```
+
+Or with specific patterns:
+
+```json title="opencode.json"
+{
+  "permission": {
+    "bash": {
+      "git *": "allow",
+      "npm install": "ask",
+      "*": "ask"
+    }
+  }
+}
+```
+
+## Configuration examples
+
+### Basic permission configuration
+
+```json title="opencode.json"
+{
+  "$schema": "https://opencode.ai/config.json",
+  "permission": {
+    "edit": "ask",
+    "bash": "ask"
+  }
+}
+```
+
+### Advanced bash permission configuration
+
+```json title="opencode.json"
+{
+  "$schema": "https://opencode.ai/config.json",
+  "permission": {
+    "edit": "ask",
+    "bash": {
+      "git status": "allow",
+      "git diff": "allow",
+      "git add *": "ask",
+      "git commit*": "ask",
+      "npm install": "ask",
+      "npm run build": "allow",
+      "ls": "allow",
+      "pwd": "allow",
+      "*": "ask"
+    }
+  }
+}
+```
+
+### Permissive configuration (development only)
+
+```json title="opencode.json"
+{
+  "$schema": "https://opencode.ai/config.json",
+  "permission": {
+    "edit": "allow",
+    "bash": "allow"
+  }
+}
+```
+
+### Strict configuration
+
+```json title="opencode.json"
+{
+  "$schema": "https://opencode.ai/config.json",
+  "permission": {
+    "edit": "ask",
+    "bash": {
+      "*": "ask"
+    }
+  }
+}
+```
+
+## Best practices
+
+1. **Start with "ask"**: Begin with asking for permissions and adjust based on your workflow
+2. **Use patterns wisely**: Create specific patterns for commands you trust
+3. **Review regularly**: Periodically review your permission settings
+4. **Be specific**: Use specific patterns rather than broad wildcards when possible
+5. **Document exceptions**: Comment your configuration to explain why certain permissions are set
+
+This permissions system ensures that you maintain control over what AI agents can do in your codebase while providing flexibility for trusted operations.