openhorse 0.2.18 → 0.2.21

package/dist/runtime/subagents/index.js

@@ -0,0 +1,62 @@
+"use strict";
+/**
+ * Subagent runtime public surface.
+ *
+ * v0.2.20 exposes a read-only subagent runtime. The root Agent may request
+ * 1-3 independent investigation packets; a Supervisor runs them as isolated
+ * child agents under a unified budget, permission boundary and trace.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deriveRootLlmConfig = exports.createSubagentBundleForTurn = exports.createSubagentToolForTurn = exports.createChildLlmConfig = exports.createProductionExecuteQuery = exports.summarizeBatchForModel = exports.coerceSubtaskRequest = exports.createSubtaskTool = exports.runSubtaskBatch = exports.SubagentProviderGate = exports.runSubtask = exports.ScopeHolder = exports.evaluateToolCall = exports.createChildToolExecutorGuard = exports.extractJsonObject = exports.parseSubtaskResult = exports.buildChildMessages = exports.budgetLimitsFromConfig = exports.TurnTaskState = exports.SubagentBudgetLedger = exports.clampSubagentConfig = exports.hasExplicitDelegationIntent = exports.canonicalizeScopePaths = exports.evaluateSubtaskPolicy = void 0;
+__exportStar(require("./types"), exports);
+__exportStar(require("./presets"), exports);
+var policy_1 = require("./policy");
+Object.defineProperty(exports, "evaluateSubtaskPolicy", { enumerable: true, get: function () { return policy_1.evaluateSubtaskPolicy; } });
+Object.defineProperty(exports, "canonicalizeScopePaths", { enumerable: true, get: function () { return policy_1.canonicalizeScopePaths; } });
+Object.defineProperty(exports, "hasExplicitDelegationIntent", { enumerable: true, get: function () { return policy_1.hasExplicitDelegationIntent; } });
+Object.defineProperty(exports, "clampSubagentConfig", { enumerable: true, get: function () { return policy_1.clampSubagentConfig; } });
+var budget_1 = require("./budget");
+Object.defineProperty(exports, "SubagentBudgetLedger", { enumerable: true, get: function () { return budget_1.SubagentBudgetLedger; } });
+Object.defineProperty(exports, "TurnTaskState", { enumerable: true, get: function () { return budget_1.TurnTaskState; } });
+Object.defineProperty(exports, "budgetLimitsFromConfig", { enumerable: true, get: function () { return budget_1.budgetLimitsFromConfig; } });
+var context_builder_1 = require("./context-builder");
+Object.defineProperty(exports, "buildChildMessages", { enumerable: true, get: function () { return context_builder_1.buildChildMessages; } });
+var result_parser_1 = require("./result-parser");
+Object.defineProperty(exports, "parseSubtaskResult", { enumerable: true, get: function () { return result_parser_1.parseSubtaskResult; } });
+Object.defineProperty(exports, "extractJsonObject", { enumerable: true, get: function () { return result_parser_1.extractJsonObject; } });
+var child_executor_guard_1 = require("./child-executor-guard");
+Object.defineProperty(exports, "createChildToolExecutorGuard", { enumerable: true, get: function () { return child_executor_guard_1.createChildToolExecutorGuard; } });
+Object.defineProperty(exports, "evaluateToolCall", { enumerable: true, get: function () { return child_executor_guard_1.evaluateToolCall; } });
+Object.defineProperty(exports, "ScopeHolder", { enumerable: true, get: function () { return child_executor_guard_1.ScopeHolder; } });
+var runner_1 = require("./runner");
+Object.defineProperty(exports, "runSubtask", { enumerable: true, get: function () { return runner_1.runSubtask; } });
+var provider_gate_1 = require("./provider-gate");
+Object.defineProperty(exports, "SubagentProviderGate", { enumerable: true, get: function () { return provider_gate_1.SubagentProviderGate; } });
+var supervisor_1 = require("./supervisor");
+Object.defineProperty(exports, "runSubtaskBatch", { enumerable: true, get: function () { return supervisor_1.runSubtaskBatch; } });
+var tool_1 = require("./tool");
+Object.defineProperty(exports, "createSubtaskTool", { enumerable: true, get: function () { return tool_1.createSubtaskTool; } });
+Object.defineProperty(exports, "coerceSubtaskRequest", { enumerable: true, get: function () { return tool_1.coerceSubtaskRequest; } });
+Object.defineProperty(exports, "summarizeBatchForModel", { enumerable: true, get: function () { return tool_1.summarizeBatchForModel; } });
+var production_1 = require("./production");
+Object.defineProperty(exports, "createProductionExecuteQuery", { enumerable: true, get: function () { return production_1.createProductionExecuteQuery; } });
+Object.defineProperty(exports, "createChildLlmConfig", { enumerable: true, get: function () { return production_1.createChildLlmConfig; } });
+var runtime_integration_1 = require("./runtime-integration");
+Object.defineProperty(exports, "createSubagentToolForTurn", { enumerable: true, get: function () { return runtime_integration_1.createSubagentToolForTurn; } });
+Object.defineProperty(exports, "createSubagentBundleForTurn", { enumerable: true, get: function () { return runtime_integration_1.createSubagentBundleForTurn; } });
+Object.defineProperty(exports, "deriveRootLlmConfig", { enumerable: true, get: function () { return runtime_integration_1.deriveRootLlmConfig; } });
+//# sourceMappingURL=index.js.map

package/dist/runtime/subagents/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/runtime/subagents/index.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;;;;;;;;;;;;;;;;AAEH,0CAAwB;AACxB,4CAA0B;AAC1B,mCAQkB;AAPhB,+GAAA,qBAAqB,OAAA;AACrB,gHAAA,sBAAsB,OAAA;AACtB,qHAAA,2BAA2B,OAAA;AAC3B,6GAAA,mBAAmB,OAAA;AAKrB,mCAQkB;AAPhB,8GAAA,oBAAoB,OAAA;AACpB,uGAAA,aAAa,OAAA;AACb,gHAAA,sBAAsB,OAAA;AAMxB,qDAAgF;AAAvE,qHAAA,kBAAkB,OAAA;AAC3B,iDAAmG;AAA1F,mHAAA,kBAAkB,OAAA;AAAE,kHAAA,iBAAiB,OAAA;AAC9C,+DAMgC;AAL9B,oIAAA,4BAA4B,OAAA;AAC5B,wHAAA,gBAAgB,OAAA;AAChB,mHAAA,WAAW,OAAA;AAIb,mCAMkB;AALhB,oGAAA,UAAU,OAAA;AAMZ,iDAGyB;AAFvB,qHAAA,oBAAoB,OAAA;AAGtB,2CAIsB;AAHpB,6GAAA,eAAe,OAAA;AAIjB,+BAIgB;AAHd,yGAAA,iBAAiB,OAAA;AACjB,4GAAA,oBAAoB,OAAA;AACpB,8GAAA,sBAAsB,OAAA;AAExB,2CAIsB;AAHpB,0HAAA,4BAA4B,OAAA;AAC5B,kHAAA,oBAAoB,OAAA;AAGtB,6DAM+B;AAL7B,gIAAA,yBAAyB,OAAA;AACzB,kIAAA,2BAA2B,OAAA;AAC3B,0HAAA,mBAAmB,OAAA"}

package/dist/runtime/subagents/policy.d.ts

@@ -0,0 +1,68 @@
+/**
+ * SubagentPolicy: deterministic approval gate for `subtask` requests.
+ *
+ * The root Agent proposes work packages; the runtime decides whether they may
+ * run. Every allow/reject decision is recorded with a reason and a budget
+ * snapshot, so the policy is auditable rather than hidden in a classifier.
+ *
+ * Scope canonicalization lives here too: child paths must stay inside the
+ * project root. `../`, absolute escapes and symlink escapes are rejected.
+ */
+import type { SubagentConfig, SubtaskRequest } from './types';
+export type PolicyVerdict = {
+    allowed: true;
+    canonicalScope: Map<number, string[]>;
+} | {
+    allowed: false;
+    reason: PolicyRejectReason;
+    detail?: string;
+};
+export type PolicyRejectReason = 'mode_off' | 'not_root_depth' | 'explicit_intent_missing' | 'too_many_tasks' | 'role_disabled' | 'objective_unbounded' | 'duplicate_scope' | 'scope_escape' | 'pending_permission' | 'parent_aborted' | 'budget_exhausted' | 'provider_unavailable' | 'concurrency_limit' | 'empty_request' | 'not_eligible_for_delegation';
+export interface PolicyContext {
+    /** Current delegation depth. Only depth 0 (root) may delegate. */
+    depth: number;
+    /** Canonical project root the children operate in. */
+    cwd: string;
+    /** Active config. */
+    config: SubagentConfig;
+    /** Root objective text, used to detect explicit delegation intent. */
+    rootObjective: string;
+    /** Subtasks already started in this root turn. */
+    tasksStartedThisTurn: number;
+    /** Children currently running. */
+    runningChildren: number;
+    /** A permission request is awaiting user decision. */
+    hasPendingPermission: boolean;
+    /** Parent turn abort signal has fired. */
+    parentAborted: boolean;
+    /** Remaining aggregate model-request budget for the turn. */
+    remainingModelRequests: number;
+    /** Provider gate can reserve a slot for every task in the batch. */
+    providerCanReserve: (count: number) => boolean;
+}
+/**
+ * Canonicalize a list of scope paths against the project root.
+ *
+ * Returns the canonical relative paths for paths that stay inside the root,
+ * or `null` if any path escapes (via `..`, absolute outside root, or symlink).
+ * Symlink defense only applies to paths that exist on disk: a non-existent
+ * path cannot be a symlink escape, and skipping it avoids root/child realpath
+ * basis mismatches (e.g. macOS `/tmp` -> `/private/tmp`).
+ */
+export declare function canonicalizeScopePaths(rootCwd: string, paths: readonly string[] | undefined): {
+    ok: true;
+    paths: string[];
+} | {
+    ok: false;
+    reason: 'scope_escape';
+    path: string;
+};
+export declare function hasExplicitDelegationIntent(rootObjective: string): boolean;
+/**
+ * Evaluate a `subtask` request against the policy. This is the single
+ * deterministic gate every request must pass before any child is queued.
+ */
+export declare function evaluateSubtaskPolicy(request: SubtaskRequest, ctx: PolicyContext): PolicyVerdict;
+/** Clamp a user-provided config value to the enforced bounds. */
+export declare function clampSubagentConfig(config: SubagentConfig): SubagentConfig;
+//# sourceMappingURL=policy.d.ts.map

