Repository navigation
feat(isolation)!: restrict a Run's Units to allowed skills, subagents and MCP servers - #38
Merged
Merged
Conversation
syn7xx
force-pushed
the
feat/isolation-clean
branch
from
November 20, 2026 08:56
e6535fe to
fd579d0
Compare
… and MCP servers
`meta.isolation` is a deny-by-default allow-list on three independent axes:
skills, subagents, and MCP servers. Skill and subagent rules are appended LAST
to the Unit session's ruleset (last match wins), so isolation can only narrow
what the surrounding config allows. MCP isolation is two-layered: the excluded
servers' tools are hidden from the Unit's toolset (context hook) and denied by
name (permission hook), before any `ask` decision.
Levels intersect (narrow-only): a Workflow's policy ∩ a Unit's policy ∩ the
caller's override. A policy can live in a JSON file and be imported into the
Workflow — the plugin reads no files itself, the bundler inlines the import.
`meta.permissions` stays a separate, raw escape hatch for tools the allow-list
does not name (shell, edits, reads); the two compose, they do not merge.
- isolation.ts: intersectIsolation, isolationRules, subagentAllowed,
mcpServersToHide / mcpToolServer / isHiddenMcpTool
- withIsolation(ctx, policy) — sugar over a Unit's isolation, not a security
boundary (parallel/pipeline thunks close over ctx and can bypass the view)
- fail-fast: a Unit naming a subagent outside the allow-list fails before its
session is created
- README and the dynamic-workflows skill: an "Isolating a Run" section
BREAKING CHANGE: the Unit option `restrict` is renamed to `isolation`, and
`agent(prompt, { isolation: "worktree" })` becomes `agent(prompt, { worktree:
true })`. Existing Workflows using either form must be updated; `meta.isolation`
is new and opt-in.
syn7xx
force-pushed
the
feat/isolation-clean
branch
from
November 20, 2026 09:14
fd579d0 to
9612a29
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
A Workflow runs in whatever OpenCode environment the machine has — locally installed skills, subagents and MCP
servers included. That makes results unpredictable.
meta.isolationbounds what a Workflow's Units may use:deny-by-default on three independent axes.
Each axis is independent: omit a field to leave that axis unrestricted;
[]allows nothing.How it works
Skills and subagents become permission rules on the Unit session:
deny *, thenallowper name, appendedlast (OpenCode's last-match-wins, so isolation can only narrow). A Unit naming a subagent outside the allow-list
fails before its session is created, with a clear message.
MCP is enforced in two layers: (1) the excluded servers' tools are removed from the Unit's toolset in the
contexthook — the model never sees them; (2) a direct call is denied by name inpermission evaluate, before anyaskdecision, so a saved "Allow always" cannot get through. A tool name<server>_<tool>resolves to its server bythe longest known prefix (server names may contain
_).Levels intersect (narrow-only):
meta.isolationagent(prompt, { isolation })workflow({ isolation })effective = meta ∩ unit ∩ caller. No level can widen another.intersectIsolationis a pure function, tested.permissionsstays separate.meta.permissions/agent(..., { permissions })remain the raw, ordered escapehatch for tools the allow-list does not name (shell, edits, reads). The two compose:
permissionsfirst, then theengine rules, then the isolation rules. They are deliberately not merged — arbitrary rules and a curated allow-list
are different concepts.
Policy in JSON. The plugin reads no files itself: keep the policy in
workflows.jsonand import it into theWorkflow — the bundler inlines the JSON.
withIsolation(ctx, policy)is sugar over a Unit'sisolationfor a region where many Units share a tighterpolicy. It is explicitly not a security boundary:
parallel/pipelinethunks close overctx, so a thunk thatcalls the original
ctx.agentbypasses the view. Use the Unitisolationoption when a Unit must be provablynarrowed.
Breaking changes
restrictis renamed toisolation.agent(prompt, { isolation: "worktree" })becomesagent(prompt, { worktree: true })— one meaning per nameinstead of an overloaded
isolation.Migration:
meta.isolationis new and opt-in; nothing changes for a Workflow that does not declare it.Verification
bun run check: 459 pass, 0 fail (format, lint, types, tests, 18 protocol schemas)isolation.test.ts(rule emission and order, intersection, fail-fast, continuation, MCP resolution andhiding) and service tests covering a real JSON import in the Workflow and that a caller cannot widen the policy
Documentation
README.md("Isolating a Run", agent options,worktrees()),packages/plugin/skill/dynamic-workflows/SKILL.md(authoring rules and the live example),
docs/development.md, andpackages/plugin/README.mdregenerated.Companion change in the configurator (the
isolationfield in the workflow manifest, hand-written):openconfigurercommits47751b3,30f7ce2,5a28e96.