Skip to content

feat(isolation)!: restrict a Run's Units to allowed skills, subagents and MCP servers - #38

Merged
syn7xx merged 1 commit into
mainfrom
feat/isolation-clean
Nov 20, 2026
Merged

syn7xx merged 1 commit into
mainfrom
feat/isolation-clean

Conversation

@syn7xx

@syn7xx syn7xx commented Nov 20, 2026 •

Copy link
Copy Markdown
Owner

Why

A Workflow runs in whatever OpenCode environment the machine has — locally installed skills, subagents and MCP
servers included. That makes results unpredictable. meta.isolation bounds what a Workflow's Units may use:
deny-by-default on three independent axes.

export default defineWorkflow({
  meta: {
    name: "audit",
    description: "Read-only audit",
    isolation: { skills: ["code-markup"], subagents: ["explore"], mcp: ["playwright"] },
  },
  async run({ agent }) { await agent("audit", { subagent: "explore" }) },
})

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 *, then allow per name, appended
last (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
context hook — the model never sees them; (2) a direct call is denied by name in permission evaluate, before any
ask decision, so a saved "Allow always" cannot get through. A tool name <server>_<tool> resolves to its server by
the longest known prefix (server names may contain _).

Levels intersect (narrow-only):

Level Where Role
Workflow meta.isolation the author's contract
Unit agent(prompt, { isolation }) this one Unit tightens further
Caller workflow({ isolation }) an ad-hoc bound for the caller

effective = meta ∩ unit ∩ caller. No level can widen another. intersectIsolation is a pure function, tested.

permissions stays separate. meta.permissions / agent(..., { permissions }) remain the raw, ordered escape
hatch for tools the allow-list does not name (shell, edits, reads). The two compose: permissions first, then the
engine 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.json and import it into the
Workflow — the bundler inlines the JSON.

import manifest from "./workflows.json"
// meta: { …, isolation: manifest.workflows.audit.isolation }

withIsolation(ctx, policy) is sugar over a Unit's isolation for a region where many Units share a tighter
policy. It is explicitly not a security boundary: parallel/pipeline thunks close over ctx, so a thunk that
calls the original ctx.agent bypasses the view. Use the Unit isolation option when a Unit must be provably
narrowed.

Breaking changes

  • The Unit option restrict is renamed to isolation.
  • agent(prompt, { isolation: "worktree" }) becomes agent(prompt, { worktree: true }) — one meaning per name
    instead of an overloaded isolation.

Migration:

-await agent("review", { subagent: "explore", restrict: { mcp: [] } })
+await agent("review", { subagent: "explore", isolation: { mcp: [] } })
-await agent("migrate", { isolation: "worktree" })
+await agent("migrate", { worktree: true })

meta.isolation is 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)
  • New tests: isolation.test.ts (rule emission and order, intersection, fail-fast, continuation, MCP resolution and
    hiding) 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, and packages/plugin/README.md regenerated.


Companion change in the configurator (the isolation field in the workflow manifest, hand-written):
openconfigurer commits 47751b3, 30f7ce2, 5a28e96.

@syn7xx
syn7xx force-pushed the feat/isolation-clean branch from e6535fe to fd579d0 Compare November 20, 2026 08:56
@syn7xx syn7xx changed the title feat(isolation): изоляция Unit'ов по скиллам, субагентам и MCP feat(isolation): restrict a Run's Units to allowed skills, subagents and MCP servers Nov 20, 2026
… 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
syn7xx force-pushed the feat/isolation-clean branch from fd579d0 to 9612a29 Compare November 20, 2026 09:14
@syn7xx syn7xx changed the title feat(isolation): restrict a Run's Units to allowed skills, subagents and MCP servers feat(isolation)!: restrict a Run's Units to allowed skills, subagents and MCP servers Nov 20, 2026
@syn7xx
syn7xx merged commit 32a8a10 into main Nov 20, 2026
4 checks passed
@syn7xx
syn7xx deleted the feat/isolation-clean branch November 20, 2026 09:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant