thoth-agents 0.2.9 → 0.2.10

package/README.md

@@ -22,8 +22,9 @@ surface that fits it best.
 OpenCode remains the stable default path: native plugin install, native `task`
 delegation, optional tmux monitoring, and generated config. Codex is supported
 through an explicit agent-pack and Personal plugin setup path, with documented
-trust review and instruction-level governance caveats where Codex does not
-provide the same hard runtime controls. Claude Code is a first-class path: a
+trust review and the current `collaboration.*` delegation surface. Codex can
+spawn and coordinate generic tasks programmatically, while named installed-role
+selection and per-role enforcement remain instruction-level. Claude Code is a first-class path: a
 single auto-discovered plugin package with native subagents, harness-enforced
 hooks, MCP, skills, and per-agent tool permissions.
 
@@ -55,7 +56,7 @@ hooks, MCP, skills, and per-agent tool permissions.
 | Harness     | Status                     | Setup path                                                                              | Notes                                                                                                                                                                                                                                                 |
 | ----------- | -------------------------- | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | OpenCode    | Stable default             | `npx thoth-agents@latest install` or `npx thoth-agents@latest install --agent=opencode` | Native plugin config, native`task` delegation, optional tmux panes, OpenCode provider auth.                                                                                                                                                           |
-| Codex       | Supported explicit path    | `npx thoth-agents@latest install --agent=codex`                                         | Installs ambient/root guidance, six role subagents, and a Personal plugin source. Requires`/plugins` and `/hooks` trust review. Some governance remains instruction-level.                                                                            |
+| Codex       | Supported explicit path    | `npx thoth-agents@latest install --agent=codex`                                         | Installs ambient/root guidance, six role subagents, and a Personal plugin source. Uses the current `collaboration.*` tools for generic delegation; named-role selection and per-role enforcement remain instruction-level. Requires `/plugins` and `/hooks` trust review. |
 | Claude Code | Supported first-class path | `npx thoth-agents@latest install --agent=claude`                                        | Installs one Claude Code plugin: six specialist subagents (`Task(subagent_type: ...)`), an `orchestrator` agent activated as the main thread via `settings.json`, `.mcp.json`, and bundled skills. Role permissions are enforced by subagent `tools`. |
 
 OpenCode can load the plugin with:
@@ -128,6 +129,12 @@ Codex install does not create a selectable orchestrator TOML, does not bypass
 trust review, and does not make role permissions or memory governance hard
 runtime guarantees unless Codex exposes those controls.
 
+Generated root guidance binds delegation to direct `collaboration.*` tools:
+`spawn_agent({ task_name, message, fork_turns? })`, mailbox-oriented
+`wait_agent`, live status through `list_agents`, non-triggering `send_message`,
+turn-triggering `followup_task`, and explicit `interrupt_agent`. A wait timeout
+or silence remains in progress; it is not a collected result body.
+
 ### Claude Code
 
 Preview, then install the plugin package:
@@ -363,7 +370,7 @@ supports that delivery surface.
 | ---------------- | ---------------------------------------------- | ------------------------------------------------------------ | ---------------------------------------------------------------- | ----------------------------------------------------------------- |
 | Skills           | Requirements, SDD, review, execution workflows | Copied into the OpenCode skills directory when`--skills=yes` | Packaged as plugin-bundled skills for the Personal plugin source | Bundled in the plugin`skills/` directory                          |
 | MCPs             | `exa`, `context7`, `grep_app`, `thoth_mem`     | Registered by generated OpenCode plugin config               | Packaged/configured only on validated Codex surfaces             | Bundled in the plugin`.mcp.json` (`type: "http"` for URL servers) |
-| Delegation       | Seven-role specialist workflow                 | Native`task` tool                                            | Custom agents plus prompt/plugin guidance                        | Native`Task(subagent_type: ...)` over auto-discovered subagents   |
+| Delegation       | Seven-role specialist workflow                 | Native`task` tool                                            | Direct `collaboration.*` generic task delegation; role behavior carried by task name/message | Native`Task(subagent_type: ...)` over auto-discovered subagents   |
 | Blocking choices | Use a structured question surface              | OpenCode`question` tool                                      | `request_user_input` when enabled and available                  | `AskUserQuestion` tool                                            |
 
 See [docs/skills-and-mcps.md](docs/skills-and-mcps.md) for the detailed matrix.

