thoth-agents 0.6.0 → 0.8.0

package/dist/harness/core/result-contract.d.ts

@@ -0,0 +1,366 @@
+declare const common: {
+    readonly type: "object";
+    readonly properties: {
+        readonly schemaVersion: {
+            readonly type: "number";
+            readonly const: 1;
+        };
+        readonly role: {
+            readonly type: "string";
+            readonly enum: readonly ["oracle"];
+        };
+        readonly status: {
+            readonly type: "string";
+            readonly enum: readonly ["complete", "partial", "blocked", "failed"];
+        };
+        readonly conclusion: {
+            readonly type: "string";
+        };
+        readonly evidence: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly id: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                    };
+                    readonly kind: {
+                        readonly type: "string";
+                    };
+                    readonly locator: {
+                        readonly type: "string";
+                    };
+                    readonly claim: {
+                        readonly type: "string";
+                    };
+                    readonly basis: {
+                        readonly type: "string";
+                        readonly enum: readonly ["observed", "inferred"];
+                    };
+                    readonly uncertainty: {
+                        readonly type: "string";
+                    };
+                };
+                readonly required: string[];
+                readonly additionalProperties: false;
+            };
+        };
+        readonly verification: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly check: {
+                        readonly type: "string";
+                    };
+                    readonly method: {
+                        readonly type: "string";
+                    };
+                    readonly outcome: {
+                        readonly type: "string";
+                        readonly enum: readonly ["pass", "fail", "not-run"];
+                    };
+                    readonly evidenceIds: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "string";
+                        };
+                    };
+                    readonly reason: {
+                        readonly type: "string";
+                    };
+                };
+                readonly required: string[];
+                readonly additionalProperties: false;
+            };
+        };
+        readonly risks: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly description: {
+                        readonly type: "string";
+                    };
+                    readonly severity: {
+                        readonly type: "string";
+                        readonly enum: readonly ["low", "medium", "high", "critical"];
+                    };
+                    readonly blocking: {
+                        readonly type: "boolean";
+                    };
+                    readonly evidenceIds: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "string";
+                        };
+                    };
+                };
+                readonly required: string[];
+                readonly additionalProperties: false;
+            };
+        };
+        readonly openQuestions: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly question: {
+                        readonly type: "string";
+                    };
+                    readonly owner: {
+                        readonly type: "string";
+                    };
+                    readonly options: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "string";
+                        };
+                    };
+                    readonly facts: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "string";
+                        };
+                    };
+                };
+                readonly required: string[];
+                readonly additionalProperties: false;
+            };
+        };
+    };
+    readonly required: string[];
+    readonly additionalProperties: false;
+};
+export declare const SPECIALIST_RESULT_CONTRACT: {
+    readonly schemaVersion: 1;
+    readonly fence: "thoth-result";
+    readonly common: {
+        readonly type: "object";
+        readonly properties: {
+            readonly schemaVersion: {
+                readonly type: "number";
+                readonly const: 1;
+            };
+            readonly role: {
+                readonly type: "string";
+                readonly enum: readonly ["oracle"];
+            };
+            readonly status: {
+                readonly type: "string";
+                readonly enum: readonly ["complete", "partial", "blocked", "failed"];
+            };
+            readonly conclusion: {
+                readonly type: "string";
+            };
+            readonly evidence: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "object";
+                    readonly properties: {
+                        readonly id: {
+                            readonly type: "string";
+                            readonly minLength: 1;
+                        };
+                        readonly kind: {
+                            readonly type: "string";
+                        };
+                        readonly locator: {
+                            readonly type: "string";
+                        };
+                        readonly claim: {
+                            readonly type: "string";
+                        };
+                        readonly basis: {
+                            readonly type: "string";
+                            readonly enum: readonly ["observed", "inferred"];
+                        };
+                        readonly uncertainty: {
+                            readonly type: "string";
+                        };
+                    };
+                    readonly required: string[];
+                    readonly additionalProperties: false;
+                };
+            };
+            readonly verification: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "object";
+                    readonly properties: {
+                        readonly check: {
+                            readonly type: "string";
+                        };
+                        readonly method: {
+                            readonly type: "string";
+                        };
+                        readonly outcome: {
+                            readonly type: "string";
+                            readonly enum: readonly ["pass", "fail", "not-run"];
+                        };
+                        readonly evidenceIds: {
+                            readonly type: "array";
+                            readonly items: {
+                                readonly type: "string";
+                            };
+                        };
+                        readonly reason: {
+                            readonly type: "string";
+                        };
+                    };
+                    readonly required: string[];
+                    readonly additionalProperties: false;
+                };
+            };
+            readonly risks: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "object";
+                    readonly properties: {
+                        readonly description: {
+                            readonly type: "string";
+                        };
+                        readonly severity: {
+                            readonly type: "string";
+                            readonly enum: readonly ["low", "medium", "high", "critical"];
+                        };
+                        readonly blocking: {
+                            readonly type: "boolean";
+                        };
+                        readonly evidenceIds: {
+                            readonly type: "array";
+                            readonly items: {
+                                readonly type: "string";
+                            };
+                        };
+                    };
+                    readonly required: string[];
+                    readonly additionalProperties: false;
+                };
+            };
+            readonly openQuestions: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "object";
+                    readonly properties: {
+                        readonly question: {
+                            readonly type: "string";
+                        };
+                        readonly owner: {
+                            readonly type: "string";
+                        };
+                        readonly options: {
+                            readonly type: "array";
+                            readonly items: {
+                                readonly type: "string";
+                            };
+                        };
+                        readonly facts: {
+                            readonly type: "array";
+                            readonly items: {
+                                readonly type: "string";
+                            };
+                        };
+                    };
+                    readonly required: string[];
+                    readonly additionalProperties: false;
+                };
+            };
+        };
+        readonly required: string[];
+        readonly additionalProperties: false;
+    };
+    readonly roles: {
+        readonly oracle: {
+            readonly type: "object";
+            readonly properties: {
+                readonly nextAction: {
+                    readonly type: readonly ["string", "null"];
+                };
+                readonly review: {
+                    readonly required: readonly ["kind", "verdict"];
+                    readonly type: "object";
+                    readonly properties: {
+                        readonly kind: {
+                            readonly type: "string";
+                            readonly enum: readonly ["plan-review", "final-verification"];
+                        };
+                        readonly verdict: {
+                            readonly type: "string";
+                        };
+                        readonly reviewedRecord: {
+                            readonly type: "string";
+                            readonly minLength: 1;
+                        };
+                        readonly reviewedRecordSha256: {
+                            readonly type: "string";
+                            readonly pattern: "^[a-f0-9]{64}$";
+                        };
+                    };
+                    readonly additionalProperties: false;
+                };
+            };
+            readonly required: string[];
+            readonly additionalProperties: false;
+        };
+    };
+    readonly reviewKinds: {
+        readonly 'plan-review': {
+            readonly verdicts: readonly ["OKAY", "REJECT"];
+        };
+        readonly 'final-verification': {
+            readonly verdicts: readonly ["PASS", "FAIL", "BLOCKED"];
+        };
+    };
+    readonly rules: {
+        readonly positiveVerdicts: readonly ["OKAY", "PASS"];
+        readonly positiveStatus: "complete";
+        readonly positiveAllowsBlockingRisks: false;
+        readonly evidenceIdUnique: true;
+        readonly evidenceReferences: readonly ["verification", "risks"];
+        readonly recordBindingReviewKind: "final-verification";
+        readonly recordBindingRequiredFields: readonly ["reviewedRecord", "reviewedRecordSha256"];
+        readonly recordBindingForbiddenUnderNoRecord: readonly ["reviewedRecord", "reviewedRecordSha256"];
+    };
+};
+export type SpecialistRole = keyof typeof SPECIALIST_RESULT_CONTRACT.roles;
+export type OracleReviewKind = keyof typeof SPECIALIST_RESULT_CONTRACT.reviewKinds;
+type SchemaValue<S> = S extends {
+    const: infer C;
+} ? C : S extends {
+    enum: readonly (infer E)[];
+} ? E : S extends {
+    type: 'object';
+    properties: infer P;
+    required: readonly string[];
+} ? {
+    [K in keyof P]: SchemaValue<P[K]>;
+} : S extends {
+    type: 'array';
+    items: infer I;
+} ? SchemaValue<I>[] : S extends {
+    type: 'string';
+} ? string : S extends {
+    type: 'number';
+} ? number : S extends {
+    type: 'boolean';
+} ? boolean : S extends {
+    type: readonly ['string', 'null'];
+} ? string | null : never;
+export type ResultCommon = SchemaValue<typeof common>;
+export type OracleReview = {
+    [K in OracleReviewKind]: {
+        kind: K;
+        verdict: (typeof SPECIALIST_RESULT_CONTRACT.reviewKinds)[K]['verdicts'][number];
+        reviewedRecord?: string;
+        reviewedRecordSha256?: string;
+    };
+}[OracleReviewKind];
+export type SpecialistResult = ResultCommon & {
+    nextAction: string | null;
+    review: OracleReview;
+};
+/** Required field names for compact role-specific prompt rendering. */
+export declare function getSpecialistResultFields(role: SpecialistRole): readonly string[];
+export {};

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

