open-multi-agent-kit 0.95.0 → 0.95.2

package/docs/sdk.md

@@ -5,6 +5,7 @@
 The SDK provides programmatic access to omk's agent capabilities. Use it to embed omk in other applications, build custom interfaces, or integrate with automated workflows.
 
 **Example use cases:**
+
 - Build a custom UI (web, desktop, mobile)
 - Integrate agent capabilities into existing applications
 - Create automated pipelines with agent reasoning
@@ -112,6 +113,7 @@ interface AgentSession {
   thinkingLevel: ThinkingLevel;
   messages: AgentMessage[];
   isStreaming: boolean;
+  getSessionStats(): SessionStats;
 
   // In-place tree navigation within the current session file
   navigateTree(targetId: string, options?: { summarize?: boolean; customInstructions?: string; replaceInstructions?: boolean; label?: string }): Promise<{ editorText?: string; cancelled: boolean }>;
@@ -128,6 +130,8 @@ interface AgentSession {
 }
 ```
 
+`getSessionStats()` returns message, token, and cost totals. Its `promptCache` field includes provider-eligible input tokens, provider hit rate (`cacheRead / (input + cacheRead + cacheWrite)`), stable-prefix characters, cache-key changes, boundary bypasses, and the last local break reason. These values diagnose cache-affinity changes; only provider-reported `cacheRead` proves a hit.
+
 Session replacement APIs such as new-session, resume, fork, and import live on `AgentSessionRuntime`, not on `AgentSession`.
 
 ### createAgentSessionRuntime() and AgentSessionRuntime
@@ -250,6 +254,7 @@ await session.prompt("After you're done, also check X", { streamingBehavior: "fo
 ```
 
 **Behavior:**
+
 - **Extension commands** (e.g., `/mycommand`): Execute immediately, even during streaming. They manage their own LLM interaction via `omk.sendMessage()`.
 - **File-based prompt templates** (from `.md` files): Expanded to their content before sending or queueing.
 - **During streaming without `streamingBehavior`**: Throws an error. Use `steer()` or `followUp()` directly, or specify the option.
@@ -280,6 +285,8 @@ const state = session.agent.state;
 // state.model: Model - current model
 // state.thinkingLevel: ThinkingLevel - current thinking level
 // state.systemPrompt: string - system prompt
+// state.systemPromptCacheBoundary?: number - stable-prefix UTF-16 offset
+// state.systemPromptCacheBoundaryBypass?: boolean - suppress explicit cache affinity/markers
 // state.tools: AgentTool[] - available tools
 // state.streamingMessage?: AgentMessage - current partial assistant message
 // state.errorMessage?: string - latest assistant error
@@ -294,6 +301,8 @@ session.agent.state.tools = tools; // copies the top-level array
 await session.agent.waitForIdle();
 ```
 
+The cache boundary must be a positive safe integer no greater than `systemPrompt.length`. Missing, invalid, or bypassed boundaries suppress explicit stable-prefix cache metadata. Providers may still ignore valid metadata, so inspect provider usage before claiming a hit.
+
 ### Events
 
 Subscribe to events to receive streaming output and lifecycle notifications.
@@ -380,6 +389,7 @@ const { session } = await createAgentSession({
 ```
 
 `cwd` is used by `DefaultResourceLoader` for:
+
 - Project extensions (`.omk/extensions/`)
 - Project skills:
   - `.omk/skills/`
@@ -389,6 +399,7 @@ const { session } = await createAgentSession({
 - Session directory naming
 
 `agentDir` is used by `DefaultResourceLoader` for:
+
 - Global extensions (`extensions/`)
 - Global skills:
   - `skills/` under `agentDir` (for example `~/.omk/agent/skills/`)
@@ -438,6 +449,7 @@ const { session } = await createAgentSession({
 ```
 
 If no model is provided:
+
 1. Tries to restore from session (if continuing)
 2. Uses default from settings
 3. Falls back to first available model
@@ -447,6 +459,7 @@ If no model is provided:
 ### API Keys and OAuth
 
 API key resolution priority (handled by AuthStorage):
+
 1. Runtime overrides (via `setRuntimeApiKey`, not persisted)
 2. Stored credentials in `auth.json` (API keys or OAuth tokens)
 3. Environment variables (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, etc.)
@@ -499,6 +512,8 @@ await loader.reload();
 const { session } = await createAgentSession({ resourceLoader: loader });
 ```
 
+OMK records a stable cache boundary before loaded context files, selected skill content, the date, and the working directory. A turn-level extension that replaces the built prompt bypasses explicit stable-prefix caching unless it returns the prompt unchanged. See [Compaction & Branch Summarization](compaction.md#context-reduction-and-prompt-caching) for provider behavior and diagnostics.
+
 > See [examples/sdk/03-custom-prompt.ts](../examples/sdk/03-custom-prompt.ts)
 
 ### Tools
@@ -847,12 +862,14 @@ const { session } = await createAgentSession({
 ```
 
 **Static factories:**
+
 - `SettingsManager.create(cwd?, agentDir?)` - Load from files
 - `SettingsManager.inMemory(settings?)` - No file I/O
 
 **Project-specific settings:**
 
 Settings load from two locations and merge:
+
 1. Global: `~/.omk/agent/settings.json`
 2. Project: `<cwd>/.omk/settings.json`
 
@@ -1120,12 +1137,14 @@ omk --mode rpc --no-session
 See [RPC documentation](rpc.md) for the JSON protocol.
 
 The SDK is preferred when:
+
 - You want type safety
 - You're in the same Node.js process
 - You need direct access to agent state
 - You want to customize tools/extensions programmatically
 
 RPC mode is preferred when:
+
 - You're integrating from another language
 - You want process isolation
 - You're building a language-agnostic client
@@ -1134,14 +1153,16 @@ RPC mode is preferred when:
 
 Execution-bound evidence records a declared verification command and reported outcome between two artifact-set snapshots, then binds that record to a tamper-evident ledger. `VerifiedEvidenceExecutor` never executes the declared command. `executeVerifiedBash()` invokes caller-supplied `BashOperations`; `executeVerifiedLocalBash()` derives the shell identity and runner from OMK's built-in local backend.
 
-**Default path (opt-out):** when an AgentSession has a replay ledger (persisted sessions create one automatically), LLM-callable `bash` and interactive/RPC `executeBash` bind through `executeVerifiedBash` with `executor: "bash-tool"` and receipts under `<sessionFile>.evidence/receipts` (or `cwd/.omk/session-evidence/<goalId>/receipts` for ephemeral sessions). Session workspace scope is git-aware: inside a worktree, the receipt binds the toplevel plus the sorted dirty set (capped at 32 paths, 1 s TTL). Set `OMK_VERIFIED_BASH=0` to restore the legacy unverified path. Custom `createBashTool()` calls stay unverified unless the caller wraps operations with `createVerifiedBashOperations()`. CI still runs release-consistency through `executeVerifiedLocalBash()` with `executor: "ci-runner"`.
+**Default path (opt-out):** when an AgentSession has a replay ledger (persisted sessions create one automatically), LLM-callable `bash` and interactive/RPC `executeBash` bind through `executeVerifiedBash` with `executor: "bash-tool"` and receipts under `<sessionFile>.evidence/receipts` (or `cwd/.omk/session-evidence/<goalId>/receipts` for ephemeral sessions). Session workspace scope is git-aware: inside a worktree, the receipt binds the toplevel plus up to 32 sorted dirty file paths (1 s TTL). Git status expands ordinary untracked directories to files; untracked nested repositories remain outside the parent scope. Set `OMK_VERIFIED_BASH=0` to restore the legacy unverified path. Custom `createBashTool()` calls stay unverified unless the caller wraps operations with `createVerifiedBashOperations()`. CI still runs release-consistency through `executeVerifiedLocalBash()` with `executor: "ci-runner"`.
+
+**Default sandbox (opt-out):** session bash defaults to `enforce`. Every built-in local spawn is wrapped by macOS `sandbox-exec` or Linux `bwrap`, writes are limited to the session workspace and OS temp directory, and network access is disabled. If the platform is unsupported or the backend is unavailable, the spawn fails closed with `sandbox.backend_missing`. Set `OMK_BASH_SANDBOX=audit` only for an unwrapped compatibility path that records each decision as a `sandbox_audit` replay event; set `OMK_BASH_SANDBOX=0` to disable the preflight entirely. Unknown values resolve to `enforce`.
 
-**Default sandbox (opt-out):** session bash also carries a default `audit`-mode sandbox preflight (workspace-write policy rooted at the session cwd). The spawn stays unwrapped, but every decision is appended to the replay ledger as a `sandbox_audit` event, giving a tamper-evident audit trail. `OMK_BASH_SANDBOX=enforce` activates the real OS backend — macOS `sandbox-exec` seatbelt or Linux `bwrap` bubblewrap — and fails closed when neither is installed; `OMK_BASH_SANDBOX=0` disables the preflight entirely.
+This boundary applies to AgentSession's built-in local bash operations. Custom `createBashTool()` calls remain unsandboxed unless they receive a `sandboxPolicy`, and injected or remote `BashOperations` own their own isolation. The default workspace-write profile is not a read-confidentiality boundary or whole-process container; use [Containerization](containerization.md) when every tool and extension must be isolated.
 
 ### Recorded and invoked inputs
 
 | Input | SDK behavior |
-|-------|--------------|
+| ------- | -------------- |
 | `request.command` (`EvidenceCommandDescriptor`) | Validates, hashes, and records the structured descriptor; never executes it |
 | `request.executor` (`"bash-tool" \| "ci-runner" \| "mcp" \| "internal"`) | Records a label only |
 | `request.workspaceScope` (`WorkspaceScope`) | Captures the selected artifact set before and after the callback |
@@ -1196,7 +1217,7 @@ Ledger and receipt publication are fail-closed but not one filesystem transactio
 `EvidenceGate` (default `receiptMode: "prefer"`) gates a `TaskContract` against its satisfied receipts. Pass `executor.createGateOptions()` so the gate resolves receipts, ledger events, and workspace fingerprints from the same store and ledger.
 
 | Mode | Soft missing data | Tamper-grade mismatch | Legacy `hash` / `command` |
-|------|-------------------|-----------------------|----------------------------|
+| ------ | ------------------- | ----------------------- | ---------------------------- |
 | `strict` | blocked | blocked | n/a |
 | `prefer` (default) | conditional | blocked | n/a |
 | `legacy` | receipt checks skipped | receipt checks skipped | checked by legacy options (enabled by default) |

package/docs/settings.md

@@ -17,7 +17,7 @@ Edit directly or use `/settings` for common options.
 | --------- | ------ | --------- | ------------- |
 | `defaultProvider` | string | - | Default provider (e.g., `"anthropic"`, `"openai"`) |
 | `defaultModel` | string | - | Default model ID |
-| `defaultThinkingLevel` | string | - | `"off"`, `"minimal"`, `"low"`, `"medium"`, `"high"`, `"xhigh"` |
+| `defaultThinkingLevel` | string | - | `"off"`, `"minimal"`, `"low"`, `"medium"`, `"high"`, `"xhigh"`, `"max"`, `"ultra"` |
 | `hideThinkingBlock` | boolean | `false` | Hide thinking blocks in output |
 | `thinkingBudgets` | object | - | Custom token budgets per thinking level |
 | `reasoningRouterLearning` | object | - | Opt-in v4 router learning bias (global settings file only) |
@@ -41,16 +41,16 @@ Edit directly or use `/settings` for common options.
 ```json
 {
   "reasoningRouterLearning": {
-    "enabled": false,
-    "biasSnapshotPath": "~/.omk/agent/router-bias.json",
-    "feedbackLedgerPath": "~/.omk/agent/router-feedback.jsonl"
+    "enabled": false
   }
 }
 ```
 
+This opt-in remains global-only, but its default data is isolated per repository or git worktree under `~/.omk/agent/router-feedback/repositories/<opaque-scope>/`. The scope is derived from the canonical worktree root and never stores the raw path. Set `biasSnapshotPath` or `feedbackLedgerPath` only when intentionally overriding that isolation with fixed paths.
+
 #### adaptorchBridge
 
-Advisory-only hint source for the v4 auto thinking-level resolver. Read from the **global** settings file only — a project-scope `.omk/settings.json` value is ignored by design. Default is fully off; the bridge is circuit-breaker protected and TTL-cached, and its hint can only nudge the resolved level by a bounded ±2 steps.
+Global-only, default-off lifecycle for a future v4 advisory source. The timeout, TTL, consult-budget, and circuit-breaker controls are wired, but the current transport is a no-op and cannot change the resolved level. A project-scope `.omk/settings.json` value is ignored by design.
 
 ```json
 {
@@ -70,7 +70,8 @@ Advisory-only hint source for the v4 auto thinking-level resolver. Read from the
 | --------- | ------ | --------- | ------------- |
 | `theme` | string | `"dark"` | Theme name (`"dark"`, `"light"`, or custom) |
 | `quietStartup` | boolean | `false` | Hide startup header |
-| `collapseChangelog` | boolean | `false` | Show condensed changelog after updates |
+| `collapseChangelog` | boolean | `true` | Show condensed changelog after updates (set `false` for the full "What's New" block) |
+| `footerSystemMetrics` | boolean | `false` | Show system-wide CPU/MEM usage in the footer stats line |
 | `enableInstallTelemetry` | boolean | `true` | Send an anonymous install/update version ping after first install or changelog-detected updates. This does not control update checks |
 | `doubleEscapeAction` | string | `"tree"` | Action for double-escape: `"tree"`, `"fork"`, or `"none"` |
 | `treeFilterMode` | string | `"default"` | Default filter for `/tree`: `"default"`, `"no-tools"`, `"user-only"`, `"labeled-only"`, `"all"` |
@@ -156,7 +157,7 @@ This setting is global-only: `.omk/settings.json` cannot enable or disable it. U
 | `agent.toolTimeoutMs` | number | `0` | Fallback tool execution timeout in milliseconds; `0` disables the fallback timer |
 | `agent.toolTimeouts` | object | built-in defaults | Per-tool-name timeout overrides; `0` disables that tool's timer |
 
-Built-in defaults are 30 seconds for `read`, `grep`, `find`, and `ls`; 60 seconds for `edit` and `write`; and 300 seconds for `bash`. Explicit `agent.toolTimeouts` entries override these defaults. Extension/custom tools without a per-name value use `agent.toolTimeoutMs`. Timeout values must be integer milliseconds from `0` through `2147483647`.
+Built-in defaults are 30 seconds for `read`, `grep`, `find`, and `ls`; 60 seconds for `edit` and `write`; and 300 seconds for `bash`. Explicit `agent.toolTimeouts` entries override these defaults. Extension tools may override settings per call with `resolveTimeoutMs(ctx)`; otherwise custom tools without a per-name value use `agent.toolTimeoutMs`. Timeout values must be integer milliseconds from `0` through `2147483647`.
 
 ```json
 {

package/docs/usage.md

@@ -87,9 +87,19 @@ Precedence:
 
 Resolved levels are clamped to the model's capabilities: models without `xhigh`/`max` are capped at their highest supported level, and models without reasoning support bypass the router entirely.
 
-The v4 learning path is available only through the global `reasoningRouterLearning` setting and is off by default. When `reasoningRouterLearning.enabled` is `true`, `/think auto` loads one validated bias snapshot for the session, applies a bounded `-2..2` ladder-step bias, and appends a privacy-safe feedback record containing only bounded enums, booleans, and buckets. Project-local settings cannot enable or redirect this feature, and the ledger never stores raw prompts, file paths, diffs, session identifiers, model/provider payloads, tool output, or hook output.
+The v4 learning path is available only through the global `reasoningRouterLearning` setting and is off by default. When enabled, `/think auto` loads one validated, session-pinned bias snapshot, applies a bounded `-2..2` ladder-step bias, and appends a privacy-safe record containing only bounded enums, booleans, and buckets. A later explicit `/think <level>` choice adds one directional `s1-override` record for the same decision. Project-local settings cannot enable the feature, and records never contain raw prompts, repository paths, diffs, session identifiers, provider payloads, tool output, or hook output.
 
-The Adaptorch advisory bridge module still ships as default-off groundwork only. It has no settings key, command, transport, or session call site yet, so it does not affect `/think auto` until a future transport and security review explicitly wire it.
+Default ledgers and snapshots are isolated by an opaque hash of the canonical repository or git worktree root. Compile the current repository's accumulated records between sessions:
+
+```bash
+omk router-feedback compile-bias --cwd /path/to/repository
+```
+
+Compilation is deterministic. It creates a randomized same-directory temporary file exclusively, enforces POSIX mode `0600`, then atomically renames it over the snapshot; this is atomic replacement, not `fsync`-backed crash durability, and explicit output paths should use a trusted directory. Snapshot loading fails closed on malformed or internally inconsistent cells, including any nonzero bias backed by fewer than five strong records. A session pins either a snapshot or a miss on its first learning-enabled auto turn, so later compilations are observed only by sessions that have not yet attempted that load. Fixed `biasSnapshotPath` or `feedbackLedgerPath` session settings remain explicit compatibility overrides and can intentionally share state across repositories; pass matching `--out` or `--ledger` paths to the compiler when using them.
+
+The ledger intentionally keeps causal buckets instead of free-form memories or raw trajectories. This follows CLIN's causal-abstraction approach ([arXiv:2310.10134](https://arxiv.org/abs/2310.10134)) and session-boundary updates from the Red Queen Gödel Machine ([arXiv:2606.26294](https://arxiv.org/abs/2606.26294)); CTIM-Rover found that repository-level episodic memories could add distracting noise and failed to improve its base coding agent ([arXiv:2505.23422](https://arxiv.org/abs/2505.23422)).
+
+The Adaptorch advisory bridge is also global-only and default-off. Its timeout, TTL, consult-budget, and circuit-breaker lifecycle is wired, but the current advisory transport is a no-op and cannot change the router level.
 
 ## Message Queue
 
@@ -242,7 +252,7 @@ cat README.md | omk -p "Summarize this text"
 | `--provider <name>` | Provider, such as `anthropic`, `openai`, or `google` |
 | `--model <pattern>` | Model pattern or ID; supports `provider/id` and optional `:<thinking>` |
 | `--api-key <key>` | API key, overriding environment variables |
-| `--thinking <level>` | `off`, `minimal`, `low`, `medium`, `high`, `xhigh` |
+| `--thinking <level>` | `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`, `ultra` |
 | `--models <patterns>` | Comma-separated patterns for Ctrl+P cycling |
 | `--list-models [search]` | List available models |
 

package/examples/extensions/custom-provider-anthropic/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "omk-extension-custom-provider-anthropic",
-  "version": "0.95.0",
+  "version": "0.95.2",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "omk-extension-custom-provider-anthropic",
-      "version": "0.95.0",
+      "version": "0.95.2",
       "dependencies": {
         "@anthropic-ai/sdk": "0.52.0"
       }

package/examples/extensions/custom-provider-anthropic/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "omk-extension-custom-provider-anthropic",
 	"private": true,
-	"version": "0.95.0",
+	"version": "0.95.2",
 	"type": "module",
 	"scripts": {
 		"clean": "echo 'nothing to clean'",

package/examples/extensions/custom-provider-gitlab-duo/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "omk-extension-custom-provider-gitlab-duo",
 	"private": true,
-	"version": "0.95.0",
+	"version": "0.95.2",
 	"type": "module",
 	"scripts": {
 		"clean": "echo 'nothing to clean'",

package/examples/extensions/gondolin/package-lock.json

@@ -1,12 +1,12 @@
 {
 	"name": "omk-extension-gondolin",
-	"version": "0.95.0",
+	"version": "0.95.2",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "omk-extension-gondolin",
-			"version": "0.95.0",
+			"version": "0.95.2",
 			"dependencies": {
 				"@earendil-works/gondolin": "0.12.0"
 			}

package/examples/extensions/gondolin/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "omk-extension-gondolin",
 	"private": true,
-	"version": "0.95.0",
+	"version": "0.95.2",
 	"type": "module",
 	"scripts": {
 		"clean": "echo 'nothing to clean'",

package/examples/extensions/plannotator-approval-bridge.ts

@@ -0,0 +1,83 @@
+import { readFileSync, realpathSync, statSync } from "node:fs";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import {
+	ApprovalReceiptStore,
+	type ExtensionAPI,
+	type ExtensionCommandContext,
+	type ExtensionContext,
+	PlannotatorApprovalBridge,
+} from "open-multi-agent-kit";
+
+interface LoadedPlan {
+	path: string;
+	content: string;
+}
+
+function loadWorkspacePlan(cwd: string, input: string): LoadedPlan {
+	const workspaceRoot = realpathSync(cwd);
+	const planPath = realpathSync(resolve(workspaceRoot, input));
+	const relativePath = relative(workspaceRoot, planPath);
+	if (!relativePath || relativePath === ".." || relativePath.startsWith(`..${sep}`) || isAbsolute(relativePath)) {
+		throw new Error("Plan must be a file inside the current workspace");
+	}
+	if (!statSync(planPath).isFile()) throw new Error("Plan must be a regular file");
+	return { path: relativePath.split(sep).join("/"), content: readFileSync(planPath, "utf8") };
+}
+
+export default function plannotatorApprovalBridgeExtension(omk: ExtensionAPI): void {
+	let bridge: PlannotatorApprovalBridge | undefined;
+
+	function initializeBridge(ctx: ExtensionContext): void {
+		bridge?.dispose();
+		bridge = new PlannotatorApprovalBridge({
+			eventBus: omk.events,
+			store: new ApprovalReceiptStore(join(ctx.sessionManager.getSessionDir(), "approval-receipts")),
+			workspaceRoot: ctx.cwd,
+			sessionId: ctx.sessionManager.getSessionId(),
+			interactive: ctx.mode === "tui" && ctx.hasUI,
+			requestTimeoutMs: 5_000,
+			onReceipt: (receipt, write) => {
+				omk.appendEntry("approval-receipt-v1", receipt);
+				ctx.ui.notify(
+					`Approval ${receipt.core.decision}; immutable receipt ${write.created ? "created" : "verified"}. No execution was started.`,
+					receipt.core.decision === "approved" ? "info" : "warning",
+				);
+			},
+			onError: () => ctx.ui.notify("Ignored an invalid or uncorrelated Plannotator event.", "warning"),
+		});
+		bridge.start();
+	}
+
+	omk.on("session_start", async (_event, ctx) => initializeBridge(ctx));
+	omk.on("session_shutdown", async () => {
+		bridge?.dispose();
+		bridge = undefined;
+	});
+
+	omk.registerCommand("approval-review", {
+		description: "Review a workspace plan with Plannotator and persist a non-executing approval receipt",
+		handler: async (args: string, ctx: ExtensionCommandContext) => {
+			if (ctx.mode !== "tui" || !ctx.hasUI) {
+				ctx.ui.notify("Approval review requires interactive TUI mode.", "error");
+				return;
+			}
+			if (!bridge) initializeBridge(ctx);
+			const input = args.trim();
+			if (!input) {
+				ctx.ui.notify("Usage: /approval-review <workspace-relative-plan.md>", "warning");
+				return;
+			}
+			try {
+				const plan = loadWorkspacePlan(ctx.cwd, input);
+				const correlation = await bridge?.requestReview({ planPath: plan.path, planContent: plan.content });
+				if (!correlation) throw new Error("Approval bridge is unavailable");
+				ctx.ui.notify(
+					`Plannotator review opened (${correlation.reviewId}); waiting for an explicit decision.`,
+					"info",
+				);
+			} catch {
+				ctx.ui.notify("Approval review failed. Confirm the plan path and that Plannotator is loaded.", "error");
+			}
+		},
+	});
+}

package/examples/extensions/sandbox/package-lock.json

@@ -1,12 +1,12 @@
 {
 	"name": "omk-extension-sandbox",
-	"version": "0.95.0",
+	"version": "0.95.2",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "omk-extension-sandbox",
-			"version": "0.95.0",
+			"version": "0.95.2",
 			"dependencies": {
 				"@anthropic-ai/sandbox-runtime": "0.0.26"
 			}

package/examples/extensions/sandbox/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "omk-extension-sandbox",
 	"private": true,
-	"version": "0.95.0",
+	"version": "0.95.2",
 	"type": "module",
 	"scripts": {
 		"clean": "echo 'nothing to clean'",

package/examples/extensions/subagent/README.md

@@ -5,8 +5,11 @@ Delegate tasks to specialized subagents with isolated context windows.
 ## Features
 
 - **Isolated context**: Each subagent runs in a separate `omk` process
+- **Session model inheritance**: Agents without `model` use the parent session's currently selected model; an explicit `model` pins the child
 - **Streaming output**: See tool calls and progress as they happen
 - **Parallel streaming**: All parallel tasks stream updates simultaneously
+- **Validated task graphs**: Dependency DAGs fail closed on duplicate/unknown/cyclic nodes and execute in deterministic parallel waves
+- **Explicit handoffs**: Graph nodes receive only declared dependency output and only when their task includes `{dependencies}`
 - **Markdown rendering**: Final output rendered with proper formatting (expanded view)
 - **Usage tracking**: Shows turns, tokens, cost, and context usage per agent
 - **Abort support**: Ctrl+C propagates to the entire detached subagent process tree
@@ -14,6 +17,7 @@ Delegate tasks to specialized subagents with isolated context windows.
 - **Checkpoint resume**: A cutoff resumes only the unfinished shard with bounded prior evidence
 - **Cutoff learning**: Completion/cutoff history is persisted per provider and model under the agent state directory
 - **Bounded cost**: At most 3 semantic shards and 1 resume across the whole logical task by default
+- **Ultra execution**: Removes task-count, concurrency, internal deadline, and outer tool-timeout caps; Ctrl+C cancellation still propagates
 
 ## Structure
 
@@ -49,7 +53,7 @@ mkdir -p ~/.omk/agent/extensions/subagent
 src="$(pwd)/packages/coding-agent/examples/extensions/subagent"
 for f in index.ts agents.ts agent-capability-router.ts capabilities.ts domain-profiles.ts \
   adaptive-agent-runtime.ts adaptive-result.ts checkpoint-runtime.ts deadline-budget.ts \
-  deadline-profile-store.ts managed-process.ts subagent-runtime-types.ts; do
+  deadline-profile-store.ts managed-process.ts subagent-runtime-types.ts workflow-graph.ts; do
   ln -sf "$src/$f" ~/.omk/agent/extensions/subagent/$f
 done
 
@@ -107,15 +111,18 @@ Use a chain: first have scout find the read tool, then have planner suggest impr
 | Mode | Parameter | Description |
 |------|-----------|-------------|
 | Single | `{ agent, task }` | One logical task; the runtime may split it into bounded semantic shards |
-| Parallel | `{ tasks: [...] }` | Multiple logical tasks run concurrently (max 8, 4 concurrent) |
+| Parallel | `{ tasks: [...] }` | Multiple logical tasks; non-Ultra allows max 8 and 4 concurrent, while Ultra starts all requested tasks concurrently |
 | Chain | `{ chain: [...] }` | Sequential with `{previous}` placeholder and a fair deadline share per remaining step |
+| Graph | `{ graph: [{ id, agent, task, dependsOn? }] }` | Validated dependency DAG; ready nodes run in parallel waves, and any failed wave blocks downstream nodes |
+
+Graph nodes opt in to dependency output by placing `{dependencies}` in `task`. The runtime injects only outputs named in that node's `dependsOn`; without the placeholder, no prior output is appended. Each dependency handoff is capped at 16 KiB. This keeps large or unrelated context from leaking across nodes.
 
 Optional execution controls:
 
 | Parameter | Default | Description |
 |-----------|---------|-------------|
-| `executionBudgetMs` | `840000` | Internal hard budget, leaving 60 seconds before a configured 900000 ms tool timeout |
-| `maxResumeAttempts` | `1` | Retries only the active unfinished shard; accepted range is 0-2 |
+| `executionBudgetMs` | `840000` | Non-Ultra internal hard budget; when explicitly supplied it also bounds Ultra execution, otherwise Ultra is unbounded |
+| `maxResumeAttempts` | `1` | Retries only the active unfinished shard; accepted range is 0-2 and ignored by unbounded Ultra execution |
 
 ## Output Display
 
@@ -152,12 +159,13 @@ Agents are markdown files with YAML frontmatter:
 name: my-agent
 description: What this agent does
 tools: read, grep, find, ls
-model: claude-haiku-4-5
 ---
 
 System prompt for the agent goes here.
 ```
 
+`model` is optional. Omit it to inherit the model currently selected in the parent session; set it only when the agent must be pinned to a specific model.
+
 **Locations:**
 - `~/.omk/agent/agents/*.md` - User-level (always loaded)
 - `.omk/agents/*.md` - Project-level (only with `agentScope: "project"` or `"both"`)
@@ -168,10 +176,10 @@ Project agents override user agents with the same name when `agentScope: "both"`
 
 | Agent | Purpose | Model | Tools |
 |-------|---------|-------|-------|
-| `scout` | Fast codebase recon | Haiku | read, grep, find, ls, bash |
-| `planner` | Implementation plans | Sonnet | read, grep, find, ls |
-| `reviewer` | Code review | Sonnet | read, grep, find, ls, bash |
-| `worker` | General-purpose | Sonnet | (all default) |
+| `scout` | Fast codebase recon | Parent session | read, grep, find, ls, bash |
+| `planner` | Implementation plans | Parent session | read, grep, find, ls |
+| `reviewer` | Code review | Parent session | read, grep, find, ls, bash |
+| `worker` | General-purpose | Parent session | (all default) |
 
 ## Workflow Prompts
 
@@ -186,8 +194,10 @@ Project agents override user agents with the same name when `agentScope: "both"`
 - **Exit code != 0**: Tool returns error with stderr/output
 - **stopReason "error"**: LLM error propagated with error message
 - **stopReason "aborted"**: User abort (Ctrl+C) terminates and reaps the subprocess tree
-- **stopReason "deadline"**: Internal cutoff returns elapsed/deadline/checkpoint/resume metadata instead of reaching the outer tool timeout
+- **stopReason "deadline"**: Outside Ultra, an internal cutoff returns elapsed/deadline/checkpoint/resume metadata instead of reaching the outer tool timeout
+- **Ultra**: No scheduler or attempt deadline is armed; provider, network, OS, and explicit caller cancellation still apply
 - **Chain mode**: Stops at first failing step, reports which step failed, and preserves completed earlier steps
+- **Graph mode**: Rejects malformed graphs before spawn; a failed wave prevents all downstream starts and preserves completed node evidence
 - **Duplicate prevention**: A cutoff with no new checkpoint or streamed evidence is not retried
 
 ## Limitations
@@ -195,6 +205,6 @@ Project agents override user agents with the same name when `agentScope: "both"`
 - Output truncated to last 10 items in collapsed view (expand to see all)
 - Parallel model-visible output is capped at 50 KB per task; full results remain in tool details
 - Agents discovered fresh on each invocation (allows editing mid-session)
-- Parallel mode limited to 8 tasks, 4 concurrent
+- Outside Ultra, parallel mode is limited to 8 tasks and 4 concurrent processes; Ultra has no extension-imposed count or concurrency cap and can consume substantial host/provider resources
 - Automatic semantic pre-sharding requires an explicit numbered/checklist action list; indivisible prose is checkpointed and resumed as one shard
 - Checkpoints are best-effort child artifacts plus runtime-captured stream evidence; workspace side effects remain the source of truth after a cutoff

package/examples/extensions/subagent/adaptive-agent-runtime.ts

@@ -73,8 +73,8 @@ export async function runAdaptiveAgent(options: RunAdaptiveAgentOptions): Promis
 	const startedAtMs = Date.now();
 	let identity = parseProviderModel(options.model);
 	let profile = await options.profileStore.profileFor(identity.provider, identity.model);
-	const initialCutoff = cutoffFor(profile, options, remainingExecutionMs(options.budget));
 	const demand = estimateTaskDemand(options.logicalTask);
+	const initialCutoff = cutoffFor(profile, options, remainingExecutionMs(options.budget), demand.predictedMs);
 	const shards = planTaskShards(options.logicalTask, demand, {
 		attemptCutoffMs: initialCutoff,
 		maxTaskShards: options.budget.maxTaskShards,
@@ -109,7 +109,7 @@ export async function runAdaptiveAgent(options: RunAdaptiveAgentOptions): Promis
 			let checkpoint: typeof lastCheckpoint;
 			while (true) {
 				const pendingShards = shards.length - completedShardIds.length;
-				const recommended = cutoffFor(profile, options, remainingExecutionMs(taskBudget));
+				const recommended = cutoffFor(profile, options, remainingExecutionMs(taskBudget), demand.predictedMs);
 				const allocation = allocateAttemptBudget({
 					budget: taskBudget,
 					pendingSequentialTasks: 1,
@@ -231,10 +231,16 @@ export async function runAdaptiveAgent(options: RunAdaptiveAgentOptions): Promis
 	return aggregate;
 }
 
-function cutoffFor(profile: DeadlineProfile | undefined, options: RunAdaptiveAgentOptions, maximumMs: number): number {
+function cutoffFor(
+	profile: DeadlineProfile | undefined,
+	options: RunAdaptiveAgentOptions,
+	maximumMs: number,
+	predictedMs: number,
+): number {
 	return recommendAttemptCutoff(profile, {
 		fallbackMs: options.policy.fallbackAttemptMs,
 		minimumMs: Math.min(options.policy.minimumAttemptMs, maximumMs),
 		maximumMs: Math.max(1, maximumMs),
+		predictedMs,
 	});
 }

package/examples/extensions/subagent/agents/planner.md

@@ -1,8 +1,6 @@
 ---
 name: planner
 description: Creates implementation plans from context and requirements
-tools: read, grep, find, ls
-model: claude-sonnet-4-5
 ---
 
 You are a planning specialist. You receive context (from a scout) and requirements, then produce a clear implementation plan.
@@ -10,7 +8,7 @@ You are a planning specialist. You receive context (from a scout) and requiremen
 You must NOT make any changes. Only read, analyze, and plan.
 
 Assigned capabilities (see ~/.omk/agent/SUBAGENTS.md for the full routing reference):
-- Skills: ulw-plan (explore-first planning, decision-complete plans), packages (if the codebase spans multiple packages), deep-interview (only if requirements are still fuzzy after reading the scout's context). Load only what the task needs; do not bulk-load the catalog.
+- Skills: ulw-plan, packages, deep-interview
 
 Input format you'll receive:
 - Context/findings from a scout agent

package/examples/extensions/subagent/agents/reviewer.md

@@ -1,8 +1,6 @@
 ---
 name: reviewer
 description: Code review specialist for quality and security analysis
-tools: read, grep, find, ls, bash
-model: claude-sonnet-4-5
 ---
 
 You are a senior code reviewer. Analyze code for quality, security, and maintainability.
@@ -11,7 +9,7 @@ Bash is for read-only commands only: `git diff`, `git log`, `git show`. Do NOT m
 Assume tool permissions are not perfectly enforceable; keep all bash usage strictly read-only.
 
 Assigned capabilities (see ~/.omk/agent/SUBAGENTS.md for the full routing reference):
-- Skills: review-work (structured multi-angle review pass), security-review (when the diff touches auth, secrets, or user input). Load only what the task needs.
+- Skills: review-work, security-review
 
 Strategy:
 1. Run `git diff` to see recent changes (if applicable)

package/examples/extensions/subagent/agents/scout.md

@@ -1,8 +1,6 @@
 ---
 name: scout
 description: Fast codebase recon that returns compressed context for handoff to other agents
-tools: read, grep, find, ls, bash
-model: claude-haiku-4-5
 ---
 
 You are a scout. Quickly investigate a codebase and return structured findings that another agent can use without re-reading everything.
@@ -10,7 +8,7 @@ You are a scout. Quickly investigate a codebase and return structured findings t
 Your output will be passed to an agent who has NOT seen the files you explored.
 
 Assigned capabilities (see ~/.omk/agent/SUBAGENTS.md for the full routing reference):
-- Skills: understand-anything (if a knowledge-graph/dependency question, not just a file lookup), ast-grep (structural search when grep-by-text isn't precise enough), headroom (if findings would otherwise be too large to hand off compactly). Load only what the task needs.
+- Skills: understand-anything, ast-grep, headroom
 
 Thoroughness (infer from task, default medium):
 - Quick: Targeted lookups, key files only

package/examples/extensions/subagent/agents/worker.md

@@ -1,7 +1,6 @@
 ---
 name: worker
 description: General-purpose subagent with full capabilities, isolated context
-model: claude-sonnet-4-5
 ---
 
 You are a worker agent with full capabilities. You operate in an isolated context window to handle delegated tasks without polluting the main conversation.

package/examples/extensions/subagent/agents.test.ts

@@ -84,3 +84,12 @@ describe("parseEnforceFlag coercion (via discoverAgents)", () => {
 		}
 	});
 });
+
+describe("bundled agent model delegation", () => {
+	it("omits model pins so bundled agents inherit the parent session model", () => {
+		for (const name of ["scout", "planner", "reviewer", "worker"]) {
+			const source = fs.readFileSync(path.join(import.meta.dirname, "agents", `${name}.md`), "utf8");
+			expect(source, `${name} must not pin a model`).not.toMatch(/^model:/m);
+		}
+	});
+});