docs: fix permission system documentation in agents section (#7652)

2 files changed, 22 insertions, 6 deletions

diff --git a/packages/web/src/content/docs/agents.mdx b/packages/web/src/content/docs/agents.mdx
index 3dfd16e7d..7e6098f43 100644
--- a/packages/web/src/content/docs/agents.mdx
+++ b/packages/web/src/content/docs/agents.mdx
@@ -429,6 +429,7 @@ permission:
     "*": ask
     "git diff": allow
     "git log*": allow
+    "grep *": allow
   webfetch: deny
 ---
 
@@ -444,7 +445,8 @@ You can set permissions for specific bash commands.
     "build": {
       "permission": {
         "bash": {
-          "git push": "ask"
+          "git push": "ask",
+          "grep *": "allow"
         }
       }
     }
@@ -480,7 +482,7 @@ Since the last matching rule takes precedence, put the `*` wildcard first and sp
       "permission": {
         "bash": {
           "*": "ask",
-          "git status": "allow"
+          "git status *": "allow"
         }
       }
     }
diff --git a/packages/web/src/content/docs/permissions.mdx b/packages/web/src/content/docs/permissions.mdx
index 69c7206c7..b4f0691ce 100644
--- a/packages/web/src/content/docs/permissions.mdx
+++ b/packages/web/src/content/docs/permissions.mdx
@@ -57,7 +57,8 @@ For most permissions, you can use an object to apply different actions based on
       "*": "ask",
       "git *": "allow",
       "npm *": "allow",
-      "rm *": "deny"
+      "rm *": "deny",
+      "grep *": "allow"
     },
     "edit": {
       "*": "deny",
@@ -139,13 +140,20 @@ The set of patterns that `always` would approve is provided by the tool (for exa
 
 You can override permissions per agent. Agent permissions are merged with the global config, and agent rules take precedence. [Learn more](/docs/agents#permissions) about agent permissions.
 
+:::note
+Refer to the [Granular Rules (Object Syntax)](#granular-rules-object-syntax) section above for more detailed pattern matching examples.
+:::
+
 ```json title="opencode.json"
 {
   "$schema": "https://opencode.ai/config.json",
   "permission": {
     "bash": {
       "*": "ask",
-      "git status": "allow"
+      "git *": "allow",
+      "git commit *": "deny",
+      "git push *": "deny",
+      "grep *": "allow"
     }
   },
   "agent": {
@@ -153,8 +161,10 @@ You can override permissions per agent. Agent permissions are merged with the gl
       "permission": {
         "bash": {
           "*": "ask",
-          "git status": "allow",
-          "git push": "allow"
+          "git *": "allow",
+          "git commit *": "ask",
+          "git push *": "deny",
+          "grep *": "allow"
         }
       }
     }
@@ -176,3 +186,7 @@ permission:
 
 Only analyze code and suggest changes.
 ```
+
+:::tip
+Use pattern matching for commands with arguments. `"grep *"` allows `grep pattern file.txt`, while `"grep"` alone would block it. Commands like `git status` work for default behavior but require explicit permission (like `"git status *"`) when arguments are passed.
+:::