@sorenllm/opencode-forge 0.3.4 → 0.5.0

package/README.md

@@ -33,8 +33,10 @@ OpenSpec spec workflows remain a third, separate lane.
 - Plan files: `.opencode/plan/<date>-<slug>.md` in your project, frontmatter
   state machine `draft → approved → done` (exit: `abandoned`).
 - While a plan is in draft, `write` / `edit` / `bash` / `task` are **denied
-  at the permission layer** — including your own `allow` config. The only
-  exits are approval and discard. This is deliberate; see Design stance.
+  at the permission layer** — including your own `allow` config, and for
+  every agent in that session (the draft protects shared session state; see
+  Agent partition below). The only exits are approval and discard. This is
+  deliberate; see Design stance.
 - `plan_approve` / `plan_close` are pinned to a confirmation dialog: the
   model can never flip the state itself.
 - Goal files: `.opencode/goal/<date>-<slug>.md`, state machine
@@ -42,9 +44,40 @@ OpenSpec spec workflows remain a third, separate lane.
   session plus a workspace queue. Completion is **verified by the plugin**,
   not attested by the model: `goal_complete` re-executes every check itself
   and refuses (fail-closed) on any failure.
-- The native `build` / `plan` agents are hidden while the plugin is loaded
-  (runtime injection, nothing written to your config). Uninstall restores
-  them automatically; plan and goal files are never deleted.
+- The native `build` / `plan` agents **stay installed and independent**:
+  forge coexists with them in the Tab cycle. The plugin hard-partitions the
+  two worlds (see Agent partition below) instead of hiding anything; plan
+  and goal files are never deleted on uninstall.
+
+## Agent partition (who sees what)
+
+The plugin draws a hard line between two agent families, enforced at the
+tool layer (verified against the host's `tools` filter):
+
+| | **forge family** — `forge` + your forge.json `forge-*` workers | **everyone else** — native `build` / `plan` / `general` / `explore` and your own agents |
+| --- | --- | --- |
+| exec surface | `forge_shell` / `forge_jobs` only; builtin `shell`/`bash` hidden (unconditional, probe-independent; covers user-defined `agent.forge` entries too) | builtin `shell`/`bash`, fully native |
+| forge tools (`plan_*`, `goal_*`, `crew_*`, `forge_shell`, `forge_jobs`) | `forge` sees all; `forge-*` workers only `forge_shell` + `forge_jobs` | none visible |
+| dispatching `forge-*` via `task` | allowed | refused at the tool layer |
+| writing `.opencode/plan/` / `.opencode/goal/` | allowed (state machine governs) | refused at the tool layer (reads stay open) |
+| forge system prompts (job guidance, plan/goal notices) | injected | never injected — zero forge text |
+| watchdog (stuck builtin shell) | governed | untouched — no markers, no kills |
+
+Escape hatches: `jobs.keepBuiltinShell: true` gives the forge family the
+builtin shell back; `jobs.mode: "native"` retires `forge_shell`/`forge_jobs`
+entirely (the hide is withdrawn in the same stroke). Mixed sessions (Tab
+between agents in one session): harness state (plans/goals) stays
+session-bound, tool surfaces follow the current speaker, and the goal loop
+parks instead of driving a non-forge turn. One deliberate exception: a
+draft-phase write ban binds the **session** (protecting shared state), so a
+non-forge agent is write-blocked until the draft is approved or discarded in
+forge. Running `/plan` `/goal` `/crew` under a non-forge agent redirects to
+forge instead of executing.
+
+**Default subject.** The host otherwise defaults new sessions to `build`
+once a build agent exists — the plugin pins `default_agent: "forge"`
+automatically (a `default_agent` you set yourself always wins), so bare
+runs and fresh sessions still land on forge under coexistence.
 
 ## Install
 
@@ -78,18 +111,19 @@ the plugin never writes them):
     "forge": {
       "model": "provider/model",   // pick any model for forge
       "disable": true              // one-knob return to native: no forge,
-                                   // build/plan restored, no tools/commands
+                                   // no injections at all, no tools/commands
     }
   },
   // per-plugin options ride the plugin entry as a [spec, options] tuple
   "plugin": [
     ["@sorenllm/opencode-forge", {
       "jobs": {
-        "mode": "auto",              // "auto" (default) | "forge" | "native" — see the stage matrix below
-        "keepBuiltinShell": false    // stage 0: keep the builtin shell visible alongside forge_shell
+        "mode": "auto",              // "auto" (default) | "forge" — equivalent, both keep the partition
+                                     // | "native" — retire the supervisor, builtin shell returns
+        "keepBuiltinShell": false    // true: give the forge family the builtin shell back (the one exec escape hatch)
       },
       "watchdog": {
-        "mode": "kill",              // "kill" (default) | "dry-run" | "off"
+        "mode": "kill",              // "kill" (default) | "dry-run" | "off" — forge-family sessions only
         "stallMs": 600000            // stall threshold, min 60000
       }
     }]
@@ -110,12 +144,14 @@ and the plugin's command of that name is not registered.
    `~/.cache/opencode/packages/github_ChengZiiii/opencode-forge/`).
 3. Delete the `agent["forge"]` block from your config if you added one
    (otherwise the name lingers in the agent list).