@@ -227,7 +227,7 @@ export declare const SDD_PHASE_PROTOCOLS: readonly [{
     readonly id: "plan-review";
     readonly objective: "Offer optional independent blocker review after the ready plan.";
     readonly requiredInputs: ["Ready substantial record", "Selected review disposition"];
-    readonly instructions: ["At ready, first show the user a concise plan summary (goal, acceptance, units, risks), then always offer “Review plan with Oracle (Recommended)” or “Implement directly without review”; record the plan-review choice as EXPLICIT_REVIEW for an explicit review answer, EXPLICIT_SKIP for an explicit direct answer, or DEFAULT_REVIEW_AFTER_3 only when the third confirmed empty return selects review. Keep selection provenance separate from implementation authorization; silence never means EXPLICIT_SKIP.", "For every orchestrator choice with a meaningful safe recommendation, after its first and second confirmed empty native returns repeat the same question and do no dependent work; after the third confirmed empty native return choose the recommendation. Explicit answers and Stop win. Pending, unavailable, failed, interrupted or host-prohibited questions do not count. If higher-priority host or tool rules prevent asking or repeating, obey them and report the limitation rather than claiming three returns or an explicit selection.", "Never fabricate facts or secrets; recommend safe deferral when needed information or material intent is unresolved, and keep dependent work blocked.", "Review scope, approach, risks, and acceptance coverage without redesigning settled intent.", "Return actionable blockers and cautions; a pass is not implementation authorization or final verification.", "After [OKAY], preserve the separate Implement (Recommended) / Stop authorization decision; honor applicable prior explicit authorization, and let explicit Stop supersede it.", "A plan review does not substitute for fresh final verification."];
+    readonly instructions: ["At ready, first show the user a concise plan summary (goal, acceptance, units, risks), then always offer “Review plan with Oracle (Recommended)” or “Proceed without review”; record the plan-review choice as EXPLICIT_REVIEW for an explicit review answer, EXPLICIT_SKIP for an explicit direct answer, or DEFAULT_REVIEW_AFTER_3 only when the third confirmed empty return selects review. Keep selection provenance separate from implementation authorization; silence never means EXPLICIT_SKIP.", "For every orchestrator choice with a meaningful safe recommendation, after its first and second confirmed empty native returns repeat the same question and do no dependent work; after the third confirmed empty native return choose the recommendation. Explicit answers and Stop win. Pending, unavailable, failed, interrupted or host-prohibited questions do not count. If higher-priority host or tool rules prevent asking or repeating, obey them and report the limitation rather than claiming three returns or an explicit selection.", "Never fabricate facts or secrets; recommend safe deferral when needed information or material intent is unresolved, and keep dependent work blocked.", "Review scope, approach, risks, and acceptance coverage without redesigning settled intent.", "Return actionable blockers and cautions; a pass is not implementation authorization or final verification.", "After [OKAY], preserve the separate Implement (Recommended) / Stop authorization decision; honor applicable prior explicit authorization, and let explicit Stop supersede it.", "A plan review does not substitute for fresh final verification."];
     readonly outputSchema: ["status", "blockers", "cautions"];
     readonly doneWhen: ["The selected review has a current, evidence-backed disposition."];
     readonly blockingConditions: ["A blocking finding remains unresolved."];

package/dist/harness/writers/codex-plugin-package.d.ts

@@ -14,11 +14,18 @@ export interface CodexPluginHookDefinition extends CodexHookValidationInput {
     matcher?: string;
     handler: CodexHookValidationInput['handler'] & {
         command?: unknown;
+        commandWindows?: unknown;
+        timeout?: unknown;
+        additionalContextLimit?: unknown;
     };
 }
 export interface CodexPluginPackageInput {
     manifest: Record<string, unknown>;
     assets?: CodexPluginPackageAsset[];
+    hookFiles?: {
+        path: string;
+        content: string;
+    }[];
 }
 export interface CodexPluginPackageResult {
     artifacts: HarnessArtifact[];

package/dist/harness/writers/pi-agent.d.ts

@@ -11,6 +11,7 @@ export interface PiAgentDefinitionInput {
     instructions: string;
     model?: string;
     effort?: string;
+    skills?: readonly string[];
     subagentMode: 'task' | 'background';
 }
 export declare function getPiSpecialistDefaultTools(role: PiSpecialistRole): string[];

package/dist/index.js

@@ -3,7 +3,7 @@ import {
   renderOpenCodeAgentConfigs,
   spawn,
   spawnSync
-} from "./chunk-MRFCA3U2.js";
+} from "./chunk-ZLEMG37R.js";
 import {
   context7,
   exa,
@@ -14,7 +14,7 @@ import {
   getOpenCodeConfigPaths,
   loadPluginConfig,
   stripJsonComments
-} from "./chunk-OW6I7ZUU.js";
+} from "./chunk-4DZSWTUM.js";
 
 // src/index.ts
 import { fileURLToPath as fileURLToPath3 } from "url";

package/dist/pi.js

@@ -4,10 +4,10 @@ import {
   createPiToolsPanelAdapter,
   renderPiRootInstructions,
   syncPiSpecialists
-} from "./chunk-U7FNFTM5.js";
+} from "./chunk-P7R4GDSO.js";
 import {
   findPackageRoot
-} from "./chunk-OW6I7ZUU.js";
+} from "./chunk-4DZSWTUM.js";
 
 // src/pi.ts
 import { homedir } from "os";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thoth-agents",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Adaptive multi-harness orchestration with six roles, runtime-autonomous AI-first execution routes, and external provider boundaries.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -51,7 +51,8 @@
     ]
   },
   "scripts": {
-    "build": "pnpm run integration:sync && tsup && tsc --emitDeclarationOnly && pnpm run generate-schema && pnpm run build:pi-extensions",
+    "build": "pnpm run generate:result-contract && pnpm run integration:sync && tsup && tsc --emitDeclarationOnly && pnpm run generate-schema && pnpm run build:pi-extensions",
+    "generate:result-contract": "tsx scripts/generate-result-contract.ts",
     "generate-schema": "tsx scripts/generate-schema.ts",
     "integration:sync": "tsx src/harness/generate-integration-packages.ts",
     "integration:verify": "vitest run src/harness/generate-integration-packages.test.ts src/harness/integration-lifecycle.test.ts",
@@ -59,8 +60,9 @@
     "setup:codex:local": "pnpm run build && tsx scripts/setup-codex-local.ts",
     "setup:pi:local": "pnpm run build && node scripts/setup-pi-local.mjs",
     "release:notes": "tsx scripts/generate-release-notes.ts",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.evals.json",
     "test": "vitest run",
+    "eval:pi": "vitest run --config vitest.evals.live.config.ts --reporter=verbose --silent=false",
     "test:pi-extensions": "node --test --test-timeout=110000 scripts/pi-extension-bundles.test.mjs",
     "lint": "biome lint .",
     "format": "biome format . --write",

package/pi/.thoth-agents-assets.json

@@ -2,10 +2,10 @@
   "schemaVersion": 1,
   "owner": "thoth-agents",
   "files": {
-    "agents/thoth-explorer.md": "d9b47792d85e479ed3e0179671223708f097e18c2173320d8a7eb1ab7886775a",
-    "agents/thoth-librarian.md": "82e5e3c1e3e8b589937382e8fb66cf3425914685d88edf968b2b52657f284511",
-    "agents/thoth-oracle.md": "808b2b6cfe9d48113704c64737d836cc14ff7fc2e1c5f87486f3e985aa8b92f5",
-    "agents/thoth-designer.md": "20cc2042c71ad2e2a783d11d75308fee5331a65eb3f066bc0d4046f117031382",
-    "agents/thoth-worker.md": "de9d9e6230ce16279c5bc929d9c1b65574c2fc589aec9a98fe5ea7cebd447323"
+    "agents/thoth-explorer.md": "ab198cc0daaa3d975d1b018098415fff3547462e842c07f279a4951f4013c068",
+    "agents/thoth-librarian.md": "c353faf5d84808a21b33ef57986acd9a2e2e37540538048afc97a22002cd48e4",
+    "agents/thoth-oracle.md": "0e682b7168aca7fa2f880ce79c39ff2f68cf5bc0ed5cd2b55d0861958fe14518",
+    "agents/thoth-designer.md": "d83b3fbcdbca611b208b7fd153a13535819388dce053b8c666d44f2dc22bfcae",
+    "agents/thoth-worker.md": "d60e4f9bdb9fe514bd7ef1ce05d7ab16653d56ec08a900497857fe561b48ef14"
   }
 }

