thoth-agents 0.6.0 → 0.8.0

package/dist/cli/managed-state-io.d.ts

@@ -2,6 +2,8 @@
  * Harness-agnostic helpers shared by the Codex and Claude Code installers for
  * managed file writes and managed-model-state JSON bookkeeping.
  */
+/** Fail closed: backups may replace regular files, never links or special files. */
+export declare function assertSafeBackupDestination(path: string): void;
 export declare function writeTextWithBackup(path: string, content: string): boolean;
 export declare function stableJson(value: unknown): string;
 export declare function uniqueMessages(messages: string[]): string[];
@@ -11,7 +13,24 @@ export interface ManagedModelState {
     models: Record<string, string>;
     configuredModels?: Record<string, string>;
     configuredEfforts?: Record<string, string>;
+    /** SHA-256 of the exact last-written Codex TOML bytes, keyed by basename. */
+    roleDigests?: Record<string, string>;
+    /** SHA-256 excluding model/effort lines, permitting operator model selection. */
+    roleStructureDigests?: Record<string, string>;
+    /** Original raw capacity integer; null records that the key was absent. */
+    priorThreadsValue?: string | null;
+    ownedHookTrustKeys?: string[];
 }
+/** Released pre-digest state: only the original version/models fields. */
+export declare function isLegacyManagedModelState(value: unknown, version: number): boolean;
 export declare function emptyManagedModelState(version: number): ManagedModelState;
 export declare function parseManagedModelStateJson(text: string | undefined, version: number): ManagedModelState;
+/** Compare normalized state, allowing only planner-approved role digest refreshes. */
+export declare function managedModelStatesEqual(actual: string, expected: string, version: number, refreshedRoleKeys?: string[]): boolean;
 export declare function readManagedModelState(path: string, version: number): ManagedModelState;
+/**
+ * Update only fields owned by this operation, retaining all other persisted data.
+ * Maps are replaced, not deep-merged, so callers can retire entries. An explicit
+ * undefined removes a field; omitted fields (including future extensions) survive.
+ */
+export declare function writeManagedModelState(path: string, version: number, updates: Partial<ManagedModelState>): boolean;

package/dist/cli/operations/codex.d.ts

