fix: update deepagents docs to reference permissions across pages (#3539)

## Description
Updates deepagents docs pages to properly reference the new permissions
system.

**Permissions page improvements:**
- Reordered examples: "Isolate to a workspace directory" first, "Deny
all access" last
- Renamed "Sandbox" to "Isolate" to avoid overloaded terminology
- Added "Read-only memory" example protecting both `/memories/` and
`/policies/`
- Fixed "Protect specific files" example to include trailing deny-all
rule

**Cross-page references added:**
- `going-to-production.mdx`: New "Filesystem permissions" subsection
under Guardrails
- `memory.mdx`: References permissions alongside policy hooks for
read-only enforcement
- `backends.mdx`: Tip before "Add policy hooks" pointing to permissions
as a simpler alternative
- `harness.mdx`: New "Filesystem permissions" section in the
capabilities overview
- `subagents.mdx`: Added `permissions` field to SubAgent spec tables
(Python and JS)
- `overview.mdx`: Added permissions to "When to use" list, Core
capabilities cards, and Get started card groups

## Test Plan
- [ ] Verify permissions page examples are reordered sensibly (isolate
first, deny-all last)
- [ ] Verify "Protect specific files" example has trailing deny-all
- [ ] Verify "Read-only memory" example denies writes to both
`/memories/` and `/policies/`
- [ ] Verify going-to-production guardrails section mentions permissions
- [ ] Verify memory read-only section references permissions
- [ ] Verify backends page has tip before policy hooks section
- [ ] Verify harness page has new filesystem permissions section
- [ ] Verify subagents page lists `permissions` field in both Python and
JS tables
- [ ] Verify overview page has permissions in capabilities and card
groups

_Opened collaboratively by Nick Hollon and open-swe._

---------

Co-authored-by: open-swe[bot] <open-swe@users.noreply.github.com>
Co-authored-by: Nick Hollon <274035459+nick-hollon-lc@users.noreply.github.com>
Co-authored-by: Nick Hollon <nick.hollon@langchain.dev>

Author: 3 people

src/oss/deepagents/backends.mdx

@@ -27,6 +27,7 @@ This page explains how to:
 - [choose a backend](#specify-a-backend),
 - [route different paths to different backends](#route-to-different-backends),
 - [implement your own virtual filesystem](#use-a-virtual-filesystem) (e.g., S3 or Postgres),
+- [set permissions](#permissions) on filesystem access,
 :::js
 - [add policy hooks](#add-policy-hooks),
 [work with binary and multimodal files](#multimodal-and-binary-files),
@@ -544,9 +545,42 @@ Postgres-style outline:
   - `grep` can fetch candidate rows by extension or last modified time, then scan lines (skip rows where `mime_type` is binary) → return `GrepResult`
 :::
 
+## Permissions
+
+Use [permissions](/oss/deepagents/permissions) to declaratively control which files and directories the agent can read or write. Permissions apply to the built-in filesystem tools and are evaluated before the backend is called.
+
+:::python
+```python
+from deepagents import create_deep_agent, FilesystemPermission
+
+agent = create_deep_agent(
+    backend=CompositeBackend(
+        default=StateBackend(),
+        routes={
+            "/memories/": StoreBackend(
+                namespace=lambda rt: (rt.server_info.user.identity,),
+            ),
+            "/policies/": StoreBackend(
+                namespace=lambda rt: (rt.context.org_id,),
+            ),
+        },
+    ),
+    permissions=[
+        FilesystemPermission(
+            operations=["write"],
+            paths=["/policies/**"],
+            mode="deny",
+        ),
+    ],
+)
+```
+:::
+
+For the full set of options including rule ordering, subagent permissions, and composite backend interactions, see the [permissions guide](/oss/deepagents/permissions).
+
 ## Add policy hooks
 
-Enforce enterprise rules by subclassing or wrapping a backend.
+For custom validation logic beyond path-based allow/deny rules (rate limiting, audit logging, content inspection), enforce enterprise rules by subclassing or wrapping a backend.
 
 Block writes/edits under selected prefixes (subclass):
 

src/oss/deepagents/going-to-production.mdx

@@ -184,7 +184,7 @@ Memory is always persistent across conversations. The main question is how it's
 | **Global** | `(org_id)` | Read-only policies for all users and assistants | "Never disclose internal pricing" |
 
 <Warning>
-Shared memory (assistant, user, or organization scope) is a vector for prompt injection. If one user can write to memory that another user's conversation reads, a malicious user could inject instructions into that shared state. Enforce read-only access where appropriate. For example, make organization-wide policies writable only through application code, not by the agent itself.
+Shared memory (assistant, user, or organization scope) is a vector for prompt injection. If one user can write to memory that another user's conversation reads, a malicious user could inject instructions into that shared state. Enforce read-only access where appropriate. For example, make organization-wide policies writable only through application code, not by the agent itself. Use [permissions](/oss/deepagents/permissions) to declaratively deny writes to shared paths, or [backend policy hooks](/oss/deepagents/backends#add-policy-hooks) for custom validation logic.
 </Warning>
 
 ### Configuration
@@ -878,7 +878,10 @@ Avoid passing secrets into sandboxes via environment variables or file uploads.
 
 ## Guardrails
 
-Agents in production run autonomously, which means they can loop indefinitely, hit rate limits, or process user data that contains sensitive information. Deep Agents support [middleware](/oss/langchain/middleware/built-in) that wraps model and tool calls to handle these concerns.
+Agents in production run autonomously, which means they can loop indefinitely, hit rate limits, or process user data that contains sensitive information. Deep Agents provide two layers of protection:
+
+- **[Permissions](/oss/deepagents/permissions)**: declarative allow/deny rules that control which files and directories the agent can read or write. Use permissions to isolate the agent to a working directory, protect sensitive files, or enforce read-only memory.
+- **[Middleware](/oss/langchain/middleware/built-in)**: hooks that wrap model and tool calls for rate limiting, error handling, and data privacy.
 
 ### Rate limiting
 

src/oss/deepagents/harness.mdx

@@ -7,6 +7,7 @@ An agent harness is a combination of several different capabilities that make bu
 
 - [Planning capabilities](#planning-capabilities)
 - [Virtual filesystem](#virtual-filesystem-access)
+- [Filesystem permissions](#filesystem-permissions)
 - [Task delegation (subagents)](#task-delegation-subagents)
 - [Context and token management](#context-management)
 - [Code execution](#code-execution)
@@ -55,6 +56,24 @@ You can also use the file system when building custom tools and middleware for D
 
 For more information, see [backends](/oss/deepagents/backends).
 
+## Filesystem permissions
+
+The harness supports declarative permission rules that control which files and directories the agent can read or write. Permissions apply to the built-in filesystem tools listed above and are evaluated in declaration order with first-match-wins semantics.
+
+**How it works:**
+- Pass a list of rules to `permissions=` when creating the agent
+- Each rule specifies `operations` (`"read"`, `"write"`), `paths` (glob patterns), and `mode` (`"allow"` or `"deny"`)
+- The first matching rule wins. If no rule matches, the operation is allowed.
+
+**Why it's useful:**
+- Restrict agents to specific directories (e.g., `/workspace/`)
+- Protect sensitive files (e.g., `.env`, credentials)
+- Give subagents narrower access than the parent agent
+
+Permissions do not apply to [sandbox backends](/oss/deepagents/sandboxes), which support arbitrary command execution via the `execute` tool. For custom validation logic, use [backend policy hooks](/oss/deepagents/backends#add-policy-hooks).
+
+For the full rule structure, examples, and subagent inheritance, see [Permissions](/oss/deepagents/permissions).
+
 ## Task delegation (subagents)
 
 The harness allows the main agent to create ephemeral "subagents" for isolated multi-step tasks.

src/oss/deepagents/memory.mdx

@@ -629,7 +629,7 @@ await client.store.putItem(
 ```
 :::
 
-Use [policy hooks](/oss/deepagents/backends#add-policy-hooks) to enforce that org-level memory is read-only.
+Use [permissions](/oss/deepagents/permissions) to enforce that org-level memory is read-only, or [policy hooks](/oss/deepagents/backends#add-policy-hooks) for custom validation logic.
 
 ### Background consolidation
 
@@ -827,15 +827,15 @@ By default, the agent can both read and write memory files. For shared state lik
 | Permission | Use case | How it works |
 |---|---|---|
 | **Read-write** (default) | User preferences, agent self-improvement, learned [skills](/oss/deepagents/skills) | Agent updates files via `edit_file` tool |
-| **Read-only** | Organization policies, compliance rules, shared knowledge bases, developer-defined [skills](/oss/deepagents/skills) | Populate via application code or the [Store API](/langsmith/custom-store). Use [policy hooks](/oss/deepagents/backends#add-policy-hooks) to block agent writes. |
+| **Read-only** | Organization policies, compliance rules, shared knowledge bases, developer-defined [skills](/oss/deepagents/skills) | Populate via application code or the [Store API](/langsmith/custom-store). Use [permissions](/oss/deepagents/permissions) to deny writes to specific paths, or [policy hooks](/oss/deepagents/backends#add-policy-hooks) for custom validation logic. |
 
 **Security considerations:** If one user can write to memory that another user reads, a malicious user could inject instructions into shared state. To mitigate this:
 
 - **Default to user scope** `(user_id)` unless you have a specific reason to share
 - Use **read-only memory** for shared policies (populate via application code, not the agent)
 - Add **human-in-the-loop** validation before the agent writes to shared memory. Use an [interrupt](/oss/langgraph/interrupts) to require human approval for writes to sensitive paths.
 
-To enforce read-only memory, use [policy hooks](/oss/deepagents/backends#add-policy-hooks) on the backend to reject write operations to specific paths.
+To enforce read-only memory, use [permissions](/oss/deepagents/permissions) to declaratively deny writes to specific paths. For custom validation logic (rate limiting, audit logging, content inspection), use [backend policy hooks](/oss/deepagents/backends#add-policy-hooks).
 
 ### Concurrent writes
 

src/oss/deepagents/overview.mdx

@@ -95,6 +95,7 @@ Use the **Deep Agents SDK** when you want to build agents that can:
 - **Execute shell commands** via the `execute` tool when using a [sandbox backend](/oss/deepagents/sandboxes)
 - **Delegate work** to specialized subagents for context isolation
 - **Persist memory** across conversations and threads
+- **Control filesystem access** with declarative [permission rules](/oss/deepagents/permissions) that restrict which files agents can read or write
 - **Require human approval** for sensitive operations with [human-in-the-loop](/oss/deepagents/human-in-the-loop) workflows
 - **Use any model** that supports tool calling — [provider agnostic](/oss/deepagents/models) across frontier and open models
 
@@ -126,6 +127,9 @@ For building simpler agents, consider using LangChain's [`createAgent`](/oss/lan
 <Card title="Long-term memory" icon="database">
     Extend agents with persistent memory across threads using LangGraph's [Memory Store](/oss/langgraph/persistence#memory-store). Agents can save and retrieve information from previous conversations.
 </Card>
+<Card title="Filesystem permissions" icon="lock">
+    Declare [permission rules](/oss/deepagents/permissions) that control which files and directories agents can read or write. Subagents can inherit or override the parent's rules.
+</Card>
 <Card title="Human-in-the-loop" icon="user-check">
     Configure [human approval](/oss/deepagents/human-in-the-loop) for sensitive tool operations using LangGraph's interrupt capabilities. Control which tools require confirmation before execution.
 </Card>
@@ -155,6 +159,9 @@ For building simpler agents, consider using LangChain's [`createAgent`](/oss/lan
     <Card title="Sandboxes" icon="cube" href="/oss/deepagents/sandboxes">
         Execute code in isolated environments
     </Card>
+    <Card title="Permissions" icon="lock" href="/oss/deepagents/permissions">
+        Control filesystem access with permission rules
+    </Card>
     <Card title="Human-in-the-loop" icon="user-check" href="/oss/deepagents/human-in-the-loop">
         Configure approval for sensitive operations
     </Card>
@@ -184,6 +191,9 @@ For building simpler agents, consider using LangChain's [`createAgent`](/oss/lan
     <Card title="Backends" icon="plug" href="/oss/deepagents/backends">
         Choose and configure pluggable filesystem backends
     </Card>
+    <Card title="Permissions" icon="lock" href="/oss/deepagents/permissions">
+        Control filesystem access with permission rules
+    </Card>
     <Card title="Human-in-the-loop" icon="user-check" href="/oss/deepagents/human-in-the-loop">
         Configure approval for sensitive operations
     </Card>

src/oss/deepagents/permissions.mdx

@@ -56,13 +56,20 @@ Rules use first-match-wins evaluation: the first rule whose `operations` and `pa
 
 :::python
 
-### Deny all access
+### Isolate to a workspace directory
+
+Allow reads and writes only under `/workspace/` and deny everything else:
 
 ```python
 agent = create_deep_agent(
     model=model,
     backend=backend,
     permissions=[
+        FilesystemPermission(
+            operations=["read", "write"],
+            paths=["/workspace/**"],
+            mode="allow",
+        ),
         FilesystemPermission(
             operations=["read", "write"],
             paths=["/**"],
@@ -72,13 +79,18 @@ agent = create_deep_agent(
 )
 ```
 
-### Sandbox to a workspace directory
+### Protect specific files
 
 ```python
 agent = create_deep_agent(
     model=model,
     backend=backend,
     permissions=[
+        FilesystemPermission(
+            operations=["read", "write"],
+            paths=["/workspace/.env", "/workspace/examples/**"],
+            mode="deny",
+        ),
         FilesystemPermission(
             operations=["read", "write"],
             paths=["/workspace/**"],
@@ -93,22 +105,47 @@ agent = create_deep_agent(
 )
 ```
 
-### Protect specific files
+### Read-only memory
+
+Allow the agent to read memory files but prevent it from modifying them. This is useful for organization-wide policies or shared knowledge bases that should only be updated by application code. See [read-only vs writable memory](/oss/deepagents/memory#read-only-vs-writable-memory) for more context.
 
 ```python
 agent = create_deep_agent(
     model=model,
-    backend=backend,
+    backend=CompositeBackend(
+        default=StateBackend(),
+        routes={
+            "/memories/": StoreBackend(
+                namespace=lambda rt: (rt.server_info.user.identity,),
+            ),
+            "/policies/": StoreBackend(
+                namespace=lambda rt: (rt.context.org_id,),
+            ),
+        },
+    ),
     permissions=[
         FilesystemPermission(
-            operations=["read", "write"],
-            paths=["/workspace/.env", "/workspace/examples/**"],
+            operations=["write"],
+            paths=["/memories/**", "/policies/**"],
             mode="deny",
         ),
+    ],
+)
+```
+
+### Deny all access
+
+Block all reads and writes. This is a restrictive baseline you can layer more specific allow rules on top of:
+
+```python
+agent = create_deep_agent(
+    model=model,
+    backend=backend,
+    permissions=[
         FilesystemPermission(
             operations=["read", "write"],
-            paths=["/workspace/**"],
-            mode="allow",
+            paths=["/**"],
+            mode="deny",
         ),
     ],
 )

src/oss/deepagents/subagents.mdx

@@ -60,6 +60,7 @@ For most use cases, define subagents as dictionaries matching the @[`SubAgent`]
 | `middleware` | `list[Middleware]` | Optional. Additional middleware for custom behavior, logging, or rate limiting.<br></br>Does not inherit from main agent. |
 | `interrupt_on` | `dict[str, bool]` | Optional. Configure [human-in-the-loop](/oss/deepagents/human-in-the-loop) for specific tools. Subagent value overrides main agent. Requires checkpointer.<br></br>Inherits from main agent by default. Subagent value overrides the default. |
 | `skills` | `list[str]` | Optional. [Skills](/oss/deepagents/skills) source paths. When specified, the subagent will load skills from these directories (e.g., `["/skills/research/", "/skills/web-search/"]`). This allows subagents to have different skill sets than the main agent.<br></br>Does not inherit from main agent. Only the general-purpose subagent inherits the main agent's skills. When a subagent has skills, it runs its own independent @[`SkillsMiddleware`] instance. Skill state is fully isolated—a subagent's loaded skills are not visible to the parent, and vice versa. |
+| `permissions` | `list[FilesystemPermission]` | Optional. [Filesystem permission rules](/oss/deepagents/permissions) for the subagent. When set, **replaces** the parent agent's permissions entirely.<br></br>Inherits from main agent by default. |
 
 :::