package/pi/agents/thoth-designer.md

@@ -1,9 +1,9 @@
 ---
 name: thoth-designer
-description: "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: conclusion, evidence, verification, risks, openQuestions, nextAction."
+description: "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."
 tools: "read, bash, edit, write, grep, find, ls"
-model: "openai-codex/gpt-6-sol"
-effort: "medium"
+model: "openai-codex/gpt-6-luna"
+effort: "max"
 subagent_mode: "background"
 managed-by: thoth-agents
 ---
@@ -43,33 +43,28 @@ Own user-facing implementation choices and visual quality for UI work.
 - Check relevant responsive and interaction states when feasible.
 </rules>
 
-- Do not delegate further; root owns progress.
+- Do not delegate further or call `todo`; root owns progress.
 - Use terminating checks; avoid watch processes and indefinite waits.
-- Preserve operator-selected model and effort. Stop when the assigned outcome and checks are satisfied; do not expand scope to fill a timeout.
+- Preserve operator-selected model/effort. Stop after the assigned outcome and checks; never expand scope to fill a timeout.
 - After two consecutive attempts without new evidence or progress, return partial evidence and the smallest blocker; do not repeat searches or unchanged failing commands.
-- Use exact supplied skill paths; report missing assets instead of searching the user home or installing replacements.
+- Use the native skill catalog or exact supplied skill paths. If a skill named by the assignment or required by the current phase contract cannot be loaded, return a blocker instead of improvising; do not search the user home or install replacements.
 - 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.
 - Use native command completion; no status/log polling merely to wait. Batch independent short reads/checks when supported; no extra process wrappers.
 - Reconcile owned background commands before returning. A late notification must preserve the substantive handoff, not replace it with a bare acknowledgment.
 - Never discard or overwrite unrelated working-tree changes.
