@fro.bot/systematic 3.32.2 → 3.33.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/HARNESSES.md CHANGED
@@ -29,7 +29,7 @@ The citations above (OC-1 to OC-8) describe the v1 adapter. The v2 adapter is th
29
29
 
30
30
  ## OpenCode v2 — Tier 1 shipped adapter
31
31
 
32
- One package serves both OpenCode lines. v1 (1.18.29 and later) reads the `plugin` key and calls `server`; v2 (2.2.5 and later) reads `plugins` and calls `setup(ctx)`. Versions below those floors are unsupported, with no shim. Both floors are held in `scripts/opencode-host-pins.json` (`v1Floor`, `v2Floor`), and the `@opencode-ai/plugin` and `@opencode/plugin` peer ranges start at them. The v2 floor is 2.2.5, the version CI runs; no CI job runs an older v2 release, and the `execute.before` hook that the `ce:connect` tool guard relies on has only been observed there.
32
+ One package serves both OpenCode lines. v1 (1.18.29 and later) reads the `plugin` key and calls `server`; v2 (2.2.5 and later) reads `plugins` and calls `setup(ctx)`. Versions below those floors are unsupported, with no shim. Both floors are held in `scripts/opencode-host-pins.json` (`v1Floor`, `v2Floor`), and the `@opencode-ai/plugin` and `@opencode/plugin` peer ranges start at them. CI runs the v2 pin, not the floor; no CI job runs a v2 release older than the floor, and the `execute.before` hook that the `ce:connect` tool guard relies on has been observed only on the floor and later pins.
33
33
 
34
34
  History of the earlier v2 floor: the first v2 floor was 2.2.0, chosen on 2026-10-27 as a support decision rather than a loader limit. The loader probe found that 1.18.28 and v2 2.1.4 load the object default exactly as the floor versions do, and that v2 2.1.4 silently drops a function default while 2.2.0 logs a warning [OC2-LOADER]. 2.2.0 was then the oldest v2 release the adapter was tested on; whether earlier releases provide every API it uses was not probed. The floor moved to 2.2.5 because that is the only v2 release CI runs.
35
35
 
@@ -37,7 +37,7 @@ Each v2 mechanism was chosen by a probe against OpenCode 2.2.0 on 2026-10-27. Th
37
37
 
38
38
  | Probe | Outcome | Mechanism the adapter uses | Evidence |
39
39
  |---|---|---|---|
40
- | Agent creation | Passed | `ctx.agent.transform` with `editor.update(id, fn)` creates a missing agent from a default skeleton. Unknown fields are stripped, so there is no ownership marker; user config applies after every plugin transform and overlays a same-named agent | [OC2-AGENT] |
40
+ | Agent creation | Passed | `ctx.agent.transform` with `editor.update(id, fn)` creates a missing agent from a default skeleton. Unknown fields are stripped, so there is no ownership marker; user config applies after every plugin transform and overlays a same-named agent. `editor.get` returns the live record of an agent an earlier transform defined, `update` mutates it in place and `remove` deletes it; a transform replay starts from an empty state, so a transform never sees its own earlier output. For a read-only agent another plugin defined, the adapter removes the entry and creates it again from the plan, keeping only that entry's `model` | [OC2-AGENT] |
41
41
  | Instruction entries | Passed, with a different trigger | One keyed entry (`systematic.bootstrap`) per session, put from `ctx.session.hook('prompt')`. `session.created` is not used, because the first session after a service start never sees it | [OC2-INSTR] |
42
42
  | Per-kind request hooks | Not needed | The `context` hook is used only to restore truncated skill output; the bootstrap does not use it | [OC2-CTX] |
43
43
  | Permissions | Passed | Ordered `{action, resource, effect}` lists, last match wins; `bash` becomes `shell`, `task` becomes `subagent`, `doom_loop` and `lsp` have no v2 action; a session-level allow overrides an agent's own deny, so see the CN-2 and CN-3 entries for the tool guard | [OC2-PERM] |
@@ -46,7 +46,7 @@ Each v2 mechanism was chosen by a probe against OpenCode 2.2.0 on 2026-10-27. Th
46
46
  | Output truncation | Truncates | The host cuts tool output at 2000 lines or 51200 bytes after the plugin's `execute.after` hook sees the full text. The full text is kept by call id and put back in the `context` hook; nothing depends on the marker text | [OC2-TRUNC] |
47
47
  | Commands | Passed, with constraints | `ctx.command.transform`; a plugin command receives only the typed text and does its own expansion; routing is not offered to plugin commands, so a bundled command that declares `agent`, `model` or `subtask` is refused, while a discovered skill's fields are dropped with a note; a name that matches a built-in replaces it | [OC2-CMD] |
48
48
  | Apply order | Documented | Plugin transforms run first, then user config and discovered sources; `reload()` replays transforms on a fresh editor and does not re-run `setup` | [OC2-ORDER] |