package/dist/runtime/subagents/policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../../../src/runtime/subagents/policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EACV,cAAc,EAId,cAAc,EACf,MAAM,SAAS,CAAC;AAGjB,MAAM,MAAM,aAAa,GACrB;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,cAAc,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAA;CAAE,GACxD;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,kBAAkB,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpE,MAAM,MAAM,kBAAkB,GAC1B,UAAU,GACV,gBAAgB,GAChB,yBAAyB,GACzB,gBAAgB,GAChB,eAAe,GACf,qBAAqB,GACrB,iBAAiB,GACjB,cAAc,GACd,oBAAoB,GACpB,gBAAgB,GAChB,kBAAkB,GAClB,sBAAsB,GACtB,mBAAmB,GACnB,eAAe,GACf,6BAA6B,CAAC;AAElC,MAAM,WAAW,aAAa;IAC5B,kEAAkE;IAClE,KAAK,EAAE,MAAM,CAAC;IACd,sDAAsD;IACtD,GAAG,EAAE,MAAM,CAAC;IACZ,qBAAqB;IACrB,MAAM,EAAE,cAAc,CAAC;IACvB,sEAAsE;IACtE,aAAa,EAAE,MAAM,CAAC;IACtB,kDAAkD;IAClD,oBAAoB,EAAE,MAAM,CAAC;IAC7B,kCAAkC;IAClC,eAAe,EAAE,MAAM,CAAC;IACxB,sDAAsD;IACtD,oBAAoB,EAAE,OAAO,CAAC;IAC9B,0CAA0C;IAC1C,aAAa,EAAE,OAAO,CAAC;IACvB,6DAA6D;IAC7D,sBAAsB,EAAE,MAAM,CAAC;IAC/B,oEAAoE;IACpE,kBAAkB,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC;CAChD;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,GACnC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,cAAc,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAwBrF;AAmBD,wBAAgB,2BAA2B,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAE1E;AAcD;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,cAAc,EACvB,GAAG,EAAE,aAAa,GACjB,aAAa,CAuEf;AAMD,iEAAiE;AACjE,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,cAAc,GAAG,cAAc,CAmB1E"}

package/dist/runtime/subagents/policy.js