-4. Done — the hidden native `build`/`plan` agents come back automatically
+4. Done — all runtime injections (agents, tool hiding, commands) are gone
+   with the plugin; nothing was ever written to your config
    (the hide was runtime-only). Your `.opencode/plan/` and `.opencode/goal/`
    files are yours; delete them yourself if you want.
-5. Optional runtime debris: delete `<tmp>/opencode-forge/` (job logs, the
-   job registry ledger, the watchdog ledger, and the dispatch ledger — the
-   file ledger table above lists everything).
+ 5. Optional runtime debris: delete `<tmp>/opencode-forge/` (job logs, the
+    job registry ledger, the watchdog ledger, and any leftover dispatch
+    ledger from older versions — the file ledger table above lists
+    everything).
 
 ## File ledger
 
@@ -125,13 +161,13 @@ What this plugin touches, exhaustively:
 | --- | --- | --- |
 | `<project>/.opencode/plan/*.md` | plan files | user data — kept forever, uninstall never deletes |
 | `<project>/.opencode/goal/*.md` | goal files (contract, Check Log, Turn Ledger) | user data — kept forever, uninstall never deletes |
-| merged config object (RAM only) | forge agent, native build/plan `disable`, `command.plan`, `command.goal`, goal permission keys, `permission.forge_shell`, stage-0 builtin shell hide | vanishes when the plugin is removed; nothing is written to disk |
+| merged config object (RAM only) | forge agent, static `forge-<id>` subagents, tool-partition injections (forge family shell hide, non-forge forge-tool hide, native build/plan/general/explore minimal entries), `command.plan`, `command.goal`, `command.crew`, goal permission keys, `permission.forge_shell`, `permission.crew_close` | vanishes when the plugin is removed; nothing is written to disk |
 | `<tmp>/opencode-forge/jobs/<jobId>.log` | job output tee (full output; oldest rotated out above 50 files) | runtime debris — delete freely, also after uninstall |
 | `<tmp>/opencode-forge/jobs/ledger.jsonl` | job registry ledger (bounded: 1 MB reset, 200 entries) | runtime debris — delete freely, also after uninstall |
 | `<tmp>/opencode-forge/jobs/registry.json` | persistent survivor registry (bounded: 100 entries) | runtime debris — after uninstall, kill any still-running `survive` jobs yourself first |
 | `<tmp>/opencode-forge/watchdog/log.jsonl` | watchdog interventions ledger (bounded: 200 entries, oldest rotated) | runtime debris — delete freely, also after uninstall |
