@guidobuilds/forge-ai 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -9,6 +9,56 @@ Versions prior to 0.3.0 are not reconstructed here; see git history for earlier
 
 ## [Unreleased]
 
+## [0.8.0] - 2026-09-03
+
+### Added
+
+- **`forge-ai list`** — prints every recorded install (the user-scope one, if any, plus one line per project) with Forge version, file count, platforms, and last-updated time. Answers "where is Forge installed and with what," which previously required manually reading manifest JSON files.
+- `tests/fixtures/<platform>/<name>.golden` — committed golden-render snapshots (6 artifacts × 4 platforms) guarding against unintended drift in installed prose. Regenerate with `npm run generate-fixtures` after reviewing the diff.
+- **Model selection.** `install`/`update` now offer an interactive model-selection step (per artifact × platform, gated on which platforms actually support a model — 3 of 4 silently drop it on skills) and accept `--model <id>` / `--model-map name=model,...` for non-interactive use (both require an explicit single `--platform`, since model ids are not portable across platforms). Choices persist in `model-preferences.json` next to the manifest and survive later `update` runs instead of silently resetting to the canonical default.
+- **`forge-ai configure`** — change an already-installed agent's model without a full reinstall. Interactive by default; non-interactive via `--model`/`--model-map`. Rewrites only the affected files.
+- **`forge-ai uninstall`** — the CLI's only removal path was previously "delete the files by hand"; now a manifest-driven uninstall mirrors `update`'s overwrite protection (a locally-edited file is backed up and requires `--yes`/`--force` or interactive confirmation before removal). Supports `--platform` to uninstall a single agent and `--dry-run` to preview.
+- **OpenCode model discovery.** The per-agent model prompt (`install` and `configure`) shells out to `opencode models` (falling back to `opencode2 models` on v2) to offer exactly the models the user has real, credential-backed access to, instead of a generic list — OpenCode has no fixed model enum and its config file is not a reliable source of truth (env-var- and credential-connected providers appear in neither). Falls back to free-text entry if neither binary is available, or if a v2 install predates the `models` command (added to `opencode2` on 2026-08-06). `OPENCODE_UNKNOWN_MODEL` / `CODEX_UNKNOWN_MODEL` warnings added, matching the existing Claude/Grok pattern (OpenCode/Codex previously had no model validation at all).
+- **OpenCode user-scope install now targets both v1 and v2, whichever actually exist.** v1 (`~/.config/opencode/`) and the v2 preview (`~/.opencode/`) read agents/skills from different directories — confirmed via `opencode2 debug config`, which doesn't list `~/.config/opencode` as a source at all. Installing only ever wrote v1's path, so a v2-only setup (no `opencode` v1 binary ever run) got files on disk that OpenCode itself would never read — `forge` silently missing from the agent list with no error. `install`/`update` now write to each generation's directory only if it already exists (`OPENCODE_USER_ROOT_NOT_FOUND` info diagnostic, defaulting to v1, if neither does yet); both get written if both exist. Project scope is unaffected — v1 and v2 already share `.opencode/` there.
+
+### Changed
+
+- **`forge` installs as a real Claude Code subagent, not a skill.** Claude subagents can now spawn subagents up to depth 5 (v2.1.172+), so the historical blocker for a Claude-side orchestrator is gone. `forge` now has a structural `tools` allowlist (`Agent(forge-worker, forge-adversary)`, `TodoWrite`, `Skill`, `AskUserQuestion`) instead of being a fully advisory skill — it cannot Read/Write/Edit/Bash itself. It still keeps `AskUserQuestion` (confirmed: that tool is only stripped from bounded sub-task dispatches, not from an agent running as the session's main driver) and still loads `using-forge`/`forge-grill` via the `Skill` tool. To make it the automatic default for a project, add `{ "agent": "forge" }` to `.claude/settings.json` yourself — the installer does not write this for you (see README).
+- **Codex agents declare an explicit `sandbox_mode`** — `read-only` for `forge` (it only dispatches), `workspace-write` for `forge-worker`/`forge-worker-leaf`/`forge-adversary` (they write files). Previously unset on all four.
+- Grok and OpenCode installs now warn (`GROK_SKILL_DISCOVERABLE_UNENFORCED` / `OPENCODE_SKILL_DISCOVERABLE_UNENFORCED`) when installing a background-only skill (`using-forge`, `forge-grill`) that Claude can hide from direct invocation but Grok/OpenCode cannot — previously silent.
+- **Per-user install state moved from `~/.forge-ai/` to `~/.forge/state/`.** Migrated automatically and transparently on first use of any command that touches it (`install`, `update`, `uninstall`, `list`) — the old directory is copied, never moved, and left in place with a `MIGRATED` note; nothing is deleted automatically. Nesting under `state/` means this can never collide with a project's own `.forge/<feature-slug>/` ledger, even in a repo where `$HOME` itself has been used as a Forge project.
+- **The manifest now records the installed Forge version** (`forgeVersion`, both per-entry and per-manifest) and **merges across separate single-`--platform` runs instead of replacing** — `install --platform claude` followed by `install --platform opencode` no longer causes the first platform's files to reclassify as untracked/foreign. Existing `schemaVersion: 1` manifests are upgraded transparently on read (`forgeVersion: "unknown"`).
+- Install/update/uninstall now warn if a legacy `~/.forge-ai/` manifest was updated more recently than the current `~/.forge/state/` one — a sign a cached old CLI is still writing to the old location.
+- **Per-harness dispatch vocabulary in canonical artifact bodies is now composed per platform instead of hardcoded.** `forge-worker.md`, `forge.md`, and `using-forge.md` no longer spell out "via `Agent` (Claude), `task` (Grok), or `task` (OpenCode)" or a standalone "Codex fallback" section inline — a `{{snippet:id}}` reference is resolved per target platform at render time (`src/compose.ts`, `src/dispatch-snippets.ts`), failing loudly at build time if a platform has no text for a referenced snippet. This is a genuine prose change on Claude/Grok/OpenCode/Codex installs, not a no-op refactor — installed agent bodies now read slightly differently (equivalent meaning, phrased per platform instead of listing all four in one sentence). `BODY_OVER_BUDGET` is now measured on the composed, per-platform body rather than the shared canonical source.
+
+### Removed
+
+- **Claude Code and Codex plugin marketplace distribution channels** (`forge-plugin/`, `plugins/forge/`, `.claude-plugin/`, `.agents/plugins/marketplace.json`, `src/adapters/claude-plugin.ts`, `src/adapters/codex-plugin.ts`, `src/build-plugin.ts`, the `forge-ai build-plugin` command, the plugin drift guard (`.githooks/`, `scripts/check-plugin-sync.mjs`, `scripts/verify-drift-guard.sh`), and 16 plugin-specific tests). The npm CLI (`npx @guidobuilds/forge-ai install`) is now the single supported distribution and install method for all four platforms, including Claude Code and Codex — both of which previously also had an alternative plugin-marketplace install path shipped in 0.7.0.
+- `PluginFile` type and `writePluginFiles` (`src/model.ts`, `src/writer.ts`).
+- Public export `export * from './adapters/codex-plugin.js'` from `src/index.ts` — anyone importing `@guidobuilds/forge-ai` programmatically for Codex plugin generation loses that entry point.
+- `prepare`/`pretest` npm scripts, which existed solely to wire the now-removed pre-commit drift guard.
+
+### Fixed
+
+- README no longer claims the Claude Code plugin channel is "Not yet live" (it had been live since 0.7.0; the line was never updated).
+
+### Security
+
+An internal application-security audit (`report/api-report.md`, `report/api-fix.md`) found 15 findings (`A`, `B`, `C`, `M1`–`M12`); the two highest-severity ones were proven exploitable end-to-end in an isolated adversarial gate (`report/verification.md`). This release fixes the two proven findings (`A`, `B`) plus four of the supporting ones (`C`, `M1`, `M2`, `M12`), with dedicated regression tests (`tests/forge-cli.test.ts`, +22 tests). The remaining nine (`M3`–`M11`, correctness/hygiene polish — see `report/summary.md` §5) are lower-priority and not security-critical; they remain open.
+
+- **Install-manifest entries are now scope-validated before any prune/uninstall delete or overwrite** (`src/paths.ts`, `src/manifest.ts`, `src/cli.ts`). `loadManifest` previously trusted any parseable JSON, and `pruneEntries`/`uninstall` deleted or overwrote `entry.path` with no check that it fell under a Forge-managed root — a poisoned `~/.forge/state/*.json` manifest was proven able to delete an arbitrary out-of-scope file, including via a symlinked path. Entries outside the per-scope allowlist (derived from the same `userBase`/`projectBase` roots as normal installs) are now rejected before any destructive operation.
+- **Subprocess binaries are now resolved via an explicit `PATH` scan against an allowlist of trusted basenames, and repo-local shims are rejected** (`src/executable-resolution.ts`, `src/self-update.ts`, `src/opencode-discovery.ts`). Model discovery and self-update previously `spawnSync`'d bare command names (`opencode`, `pnpm`, `npm`, `forge-ai`) resolved from the ambient `PATH`, with model discovery additionally passing `cwd = process.cwd()` — a shim named `opencode` placed on `PATH` (e.g. via `node_modules/.bin`) was proven to execute with the user's privileges. Discovery no longer passes `cwd`, and every spawn now resolves to an absolute, allowlisted path first.
+- **`self-update --to <version>` now allowlists its argument to a semver or `latest` spec** (`src/self-update.ts`, `src/cli.ts`) before it reaches `npm`/`pnpm install -g` — previously an arbitrary string was interpolated directly into the install command.
+- **Manifest and model-preferences writes are now atomic** (temp-file + rename) (`src/manifest.ts`, `src/model-preferences.ts`), closing a TOCTOU window where an interrupted write could leave a corrupt state file.
+- **Corrupt manifest/preferences files now fail safe instead of crashing the CLI with a raw stack trace** — malformed JSON or a non-object shape falls back to empty state with a diagnostic pointing at `forge-ai install` to regenerate it (`src/manifest.ts`, `src/model-preferences.ts`).
+- **OpenCode adapter now validates `permissions` shape before emitting** (`src/adapters/opencode.ts`, `src/adapters/shared.ts`) instead of passing an unvalidated value straight through to frontmatter, matching the validation Claude/Grok/Codex already had.
+
+### Migration from 0.7.x
+
+- If you installed Forge via `/plugin install forge@guidobuilds` (Claude Code) or `codex plugin add forge@guidobuilds-forge` (Codex), those marketplace sources no longer exist in this repository. Remove the plugin (`/plugin uninstall forge@guidobuilds` or `codex plugin remove forge@guidobuilds-forge`, then remove the marketplace) and install via the CLI instead: `npx @guidobuilds/forge-ai install --platform claude` or `--platform codex`.
+- If you only ever used the CLI (`npx @guidobuilds/forge-ai install/update`), nothing changes for you.
+- Programmatic consumers importing Codex plugin generation from `@guidobuilds/forge-ai`'s package export must vendor that logic themselves; it is no longer part of this package.
+
 ## [0.7.0] - 2026-08-06
 
 ### Added

package/README.md

@@ -94,13 +94,22 @@ The same operating model is shared across all supported agents so the workflow s
 
 ## Installation
 
-The primary installer is the npm CLI:
+Install with the npm CLI:
 
 ```sh
 npx @guidobuilds/forge-ai install
 ```
 
-The installer prompts for the target agent platform and whether Forge should be installed globally for your user or locally for the current project.
+The installer prompts for the target agent platform, whether Forge should be installed globally for your user or locally for the current project, and — interactively — which model each agent should use: keep each agent's recommended default, or choose per agent. For OpenCode, the per-agent prompt shows the models you actually have configured (via `opencode models`, falling back to free-text entry if that command isn't available), not a generic list.
+
+To choose models non-interactively (requires an explicit single `--platform` — model ids aren't portable across platforms):
+
+```sh
+npx @guidobuilds/forge-ai install --platform claude --scope user --model opus --yes
+npx @guidobuilds/forge-ai install --platform opencode --scope user --model-map forge=anthropic/claude-opus-4-1,forge-worker=anthropic/claude-sonnet-4-5 --yes
+```
+
+`--model` applies to every agent that supports a model on the target platform; `--model-map name=model,...` sets it per artifact. Choices persist across `update` — they are not silently reset back to the canonical default. To change a model later without a full reinstall, see [Configuring models](#configuring-models) below.
 
 To update an existing install:
 
@@ -126,52 +135,6 @@ Validate a local Forge source tree:
 npx @guidobuilds/forge-ai validate --source .
 ```
 
-### Claude Code plugin (alternative to the CLI installer)
-
-Claude Code users can also install Forge as a plugin, using Claude Code's built-in marketplace mechanism instead of (or alongside) the CLI installer above:
-
-```
-/plugin marketplace add guidobuilds/forge
-/plugin install forge@guidobuilds
-```
-
-Things to know before switching to this channel:
-
-- **Claude Code channel.** Codex also has its own plugin channel (below); OpenCode and Grok Build remain CLI-only.
-- **The entry point changes.** Plugin skills are always namespaced, so the orchestrator is invoked as `/forge:forge`, not the bare `/forge` used by a CLI-pushed install. Claude can still auto-load the `forge` skill from its description without you typing a slash command at all — this is Claude Code's general skill-invocation mechanism (skills are automatically discovered and can be invoked by Claude based on task context), not something specific to the plugin — a practical mitigation, but not a guaranteed substitute for the namespaced command.
-- **Auto-update is off by default.** Official Anthropic-managed marketplaces have auto-update enabled by default; third-party marketplaces like `guidobuilds` default to auto-update off, so you need to explicitly run `/plugin update forge@guidobuilds` (or toggle auto-update on for the `guidobuilds` marketplace) to pick up new releases.
-- **Same source, two channels.** The plugin package and the CLI-pushed files are both generated from the same canonical `artifacts/` source (via `forge-ai build-plugin`), so behavior is consistent — the plugin is not a fork of the CLI content.
-- **Not yet live:** `/plugin marketplace add guidobuilds/forge` requires this repo's generated `forge-plugin/` and `.claude-plugin/` directories to be committed and pushed first (see the release process in `CONTRIBUTING.md`). The marketplace/install mechanics were independently verified end-to-end against a real git-clone-based install, but not yet against a pushed `guidobuilds/forge` itself.
-
-### Codex plugin (alternative to the CLI installer)
-
-Codex can install Forge from this repository as a standalone, skills-only plugin:
-
-```sh
-codex plugin marketplace add guidobuilds/forge --ref main
-codex plugin add forge@guidobuilds-forge
-```
-
-Open a new Codex session after installation. The plugin exposes one public `forge` skill and keeps the worker, leaf, adversary, routing, and grill contracts as private references. Codex plugins cannot register `.codex/agents/*.toml`, so Forge spawns standard/default Codex sub-agents and injects the complete applicable contract. When sub-agent spawning is unavailable it uses a documented sequential inline fallback.
-
-This is independent from the direct CLI channel:
-
-```sh
-npx @guidobuilds/forge-ai install --platform codex --scope user
-npx @guidobuilds/forge-ai update --platform codex --scope user
-```
-
-Choose one channel when possible. Installing both does not overwrite the other channel's files, but it can expose duplicate Forge workflows. Update or remove Forge using the same channel used to install it.
-
-To refresh or uninstall the marketplace channel:
-
-```sh
-codex plugin marketplace upgrade guidobuilds-forge
-codex plugin remove forge@guidobuilds-forge
-# Optional after removing Forge:
-codex plugin marketplace remove guidobuilds-forge
-```
-
 ## How to Use
 
 Forge installs the **same operating model** on every agent, but **how you invoke it differs per platform**, because each agent exposes different primitives (skills, subagents, agent switching). The installer is only step one — this section is how you actually drive Forge once it is installed.
@@ -193,16 +156,22 @@ What changes per platform is the **kind** each piece is installed as, and theref
 
 | Piece | Installed as | How you invoke it |
 |---|---|---|
-| `forge` | skill (`model: opus`) | type `/forge` in the prompt — the only Forge skill you invoke directly |
+| `forge` | subagent (`model: opus`, structural `tools` allowlist) | mention it by name, `@forge`, or `claude --agent forge` |
 | `forge-grill` | skill (`model: sonnet`, not user-invocable) | loaded automatically by `forge` before non-trivial or risk-bearing builds |
 | `using-forge` | skill (`model: sonnet`, not user-invocable) | loaded automatically by `forge` before routing work |
-| `forge-worker` | subagent | coordinator; main thread delegates via `Agent` (or legacy `Task`) |
+| `forge-worker` | subagent | coordinator; `forge` delegates via `Agent(forge-worker, forge-adversary)` |
 | `forge-worker-leaf` | subagent | terminal shard; spawned by `forge-worker` (or orchestrator on Codex) |
 | `forge-adversary` | subagent | the orchestrator delegates to it after build to gate risk-bearing work |
 
-Start a session by typing **`/forge`**. That loads the orchestrator role into your main Claude Code thread, which delegates each bounded task to `forge-worker`, which may spawn `forge-worker-leaf` for heavy inspect/build shards. Requires **Claude Code v2.1.172+** for nested sub-agents. `forge-grill` and `using-forge` are marked `user-invocable: false`: Claude still loads and runs them as part of `forge`'s routing, but they no longer appear in the `/` menu or run as standalone commands — `forge` is the single entry point.
+`forge` installs as a real Claude Code subagent with a structural `tools` allowlist (`Agent(forge-worker, forge-adversary)`, `TodoWrite`, `Skill`, `AskUserQuestion`) — it cannot Read/Write/Edit/Bash itself, only dispatch. It loads `using-forge` and `forge-grill` via the `Skill` tool and can still ask you clarifying questions directly (`AskUserQuestion` is retained for an agent running as the session's main driver, unlike a bounded sub-task dispatch). Requires **Claude Code v2.1.172+**.
 
-> Why a skill and not an agent on Claude? The main thread retains `Agent`/`Task` and can delegate. A skill injects orchestrator behavior without replacing the main agent. The trade-off: "delegate, never do worker work inline" is followed by instruction at the orchestrator layer, not by tool restrictions — but `forge-worker` **can** structurally spawn leaves when given `Agent` in its tool list.
+To make `forge` the automatic default for a project (equivalent to the old `/forge` auto-load), add to `.claude/settings.json`:
+
+```json
+{ "agent": "forge" }
+```
+
+Without that, invoke it explicitly per session (mention it by name, `@forge`, or `claude --agent forge`). `forge-ai install`/`update`/`uninstall` manage `forge`'s own file; they do not write `settings.json` for you.
 
 ### OpenCode
 
@@ -223,7 +192,7 @@ Switch your primary agent to **`forge`**. Unlike Claude Code, the orchestrator h
 | `forge`, `forge-worker`, `forge-worker-leaf`, `forge-adversary` | agents (`.toml`) | `~/.codex/agents/` (or `.codex/agents/` per project) |
 | `using-forge`, `forge-grill` | skills | `~/.agents/skills/` (or `.agents/skills/` per project) |
 
-The direct CLI channel writes agent `.toml` files but does not generate `AGENTS.md` or profiles. The plugin channel instead uses one skill plus injected private role contracts, so it needs no separate agent installation.
+The CLI writes agent `.toml` files but does not generate `AGENTS.md` or profiles.
 
 ### Project vs user scope
 
@@ -303,15 +272,33 @@ npx @guidobuilds/forge-ai@latest update
 
 Forge replaces its managed agent and skill definitions in your supported agent configuration directories.
 
-Forge records installed files in manifests under `~/.forge-ai/` so updates can safely remove files that are no longer bundled. `update` prunes stale managed files by default only when the current file still matches the recorded checksum; use `--no-prune` to keep stale managed files. `--dry-run` previews writes and deletes without changing files or manifests.
+Forge records installed files in manifests under `~/.forge/state/` (migrated automatically and transparently from the earlier `~/.forge-ai/` on first run — the old directory is left in place, marked with a `MIGRATED` note, and never deleted automatically) so updates can safely remove files that are no longer bundled. `update` prunes stale managed files by default only when the current file still matches the recorded checksum; use `--no-prune` to keep stale managed files. `--dry-run` previews writes and deletes without changing files or manifests.
 
-Forge now routes a single canonical artifact to the right artifact kind per agent: the orchestrator installs as a Claude Code skill (`/forge`) but as an agent on OpenCode and Codex. If you installed an earlier version, run `update` (not `install`) so Forge prunes the now-stale `forge` agent and standalone `forge-worker` skill left by the previous layout.
+Forge routes a single canonical artifact to the right artifact kind per agent: the orchestrator installs as a real subagent on Claude Code, OpenCode, and Codex, and as a skill on Grok. If you installed an earlier version where Claude's orchestrator was a skill, run `update` (not `install`) so Forge prunes the now-stale `~/.claude/skills/forge/SKILL.md` left by the previous layout.
 
 ## Uninstalling
 
-Remove Forge from the agent configuration directories for OpenCode, Codex, or Claude Code by deleting the installed Forge agent and skill entries.
+```sh
+npx @guidobuilds/forge-ai uninstall
+```
+
+This removes exactly the files Forge's manifest recorded for the given `--scope` (default: `user`), refusing to silently delete anything you edited locally — a locally-modified file is backed up and requires `--yes`/`--force` (or interactive confirmation) before it's removed, mirroring `update`'s overwrite protection. Pass `--platform` to uninstall a single agent instead of all of them, and `--dry-run` to preview what would be removed.
+
+## Listing installs
+
+```sh
+npx @guidobuilds/forge-ai list
+```
+
+Prints every recorded install — the user-scope one, if any, plus one line per project you've installed Forge into — with the Forge version, file count, platforms, and last-updated time for each.
+
+## Configuring models
+
+```sh
+npx @guidobuilds/forge-ai configure --platform claude --scope user
+```
 
-If you installed Forge for multiple tools, repeat the removal for each one you no longer want to use.
+Change which model an already-installed agent uses without a full reinstall. Interactively, it walks every agent on the given scope/platform that supports a model (using OpenCode's live `opencode models` output where applicable, same as `install`). Non-interactively, pass `--model <id>` or `--model-map name=model,...` (same rules as `install`: an explicit single `--platform`, no `--force`/`--yes` — the point of the command is to make a choice, not skip one). Only the affected files are rewritten; the manifest and every other installed platform are left untouched.
 
 ## Project Status
 

package/artifacts/forge/forge.md

@@ -3,11 +3,14 @@ name: forge
 description: Forge orchestrator with dynamic runtime routing and a single worker type
 kind: agent
 claude:
-  kind: skill
   model: opus
-  when_to_use: Use for any development or operational task in this repo — build a feature, fix a bug, investigate code, plan work, or verify a change. This is the default entry point; invoke explicitly with /forge or let Claude select it automatically for repo work.
+  permissions:
+    tools: ["Agent(forge-worker, forge-adversary)", TodoWrite, Skill, AskUserQuestion]
 grok:
   kind: skill
+codex:
+  permissions:
+    sandbox_mode: read-only
 opencode:
   mode: primary
   permissions:
@@ -49,7 +52,7 @@ The `using-forge` skill owns runtime routing, operating principles, approval heu
 
 ## Worker model
 - `forge-worker` is the coordinator worker; route all build and operational work to it at `DISPATCH_DEPTH: 1`.
-- `forge-worker-leaf` is the terminal worker for bounded shards at `DISPATCH_DEPTH: 2`; coordinators spawn it — or you fan out leaves when a coordinator returns `DELEGATION_REQUESTS` (Codex).
+- `forge-worker-leaf` is the terminal worker for bounded shards at `DISPATCH_DEPTH: 2`; {{snippet:who-spawns-leaf}}.
 - `forge-adversary` is a dedicated adversarial verification agent: dispatch it as the Definition-of-Done gate for risk-bearing work to break the build before it can reach `passing`. Never sub-delegate verify or adversary work.
 - You may launch one worker instance for a bounded task.
 - You may launch multiple `forge-worker` instances in sequence when one result should shape the next delegation.
@@ -89,7 +92,7 @@ QUESTIONS:
 1) <question>
 ```
 
-`QUESTIONS` appears only when `STATUS: blocked`. On `DELEGATION_REQUESTS`, fan out `forge-worker-leaf` dispatches (Codex fallback). Trust coordinator `SUB_RESULTS` unless `partial` or `blocked`.
+`QUESTIONS` appears only when `STATUS: blocked`. {{snippet:orchestrator-delegation-requests-handling}} Trust coordinator `SUB_RESULTS` unless `partial` or `blocked`.
 
 If output is malformed:
 1) request one reformat retry with same task_id

package/artifacts/forge-adversary/forge-adversary.md

@@ -8,6 +8,9 @@ claude:
 grok:
   permissions:
     tools: [todo_write, read_file, search_replace, run_terminal_cmd, grep_search, list_dir, web_fetch]
+codex:
+  permissions:
+    sandbox_mode: workspace-write
 opencode:
   mode: subagent
   permissions:

package/artifacts/forge-worker/forge-worker.md

@@ -8,6 +8,9 @@ claude:
 grok:
   permissions:
     tools: [todo_write, read_file, search_replace, run_terminal_cmd, grep_search, list_dir, web_fetch, task, get_task_output, kill_task]
+codex:
+  permissions:
+    sandbox_mode: workspace-write
 opencode:
   mode: subagent
   permissions:
@@ -154,14 +157,10 @@ Spawn `forge-worker-leaf` when `DELEGATION: required`, or when **any** trigger f
 ### Spawn protocol
 
 1. Decompose into bounded leaf subgoals with disjoint `files_hint` paths.
-2. Spawn `forge-worker-leaf` via `Agent` (Claude), `task` (Grok), or `task` (OpenCode). Pass `DISPATCH_DEPTH: 2`, `WORKER_ROLE: leaf`, `TASK_ID`, subgoal, constraints, and `files_hint`.
+2. {{snippet:worker-spawn-leaf-instruction}}
 3. Prefer **parallel** leaves for read-only `inspect`; prefer **sequential** leaves for `build` writes unless files are strictly disjoint.
 4. Synthesize: write durable detail to `.forge/<slug>/explore.md` or `build-log.md`; return ≤ 8 `SUMMARY` bullets plus compact `SUB_RESULTS`. Do not paste full child logs.
 
-### Codex fallback
-
-On harnesses without spawn tools (Codex), return `DELEGATION_REQUESTS` for the orchestrator to fan out `forge-worker-leaf` dispatches. Omit `DELEGATION_REQUESTS` when you self-spawn.
-
 ## Concurrency discipline
 
 When the orchestrator or sibling leaves may be running in parallel:

package/artifacts/forge-worker-leaf/forge-worker-leaf.md

@@ -8,6 +8,9 @@ claude:
 grok:
   permissions:
     tools: [todo_write, read_file, search_replace, run_terminal_cmd, grep_search, list_dir, web_fetch]
+codex:
+  permissions:
+    sandbox_mode: workspace-write
 opencode:
   mode: subagent
   permissions:

package/artifacts/using-forge/using-forge.md

@@ -87,7 +87,7 @@ Forge uses **two levels below the orchestrator** (`DISPATCH_DEPTH` 0 → 1 → 2
 
 ### Coordinator triggers
 
-`forge-worker` **must** spawn leaves (or return `DELEGATION_REQUESTS` on Codex) when any: ≥ 8 file reads, ≥ 6 searches, ≥ 20 tool calls, ≥ 5 files to edit, `DELEGATION: required`, or plan implies ≥ 3 shards. **Never** sub-delegate `verify` or adversary work.
+`forge-worker` **must** {{snippet:worker-must-spawn-or-delegate}} when any: ≥ 8 file reads, ≥ 6 searches, ≥ 20 tool calls, ≥ 5 files to edit, `DELEGATION: required`, or plan implies ≥ 3 shards. **Never** sub-delegate `verify` or adversary work.
 
 ### Orchestrator dispatch hints
 
@@ -100,7 +100,7 @@ TASK_ID: <unique>
 
 - Unfamiliar-repo `inspect` → `DELEGATION: allowed`
 - Narrow bugfix → `DELEGATION: forbidden`
-- Codex: parse `DELEGATION_REQUESTS` and fan out `forge-worker-leaf` yourself
+{{snippet:codex-orchestrator-dispatch-hint}}
 
 ## Routing rules
 

package/bin/forge-ai.mjs

@@ -2,6 +2,6 @@
 import { main } from '../dist/src/cli.js';
 
 main().then((code) => { process.exitCode = code; }, (error) => {
-  console.error(error);
+  console.error(error?.message ?? error);
   process.exitCode = 1;
 });

package/dist/src/adapters/claude-known.js

@@ -14,11 +14,15 @@ export const knownClaudeTools = new Set([
     'WebFetch',
     'WebSearch',
     'AskUserQuestion',
-    'ExitPlanMode'
+    'ExitPlanMode',
+    'Skill'
 ]);
 const mcpToolPattern = /^mcp__[A-Za-z0-9_-]+__[A-Za-z0-9_*-]+$/;
+// `Agent(name, name2)` restricts which subagent types an agent running as the main
+// session (via --agent/settings.json) is allowed to spawn — see sub-agents.md.
+export const agentAllowlistPattern = /^Agent\([A-Za-z0-9_-]+(?:,\s*[A-Za-z0-9_-]+)*\)$/;
 export function isKnownClaudeTool(name) {
-    return knownClaudeTools.has(name) || mcpToolPattern.test(name);
+    return knownClaudeTools.has(name) || mcpToolPattern.test(name) || agentAllowlistPattern.test(name);
 }
 export const knownClaudeModels = new Set([
     'sonnet',

package/dist/src/adapters/codex-known.js

@@ -0,0 +1,9 @@
+// Codex's current model-id list was not verified against live docs at the time this was written
+// (unlike Claude/Grok/OpenCode, which have a confirmed format). Rather than invent a shape we
+// haven't checked, this accepts any non-empty, whitespace-free value and lets Codex itself be the
+// real check — the same "don't guess" discipline this codebase applies elsewhere. Tighten this
+// once Codex's actual model-id format is verified against its docs.
+const codexModelPattern = /^\S+$/;
+export function isKnownCodexModel(value) {
+    return codexModelPattern.test(value);
+}

package/dist/src/adapters/codex.js

@@ -1,12 +1,17 @@
 import { stringifyYaml } from '../frontmatter.js';
 import { diagnostic } from '../diagnostics.js';
 import { isRecord, tomlString } from './shared.js';
+import { isKnownCodexModel } from './codex-known.js';
 const safeSandboxModes = new Set(['read-only', 'workspace-write']);
 export function renderCodexAgent(artifact) {
     const diagnostics = [diagnostic('info', 'CODEX_PARTIAL_AGENT_SUPPORT', `Codex agent output is partial and does not generate AGENTS.md or profiles for ${artifact.name}`, { platform: 'codex' })];
     const lines = [`name = ${tomlString(artifact.name)}`, `description = ${tomlString(artifact.description)}`, `developer_instructions = ${tomlString(artifact.body)}`];
-    if (artifact.codex?.model)
+    if (artifact.codex?.model) {
         lines.push(`model = ${tomlString(artifact.codex.model)}`);
+        if (!isKnownCodexModel(artifact.codex.model)) {
+            diagnostics.push(diagnostic('warning', 'CODEX_UNKNOWN_MODEL', `Unknown Codex model "${artifact.codex.model}" for ${artifact.name}`, { platform: 'codex' }));
+        }
+    }
     const permissions = artifact.codex?.permissions;
     if (isRecord(permissions) && typeof permissions.sandbox_mode === 'string') {
         if (safeSandboxModes.has(permissions.sandbox_mode))

package/dist/src/adapters/grok.js

@@ -37,5 +37,8 @@ export function renderGrokSkill(artifact) {
     if (artifact.grok?.model) {
         diagnostics.push(diagnostic('info', 'GROK_SKILL_MODEL_IGNORED', `Grok skill model is not emitted for ${artifact.name}`, { platform: 'grok' }));
     }
+    if (artifact.claude?.['user-invocable'] === false) {
+        diagnostics.push(diagnostic('warning', 'GROK_SKILL_DISCOVERABLE_UNENFORCED', `${artifact.name} is meant to be background-only, but Grok has no mechanism to hide a skill from direct invocation — it will be directly invocable here`, { platform: 'grok' }));
+    }
     return { content: `${stringifyYaml({ name: artifact.name, description: artifact.description })}${artifact.body}\n`, diagnostics };
 }

package/dist/src/adapters/opencode-known.js

@@ -0,0 +1,15 @@
+// OpenCode has no fixed model enum — models.dev's catalog, filtered to whatever providers the
+// user has credentials for (env var, stored auth, or a config/plugin-declared provider). The
+// `provider/model-id` format is verified (opencode.ai/v2/docs/models: "Provider and model IDs are
+// case-sensitive"); the model id itself MAY contain further slashes (e.g.
+// `openrouter/openai/gpt-5-chat` is provider `openrouter`, model `openai/gpt-5-chat`), so this
+// pattern only requires a first segment before the first `/`, not exactly two segments.
+// OpenCode itself does not validate `model` at load time — a bad value fails only when the agent
+// first runs (ModelNotFoundError) — so this pattern check is a genuine safety net, not redundant.
+// Prefer live discovery (`opencode models`, see src/opencode-discovery.ts) when available; this is
+// the fallback for when that isn't possible (non-interactive install, opencode not on PATH, a v2
+// install predating the `models` command, etc).
+const openCodeModelPattern = /^[A-Za-z0-9][A-Za-z0-9._-]*\/.+$/;
+export function isKnownOpenCodeModel(value) {
+    return openCodeModelPattern.test(value);
+}

package/dist/src/adapters/opencode.js

@@ -1,14 +1,27 @@
 import { stringifyYaml } from '../frontmatter.js';
 import { diagnostic } from '../diagnostics.js';
+import { isKnownOpenCodeModel } from './opencode-known.js';
+import { isOpenCodePermissions } from './shared.js';
 export function renderOpenCodeAgent(artifact) {
+    const diagnostics = [];
     const fm = { description: artifact.description };
     if (artifact.opencode?.mode)
         fm.mode = artifact.opencode.mode;
-    if (artifact.opencode?.model)
+    if (artifact.opencode?.model) {
         fm.model = artifact.opencode.model;
-    if (artifact.opencode?.permissions)
-        fm.permission = artifact.opencode.permissions;
-    return { content: `${stringifyYaml(fm)}${artifact.body}\n`, diagnostics: [] };
+        if (!isKnownOpenCodeModel(artifact.opencode.model)) {
+            diagnostics.push(diagnostic('warning', 'OPENCODE_UNKNOWN_MODEL', `Unknown OpenCode model "${artifact.opencode.model}" for ${artifact.name}`, { platform: 'opencode' }));
+        }
+    }
+    if (artifact.opencode?.permissions) {
+        if (isOpenCodePermissions(artifact.opencode.permissions)) {
+            fm.permission = artifact.opencode.permissions;
+        }
+        else {
+            diagnostics.push(diagnostic('warning', 'OPENCODE_INVALID_PERMISSIONS', `opencode.permissions for ${artifact.name} is not a flat allow/deny/ask object (≤ 64 scalar-valued keys); the block was not emitted`, { platform: 'opencode' }));
+        }
+    }
+    return { content: `${stringifyYaml(fm)}${artifact.body}\n`, diagnostics };
 }
 export function renderOpenCodeSkill(artifact) {
     const diagnostics = [];
@@ -16,5 +29,8 @@ export function renderOpenCodeSkill(artifact) {
         diagnostics.push(diagnostic('info', 'OPENCODE_SKILL_PERMISSIONS_IGNORED', `OpenCode skill permissions are not emitted for ${artifact.name}`, { platform: 'opencode' }));
     if (artifact.opencode?.model)
         diagnostics.push(diagnostic('info', 'OPENCODE_SKILL_MODEL_IGNORED', `OpenCode skill model is not emitted for ${artifact.name}`, { platform: 'opencode' }));
+    if (artifact.claude?.['user-invocable'] === false) {
+        diagnostics.push(diagnostic('warning', 'OPENCODE_SKILL_DISCOVERABLE_UNENFORCED', `${artifact.name} is meant to be background-only, but OpenCode has no mechanism to hide a skill from direct invocation — it will be directly invocable here`, { platform: 'opencode' }));
+    }
     return { content: `${stringifyYaml({ name: artifact.name, description: artifact.description })}${artifact.body}\n`, diagnostics };
 }

package/dist/src/adapters/shared.js

@@ -1,10 +1,11 @@
+import { agentAllowlistPattern } from './claude-known.js';
 export function isRecord(value) {
     return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
 }
 const toolNamePattern = /^[A-Za-z0-9_*-]+$/;
 const patternBodyPattern = /^[^,\n]+$/;
 export function stringList(value) {
-    return Array.isArray(value) && value.every((item) => typeof item === 'string' && toolNamePattern.test(item)) ? value : undefined;
+    return Array.isArray(value) && value.every((item) => typeof item === 'string' && (toolNamePattern.test(item) || agentAllowlistPattern.test(item))) ? value : undefined;
 }
 export function patternList(value) {
     return Array.isArray(value) && value.every((item) => typeof item === 'string' && item.length > 0 && patternBodyPattern.test(item)) ? value : undefined;
@@ -12,3 +13,16 @@ export function patternList(value) {
 export function tomlString(value) {
     return JSON.stringify(value);
 }
+const OPENCODE_PERMISSION_VALUES = new Set(['allow', 'deny', 'ask']);
+const OPENCODE_PERMISSIONS_MAX_KEYS = 64;
+export function isOpenCodePermissions(value) {
+    if (!isRecord(value))
+        return false;
+    const keys = Object.keys(value);
+    if (keys.length === 0 || keys.length > OPENCODE_PERMISSIONS_MAX_KEYS)
+        return false;
+    return keys.every((key) => {
+        const v = value[key];
+        return v === true || v === false || (typeof v === 'string' && OPENCODE_PERMISSION_VALUES.has(v));
+    });
+}