@@ -0,0 +1,230 @@
+"use strict";
+/**
+ * SubagentPolicy: deterministic approval gate for `subtask` requests.
+ *
+ * The root Agent proposes work packages; the runtime decides whether they may
+ * run. Every allow/reject decision is recorded with a reason and a budget
+ * snapshot, so the policy is auditable rather than hidden in a classifier.
+ *
+ * Scope canonicalization lives here too: child paths must stay inside the
+ * project root. `../`, absolute escapes and symlink escapes are rejected.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.canonicalizeScopePaths = canonicalizeScopePaths;
+exports.hasExplicitDelegationIntent = hasExplicitDelegationIntent;
+exports.evaluateSubtaskPolicy = evaluateSubtaskPolicy;
+exports.clampSubagentConfig = clampSubagentConfig;
+const path_1 = require("path");
+const fs_1 = require("fs");
+const types_1 = require("./types");
+/**
+ * Canonicalize a list of scope paths against the project root.
+ *
+ * Returns the canonical relative paths for paths that stay inside the root,
+ * or `null` if any path escapes (via `..`, absolute outside root, or symlink).
+ * Symlink defense only applies to paths that exist on disk: a non-existent
+ * path cannot be a symlink escape, and skipping it avoids root/child realpath
+ * basis mismatches (e.g. macOS `/tmp` -> `/private/tmp`).
+ */
+function canonicalizeScopePaths(rootCwd, paths) {
+    if (!paths || paths.length === 0)
+        return { ok: true, paths: [] };
+    const realRoot = realpathSafe(rootCwd);
+    const canonical = [];
+    for (const raw of paths) {
+        if (typeof raw !== 'string' || raw.trim() === '') {
+            return { ok: false, reason: 'scope_escape', path: String(raw) };
+        }
+        const resolved = (0, path_1.resolve)(rootCwd, raw);
+        const rel = (0, path_1.relative)(rootCwd, resolved);
+        if (rel.startsWith('..') || (0, path_1.isAbsolute)(rel)) {
+            return { ok: false, reason: 'scope_escape', path: raw };
+        }
+        if ((0, fs_1.existsSync)(resolved)) {
+            const realResolved = realpathSafe(resolved);
+            const realRel = (0, path_1.relative)(realRoot, realResolved);
+            if (realRel.startsWith('..') || (0, path_1.isAbsolute)(realRel)) {
+                return { ok: false, reason: 'scope_escape', path: raw };
+            }
+        }
+        canonical.push((0, path_1.normalize)(rel));
+    }
+    return { ok: true, paths: canonical };
+}
+function realpathSafe(p) {
+    try {
+        return (0, fs_1.realpathSync)(p);
+    }
+    catch {
+        return p;
+    }
+}
+const DELEGATION_INTENT_PATTERNS = [
+    /\b(parallel|concurrent|separately|independent)\b/i,
+    /\b(research|review|investigate|audit)\b/i,
+    /\bsub-?agent\b/i,
+    /\bsubtask\b/i,
+    // CJK patterns: \b word-boundary does not match CJK, so no anchors here.
+    /(多个|并行|分别|独立|调研|审查|调查)/,
+];
+function hasExplicitDelegationIntent(rootObjective) {
+    return DELEGATION_INTENT_PATTERNS.some(re => re.test(rootObjective));
+}
+const UNBOUNDED_OBJECTIVE_PATTERNS = [
+    /^(处理一下|继续看看|看一下|随便|帮个忙)/,
+    /^\s*(todo|tbd|fixme)\s*$/i,
+];
+function isObjectiveBounded(objective) {
+    const trimmed = objective.trim();
+    if (trimmed.length < 4)
+        return false;
+    if (UNBOUNDED_OBJECTIVE_PATTERNS.some(re => re.test(trimmed)))
+        return false;
+    return true;
+}
+/**
+ * Evaluate a `subtask` request against the policy. This is the single
+ * deterministic gate every request must pass before any child is queued.
+ */
+function evaluateSubtaskPolicy(request, ctx) {
+    if (ctx.parentAborted)
+        return reject('parent_aborted');
+    if (ctx.hasPendingPermission)
+        return reject('pending_permission');
+    if (ctx.depth !== 0)
+        return reject('not_root_depth');
+    if (ctx.config.mode === 'off')
+        return reject('mode_off');
+    const tasks = request.tasks;
+    if (!Array.isArray(tasks) || tasks.length === 0)
+        return reject('empty_request');
+    if (tasks.length > ctx.config.maxTasksPerTurn) {
+        return reject('too_many_tasks', `${tasks.length} > ${ctx.config.maxTasksPerTurn}`);
+    }
+    if (ctx.config.mode === 'explicit' && !hasExplicitDelegationIntent(ctx.rootObjective)) {
+        return reject('explicit_intent_missing');
+    }
+    // R9: for `auto` mode, require at least two independent investigation
+    // directions in the root objective OR a review + test-investigate
+    // combination. A single-file read or simple Q&A cannot accidentally
+    // delegate. `explicit` mode ensures explicit intent manually; this gate
+    // only applies when the model proposes delegation unbidden.
+    if (ctx.config.mode === 'auto' && tasks.length === 1) {
+        if (!meetsAutoEligibility(ctx.rootObjective, tasks)) {
+            return reject('not_eligible_for_delegation', 'auto mode requires at least 2 independent investigation directions or a review+test-investigate combination');
+        }
+    }
+    const totalTasks = ctx.tasksStartedThisTurn + tasks.length;
+    if (totalTasks > ctx.config.maxTasksPerTurn) {
+        return reject('too_many_tasks', `turn total ${totalTasks} > ${ctx.config.maxTasksPerTurn}`);
+    }
+    // Concurrency: a parallel batch must fit within maxParallel alongside running children.
+    if (request.execution === 'parallel') {
+        if (ctx.runningChildren > 0 && ctx.runningChildren + tasks.length > ctx.config.maxParallel) {
+            return reject('concurrency_limit', `${ctx.runningChildren}+${tasks.length} > ${ctx.config.maxParallel}`);
+        }
+    }
+    if (ctx.remainingModelRequests < tasks.length) {
+        return reject('budget_exhausted', `need >=${tasks.length} requests, have ${ctx.remainingModelRequests}`);
+    }
+    if (!ctx.providerCanReserve(tasks.length)) {
+        return reject('provider_unavailable');
+    }
+    const canonicalScope = new Map();
+    const seenScopes = new Set();
+    for (let i = 0; i < tasks.length; i++) {
+        const packet = tasks[i];
+        if (!ctx.config.roles.includes(packet.role)) {
+            return reject('role_disabled', packet.role);
+        }
+        if (!isObjectiveBounded(packet.objective)) {
+            return reject('objective_unbounded', packet.objective.slice(0, 40));
+        }
+        const scope = canonicalizeScopePaths(ctx.cwd, packet.scope?.paths);
+        if (!scope.ok) {
+            return reject('scope_escape', scope.path);
+        }
+        const scopeKey = scope.paths.join(',');
+        if (scopeKey && seenScopes.has(scopeKey)) {
+            return reject('duplicate_scope', scopeKey);
+        }
+        if (scopeKey)
+            seenScopes.add(scopeKey);
+        canonicalScope.set(i, scope.paths);
+    }
+    return { allowed: true, canonicalScope };
+}
+function reject(reason, detail) {
+    return { allowed: false, reason, detail };
+}
+/** Clamp a user-provided config value to the enforced bounds. */
+function clampSubagentConfig(config) {
+    const clamp = (value, bounds) => Math.max(bounds.min, Math.min(bounds.max, Math.floor(value) || bounds.min));
+    const roles = Array.from(new Set(config.roles)).filter(r => ['research', 'review', 'test-investigate'].includes(r));
+    const clampedRoles = roles.length > 0 ? roles : DEFAULT_ROLES;
+    const mode = ['off', 'explicit', 'auto'].includes(config.mode) ? config.mode : 'auto';
+    return {
+        mode,
+        maxParallel: clamp(config.maxParallel, types_1.SUBAGENT_LIMITS.maxParallel),
+        maxTasksPerTurn: clamp(config.maxTasksPerTurn, types_1.SUBAGENT_LIMITS.maxTasksPerTurn),
+        maxTurnsPerTask: clamp(config.maxTurnsPerTask, types_1.SUBAGENT_LIMITS.maxTurnsPerTask),
+        maxModelRequestsPerTask: clamp(config.maxModelRequestsPerTask, types_1.SUBAGENT_LIMITS.maxModelRequestsPerTask),
+        maxModelRequestsPerTurn: clamp(config.maxModelRequestsPerTurn, types_1.SUBAGENT_LIMITS.maxModelRequestsPerTurn),
+        maxToolCallsPerTask: clamp(config.maxToolCallsPerTask, types_1.SUBAGENT_LIMITS.maxToolCallsPerTask),
+        timeoutMs: clamp(config.timeoutMs, types_1.SUBAGENT_LIMITS.timeoutMs),
+        roles: clampedRoles,
+    };
+}
+const DEFAULT_ROLES = ['research', 'review', 'test-investigate'];
+/**
+ * R9: determine whether a single-task `auto` delegation is eligible.
+ *
+ * A single-packet delegation is only allowed when the root objective shows
+ * two or more independent investigation directions (so the model could have
+ * proposed multiple tasks but chose one) OR when the packet requests a review
+ * or test-investigation with a well-scoped objective. Simple Q&A, single-file
+ * reads, or vague "look at" prompts are never eligible.
+ *
+ * The check is conservative and explainable. `explicit` mode bypasses this
+ * gate entirely (the user said "delegate").
+ *
+ * @returns true if the task meets the minimum eligibility bar.
+ */
+function meetsAutoEligibility(rootObjective, tasks) {
+    if (tasks.length >= 2)
+        return true;
+    const task = tasks[0];
+    const role = task.role;
+    const objective = task.objective;
+    // review and test-investigate are inherently multi-faceted: they imply a
+    // diff/changeset and test coverage analysis respectively. A single review
+    // or test-investigate task is eligible when the objective is concrete.
+    if (role === 'review' || role === 'test-investigate') {
+        return objective.trim().length >= 10;
+    }
+    // research: require multiple independent investigation signals in either
+    // the root objective or the task's scope/packet details.
+    const hasMultiDirectionInRoot = hasMultipleInvestigationDirections(rootObjective);
+    if (hasMultiDirectionInRoot)
+        return true;
+    // The packet must show at least two independent aspects.
+    const scopeCount = task.scope?.paths?.length ?? 0;
+    const hintCount = task.contextHints?.length ?? 0;
+    return scopeCount >= 2 || hintCount >= 2;
+}
+/** True if the objective text suggests at least two independent work items. */
+function hasMultipleInvestigationDirections(objective) {
+    const lower = objective.toLowerCase();
+    // Conjunctions that signal multiple independent directions.
+    const multiMarkers = [
+        / and /, /, and /, / or /,
+        / both /, / each /,
+        / parallel/, /separately/, /independently/,
+        / respectively/,
+        // CJK: multiple items or separation
+        /(和|与|以及|分别|并行|独立|同时)/,
+        /(两个|多个|若干|各个|分别)/,
+    ];
+    return multiMarkers.some(re => re.test(lower));
+}
+//# sourceMappingURL=policy.js.map

