使用 declarative permission rules 控制 agent 可以 read 或 write 哪些 files 和 directories。将 rules list 传给 permissions= 后，agent 的 built-in filesystem tools 会遵守这些规则。
Permissions 需要 deepagents>=1.9.1。
Permissions 只适用于 built-in filesystem tools（ls、read_file、glob、grep、write_file、edit_file）。访问 filesystem 的 custom tools 和 MCP tools 不在覆盖范围内。Permissions 也不适用于 sandbox backends，后者通过 execute tool 支持任意 command execution。
当你需要对 built-in filesystem tools 设置 path-based allow/deny rules 时，请使用 permissions。当你需要 custom validation logic（rate limiting、audit logging、content inspection），或需要控制 custom tools 时，请使用 backend policy hooks。

​
Basic usage

将 FilesystemPermission rules list 传给 createDeepAgent。Rules 按 declaration order 求值。第一条匹配的 rule 生效。如果没有 rule 匹配，则允许 operation。 
const agent = createDeepAgent({
  model,
  backend,
  permissions: [
    {
      operations: ["write"],
      paths: ["/**"],
      mode: "deny",
    },
  ],
});
if (!agent) throw new Error("basic: agent not created");

​
Rule structure

每个 FilesystemPermission 都有三个 fields：
FieldTypeDescription
operations("read" | "write")[]该 rule 适用的 operations。"read" 覆盖 ls、read_file、glob、grep。"write" 覆盖 write_file、edit_file。
pathsstring[]用于匹配 file paths 的 glob patterns（例如 ["/workspace/**"]）。支持 ** recursive matching 和 {a,b} alternation。
mode"allow" | "deny"匹配 operations 时是允许还是拒绝。默认值为 "allow"。
Rules 使用 first-match-wins evaluation：第一条 operations 和 paths 与当前 call 匹配的 rule 会决定结果。如果没有 rule 匹配，则 call 会被 allowed（permissive default）。 Paths 必须是 absolute（以 / 开头），且不能包含 .. 或 ~。Invalid paths 会在 agent construction time 抛出错误。

​
Examples

​
Isolate to a workspace directory

只允许在 /workspace/ 下 read 和 write，并拒绝其他所有内容： 
const agent = createDeepAgent({
  model,
  backend,
  permissions: [
    {
      operations: ["read", "write"],
      paths: ["/workspace/**"],
      mode: "allow",
    },
    {
      operations: ["read", "write"],
      paths: ["/**"],
      mode: "deny",
    },
  ],
});
if (!agent) throw new Error("isolate-workspace: agent not created");

​
Protect specific files

const agent = createDeepAgent({
  model,
  backend,
  permissions: [
    {
      operations: ["read", "write"],
      paths: ["/workspace/.env", "/workspace/examples/**"],
      mode: "deny",
    },
    {
      operations: ["read", "write"],
      paths: ["/workspace/**"],
      mode: "allow",
    },
    {
      operations: ["read", "write"],
      paths: ["/**"],
      mode: "deny",
    },
  ],
});
if (!agent) throw new Error("protect-files: agent not created");

​
Read-only memory

允许 agent read memory files，但阻止其修改这些 files。这适用于 organization-wide policies 或只应由 application code 更新的 shared knowledge bases。更多 context 请参阅 read-only vs writable memory。 
const store = new InMemoryStore();
const agent = createDeepAgent({
  model,
  backend: new CompositeBackend(new StateBackend(), {
    "/memories/": new StoreBackend({
      namespace: (rt) => [rt.serverInfo.user.identity],
    }),
    "/policies/": new StoreBackend({
      namespace: (rt) => [rt.context.orgId],
    }),
  }),
  permissions: [
    {
      operations: ["write"],
      paths: ["/memories/**", "/policies/**"],
      mode: "deny",
    },
  ],
  store,
});
if (!agent) throw new Error("read-only-memory: agent not created");

​
Deny all access

阻止所有 reads 和 writes。这是一个 restrictive baseline，你可以在其上叠加更具体的 allow rules： 
const agent = createDeepAgent({
  model,
  backend,
  permissions: [
    {
      operations: ["read", "write"],
      paths: ["/**"],
      mode: "deny",
    },
  ],
});
if (!agent) throw new Error("deny-all: agent not created");

​
Rule ordering

由于 first-match-wins，rule order 很重要。请将更 specific 的 rules 放在更 broad 的 rules 前： 
const correctPermissions: FilesystemPermission[] = [
  { operations: ["read", "write"], paths: ["/workspace/.env"], mode: "deny" },
  {
    operations: ["read", "write"],
    paths: ["/workspace/**"],
    mode: "allow",
  },
  { operations: ["read", "write"], paths: ["/**"], mode: "deny" },
];

const incorrectPermissions: FilesystemPermission[] = [
  {
    operations: ["read", "write"],
    paths: ["/workspace/**"],
    mode: "allow",
  },
  {
    operations: ["read", "write"],
    paths: ["/workspace/.env"],
    mode: "deny",
  },
  { operations: ["read", "write"], paths: ["/**"], mode: "deny" },
];

​
Subagent permissions

Subagents 默认继承 parent agent 的 permissions。若要为 subagent 提供不同 permissions，请在其 spec 中设置 permissions field。这会完全 replace parent 的 rules。 
const agent = createDeepAgent({
  model,
  backend,
  permissions: [
    {
      operations: ["read", "write"],
      paths: ["/workspace/**"],
      mode: "allow",
    },
    { operations: ["read", "write"], paths: ["/**"], mode: "deny" },
  ],
  subagents: [
    {
      name: "auditor",
      description: "Read-only code reviewer",
      systemPrompt: "Review the code for issues.",
      permissions: [
        { operations: ["write"], paths: ["/**"], mode: "deny" },
        { operations: ["read"], paths: ["/workspace/**"], mode: "allow" },
        { operations: ["read"], paths: ["/**"], mode: "deny" },
      ],
    },
  ],
});
if (!agent) throw new Error("subagent: agent not created");
若要显式授予 subagent unrestricted access，请设置 permissions: []。空 array 会用无 restrictions 覆盖 parent rules。省略 permissions 则从 parent 继承。

​
Composite backends

使用带 sandbox default 的 CompositeBackend 时，每个 permission path 都必须限定在已知 route prefix 下。Sandboxes 支持任意 command execution，因此仅靠 path-based restrictions 无法阻止通过 shell commands 访问 filesystem。将 permissions 限定到 route-specific backends 可以避免这一冲突。 
const sandbox = new StateBackend();
const memoriesBackend = new StateBackend();
const composite = new CompositeBackend(sandbox, {
  "/memories/": memoriesBackend,
});
const agent = createDeepAgent({
  model,
  backend: composite,
  permissions: [
    { operations: ["write"], paths: ["/memories/**"], mode: "deny" },
  ],
});
if (!agent) throw new Error("composite-backend: agent not created");
包含任何 route 外 paths 的 permissions 会在 construction time 抛出错误： 
const sandbox = new StateBackend();
const memoriesBackend = new StateBackend();
const composite = new CompositeBackend(sandbox, {
  "/memories/": memoriesBackend,
});

createDeepAgent({
  model,
  backend: composite,
  permissions: [
    { operations: ["write"], paths: ["/workspace/**"], mode: "deny" },
  ],
});

createDeepAgent({
  model,
  backend: composite,
  permissions: [{ operations: ["read"], paths: ["/**"], mode: "deny" }],
});
Connect these docs to Claude, VSCode, and more via MCP for real-time answers.
Edit this page on GitHub or file an issue.