sortie-dogs 0.1.4 → 0.1.11

package/README.md

@@ -80,6 +80,55 @@ OpenCode discovers the bridge automatically; no `plugin` entry in
 
 Selecting `dog-coordinator` directly also activates the workflow.
 
+## The write gate
+
+The write gate is opt-in per project. Without `operation-manifest.json` in the
+project root, the plugin stays passive and never denies a tool call. Creating
+that file is how a project opts in, so the coordinator can always create it.
+
+```json
+{
+  "version": "0.1.0",
+  "task_id": "add-requested-behavior",
+  "read": ["src/feature.ts", "test/feature.test.ts"],
+  "write": ["src/feature.ts", "test/feature.test.ts"],
+  "validation": ["npm test"]
+}
+```
+
+- `write` lists the only paths a bound worker may change. A listed directory
+  covers the files under it; every other entry is an exact path.
+- `validation` lists the exact commands a bound worker may run. Build and test
+  commands cannot be classified by path, so a command is allowed only when it
+  matches a declared entry exactly. Anything else is denied as unclassified.
+- `read` documents the intended reading scope; reads are never blocked.
+
+`dog-coordinator` owns this file. A worker binds to it once per candidate with
+`sortie_bind_write_gate`, and only after the coordinator's handoff has been
+inspected. Coordinator sessions are never gated.
+
+Optional settings in `.opencode/sortie-dogs.json`:
+
+```json
+{
+  "operationManifestPath": "operation-manifest.json",
+  "handoffPaths": ["handoff.json"],
+  "readOnlyTools": ["my_mcp_search"],
+  "dedicatedWorkerModel": { "model": "provider/model", "variant": "deep" }
+}
+```
+
+- `operationManifestPath` moves the manifest; the path is project-relative.
+- `handoffPaths` lists the handoff files the plugin inspects. A worker can only
+  bind after one of these files passes inspection, so an empty list disables
+  binding entirely.
+- `readOnlyTools` adds host-specific tool names that never change files, such as
+  MCP tools. Unknown tools are denied for a bound session by default.
+- `dedicatedWorkerModel` selects the single model every worker role resolves to.
+  It defaults to `openai/gpt-5.6-sol` with variant `xhigh`; declare your own when
+  that model is unavailable. Worker roles always resolve to this one target and
+  cannot be routed per role.
+
 ## Why Sortie-dogs
 
 - **Focused when invited, invisible otherwise.** Activate it with `/sortie` or

package/dist/asset-version.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Version of the installable runtime assets. Kept in its own module so the plugin can compare an
+ * installed project marker without importing every asset body.
+ */
+export declare const RUNTIME_ASSET_VERSION = "0.2.0-card05";
+export type RuntimeAssetVersion = typeof RUNTIME_ASSET_VERSION;

package/dist/asset-version.js

@@ -0,0 +1,5 @@
+/**
+ * Version of the installable runtime assets. Kept in its own module so the plugin can compare an
+ * installed project marker without importing every asset body.
+ */
+export const RUNTIME_ASSET_VERSION = "0.2.0-card05";

package/dist/core/consultation.d.ts

@@ -102,7 +102,10 @@ export interface SourceReviewConsultationResult {
     readonly review: ReviewVerdict;
 }
 export type ConsultationResult = StrategyConsultationResult | SourceReviewConsultationResult | UnavailableConsultationResult;
-/** Host-owned adapters implement transport. Core never executes commands or selects providers. */
+/**
+ * Sole consultation transport boundary. The host supplies this adapter; core passes only the
+ * provider-, model-, variant-, and transport-neutral request and result envelopes above.
+ */
 export interface ConsultationAdapter {
     consult(request: ConsultationRequest): Promise<ConsultationResult>;
 }

package/dist/plugin/config.d.ts