package/dist/runtime/subagents/policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.js","sourceRoot":"","sources":["../../../src/runtime/subagents/policy.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG;;AAkEH,wDA2BC;AAmBD,kEAEC;AAkBD,sDA0EC;AAOD,kDAmBC;AAtOD,+BAAgE;AAChE,2BAA8C;AAQ9C,mCAA0C;AA8C1C;;;;;;;;GAQG;AACH,SAAgB,sBAAsB,CACpC,OAAe,EACf,KAAoC;IAEpC,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;IAEjE,MAAM,QAAQ,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;IACvC,MAAM,SAAS,GAAa,EAAE,CAAC;IAC/B,KAAK,MAAM,GAAG,IAAI,KAAK,EAAE,CAAC;QACxB,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;YACjD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;QAClE,CAAC;QACD,MAAM,QAAQ,GAAG,IAAA,cAAO,EAAC,OAAO,EAAE,GAAG,CAAC,CAAC;QACvC,MAAM,GAAG,GAAG,IAAA,eAAQ,EAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QACxC,IAAI,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,IAAA,iBAAU,EAAC,GAAG,CAAC,EAAE,CAAC;YAC5C,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC;QAC1D,CAAC;QACD,IAAI,IAAA,eAAU,EAAC,QAAQ,CAAC,EAAE,CAAC;YACzB,MAAM,YAAY,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAC;YAC5C,MAAM,OAAO,GAAG,IAAA,eAAQ,EAAC,QAAQ,EAAE,YAAY,CAAC,CAAC;YACjD,IAAI,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,IAAA,iBAAU,EAAC,OAAO,CAAC,EAAE,CAAC;gBACpD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC;YAC1D,CAAC;QACH,CAAC;QACD,SAAS,CAAC,IAAI,CAAC,IAAA,gBAAS,EAAC,GAAG,CAAC,CAAC,CAAC;IACjC,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;AACxC,CAAC;AAED,SAAS,YAAY,CAAC,CAAS;IAC7B,IAAI,CAAC;QACH,OAAO,IAAA,iBAAY,EAAC,CAAC,CAAC,CAAC;IACzB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,CAAC,CAAC;IACX,CAAC;AACH,CAAC;AAED,MAAM,0BAA0B,GAAG;IACjC,mDAAmD;IACnD,0CAA0C;IAC1C,iBAAiB;IACjB,cAAc;IACd,yEAAyE;IACzE,wBAAwB;CACzB,CAAC;AAEF,SAAgB,2BAA2B,CAAC,aAAqB;IAC/D,OAAO,0BAA0B,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC;AACvE,CAAC;AAED,MAAM,4BAA4B,GAAG;IACnC,yBAAyB;IACzB,2BAA2B;CAC5B,CAAC;AAEF,SAAS,kBAAkB,CAAC,SAAiB;IAC3C,MAAM,OAAO,GAAG,SAAS,CAAC,IAAI,EAAE,CAAC;IACjC,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC;IACrC,IAAI,4BAA4B,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC;IAC5E,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;GAGG;AACH,SAAgB,qBAAqB,CACnC,OAAuB,EACvB,GAAkB;IAElB,IAAI,GAAG,CAAC,aAAa;QAAE,OAAO,MAAM,CAAC,gBAAgB,CAAC,CAAC;IACvD,IAAI,GAAG,CAAC,oBAAoB;QAAE,OAAO,MAAM,CAAC,oBAAoB,CAAC,CAAC;IAClE,IAAI,GAAG,CAAC,KAAK,KAAK,CAAC;QAAE,OAAO,MAAM,CAAC,gBAAgB,CAAC,CAAC;IACrD,IAAI,GAAG,CAAC,MAAM,CAAC,IAAI,KAAK,KAAK;QAAE,OAAO,MAAM,CAAC,UAAU,CAAC,CAAC;IAEzD,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;IAC5B,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,MAAM,CAAC,eAAe,CAAC,CAAC;IAChF,IAAI,KAAK,CAAC,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,eAAe,EAAE,CAAC;QAC9C,OAAO,MAAM,CAAC,gBAAgB,EAAE,GAAG,KAAK,CAAC,MAAM,MAAM,GAAG,CAAC,MAAM,CAAC,eAAe,EAAE,CAAC,CAAC;IACrF,CAAC;IAED,IAAI,GAAG,CAAC,MAAM,CAAC,IAAI,KAAK,UAAU,IAAI,CAAC,2BAA2B,CAAC,GAAG,CAAC,aAAa,CAAC,EAAE,CAAC;QACtF,OAAO,MAAM,CAAC,yBAAyB,CAAC,CAAC;IAC3C,CAAC;IAED,sEAAsE;IACtE,kEAAkE;IAClE,oEAAoE;IACpE,wEAAwE;IACxE,4DAA4D;IAC5D,IAAI,GAAG,CAAC,MAAM,CAAC,IAAI,KAAK,MAAM,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACrD,IAAI,CAAC,oBAAoB,CAAC,GAAG,CAAC,aAAa,EAAE,KAAK,CAAC,EAAE,CAAC;YACpD,OAAO,MAAM,CAAC,6BAA6B,EACzC,6GAA6G,CAAC,CAAC;QACnH,CAAC;IACH,CAAC;IAED,MAAM,UAAU,GAAG,GAAG,CAAC,oBAAoB,GAAG,KAAK,CAAC,MAAM,CAAC;IAC3D,IAAI,UAAU,GAAG,GAAG,CAAC,MAAM,CAAC,eAAe,EAAE,CAAC;QAC5C,OAAO,MAAM,CAAC,gBAAgB,EAAE,cAAc,UAAU,MAAM,GAAG,CAAC,MAAM,CAAC,eAAe,EAAE,CAAC,CAAC;IAC9F,CAAC;IAED,wFAAwF;IACxF,IAAI,OAAO,CAAC,SAAS,KAAK,UAAU,EAAE,CAAC;QACrC,IAAI,GAAG,CAAC,eAAe,GAAG,CAAC,IAAI,GAAG,CAAC,eAAe,GAAG,KAAK,CAAC,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC;YAC3F,OAAO,MAAM,CAAC,mBAAmB,EAAE,GAAG,GAAG,CAAC,eAAe,IAAI,KAAK,CAAC,MAAM,MAAM,GAAG,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC,CAAC;QAC3G,CAAC;IACH,CAAC;IAED,IAAI,GAAG,CAAC,sBAAsB,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC;QAC9C,OAAO,MAAM,CAAC,kBAAkB,EAAE,UAAU,KAAK,CAAC,MAAM,mBAAmB,GAAG,CAAC,sBAAsB,EAAE,CAAC,CAAC;IAC3G,CAAC;IAED,IAAI,CAAC,GAAG,CAAC,kBAAkB,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC;QAC1C,OAAO,MAAM,CAAC,sBAAsB,CAAC,CAAC;IACxC,CAAC;IAED,MAAM,cAAc,GAAG,IAAI,GAAG,EAAoB,CAAC;IACnD,MAAM,UAAU,GAAG,IAAI,GAAG,EAAU,CAAC;IACrC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QACxB,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;YAC5C,OAAO,MAAM,CAAC,eAAe,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;QAC9C,CAAC;QACD,IAAI,CAAC,kBAAkB,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC;YAC1C,OAAO,MAAM,CAAC,qBAAqB,EAAE,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;QACtE,CAAC;QACD,MAAM,KAAK,GAAG,sBAAsB,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;QACnE,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC;YACd,OAAO,MAAM,CAAC,cAAc,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;QAC5C,CAAC;QACD,MAAM,QAAQ,GAAG,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACvC,IAAI,QAAQ,IAAI,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;YACzC,OAAO,MAAM,CAAC,iBAAiB,EAAE,QAAQ,CAAC,CAAC;QAC7C,CAAC;QACD,IAAI,QAAQ;YAAE,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACvC,cAAc,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;IACrC,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,cAAc,EAAE,CAAC;AAC3C,CAAC;AAED,SAAS,MAAM,CAAC,MAA0B,EAAE,MAAe;IACzD,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;AAC5C,CAAC;AAED,iEAAiE;AACjE,SAAgB,mBAAmB,CAAC,MAAsB;IACxD,MAAM,KAAK,GAAG,CAAC,KAAa,EAAE,MAAoC,EAAE,EAAE,CACpE,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IAC9E,MAAM,KAAK,GAAmB,KAAK,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CACxE,CAAC,UAAU,EAAE,QAAQ,EAAE,kBAAkB,CAAoB,CAAC,QAAQ,CAAC,CAAC,CAAC,CACzD,CAAC;IACpB,MAAM,YAAY,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,aAAa,CAAC;IAC9D,MAAM,IAAI,GAAiB,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC;IACpG,OAAO;QACL,IAAI;QACJ,WAAW,EAAE,KAAK,CAAC,MAAM,CAAC,WAAW,EAAE,uBAAe,CAAC,WAAW,CAAC;QACnE,eAAe,EAAE,KAAK,CAAC,MAAM,CAAC,eAAe,EAAE,uBAAe,CAAC,eAAe,CAAC;QAC/E,eAAe,EAAE,KAAK,CAAC,MAAM,CAAC,eAAe,EAAE,uBAAe,CAAC,eAAe,CAAC;QAC/E,uBAAuB,EAAE,KAAK,CAAC,MAAM,CAAC,uBAAuB,EAAE,uBAAe,CAAC,uBAAuB,CAAC;QACvG,uBAAuB,EAAE,KAAK,CAAC,MAAM,CAAC,uBAAuB,EAAE,uBAAe,CAAC,uBAAuB,CAAC;QACvG,mBAAmB,EAAE,KAAK,CAAC,MAAM,CAAC,mBAAmB,EAAE,uBAAe,CAAC,mBAAmB,CAAC;QAC3F,SAAS,EAAE,KAAK,CAAC,MAAM,CAAC,SAAS,EAAE,uBAAe,CAAC,SAAS,CAAC;QAC7D,KAAK,EAAE,YAAY;KACpB,CAAC;AACJ,CAAC;AAED,MAAM,aAAa,GAAmB,CAAC,UAAU,EAAE,QAAQ,EAAE,kBAAkB,CAAC,CAAC;AAEjF;;;;;;;;;;;;;GAaG;AACH,SAAS,oBAAoB,CAC3B,aAAqB,EACrB,KAAsB;IAEtB,IAAI,KAAK,CAAC,MAAM,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAEnC,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IACtB,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;IACvB,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;IAEjC,yEAAyE;IACzE,0EAA0E;IAC1E,uEAAuE;IACvE,IAAI,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,kBAAkB,EAAE,CAAC;QACrD,OAAO,SAAS,CAAC,IAAI,EAAE,CAAC,MAAM,IAAI,EAAE,CAAC;IACvC,CAAC;IAED,yEAAyE;IACzE,yDAAyD;IACzD,MAAM,uBAAuB,GAAG,kCAAkC,CAAC,aAAa,CAAC,CAAC;IAClF,IAAI,uBAAuB;QAAE,OAAO,IAAI,CAAC;IAEzC,yDAAyD;IACzD,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,IAAI,CAAC,CAAC;IAClD,MAAM,SAAS,GAAG,IAAI,CAAC,YAAY,EAAE,MAAM,IAAI,CAAC,CAAC;IAEjD,OAAO,UAAU,IAAI,CAAC,IAAI,SAAS,IAAI,CAAC,CAAC;AAC3C,CAAC;AAED,+EAA+E;AAC/E,SAAS,kCAAkC,CAAC,SAAiB;IAC3D,MAAM,KAAK,GAAG,SAAS,CAAC,WAAW,EAAE,CAAC;IACtC,4DAA4D;IAC5D,MAAM,YAAY,GAAG;QACnB,OAAO,EAAE,QAAQ,EAAE,MAAM;QACzB,QAAQ,EAAE,QAAQ;QAClB,WAAW,EAAE,YAAY,EAAE,eAAe;QAC1C,eAAe;QACf,oCAAoC;QACpC,sBAAsB;QACtB,kBAAkB;KACnB,CAAC;IACF,OAAO,YAAY,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;AACjD,CAAC"}

