权限、审批、安全边界

6. 用户输入到 agent 行动的整体链路

model emits tool-call
  -> tool execute(params, ctx)
  -> ctx.ask({ permission, patterns })
  -> Permission.ask
  -> evaluate ruleset + approved
     - allow: continue
     - deny: throw DeniedError
     - ask: publish permission.asked and wait
  -> UI/CLI replies once/always/reject
  -> Deferred succeed/fail
  -> tool continues or fails

7. 核心源码逐段讲解

权限类型

export const Action = Schema.Literals(["allow", "deny", "ask"])

export const Rule = Schema.Struct({
  permission: Schema.String,
  pattern: Schema.String,
  action: Action,
})

export class Request extends Schema.Class<Request>("PermissionRequest")({
  id: PermissionID,
  sessionID: SessionID,
  permission: Schema.String,
  patterns: Schema.Array(Schema.String),
  metadata: Schema.Record(Schema.String, Schema.Unknown),
  always: Schema.Array(Schema.String),
  tool: Schema.optional(Schema.Struct({ messageID: MessageID, callID: Schema.String })),
}) {}

路径：packages/opencode/src/permission/index.ts:19-45。

规则计算

const match = rules.findLast(
  (rule) => Wildcard.match(permission, rule.permission) && Wildcard.match(pattern, rule.pattern),
)
return match ?? { action: "ask", permission, pattern: "*" }

路径：packages/opencode/src/permission/evaluate.ts:11-15。后写规则优先，默认 ask。

ask

for (const pattern of request.patterns) {
  const rule = evaluate(request.permission, pattern, ruleset, approved)
  if (rule.action === "deny") return yield* new DeniedError(...)
  if (rule.action === "allow") continue
  needsAsk = true
}

if (!needsAsk) return
const deferred = yield* Deferred.make<void, RejectedError | CorrectedError>()
pending.set(id, { info, deferred })
yield* bus.publish(Event.Asked, info)
return yield* Deferred.await(deferred)

路径：packages/opencode/src/permission/index.ts:161-196。

reply

if (input.reply === "reject") {
  yield* Deferred.fail(existing.deferred, new RejectedError())
  for (const [id, item] of pending.entries()) {
    if (item.info.sessionID !== existing.info.sessionID) continue
    pending.delete(id)
    yield* Deferred.fail(item.deferred, new RejectedError())
  }
  return
}

yield* Deferred.succeed(existing.deferred, undefined)
if (input.reply === "once") return

路径：packages/opencode/src/permission/index.ts:210-230。

默认权限

const defaults = Permission.fromConfig({
  "*": "allow",
  doom_loop: "ask",
  external_directory: { "*": "ask", ...whitelisted },
  question: "deny",
  plan_enter: "deny",
  plan_exit: "deny",
  repo_clone: "deny",
  read: {
    "*": "allow",
    "*.env": "ask",
    "*.env.*": "ask",
    "*.env.example": "allow",
  },
})

路径：packages/opencode/src/agent/agent.ts:103-122。

8. 关键 TypeScript 语法复习

• Schema.Literals(["allow", "deny", "ask"])：类似 Java enum。
• Schema.Class：运行时 schema + TS 类型 + class。
• Schema.optional：可选字段，运行时可能不存在。
• const { ruleset, ...request } = input：对象 rest。
• findLast：后面的规则优先。
• { -readonly [K in keyof _Info]: _Info[K] }：mapped type 去 readonly。

9-10. 架构思想与模块协作

• Policy engine：evaluate 计算 action。
• Event bus：permission.asked/replied 解耦 UI 和工具执行。
• Async gate：Deferred.await 暂停 tool execution。
• Layered ruleset：agent/session/approved 多层规则合并。
• Fail closed：默认 ask，非交互 CLI 默认 reject。

11. mini agent 对应代码

async function ask(input) {
  for (const pattern of input.patterns) {
    const rule = evaluate(input.permission, pattern, input.ruleset)
    if (rule.action === "deny") throw new Error("permission denied")
    if (rule.action === "ask") {
      const request = createPendingRequest(input)
      eventBus.emit("permission.asked", request)
      return await request.deferred
    }
  }
}