package/dist/agents/prompt-dialects.d.ts

@@ -1,6 +1,13 @@
 import type { AgentDispatchMethod, AgentRoleName } from '../harness/core/agent-pack';
 import type { HarnessCapabilities, HarnessId } from '../harness/types';
 export type AgentPromptRole = AgentRoleName;
+export interface LifecycleNomenclature {
+    statusAction: string;
+    terminalState: string;
+    nonterminalState: string;
+    sameSessionProbe: string;
+    enforcement: 'runtime-supported' | 'instruction-only' | 'unknown';
+}
 export interface ToolNomenclature {
     delegationTool: string;
     backgroundDelegationTool?: string;
@@ -8,6 +15,7 @@ export interface ToolNomenclature {
     userQuestionTool: string;
     progressTool: string;
     hostStatusSurface?: string;
+    lifecycle: LifecycleNomenclature;
     roleReference(role: AgentPromptRole): string;
 }
 export interface CapabilityProfile {

package/dist/{chunk-75JOF37E.js → chunk-MF5NNCPC.js}

@@ -13,7 +13,7 @@ import {
   getStepBudgetPromptSection,
   loadAgentPrompt,
   renderRolePrompt
-} from "./chunk-YLRPDTU7.js";
+} from "./chunk-WBRGPRRB.js";
 
 // src/agents/deep.ts
 var DEEP_PROMPT = renderRolePrompt(

package/dist/{chunk-YLRPDTU7.js → chunk-WBRGPRRB.js}

@@ -710,8 +710,8 @@ var OPENCODE_CAPABILITIES = {
 };
 var CODEX_PROMPT_CAPABILITIES = {
   agentDefinitions: "supported",
-  delegatedExecution: "instruction-only",
-  parallelDelegation: "instruction-only",
+  delegatedExecution: "supported",
+  parallelDelegation: "supported",
   runtimeHooks: "unknown",
   mcpConfiguration: "supported",
   skillPackaging: "supported",
@@ -755,6 +755,13 @@ var OPENCODE_PROMPT_DIALECT = {
     userQuestionTool: "question",
     progressTool: "todowrite",
     hostStatusSurface: "task_status",
+    lifecycle: {
+      statusAction: "wait, poll, and collect",
+      terminalState: "terminal task_status result",
+      nonterminalState: "nonterminal task_status result",
+      sameSessionProbe: "task_status on the same task session",
+      enforcement: "runtime-supported"
+    },
     roleReference: (role) => `@${role}`
   },
   capabilities: supportedCapabilityProfile(OPENCODE_CAPABILITIES),
@@ -775,12 +782,19 @@ var OPENCODE_PROMPT_DIALECT = {
 var CODEX_PROMPT_DIALECT = {
   harness: "codex",
   tools: {
-    delegationTool: "multi_agent_v1.spawn_agent",
-    backgroundDelegationTool: "multi_agent_v1.spawn_agent",
-    backgroundStatusTool: "multi_agent_v1.wait_agent",
+    delegationTool: "collaboration.spawn_agent",
+    backgroundDelegationTool: "collaboration.spawn_agent",
+    backgroundStatusTool: "collaboration.wait_agent",
     userQuestionTool: "request_user_input",
     progressTool: "functions.update_plan",
-    hostStatusSurface: "multi_agent_v1.wait_agent",
+    hostStatusSurface: "collaboration.list_agents",
+    lifecycle: {
+      statusAction: "wait and inspect status",
+      terminalState: "terminal mailbox completion or failure update",
+      nonterminalState: "collaboration.wait_agent timeout or silence",
+      sameSessionProbe: "collaboration.list_agents on the same task path",
+      enforcement: "runtime-supported"
+    },
     roleReference: (role) => `${role} role agent`
   },
   capabilities: {
@@ -792,9 +806,9 @@ var CODEX_PROMPT_DIALECT = {
       case "root-coordinator":
         return "ambient Codex root session coordinator";
       case "task":
-        return "multi_agent_v1.spawn_agent";
+        return "collaboration.spawn_agent";
       case "synchronous-task-only":
-        return "synchronous multi_agent_v1.spawn_agent only";
+        return "synchronous collaboration.spawn_agent only";
     }
   },
   renderRoleInvocation(role) {
@@ -814,6 +828,13 @@ var CLAUDE_CODE_PROMPT_DIALECT = {
     userQuestionTool: "AskUserQuestion",
     progressTool: "TodoWrite",
     hostStatusSurface: "TodoWrite",
+    lifecycle: {
+      statusAction: "wait, poll, and collect",
+      terminalState: "terminal TaskOutput result",
+      nonterminalState: "nonterminal TaskOutput result",
+      sameSessionProbe: "TaskOutput on the same task session",
+      enforcement: "runtime-supported"
+    },
     roleReference: (role) => role === "orchestrator" ? "the main-thread orchestrator" : `Task(subagent_type: ${claudeCodeSubagentType(role)})`
   },
   capabilities: supportedCapabilityProfile(CLAUDE_CODE_PROMPT_CAPABILITIES),
@@ -943,6 +964,7 @@ var SDD_PHASES = [
     artifactSkill: "sdd-tasks",
     defaultAgentRole: "quick",
     alternateAgentRoles: ["deep"],
+    alternateAgentCondition: "Only when the task plan is complex.",
     delegationReason: "Mechanical conversion of settled design into dependency-ordered execution tasks."
   },
   {
@@ -1131,6 +1153,10 @@ function alternateSddRoles(id) {
   const phase = getDelegatedSddPhase(id);
   return phase.alternateAgentRoles?.length ? renderRoleList(phase.alternateAgentRoles) : "";
 }
+function alternateSddCondition(id) {
+  const condition = getDelegatedSddPhase(id).alternateAgentCondition;
+  return condition ? condition.replace(/^Only/, "only").replace(/\.$/, "") : "";
+}
 function supportSddRoles(id) {
   const phase = getDelegatedSddPhase(id);
   return phase.supportingAgentRoles?.length ? renderRoleList(phase.supportingAgentRoles) : "";
@@ -1142,7 +1168,7 @@ function persistenceSddRole(id) {
 function renderSddDelegationMatrix() {
   return `<sdd-delegation-matrix>
 - sdd-init -> ${primarySddRole("init")} (+${supportSddRoles("init")}, if openspec/ missing); sdd-explore -> ${primarySddRole("explore")} (+${supportSddRoles("explore")})
-- sdd-propose/sdd-spec/sdd-design -> ${primarySddRole("proposal")}; sdd-clarify -> ${primarySddRole("clarify")}; sdd-tasks -> ${primarySddRole("tasks")} (fallback: ${alternateSddRoles("tasks")})
+- sdd-propose/sdd-spec/sdd-design -> ${primarySddRole("proposal")}; sdd-clarify -> ${primarySddRole("clarify")}; sdd-tasks -> ${primarySddRole("tasks")} (fallback: ${alternateSddRoles("tasks")} ${alternateSddCondition("tasks")})
 - plan-reviewer -> ${primarySddRole("plan-review")}; sdd-apply -> ${primarySddRole("apply")} (fallback: ${alternateSddRoles("apply")}); sdd-verify -> ${primarySddRole("verify")} (persistence: ${persistenceSddRole("verify")}); sdd-archive -> ${primarySddRole("archive")}
 </sdd-delegation-matrix>`;
 }
@@ -1280,11 +1306,9 @@ For {{role.explorer}}/{{role.librarian}}, ask narrow fact-finding questions for
 - Experimental background \`{{backgroundDelegationTool}}\` is allowed only for {{role.explorer}} and {{role.librarian}} for asynchronous delegation.
 - {{role.oracle}}, {{role.designer}}, {{role.quick}}, and {{role.deep}} always use normal synchronous \`{{delegationTool}}\` execution.
 - When using background \`{{delegationTool}}\`, treat it as conditional and non-portable: if the host does not expose the experimental path, fall back to normal synchronous \`{{delegationTool}}\`.
-- Use \`{{backgroundStatusTool}}\` to wait, poll, and collect background task results before synthesizing or reporting completion.
-- If a result is empty, contradictory, or low-confidence, retry once with a materially sharper prompt; then escalate with evidence via \`{{userQuestionTool}}\`.
-- If a named subagent hits capacity, retry that same role up to 3 attempts.
-- Never switch to \`default\`, \`worker\`, or any other role.
-- After 3 failures, stay on the same role; if a same-role model override exists, use it. Otherwise report a capacity blocker.
+- Use \`{{backgroundStatusTool}}\` to {{lifecycleStatusAction}}: treat \`{{lifecycleNonterminalState}}\` as in progress and probe the same session via \`{{lifecycleSameSessionProbe}}\`; no retry/reroute/interruption before \`{{lifecycleTerminalState}}\`, an explicit user deadline, user cancellation, or a superseding request.
+- Terminal result-quality and required-artifact checks share one sharpened retry; nonterminal probes use none.
+- Capacity is separate: retry the named role up to 3 times; never switch to \`default\`, \`worker\`, or another role; then use a same-role model override or report a blocker.
 - Write-capable dispatches must include task instructions and handoff retrieval instructions when a root-owned handoff summary exists, so implementers can recover context without rediscovering settled scope.
 - Never tell sub-agents to discard working-tree changes.
 </dispatch>
@@ -1311,7 +1335,6 @@ Hard gates:
 - Group consecutive ready SDD tasks for the same execution agent into one dispatch when dependencies, scope, and verification can be handled together. Keep per-task tracking and evidence; do not split a compatible {{role.designer}}/{{role.quick}}/{{role.deep}} run into one delegation per checkbox.
 
 SDD dispatch envelope must include: skill name, persistence mode, pipeline type, change name, project name, needed prior artifact context, verification expectation, and return envelope.
-After each phase, verify the sub-agent reported the openspec path and/or thoth-mem topic_key. Retry once if missing.
 
 Artifact governance handoff:
 - After \`sdd-tasks\`, you may surface report-only artifact governance findings before execution preparation starts.
@@ -1614,7 +1637,19 @@ function renderRoleText(section, dialect) {
   ).replaceAll(
     "{{backgroundStatusTool}}",
     dialect.tools.backgroundStatusTool ?? dialect.tools.hostStatusSurface ?? ""
-  ).replaceAll("{{userQuestionTool}}", dialect.tools.userQuestionTool).replaceAll("{{progressTool}}", dialect.tools.progressTool).replaceAll("{{dispatch.task}}", dialect.dispatchLabel("task")).replaceAll(
+  ).replaceAll("{{userQuestionTool}}", dialect.tools.userQuestionTool).replaceAll("{{progressTool}}", dialect.tools.progressTool).replaceAll(
+    "{{lifecycleStatusAction}}",
+    dialect.tools.lifecycle.statusAction
+  ).replaceAll(
+    "{{lifecycleTerminalState}}",
+    dialect.tools.lifecycle.terminalState
+  ).replaceAll(
+    "{{lifecycleNonterminalState}}",
+    dialect.tools.lifecycle.nonterminalState
+  ).replaceAll(
+    "{{lifecycleSameSessionProbe}}",
+    dialect.tools.lifecycle.sameSessionProbe
+  ).replaceAll("{{dispatch.task}}", dialect.dispatchLabel("task")).replaceAll(
     "{{dispatch.synchronous-task-only}}",
     dialect.dispatchLabel("synchronous-task-only")
   ).replace(

package/dist/{chunk-6NMPKYWY.js → chunk-YYVE7YHR.js}

@@ -37,7 +37,7 @@ import {
   renderRolePrompt,
   writeConfig,
   writeLiteConfig
-} from "./chunk-YLRPDTU7.js";
+} from "./chunk-WBRGPRRB.js";
 
 // src/cli/codex-paths.ts
 import { homedir } from "os";
@@ -611,26 +611,31 @@ var CODEX_SURFACES = [
     id: "per-agent-runtime-permissions",
     target: "permission-control",
     status: "unsupported",
-    fields: ["per-agent tool allow/deny equivalent to OpenCode permissions"],
+    fields: [
+      "named installed-role selection",
+      "per-role permission enforcement",
+      "per-agent tool allow/deny equivalent to OpenCode permissions"
+    ],
     diagnosticCode: "codex.permission.memory.enforcement_gap",
-    summary: "Codex sandbox and approval policy can constrain sessions, but OpenCode-style per-agent MCP/tool deny maps are not validated.",
+    summary: "Named installed-role selection and per-role permission enforcement are instruction-only because collaboration.spawn_agent has no role selector; OpenCode-style per-agent MCP/tool deny maps are not validated.",
     evidence: "Codex approvals/security docs cover sandbox and approval policies, not exact OpenCode per-agent permission maps.",
     fallback: "instruction-only"
   },
   {
     id: "programmatic-delegation-runtime",
     target: "delegation-runtime",
-    status: "unsupported",
+    status: "validated",
     fields: [
-      "task API",
-      "background task sessions",
-      "tmux lifecycle hooks",
-      "automatic subagent session close"
+      "collaboration.spawn_agent",
+      "collaboration.wait_agent",
+      "collaboration.list_agents",
+      "collaboration.send_message",
+      "collaboration.followup_task",
+      "collaboration.interrupt_agent"
     ],
-    diagnosticCode: "codex.delegation.runtime.unsupported",
-    summary: "Codex subagents are user/instruction-triggered; no OpenCode plugin task API or automatic subagent session close parity is validated.",
-    evidence: "Codex subagents docs describe manual spawning and agent threads, not this plugin runtime task API or a validated runtime close hook.",
-    fallback: "instruction-only"
+    diagnosticCode: "codex.delegation.runtime.validated",
+    summary: "The current Codex collaboration surface supports generic programmatic delegation, mailbox waits, live task-tree inspection, messages, follow-up turns, and explicit interruption.",
+    evidence: "The callable runtime exposes collaboration.spawn_agent with task_name, message, and optional fork_turns plus wait_agent, list_agents, send_message, followup_task, and interrupt_agent."
   },
   {
     id: "parent-context-injection",
@@ -1432,15 +1437,18 @@ function renderCodexRolePrompt(roleName, config, model) {
 function codexInternalHandoffGuidance() {
   return [
     "<codex-delegation-guidance>",
-    "- The user has explicitly authorized this generated Codex orchestrator to use `multi_agent_v1.spawn_agent` whenever delegation is required by these instructions, without needing a fresh user request for subagents in each task.",
-    "- Delegate by calling `multi_agent_v1.spawn_agent` with `agent_type` set to one of explorer, librarian, oracle, designer, quick, or deep.",
+    "- The user has explicitly authorized this generated Codex orchestrator to use `collaboration.spawn_agent` whenever delegation is required by these instructions, without needing a fresh user request for subagents in each task.",
+    "- Collaboration tools are direct tools and must not be called from inside `functions.exec`.",
+    "- Delegate with `collaboration.spawn_agent` using `task_name`, `message`, and optional `fork_turns`; `fork_turns` must be `none`, `all`, or a positive integer string.",
+    "- Role behavior is carried by `task_name` and `message`; named installed-role selection and hard role/profile enforcement are instruction-level because this surface has no role selector.",
     "- Pass the self-contained delegated task instructions plus handoff retrieval instructions in `message`; do not embed the root-owned handoff summary body in `message`.",
     '- When memory recovery is delegated, include parent `session_id`, project, permissions, and the recovery funnel `mem_recall(mode="compact")` -> `mem_recall(mode="context")` -> `mem_get(...)`.',
     '- For that funnel, use `mem_recall` `limit` from 1 to 20; use `mem_get` with `kind="observation"|"prompt"`, `include_timeline=true` plus `before`/`after`, and `offset`/`max_length`; `mem_project(action="graph")` relations are `HAS_TYPE`, `IN_PROJECT`, `HAS_TOPIC_KEY`, `HAS_WHAT`, `HAS_WHY`, `HAS_WHERE`, and `HAS_LEARNED`.',
-    "- Do not include the handoff body in `message` or `items`, and do not pass both `message` and `items` for the same handoff.",
-    "- Use `items` only for structured attachments or mentions when they are truly required; do not use `items` as a handoff-summary payload.",
-    "- Leave `fork_context` omitted or false by default; set `fork_context: true` only when the exact current thread history is required.",
-    "- Use `multi_agent_v1.wait_agent` only when the root needs the result, `multi_agent_v1.send_input` for follow-up or redirect, `multi_agent_v1.resume_agent` only for a closed agent that must continue, and `multi_agent_v1.close_agent` after completion.",
+    "- Do not include the handoff body in `message`.",
+    "- `collaboration.wait_agent` waits for mailbox updates. A `collaboration.wait_agent` timeout or silence is nonterminal and remains in progress, so inspect `collaboration.list_agents` with the same task path before deciding what to do next.",
+    "- `collaboration.send_message` delivers a message without triggering a turn; `collaboration.followup_task` triggers a turn when an idle task must continue.",
+    "- Use `collaboration.interrupt_agent` only for explicit cancellation, a deadline, or supersession.",
+    "- Do not invent result payloads or numeric wait, poll, or timeout rules.",
     "- Memory ownership, handoff recovery, permissions, and prompt-body exclusion are instruction-level unless the active Codex runtime documents stronger enforcement.",
     "</codex-delegation-guidance>"
   ].join("\n");
@@ -1488,8 +1496,7 @@ function renderCodexRootInstructions(config) {
     "- If metadata tooling is unavailable, or the required fields are missing, disclose that memory bootstrap could not run and continue without claiming memory was saved.",
     '- Before delegating after meaningful context changes, save or refresh the handoff body with root-owned mem_session(action="summary") or mem_save(kind="session_summary") when available; if unavailable, disclose that root-owned compaction could not be persisted.',
     "- Use the ambient Codex root session as the delegate-first root coordinator; do not generate or select an orchestrator TOML.",
-    "- Delegate by invoking `multi_agent_v1.spawn_agent` for the installed Codex role agents: explorer, librarian, oracle, designer, quick, and deep.",
-    "- After receiving a delegated subagent response, close that subagent session unless you will retry or intentionally keep using that exact same session; explorer and librarian sessions must always be closed immediately after their response, and retry sessions must be closed after the retry result unless explicit same-session reuse is still required.",
+    "- Delegate by invoking `collaboration.spawn_agent`; use role-prefixed task names and explicit role instructions for the installed Codex role agents: explorer, librarian, oracle, designer, quick, and deep.",
     "- Use packaged thoth-agents plugin capabilities through Codex plugin, skill, MCP, and hook review surfaces after enabling them with /plugins and /hooks.",
     "- For blocking user decisions in Codex Default mode, use request_user_input after features.default_mode_request_user_input is enabled; do not ask those questions in plain prose.",
     "- Whenever the root orchestrator calls `request_user_input`, it MUST NEVER set or pass `autoResolutionMs`; omit the field entirely.",

package/dist/cli/index.js

@@ -4,7 +4,7 @@ import {
   getOpenCodeVersion,
   isOpenCodeInstalled,
   opencodeAdapter
-} from "../chunk-75JOF37E.js";
+} from "../chunk-MF5NNCPC.js";
 import {
   CODEX_ROLE_NAMES,
   RECOMMENDED_SKILLS,
@@ -41,7 +41,7 @@ import {
   installRecommendedSkill,
   listOperationHarnesses,
   normalizeEffortSelection
-} from "../chunk-6NMPKYWY.js";
+} from "../chunk-YYVE7YHR.js";
 import {
   ALL_AGENT_NAMES,
   CUSTOM_SKILLS,
@@ -53,7 +53,7 @@ import {
   getExistingLiteConfigPath,
   installCustomSkills,
   writeLiteConfig
-} from "../chunk-YLRPDTU7.js";
+} from "../chunk-WBRGPRRB.js";
 
 // src/cli/index.ts
 import { pathToFileURL } from "url";

package/dist/cli/tui/index.js

@@ -2,8 +2,8 @@ import {
   defaultTuiOperations,
   effortChoicesForModel,
   listOperationHarnesses
-} from "../../chunk-6NMPKYWY.js";
-import "../../chunk-YLRPDTU7.js";
+} from "../../chunk-YYVE7YHR.js";
+import "../../chunk-WBRGPRRB.js";
 
 // src/cli/tui/index.tsx
 import { render } from "ink";

package/dist/harness/adapters/codex-surfaces.d.ts

@@ -170,20 +170,19 @@ export declare const CODEX_SURFACES: readonly [{
     readonly id: "per-agent-runtime-permissions";
     readonly target: "permission-control";
     readonly status: "unsupported";
-    readonly fields: ["per-agent tool allow/deny equivalent to OpenCode permissions"];
+    readonly fields: ["named installed-role selection", "per-role permission enforcement", "per-agent tool allow/deny equivalent to OpenCode permissions"];
     readonly diagnosticCode: "codex.permission.memory.enforcement_gap";
-    readonly summary: "Codex sandbox and approval policy can constrain sessions, but OpenCode-style per-agent MCP/tool deny maps are not validated.";
+    readonly summary: "Named installed-role selection and per-role permission enforcement are instruction-only because collaboration.spawn_agent has no role selector; OpenCode-style per-agent MCP/tool deny maps are not validated.";
     readonly evidence: "Codex approvals/security docs cover sandbox and approval policies, not exact OpenCode per-agent permission maps.";
     readonly fallback: "instruction-only";
 }, {
     readonly id: "programmatic-delegation-runtime";
     readonly target: "delegation-runtime";
-    readonly status: "unsupported";
-    readonly fields: ["task API", "background task sessions", "tmux lifecycle hooks", "automatic subagent session close"];
-    readonly diagnosticCode: "codex.delegation.runtime.unsupported";
-    readonly summary: "Codex subagents are user/instruction-triggered; no OpenCode plugin task API or automatic subagent session close parity is validated.";
-    readonly evidence: "Codex subagents docs describe manual spawning and agent threads, not this plugin runtime task API or a validated runtime close hook.";
-    readonly fallback: "instruction-only";
+    readonly status: "validated";
+    readonly fields: ["collaboration.spawn_agent", "collaboration.wait_agent", "collaboration.list_agents", "collaboration.send_message", "collaboration.followup_task", "collaboration.interrupt_agent"];
+    readonly diagnosticCode: "codex.delegation.runtime.validated";
+    readonly summary: "The current Codex collaboration surface supports generic programmatic delegation, mailbox waits, live task-tree inspection, messages, follow-up turns, and explicit interruption.";
+    readonly evidence: "The callable runtime exposes collaboration.spawn_agent with task_name, message, and optional fork_turns plus wait_agent, list_agents, send_message, followup_task, and interrupt_agent.";
 }, {
     readonly id: "parent-context-injection";
     readonly target: "parent-context-injection";

package/dist/harness/core/sdd.d.ts

@@ -15,6 +15,7 @@ export interface SddPhaseContract {
     condition?: string;
     defaultAgentRole?: AgentRoleName;
     alternateAgentRoles?: AgentRoleName[];
+    alternateAgentCondition?: string;
     supportingAgentRoles?: AgentRoleName[];
     persistenceAgentRole?: AgentRoleName;
     delegationReason?: string;
@@ -117,6 +118,7 @@ export declare const SDD_PHASES: readonly [{
     readonly artifactSkill: "sdd-tasks";
     readonly defaultAgentRole: "quick";
     readonly alternateAgentRoles: ["deep"];
+    readonly alternateAgentCondition: "Only when the task plan is complex.";
     readonly delegationReason: "Mechanical conversion of settled design into dependency-ordered execution tasks.";
 }, {
     readonly id: "plan-review";

package/dist/index.js

@@ -3,7 +3,7 @@ import {
   renderOpenCodeAgentConfigs,
   spawn,
   spawnSync
-} from "./chunk-75JOF37E.js";
+} from "./chunk-MF5NNCPC.js";
 import {
   DEFAULT_THOTH_COMMAND,
   POLL_INTERVAL_BACKGROUND_MS,
@@ -14,7 +14,7 @@ import {
   installCustomSkills,
   loadPluginConfig,
   stripJsonComments
-} from "./chunk-YLRPDTU7.js";
+} from "./chunk-WBRGPRRB.js";
 
 // src/index.ts
 import path4 from "path";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thoth-agents",
-  "version": "0.2.9",
+  "version": "0.2.10",
   "description": "Delegate-first OpenCode plugin with seven agents, thoth-mem persistence, and bundled SDD skills.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/skills/sdd-tasks/SKILL.md

@@ -47,19 +47,43 @@ The orchestrator passes the artifact store mode (`thoth-mem`, `openspec`, or
    - In accelerated pipeline, derive task structure directly from the proposal.
 3. If a task plan already exists, recover `sdd/{change-name}/tasks` with the
    same mode-aware retrieval rules before rewriting it.
-4. **Validate existing-file references**: For every task that modifies an existing file (not creates a new one), verify the file actually exists on disk before including it in the task list. If a referenced "existing" file is not found, flag it as a design defect in an `> ⚠️ Warning` block at the top of the tasks artifact, and omit the task or add a note.
-5. **Codebase discovery (required when design artifact is absent or lacks file paths)**:
-   Before generating tasks, actively explore the repository to gather the concrete data needed for accurate Verification blocks:
-    1. Read the project's build manifest or task runner config (e.g., `package.json`, `Makefile`, `Cargo.toml`, `.csproj`, `pyproject.toml`) to discover available commands for testing, building, linting, and type-checking. Use the exact commands the project defines in `Run:` fields — never invent commands that don't exist in the project.
-   2. Explore the directory structure of affected areas to confirm actual file paths and module layout.
-   3. Check for existing test files (e.g., `*.test.ts`, `*.spec.ts`) to reference in Verification commands.
-   4. Use the proposal's "Affected Areas" and "Approach" as navigation hints, not as authoritative file paths.
-
-   This exploration is mandatory in accelerated pipeline. In full pipeline, prefer paths from the design artifact's `File Changes` section but still validate commands from `package.json`.
+4. **Reuse settled evidence before validating**: Reuse settled proposal, design, exploration, and handoff evidence first. Treat accepted scope, success
+   criteria, recorded assumptions, and surfaced `handoffHints` as preservation
+   constraints. Do not repeat broad discovery merely because the accelerated
+   pipeline has no design artifact or because an available artifact omits a
+   path.
+5. **Run bounded validation**: Validate only the accepted affected areas, the
+   authoritative command source, task-referenced existing files, and neighboring relevant tests needed to make the plan executable.
+   - Identify the authoritative command source from project instructions and
+     existing conventions (for example `package.json`, `Makefile`, `Cargo.toml`,
+     `.csproj`, or `pyproject.toml`). Use only commands confirmed there in
+     `Run:` fields; never invent commands or imply that an unchecked command
+     exists.
+   - For every task that modifies an existing file, verify that path within the
+     accepted affected areas. Check neighboring relevant tests only where they
+     support a planned task or its Verification block. Never present an unverified path, command, or test reference as confirmed.
+   - Do not expand this pass into repository-wide discovery. If a required
+     reference remains unresolved, defer or omit the dependent task, add a
+     bounded discovery or coordination task when appropriate, and record the
+     unresolved reference once under `## Validation Gaps`.
+   - Emit one entry per unresolved reference using this exact structure:
+
+     ```md
+     ## Validation Gaps
+
+     | Target | Checks performed | Impact / task disposition | Next action |
+     | --- | --- | --- | --- |
+     | {unverified path, command, or test} | {bounded checks completed} | {blocked, deferred, omitted, or follow-up task} | {specific discovery, owner, or decision needed} |
+     ```
+
+   - Escalate a gap that prevents an executable plan. If the accumulated gaps or
+     cross-area validation exceed bounded mechanical planning, recommend
+     escalation or complexity-based routing; do not use role changes as generic
+     failure recovery.
 6. Build a phased checklist for `openspec/changes/{change-name}/tasks.md`. In
    `thoth-mem` mode, produce the same canonical checklist content without
    creating the file.
-5. Use hierarchical numbering and Markdown checkboxes with per-task verification:
+7. Use hierarchical numbering and Markdown checkboxes with per-task verification:
 
     ```md
     # Tasks: {Change Title}
@@ -112,21 +136,21 @@ The orchestrator passes the artifact store mode (`thoth-mem`, `openspec`, or
      - `- [x]` completed
      - `- [-]` skipped — always append a reason: `- [-] 1.2 Task name — skipped: reason here`
 
-7. Reference concrete file paths and specific spec scenarios in the tasks.
-8. If the selected mode includes thoth-mem, persist the full checklist with:
+8. Reference concrete file paths and specific spec scenarios in the tasks.
+9. If the selected mode includes thoth-mem, persist the full checklist with:
 
    Use the memory tool binding for `mem_save` with the canonical SDD topic key
    and required metadata fields: `title`, `topic_key`, `type`, `project`,
    `scope`, and `content`.
 
-9. After `tasks.md` is generated, the workflow proceeds to an optional oracle
+10. After `tasks.md` is generated, the workflow proceeds to an optional oracle
    plan review via the `plan-reviewer` skill. This is managed outside the scope
    of this skill.
-10. The artifact governance validator may run **after** `sdd-tasks` as a
+11. The artifact governance validator may run **after** `sdd-tasks` as a
     report-only handoff. It captures placement guidance for the future
     pre-`sdd-apply` entrypoint, but it does not enforce execution or overlap
     with plan review.
-11. The orchestrator handles the `[OKAY]` / `[REJECT]` review loop and any
+12. The orchestrator handles the `[OKAY]` / `[REJECT]` review loop and any
      necessary fixes before proceeding to execution.
 
 ## Traceability, TDD Ordering, and Handoff Hints