Skip to content

Commit 8ad93be

Browse files
committed
fix(agent): preserve subagent self-declared tool allows over inherited parent denies
deriveSubagentSessionPermission no longer forwards a parent agent's edit deny (or parent-session denies) for any permission the subagent explicitly allows, so custom subagents like general-opus-4.7 (edit: allow) spawned by edit-denying orchestrators keep edit/write access. Built-in explore/general still inherit the Plan Mode ceiling since they don't declare edit: allow. Adds regression tests and documents the recurring regression + invariant in AGENTS.md. Refs anomalyco#26514 anomalyco#27201 anomalyco#27654.
1 parent 9465f3e commit 8ad93be

3 files changed

Lines changed: 127 additions & 9 deletions

File tree

‎AGENTS.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -221,6 +221,38 @@ const table = sqliteTable("session", {
221221
- Keep EventV2 replay owner claims separate from clustered Session execution ownership.
222222
- Keep the System Context algebra, registry, and built-ins in `src/system-context`; keep Context Source producers with their observed domains, and keep Session History selection plus Context Epoch persistence Session-owned.
223223

224+
## Custom Agent / Subagent Permissions (RECURRING REGRESSION)
225+
226+
This is a recurring regression that breaks on rebases. Re-verify the invariant below every time you rebase onto `origin/dev`.
227+
228+
### Symptom
229+
230+
Custom subagents defined in `~/.config/opencode/agents/*.md` (e.g. `explore-opus-4.7`) lose access to tools they explicitly allow in their frontmatter `permission:` block (`read`/`grep`/`glob`/`edit`/`bash`) when spawned via the `task` tool by a parent agent — especially orchestrators like `beast-orchestrator-*` that `deny` those tools.
231+
232+
### Mechanism
233+
234+
- Permission gating is **permission-only** (there is no per-agent tools list) and is **LAST-MATCH-WINS** via `findLast` in `packages/core/src/permission.ts`.
235+
- A subagent's runtime ruleset is `Permission.merge(subagent.permission, derivedSessionPermission)`.
236+
- Denies forwarded from the parent into the derived session permission land **last** and therefore override the subagent's own `allow` rules.
237+
238+
### Canonical Fix Location
239+
240+
`deriveSubagentSessionPermission` in `packages/opencode/src/agent/subagent-permissions.ts` (find by function name, not line number).
241+
242+
### INVARIANT (re-verify after every rebase)
243+
244+
A parent agent's `edit`/tool `deny` must **NOT** be forwarded into a subagent session for any permission the subagent explicitly `allow`s. Subagent self-declared allows win over inherited parent ceilings — **EXCEPT** where Plan Mode requires the ceiling: built-in `explore`/`general` do **not** declare `edit: allow`, so they still inherit the parent `edit` deny (Plan Mode read-only stays enforced).
245+
246+
### Upstream Issue Chain
247+
248+
`#26514 → #27201 → #27654` — watch these so future rebases can recognize related upstream churn around this code.
249+
250+
### Verification
251+
252+
- From `packages/opencode` run `bun test test/agent/` (specifically subagent permission tests like `plan-mode-subagent-bypass.test.ts`) plus `bun typecheck`.
253+
- Tests CANNOT run from repo root (guard `do-not-run-tests-from-root`).
254+
- Manual repro: define a custom agent with `edit: allow`, have an orchestrator agent (which has `edit: deny`) spawn it via the `task` tool, and confirm `edit`/`write` are available in the spawned subagent.
255+
224256
## Troubleshooting
225257

226258
### "Unknown component type: spinner" Error

‎packages/opencode/src/agent/subagent-permissions.ts‎

Lines changed: 29 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -4,14 +4,27 @@ import type { Agent } from "./agent"
44

55
/**
66
* Build the `permission` ruleset for a subagent's session when it's spawned
7-
* via the task tool. Combines:
7+
* via the task tool.
88
*
9-
* 1. The parent **agent's** edit-class deny rules — Plan Mode's file-edit
9+
* Permission resolution is LAST-MATCH-WINS, and the subagent's runtime
10+
* ruleset is `Permission.merge(subagent.permission, derivedSessionPermission)`
11+
* — so any deny appended here lands LAST and would override the subagent's
12+
* own explicit allows. To respect self-declaration (#27654) while still
13+
* enforcing the Plan Mode ceiling for built-ins (#26514, #27201), we DO NOT
14+
* forward a parent `edit`/tool deny for any permission the subagent
15+
* explicitly `allow`s. Built-in `explore`/`general` subagents do not declare
16+
* `edit: allow`, so they still inherit the Plan Mode read-only ceiling.
17+
*
18+
* Combines:
19+
*
20+
* 1. The parent **agent's** `edit` deny rules — Plan Mode's file-edit
1021
* restriction lives on the agent ruleset, not on the session, so a
1122
* subagent that only inherited the parent SESSION's permission would
12-
* silently bypass it. (#26514)
13-
* 2. The parent **session's** deny rules and external_directory rules —
14-
* same forwarding the original code already did.
23+
* silently bypass it (#26514, #27201). These are skipped entirely when
24+
* the subagent explicitly allows `edit` (#27654).
25+
* 2. The parent **session's** `external_directory` rules (forwarded
26+
* unconditionally) and generic deny rules (forwarded only when the
27+
* subagent does not explicitly allow that same permission, #27654).
1528
* 3. Default `todowrite` and `task` denies if the subagent's own ruleset
1629
* doesn't already permit them.
1730
*/
@@ -22,12 +35,20 @@ export function deriveSubagentSessionPermission(input: {
2235
}): PermissionV1.Ruleset {
2336
const canTask = input.subagent.permission.some((rule) => rule.permission === "task")
2437
const canTodo = input.subagent.permission.some((rule) => rule.permission === "todowrite")
25-
const parentAgentDenies =
26-
input.parentAgent?.permission.filter((rule) => rule.action === "deny" && rule.permission === "edit") ?? []
38+
const subagentAllowsEdit = input.subagent.permission.some(
39+
(rule) => rule.permission === "edit" && rule.action === "allow",
40+
)
41+
const subagentAllows = new Set(
42+
input.subagent.permission.filter((rule) => rule.action === "allow").map((rule) => rule.permission),
43+
)
44+
const parentAgentDenies = subagentAllowsEdit
45+
? []
46+
: (input.parentAgent?.permission.filter((rule) => rule.action === "deny" && rule.permission === "edit") ?? [])
2747
return [
2848
...parentAgentDenies,
2949
...input.parentSessionPermission.filter(
30-
(rule) => rule.permission === "external_directory" || rule.action === "deny",
50+
(rule) =>
51+
rule.permission === "external_directory" || (rule.action === "deny" && !subagentAllows.has(rule.permission)),
3152
),
3253
...(canTodo ? [] : [{ permission: "todowrite" as const, pattern: "*" as const, action: "deny" as const }]),
3354
...(canTask ? [] : [{ permission: "task" as const, pattern: "*" as const, action: "deny" as const }]),

‎packages/opencode/test/agent/plan-mode-subagent-bypass.test.ts‎

Lines changed: 66 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -192,11 +192,15 @@ it.effect("[#26700] controller self-restrictions do not erase executor permissio
192192

193193
it.effect("subagent inherits parent session deny rules as hard runtime ceilings", () =>
194194
Effect.sync(() => {
195+
// The executor does NOT explicitly allow `bash`, so the parent
196+
// session's `bash: deny` is forwarded and remains a hard ceiling.
197+
// (An explicit subagent `bash: allow` would override it per #27654 —
198+
// see the [#27654] test below.)
195199
const executor = testAgent({
196200
name: "executor",
197201
mode: "subagent",
198202
permission: {
199-
bash: "allow",
203+
read: "allow",
200204
},
201205
})
202206
const effective = Permission.merge(
@@ -211,3 +215,64 @@ it.effect("subagent inherits parent session deny rules as hard runtime ceilings"
211215
expect(Permission.evaluate("bash", "git status", effective).action).toBe("deny")
212216
}),
213217
)
218+
219+
it.effect("[#27654] subagent self-declared edit:allow wins over parent agent edit:deny", () =>
220+
Effect.sync(() => {
221+
const orchestrator = testAgent({ name: "orchestrator", mode: "primary", permission: { edit: "deny", bash: "deny" } })
222+
const custom = testAgent({
223+
name: "custom",
224+
mode: "subagent",
225+
permission: { edit: "allow", bash: "allow", read: "allow" },
226+
})
227+
const derived = deriveSubagentSessionPermission({
228+
parentSessionPermission: [],
229+
parentAgent: orchestrator,
230+
subagent: custom,
231+
})
232+
233+
// The parent agent's `edit: deny` is NOT forwarded because the subagent
234+
// explicitly allows `edit`.
235+
expect(derived.some((r) => r.permission === "edit" && r.action === "deny")).toBe(false)
236+
237+
const effective = Permission.merge(custom.permission, derived)
238+
expect(Permission.evaluate("edit", "/some/file.ts", effective).action).toBe("allow")
239+
}),
240+
)
241+
242+
it.effect("[#26514] subagent without edit:allow still inherits parent agent edit:deny ceiling", () =>
243+
Effect.sync(() => {
244+
const orchestrator = testAgent({ name: "orchestrator", mode: "primary", permission: { edit: "deny", bash: "deny" } })
245+
const plain = testAgent({ name: "plain", mode: "subagent", permission: { read: "allow" } })
246+
const derived = deriveSubagentSessionPermission({
247+
parentSessionPermission: [],
248+
parentAgent: orchestrator,
249+
subagent: plain,
250+
})
251+
252+
// No explicit `edit: allow` on the subagent, so the parent's `edit: deny`
253+
// is still forwarded as a hard ceiling.
254+
expect(derived.some((r) => r.permission === "edit" && r.action === "deny")).toBe(true)
255+
256+
const effective = Permission.merge(plain.permission, derived)
257+
expect(Permission.evaluate("edit", "/some/file.ts", effective).action).toBe("deny")
258+
}),
259+
)
260+
261+
it.effect("[#27654] parent session deny is not forwarded for a permission the subagent allows", () =>
262+
Effect.sync(() => {
263+
const sub = testAgent({ name: "sub", mode: "subagent", permission: { bash: "allow" } })
264+
const parentSession = Permission.fromConfig({ bash: "deny", external_directory: "deny" })
265+
const derived = deriveSubagentSessionPermission({
266+
parentSessionPermission: parentSession,
267+
parentAgent: undefined,
268+
subagent: sub,
269+
})
270+
271+
// `bash` deny is NOT forwarded because the subagent explicitly allows bash.
272+
const effective = Permission.merge(sub.permission, derived)
273+
expect(Permission.evaluate("bash", "git status", effective).action).toBe("allow")
274+
275+
// `external_directory` is forwarded unconditionally.
276+
expect(derived.some((r) => r.permission === "external_directory")).toBe(true)
277+
}),
278+
)

0 commit comments

Comments
 (0)