Per-session/per-worktree external_directory permission scoping #46372

Context

Investigation from medialib-dev #298 confirmed that opencode has no per-session or per-instance scoping of permission.external_directory. The external_directory rules in opencode.json are merged into every agent at startup. When a subagent is spawned, it receives Permission.merge(agent.permission, session.permission) — both carry the same top-level external_directory rules. There is no mechanism to scope a rule to "this session's worktree only."

Concrete scenario: A user runs multiple parallel sessions, each rooted in a different git worktree under a shared parent directory (e.g. ~/dev/MyProject/worktrees/issue-1/, ~/dev/MyProject/worktrees/issue-2/). A wildcard like ~/dev/MyProject/worktrees/*: allow is necessary for sessions to write outside the repo root, but it grants every session and subagent write access to every sibling worktree. There is no permission-layer isolation between parallel sessions.

Evidence from source:

• packages/opencode/src/permission/index.ts — Permission.merge is a flat merge; no session-context awareness
• packages/opencode/src/session/prompt.ts — handleSubtask passes merged permissions to child sessions with no sandboxing
• packages/opencode/src/subagent-permissions.ts — subagents inherit parent's external_directory + deny rules (no per-subagent config)
• Config is loaded once at startup (instance-context.ts) and not hot-reloaded

Related upstream work:

• Subagent loses inherited external_directory allow when spawned via task tool #30527 (fixed) — subagent losing inherited external_directory allow (different bug, same code path)
• [FEATURE]: Per-agent isolation: worktree config field for automatic subagent worktree provisioning #34216 (closed/not-planned) — per-agent worktree isolation via isolation: worktree config (auto-provisions worktrees for subagents, complementary but not addressing permission scoping)
• Feature request: subagent worktree isolation (isolation: worktree) #34872 (closed/not-planned) — same concept as [FEATURE]: Per-agent isolation: worktree config field for automatic subagent worktree provisioning #34216, different proposal shape

Scope

In scope:

• Add a mechanism to scope external_directory allow rules to a specific session or worktree
• Two proposed shapes (either would work):
  1. session_scoped: true flag on individual permission rules — when set, the rule only applies to the session that defined it, not inherited by child sessions
  2. ctx.worktree-aware resolve — the resolver automatically scopes external_directory checks to the session's working directory (if session-rooted, only its own worktree is reachable)
• Update Permission.merge to respect session scoping during subagent spawn
• Tests for the new scoping behavior

Out of scope:

• Automatic worktree provisioning for subagents ([FEATURE]: Per-agent isolation: worktree config field for automatic subagent worktree provisioning #34216 covers that)
• Changes to the config hot-reload mechanism
• Changes to the Worktree.Service API
• Breaking changes to existing external_directory rule semantics (opt-in only)

Constraints:

• Must be backward-compatible: existing configs without session_scoped must behave identically to today
• No new dependencies
• Must work with the existing Permission.merge contract when the flag is absent

Acceptance Criteria

• A permission rule with session_scoped: true is NOT inherited by subagents spawned from that session
• A permission rule without session_scoped (or with session_scoped: false) continues to be inherited by subagents (backward-compatible)
• Session-scoped rules resolve correctly when the session is rooted in a worktree (i.e., only that worktree's path is allowed)
• Existing tests pass with no regressions (pnpm run check + pnpm test)
• New tests cover: session-scoped rule inheritance, non-scoped rule inheritance (regression), and worktree-rooted session resolution

Story Points

Estimate: 3 points

Weighted score: 2.65 → mapped to 3 points (Fibonacci)

Calibration: No comparable issues with known Story Points found in this repo. Estimated based on the STORY-POINTS.md calibration: similar to "Add a small API endpoint following an existing architecture" (3 points) — multiple implementation steps but well-understood code paths.

Rationale: Three distinct code locations need changes (permission/index.ts, session/prompt.ts, subagent-permissions.ts) but each is a small, localized modification. Uncertainty around the preferred design shape (flag vs. auto-scoping) adds modest complexity. Testing is straightforward since the permission merge paths are well-exercised.

Decomposition: not required