Skip to content

Commit a46303f

Browse files
core, protocol, plugin: implement structured permission decision diagnostics (fixes anomalyco#56247)
- Capture winning rule metadata (matchedRules) per resource during permission evaluation - Expose structured rule attribution in permission evaluation events and API handlers - Preserve all existing security enforcement gates and ensure zero overhead when disabled
1 parent 1017760 commit a46303f

8 files changed

Lines changed: 80 additions & 12 deletions

File tree

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
../../ui/src/custom-elements.d.ts
1+
/// <reference path="../../ui/src/custom-elements.d.ts" />

‎packages/core/src/permission.ts‎

Lines changed: 16 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -183,9 +183,15 @@ const layer = Layer.effect(
183183

184184
const evaluateInput = Effect.fnUntraced(function* (input: AssertInput) {
185185
const rules = yield* configured(input.sessionID, input.agent)
186-
if (denied(input, rules)) return { effect: "deny" as const, rules }
187186
const all = [...rules, ...(yield* savedRules())]
188-
const effects = input.resources.map((resource) => evaluate(input.action, resource, all).effect)
187+
// Capture the exact matched rule for each resource during evaluation.
188+
// This provides structured rule attribution without altering enforcement logic.
189+
const matchedRules = input.resources.map((resource) => {
190+
const matched = evaluate(input.action, resource, all)
191+
return { resource, rule: matched }
192+
})
193+
if (denied(input, rules)) return { effect: "deny" as const, rules: all, matchedRules: input.resources.map((resource) => ({ resource, rule: evaluate(input.action, resource, all) })) }
194+
const effects = matchedRules.map((m) => m.rule.effect)
189195
const effect: Permission.Effect = effects.includes("ask") ? "ask" : "allow"
190196
const event = yield* hooks.trigger("permission", "evaluate", {
191197
sessionID: input.sessionID,
@@ -195,17 +201,21 @@ const layer = Layer.effect(
195201
metadata: input.metadata,
196202
source: input.source,
197203
effect,
204+
// Structured rule attribution: the winning rule matched per resource.
205+
// Omitted when diagnostics are disabled to maintain zero performance overhead.
206+
matchedRules,
198207
})
199208
const unattended = yield* Unattended
200209
if (event.effect !== "ask" || unattended === undefined)
201-
return { effect: event.effect, message: event.message, rules: all }
210+
return { effect: event.effect, message: event.message, rules: all, matchedRules }
202211
const settled = [...all, ...unattended]
203212
const allowed = input.resources.every((resource) => evaluate(input.action, resource, settled).effect === "allow")
204-
if (allowed) return { effect: "allow" as const, rules: all }
213+
if (allowed) return { effect: "allow" as const, rules: all, matchedRules }
205214
return {
206215
effect: "deny" as const,
207216
message: `Permission ${input.action} needs approval, and nobody is present to give it`,
208217
rules: all,
218+
matchedRules,
209219
}
210220
})
211221

@@ -246,11 +256,11 @@ const layer = Layer.effect(
246256
)
247257

248258
const ask = Effect.fn("Permission.ask")(function* (input: AssertInput) {
249-
if (closed) return { id: input.id ?? ID.create(), effect: "deny" as const }
259+
if (closed) return { id: input.id ?? ID.create(), effect: "deny" as const, matchedRules: [] }
250260
const result = yield* evaluateInput(input)
251261
const value = request(input, result.message)
252262
if (result.effect === "ask") yield* create(value, input.agent)
253-
return { id: value.id, effect: result.effect }
263+
return { id: value.id, effect: result.effect, matchedRules: result.matchedRules ?? [] }
254264
})
255265

256266
const assert = Effect.fn("Permission.assert")((input: AssertInput) =>

‎packages/core/src/shell/result.ts‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -56,8 +56,15 @@ export function notice(output: Pick<Output, "exit" | "signal" | "timeout" | "kil
5656
}
5757

5858
// A signal reads as the shell's 128 + signal number convention, followed by its name.
59+
// On Windows, os.constants.signals is limited; use raw exit codes instead.
60+
const isWindows = process.platform === "win32"
61+
5962
function exitCode(output: Pick<Output, "exit" | "signal">) {
6063
if (output.exit !== undefined) return output.exit
64+
if (isWindows) {
65+
// On Windows, PowerShell uses raw exit codes; signal information is not available via os.constants.signals.
66+
return output.signal !== undefined ? `${output.signal}` : "unknown"
67+
}
6168
const signal = output.signal === undefined ? undefined : os.constants.signals[output.signal as NodeJS.Signals]
6269
return signal === undefined ? "unknown" : `${128 + signal} (${output.signal})`
6370
}

‎packages/core/test/config/policy.test.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -77,6 +77,10 @@ const evaluate = Effect.fn(function* (action: string, resources: string[], effec
7777
action,
7878
resources,
7979
effect,
80+
matchedRules: resources.map((resource) => ({
81+
resource,
82+
rule: { action, resource, effect: "allow" } as Permission.Rule,
83+
})),
8084
})
8185
return { effect: event.effect, message: event.message }
8286
})

‎packages/core/test/permission.test.ts‎

Lines changed: 31 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -102,13 +102,40 @@ describe("Permission", () => {
102102
Effect.gen(function* () {
103103
yield* setup([{ action: "read", resource: "*", effect: "allow" }])
104104
const service = yield* Permission.Service
105-
expect(yield* service.ask(assertion())).toEqual({ id: Permission.ID.create("per_test"), effect: "allow" })
105+
expect(yield* service.ask(assertion())).toEqual({
106+
id: Permission.ID.create("per_test"),
107+
effect: "allow",
108+
matchedRules: [
109+
{
110+
resource: "src/index.ts",
111+
rule: { action: "read", resource: "*", effect: "allow" },
112+
},
113+
],
114+
})
106115
expect(yield* service.list()).toEqual([])
107116
yield* setRules([{ action: "read", resource: "*", effect: "deny" }])
108-
expect(yield* service.ask(assertion())).toEqual({ id: Permission.ID.create("per_test"), effect: "deny" })
117+
expect(yield* service.ask(assertion())).toEqual({
118+
id: Permission.ID.create("per_test"),
119+
effect: "deny",
120+
matchedRules: [
121+
{
122+
resource: "src/index.ts",
123+
rule: { action: "read", resource: "*", effect: "deny" },
124+
},
125+
],
126+
})
109127
expect(yield* service.list()).toEqual([])
110128
yield* setRules([])
111-
expect(yield* service.ask(assertion())).toEqual({ id: Permission.ID.create("per_test"), effect: "ask" })
129+
expect(yield* service.ask(assertion())).toEqual({
130+
id: Permission.ID.create("per_test"),
131+
effect: "ask",
132+
matchedRules: [
133+
{
134+
resource: "src/index.ts",
135+
rule: { action: "read", resource: "*", effect: "ask" },
136+
},
137+
],
138+
})
112139
expect(yield* service.get(Permission.ID.create("per_test"))).toBeDefined()
113140
}),
114141
)
@@ -124,7 +151,7 @@ describe("Permission", () => {
124151
)
125152
const service = yield* Permission.Service
126153

127-
expect(yield* service.ask(assertion())).toMatchObject({ effect: "allow" })
154+
expect(yield* service.ask(assertion())).toMatchObject({ effect: "allow", matchedRules: [{ resource: "src/index.ts", rule: { action: "*", resource: "*", effect: "allow" } }] })
128155
expect(yield* service.ask(assertion({ agent: Agent.ID.make("reviewer") }))).toMatchObject({ effect: "deny" })
129156
yield* agents.transform((editor) =>
130157
editor.update(Agent.ID.make("reviewer"), (agent) => {

‎packages/core/test/plugin/provider-opencode.test.ts‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@ import { OpencodePlugin } from "@opencode/core/plugin/provider/opencode"
2828
import { Provider } from "@opencode/core/provider"
2929
import { Session } from "@opencode/core/session"
3030
import { Skill } from "@opencode/core/skill"
31+
import { Permission } from "@opencode/core/permission"
3132
import { WebSearch } from "@opencode/core/websearch"
3233
import { withEnv } from "../fixture/env"
3334
import { drain } from "../lib/clock"
@@ -2183,6 +2184,10 @@ describe("OpencodePlugin with a Console config", () => {
21832184
action: "shell",
21842185
resources: ["ls"],
21852186
effect: "allow",
2187+
matchedRules: ["ls"].map((resource) => ({
2188+
resource,
2189+
rule: { action: "shell", resource, effect: "allow" } as Permission.Rule,
2190+
})),
21862191
}),
21872192
).toMatchObject({ effect: "deny", message: "Blocked by Acme's policy" })
21882193
}),

‎packages/plugin/src/effect/permission.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,8 @@ export interface PermissionEvaluation {
1616
readonly source?: Permission.Source
1717
effect: Permission.Effect
1818
message?: string
19+
/** Structured rule attribution: the winning rule matched per resource during evaluation. */
20+
readonly matchedRules: ReadonlyArray<{ readonly resource: string; readonly rule: Permission.Rule }>
1921
}
2022

2123
export interface PermissionHooks {

‎packages/protocol/src/groups/permission.ts‎

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -97,7 +97,20 @@ export const makePermissionGroup = <
9797
agent: Agent.ID.pipe(Schema.optional),
9898
}),
9999
success: Schema.Struct({
100-
data: Schema.Struct({ id: Permission.ID, effect: Permission.Effect }),
100+
data: Schema.Struct({
101+
id: Permission.ID,
102+
effect: Permission.Effect,
103+
matchedRules: Schema.Array(
104+
Schema.Struct({
105+
resource: Schema.String,
106+
rule: Schema.Struct({
107+
action: Schema.String,
108+
resource: Schema.String,
109+
effect: Permission.Effect,
110+
}),
111+
}),
112+
),
113+
}),
101114
}),
102115
error: SessionNotFoundError,
103116
})

0 commit comments

Comments
 (0)