package/dist/runtime/subagents/presets.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Built-in subagent role presets: system prompts and tool allowlists.
+ *
+ * v0.2.20 ships read-only investigation roles. Every role's allowlist is the
+ * intersection of (read-only tools) and (role-appropriate tools). No role
+ * receives exec_command, write/edit, memory mutation, or the recursive
+ * `subtask` capability - this is enforced structurally, not by prompt alone.
+ */
+import type { SubagentRole } from './types';
+import type { OpenHorseTool } from '../../framework/tool';
+/** Read-only investigation tools available to children in v0.2.20. */
+export declare const READ_ONLY_INVESTIGATION_TOOLS: readonly ["read_file", "list_files", "glob", "grep", "batch_read"];
+/**
+ * Tools a child must NEVER receive. Kept as an explicit deny-set so the
+ * supervisor can assert that a filtered tool list contains none of these,
+ * even if future tools are added upstream.
+ */
+export declare const SUBAGENT_FORBIDDEN_TOOLS: readonly ["exec_command", "edit_file", "write_file", "memory_save", "memory_recall", "memory_forget", "openhorse", "subtask", "mcp_call", "mcp_list", "history_search"];
+export interface RolePreset {
+    role: SubagentRole;
+    /** Tool names the child may use. */
+    tools: readonly string[];
+    /** System prompt enforcing the role's contract and JSON output schema. */
+    systemPrompt: string;
+}
+export declare const ROLE_PRESETS: Record<SubagentRole, RolePreset>;
+/** Resolve the tool allowlist for a role. Falls back to the read-only set. */
+export declare function toolsForRole(role: SubagentRole): readonly string[];
+/** Resolve the system prompt for a role. */
+export declare function systemPromptForRole(role: SubagentRole): string;
+/**
+ * Filter an upstream tool list to a role's allowlist, removing any forbidden
+ * tool and the recursive `subtask` capability. Also includes first-class MCP
+ * tools (mcp__<server>__<tool>) that declare `readOnlyHint === true` via
+ * their `isReadOnly()` method — these are safe for children because they
+ * cannot invoke arbitrary MCP actions.
+ *
+ * Returns the names the child may receive; the caller is responsible for
+ * resolving them to tool definitions.
+ */
+export declare function filterToolsForRole(availableToolNames: readonly string[], role: SubagentRole, runtimeTools?: readonly OpenHorseTool[]): string[];
+/** Assert a filtered tool list contains no forbidden tool. Used by the runner. */
+export declare function assertNoForbiddenTools(toolNames: readonly string[]): void;
+//# sourceMappingURL=presets.d.ts.map