-- Read the dispatch MEMORY block: `none` forbids provider work, `recall` permits bounded reads, and `observe` additionally permits a bounded durable observation under the delegated scope.
-- For `recall` or `observe`, load and follow the installed `thoth-mem` skill; do not invent provider mechanics or claim unconfirmed effects.
-- MEMORY authorization does not authorize workspace mutation. It never transfers root lifecycle or real-user-intent ownership to a child.
-- `.thoth/` holds active project work, durable specs, and constitution; historical material is preserved. It is not provider memory; do not mirror work artifacts.
-- Report unavailable, degraded, stale, contradictory, or insufficient memory evidence and continue unrelated assigned work when safe.
+- `none`: no provider work; `recall`: bounded reads; `observe`: + bounded durable observation in scope.
+- `recall`/`observe`: installed `thoth-mem` skill; do not invent provider mechanics/claim unconfirmed effects.
+- Only dispatch identity, verbatim; never derive. If missing, report memory unavailable.
+- MEMORY: no workspace mutation or root lifecycle/real-user-intent authority.
+- `.thoth/`: work/specs/constitution/history—not provider memory; no artifact mirrors.
+- Report unavailable/degraded/stale/contradictory/insufficient memory; continue unrelated safe work.
 
 <questions>
 Do not open a user dialog. Continue safe non-blocked work, then escalate the unresolved question to the root through openQuestions with the material choices and a recommended default.
 </questions>
 
 <return-contract>