@@ -8,6 +8,8 @@ import { type ExecutingPackageVersionResult } from '../package-version';
 import { installRequiredSkill } from '../skills';
 import type { HarnessAction, HarnessStatusReport, ModelConfigInput, ModelRoleInput, OperationApplyResult, OperationContext, OperationPlan } from './types';
 export interface CodexOperationContext extends OperationContext {
+    trustHooks?: boolean;
+    replaceLegacyAgents?: boolean;
     scope?: CodexInstallScope;
     homeDir?: string;
     codexHome?: string;

package/dist/cli/operations/types.d.ts

@@ -3,7 +3,7 @@ import type { HarnessInstallCompletionResult } from '../install-completion';
 import { type InstallHarnessId } from '../install-ledger';
 import type { EffortSelection } from '../model-effort';
 export type ManagedState = 'installed' | 'missing' | 'drift' | 'outdated' | 'unknown';
-export type OperationActionKind = 'status' | 'list' | 'install' | 'update' | 'sync' | 'repair' | 'model-config';
+export type OperationActionKind = 'doctor' | 'uninstall' | 'status' | 'list' | 'install' | 'update' | 'sync' | 'repair' | 'model-config';
 export type ManagedTargetKind = 'file' | 'directory' | 'config' | 'skill' | 'hook' | 'memory-state' | 'generated-artifact' | 'package' | 'surface' | 'unknown';
 export type WarningSeverity = 'minor' | 'important' | 'critical';
 export interface OperationPath {

package/dist/cli/pi-install.d.ts

@@ -141,6 +141,7 @@ export declare function getPiExternalPackageSpecs(options?: Pick<PiSetupOptions,
 export declare function inspectPiSetupPackage(packages: readonly PiConfiguredPackage[], spec: PiSetupPackageSpec, requireManagedSource?: boolean): PiExternalPackageEvidence;
 export declare function piIncumbentTodoRecovery(source: string, scope: PiConfiguredPackage['scope'], identityLimitation?: string, unmappedSource?: boolean): string;
 export declare function resolvePiPreservationPackages(output: string, options: PiSetupOptions): PiConfiguredPackage[];
+export declare function mergePiCodemodeSettings(current: Record<string, unknown>): Record<string, unknown>;
 export declare function mergePiSubagentsConfig(current: Record<string, unknown>): Record<string, unknown>;
 export declare function mergePiGrepMcpConfig(current: Record<string, unknown>): Record<string, unknown>;
 export declare function mergePiRootBlock(current: string, managedBlock: string): string;

package/dist/cli/safe-atomic-write.d.ts

@@ -0,0 +1,2 @@
+/** Replace a file without following or clobbering pre-existing staging paths. */
+export declare function safeAtomicWriteFileSync(path: string, content: string | Uint8Array): void;

package/dist/cli/tui/index.js

@@ -2,10 +2,10 @@ import {
   defaultTuiOperations,
   effortChoicesForModel,
   listOperationHarnesses
-} from "../../chunk-7YCSKK2X.js";
+} from "../../chunk-5LW4CNA5.js";
 import "../../chunk-62L3ORXN.js";
-import "../../chunk-U7FNFTM5.js";
-import "../../chunk-OW6I7ZUU.js";
+import "../../chunk-P7R4GDSO.js";
+import "../../chunk-4DZSWTUM.js";
 
 // src/cli/tui/index.tsx
 import { render } from "ink";
@@ -879,6 +879,8 @@ function App({
   const [previewAction, setPreviewAction] = useState(
     "cancel"
   );
+  const [hookTrustSelected, setHookTrustSelected] = useState(0);
+  const [pendingHookAction, setPendingHookAction] = useState("install");
   const [previewBackView, setPreviewBackView] = useState("harness");
   const [modelHarness, setModelHarness] = useState("codex");
   const [modelRoles, setModelRoles] = useState([]);
@@ -972,7 +974,7 @@ function App({
       setView("harness");
     } else if (view === "action") {
       setView("root");
-    } else if (view === "preview") {
+    } else if (view === "preview" || view === "hookTrust") {
       setView(previewBackView);
     } else if (view === "modelRoles") {
       setView("manageHarness");
@@ -992,10 +994,16 @@ function App({
   function openPlan(harness, action, backView = "harness") {
     setActiveHarness(harness);
     setRestoringDefaults(false);
-    setPlan(operations.plan(harness, action));
     setResult(void 0);
     setPreviewAction("cancel");
     setPreviewBackView(backView);
+    if (harness === "codex" && (action === "install" || action === "update")) {
+      setPendingHookAction(action);
+      setHookTrustSelected(0);
+      setView("hookTrust");
+      return;
+    }
+    setPlan(operations.plan(harness, action));
     setView("preview");
   }
   function openModelRoles(harness) {
@@ -1186,6 +1194,19 @@ function App({
       if (view !== "root") goBack();
       return;
     }
+    if (view === "hookTrust") {
+      if (key.upArrow || key.downArrow || input === "j" || input === "k")
+        setHookTrustSelected((current) => current === 0 ? 1 : 0);
+      if (key.return) {
+        setPlan(
+          operations.plan("codex", pendingHookAction, {
+            trustHooks: hookTrustSelected === 1
+          })
+        );
+        setView("preview");
+      }
+      return;
+    }
     if (view === "root") {
       if (key.upArrow || input === "k") {
         setRootSelected((current) => moveSelection(current, -1, rootItems));
@@ -1484,6 +1505,36 @@ function App({
       )
     ] });
   }
+  if (view === "hookTrust") {
+    return /* @__PURE__ */ jsxs7(Box8, { flexDirection: "column", children: [
+      /* @__PURE__ */ jsx8(
+        Header,
+        {
+          title: "Trust Codex hooks?",
+          subtitle: "Trusted hooks can run outside the sandbox."
+        }
+      ),
+      /* @__PURE__ */ jsx8(Text8, { children: "Trust thoth-agents SessionStart and SubagentStart hooks?" }),
+      /* @__PURE__ */ jsx8(
+        Menu,
+        {
+          items: [
+            {
+              id: "no",
+              label: "No \u2014 review in Codex",
+              detail: "Use /hooks or the startup Trust all and continue prompt."
+            },
+            {
+              id: "yes",
+              label: "Yes \u2014 trust plugin hooks",
+              detail: "Consent to running outside the sandbox."
+            }
+          ],
+          selected: hookTrustSelected
+        }
+      )
+    ] });
+  }
   if (view === "preview" && plan) {
     return /* @__PURE__ */ jsxs7(Box8, { flexDirection: "column", children: [
       /* @__PURE__ */ jsx8(

package/dist/cli/tui/operations.d.ts

@@ -9,7 +9,9 @@ export interface TuiOperations {
     providerCapability?(harness: HarnessId): Promise<ProviderCapabilityEvidence>;
     modelRoles(harness: HarnessId): ModelRoleInput[];
     modelOptions(harness: HarnessId): Promise<ModelOption[]>;
-    plan(harness: HarnessId, action: Exclude<TuiAction, 'status' | 'list'>): OperationPlan;
+    plan(harness: HarnessId, action: Exclude<TuiAction, 'status' | 'list'>, options?: {
+        trustHooks?: boolean;
+    }): OperationPlan;
     modelPlan(harness: HarnessId, roles: ModelRoleInput[]): OperationPlan;
     restoreModelPlan(harness: HarnessId, options: readonly ModelOption[]): OperationPlan;
     apply(plan: OperationPlan): OperationApplyResult;

package/dist/cli/types.d.ts

@@ -7,6 +7,7 @@ export interface InstallArgs {
     localPiRuntimeRoot?: string;
     tmux?: BooleanArg;
     dryRun?: boolean;
+    trustHooks?: boolean;
     reset?: boolean;
 }
 export interface GenerateArgs {
@@ -22,13 +23,15 @@ export interface CliModelRoleArg {
     effort?: EffortSelection;
 }
 export interface OperationArgs {
+    replaceLegacyAgents?: boolean;
     harness?: OperationHarnessArg;
     all?: boolean;
     apply?: boolean;
     dryRun?: boolean;
+    trustHooks?: boolean;
     roles: CliModelRoleArg[];
 }
-export type CliOperationCommand = 'status' | 'list' | 'update' | 'sync' | 'model';
+export type CliOperationCommand = 'uninstall' | 'doctor' | 'status' | 'list' | 'update' | 'sync' | 'model';
 export type CliParseResult = {
     command: 'install';
     installArgs: InstallArgs;

package/dist/config/constants.d.ts

@@ -4,7 +4,8 @@ export declare const SUBAGENT_NAMES: readonly ["explorer", "librarian", "oracle"
 export declare const ORCHESTRATOR_NAME: "orchestrator";
 export declare const ALL_AGENT_NAMES: readonly BuiltinAgentName[];
 export declare const SUBAGENT_DELEGATION_RULES: Record<AgentName, readonly string[]>;
-export declare const CONFIRMED_OPENAI_SUBAGENT_PRESET: {
+/** Previous shipped defaults, retained only for upgrade comparison. */
+export declare const LEGACY_OPENAI_PRESET: {
     readonly explorer: {
         readonly model: "gpt-6-luna";
         readonly effort: "low";
@@ -25,10 +26,36 @@ export declare const CONFIRMED_OPENAI_SUBAGENT_PRESET: {
         readonly model: "gpt-6-luna";
         readonly effort: "max";
     };
+    readonly orchestrator: {
+        readonly model: "gpt-6-sol";
+        readonly effort: "xhigh";
+    };
+};
+export declare const CONFIRMED_OPENAI_SUBAGENT_PRESET: {
+    readonly explorer: {
+        readonly model: "gpt-6-luna";
+        readonly effort: "max";
+    };
+    readonly librarian: {
+        readonly model: "gpt-6-luna";
+        readonly effort: "max";
+    };
+    readonly oracle: {
+        readonly model: "gpt-6.1-sol";
+        readonly effort: "xhigh";
+    };
+    readonly designer: {
+        readonly model: "gpt-6-luna";
+        readonly effort: "max";
+    };
+    readonly worker: {
+        readonly model: "gpt-6-luna";
+        readonly effort: "max";
+    };
 };
 export declare const OPENCODE_OPENAI_ORCHESTRATOR_PRESET: {
-    readonly model: "gpt-6-sol";
-    readonly effort: "xhigh";
+    readonly model: "gpt-6.1-sol";
+    readonly effort: "high";
 };
 export declare const DEFAULT_MODELS: Record<AgentName, string | undefined>;
 export declare function getDefaultOpenCodeModel(name: BuiltinAgentName): string;

package/dist/config/schema.d.ts

@@ -54,6 +54,7 @@ export declare const AgentOverrideConfigSchema: z.ZodObject<{
         id: z.ZodString;
         variant: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>]>>]>>;
+    skills: z.ZodOptional<z.ZodArray<z.ZodString>>;
     temperature: z.ZodOptional<z.ZodNumber>;
     steps: z.ZodOptional<z.ZodNumber>;
     variant: z.ZodCatch<z.ZodOptional<z.ZodString>>;
@@ -89,6 +90,7 @@ export declare const PresetSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
         id: z.ZodString;
         variant: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>]>>]>>;
+    skills: z.ZodOptional<z.ZodArray<z.ZodString>>;
     temperature: z.ZodOptional<z.ZodNumber>;
     steps: z.ZodOptional<z.ZodNumber>;
     variant: z.ZodCatch<z.ZodOptional<z.ZodString>>;
@@ -180,6 +182,7 @@ export declare const PluginConfigSchema: z.ZodObject<{
             id: z.ZodString;
             variant: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>]>>]>>;
+        skills: z.ZodOptional<z.ZodArray<z.ZodString>>;
         temperature: z.ZodOptional<z.ZodNumber>;
         steps: z.ZodOptional<z.ZodNumber>;
         variant: z.ZodCatch<z.ZodOptional<z.ZodString>>;
@@ -189,6 +192,7 @@ export declare const PluginConfigSchema: z.ZodObject<{
             id: z.ZodString;
             variant: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>]>>]>>;
+        skills: z.ZodOptional<z.ZodArray<z.ZodString>>;
         temperature: z.ZodOptional<z.ZodNumber>;
         steps: z.ZodOptional<z.ZodNumber>;
         variant: z.ZodCatch<z.ZodOptional<z.ZodString>>;

package/dist/harness/adapters/claude-code.d.ts

@@ -13,7 +13,7 @@ export declare const CLAUDE_CODE_SUBAGENT_DEFAULT_MODELS: {
     readonly worker: "sonnet";
 };
 export declare const CLAUDE_CODE_SUBAGENT_DEFAULT_EFFORTS: {
-    readonly explorer: "low";
+    readonly explorer: "medium";
     readonly designer: "medium";
     readonly worker: "medium";
     readonly librarian: "high";

package/dist/harness/adapters/codex-legacy-agents.d.ts

@@ -0,0 +1,31 @@
+export declare const LEGACY_CODEX_AGENT_ARTIFACTS: readonly [{
+    readonly harness: "codex";
+    readonly kind: "agent-config";
+    readonly path: ".codex/agents/thoth-agents-explorer.toml";
+    readonly description: "Codex agent definition for explorer.";
+    readonly content: "name = \"explorer\"\ndescription = \"Resolve broad or uncertain repository questions and return distilled evidence. Use when: Local source, effective flow, responsibility, repository ownership, or behavior is unknown or uncertain. Do not use when: Not for implementation, edits, or known narrow questions. Escalate when: Send external evidence to librarian and mutation scope to root. Mutation: read-only; never mutate the workspace. Verification: reports inspected paths, confidence, and remaining gaps Return: compact markdown fields: conclusion, evidence, verification, risks, openQuestions.\"\ndeveloper_instructions = \"\"\"\n<role>\nYou are explorer.\n</role>\n\n<mode>\n- Mode: read-only\n- Dispatch: collaboration.spawn_agent\n- Scope: local repository discovery\n</mode>\n\n<responsibility>\nResolve broad or uncertain repository questions and return distilled evidence.\n</responsibility>\n\n<routing-contract>\n- Use when: Local source, effective flow, responsibility, repository ownership, or behavior is unknown or uncertain.\n- Do not use when: Not for implementation, edits, or known narrow questions.\n- Escalate when: Send external evidence to librarian and mutation scope to root.\n- Verification: reports inspected paths, confidence, and remaining gaps\n</routing-contract>\n\n<reasoning-discipline>\n- Check the most likely failure mode and one meaningful alternative before acting.\n- Ground conclusions in current evidence and verify the assigned outcome before returning.\n</reasoning-discipline>\n\n<rules>\n- Do not mutate the workspace.\n- Do not create coordination artifacts.\n- Resolve the assigned repository question with paths, symbols, and concise anchors.\n- Search broadly only when the target is genuinely unknown; stop once the evidence is decision-ready.\n</rules>\n\n<evidence-only>\n- Report facts with evidence and uncertainty; never recommend fixes, designs, defaults or next actions.\n- Treat conclusion as a factual finding, not advice.\n- Return any open question you cannot settle through openQuestions as the question, the possible options and the facts for each option, without recommending one. Root decides or asks Oracle.\n</evidence-only>\n\n- Do not delegate further or call `functions.update_plan`; root owns progress.\n- Use terminating checks; avoid watch processes and indefinite waits.\n- Preserve operator-selected model/effort. Stop after the assigned outcome and checks; never expand scope to fill a timeout.\n- After two consecutive attempts without new evidence or progress, return partial evidence and the smallest blocker; do not repeat searches or unchanged failing commands.\n- Use exact supplied skill paths; report missing assets instead of searching the user home or installing replacements.\n- During edits use focused checks. Freeze relevant inputs before final validation; rerun only checks invalidated by later edits. Reuse fresh evidence for unchanged inputs, not full suites per child.\n- Use native command completion; no status/log polling merely to wait. Batch independent short reads/checks when supported; no extra process wrappers.\n- Reconcile owned background commands before returning. A late notification must preserve the substantive handoff, not replace it with a bare acknowledgment.\n- Never discard or overwrite unrelated working-tree changes.\n- `none`: no provider work; `recall`: bounded reads; `observe`: + bounded durable observation in scope.\n- `recall`/`observe`: installed `thoth-mem` skill; do not invent provider mechanics/claim unconfirmed effects.\n- Only dispatch identity, verbatim; never derive. If missing, report memory unavailable.\n- MEMORY: no workspace mutation or root lifecycle/real-user-intent authority.\n- `.thoth/`: work/specs/constitution/history—not provider memory; no artifact mirrors.\n- Report unavailable/degraded/stale/contradictory/insufficient memory; continue unrelated safe work.\n\n<questions>\nUse `request_user_input` only for a blocking material choice, destructive or security-sensitive action, or missing secret. Do safe non-blocked work first, then escalate the unresolved question to the root through openQuestions as the question, the possible options and the facts for each option, without recommending one.\n</questions>\n\n<return-contract>\nReturn compact markdown fields (no JSON): conclusion, evidence, verification, risks, openQuestions.\n</return-contract>\n\nBe concise. Return distilled evidence and outcomes, not raw logs or full-file dumps.\n\n<model-profile family=\"openai\">\n- Plan briefly, then act with explicit tool targets and return shapes.\n- Navigate from broad uncertainty to exact repository anchors.\n</model-profile>\n\n<role-operational-contract>\n- Permissions, memory governance, runtime hooks, and provider-per-agent controls are instruction-level unless the active Codex runtime documents stronger enforcement.\n- explorer runs as a Codex custom-agent TOML entry; the orchestrator remains the ambient Codex root session, not a generated role TOML.\n</role-operational-contract>\n\"\"\"\n\nmodel = \"gpt-6-luna\"\nmodel_reasoning_effort = \"max\"\nsandbox_mode = \"read-only\"\n";
+}, {
+    readonly harness: "codex";
+    readonly kind: "agent-config";
+    readonly path: ".codex/agents/thoth-agents-librarian.toml";
+    readonly description: "Codex agent definition for librarian.";
+    readonly content: "name = \"librarian\"\ndescription = \"Gather current authoritative evidence and separate documented facts from inference. Use when: Current authoritative external evidence is required. Do not use when: Not for implementation, edits, or purely local discovery. Escalate when: Report contradictory or insufficient sources to root. Mutation: read-only; never mutate the workspace. Verification: provides direct sources for substantive external claims Return: compact markdown fields: conclusion, evidence, verification, risks, openQuestions.\"\ndeveloper_instructions = \"\"\"\n<role>\nYou are librarian.\n</role>\n\n<mode>\n- Mode: read-only\n- Dispatch: collaboration.spawn_agent\n- Scope: authoritative external research with local confirmation when needed\n</mode>\n\n<responsibility>\nGather current authoritative evidence and separate documented facts from inference.\n</responsibility>\n\n<routing-contract>\n- Use when: Current authoritative external evidence is required.\n- Do not use when: Not for implementation, edits, or purely local discovery.\n- Escalate when: Report contradictory or insufficient sources to root.\n- Verification: provides direct sources for substantive external claims\n</routing-contract>\n\n<reasoning-discipline>\n- Check the most likely failure mode and one meaningful alternative before acting.\n- Ground conclusions in current evidence and verify the assigned outcome before returning.\n</reasoning-discipline>\n\n<rules>\n- Do not mutate the workspace.\n- Do not create coordination artifacts.\n- Prefer current official documentation and primary sources.\n- Cite every substantive external claim and label inference explicitly.\n</rules>\n\n<evidence-only>\n- Report facts with evidence and uncertainty; never recommend fixes, designs, defaults or next actions.\n- Treat conclusion as a factual finding, not advice.\n- Return any open question you cannot settle through openQuestions as the question, the possible options and the facts for each option, without recommending one. Root decides or asks Oracle.\n</evidence-only>\n\n- Do not delegate further or call `functions.update_plan`; root owns progress.\n- Use terminating checks; avoid watch processes and indefinite waits.\n- Preserve operator-selected model/effort. Stop after the assigned outcome and checks; never expand scope to fill a timeout.\n- After two consecutive attempts without new evidence or progress, return partial evidence and the smallest blocker; do not repeat searches or unchanged failing commands.\n- Use exact supplied skill paths; report missing assets instead of searching the user home or installing replacements.\n- During edits use focused checks. Freeze relevant inputs before final validation; rerun only checks invalidated by later edits. Reuse fresh evidence for unchanged inputs, not full suites per child.\n- Use native command completion; no status/log polling merely to wait. Batch independent short reads/checks when supported; no extra process wrappers.\n- Reconcile owned background commands before returning. A late notification must preserve the substantive handoff, not replace it with a bare acknowledgment.\n- Never discard or overwrite unrelated working-tree changes.\n- `none`: no provider work; `recall`: bounded reads; `observe`: + bounded durable observation in scope.\n- `recall`/`observe`: installed `thoth-mem` skill; do not invent provider mechanics/claim unconfirmed effects.\n- Only dispatch identity, verbatim; never derive. If missing, report memory unavailable.\n- MEMORY: no workspace mutation or root lifecycle/real-user-intent authority.\n- `.thoth/`: work/specs/constitution/history—not provider memory; no artifact mirrors.\n- Report unavailable/degraded/stale/contradictory/insufficient memory; continue unrelated safe work.\n\n<questions>\nUse `request_user_input` only for a blocking material choice, destructive or security-sensitive action, or missing secret. Do safe non-blocked work first, then escalate the unresolved question to the root through openQuestions as the question, the possible options and the facts for each option, without recommending one.\n</questions>\n\n<return-contract>\nReturn compact markdown fields (no JSON): conclusion, evidence, verification, risks, openQuestions.\n</return-contract>\n\nBe concise. Return distilled evidence and outcomes, not raw logs or full-file dumps.\n\n<model-profile family=\"openai\">\n- Plan briefly, then act with explicit tool targets and return shapes.\n- Prioritize current primary sources, versions, and explicit citations.\n</model-profile>\n\n<role-operational-contract>\n- Permissions, memory governance, runtime hooks, and provider-per-agent controls are instruction-level unless the active Codex runtime documents stronger enforcement.\n- librarian runs as a Codex custom-agent TOML entry; the orchestrator remains the ambient Codex root session, not a generated role TOML.\n</role-operational-contract>\n\"\"\"\n\nmodel = \"gpt-6-luna\"\nmodel_reasoning_effort = \"max\"\nsandbox_mode = \"read-only\"\n";
+}, {
+    readonly harness: "codex";
+    readonly kind: "agent-config";
+    readonly path: ".codex/agents/thoth-agents-oracle.toml";
+    readonly description: "Codex agent definition for oracle.";
+    readonly content: "name = \"oracle\"\ndescription = \"Independently review plans when selected and provide independent judgment for artifact-backed or material-risk final verification, exposing correctness risks and judging whether results satisfy their contracts. Use when: Selected focused plan review, persistent diagnosis, material architecture or security risk, contradictory evidence, high failure cost, or artifact-backed final verification needs independent judgment. Do not use when: Not for implementation, mutation, persistence, or self-review. Escalate when: Return blockers and remediation anchors to root. Mutation: read-only; never mutate the workspace. Verification: separates observations, risks, and recommendations Return: compact markdown fields: conclusion, evidence, verification, risks, openQuestions, nextAction. Only plan-review/final-verification uses a thoth-result gate envelope; diagnosis/advice cannot approve.\"\ndeveloper_instructions = \"\"\"\n<role>\nYou are oracle.\n</role>\n\n<mode>\n- Mode: read-only\n- Dispatch: collaboration.spawn_agent\n- Scope: diagnosis, architecture, optional focused plan review, and independent verification\n</mode>\n\n<responsibility>\nIndependently review plans when selected and provide independent judgment for artifact-backed or material-risk final verification, exposing correctness risks and judging whether results satisfy their contracts.\n</responsibility>\n\n<routing-contract>\n- Use when: Selected focused plan review, persistent diagnosis, material architecture or security risk, contradictory evidence, high failure cost, or artifact-backed final verification needs independent judgment.\n- Do not use when: Not for implementation, mutation, persistence, or self-review.\n- Escalate when: Return blockers and remediation anchors to root.\n- Verification: separates observations, risks, and recommendations\n</routing-contract>\n\n<reasoning-discipline>\n- Check the most likely failure mode and one meaningful alternative before acting.\n- Ground conclusions in current evidence and verify the assigned outcome before returning.\n</reasoning-discipline>\n\n<rules>\n- Do not mutate the workspace.\n- Do not create coordination artifacts.\n- Separate observations, risks and recommendations; review stated requirements/contracts, not invented scope.\n- For plan review or final verify, load matching bundled thoth-sdd guidance; remain read-only.\n- Reject self-review: implementing root/writer cannot substitute for independent oracle judgment.\n</rules>\n\n- Do not delegate further or call `functions.update_plan`; root owns progress.\n- Use terminating checks; avoid watch processes and indefinite waits.\n- Preserve operator-selected model/effort. Stop after the assigned outcome and checks; never expand scope to fill a timeout.\n- After two consecutive attempts without new evidence or progress, return partial evidence and the smallest blocker; do not repeat searches or unchanged failing commands.\n- Use exact supplied skill paths; report missing assets instead of searching the user home or installing replacements.\n- During edits use focused checks. Freeze relevant inputs before final validation; rerun only checks invalidated by later edits. Reuse fresh evidence for unchanged inputs, not full suites per child.\n- Use native command completion; no status/log polling merely to wait. Batch independent short reads/checks when supported; no extra process wrappers.\n- Reconcile owned background commands before returning. A late notification must preserve the substantive handoff, not replace it with a bare acknowledgment.\n- Never discard or overwrite unrelated working-tree changes.\n- `none`: no provider work; `recall`: bounded reads; `observe`: + bounded durable observation in scope.\n- `recall`/`observe`: installed `thoth-mem` skill; do not invent provider mechanics/claim unconfirmed effects.\n- Only dispatch identity, verbatim; never derive. If missing, report memory unavailable.\n- MEMORY: no workspace mutation or root lifecycle/real-user-intent authority.\n- `.thoth/`: work/specs/constitution/history—not provider memory; no artifact mirrors.\n- Report unavailable/degraded/stale/contradictory/insufficient memory; continue unrelated safe work.\n\n<questions>\nUse `request_user_input` only for a blocking material choice, destructive or security-sensitive action, or missing secret. Do safe non-blocked work first and ask one targeted question with a recommended default.\n</questions>\n\n<return-contract>\nReturn compact markdown fields (no JSON): conclusion, evidence, verification, risks, openQuestions, nextAction.\nDiagnosis/advice uses markdown fields and cannot approve. Only for assigned plan-review or final-verification, instead return exactly one fenced ```thoth-result JSON block and nothing else. Types: s=string, s+=nonempty string, hex64=64 lowercase hex. No extra keys; ?=optional. evidenceIds reference unique evidence IDs.\n- schemaVersion: 1\n- role: \"oracle\"\n- status: complete|partial|blocked|failed\n- conclusion: s\n- evidence: {id: s+, kind: s, locator: s, claim: s, basis: observed|inferred, uncertainty: s}[]\n- verification: {check: s, method: s, outcome: pass|fail|not-run, evidenceIds: s[], reason: s}[]\n- risks: {description: s, severity: low|medium|high|critical, blocking: boolean, evidenceIds: s[]}[]\n- openQuestions: {question: s, owner: s, options: s[], facts: s[]}[]\n- nextAction: s|null\n- review: {kind: plan-review|final-verification, verdict: s, reviewedRecord?: s+, reviewedRecordSha256?: hex64}\nplan-review: OKAY|REJECT; final-verification: PASS|FAIL|BLOCKED; OKAY|PASS requires complete status and no blocking risks. Final-verification requires reviewedRecord and reviewedRecordSha256 if the assignment names a record; otherwise omit both.\n</return-contract>\n\nBe concise. Return distilled evidence and outcomes, not raw logs or full-file dumps.\n\n<model-profile family=\"openai\">\n- Plan briefly, then act with explicit tool targets and return shapes.\n- Challenge assumptions and return evidence-backed judgment.\n</model-profile>\n\n<role-operational-contract>\n- Permissions, memory governance, runtime hooks, and provider-per-agent controls are instruction-level unless the active Codex runtime documents stronger enforcement.\n- oracle runs as a Codex custom-agent TOML entry; the orchestrator remains the ambient Codex root session, not a generated role TOML.\n</role-operational-contract>\n\"\"\"\n\nmodel = \"gpt-6.1-sol\"\nmodel_reasoning_effort = \"xhigh\"\nsandbox_mode = \"read-only\"\n";
+}, {
+    readonly harness: "codex";
+    readonly kind: "agent-config";
+    readonly path: ".codex/agents/thoth-agents-designer.toml";
+    readonly description: "Codex agent definition for designer.";
+    readonly content: "name = \"designer\"\ndescription = \"Own user-facing implementation choices and visual quality for UI work. Use when: User-facing UI/UX, interaction, accessibility, or visual quality is material. Do not use when: Not for backend-only, non-visual, or correctness-heavy cross-cutting work. Escalate when: Escalate coupled contracts, migrations, or high risk to worker. Mutation: only the assigned UI/UX decisions, implementation, and visual verification surface. Verification: includes visual verification when applicable Return: compact markdown fields: conclusion, evidence, verification, risks, openQuestions, nextAction, changedFiles.\"\ndeveloper_instructions = \"\"\"\n<role>\nYou are designer.\n</role>\n\n<mode>\n- Mode: write-capable\n- Dispatch: collaboration.spawn_agent\n- Scope: UI/UX decisions, implementation, and visual verification\n</mode>\n\n<responsibility>\nOwn user-facing implementation choices and visual quality for UI work.\n</responsibility>\n\n<routing-contract>\n- Use when: User-facing UI/UX, interaction, accessibility, or visual quality is material.\n- Do not use when: Not for backend-only, non-visual, or correctness-heavy cross-cutting work.\n- Escalate when: Escalate coupled contracts, migrations, or high risk to worker.\n- Verification: includes visual verification when applicable\n</routing-contract>\n\n<reasoning-discipline>\n- Check the most likely failure mode and one meaningful alternative before acting.\n- Ground conclusions in current evidence and verify the assigned outcome before returning.\n</reasoning-discipline>\n\n<rules>\n- Edit only the assigned work-unit surface.\n- Preserve unrelated working-tree changes and never use destructive Git cleanup.\n- Use local judgment to complete the accepted outcome within the assigned boundaries.\n- If a new independently acceptable outcome or material scope change appears, return bounded progress for root reassessment before expanding.\n- Own user-facing choices, implementation, and visual verification.\n- Check relevant responsive and interaction states when feasible.\n</rules>\n\n- Do not delegate further or call `functions.update_plan`; root owns progress.\n- Use terminating checks; avoid watch processes and indefinite waits.\n- Preserve operator-selected model/effort. Stop after the assigned outcome and checks; never expand scope to fill a timeout.\n- After two consecutive attempts without new evidence or progress, return partial evidence and the smallest blocker; do not repeat searches or unchanged failing commands.\n- Use exact supplied skill paths; report missing assets instead of searching the user home or installing replacements.\n- During edits use focused checks. Freeze relevant inputs before final validation; rerun only checks invalidated by later edits. Reuse fresh evidence for unchanged inputs, not full suites per child.\n- Use native command completion; no status/log polling merely to wait. Batch independent short reads/checks when supported; no extra process wrappers.\n- Reconcile owned background commands before returning. A late notification must preserve the substantive handoff, not replace it with a bare acknowledgment.\n- Never discard or overwrite unrelated working-tree changes.\n- `none`: no provider work; `recall`: bounded reads; `observe`: + bounded durable observation in scope.\n- `recall`/`observe`: installed `thoth-mem` skill; do not invent provider mechanics/claim unconfirmed effects.\n- Only dispatch identity, verbatim; never derive. If missing, report memory unavailable.\n- MEMORY: no workspace mutation or root lifecycle/real-user-intent authority.\n- `.thoth/`: work/specs/constitution/history—not provider memory; no artifact mirrors.\n- Report unavailable/degraded/stale/contradictory/insufficient memory; continue unrelated safe work.\n\n<questions>\nUse `request_user_input` only for a blocking material choice, destructive or security-sensitive action, or missing secret. Do safe non-blocked work first and ask one targeted question with a recommended default.\n</questions>\n\n<return-contract>\nReturn compact markdown fields (no JSON): conclusion, evidence, verification, risks, openQuestions, nextAction, changedFiles.\n</return-contract>\n\nBe concise. Return distilled evidence and outcomes, not raw logs or full-file dumps.\n\n<model-profile family=\"openai\">\n- Plan briefly, then act with explicit tool targets and return shapes.\n- Make concrete UX choices and verify the visible result.\n</model-profile>\n\n<role-operational-contract>\n- Permissions, memory governance, runtime hooks, and provider-per-agent controls are instruction-level unless the active Codex runtime documents stronger enforcement.\n- designer runs as a Codex custom-agent TOML entry; the orchestrator remains the ambient Codex root session, not a generated role TOML.\n</role-operational-contract>\n\"\"\"\n\nmodel = \"gpt-6-luna\"\nmodel_reasoning_effort = \"max\"\nsandbox_mode = \"workspace-write\"\n";
+}, {
+    readonly harness: "codex";
+    readonly kind: "agent-config";
+    readonly path: ".codex/agents/thoth-agents-worker.toml";
+    readonly description: "Codex agent definition for worker.";
+    readonly content: "name = \"worker\"\ndescription = \"Handle bounded nonvisual implementation with full local context, including exact low-risk edits and correctness-critical, multi-file, edge-case-heavy, or high-risk work. Use when: Known bounded nonvisual implementation is ready, regardless of complexity; root direct work is limited to the bounded implementation-ownership exceptions. Correctness-critical work may be multi-file, edge-case-heavy, migration, concurrency, shared-contract, or high-risk. Do not use when: Not for visual-only work, reviewed commits, or work explicitly retained by the user in root. Escalate when: Return product or architecture choices to root. Mutation: only the assigned bounded nonvisual implementation and verification surface. Verification: reports focused checks and relevant edge-case evidence Return: compact markdown fields: conclusion, evidence, verification, risks, openQuestions, nextAction, changedFiles.\"\ndeveloper_instructions = \"\"\"\n<role>\nYou are worker.\n</role>\n\n<mode>\n- Mode: write-capable\n- Dispatch: collaboration.spawn_agent\n- Scope: bounded nonvisual implementation and verification\n</mode>\n\n<responsibility>\nHandle bounded nonvisual implementation with full local context, including exact low-risk edits and correctness-critical, multi-file, edge-case-heavy, or high-risk work.\n</responsibility>\n\n<routing-contract>\n- Use when: Known bounded nonvisual implementation is ready, regardless of complexity; root direct work is limited to the bounded implementation-ownership exceptions. Correctness-critical work may be multi-file, edge-case-heavy, migration, concurrency, shared-contract, or high-risk.\n- Do not use when: Not for visual-only work, reviewed commits, or work explicitly retained by the user in root.\n- Escalate when: Return product or architecture choices to root.\n- Verification: reports focused checks and relevant edge-case evidence\n</routing-contract>\n\n<reasoning-discipline>\n- Check the most likely failure mode and one meaningful alternative before acting.\n- Ground conclusions in current evidence and verify the assigned outcome before returning.\n</reasoning-discipline>\n\n<rules>\n- Edit only the assigned work-unit surface.\n- Preserve unrelated working-tree changes and never use destructive Git cleanup.\n- Use local judgment to complete the accepted outcome within the assigned boundaries.\n- If a new independently acceptable outcome or material scope change appears, return bounded progress for root reassessment before expanding.\n- Start at supplied entrypoints; read further only to resolve a concrete missing fact. Use tests first for behavior changes.\n- Verify relevant call sites and shared contracts within the assigned outcome; do not restart broad discovery or unrelated cleanup.\n</rules>\n\n- Do not delegate further or call `functions.update_plan`; root owns progress.\n- Use terminating checks; avoid watch processes and indefinite waits.\n- Preserve operator-selected model/effort. Stop after the assigned outcome and checks; never expand scope to fill a timeout.\n- After two consecutive attempts without new evidence or progress, return partial evidence and the smallest blocker; do not repeat searches or unchanged failing commands.\n- Use exact supplied skill paths; report missing assets instead of searching the user home or installing replacements.\n- During edits use focused checks. Freeze relevant inputs before final validation; rerun only checks invalidated by later edits. Reuse fresh evidence for unchanged inputs, not full suites per child.\n- Use native command completion; no status/log polling merely to wait. Batch independent short reads/checks when supported; no extra process wrappers.\n- Reconcile owned background commands before returning. A late notification must preserve the substantive handoff, not replace it with a bare acknowledgment.\n- Never discard or overwrite unrelated working-tree changes.\n- `none`: no provider work; `recall`: bounded reads; `observe`: + bounded durable observation in scope.\n- `recall`/`observe`: installed `thoth-mem` skill; do not invent provider mechanics/claim unconfirmed effects.\n- Only dispatch identity, verbatim; never derive. If missing, report memory unavailable.\n- MEMORY: no workspace mutation or root lifecycle/real-user-intent authority.\n- `.thoth/`: work/specs/constitution/history—not provider memory; no artifact mirrors.\n- Report unavailable/degraded/stale/contradictory/insufficient memory; continue unrelated safe work.\n\n<questions>\nUse `request_user_input` only for a blocking material choice, destructive or security-sensitive action, or missing secret. Do safe non-blocked work first and ask one targeted question with a recommended default.\n</questions>\n\n<return-contract>\nReturn compact markdown fields (no JSON): conclusion, evidence, verification, risks, openQuestions, nextAction, changedFiles.\n</return-contract>\n\nBe concise. Return distilled evidence and outcomes, not raw logs or full-file dumps.\n\n<model-profile family=\"openai\">\n- Plan briefly, then act with explicit tool targets and return shapes.\n- Trace shared behavior, test assumptions, and verify edge cases.\n</model-profile>\n\n<role-operational-contract>\n- Permissions, memory governance, runtime hooks, and provider-per-agent controls are instruction-level unless the active Codex runtime documents stronger enforcement.\n- worker runs as a Codex custom-agent TOML entry; the orchestrator remains the ambient Codex root session, not a generated role TOML.\n</role-operational-contract>\n\"\"\"\n\nmodel = \"gpt-6-luna\"\nmodel_reasoning_effort = \"max\"\nsandbox_mode = \"workspace-write\"\n";
+}];

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

@@ -13,7 +13,7 @@ export interface CodexSurfaceRecord {
     evidence: string;
     fallback?: 'instruction-only' | 'diagnostic-only' | 'none';
 }
-export type CodexHookEvent = 'SessionStart' | 'UserPromptSubmit' | 'PreToolUse' | 'PermissionRequest' | 'PostToolUse' | 'Stop';
+export type CodexHookEvent = 'SessionStart' | 'SubagentStart' | 'UserPromptSubmit' | 'PreToolUse' | 'PermissionRequest' | 'PostToolUse' | 'Stop';
 export type CodexHookHandlerType = 'command' | 'prompt' | 'agent';
 export interface CodexHookValidationInput {
     event: string;

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

@@ -1,9 +1,11 @@
 import { type PluginConfig } from '../../config';
-import type { HarnessAdapter, HarnessCapabilities, HarnessRenderContext } from '../types';
+import type { HarnessAdapter, HarnessArtifact, HarnessCapabilities, HarnessRenderContext } from '../types';
 export interface CodexRenderContext extends HarnessRenderContext {
     config?: PluginConfig;
     packageRoot?: string;
 }
 export declare const CODEX_CAPABILITIES: HarnessCapabilities;
 export declare function renderCodexRootInstructions(config?: PluginConfig): string;
+/** @internal Exact pre-hook rendering, retained only for ownership attribution. */
+export declare function renderLegacyCodexAgentArtifacts(): HarnessArtifact[];
 export declare const codexAdapter: HarnessAdapter;

package/dist/harness/codex-hook-script.d.ts

@@ -0,0 +1,2 @@
+/** Canonical CommonJS runtime emitted into the Codex-only plugin hook directory. */
+export declare function renderCodexHookScript(roleNames: readonly string[]): string;

package/dist/harness/core/agent-pack.d.ts

@@ -1,3 +1,5 @@
+export type { OracleReview, OracleReviewKind, ResultCommon, SpecialistResult, SpecialistRole, } from './result-contract';
+export { getSpecialistResultFields, SPECIALIST_RESULT_CONTRACT, } from './result-contract';
 export type AgentRoleName = 'orchestrator' | 'explorer' | 'librarian' | 'oracle' | 'designer' | 'worker';
 export type AgentMutationMode = 'adaptive-root' | 'read-only' | 'write-capable';
 export type AgentDispatchMethod = 'root-coordinator' | 'task';
@@ -146,16 +148,20 @@ export declare const AGENT_ROLES: readonly [{
 }];
 export declare function getImplementationOwnershipInstructions(policy: ImplementationOwnershipPolicy): string[];
 export declare const ORCHESTRATION_POLICY: OrchestrationPolicy;
+export declare const DEFAULT_DELEGATION_LIFECYCLE = "- New objectives, phases, work units, mutable surfaces or independent judgments require fresh specialist sessions via {{lifecycleFreshDelegation}}; {{lifecycleIndependentContext}}. These are fresh-session boundaries, not permission for root execution; completed agents are not a reusable role pool.\n- Use {{lifecycleSameAssignmentContinuation}} only to steer, complete or clarify the same bounded assignment.\n- {{lifecycleSameSessionProbe}} only collects the active nonterminal assignment.\n- Every Oracle plan review, verification round, and PASS judgment uses a fresh Oracle instance. Existing ones only clarify their findings.";
+export declare const CODEX_DELEGATION_LIFECYCLE: string;
 export declare const AGENT_RETURN_CONTRACT: {
     readonly orchestrator: readonly ["conclusion", "evidence", "verification", "risks", "openQuestions", "nextAction"];
     readonly explorer: readonly ["conclusion", "evidence", "verification", "risks", "openQuestions"];
     readonly librarian: readonly ["conclusion", "evidence", "verification", "risks", "openQuestions"];
     readonly oracle: readonly ["conclusion", "evidence", "verification", "risks", "openQuestions", "nextAction"];
-    readonly designer: readonly ["conclusion", "evidence", "verification", "risks", "openQuestions", "nextAction"];
-    readonly worker: readonly ["conclusion", "evidence", "verification", "risks", "openQuestions", "nextAction"];
+    readonly designer: readonly ["conclusion", "evidence", "verification", "risks", "openQuestions", "nextAction", "changedFiles"];
+    readonly worker: readonly ["conclusion", "evidence", "verification", "risks", "openQuestions", "nextAction", "changedFiles"];
 };
 export declare const VERIFICATION_PROTOCOL: readonly ["Completion reports identify changed files and verification evidence.", "Behavior changes receive the smallest sufficient automated check or a declared manual check.", "Visual changes receive designer-owned visual QA when applicable."];
 export declare const AGENT_PACK_CONTRACT: AgentPackContract;
 export declare function getAgentRole(name: AgentRoleName): AgentRoleContract;
+/** Keep non-gate returns independent of the Oracle validator contract. */
+export declare function renderSpecialistResultContract(role: Exclude<AgentRoleName, 'orchestrator'>): string;
 export declare function renderAgentRoutingDescription(role: AgentRoleContract): string;
 export declare function getAgentPackContract(): AgentPackContract;