-| `<tmp>/opencode-forge/dispatch/ledger.jsonl` | dispatch ledger: resolved identity/depth, outcomes, tokens/cost, timeouts, transport interruptions, lost-on-exit, crew summaries (bounded, capped rotation) | runtime debris — delete freely, also after uninstall |
-| `<project>/.opencode/forge.json`, `~/.config/opencode/forge.json` | your dispatch agent definitions (JSONC). **User data — the plugin only reads it, never writes or migrates it** | yours — version the project one, keep the global one out of sync tools if it holds machine-specific models |
+| `<tmp>/opencode-forge/dispatch/ledger.jsonl` | dispatch ledger — **no longer written** (the dispatch engine was removed); only present as inert debris from older versions | runtime debris — delete freely |
+| `<project>/.opencode/forge.json`, `~/.config/opencode/forge.json` | your static subagent definitions (JSONC). **User data — the plugin only reads it, never writes or migrates it** | yours — version the project one, keep the global one out of sync tools if it holds machine-specific models |
 | `~/.cache/opencode/packages/...` | installed package copy | written by the `opencode plugin` installer, not the plugin |
 | `~/.config/opencode/opencode.json` | `plugin` array entry | written by the installer |
 
@@ -292,19 +328,20 @@ as usual. Config `jobs.survive: "always"` flips the per-call default; config
 whose pid died are detected at next start, ledgered as orphans, and dropped
 from the registry. Stop survivors explicitly — nothing else will.
 
-### Stage matrix (future compatibility, by design)
+### Mode matrix (supervisor lifecycle)
 