-Return a compact result with these fields:
-- conclusion
-- evidence
-- verification
-- risks
-- openQuestions
-- nextAction
+Return compact markdown fields (no JSON): conclusion, evidence, verification, risks, openQuestions, nextAction, changedFiles.
 </return-contract>
 
 Be concise. Return distilled evidence and outcomes, not raw logs or full-file dumps.
@@ -87,10 +82,10 @@ Be concise. Return distilled evidence and outcomes, not raw logs or full-file du
 
 - Child tools are filtered by `tools`, configuration, `disallowed_tools`, and native `subagent_*` exclusions with runtime-verified registry filtering; behavioral role limits are instruction-level, not an OS or credential sandbox.
 
-- When available, use `ask_orchestrator({ kind: "question", message: "…" })` only for material alignment or clarification ambiguity that blocks this assignment. Never use it as a substitute for your own discovery, to delegate, or to request other agents. Keep questions concise.
+- When available, use `ask_orchestrator({ message: "…" })` only for material alignment or clarification ambiguity that blocks this assignment. Never use it as a substitute for your own discovery, to delegate, or to request other agents. Keep questions concise.
 
 - A question waits for the root reply in this same session. If the tool is unavailable, use the return contract's `openQuestions`; continue safe non-blocked work without opening a user dialog.
 