package/dist/runtime/subagents/presets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"presets.d.ts","sourceRoot":"","sources":["../../../src/runtime/subagents/presets.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAE1D,sEAAsE;AACtE,eAAO,MAAM,6BAA6B,oEAYhC,CAAC;AAEX;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,yKAgB3B,CAAC;AAEX,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,YAAY,CAAC;IACnB,oCAAoC;IACpC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,0EAA0E;IAC1E,YAAY,EAAE,MAAM,CAAC;CACtB;AAqBD,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,YAAY,EAAE,UAAU,CAwBzD,CAAC;AAEF,8EAA8E;AAC9E,wBAAgB,YAAY,CAAC,IAAI,EAAE,YAAY,GAAG,SAAS,MAAM,EAAE,CAElE;AAED,4CAA4C;AAC5C,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,CAE9D;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,kBAAkB,EAAE,SAAS,MAAM,EAAE,EACrC,IAAI,EAAE,YAAY,EAClB,YAAY,CAAC,EAAE,SAAS,aAAa,EAAE,GACtC,MAAM,EAAE,CA4BV;AAED,kFAAkF;AAClF,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAMzE"}

package/dist/runtime/subagents/presets.js

@@ -0,0 +1,148 @@
+"use strict";
+/**
+ * Built-in subagent role presets: system prompts and tool allowlists.
+ *
+ * v0.2.20 ships read-only investigation roles. Every role's allowlist is the
+ * intersection of (read-only tools) and (role-appropriate tools). No role
+ * receives exec_command, write/edit, memory mutation, or the recursive
+ * `subtask` capability - this is enforced structurally, not by prompt alone.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ROLE_PRESETS = exports.SUBAGENT_FORBIDDEN_TOOLS = exports.READ_ONLY_INVESTIGATION_TOOLS = void 0;
+exports.toolsForRole = toolsForRole;
+exports.systemPromptForRole = systemPromptForRole;
+exports.filterToolsForRole = filterToolsForRole;
+exports.assertNoForbiddenTools = assertNoForbiddenTools;
+/** Read-only investigation tools available to children in v0.2.20. */
+exports.READ_ONLY_INVESTIGATION_TOOLS = [
+    'read_file',
+    'list_files',
+    'glob',
+    'grep',
+    'batch_read',
+    // NOTE: mcp_call and mcp_list are intentionally EXCLUDED from the child
+    // allowlist. mcp_call is a generic escape hatch that can invoke any MCP
+    // action (including mutating ones) without going through the root's
+    // permission flow. mcp_list leaks server topology. Instead, first-class
+    // MCP tools (mcp__<server>__<tool>) with readOnlyHint === true are
+    // dynamically included by filterToolsForRole at runtime.
+];
+/**
+ * Tools a child must NEVER receive. Kept as an explicit deny-set so the
+ * supervisor can assert that a filtered tool list contains none of these,
+ * even if future tools are added upstream.
+ */
+exports.SUBAGENT_FORBIDDEN_TOOLS = [
+    'exec_command',
+    'edit_file',
+    'write_file',
+    'memory_save',
+    'memory_recall',
+    'memory_forget',
+    'openhorse',
+    'subtask',
+    // Generic MCP escape hatches — children must use first-class MCP tools
+    // (mcp__<server>__<tool>) with readOnlyHint === true instead.
+    'mcp_call',
+    'mcp_list',
+    // Cross-session information leak: history_search reads transcripts from
+    // all projects. Children must never access session history.
+    'history_search',
+];
+const JSON_OUTPUT_CONTRACT = `
+You MUST end your investigation by emitting a single JSON object and nothing else after it, matching this schema:
+
+{
+  "summary": "one concise paragraph of the overall conclusion",
+  "findings": [{ "severity": "critical|high|medium|low|info", "title": "short", "evidence": "specific file:line or quoted fact", "file": "optional path", "line": 0 }],
+  "files": ["paths you inspected or that are relevant"],
+  "commands": [{ "command": "suggested read-only or root-owned command", "purpose": "why" }],
+  "verification": ["how the root Agent can verify your conclusion"],
+  "risks": ["caveats, unknowns, or things that could invalidate this"]
+}
+
+Rules:
+- Every finding must cite concrete evidence (file path, line, quoted text, or command output you observed). Do not speculate.
+- "commands.executed" is always false; you may only SUGGEST commands for the root Agent to run. Never claim you executed one.
+- You cannot edit, write, delete, commit, push, publish, install dependencies, run tests, or create further subagents.
+- If you cannot reach a confident conclusion, say so in "risks" rather than fabricating evidence.
+- Keep the JSON valid and self-contained. No trailing prose.`;
+exports.ROLE_PRESETS = {
+    research: {
+        role: 'research',
+        tools: exports.READ_ONLY_INVESTIGATION_TOOLS,
+        systemPrompt: `You are a read-only research subagent for OpenHorse. Your job is to gather repository facts, official documentation, or API behavior and return a structured conclusion.
+
+You may only read files, list/glob/grep, batch read-only steps, and use configured read-only MCP tools (e.g. web search/fetch). You may inspect git state only through read-only means available to you.
+
+Focus narrowly on the objective you were given. Do not attempt edits or commands.${JSON_OUTPUT_CONTRACT}`,
+    },
+    review: {
+        role: 'review',
+        tools: exports.READ_ONLY_INVESTIGATION_TOOLS,
+        systemPrompt: `You are a read-only code review subagent for OpenHorse. Your job is to review a diff, changeset, or code area for risks, regressions, and test gaps, and return a structured conclusion.
+
+You may read files, list/glob/grep, batch read-only steps, and use read-only MCP tools. You may NOT fix code, change review scope, execute shell, or commit.${JSON_OUTPUT_CONTRACT}`,
+    },
+    'test-investigate': {
+        role: 'test-investigate',
+        tools: exports.READ_ONLY_INVESTIGATION_TOOLS,
+        systemPrompt: `You are a read-only test investigation subagent for OpenHorse. You analyze failing test logs, test code, and configuration to identify likely root causes, and return a structured conclusion.
+
+You may read files, list/glob/grep, batch read-only steps, and use read-only MCP tools. You may NOT execute tests, install dependencies, update snapshots, write fixtures, or publish. If a command would help diagnose the failure, suggest it in "commands" for the root Agent to run.${JSON_OUTPUT_CONTRACT}`,
+    },
+};
+/** Resolve the tool allowlist for a role. Falls back to the read-only set. */
+function toolsForRole(role) {
+    return exports.ROLE_PRESETS[role]?.tools ?? exports.READ_ONLY_INVESTIGATION_TOOLS;
+}
+/** Resolve the system prompt for a role. */
+function systemPromptForRole(role) {
+    return exports.ROLE_PRESETS[role]?.systemPrompt ?? exports.ROLE_PRESETS.research.systemPrompt;
+}
+/**
+ * Filter an upstream tool list to a role's allowlist, removing any forbidden
+ * tool and the recursive `subtask` capability. Also includes first-class MCP
+ * tools (mcp__<server>__<tool>) that declare `readOnlyHint === true` via
+ * their `isReadOnly()` method — these are safe for children because they
+ * cannot invoke arbitrary MCP actions.
+ *
+ * Returns the names the child may receive; the caller is responsible for
+ * resolving them to tool definitions.
+ */
+function filterToolsForRole(availableToolNames, role, runtimeTools) {
+    const allowed = new Set(toolsForRole(role));
+    const denied = new Set(exports.SUBAGENT_FORBIDDEN_TOOLS);
+    // Build a map of tool name → tool definition for annotation checks.
+    const toolMap = new Map();
+    if (runtimeTools) {
+        for (const t of runtimeTools) {
+            toolMap.set(t.name, t);
+        }
+    }
+    return availableToolNames.filter(name => {
+        // Explicitly denied tools are never allowed.
+        if (denied.has(name))
+            return false;
+        // First-class MCP tools (mcp__<server>__<tool>) are allowed only if
+        // they declare isReadOnly() === true. Unknown or missing annotation
+        // means denied — conservative default.
+        if (name.startsWith('mcp__')) {
+            const tool = toolMap.get(name);
+            if (!tool)
+                return false;
+            return tool.isReadOnly?.({}) === true;
+        }
+        // Static allowlist covers non-MCP tools.
+        return allowed.has(name);
+    });
+}
+/** Assert a filtered tool list contains no forbidden tool. Used by the runner. */
+function assertNoForbiddenTools(toolNames) {
+    const denied = new Set(exports.SUBAGENT_FORBIDDEN_TOOLS);
+    const found = toolNames.filter(name => denied.has(name));
+    if (found.length > 0) {
+        throw new Error(`Subagent tool list contains forbidden tools: ${found.join(', ')}`);
+    }
+}
+//# sourceMappingURL=presets.js.map