49
- | Error handling | Documented | A rejected `setup` leaves the plugin unloaded and the host running; a throwing transform disables the whole plugin; a throwing hook breaks the turn. Every callback is guarded, except the read-only tool guard, whose installer runs outside the never-throw wrapper so a failed registration holds its agents back and whose hook throws on purpose, and invalid config rejects `setup` as it throws on v1 | [OC2-ERR] |
49
+ | Error handling | Documented | A rejected `setup` leaves the plugin unloaded and the host running; a throwing transform disables the whole plugin; a throwing hook breaks the turn. Ordinary installers and the callbacks they register are guarded and never throw. The read-only tool guard is the exception and fails closed: its installer runs first and outside the never-throw wrapper, so a failed registration reports once and withholds its agents, and its hook throws on purpose. Invalid config rejects `setup` as it throws on v1 | [OC2-ERR] |
50
50
  | Project directory | Documented | `ctx.location.directory` is the project directory (the service's working directory is not); each location gets a fresh module instance and its own `setup` | [OC2-TRUST] |
51
51
  | Task tracking tool | Conditional, unobserved | Binary strings name a `todowrite` tool behind the experimental `todo` option; no live request showed it | [OC2-TODO] |
52
52
 
@@ -98,7 +98,7 @@ Systematic ships its own search over four kinds of durable output: `docs/solutio
98
98
 
99
99
  Evidence tiers differ by host, and this file does not claim more than the tests do:
100
100
  - **Host-free contract evidence:** one parity test drives each adapter's real entry over one fixture corpus and compares the rendered text; a second runs the built bin under real Node from a directory with no `node_modules` [SR-1].
101
- - **Real-host tests:** OpenCode v1 on the floor (1.18.29) and current (1.19.4) lanes, and OpenCode v2 (the pinned 2.2.5), each call the tool through a real host [SR-2]. CI runs them in the host-contract jobs.
101
+ - **Real-host tests:** OpenCode v1 on the floor (1.18.29) and current lanes, and OpenCode v2 at the pinned version, each call the tool through a real host [SR-2]. CI runs them in the host-contract jobs.
102
102
  - **Delegated-reach tests:** on OpenCode v1 (floor and current), OpenCode v2 and Pi, a dispatched learnings-researcher child calls `systematic_search` and its result reaches the parent. The child's next model request must carry a tool message that starts `Search "` and names both planted documents, and the parent's final request must carry both paths [SR-5]. These prove reach and plumbing. A scripted model makes the call, so they do not show that a live model chooses to search.
103
103
  - **External search, host-free:** one parity test drives v1, v2, Pi, the CLI, the bin in process and the built bin under Node over one fixture project with a project source and a user source, and compares the rendered `external` text byte for byte. It also covers the not-allowed reply, an allow-list edit between two calls with nothing restarted, and `search.enabled: false` [SR-6].
104
104
  - **External search, delegated:** on OpenCode v2 only, a dispatched learnings-researcher child searches `kind: external` and the planted external path reaches the parent's final answer, with a negative control that withholds the allow entry [SR-6]. Delegated external proofs on OpenCode v1, Pi and Claude Code have not been run, and a scripted model makes the call, so this shows reach and plumbing, not that a live model chooses `external`. The researcher's side of the call is pinned by the wiring contract test [SR-6].
@@ -108,12 +108,12 @@ Evidence tiers differ by host, and this file does not claim more than the tests
108
108
 
109
109
  The `ce:connect` skill dispatches `connections-researcher`, an agent that must not run shell commands, write, edit or fetch. Each host enforces that differently, so a host and version counts as supported only after a deny was observed on that host: the shipped researcher is dispatched, a scripted model calls shell, write, edit and web fetch, each is refused, a read succeeds and reaches the parent, and the planted marker file is never written. A negative control removes the limits and the proof fails under its own name. The supported pairs are in `HOST_SUPPORT_TABLE` in `src/lib/connect-config.ts`; each row names the test that observed it in `observedBy`. A definition test is a regression pin and is never counted as proof.
110
110
 
111
- | Host | Version | Mechanism | Support evidence |
112
- |---|---|---|---|
113
- | OpenCode v1 | 1.19.5 | `permission:` denies `bash`, `edit`, `webfetch`, `websearch` and `task`, plus `external_directory: allow` so a headless run can read allowed projects outside the working directory. A string `tools:` is dropped by the host's converter and is not relied on. | Observed [CN-1] |
114
- | OpenCode v2 | 2.2.5 | The same denies, plus Systematic's `execute.before` tool guard, which refuses every call from `connections-researcher` outside `read`, `grep`, `glob`, `skill`, `systematic_search` and `systematic_skill`, direct or from inside Code Mode. A session-level allow overrides an agent's own deny on v2, so the guard does the enforcing. | Observed [CN-2][CN-3] |
115
- | Pi | 1.5.0 | The agent's `tools: Read, Grep, Glob` reach the delegate session as read, grep and find. The agent is not one of the curated pi-subagents personas, which carry no tool allowlist. | Observed [CN-4] |
116
- | Claude Code | 2.1.319 | The agent declares `tools: Read, Grep, Glob` and `disallowedTools`. The positive `tools` allowlist is what the host enforced in the manual run: the session's tools were Read, Grep and Glob. Upstream reports describe `disallowedTools` not being enforced for plugin subagents, so the allowlist leads. | Observed once, by hand, with a live model [CN-5]. Any other version is unlisted: headless mode refuses it and interactive mode warns and asks consent. |
111
+ | Host | Mechanism | Support evidence |
112
+ |---|---|---|
113
+ | OpenCode v1 | `permission:` denies `bash`, `edit`, `webfetch`, `websearch` and `task`, plus `external_directory: allow` so a headless run can read allowed projects outside the working directory. Another config entry of the same agent name keeps only its `model` and `variant`; the denies and prompt are Systematic's. A string `tools:` is dropped by the host's converter and is not relied on. | Observed [CN-1] |
114
+ | OpenCode v2 | The same denies, plus Systematic's `execute.before` tool guard, which refuses every call from `connections-researcher` outside `read`, `grep`, `glob`, `skill`, `systematic_search` and `systematic_skill`, direct or from inside Code Mode. A session-level allow overrides an agent's own deny on v2, so the guard does the enforcing. Another plugin's definition of the same agent name is replaced by Systematic's, keeping only its `model`; a definition in the user's own config applies after the plugin transforms and is not replaced. | Observed [CN-2][CN-3] |
115
+ | Pi | The agent's `tools: Read, Grep, Glob` reach the delegate session as read, grep and find. The agent is not one of the curated pi-subagents personas, which carry no tool allowlist. | Observed [CN-4] |
116
+ | Claude Code | The agent declares `tools: Read, Grep, Glob` and `disallowedTools`. The positive `tools` allowlist is what the host enforced in the manual run: the session's tools were Read, Grep and Glob. Upstream reports describe `disallowedTools` not being enforced for plugin subagents, so the allowlist leads. | Observed once, by hand, with a live model [CN-5]. Any other version is unlisted: headless mode refuses it and interactive mode warns and asks consent. |
117
117
 
118
118
  What the evidence does not show: a scripted model makes the calls, so these proofs show enforcement plumbing, not live model choice. Read tools are not path-scoped on any host and session MCP tools are not denied; the guide documents both as limits. The v1 floor (1.18.29) has no row and is not run against this proof.
119
119
 
@@ -232,13 +232,13 @@ Migrated-skill discipline is enforced by the [content-integrity gate](scripts/co
232
232
  - **OC-3** — cloned OpenCode source, `.slim/clonedeps/repos/anomalyco__opencode/packages/core/src/tool/todowrite.ts:1-10`.
233
233
  - **OC-4** — `src/lib/asset-plan.ts:223-234` (`loadSkillAsCommand`), `:532-551` (bundled skills as `systematic:<name>` commands), `:553-618` (discovered skills as commands); `src/lib/config-handler.ts:367-377` (`registerSkillsPaths`, the v1 skill path); `src/lib/config-handler.ts:188-274` (the v1 config hook that writes the plan into the host config); `src/lib/config-handler.ts:112-170` (`foldPermissionRulesToV1Map`, which writes each managed skill allow under both the bare and the `systematic:` name unless the user wrote a rule for the prefixed name, because v1's native `skill` tool asks with the bare name and `systematic_skill` with the prefixed one); `src/lib/config-handler.ts:276-360` (`denyDisabledSkills`, the top-level `permission.skill` deny in both name forms for each disabled skill, because the registered skills folder is not filtered). Real v1 host, 1.19.4: `tests/integration/opencode-v1.test.ts` (a managed `skills` list loads through `systematic_skill`; the native `skill` tool refuses a disabled skill).
234
234
  - **OC-5** — `src/lib/skill-tool.ts:146-230` (`createSkillTool`, the v1 tool with the `context.ask` permission check at `:198-203`).
235
- - **OC-6** — `ARCHITECTURE.md:217-223` (invariant 2) and `agents/`.
235
+ - **OC-6** — `ARCHITECTURE.md:255-261` (invariant 2) and `agents/`.
236
236
  - **OC-7** — `src/lib/asset-plan.ts:274-380` (a model reaches an agent only through `applyAgentOverlays`, `applyAgentOverlayPass` and `applyRoutingModel`, all driven by user-owned overlays); `tests/unit/config-handler.test.ts:1173-1330` (overlay model emitted, `model: null` restores inheritance, native same-name replacement stays model-free).
237
237
  - **OC-8** — `src/lib/opencode-v1.ts:73-79` (v1: the loaded config and `composeBootstrapContent`; the rule is always supplied and the gate lives in `getBootstrapContent`); `src/lib/bootstrap.ts:144-160` (`readWorktreePlacementRule`), `:244-253` (`bootstrap.enabled` and `bootstrap.file` return before the rule is composed), `:265-269` (the rule is omitted when `disabled_skills` contains `git-worktree`), `:279` (placement after the usage template and before the profile), `:291-314` (`composeBootstrapContent`, shared by v1 and v2); `tests/unit/bootstrap.test.ts:1025-1227` (real `loadConfig`: default, `git-worktree` disabled, another skill disabled, qualified name rejected, `bootstrap.enabled: false`, existing and missing `bootstrap.file`); `tests/unit/plugin.test.ts:1473-1610` (real v1 plugin init).
238
238
  - **OC2-PROFILE** — [OpenCode v2 profile](skills/using-systematic/references/opencode-v2-profile.md#L5-L11). Tool names and arguments: Local probe, OpenCode 2.2.0, 2026-10-27, from the tool list of a real request (`edit`, `glob`, `grep`, `question`, `read`, `shell`, `skill`, `subagent`, `webfetch`, `websearch`, `write`, `execute`): `subagent` takes `agent`, `description`, `prompt`, `model`, `sessionID` and `background`; `question` takes `questions` with `question`, `header`, `options` and `multiple`. CI covers the `subagent` call: CI job `Host Contract v2 shard N/4` (the pinned v2 CLI), `tests/integration/opencode-v2.test.ts` › "a subagent request carries the bootstrap once, and so does the parent request that follows it". `question` has no CI test.
239
239
  - **OC2-LOADER** — OpenCode v1 1.18.28, 1.18.29, 1.19.4 and v2 2.1.4, 2.2.0, 2026-10-27. The object default `{id, setup, server}` loads on all five. A v1 host calls `server(input)` and then `setup(ctx)` in the same process, with a reduced context of 9 keys and no `location` or `session`; a v2 host never calls `server`. v2 2.1.4 drops a function default with no log line, and 2.2.0 logs a warning. Tarball config forms fail on v1, so installs go through `npm install <tarball>` and load the installed directory. Local probe for the version comparison. CI covers the load: CI job `Host Contract v2 shard N/4` (the pinned v2 CLI), `tests/integration/opencode-v2.test.ts` › "the packed plugin loads, setup runs once and stderr carries nothing unexpected"; the v1 loads: CI jobs `Host Contract v1 floor` and `Host Contract v1 current`, `tests/integration/opencode-v1.test.ts` › "packaged plugin loads, warns on a removed disabled_skills name, and exposes a compliant catalog"; the bridge no-op: `tests/unit/opencode-v2.test.ts` › "default export wiring" › "setup does nothing for the reduced context a v1 host passes".
240
240
  - **OC2-HOST** — Local probe, OpenCode 2.2.0, 2026-10-27. Isolation takes `HOME`, the four `XDG_*` variables, `OPENCODE_CONFIG_DIR` and `TMPDIR`; a managed config under `/Library` on macOS is read and cannot be isolated. One-shot runs use `run --standalone`; the default `run` starts a detached shared service on port 49374. The remote client is `@opencode/client` (`OpenCode.make`), not `@opencode/sdk`, which has only the embedded `create`. The plugin runs in the service process under a compiled Bun 1.4.4, with the home directory as its working directory. The CLI install needs `npm install --dangerously-allow-all-scripts` on npm 12. CI uses this recipe: the host install step and `tests/integration/fixtures/opencode-host.ts` in CI job `Host Contract v2 shard N/4` (the pinned v2 CLI).
241
- - **OC2-AGENT** — CI job `Host Contract v2 shard N/4` (the pinned v2 CLI): `tests/integration/opencode-v2.test.ts` › "the bundled agents appear in the agent list with their v1 description and prompt" and "a user agent with the same id in config keeps the user system prompt"; `tests/unit/opencode-v2.test.ts` › "agents installer" › "replaying the transform on a fresh editor yields the same single agent set". Local probe, OpenCode 2.2.0, 2026-10-27: an extra property set in a transform is visible to later plugins in the same replay and gone from `agent.list`, so no ownership marker survives; an agent's `model` applies only when the session names no model; a session whose agent is later unregistered fails its next turn with `Session.AgentNotFoundError`.
241
+ - **OC2-AGENT** — CI job `Host Contract v2 shard N/4` (the pinned v2 CLI): `tests/integration/opencode-v2.test.ts` › "the bundled agents appear in the agent list with their v1 description and prompt" and "a user agent with the same id in config keeps the user system prompt"; `tests/unit/opencode-v2.test.ts` › "agents installer" › "replaying the transform on a fresh editor yields the same single agent set"; `tests/unit/opencode-v2.test.ts` › "a read-only agent another plugin already defined" and `tests/integration/opencode-v2.test.ts` › "a researcher an earlier plugin defined with no denies is replaced by the shipped one: Systematic prompt, shell and write refused". Local probe, OpenCode 2.2.0, 2026-10-27: an extra property set in a transform is visible to later plugins in the same replay and gone from `agent.list`, so no ownership marker survives; an agent's `model` applies only when the session names no model; a session whose agent is later unregistered fails its next turn with `Session.AgentNotFoundError`.
242
242
  - **OC2-INSTR** — CI job `Host Contract v2 shard N/4` (the pinned v2 CLI): `tests/integration/opencode-v2.test.ts` › "the first request of a new session carries the bootstrap with the v2 profile, once", "the title request does not carry the bootstrap", "a subagent request carries the bootstrap once, and so does the parent request that follows it", "a second turn does not duplicate the bootstrap or announce a change", "git-worktree in disabled_skills leaves the worktree rule out of the bootstrap" and "bootstrap.enabled false puts no entry and nothing reaches the model". Local probe, OpenCode 2.2.0, 2026-10-27: the entry lands in the first system message as `<context key="...">`; compaction and later requests carry it once; entries persist across a host restart, even with the plugin removed; a changed value freezes the system block at the old text and adds a `<system-update>` message; a value is capped at 256 KiB; a `session.created` subscription misses the first session after a service start, so the `prompt` hook is the trigger. The composed bootstrap is about 9.2 KB.
243
243
  - **OC2-CTX** — Local probe, OpenCode 2.2.0, 2026-10-27. Per-kind hooks `prompt`, `title`, `context`, `compaction` and `generate`; pushing to `event.system` in a hook reaches the model once per request. Not used for the bootstrap. The `context` hook is used for skill output restoration, which CI job `Host Contract v2 shard N/4` (the pinned v2 CLI), `tests/integration/opencode-v2.test.ts` › "a skill above the host output limit reaches the model in full on the continuation request and later turns" covers.
244
244
  - **OC2-PERM** — CI job `Host Contract v2 shard N/4` (the pinned v2 CLI): `tests/integration/opencode-v2.test.ts` › "an agent with a managed skills list is refused a skill outside it, and an unmanaged agent is not" and "systematic_skill refuses a skill a managed agent may not load while a sibling agent loads it"; `tests/unit/opencode-v2-permissions.test.ts` (the v1 golden corpus replayed through the translator, including the integer-like skill names that v1 hoists and v2 keeps in order). Local probe, OpenCode 2.2.0, 2026-10-27: last match wins, `*` and `?` match whole values, `deny *` then one allow per skill works, any deny blocks a compound shell command, and the action names are `shell` and `subagent`. The tool asserts the bare skill id, so a rule written for `systematic:<id>` (the v1 spelling) is translated to the bare id; CI: `tests/integration/opencode-v2.test.ts` › "a skill deny written with the systematic: prefix refuses the skill, as it does on v1".
@@ -298,6 +298,6 @@ Migrated-skill discipline is enforced by the [content-integrity gate](scripts/co
298
298
  - **SR-6** — External search reach (`kind: "external"`). Code: `src/lib/search-external-sources.ts` (the per-call reader every surface shares), `src/lib/search-project-identity.ts` (main-root identity from filesystem reads), `src/lib/search-external.ts` and `src/lib/search-external-deciduous.ts` (the Markdown and Deciduous loaders), `src/lib/search-user-config.ts` (the field and entry validators, the user-level and project file selection, and the 1 MB bin-safe project reader), `src/lib/search-exclude.ts` (the `exclude` pattern validators and matcher), `src/lib/search-render.ts` (the external renderer). Host-free tests: `tests/unit/search-project-identity.test.ts` (real git repositories and `git worktree add`: a worktree maps to its main root, forged and inconsistent `.git` files, a bare repository, `core.worktree` and a symlinked `.git` never resolve); `tests/unit/search-external-sources.test.ts` (resolution order, worktrees, shadowing, the 8-source cap, user and custom config directories, nothing cached between calls, the module graph); `tests/unit/search-external.test.ts` and `tests/unit/search-external-deciduous.test.ts` (records, caps, the shared read budget, states, symlinks and read-only behavior); `tests/unit/search-adapters-parity.test.ts` › \"search adapters parity: kind external\" (v1, v2, Pi, CLI, the bin in process and the built bin under Node give byte-identical text; not-allowed replies; an allow-list edit between calls; `search.enabled` false); `tests/unit/claude-code-search.test.ts` (`--kind external` in process and from a foreign directory under Node, the stderr warning for a broken project file, and a bundle that contains neither `config.ts` nor `config-schema.ts`); `tests/unit/opencode-v2-search.test.ts` › \"setupOpenCodeV2 with a project search.sources problem\" (a project file that parses never fails v2 setup, and one that cannot be parsed still does); `tests/unit/past-work-wiring-contract.test.ts` › \"the external call in past-work scope\" and the External records group (the researcher prompt side); `tests/unit/delegated-search-proof.test.ts` › \"external mode\" and `tests/helpers/delegated-search-proof.ts` (the external fixture, script and assertion). Real host: `tests/integration/opencode-v2.test.ts` › \"a dispatched learnings-researcher child searches kind external and the planted external record reaches the parent\" and its negative control \"with the allow entry absent the child receives the not-allowed reply, the parent never sees the external path and the proof names the failure\" (CI job `Host Contract v2 shard N/4`, the pinned v2 CLI, run only when `SYSTEMATIC_OPENCODE_V2_BIN` is set). Config locations, local overlays and excludes (host-free; the per-file counts are the tests in each file today, not only the ones added): `tests/unit/search-exclude.test.ts` (77 tests: pattern validation, the matcher on slash, `**` and `?` patterns, adversarial inputs, and a module that imports nothing); `tests/unit/search-user-config.test.ts` (192 tests: file selection by existence, the four user-level layers, an aliased custom directory read once, project file selection, `exclude` validation); `tests/unit/search-corpus.test.ts` › "lookupSearchRoot" and "discoverSourceFiles: excludes" (109 tests); `tests/unit/search-external.test.ts` › "loadExternalSources: excludes" (58 tests) and `tests/unit/search-external-deciduous.test.ts` › "Deciduous loader: excludes" (54 tests); `tests/unit/search-external-sources.test.ts` › "resolveExternalSources: locations, local overlays and diagnostics" and "inspectSearch" (66 tests); `tests/unit/search-adapters-parity.test.ts` › "search adapters parity: repo-root project file, local overlays and excludes" and "search adapters parity: an invalid local file" (43 tests: one fixture started in a subfolder gives byte-identical external text on v1, v2, Pi, the CLI, the bin in process and the built bin, with every layer and the excludes applied; v1 and Pi throw at init and v2 setup rejects naming an invalid local file; a project file over 1 MB fails v1, v2 and Pi while the CLI and the bin carry on); `tests/unit/config.test.ts` › "layered config files" (374 tests); `tests/unit/pi.test.ts` › "src/pi.ts config resolved from the repository root" (72 tests); `tests/unit/opencode-v2.test.ts` (44 tests: a project directory below the repository root applies the root file, the home fallback applies no project file, an invalid user.local rejects setup naming it); `tests/unit/cli.test.ts` › "cli config show: locations and search" and the `loadSearchSettingsForCli` cases (132 tests). Scope limits: a scripted model makes the call, so the real-host proof shows reach and plumbing only; it covers OpenCode v2 alone. No real-host external proof exists for OpenCode v1, Pi or Claude Code.
299
299
  - **CN-1** — OpenCode v1 1.19.5 (CI job `Host Contract v1 current`): `tests/integration/opencode-v1-isolation.test.ts` › "the shipped researcher, dispatched from the packed plugin, is refused shell, write, edit and web fetch and its read reaches the parent" (the `HOST_SUPPORT_TABLE` `observedBy` for this row); "with the deny entries removed the same script writes a file and the proof names an isolation breach" (negative control); "a blanket allow in the host's own permission block does not lift the shipped researcher's deny"; "a headless run reads a git checkout outside the project and the marker reaches the parent, with every denied tool still refused" and "without external_directory: allow the same read is auto-rejected, which pins what the entry does". The file runs on the `v1-current` profile only (`scripts/host-contract-guard.ts`, `V1_CURRENT_ONLY_FILES`). Local observation on 1.19.5: a headless run whose work file lay in the state directory was refused as an `external_directory` request, which ended the session before any final line. A host-config `permission.external_directory` allow for `<state directory>/*` let the whole pipeline run and end `Connect complete`. Scope limit: other v1 versions, including the 1.18.29 floor, are unobserved and unsupported.
300
300
  - **CN-2** — OpenCode v2 2.2.5 (CI job `Host Contract v2 shard N/4`, run only when `SYSTEMATIC_OPENCODE_V2_BIN` is set): `tests/integration/opencode-v2.test.ts` › "a session-level allow does not lift the guarded researcher when a parent with that rule dispatches it" (the `observedBy` for this row), "a session-level allow does not lift the guarded researcher when it runs directly", "the shipped researcher, dispatched from the packed plugin, is refused shell, write, edit and web fetch and its read reaches the parent", and the negative control "the shipped definition alone, under a name the guard does not know, is refused each denied tool and its read reaches the parent". Scope limit: a scripted model makes the calls.
301
- - **CN-3** — The v2 tool guard. Code: `src/lib/opencode-v2-tool-guard.ts` (`decideToolCall`, the `execute.before` registration, `READ_ONLY_AGENT_NAMES`, `READ_ONLY_TOOL_ALLOWLIST`). Tests: `tests/unit/opencode-v2-tool-guard.test.ts` (the allowlist is exactly read, grep, glob, skill and the two Systematic tools; exact-name matching; every other agent left alone; a refused call throws so the host fails that call alone; a failed hook registration is reported and never thrown into the host); `tests/integration/opencode-v2.test.ts` › "the execute.before hook sees each call with the session agent, including Code Mode calls, and a throw fails that call alone" (a plugin hook that throws fails the call without any Systematic guard in play). The reason for the guard, observed on 2.2.5: a session-level allow rule overrides an agent's own deny, and Code Mode `execute` reaches host-native `opencode_*` tools that no frontmatter key can name.
301
+ - **CN-3** — The v2 tool guard. Code: `src/lib/opencode-v2-tool-guard.ts` (`decideToolCall`, the `execute.before` registration, `READ_ONLY_AGENT_NAMES`, `READ_ONLY_TOOL_ALLOWLIST`). Tests: `tests/unit/opencode-v2-tool-guard.test.ts` (the allowlist is exactly read, grep, glob, skill and the two Systematic tools; exact-name matching; every other agent left alone; a refused call throws so the host fails that call alone; a failed hook registration rejects, so `setupOpenCodeV2` can catch it and withhold the guarded agents); `tests/integration/opencode-v2.test.ts` › "the execute.before hook sees each call with the session agent, including Code Mode calls, and a throw fails that call alone" (a plugin hook that throws fails the call without any Systematic guard in play). The reason for the guard, observed on 2.2.5: a session-level allow rule overrides an agent's own deny, and Code Mode `execute` reaches host-native `opencode_*` tools that no frontmatter key can name.
302
302
  - **CN-4** — Pi 1.5.0: `tests/unit/pi-delegate-session.test.ts` › "the shipped researcher reaches createAgentSession with read, grep and find and none of bash, write, edit or systematic_delegate" (the `observedBy` for this row; the real session builder runs against a fake runtime and the test asserts the `tools` that reach `createAgentSession`, not the mock); `tests/integration/pi.test.ts` › "a family completes inside the delegate turn cap with read, search and find tools only, and its batch validates" and "a child that never answers stops at the turn cap and the family is degraded, not empty" (the real Pi runtime, run in the v2 host-contract profile). Scope limit: the delegate is capped at 20 turns, and a scripted model drives the integration tests.
303
303
  - **CN-5** — Manual evidence, not a CI check. Recorded 2026-11-08 with Claude Code 2.1.319 (`claude --version` prints `2.1.319 (Claude Code)`), run by hand with the plugin bundle built from the rebased branch head and a live model. Verdict PASS. Run A dispatched `systematic:connections-researcher` through the `Agent` tool: the subagent reported its tools as Read, Grep and Glob, read a planted file and returned its marker, skipped Bash, Write, Edit and WebFetch as unavailable, and never called any of them (the checker found no call to Bash, Write, Edit, WebFetch, WebSearch or NotebookEdit). Run B started a session with `claude --agent systematic:connections-researcher`: the session's init message listed Read, Grep and Glob as its tools, none of Bash, Write, Edit, WebFetch, WebSearch or NotebookEdit, and no MCP tools; the read worked and its marker reached the answer. The `HOST_SUPPORT_TABLE` row names this entry as its `observedBy`. Limits: one live model on one Claude Code version; in run A the denial is the subagent's own report, because it never called the tools, and the host's own statement comes from run B's session tool list; the read tools are not path-scoped; whether a dispatched subagent can reach its parent session's MCP tools was not tested. `tests/unit/connect-host-isolation.test.ts` › "claude plugin validate accepts the definition and rejects one that does not parse" remains a parse check only, because an agent whose frontmatter fails to parse loads without its limits. Upstream issue reports 58645 and 94202 (cited from the research behind this feature, not re-checked) describe `disallowedTools` not being enforced for plugin and subagent Bash, so the agent leads with the positive `tools` allowlist.
@@ -1,6 +1,6 @@
1
1
  import { type ConnectConfigOptions, type HostSupportRow } from './lib/connect-config.js';
2
2
  import { type ConnectBounds } from './lib/connect-evidence.js';
3
- import { type ProcessTable, type PublishOptions } from './lib/connect-state.js';
3
+ import { type InvocationWriteOptions, type ProcessTable, type PublishOptions } from './lib/connect-state.js';
4
4
  /**
5
5
  * Entry point for the generated, self-contained `ce:connect` helper
6
6
  * (`skills/ce-connect/scripts/connect.mjs`).
@@ -17,7 +17,7 @@ import { type ProcessTable, type PublishOptions } from './lib/connect-state.js';
17
17
  * file the skill writes in the run's work directory, read here through the
18
18
  * bounded reader as a regular file.
19
19
  */
20
- export declare const CE_CONNECT_USAGE = "Usage: node connect.mjs <begin|validate|publish|decide|ledger show [--offset N]|ledger clear|ledger unlock>";
20
+ export declare const CE_CONNECT_USAGE = "Usage: node connect.mjs <begin|validate|publish|decide|import|apply-ticks|render-report|ledger show [--offset N]|ledger clear|ledger unlock>";
21
21
  export interface HelperDeps {
22
22
  /** Environment for `XDG_STATE_HOME`. Defaults to `process.env`. */
23
23
  readonly env?: Readonly<Record<string, string | undefined>>;
@@ -34,6 +34,8 @@ export interface HelperDeps {
34
34
  readonly inspector?: ProcessInspector;
35
35
  /** Seams in the middle of a publish, for tests of a crash or a failed write. */
36
36
  readonly publishHooks?: NonNullable<PublishOptions['hooks']>;
37
+ /** Seams in the write of the invocation record, for tests of a failed write. */
38
+ readonly invocationHooks?: InvocationWriteOptions;
37
39
  }
38
40
  export interface HelperResult {
39
41
  readonly ok: boolean;
package/dist/cli.js CHANGED
@@ -48,7 +48,7 @@ import {
48
48
  SEARCH_NOTICES,
49
49
  SEARCH_CONFIG_UNREADABLE_NOTE,
50
50
  runSearch
51
- } from "./index-nrbdgp4m.js";
51
+ } from "./index-1cj1mrpb.js";
52
52
  var __defProp = Object.defineProperty;
53
53
  var __returnValue = (v) => v;
54
54
  function __exportSetter(name, newValue) {
@@ -7621,6 +7621,8 @@ function isAllowedProject(identity, allowList, options = {}) {
7621
7621
  var MAX_ALLOW_PROJECTS = 64;
7622
7622
  var MAX_ALLOW_PROJECT_LENGTH = 4096;
7623
7623
  var MAX_CONNECT_CONFIG_BYTES = 1024 * 1024;
7624
+ var MAX_CONNECT_GROUPS = 32;
7625
+ var CONNECT_GROUP_NAME_PATTERN = /^[a-z0-9][a-z0-9-]{0,63}$/;
7624
7626
 
7625
7627
  // src/lib/removed-names.ts
7626
7628
  var REMOVED_BUNDLED_SKILL_NAMES = [
@@ -8752,11 +8754,30 @@ var ConnectSettingsSchema = trustProtected(object({
8752
8754
  allow_projects: array(string().min(1).max(MAX_ALLOW_PROJECT_LENGTH)).max(MAX_ALLOW_PROJECTS).optional().meta({
8753
8755
  description: `Main repository roots that \`ce:connect\` may read for contradictions and transferable lessons. Each entry is an absolute or \`~\`-prefixed path to the root of a repository checkout, not a subdirectory and not a linked worktree. At most ${MAX_ALLOW_PROJECTS} entries; an entry that matches no repository is reported by the run and does not widen the list. The lists in user, user.local, custom and custom.local config are merged as a union. Omitted or empty, it allows no project.`,
8754
8756
  examples: [["~/src/github.com/me/app", "/srv/checkouts/shared-lib"]]
8757
+ }),
8758
+ groups: record(string().regex(CONNECT_GROUP_NAME_PATTERN), array(string().min(1).max(MAX_ALLOW_PROJECT_LENGTH)).min(1).max(MAX_ALLOW_PROJECTS)).refine((groups) => Object.keys(groups).length <= MAX_CONNECT_GROUPS).optional().meta({
8759
+ description: `Named subsets of the allow list that \`ce:connect\` can be narrowed to with \`group:<name>\`. A group name is 1 to 64 characters of lowercase letters, digits and hyphens, led by a letter or digit (\`${CONNECT_GROUP_NAME_PATTERN.source}\`). Each group lists at least one and at most ${MAX_ALLOW_PROJECTS} members in the same form as an \`allow_projects\` entry. At most ${MAX_CONNECT_GROUPS} groups per file. A group never adds a project: a member that is not on the allow list stops the run that selects the group. Groups merge by name across user, user.local, custom and custom.local config, and a later file replaces a same-named group whole.`,
8760
+ examples: [
8761
+ {
8762
+ "harness-tools": [
8763
+ "~/src/github.com/me/app",
8764
+ "/srv/checkouts/shared-lib"
8765
+ ]
8766
+ }
8767
+ ],
8768
+ maxProperties: MAX_CONNECT_GROUPS
8755
8769
  })
8756
8770
  }).strict().meta({
8757
- description: "Cross-project connections. User-owned only: valid in user config or OPENCODE_CONFIG_DIR config, and a project config setting it has the whole block ignored with a warning, because a repository cannot grant itself access to other projects. A block with an unknown key or a bad value is unreadable and counts as an empty allow list.",
8771
+ description: "Cross-project connections. User-owned only: valid in user config or OPENCODE_CONFIG_DIR config, and a project config setting it has the whole block ignored with a warning, because a repository cannot grant itself access to other projects. A block with an unknown key or a bad value is unreadable and counts as an empty allow list and no groups.",
8758
8772
  examples: [
8759
8773
  { allow_projects: ["~/src/github.com/me/app"] },
8774
+ {
8775
+ allow_projects: [
8776
+ "~/src/github.com/me/app",
8777
+ "~/src/github.com/me/lib"
8778
+ ],
8779
+ groups: { "harness-tools": ["~/src/github.com/me/app"] }
8780
+ },
8760
8781
  { allow_projects: [] }
8761
8782
  ]
8762
8783
  }));
@@ -10515,9 +10536,20 @@ function mergeConnect(sources) {
10515
10536
  const blocks = sources.flatMap((source) => source.config.connect === undefined ? [] : [source.config.connect]);
10516
10537
  if (blocks.length === 0)
10517
10538
  return {};
10539
+ const groups = {};
10540
+ let hasGroups = false;
10541
+ for (const block of blocks) {
10542
+ if (block.groups === undefined)
10543
+ continue;
10544
+ hasGroups = true;
10545
+ for (const [name, members] of Object.entries(block.groups)) {
10546
+ groups[name] = [...members];
10547
+ }
10548
+ }
10518
10549
  return {
10519
10550
  connect: {
10520
- allow_projects: blocks.reduce((merged, block) => mergeArraysUnique(merged, block.allow_projects), [])
10551
+ allow_projects: blocks.reduce((merged, block) => mergeArraysUnique(merged, block.allow_projects), []),
10552
+ ...hasGroups && { groups }
10521
10553
  }
10522
10554
  };
10523
10555
  }
package/dist/index.js CHANGED
@@ -26,7 +26,7 @@ import {
26
26
  SEARCH_NOTICES,
27
27
  SEARCH_CONFIG_UNREADABLE_NOTE,
28
28
  runSearch
29
- } from "./index-nrbdgp4m.js";
29
+ } from "./index-1cj1mrpb.js";
30
30
 
31
31
  // src/index.ts
32
32
  import path8 from "path";
@@ -748,16 +748,53 @@ function buildAssetPlan(input) {
748
748
  };
749
749
  }
750
750
 
751
+ // src/lib/opencode-v2-tool-guard.ts
752
+ var READ_ONLY_AGENT_NAMES = [
753
+ "connections-researcher"
754
+ ];
755
+ var READ_ONLY_TOOL_ALLOWLIST = [
756
+ "read",
757
+ "grep",
758
+ "glob",
759
+ "skill",
760
+ "systematic_search",
761
+ "systematic_skill"
762
+ ];
763
+ var ALLOWED = { allowed: true };
764
+ function decideToolCall(agent, tool) {
765
+ if (typeof agent !== "string" || !READ_ONLY_AGENT_NAMES.includes(agent)) {
766
+ return ALLOWED;
767
+ }
768
+ if (typeof tool === "string" && READ_ONLY_TOOL_ALLOWLIST.includes(tool)) {
769
+ return ALLOWED;
770
+ }
771
+ const name = typeof tool === "string" ? tool : "unknown";
772
+ return {
773
+ allowed: false,
774
+ message: `The tool "${name}" is not available to the read-only ${agent} agent. It may call only: ${READ_ONLY_TOOL_ALLOWLIST.join(", ")}.`
775
+ };
776
+ }
777
+ function refuseOutsideAllowlist(event) {
778
+ const verdict = decideToolCall(event.agent, event.tool);
779
+ if (!verdict.allowed)
780
+ throw new Error(verdict.message);
781
+ }
782
+ var installToolGuard = async ({ ctx }) => {
783
+ await ctx.tool.hook("execute.before", refuseOutsideAllowlist);
784
+ };
785
+
751
786
  // src/lib/config-handler.ts
752
787
  function isSystematicAgentConfig(agent) {
753
788
  const description = agent?.description;
754
789
  return typeof description === "string" && /\(.* - Systematic\)$/.test(description);
755
790
  }
791
+ var reportedSecuritySensitiveAgents = new Set;
792
+ var foreignRoutingByConfig = new WeakMap;
756
793
  function isSystematicCommandConfig(command) {
757
794
  const description = command?.description;
758
795
  return typeof description === "string" && description.startsWith("(Systematic) ");
759
796
  }
760
- function mergeSystematicEntries(existing, emitted, shouldDropExisting) {
797
+ function mergeSystematicEntries(existing, emitted, shouldDropExisting, enforceOver) {
761
798
  const merged = { ...existing ?? {} };
762
799
  for (const [key, value] of Object.entries(existing ?? {})) {
763
800
  if (shouldDropExisting(key, value)) {
@@ -765,12 +802,54 @@ function mergeSystematicEntries(existing, emitted, shouldDropExisting) {
765
802
  }
766
803
  }
767
804
  for (const [key, value] of Object.entries(emitted)) {
768
- if (Object.hasOwn(merged, key))
805
+ if (Object.hasOwn(merged, key)) {
806
+ if (enforceOver !== undefined) {
807
+ merged[key] = enforceOver(key, merged[key], value);
808
+ }
769
809
  continue;
810
+ }
770
811
  merged[key] = value;
771
812
  }
772
813
  return merged;
773
814
  }
815
+ function isSecuritySensitiveAgent(name) {
816
+ return READ_ONLY_AGENT_NAMES.includes(name);
817
+ }
818
+ function readForeignRouting(entry) {
819
+ if (!isRecord(entry))
820
+ return {};
821
+ const { model, variant } = entry;
822
+ return {
823
+ ...typeof model === "string" ? { model } : {},
824
+ ...typeof variant === "string" ? { variant } : {}
825
+ };
826
+ }
827
+ function reportForeignDefinition(name) {
828
+ if (reportedSecuritySensitiveAgents.has(name))
829
+ return;
830
+ reportedSecuritySensitiveAgents.add(name);
831
+ console.warn(`[systematic] agent "${name}" is also defined by another config entry; applied Systematic's read-only definition and kept only that entry's model and variant.`);
832
+ }
833
+ function enforceSecuritySensitiveAgent(config, name, present, emitted) {
834
+ if (!isSecuritySensitiveAgent(name))
835
+ return present ?? emitted;
836
+ const captured = foreignRoutingByConfig.get(config) ?? new Map;
837
+ foreignRoutingByConfig.set(config, captured);
838
+ let foreign;
839
+ if (isSystematicAgentConfig(present)) {
840
+ foreign = captured.get(name);
841
+ } else {
842
+ foreign = readForeignRouting(present);
843
+ captured.set(name, foreign);
844
+ reportForeignDefinition(name);
845
+ }
846
+ const result = { ...emitted };
847
+ if (foreign?.model !== undefined)
848
+ result.model = foreign.model;
849
+ if (foreign?.variant !== undefined)
850
+ result.variant = foreign.variant;
851
+ return result;
852
+ }
774
853
  function foldPermissionRulesToV1Map(rules) {
775
854
  const explicitSkillSettings = new Map;
776
855
  for (const rule of rules) {
@@ -884,7 +963,7 @@ function createConfigHandler(deps) {
884
963
  const { config: systematicConfig, overlays } = loadConfigWithSources(directory);
885
964
  const existingAgents = { ...config.agent ?? {} };
886
965
  const existingCommands = { ...config.command ?? {} };
887
- const nativeAgentNames = Object.entries(existingAgents).filter(([, agent]) => !isSystematicAgentConfig(agent)).map(([name]) => name);
966
+ const nativeAgentNames = Object.entries(existingAgents).filter(([name, agent]) => !isSystematicAgentConfig(agent) && !isSecuritySensitiveAgent(name)).map(([name]) => name);
888
967
  const plan = buildAssetPlan({
889
968
  config: systematicConfig,
890
969
  overlays,
@@ -902,7 +981,7 @@ function createConfigHandler(deps) {
902
981
  toV1AgentConfig(planned)
903
982
  ]));
904
983
  const bundledAgentKeys = new Set(Object.keys(bundledAgents));
905
- config.agent = mergeSystematicEntries(existingAgents, bundledAgents, (key, agent) => bundledAgentKeys.has(key) && isSystematicAgentConfig(agent));
984
+ config.agent = mergeSystematicEntries(existingAgents, bundledAgents, (key, agent) => bundledAgentKeys.has(key) && isSystematicAgentConfig(agent) && !isSecuritySensitiveAgent(key), (key, present, emitted) => enforceSecuritySensitiveAgent(config, key, present, emitted));
906
985
  config.command = mergeSystematicEntries(existingCommands, plan.commands, (_key, command) => isSystematicCommandConfig(command));
907
986
  applyDiscoveredRouting(config, plan, reportedRouting);
908
987
  registerSkillsPaths(config, plan.skillsDir);
@@ -1863,41 +1942,6 @@ var installSkills = async ({
1863
1942
  await guard.async("skill output restore registration", () => ctx.session.hook("context", restore))();
1864
1943
  };
1865
1944
 
1866
- // src/lib/opencode-v2-tool-guard.ts
1867
- var READ_ONLY_AGENT_NAMES = [
1868
- "connections-researcher"
1869
- ];
1870
- var READ_ONLY_TOOL_ALLOWLIST = [
1871
- "read",
1872
- "grep",
1873
- "glob",
1874
- "skill",
1875
- "systematic_search",
1876
- "systematic_skill"
1877
- ];
1878
- var ALLOWED = { allowed: true };
1879
- function decideToolCall(agent, tool) {
1880
- if (typeof agent !== "string" || !READ_ONLY_AGENT_NAMES.includes(agent)) {
1881
- return ALLOWED;
1882
- }
1883
- if (typeof tool === "string" && READ_ONLY_TOOL_ALLOWLIST.includes(tool)) {
1884
- return ALLOWED;
1885
- }
1886
- const name = typeof tool === "string" ? tool : "unknown";
1887
- return {
1888
- allowed: false,
1889
- message: `The tool "${name}" is not available to the read-only ${agent} agent. It may call only: ${READ_ONLY_TOOL_ALLOWLIST.join(", ")}.`
1890
- };
1891
- }
1892
- function refuseOutsideAllowlist(event) {
1893
- const verdict = decideToolCall(event.agent, event.tool);
1894
- if (!verdict.allowed)
1895
- throw new Error(verdict.message);
1896
- }
1897
- var installToolGuard = async ({ ctx }) => {
1898
- await ctx.tool.hook("execute.before", refuseOutsideAllowlist);
1899
- };
1900
-
1901
1945
  // src/lib/opencode-v2.ts
1902
1946
  var DIAGNOSTIC_PREFIX = "systematic:";
1903
1947
  function describeFailure(error) {
@@ -1979,10 +2023,37 @@ function writeAgentFields(agent, planned, reported) {
1979
2023
  writeAgentModel(agent, planned, reported);
1980
2024
  agent.permissions.push(...agentPermissionRules(planned));
1981
2025
  }
2026
+ function readForeignModel(entry) {
2027
+ if (!isRecord(entry) || !isRecord(entry.model))
2028
+ return;
2029
+ const { providerID, id, variant } = entry.model;
2030
+ if (typeof providerID !== "string" || typeof id !== "string")
2031
+ return;
2032
+ return typeof variant === "string" ? { providerID, id, variant } : { providerID, id };
2033
+ }
2034
+ function replaceReadOnlyAgent(editor, planned, existing, reported) {
2035
+ const foreignModel = readForeignModel(existing);
2036
+ const key = `replaced:${planned.name}`;
2037
+ if (!reported.has(key)) {
2038
+ reported.add(key);
2039
+ console.error(`${DIAGNOSTIC_PREFIX} agent "${planned.name}" is also defined by the host or another plugin; applied Systematic's read-only definition and kept only that entry's model`);
2040
+ }
2041
+ editor.remove(planned.name);
2042
+ editor.update(planned.name, (agent) => {
2043
+ writeAgentFields(agent, planned, reported);
2044
+ if (foreignModel !== undefined)
2045
+ agent.model = foreignModel;
2046
+ });
2047
+ }
1982
2048
  function applyPlannedAgent(editor, planned, reported = new Set) {
1983
2049
  if (planned.config.disable === true)
1984
2050
  return;
1985
- if (editor.get(planned.name) !== undefined) {
2051
+ const existing = editor.get(planned.name);
2052
+ if (existing !== undefined) {
2053
+ if (READ_ONLY_AGENT_NAMES.includes(planned.name)) {
2054
+ replaceReadOnlyAgent(editor, planned, existing, reported);
2055
+ return;
2056
+ }
1986
2057
  const key = `clash:${planned.name}`;
1987
2058
  if (reported.has(key))
1988
2059
  return;
@@ -13,6 +13,8 @@ export interface ConfigHandlerDeps {
13
13
  /** OpenCode global config directory override for discovered-skill lookups. Defaults to `<homeDir>/.config/opencode`. */
14
14
  opencodeConfigDir?: string;
15
15
  }
16
+ /** Clear the once-per-process notice record and captured routing. For tests. */
17
+ export declare function resetSecuritySensitiveAgentNotices(): void;
16
18
  /**
17
19
  * Per-tool permission rule map as actually emitted by {@link foldPermissionRulesToV1Map}:
18
20
  * each key is a match pattern (`'*'` or an exact name) mapped to a setting.
@@ -86,7 +88,10 @@ export declare function toV1AgentConfig(planned: PlannedAgent): AgentConfig;
86
88
  *
87
89
  * Bundled content is loaded and then tuned with Systematic agent overlays.
88
90
  * Existing native OpenCode agents with the same emitted key are preserved as
89
- * replacements for bundled agents.
91
+ * replacements for bundled agents. The exception is a security-sensitive agent
92
+ * (see {@link isSecuritySensitiveAgent}): its Systematic definition is applied
93
+ * over any other entry of the same name, keeping only that entry's model and
94
+ * variant.
90
95
  */
91
96
  export declare function createConfigHandler(deps: ConfigHandlerDeps): (config: Config) => Promise<void>;
92
97
  /** Register a directory for OpenCode's native skill discovery (`skill` tool). */
@@ -401,6 +401,7 @@ export declare function createSystematicConfigSchema(opts: SystematicConfigSchem
401
401
  }, z.core.$strict>>;
402
402
  connect: z.ZodOptional<z.ZodObject<{
403
403
  allow_projects: z.ZodOptional<z.ZodArray<z.ZodString>>;
404
+ groups: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;
404
405
  }, z.core.$strict>>;
405
406
  disabled_skills: z.ZodDefault<z.ZodArray<z.ZodEnum<{
406
407
  [x: string]: string;
@@ -613,6 +614,7 @@ export declare const SystematicConfigSchema: z.ZodObject<{
613
614
  }, z.core.$strict>>;
614
615
  connect: z.ZodOptional<z.ZodObject<{
615
616
  allow_projects: z.ZodOptional<z.ZodArray<z.ZodString>>;
617
+ groups: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;
616
618
  }, z.core.$strict>>;
617
619
  disabled_skills: z.ZodDefault<z.ZodArray<z.ZodEnum<{
618
620
  [x: string]: string;
@@ -201,8 +201,9 @@ export interface SystematicConfig {
201
201
  searchUnreadable?: boolean;
202
202
  /**
203
203
  * Merged `connect` settings from user and custom config only: the
204
- * `allow_projects` lists of every layer that sets one, as a union. Absent
205
- * when no layer sets the block, which allows no project. A project
204
+ * `allow_projects` lists of every layer that sets one, as a union, and the
205
+ * `groups` by name with a later layer replacing a same-named group whole.
206
+ * Absent when no layer sets the block, which allows no project. A project
206
207
  * config's `connect` is stripped at load with a warning and never appears
207
208
  * here. The `ce:connect` helper reads the same files itself
208
209
  * (`loadConnectAllowList`) and never consults this value.