-- Optional brief `ask_orchestrator({ kind: "progress", message: "…" })` updates return immediately, are recorded on this task, and do not trigger a root turn; root still owns progress tracking.
+- Optional brief `notify_orchestrator({ message: "…" })` progress/checkpoint updates return immediately, are recorded on this task, and do not trigger a root turn; root still owns progress tracking.
 
 </role-operational-contract>

package/pi/agents/thoth-explorer.md

@@ -1,9 +1,9 @@
 ---
 name: thoth-explorer
-description: "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: conclusion, evidence, verification, risks, openQuestions."
-tools: "read, bash, grep, find, ls"
+description: "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."
+tools: "read, bash, grep, find, ls, codemode"
 model: "openai-codex/gpt-6-luna"
-effort: "low"
+effort: "max"
 subagent_mode: "background"
 managed-by: thoth-agents
 ---
@@ -47,32 +47,28 @@ Resolve broad or uncertain repository questions and return distilled evidence.
 - 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.
 </evidence-only>
 
-- Do not delegate further; root owns progress.
+- Do not delegate further or call `todo`; root owns progress.
 - Use terminating checks; avoid watch processes and indefinite waits.
-- Preserve operator-selected model and effort. Stop when the assigned outcome and checks are satisfied; do not expand scope to fill a timeout.
+- Preserve operator-selected model/effort. Stop after the assigned outcome and checks; never expand scope to fill a timeout.
 - After two consecutive attempts without new evidence or progress, return partial evidence and the smallest blocker; do not repeat searches or unchanged failing commands.