@@ -1,7 +1,17 @@
-import { type ModelCatalog, type ModelRoutingConfig } from "./model-routing.js";
+import { type ModelCatalog, type ModelRoutingConfig, type ModelTarget } from "./model-routing.js";
 export interface SortieDogsPluginOptions {
     operationManifestPath?: string;
     handoffPaths?: readonly string[];
+    /**
+     * Host-specific tool names that never change project files, such as MCP tools. Names accumulate
+     * across layers because each layer describes a different part of the same environment.
+     */
+    readOnlyTools?: readonly string[];
+    /**
+     * The single model every dedicated worker role resolves to. Worker routing stays fixed to one
+     * target; a host that cannot serve the shipped target declares its own here.
+     */
+    dedicatedWorkerModel?: ModelTarget;
     modelRouting?: ModelRoutingConfig;
     modelCatalog?: ModelCatalog;
     consultation?: ConsultationPolicyInput;
@@ -31,6 +41,8 @@ export interface ConfiguredPlugin {
     kind: "configured";
     operationManifestPath: string;
     handoffPaths: readonly string[];
+    readOnlyTools: readonly string[];
+    dedicatedWorkerModel: ModelTarget;
     modelRouting: ModelRoutingConfig;
     modelCatalog: ModelCatalog;
     consultation: ConsultationPolicy;

package/dist/plugin/config.js

@@ -1,8 +1,10 @@
-import { BUILT_IN_MODEL_CATALOG, FIXED_MODEL_ROUTING, RECOMMENDED_LUNA_ROUTING, isFixedModelRole, parseModelRoutingConfig, } from "./model-routing.js";
+import { BUILT_IN_MODEL_CATALOG, DEFAULT_DEDICATED_WORKER_TARGET, RECOMMENDED_LUNA_ROUTING, dedicatedWorkerRouting, isFixedModelRole, parseModelRoutingConfig, parseModelTarget, } from "./model-routing.js";
 import { CONSULTATION_ROLE_POLICY } from "../core/consultation.js";
 export const DEFAULT_PLUGIN_OPTIONS = {
     operationManifestPath: "operation-manifest.json",
     handoffPaths: ["handoff.json"],
+    readOnlyTools: [],
+    dedicatedWorkerModel: DEFAULT_DEDICATED_WORKER_TARGET,
     modelRouting: RECOMMENDED_LUNA_ROUTING,
     modelCatalog: BUILT_IN_MODEL_CATALOG,
     consultation: Object.freeze({
@@ -156,11 +158,20 @@ function parseLayer(value) {
         return {};
     if (!isRecord(value))
         return undefined;
-    if (Object.keys(value).some((key) => !["operationManifestPath", "handoffPaths", "modelRouting", "modelCatalog", "consultation"].includes(key))) {
+    if (Object.keys(value).some((key) => ![
+        "operationManifestPath", "handoffPaths", "readOnlyTools", "dedicatedWorkerModel",
+        "modelRouting", "modelCatalog", "consultation",
+    ].includes(key))) {
         return undefined;
     }
     const manifestPath = value.operationManifestPath;
     const handoffPaths = value.handoffPaths;
+    const readOnlyTools = value.readOnlyTools;
+    const dedicatedWorkerModel = value.dedicatedWorkerModel === undefined
+        ? undefined
+        : parseModelTarget(value.dedicatedWorkerModel);
+    if (value.dedicatedWorkerModel !== undefined && dedicatedWorkerModel === undefined)
+        return undefined;
     const modelRouting = value.modelRouting === undefined
         ? undefined
         : parseModelRoutingConfig(value.modelRouting);
@@ -177,6 +188,11 @@ function parseLayer(value) {
         (!Array.isArray(handoffPaths) || handoffPaths.some((path) => typeof path !== "string" || path.length === 0))) {
         return undefined;
     }
+    if (readOnlyTools !== undefined &&
+        (!Array.isArray(readOnlyTools) ||
+            readOnlyTools.some((tool) => typeof tool !== "string" || tool.trim().length === 0))) {
+        return undefined;
+    }
     if (value.modelRouting !== undefined && modelRouting === undefined)
         return undefined;
     if (value.modelCatalog !== undefined && modelCatalog === undefined)
@@ -186,6 +202,8 @@ function parseLayer(value) {
     return {
         operationManifestPath: manifestPath,
         handoffPaths: handoffPaths,
+        readOnlyTools: readOnlyTools,
+        dedicatedWorkerModel,
         modelRouting,
         modelCatalog,
         consultation,
@@ -195,6 +213,8 @@ function parseLayer(value) {
 export function resolvePluginConfiguration(...values) {
     let operationManifestPath = DEFAULT_PLUGIN_OPTIONS.operationManifestPath;
     let handoffPaths = DEFAULT_PLUGIN_OPTIONS.handoffPaths;
+    const readOnlyTools = new Set(DEFAULT_PLUGIN_OPTIONS.readOnlyTools);
+    let dedicatedWorkerModel = DEFAULT_PLUGIN_OPTIONS.dedicatedWorkerModel;
     let modelRouting = DEFAULT_PLUGIN_OPTIONS.modelRouting;
     let modelCatalog = DEFAULT_PLUGIN_OPTIONS.modelCatalog;
     let consultation = DEFAULT_PLUGIN_OPTIONS.consultation;
@@ -206,6 +226,10 @@ export function resolvePluginConfiguration(...values) {
             operationManifestPath = layer.operationManifestPath;
         if (layer.handoffPaths !== undefined)
             handoffPaths = layer.handoffPaths;
+        for (const tool of layer.readOnlyTools ?? [])
+            readOnlyTools.add(tool.trim().toLowerCase());
+        if (layer.dedicatedWorkerModel !== undefined)
+            dedicatedWorkerModel = layer.dedicatedWorkerModel;
         if (layer.modelRouting !== undefined) {
             modelRouting = { ...modelRouting, ...layer.modelRouting };
         }
@@ -227,7 +251,16 @@ export function resolvePluginConfiguration(...values) {
     }
     modelRouting = {
         ...Object.fromEntries(Object.entries(modelRouting).filter(([role]) => !isFixedModelRole(role))),
-        ...FIXED_MODEL_ROUTING,
+        ...dedicatedWorkerRouting(dedicatedWorkerModel),
+    };
+    // The dedicated target is authoritative for worker roles, so it is always a known catalog entry.
+    modelCatalog = {
+        ...modelCatalog,
+        global: mergeCatalogModels(modelCatalog.global ?? [], [
+            dedicatedWorkerModel.variant === undefined
+                ? { model: dedicatedWorkerModel.model }
+                : { model: dedicatedWorkerModel.model, variants: [dedicatedWorkerModel.variant] },
+        ]),
     };
     const hasRouting = Object.keys(modelRouting).length > 0;
     const hasCatalogEntries = (modelCatalog.project?.length ?? 0) + (modelCatalog.global?.length ?? 0) > 0;
@@ -237,6 +270,8 @@ export function resolvePluginConfiguration(...values) {
         kind: "configured",
         operationManifestPath,
         handoffPaths,
+        readOnlyTools: [...readOnlyTools],
+        dedicatedWorkerModel,
         modelRouting,
         modelCatalog,
         consultation,
@@ -258,16 +293,17 @@ export function resolvePluginConfigurationSources(projectValue, environmentValue
         ...(environmentLayer.modelRouting ?? {}),
         ...(hostLayer.modelRouting ?? {}),
     }).filter(([role]) => !isFixedModelRole(role)));
+    const fixedRouting = dedicatedWorkerRouting(configured.dedicatedWorkerModel);
     const modelRouting = {
         ...Object.fromEntries(Object.entries(configured.modelRouting)
             .filter(([role]) => !isFixedModelRole(role))),
-        ...FIXED_MODEL_ROUTING,
+        ...fixedRouting,
     };
     return {
         ...configured,
         modelRouting,
         // Dedicated worker policy is authoritative over every configurable layer.
-        localModelRouting: { ...(projectLayer.modelRouting ?? {}), ...FIXED_MODEL_ROUTING },
+        localModelRouting: { ...(projectLayer.modelRouting ?? {}), ...fixedRouting },
         globalModelRouting,
     };
 }

package/dist/plugin/gate.d.ts

@@ -6,7 +6,7 @@ export interface ToolExecuteBeforeInput {
 export interface ToolExecuteBeforeOutput {
     args: unknown;
 }
-export type WriteDenialReason = "manifest-unavailable" | "path-required" | "project-boundary" | "manifest-scope";
+export type WriteDenialReason = "manifest-unavailable" | "session-expired" | "unclassified-command" | "path-required" | "project-boundary" | "manifest-scope" | "repeated-denial";
 export declare class WriteDeniedError extends Error {
     readonly reason: WriteDenialReason;
     constructor(reason: WriteDenialReason, path: string, options?: ErrorOptions);
@@ -27,14 +27,28 @@ interface Extraction {
     ambiguous: boolean;
     paths: string[];
     gitCommit?: boolean;
+    issue?: CommandIssue;
+}
+interface CommandIssue {
+    segment: string;
+    cause: string;
+    hint: string;
 }
 export declare function safePath(path: string): string;
 export declare function resolveProjectRoot(input: {
     directory: string;
     worktree?: string;
 }): string;
+export declare function describeUnclassifiedCommand(tool: string, args: unknown): string | undefined;
 /** Extract known write destinations; unknown shell executables fail closed as ambiguous. */
 export declare function extractWritePaths(tool: string, args: unknown): Extraction;
+/**
+ * Quoted segments keep their contents; every unquoted whitespace run collapses to one space so the
+ * same command written with different spacing compares equal.
+ */
+export declare function normalizeCommand(command: string): string;
+/** Unbound sessions may invoke only tools whose complete input is known to be read-only. */
+export declare function isKnownReadOnlyTool(tool: string, args: unknown, additionalReadOnlyTools?: ReadonlySet<string>): boolean;
 export declare function createProjectPaths(rootCandidate: string): Promise<ProjectPaths>;
 export declare function createWriteGate(project: ProjectPaths, value: unknown): Promise<WriteGate>;
 export {};

package/dist/plugin/gate.js

@@ -9,9 +9,12 @@ export class WriteDeniedError extends Error {
     constructor(reason, path, options) {
         const messages = {
             "manifest-unavailable": "operation manifest unavailable.",
+            "session-expired": "active session expired; start or resume an explicit Task takeover.",
+            "unclassified-command": "unclassified command; use the stated direct-command hint.",
             "path-required": "write path must be explicit.",
             "project-boundary": "project-root-relative path required.",
             "manifest-scope": "operation manifest write scope.",
+            "repeated-denial": "same command and denial reason already denied in this session; retry blocked.",
         };
         super(`Write denied for "${safePath(path)}": ${messages[reason]}`, options);
         this.name = "WriteDeniedError";
@@ -25,8 +28,9 @@ const DIRECT_PATH_KEYS = new Set([
 const ALL_OPERAND_COMMANDS = new Set(["mkdir", "rm", "rmdir", "touch", "truncate", "unlink"]);
 const LAST_OPERAND_COMMANDS = new Set(["cp", "install"]);
 const READ_ONLY_COMMANDS = new Set([
-    "cat", "echo", "false", "get-childitem", "get-content", "grep", "head", "ls", "pwd",
-    "rg", "stat", "tail", "test-path", "true", "type", "wc",
+    "cat", "echo", "false", "get-childitem", "get-content", "get-date", "grep", "head", "ls", "pwd",
+    "measure-object", "rg", "select-object", "stat", "tail", "test-path", "true", "type",
+    "where-object", "wc",
 ]);
 const READ_ONLY_GIT_COMMANDS = new Set(["diff", "log", "ls-files", "rev-parse", "show", "status"]);
 const POWERSHELL_WRITE_COMMANDS = new Set([
@@ -34,6 +38,16 @@ const POWERSHELL_WRITE_COMMANDS = new Set([
     "rename-item", "set-content",
 ]);
 const READ_ONLY_OPTIONS_WITH_VALUES = new Set(["-c", "--directory", "--exclude", "--include"]);
+/**
+ * Tools that never change project files themselves. A dispatched subagent runs in its own session
+ * and is gated there, and task-list tools only change session state, so denying them would stop
+ * delegation and progress tracking without protecting any path.
+ */
+const READ_ONLY_TOOLS = new Set([
+    "glob", "grep", "list", "list_mcp_resource_templates", "list_mcp_resources", "question",
+    "read", "read_mcp_resource", "review_git_evidence", "skill", "task", "todoread", "todowrite",
+    "webfetch",
+]);
 function isRecord(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
 }
@@ -149,23 +163,143 @@ function isSafeGitCommit(tokens) {
     }
     return true;
 }
-function shellPaths(command) {
+function isLiteralPowerShellAssignment(value) {
+    return /^(?:[+-]?(?:\d+(?:\.\d+)?|\.\d+)|\$(?:null|true|false)|\$[A-Za-z_][A-Za-z0-9_]*|\$env:[A-Za-z_][A-Za-z0-9_]*|'[^']*'|"[^"`$]*")$/iu.test(value);
+}
+function isSafePowerShellForEach(source) {
+    return /^(?:foreach-object|%)\s+\{\s*\$_(?:\.[A-Za-z_][A-Za-z0-9_]*)?\s*\}$/iu.test(source);
+}
+function scanShellSyntax(source, dialect) {
+    const masked = new Array(source.length).fill(" ");
+    let quote;
+    let unsafeExpansion = false;
+    let activeBrace = false;
+    for (let index = 0; index < source.length; index += 1) {
+        const character = source[index];
+        if (quote !== undefined) {
+            if (dialect === "powershell" && quote === "\"" && character === "`") {
+                unsafeExpansion = true;
+                index += 1;
+                continue;
+            }
+            if (dialect === "posix" && quote === "\"" && character === "\\") {
+                index += 1;
+                continue;
+            }
+            if (character === quote) {
+                if (dialect === "powershell" && source[index + 1] === quote)
+                    index += 1;
+                else
+                    quote = undefined;
+                continue;
+            }
+            if (quote === "\"" &&
+                (((character === "$" || character === "<") && source[index + 1] === "(") ||
+                    (character === "$" && source[index + 1] === "{")))
+                unsafeExpansion = true;
+            continue;
+        }
+        if (character === "\"" || character === "'") {
+            quote = character;
+            continue;
+        }
+        masked[index] = character;
+        if (character === "`") {
+            unsafeExpansion = true;
+            if (dialect === "powershell")
+                index += 1;
+        }
+        else if (((character === "$" || character === "<") && source[index + 1] === "(") ||
+            (character === "$" && source[index + 1] === "{")) {
+            unsafeExpansion = true;
+        }
+        else if (character === "{" || character === "}") {
+            activeBrace = true;
+        }
+    }
+    return { masked: masked.join(""), unsafeExpansion, activeBrace };
+}
+function shellSegments(command, dialect) {
+    const segments = [];
+    const masked = scanShellSyntax(command, dialect).masked;
+    let start = 0;
+    for (let index = 0; index < masked.length; index += 1) {
+        const character = masked[index];
+        const pair = masked.slice(index, index + 2);
+        const separator = pair === "&&" || pair === "||" ? 2
+            : character === ";" || character === "\n" || character === "\r" ||
+                (character === "|" && command[index - 1] !== ">") ? 1 : 0;
+        if (separator === 0)
+            continue;
+        segments.push(command.slice(start, index));
+        index += separator - 1;
+        if (character === "\r" && command[index + 1] === "\n")
+            index += 1;
+        start = index + 1;
+    }
+    segments.push(command.slice(start));
+    return segments;
+}
+function depthOnePowerShellLiteral(source) {
+    const match = /^\s*(?:"[^"]*(?:pwsh|powershell)(?:\.exe)?"|[^\s"']*(?:pwsh|powershell)(?:\.exe)?)\s+-noprofile\s+-command\s+'((?:''|[^'])*)'\s*$/iu.exec(source);
+    return match?.[1].replaceAll("''", "'");
+}
+function commandIssue(segment, cause, hint) {
+    return { segment: segment.trim().slice(0, 240), cause, hint };
+}
+function shellPaths(command, powershell, depth = 0) {
     const paths = [];
     let applies = false;
     let ambiguous = false;
     let gitCommit = false;
-    const redirection = /(?:^|[\s;&|])(?:\d*)(?:>>?|>\|)\s*("(?:\\.|[^"])*"|'[^']*'|[^\s;&|]+)/gu;
-    for (const match of command.matchAll(redirection)) {
-        applies = true;
-        paths.push(unquote(match[1]));
-    }
-    for (const segment of command.split(/(?:&&|\|\||(?<!>)\|(?!\|)|;|\r?\n)/u)) {
-        const tokens = unwrapEnvironmentCommand(words(segment.trim()));
+    let issue;
+    const redirection = /(?<![<>=!])(?:&|\d*)?(?:>>|>\||>)(?![=])/gu;
+    const redirectionTarget = /^\s*("(?:\\.|[^"])*"|'[^']*'|&?\d+|[^\s;&|]+)/u;
+    const dialect = powershell ? "powershell" : "posix";
+    const segments = shellSegments(command, dialect);
+    for (let segmentIndex = 0; segmentIndex < segments.length; segmentIndex += 1) {
+        const segment = segments[segmentIndex];
+        let source = segment.trim();
+        let assignment = false;
+        const syntax = scanShellSyntax(source, dialect);
+        for (const match of syntax.masked.matchAll(redirection)) {
+            applies = true;
+            const target = redirectionTarget.exec(source.slice(match.index + match[0].length))?.[1];
+            if (target === undefined || target.startsWith("&")) {
+                ambiguous = true;
+                issue ??= commandIssue(source, "redirect-target-unresolved", "name one manifest-scoped output path");
+            }
+            else {
+                paths.push(unquote(target));
+            }
+        }
+        if (syntax.unsafeExpansion) {
+            applies = true;
+            ambiguous = true;
+            issue ??= commandIssue(source, "active-expansion", "remove substitution and run a direct literal command");
+            continue;
+        }
+        if (powershell) {
+            const stripped = source.replace(/^\$[A-Za-z_][A-Za-z0-9_:]*\s*=\s*/u, "");
+            assignment = stripped !== source;
+            source = stripped;
+            if (/^\$env:[A-Za-z_][A-Za-z0-9_]*$/iu.test(source) ||
+                (assignment && isLiteralPowerShellAssignment(source)))
+                continue;
+        }
+        const tokens = unwrapEnvironmentCommand(words(source));
         if (tokens.length === 0)
             continue;
         const executable = tokens[0].replaceAll("\\", "/").split("/").at(-1).toLowerCase();
         const commandOperands = operands(tokens);
-        if (ALL_OPERAND_COMMANDS.has(executable)) {
+        if (powershell && syntax.activeBrace) {
+            if (segmentIndex > 0 && isSafePowerShellForEach(source))
+                continue;
+            applies = true;
+            ambiguous = true;
+            issue ??= commandIssue(source, "active-scriptblock", "use strict ForEach-Object { $_.Property } or a direct command");
+        }
+        else if (ALL_OPERAND_COMMANDS.has(executable)) {
             applies = true;
             paths.push(...commandOperands);
         }
@@ -229,12 +363,36 @@ function shellPaths(command) {
         else if (/^gh(?:\.exe)?$/u.test(executable) && isRemoteOnlyGitHubCommand(tokens)) {
             // GitHub Project commands mutate remote state, not project files. Redirections remain gated above.
         }
+        else if (depth === 0 && /^(?:pwsh|powershell)(?:\.exe)?$/u.test(executable)) {
+            const literal = depthOnePowerShellLiteral(source);
+            if (literal === undefined) {
+                applies = true;
+                ambiguous = true;
+                issue ??= commandIssue(source, "unsupported-pwsh-form", "use pwsh -NoProfile -Command '<literal>' at depth one");
+            }
+            else {
+                const nested = shellPaths(literal, true, depth + 1);
+                applies ||= nested.applies;
+                ambiguous ||= nested.ambiguous;
+                paths.push(...nested.paths);
+                gitCommit ||= nested.gitCommit === true;
+                issue ??= nested.issue;
+            }
+        }
         else if (!READ_ONLY_COMMANDS.has(executable)) {
             applies = true;
             ambiguous = true;
+            issue ??= commandIssue(source, "executable-not-allowlisted", "use a direct allowlisted read-only command");
         }
     }
-    return { applies, ambiguous, paths, ...(gitCommit ? { gitCommit: true } : {}) };
+    return { applies, ambiguous, paths, ...(gitCommit ? { gitCommit: true } : {}), ...(issue ? { issue } : {}) };
+}
+function issuePath(issue) {
+    return `segment=${issue.segment}; cause=${issue.cause}; hint=${issue.hint}`;
+}
+export function describeUnclassifiedCommand(tool, args) {
+    const extracted = extractWritePaths(tool, args);
+    return extracted.ambiguous && extracted.issue !== undefined ? issuePath(extracted.issue) : undefined;
 }
 /** Extract known write destinations; unknown shell executables fail closed as ambiguous. */
 export function extractWritePaths(tool, args) {
@@ -251,18 +409,71 @@ export function extractWritePaths(tool, args) {
     }
     if (/^(?:bash|shell|powershell|pwsh)(?:$|[_-])/u.test(name)) {
         const command = isRecord(args) && typeof args.command === "string" ? args.command : undefined;
-        if (command === undefined)
-            return { applies: paths.length > 0, ambiguous: paths.length === 0, paths };
-        const extracted = shellPaths(command);
+        if (command === undefined) {
+            const ambiguous = paths.length === 0;
+            return {
+                applies: paths.length > 0,
+                ambiguous,
+                paths,
+                ...(ambiguous ? {
+                    issue: commandIssue("<missing-command>", "command-argument-missing", "provide one direct literal command"),
+                } : {}),
+            };
+        }
+        const extracted = shellPaths(command, /^(?:powershell|pwsh)(?:$|[_-])/u.test(name));
         return {
             applies: extracted.applies || paths.length > 0,
             ambiguous: extracted.ambiguous,
             paths: [...paths, ...extracted.paths],
             ...(extracted.gitCommit ? { gitCommit: true } : {}),
+            ...(extracted.issue ? { issue: extracted.issue } : {}),
         };
     }
     return { applies: false, ambiguous: false, paths: [] };
 }
+/**
+ * Quoted segments keep their contents; every unquoted whitespace run collapses to one space so the
+ * same command written with different spacing compares equal.
+ */
+export function normalizeCommand(command) {
+    let quote;
+    let whitespace = false;
+    let normalized = "";
+    for (const character of command.trim()) {
+        if (quote !== undefined) {
+            normalized += character;
+            if (character === quote)
+                quote = undefined;
+        }
+        else if (character === "\"" || character === "'") {
+            if (whitespace && normalized.length > 0)
+                normalized += " ";
+            whitespace = false;
+            quote = character;
+            normalized += character;
+        }
+        else if (/\s/u.test(character)) {
+            whitespace = true;
+        }
+        else {
+            if (whitespace && normalized.length > 0)
+                normalized += " ";
+            whitespace = false;
+            normalized += character;
+        }
+    }
+    return normalized;
+}
+/** Unbound sessions may invoke only tools whose complete input is known to be read-only. */
+export function isKnownReadOnlyTool(tool, args, additionalReadOnlyTools = new Set()) {
+    const name = tool.toLowerCase();
+    if (READ_ONLY_TOOLS.has(name) || additionalReadOnlyTools.has(name))
+        return true;
+    if (!/^(?:bash|shell|powershell|pwsh)(?:$|[_-])/u.test(name))
+        return false;
+    const extraction = extractWritePaths(tool, args);
+    return !extraction.applies && !extraction.ambiguous;
+}
 async function nearestExistingRealPath(path) {
     let candidate = path;
     while (true) {
@@ -311,6 +522,10 @@ export async function createWriteGate(project, value) {
     if (!validated.ok)
         throw new WriteDeniedError("manifest-unavailable", "<unknown>");
     const manifest = validated.value;
+    // A build or test command may touch any path its toolchain owns, so it can never be classified by
+    // path extraction. The manifest already declares the commands this candidate is allowed to run,
+    // so an exact match against that declaration is the only accepted form.
+    const declaredValidation = new Set(manifest.validation.map(normalizeCommand));
     const writable = new Set(manifest.write.map((path) => normalizeRelativePath(path)));
     const writableDirectories = [];
     for (const path of writable) {
@@ -389,11 +604,19 @@ export async function createWriteGate(project, value) {
         checkPath,
         toRelativePath: project.toRelativePath,
         async check(_input, output) {
+            const command = isRecord(output.args) && typeof output.args.command === "string"
+                ? normalizeCommand(output.args.command)
+                : undefined;
+            if (command !== undefined && declaredValidation.has(command))
+                return;
             const extracted = extractWritePaths(_input.tool, output.args);
             if (!extracted.applies)
                 return;
             if (extracted.ambiguous || (extracted.paths.length === 0 && !extracted.gitCommit)) {
-                throw new WriteDeniedError("path-required", "<unknown>");
+                if (extracted.issue !== undefined) {
+                    throw new WriteDeniedError("unclassified-command", issuePath(extracted.issue));
+                }
+                throw new WriteDeniedError("path-required", "<missing-path>");
             }
             for (const path of extracted.paths)
                 await checkPath(path);

package/dist/plugin/index.d.ts

@@ -23,6 +23,7 @@ export interface OpenCodeHooks {
     }) => Promise<void>;
     "tool.execute.before"?: (input: ToolExecuteBeforeInput, output: ToolExecuteBeforeOutput) => Promise<void>;
     "chat.message"?: OpenCodeChatMessageHook;
+    tool?: Record<string, OpenCodeToolDefinition>;
 }
 export type OpenCodePlugin = (input: OpenCodePluginInput, options?: SortieDogsPluginOptions | Record<string, unknown>) => Promise<OpenCodeHooks>;
 export type HandoffDenialReason = "configuration-unavailable" | "path-invalid" | "input-unavailable" | "schema-invalid" | "contract-invalid";
@@ -30,6 +31,14 @@ export declare class HandoffDeniedError extends Error {
     readonly reason: HandoffDenialReason;
     constructor(reason: HandoffDenialReason, path: string, options?: ErrorOptions);
 }
+interface OpenCodeToolDefinition {
+    description: string;
+    args: Record<string, unknown>;
+    execute(args: Record<string, string>, context: {
+        sessionID: string;
+    }): Promise<string>;
+}
+export declare function isExplicitTaskHandoff(text: string): boolean;
 /** Named OpenCode plugin export. Importing the package has no side effects; invoking it installs active gates. */
 export declare const SortieDogsPlugin: OpenCodePlugin;
 export type { SortieDogsPluginOptions } from "./config.js";