package/dist/runtime/subagents/presets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"presets.js","sourceRoot":"","sources":["../../../src/runtime/subagents/presets.ts"],"names":[],"mappings":"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"}

package/dist/runtime/subagents/production.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Production binding for {@link ExecuteChildQuery}.
+ *
+ * Bridges the Supervisor (which is LLM-agnostic) to the real `query()` loop.
+ * Each child gets its own {@link LLMService} so mutable per-request state
+ * (`consecutive529Errors`, `usingFallback`, `lastRequestDiagnostics`) is not
+ * shared across concurrent children. All children still flow through the shared
+ * {@link SubagentProviderGate} for concurrency bounding and cooldown.
+ *
+ * `createLlm` and `runQuery` are injectable so the binding is unit-testable
+ * without a live provider; production wires them to `new LLMService(...)` and
+ * `query()`.
+ */
+import { LLMService, type LLMConfig } from '../../services/llm';
+import { type QueryEvent, type QueryParams } from '../../framework/query';
+import type { ExecuteChildQuery } from './runner';
+import type { SubagentProviderGate } from './provider-gate';
+export interface SubagentLlmFactoryDeps {
+    /** Root config used to derive each child's LLMConfig. */
+    rootConfig: Pick<LLMConfig, 'apiKey' | 'baseUrl' | 'model' | 'fallbackModel'>;
+    /** Injectable LLMService factory (production: `new LLMService(config)`). */
+    createLlm?: (config: LLMConfig) => LLMService;
+    /** Injectable query loop (production: `query`). */
+    runQuery?: (params: QueryParams) => AsyncIterable<QueryEvent>;
+    /** Shared gate; a child that observes a 429 enters cooldown for siblings. */
+    providerGate: SubagentProviderGate;
+    /** Per-child turn cap. */
+    maxTurnsPerTask: number;
+}
+/**
+ * Create a per-child LLMService. Children share the provider account but not
+ * the mutable request state, so one child's fallback/retry does not reshape
+ * another child's model choice or diagnostics.
+ */
+export declare function createChildLlmConfig(rootConfig: Pick<LLMConfig, 'apiKey' | 'baseUrl' | 'model' | 'fallbackModel'>): LLMConfig;
+/**
+ * Build the production {@link ExecuteChildQuery}. The returned function runs one
+ * child to completion: it creates an isolated LLMService, drives `query()` with
+ * the child messages + filtered tools, and returns the final assistant text and
+ * observed usage. Never throws - provider errors surface as an empty result so
+ * the runner normalizes them into a `failed` SubtaskResult.
+ */
+export declare function createProductionExecuteQuery(deps: SubagentLlmFactoryDeps): ExecuteChildQuery;
+//# sourceMappingURL=production.d.ts.map