-- Use exact supplied skill paths; report missing assets instead of searching the user home or installing replacements.
+- Use the native skill catalog or exact supplied skill paths. If a skill named by the assignment or required by the current phase contract cannot be loaded, return a blocker instead of improvising; do not search the user home or install replacements.
 - 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.
 - Use native command completion; no status/log polling merely to wait. Batch independent short reads/checks when supported; no extra process wrappers.
 - Reconcile owned background commands before returning. A late notification must preserve the substantive handoff, not replace it with a bare acknowledgment.
 - Never discard or overwrite unrelated working-tree changes.
-- Read the dispatch MEMORY block: `none` forbids provider work, `recall` permits bounded reads, and `observe` additionally permits a bounded durable observation under the delegated scope.
-- For `recall` or `observe`, load and follow the installed `thoth-mem` skill; do not invent provider mechanics or claim unconfirmed effects.
-- MEMORY authorization does not authorize workspace mutation. It never transfers root lifecycle or real-user-intent ownership to a child.
-- `.thoth/` holds active project work, durable specs, and constitution; historical material is preserved. It is not provider memory; do not mirror work artifacts.
-- Report unavailable, degraded, stale, contradictory, or insufficient memory evidence and continue unrelated assigned work when safe.
+- `none`: no provider work; `recall`: bounded reads; `observe`: + bounded durable observation in scope.
+- `recall`/`observe`: installed `thoth-mem` skill; do not invent provider mechanics/claim unconfirmed effects.
+- Only dispatch identity, verbatim; never derive. If missing, report memory unavailable.
+- MEMORY: no workspace mutation or root lifecycle/real-user-intent authority.
+- `.thoth/`: work/specs/constitution/history—not provider memory; no artifact mirrors.
+- Report unavailable/degraded/stale/contradictory/insufficient memory; continue unrelated safe work.
 
 <questions>
 Do not open a user dialog. Continue safe non-blocked work, 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.
 </questions>
 
 <return-contract>
-Return a compact result with these fields:
-- conclusion
-- evidence
-- verification
-- risks
-- openQuestions
+Return compact markdown fields (no JSON): conclusion, evidence, verification, risks, openQuestions.
 </return-contract>
 
 Be concise. Return distilled evidence and outcomes, not raw logs or full-file dumps.
@@ -90,11 +86,11 @@ Be concise. Return distilled evidence and outcomes, not raw logs or full-file du
 
 - Child tools are filtered by `tools`, configuration, `disallowed_tools`, and native `subagent_*` exclusions with runtime-verified registry filtering; behavioral role limits are instruction-level, not an OS or credential sandbox.
 
-- When available, use `ask_orchestrator({ kind: "question", message: "…" })` only for material alignment or clarification ambiguity that blocks this assignment. Never use it as a substitute for your own discovery, to delegate, or to request other agents. Keep questions concise.
+- When available, use `ask_orchestrator({ message: "…" })` only for material alignment or clarification ambiguity that blocks this assignment. Never use it as a substitute for your own discovery, to delegate, or to request other agents. Keep questions concise.
 
 - A question waits for the root reply in this same session. If the tool is unavailable, use the return contract's `openQuestions`; continue safe non-blocked work without opening a user dialog.
 
-- Optional brief `ask_orchestrator({ kind: "progress", message: "…" })` updates return immediately, are recorded on this task, and do not trigger a root turn; root still owns progress tracking.
+- Optional brief `notify_orchestrator({ message: "…" })` progress/checkpoint updates return immediately, are recorded on this task, and do not trigger a root turn; root still owns progress tracking.
 
 - Questions and progress report facts only: include options and evidence without recommending fixes, designs, defaults, or next actions.