-OpenCode upstream is converging on native backgrounding (PRs #47231 /
-#50276, umbrella #34366). The supervisor degrades ahead of it:
+The old three-stage capability probe is retired: the forge-side partition
+holds regardless of what the host's builtin shell can do, so `auto` and
+`forge` are equivalent. Only the manual `native` mode retires the
+supervisor:
 
-| stage | how you get there | builtin shell | forge_shell / forge_jobs |
+| mode | how you get there | builtin shell (forge family) | forge_shell / forge_jobs |
 | --- | --- | --- | --- |
-| 0 — full forge path | default (`jobs.mode: "auto"`, no native support detected) | hidden on the plugin-created forge agent (runtime injection only) | registered; the exec surface |
-| 1 — native backgrounding detected | automatic: `config.experimental` background flag, or the builtin shell's schema grows `run_in_background` | visible again | still registered as the additive layer (idle/success/wake supervision); its description now points plain backgrounding at the native parameter |
-| 2 — native confirmed complete | manual only: `jobs.mode: "native"` (never auto-detected — completeness is a semantic judgement) | visible | retired; calls throw with a pointer to the native parameter |
+| auto (default) / forge | nothing to do | hidden — the exec surface is forge_shell, always | registered |
+| native | manual only: `jobs.mode: "native"` | restored | retired; calls throw with a pointer to the native parameter |
 
-Pin `jobs.mode: "forge"` to stay on stage 0 forever; `jobs.keepBuiltinShell:
-true` keeps the builtin shell visible at any stage.
+`jobs.keepBuiltinShell: true` gives the forge family the builtin shell back
+in any mode (the watchdog keeps governing those calls).
 
 ### Artifacts and uninstall additions
 
@@ -319,163 +356,144 @@ These are runtime debris, not data — with ONE caveat: **if you uninstall with
 /F /T`, or just reboot); deleting the directory afterwards is safe and
 complete.
 
-## Worker dispatch (scoped subagents on a chosen model + depth)
+## Forge subagents (static worker agents in forge.json)
+
+Forge subagents are **static, user-authored worker agents**: each forge.json
+entry pins a model and an optional reasoning depth, materializes as a native
+`forge-<id>` subagent, and is dispatched through the host's **native `task`
+tool** — which means every run is visible in the TUI, expandable and
+monitorable, exactly like any native subagent. There is no dispatch tool, no
+child-session engine, and no configuration invitation anywhere: the session
+AI never writes your config.
 
-`forge_dispatch {prompt, agent, depth}` spawns a child session that runs one
-scoped task on the agent's pinned model at the requested reasoning depth. The
-result is an honest report: the actual model/depth used, real token counts, a
-self-computed cost (`null` when the model is unpriced), the
-`depthTranslation` disclosure (`canonical high → native XHigh`, or
-`verbatim`), and the worker's concluding report.
+No forge.json? Nothing happens — the plugin registers nothing and the native
+subagent behavior is untouched. Onboarding is this README, for you the human.
 
-### forge.json — the dispatch configuration
+### forge.json — the configuration
 
-Agents live in a dedicated `forge.json` (JSONC — comments allowed), resolved
-by a three-level cascade with a single winning source (never merged):
+A dedicated `forge.json` (JSONC — comments allowed), resolved by a two-level
+cascade with a single winning source (never merged):
 
 1. `<project>/.opencode/forge.json` — project-level, versionable, team-shared
 2. `~/.config/opencode/forge.json` — global
-3. the built-in seed — `research {depths: [low, medium]}` and
-   `review {depths: [medium, high, max]}`, both pinned to the placeholder
-   `Local/GPT Luna` (an identity that never resolves: an unconfigured install
-   fails every dispatch with the configuration recipe below)
 
 ```jsonc
 {
-  // forge dispatch agents — save the file; changes apply on the next dispatch, no restart
+  // forge subagents — definitions; see the restart table below for apply timing
   "agents": {
     "research": {
-      "model": "zai-coding-plan/glm-5.3", // exact "provider/model" string
-      "depths": ["low", "medium"], // first entry is the default
-      // "prompt": "optional role prompt riding inside the discipline wrapper",
-      // "shape": "write", // default readonly denies mutating tools
-      // "permission": { "bash": "deny" } // optional override; "task" is always denied
+      "model": "zai-coding-plan/glm-5.3", // exact "provider/model" string — REQUIRED
+      "thoughtLevel": "low",              // optional: none/low/medium/high/max or a native level name
+      // "prompt": "optional role prompt; built-in research/review defaults exist",
+      // "shape": "write",   // default readonly denies write/edit/bash
+      // "permission": { "bash": "deny" } // optional override; "task" is ALWAYS denied
     }
   }
 }
 ```
 
 - **The plugin only ever reads this file.** It never creates, writes, or
-  migrates it. Unconfigured? The first `forge_dispatch` error carries a
-  machine-actionable recipe (detected identities, both file paths, the
-  template, a verify dispatch) — or just ask your session AI to configure
-  dispatch; `forge_dispatch_config` shows the exact live state.
-- **Hot-apply**: the file is re-read (mtime-cached) before every dispatch and
-  on every `forge_dispatch_config` call — edits take effect on the next
-  dispatch, no host restart. One boundary: newly added agents materialize
-  their hidden `forge-<agent>` entry only on the next config reload; the
-  dispatch itself still works (the body names the agent), but a brand-new
-  agent's first dispatch may need a host reload if the host validates agent
-  names on session create.
-- Each agent materializes as a hidden `mode: subagent` agent `forge-<agent>`
-  carrying the role prompt (explicit `prompt` > built-in research/review
-  defaults > generic worker) and a deny-style permission: `shape: "readonly"`
-  (the default) denies `write`/`edit`/`bash`, `shape: "write"` allows them,
-  an explicit `permission` map overrides the shape default — and `task` is
-  ALWAYS denied (recursive dispatch stays physically impossible). Agents
-  never carry a `model` field; the brain is bound per dispatch.
-
-### The depth metalanguage
-
-`depth` comes from the canonical five-word set `none | low | medium | high |
-max`, or the model's **native level names verbatim** (escape hatch — e.g.
-Qwen's `XHigh`). Translation to the provider's native parameter follows three
-hard rules:
-
-- **verbatim-first**: a meta word the model natively offers passes as-is
-- **no interpolation**: a meta word with no counterpart errors listing both
-  vocabularies — never a nearest guess
-- **full disclosure**: the report always shows `canonical → native`
-
-Per family: effort-style providers (OpenAI-compatible) receive
-`reasoningEffort = <word>`; budget-style (Anthropic-style) receive a
-published thinking tier — `low → 8192`, `medium → 16384`, `high → 24576`,
-`max → 32768` budget tokens, `none → thinking off`; toggle-style (zai/GLM)
-receive thinking on/off (that shape has no level slot — disclosed honestly).
-A provider whose option shape the plugin does not know gets nothing injected,
-disclosed as `not injected (unknown provider shape)`. The provider is the
-final judge of every depth word: its raw errors flow back unedited.
-
-### Legacy inline roster (advanced)
-
-The pre-forge.json inline form still works when configured (the plugin
-options `dispatch.roster` / `dispatch.tiers`): tier ids it defines keep their
-exact-match resolution, one-retry-excluding-a-failed-identity semantics, and
-startup dead-key warnings. Legacy tier ids win over forge.json agents of the
-same name while inline options exist. Zero-config auto-generation of roster
-entries was removed (configured ≠ usable) — dispatch without configuration is
-the seed + recipe path above.
-
-### Background dispatch and wake briefs
-
-`forge_dispatch` takes `background: true`: it returns
-`{dispatchId, agent, requested, resolved, depth, queuedAt}` immediately and
-the full result arrives later as a coalesced `[forge:dispatch-complete]`
-brief — debounced, never interrupting an active turn (delivery waits for an
-idle), each terminal delivered exactly once, and merged into a single
-combined re-prompt when a goal continuation fires on the same idle.
-`forge_dispatch_list` recovers in-flight and recent terminal state (with
-dispatchIds) after context compaction; `forge_dispatch_kill {dispatchId}`
-stops polling, suppresses the brief, and ledgers `killed`. On host exit,
-in-flight dispatches are ledgered `lost-on-exit` — sessions are host memory
-objects, there are no orphan processes and no survive semantics.
-
-**Transport-interruption recovery**: the child's prompt is delivered by a
-turn-synchronous HTTP POST that stays open for the whole first turn. If that
-POST dies at the transport layer (fetch abort / network failure — anything
-that is not an HTTP error response), the dispatch does **not** fail: the
-engine ledgers `transport-interrupted` (with the child sessionID) and falls
-back to completion polling under the same deadline — the child session is a
-host-side object and usually keeps running, so its result is still collected
-and delivered normally. The message is never re-POSTed (the prompt may
-already be delivering); a message that never arrived polls as waiting and
-ends in the honest deadline `timeout`. Terminal reports and terminal ledger
-rows carry the child sessionID, dispatchId, parentSessionID, and durationMs.
-
-### Crew workflow (`/crew`)
-
-`/crew <objective>` registers a crew: decompose the objective into
-evidence-checked subtasks, dispatch them as background waves paced on
-completion briefs (**never past the concurrency cap — launch the next batch
-only as briefs free capacity**), at most ONE retry per failed subtask, then
-`crew_close` with the full report. The close is a hard gate: every subtask
-needs a PASS/FAIL verdict with evidence, a FAIL needs both failure reports,
-and the report is cross-checked against the dispatch ledger — a dispatched
-subtask missing from the report refuses the close (refusals never bother you
-with a dialog). A valid close asks once, appends a crew summary to the
-ledger, and ends the crew. Crew state is in-memory by design: a host restart
-ends it honestly and the ledger keeps the history.
-
-### Known pitfalls
-
-- **Keyless endpoints × readonly agents**: free/keyless providers can return
-  a deterministic EMPTY response for any toolset-reduced (readonly) agent —
-  0 tokens, no parts. The plugin detects this and fails the dispatch honestly
-  (`empty-response`, never counted as success); use a `shape: "write"` agent
-  or a keyed provider for readonly work on such endpoints.
-- **`opencode run` and background**: a finished run-mode session cannot be
-  re-prompted, so completion briefs have nowhere to land — completions are
-  ledger-only (read them via `forge_dispatch_list`). Background mode targets
-  live TUI sessions; prefer sync under `opencode run`.
-- **Host tool ceiling (~262s observed on 1.18.32)**: the host may kill a
-  sync tool call that exceeds roughly 262 seconds even though the plugin's
-  own deadline is higher. A same-family transport abort (~281s observed,
-  2026-09-27 incident) can also kill the background dispatch's turn POST.
-  Transport-interruption recovery (above) absorbs both: the dispatch falls
-  back to polling and still delivers the child's result; keep `timeoutMs`
-  modest anyway for sync-heavy workflows.
-- **Child permission asks**: a worker that hits a permission ask surfaces the
-  ask on the CHILD's session in the TUI. An unanswered ask stalls the child
-  until the dispatch deadline — scope worker prompts to avoid permission
-  boundaries (readonly tiers and workspace-relative paths help).
+  migrates it. The old AI-authored onboarding path (seed placeholder +
+  error recipe) is gone: an unconfigured host is inert and silent, and the
+  session AI is never invited to touch config. The ONE exception is the
+  `/crew` initialization gate (below), where AI-assisted configuration is
+  offered to YOU and happens only on your explicit go-ahead.
+- **Parsing is field-level fail-soft** (ZCode-style): a semantically bad
+  agent entry is skipped with an error finding while its siblings apply; a
+  mistyped optional field is ignored with a warning; a syntactically broken
+  file empties the agent set with one parse-location error. There is no seed
+  in any failure path. Findings surface in the plugin diagnostics log.
+- **`depths` is deprecated**: the array is ignored with a warning finding.
+  Pin ONE `thoughtLevel` per agent instead.
+- Each agent materializes as `forge-<id>` — a subagent-mode agent visible in
+  the task tool's vocabulary (never hidden), carrying the pinned `model`,
+  the worker discipline (workspace-relative paths only, verbatim reporting
+  of tool refusals, evidence-bearing conclusions) around its role prompt,
+  and a deny-style permission: `shape: "readonly"` (the default) denies
+  `write`/`edit`/`bash`, `shape: "write"` allows them, an explicit
+  `permission` map overrides the shape default — and `task` is ALWAYS
+  denied (recursive spawning stays physically impossible).
+
+**What applies when** — edits take hold per field:
+
+| change | needs a host restart? |
+| --- | --- |
+| `thoughtLevel` on an existing agent | no (applies to NEW sessions of that agent; running sessions keep their frozen depth) |
+| agent added / removed, or `model` / `prompt` / `permission` changed | yes (materialization runs on the config hook) |
+
+### Dispatching
+
+Say "dispatch a subagent..." in a forge session and the model picks from the
+task tool vocabulary: a configured `forge-*` agent whose description matches
+runs on its pinned brain; if none matches, forge is instructed to say so
+plainly and fall back to the native task channel. During a plan draft the
+native `task` tool is already denied by the plan harness — no plugin-side
+rule needed.
+
+**Known pitfall — keyless endpoints × readonly agents**: free/keyless
+providers can return a deterministic EMPTY response for any toolset-reduced
+(readonly) agent. On the native task channel this now surfaces as a visible,
+attributable task failure; the mitigation is unchanged — use
+`shape: "write"` for such endpoints, or a keyed provider.
+
+### The thoughtLevel word
+
+One word per agent: the canonical `none | low | medium | high | max`, or the
+model's native level name verbatim (e.g. Qwen's `XHigh`). Injection rides the
+`chat.params` hook keyed by agent name, translated per provider family:
+effort-style (OpenAI-compatible) receives `reasoningEffort = <word>`;
+budget-style (Anthropic-style) receives a published thinking tier
+(`low → 8192`, `medium → 16384`, `high → 24576`, `max → 32768`,
+`none → off`); toggle-style (zai/GLM) receives thinking on/off. Rules:
+verbatim-first, no interpolation, unknown family injects nothing. A word the
+model does not natively offer injects NOTHING and records one finding naming
+both vocabularies — the session is never broken by a config word. A
+session's depth is frozen at its first request (editing forge.json
+mid-session never rewrites a running session).
+
+## Crew workflow (`/crew`)
+
+`/crew <objective>` is the third state-activation command next to `/plan` and
+`/goal`: it enters crew orchestration discipline for the session. The flow:
+
+1. **Register** the declared plan: `crew_begin {objective, subtasks}` — one
+   titled subtask each, optionally naming the intended `forge-*` agent.
+2. **Execute in waves** of parallel native `task` calls (results return
+   in-turn; the next wave launches only after the previous wave's results).
+3. **Missing role?** Run the subtask through a native task call anyway and
+   tell the user — suggest configuring the missing role.
+4. **Verify** each subtask against its acceptance-evidence statement;
+   retry a failure at most once.
+5. **Close** with `crew_close` — a hard, ask-gated gate cross-checking the
+   report against the DECLARED plan: every declared subtask needs a
+   PASS/FAIL verdict with evidence; an undeclared subtask in the report
+   refuses the close (fold discoveries into an existing verdict, or discard
+   and re-crew); a FAIL needs both failure reports. The close output is the
+   crew's record — crew state is in-memory and a host restart ends it
+   honestly.
+
+**Not initialized?** `/crew` on a host with zero usable forge agents refuses
+with one-time setup guidance: the two file paths, a copy-paste template, and
+the choice of configuring it yourself OR having the session AI do it — the
+latter only on your explicit go-ahead in that conversation, through the
+normal visible write path. This is the plugin's only configuration
+invitation. After saving the file, restart opencode to materialize the
+agents.
+
+### Debris note
+
+The old dispatch suite's ledger at `<tmp>/opencode-forge/dispatch/` is no
+longer written. If it exists on your machine it is inert runtime debris —
+delete the directory freely, also after uninstalling.
 
 ## Hang watchdog (a stuck builtin shell unblocks itself)
 
 `forge_shell` is structurally immune to the stdio-EOF hang, but the builtin
-`shell`/`bash` tool can still hang outside it — user-defined agents keep
-the builtin shell, and the stage matrix above restores it at stage 1/2.
-The watchdog is the independent backstop for those paths, in **every**
-session (primary and delegated subagents alike):
+`shell`/`bash` tool can still hang outside it — under `jobs.mode: "native"`
+or `jobs.keepBuiltinShell: true`, forge-family sessions carry it again. The
+watchdog is the independent backstop for those paths, in **forge-family
+sessions only** (primary and delegated forge-* workers alike) — non-forge
+agents' builtin shells are entirely native: no markers, no timing, no kills:
 
 1. The host's shell environment hook stamps each builtin shell call's
    process with a plugin-namespaced marker (`FORGE_WATCHDOG_MARK`), and the
@@ -538,11 +556,12 @@ read/grep/glob; if you genuinely need a shell command to decide the plan,
 approve the plan first (revising after approval is allowed via a new `/plan`).
 The escape hatches are `plan_approve` and `/plan discard`, by design.
 
-Separately, at stage 0 the builtin shell is hidden on the plugin-created
-forge agent on purpose — `forge_shell` is the exec surface there (see the
-job supervisor chapter above). A **user-defined** `agent.forge` entry,
-`jobs.keepBuiltinShell: true`, or any stage ≥ 1 keeps the builtin shell
-visible.
+Separately, the builtin shell is hidden on the forge agent on purpose —
+`forge_shell` is the exec surface there (see Agent partition and the job
+supervisor chapter above). The hide is unconditional: it covers a
+**user-defined** `agent.forge` entry too. The escape hatches are
+`jobs.keepBuiltinShell: true` (builtin shell back on the forge family) and
+`jobs.mode: "native"` (supervisor retired entirely).
 
 A process restart forgets the session binding: the write-ban soft-disables
 (safety over strictness) and the next session's system notice + `/plan