package/dist/runtime/subagents/production.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"production.d.ts","sourceRoot":"","sources":["../../../src/runtime/subagents/production.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,UAAU,EAAE,KAAK,SAAS,EAAgB,MAAM,oBAAoB,CAAC;AAE9E,OAAO,EAAS,KAAK,UAAU,EAAE,KAAK,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACjF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAGlD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAE5D,MAAM,WAAW,sBAAsB;IACrC,yDAAyD;IACzD,UAAU,EAAE,IAAI,CAAC,SAAS,EAAE,QAAQ,GAAG,SAAS,GAAG,OAAO,GAAG,eAAe,CAAC,CAAC;IAC9E,4EAA4E;IAC5E,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,SAAS,KAAK,UAAU,CAAC;IAC9C,mDAAmD;IACnD,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,aAAa,CAAC,UAAU,CAAC,CAAC;IAC9D,6EAA6E;IAC7E,YAAY,EAAE,oBAAoB,CAAC;IACnC,0BAA0B;IAC1B,eAAe,EAAE,MAAM,CAAC;CACzB;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,IAAI,CAAC,SAAS,EAAE,QAAQ,GAAG,SAAS,GAAG,OAAO,GAAG,eAAe,CAAC,GAC5E,SAAS,CAQX;AAED;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,sBAAsB,GAAG,iBAAiB,CA8C5F"}