@xingular/harness 1.2.0 → 1.3.1-unstable.0

package/dist/sdk/agents/builtin.js

@@ -1,6 +1,6 @@
 import { PLAN_RESEARCH_PLUGINS } from "./planResearch.js";
 const RECALL = ['history_search', 'history_read', 'trajectory_search', 'trajectory_read', 'wiki_search', 'wiki_read', 'wiki_list', 'skill_load'];
-const PROGRESS = ['checklist_write', 'session_name'];
+const PROGRESS = ['todo_write', 'session_name'];
 const WEB = ['web_search', 'web_fetch'];
 export const BUILTIN_PROFILES = [
     {
@@ -10,7 +10,7 @@ export const BUILTIN_PROFILES = [
         instructions: [
             'You carry out one piece of work from your brief, end to end.',
             '- Read the code you change first and follow the conventions you find.',
-            '- Keep a checklist with checklist_write when the brief has more than one step, and name your session with session_name.',
+            '- Keep a todo list with todo_write when the brief has more than one step, and name your session with session_name.',
             '- Make the change, then check it: run the relevant tests, type checks or commands.',
             '- Stay inside the brief. If something outside it blocks you, stop and say so instead of widening the change.',
             '- Finish with a short report: what you changed (files), how you checked it, and anything left open.'
@@ -25,7 +25,7 @@ export const BUILTIN_PROFILES = [
         instructions: [
             'You answer a question about the code, files or history in your brief. You never change anything.',
             '- Search broadly first, then read the parts that matter.',
-            '- Keep a checklist with checklist_write when the search has several parts, and name your session with session_name.',
+            '- Keep a todo list with todo_write when the search has several parts, and name your session with session_name.',
             '- Cite what you found as path:line.',
             '- Return conclusions, not file dumps: what you found, where, and how sure you are.'
         ].join('\n'),

package/dist/sdk/agents/planResearch.d.ts

@@ -1,5 +1,27 @@
+import type { CapabilitySet } from "../capabilities/types.js";
+import type { PluginDescriptor } from "../plugins/types.js";
 import type { AgentProfile } from "./profiles.js";
 export declare const PLAN_RESEARCH_TOOLS: ReadonlySet<string>;
 export declare const PLAN_RESEARCH_PLUGINS: readonly string[];
 export declare const PLAN_RESEARCH_EVIDENCE_TOOLS: ReadonlySet<string>;
-export declare function planResearchProfile(profile: Pick<AgentProfile, 'tools' | 'plugins'> | null | undefined): boolean;
+/** Capability snapshot needed to tell whether a profile can research in this particular run. */
+export interface PlanResearchContext {
+    frozenTools: readonly string[];
+    contributions: readonly string[];
+    descriptors: readonly PluginDescriptor[];
+}
+export interface PlanResearchEligibility {
+    eligible: boolean;
+    refusal: string | null;
+    /** The exact safe child snapshot to launch when eligible. */
+    capabilities: CapabilitySet;
+    unavailableTools: string[];
+}
+/** Whether the profile's explicit allowlists are restricted to read-only research. */
+export declare function planResearchProfile(profile: Pick<AgentProfile, 'name' | 'tools' | 'plugins'> | null | undefined): boolean;
+/**
+ * Evaluate the same effective intersection used for launch, including tool ownership removed by
+ * profile plugin narrowing. An explicit request is a strict override; omission inherits the safe
+ * profile/parent intersection.
+ */
+export declare function planResearchEligibility(profile: Pick<AgentProfile, 'name' | 'tools' | 'plugins'> | null | undefined, context: PlanResearchContext, requested?: readonly string[]): PlanResearchEligibility;

package/dist/sdk/agents/planResearch.js

@@ -1,5 +1,6 @@
+import { narrowForProfile } from "./narrow.js";
 export const PLAN_RESEARCH_TOOLS = new Set([
-    'read', 'grep', 'find', 'ls', 'checklist_write', 'session_name',
+    'read', 'grep', 'find', 'ls', 'todo_write', 'session_name',
     'history_search', 'history_read', 'trajectory_search', 'trajectory_read',
     'wiki_entrypoint', 'wiki_search', 'wiki_read', 'wiki_list', 'memory_facts', 'skill_load',
     'web_search', 'web_fetch'
@@ -8,12 +9,74 @@ export const PLAN_RESEARCH_PLUGINS = ['history', 'variant', 'web', 'wiki'];
 export const PLAN_RESEARCH_EVIDENCE_TOOLS = new Set([
     'read', 'grep', 'find', 'ls', 'history_search', 'trajectory_search', 'wiki_search', 'web_search', 'web_fetch'
 ]);
+function profileRefusal(profile) {
+    if (!profile)
+        return 'Plan-mode delegation requires a named, eligible read-only research profile.';
+    if (!Array.isArray(profile.tools) || profile.tools.length === 0) {
+        return `Profile ${profile.name} must declare an explicit tools allowlist for plan-mode research.`;
+    }
+    const unsafeTools = profile.tools.filter(name => !PLAN_RESEARCH_TOOLS.has(name));
+    if (unsafeTools.length) {
+        return `Profile ${profile.name} includes non-research tools: ${[...new Set(unsafeTools)].join(', ')}. Use a profile whose tools are all plan research tools.`;
+    }
+    if (!profile.tools.some(name => PLAN_RESEARCH_EVIDENCE_TOOLS.has(name))) {
+        return `Profile ${profile.name} must allow at least one read-only research evidence tool.`;
+    }
+    if (!Array.isArray(profile.plugins)) {
+        return `Profile ${profile.name} must declare an explicit plugin allowlist for plan-mode research.`;
+    }
+    const unsafePlugins = profile.plugins.filter(name => !PLAN_RESEARCH_PLUGINS.includes(name));
+    if (unsafePlugins.length) {
+        return `Profile ${profile.name} includes non-research plugins: ${[...new Set(unsafePlugins)].join(', ')}. Use only the plan research plugins: ${PLAN_RESEARCH_PLUGINS.join(', ')}.`;
+    }
+    return null;
+}
+/** Whether the profile's explicit allowlists are restricted to read-only research. */
 export function planResearchProfile(profile) {
-    return Boolean(profile
-        && Array.isArray(profile.tools)
-        && profile.tools.length > 0
-        && profile.tools.some(name => PLAN_RESEARCH_EVIDENCE_TOOLS.has(name))
-        && profile.tools.every(name => PLAN_RESEARCH_TOOLS.has(name))
-        && Array.isArray(profile.plugins)
-        && profile.plugins.every(name => PLAN_RESEARCH_PLUGINS.includes(name)));
+    return profileRefusal(profile) === null;
+}
+/**
+ * Evaluate the same effective intersection used for launch, including tool ownership removed by
+ * profile plugin narrowing. An explicit request is a strict override; omission inherits the safe
+ * profile/parent intersection.
+ */
+export function planResearchEligibility(profile, context, requested) {
+    const empty = { version: 1, tools: [], connectors: [], contributions: [] };
+    const profileProblem = profileRefusal(profile);
+    if (profileProblem)
+        return { eligible: false, refusal: profileProblem, capabilities: empty, unavailableTools: [] };
+    const parent = {
+        version: 1,
+        tools: [...context.frozenTools],
+        connectors: [],
+        contributions: [...context.contributions]
+    };
+    const narrowed = narrowForProfile(parent, profile, requested, context.descriptors);
+    const capabilities = {
+        ...narrowed.capabilities,
+        tools: narrowed.capabilities.tools.filter(name => PLAN_RESEARCH_TOOLS.has(name)),
+        connectors: []
+    };
+    if (requested) {
+        const effective = new Set(capabilities.tools);
+        const incompatible = [...new Set(requested.filter(name => !PLAN_RESEARCH_TOOLS.has(name)
+                || !profile.tools.includes(name)
+                || !context.frozenTools.includes(name)
+                || !effective.has(name)))];
+        if (incompatible.length) {
+            return {
+                eligible: false,
+                refusal: `Plan-mode tools override contains incompatible tool(s): ${incompatible.join(', ')}. Omit \`tools\` to inherit the selected profile's safe research intersection, or retry with only tools allowed by that profile, available in this parent run, and in the plan research set.`,
+                capabilities,
+                unavailableTools: narrowed.unavailable
+            };
+        }
+    }
+    if (!capabilities.tools.some(name => PLAN_RESEARCH_EVIDENCE_TOOLS.has(name))) {
+        const refusal = requested
+            ? `The tools override [${requested.join(', ')}] leaves no available research evidence tool for profile ${profile.name}. Omit \`tools\` to inherit the safe intersection, or retry with an available evidence tool from this profile.`
+            : `Profile ${profile.name} has no read-only research evidence tool after intersecting its allowlists with this run's frozen capabilities and plugin contributions. Choose a profile with an available evidence tool.`;
+        return { eligible: false, refusal, capabilities, unavailableTools: narrowed.unavailable };
+    }
+    return { eligible: true, refusal: null, capabilities, unavailableTools: narrowed.unavailable };
 }

package/dist/sdk/agents/profiles.d.ts

@@ -1,5 +1,8 @@
 import { type Effort } from "../core/effort.js";
+import { type PlanResearchContext } from "./planResearch.js";
 export declare const PROFILE_NAME: RegExp;
+/** Names a profile cannot take: `main` is how rosters show the agent a person talks to. */
+export declare const RESERVED_PROFILE_NAMES: readonly string[];
 export declare const PROFILE_COLORS: readonly ["blue", "green", "yellow", "red", "magenta", "cyan", "orange", "purple"];
 export type ProfileColor = (typeof PROFILE_COLORS)[number];
 export type ProfileSource = 'builtin' | 'global' | 'project' | 'variant';
@@ -71,7 +74,7 @@ export declare function removeProfile(root: string, cwd: string | null | undefin
 /** Where the profile list sits among the prompt sections: the slot a variant's subagents used. */
 export declare const PROFILE_SECTION_ORDER = 64;
 /** The prompt section that lists the profiles a run can start subagents from. */
-export declare function profileSection(root: string, cwd: string | null | undefined, variantDir?: string | null, planResearchOnly?: boolean): {
+export declare function profileSection(root: string, cwd: string | null | undefined, variantDir?: string | null, planResearchOnly?: boolean, researchContext?: PlanResearchContext): {
     id: string;
     title: string;
     body: string;

package/dist/sdk/agents/profiles.js

@@ -10,8 +10,11 @@ import { parse, serialize } from "../core/frontmatter.js";
 import { atomicWrite } from "../core/fs.js";
 import { subagentOf } from "../variant/materialise.js";
 import { BUILTIN_PROFILES } from "./builtin.js";
-import { planResearchProfile } from "./planResearch.js";
+import { planResearchEligibility, planResearchProfile } from "./planResearch.js";
 export const PROFILE_NAME = /^[a-z0-9][a-z0-9_-]*$/;
+/** Names a profile cannot take: `main` is how rosters show the agent a person talks to. */
+export const RESERVED_PROFILE_NAMES = ['main'];
+const reservedRefusal = (name) => `${name} is reserved for the main agent; choose another profile name.`;
 export const PROFILE_COLORS = ['blue', 'green', 'yellow', 'red', 'magenta', 'cyan', 'orange', 'purple'];
 /** Nearest folder above `cwd` that holds `.git`, or `cwd` itself. */
 export function projectRoot(cwd) {
@@ -65,6 +68,8 @@ export function formatVariant(variant) {
 export function parseProfile(text, name, source, path) {
     if (!PROFILE_NAME.test(name))
         throw invalid('A profile name uses lowercase letters, digits, - and _, and starts with a letter or digit.');
+    if (RESERVED_PROFILE_NAMES.includes(name))
+        throw invalid(reservedRefusal(name));
     const parsed = parse(text);
     if (!parsed)
         throw invalid('The profile needs a frontmatter block between --- lines.');
@@ -124,7 +129,7 @@ function variantDefinitions(variantDir) {
     if (!folder || !existsSync(folder))
         return [];
     return readdirSync(folder).sort().flatMap(name => {
-        const definition = subagentOf(variantDir, name);
+        const definition = RESERVED_PROFILE_NAMES.includes(name) ? null : subagentOf(variantDir, name);
         if (!definition)
             return [];
         return [{
@@ -175,6 +180,8 @@ export function createProfile(root, cwd, input) {
     const name = typeof input.name === 'string' ? input.name.trim() : '';
     if (!PROFILE_NAME.test(name))
         throw invalid('A profile name uses lowercase letters, digits, - and _, and starts with a letter or digit.');
+    if (RESERVED_PROFILE_NAMES.includes(name))
+        throw invalid(reservedRefusal(name));
     if (input.scope !== 'global' && input.scope !== 'project')
         throw invalid('scope must be global or project.');
     const dir = scopeDir(root, cwd, input.scope);
@@ -207,16 +214,20 @@ export function removeProfile(root, cwd, input) {
 /** Where the profile list sits among the prompt sections: the slot a variant's subagents used. */
 export const PROFILE_SECTION_ORDER = 64;
 /** The prompt section that lists the profiles a run can start subagents from. */
-export function profileSection(root, cwd, variantDir, planResearchOnly = false) {
+export function profileSection(root, cwd, variantDir, planResearchOnly = false, researchContext) {
     const { profiles } = listProfiles(root, cwd, variantDir);
-    const listed = planResearchOnly ? profiles.filter(planResearchProfile) : profiles;
+    const listed = planResearchOnly
+        ? profiles.filter(profile => researchContext
+            ? planResearchEligibility(profile, researchContext).eligible
+            : planResearchProfile(profile))
+        : profiles;
     return {
         id: 'subagents',
         title: 'Subagents',
         body: [
             planResearchOnly
-                ? 'Plan mode may start only a named profile listed here, for read-only research. Do not omit agent or use a profile not listed.'
-                : 'Delegate when it meaningfully reduces work: choose a substantial, bounded task that can proceed independently, such as unfamiliar cross-file research likely to take several searches or a self-contained implementation. Do a known-file lookup, one or two simple tool calls, a tiny edit or tightly coupled work yourself. Prefer a named profile: explorer for repository research, researcher for public-source research, and worker for a defined change it can own end to end; omit agent only when no profile fits. Each child starts without this conversation, so give it the goal, relevant context or paths, non-goals, expected result and acceptance or verification; use its own checklist for multi-step work. Prefer context-heavy research with concise evidence-backed findings. Parallelize only independent tasks and never assign overlapping edits. Return without waiting only when useful independent work remains; otherwise wait. You own integration, verification and the user-facing report. A profile can only narrow your tools.',
+                ? 'Plan mode may start only a named profile listed here, for read-only research. Do not omit agent or use a profile not listed. Omit the optional tools field to inherit the safe available intersection; specify it only to narrow further.'
+                : 'Delegate when it meaningfully reduces work: choose a substantial, bounded task that can proceed independently, such as unfamiliar cross-file research likely to take several searches or a self-contained implementation. Do a known-file lookup, one or two simple tool calls, a tiny edit or tightly coupled work yourself. Prefer a named profile: explorer for repository research, researcher for public-source research, and worker for a defined change it can own end to end; omit agent only when no profile fits. Each child starts without this conversation, so give it the goal, relevant context or paths, non-goals, expected result and acceptance or verification; use its own todo list for multi-step work. Prefer context-heavy research with concise evidence-backed findings. Parallelize only independent tasks and never assign overlapping edits. Return without waiting only when useful independent work remains; otherwise wait. You own integration, verification and the user-facing report. A profile can only narrow your tools.',
             ...(listed.length ? listed.map((profile) => `- ${profile.name} — ${profile.description}`) : ['- No eligible read-only research profiles are configured.'])
         ].join('\n'),
         budget: 6_000,

package/dist/sdk/capabilities/runSnapshot.js

@@ -6,11 +6,16 @@ const path = (root, runId) => join(root, 'runs', safeId(runId), 'capabilities.js
 function strings(value) {
     return Array.isArray(value) ? [...new Set(value.filter((item) => typeof item === 'string' && item.length > 0))] : [];
 }
+/** Tool names that were renamed; a pinned run keeps the current name so a continuation can use it. */
+const RENAMED_TOOLS = { checklist_write: 'todo_write' };
+function tools(value) {
+    return [...new Set(strings(value).map((name) => RENAMED_TOOLS[name] ?? name))];
+}
 export function capabilitySet(value) {
     if (!value || typeof value !== 'object' || value.version !== 1)
         throw invalid('A capability set must use version 1.');
     const record = value;
-    return { version: 1, tools: strings(record.tools), connectors: strings(record.connectors), contributions: strings(record.contributions) };
+    return { version: 1, tools: tools(record.tools), connectors: strings(record.connectors), contributions: strings(record.contributions) };
 }
 /** Writes a run's capability set once. A resumed or duplicate launch cannot replace it. */
 export function freezeRun(root, runId, caller, set) {
@@ -18,11 +23,12 @@ export function freezeRun(root, runId, caller, set) {
     const snapshot = {
         version: 1,
         caller: { agentId: caller.agentId ?? null, projectId: caller.projectId ?? null },
-        tools: strings(set.tools),
+        tools: tools(set.tools),
         connectors: strings(set.connectors),
         contributions: strings(set.contributions)
     };
-    const existing = existsSync(target) ? readJson(target) : null;
+    const stored = existsSync(target) ? readJson(target) : null;
+    const existing = stored ? { ...stored, tools: tools(stored.tools) } : null;
     if (existing) {
         if (JSON.stringify(existing) !== JSON.stringify(snapshot))
             throw new HarnessError('capabilities_frozen', 'This run already has a different frozen capability set.');
@@ -40,7 +46,7 @@ export function loadRun(root, runId) {
     return {
         version: 1,
         caller: { agentId: typeof caller.agentId === 'string' ? caller.agentId : null, projectId: typeof caller.projectId === 'string' ? caller.projectId : null },
-        tools: strings(record.tools),
+        tools: tools(record.tools),
         connectors: strings(record.connectors),
         contributions: strings(record.contributions)
     };

package/dist/sdk/commands/registry.d.ts

@@ -121,6 +121,13 @@ export declare const CORE_COMMANDS: readonly [{
     readonly group: "Inspect";
     readonly kind: "session";
     readonly methods: readonly ["sessions.export", "sessions.run"];
+}, {
+    readonly name: "todo";
+    readonly aliases: readonly ["checklist"];
+    readonly description: "Show the current todo list";
+    readonly group: "Inspect";
+    readonly kind: "session";
+    readonly methods: readonly ["runs.todo"];
 }, {
     readonly name: "trajectory";
     readonly args: "[run-id]";
@@ -173,15 +180,16 @@ export declare const CORE_COMMANDS: readonly [{
     readonly kind: "page";
 }, {
     readonly name: "plugins";
-    readonly description: "Switch plugins on or off and trust their code";
+    readonly description: "Manage local plugins, packages, trust and settings";
     readonly group: "Harness";
     readonly kind: "page";
-    readonly methods: readonly ["plugins.inventory"];
+    readonly methods: readonly ["plugins.list", "plugins.attach", "plugins.detach", "plugins.trust", "plugins.untrust", "plugins.configure", "plugins.install", "plugins.update", "plugins.remove", "hub.list"];
 }, {
     readonly name: "hub";
-    readonly description: "Browse and install reviewed skills, plugins and documents";
+    readonly description: "Browse the Community catalog and manage Hub installs";
     readonly group: "Harness";
     readonly kind: "page";
+    readonly methods: readonly ["hub.list", "hub.install", "hub.uninstall"];
 }, {
     readonly name: "components";
     readonly description: "Browse skills, prompts and rules for this Harness scope";

package/dist/sdk/commands/registry.js

@@ -18,6 +18,7 @@ export const CORE_COMMANDS = [
     { name: 'compact', args: '[instructions]', description: 'Compact the context', group: 'Session', kind: 'session', methods: ['sessions.run'] },
     { name: 'copy', description: 'Copy the last reply', group: 'Inspect', kind: 'local', methods: ['sessions.lastReply'] },
     { name: 'export', args: '[path.html|path.jsonl]', description: 'Export this branch to HTML or JSONL', group: 'Inspect', kind: 'session', methods: ['sessions.export', 'sessions.run'] },
+    { name: 'todo', aliases: ['checklist'], description: 'Show the current todo list', group: 'Inspect', kind: 'session', methods: ['runs.todo'] },
     { name: 'trajectory', args: '[run-id]', description: 'Inspect recorded runs for this session', group: 'Inspect', kind: 'page', methods: ['runs.list', 'runs.events'] },
     { name: 'reload', description: 'Reload trusted resources and keybindings', group: 'Harness', kind: 'session', methods: ['sessions.reload'] },
     { name: 'accounts', description: 'Sign in, switch, check and remove Pi accounts', group: 'Harness', kind: 'page', methods: ['accounts.list'] },
@@ -27,8 +28,8 @@ export const CORE_COMMANDS = [
     { name: 'connections', description: 'Manage local and remote MCP connections', group: 'Harness', kind: 'page' },
     { name: 'mcp', description: 'Open Connections in the Harness browser', group: 'Harness', kind: 'page' },
     { name: 'tools', description: 'Inspect available tools, owners and approvals', group: 'Harness', kind: 'page' },
-    { name: 'plugins', description: 'Switch plugins on or off and trust their code', group: 'Harness', kind: 'page', methods: ['plugins.inventory'] },
-    { name: 'hub', description: 'Browse and install reviewed skills, plugins and documents', group: 'Harness', kind: 'page' },
+    { name: 'plugins', description: 'Manage local plugins, packages, trust and settings', group: 'Harness', kind: 'page', methods: ['plugins.list', 'plugins.attach', 'plugins.detach', 'plugins.trust', 'plugins.untrust', 'plugins.configure', 'plugins.install', 'plugins.update', 'plugins.remove', 'hub.list'] },
+    { name: 'hub', description: 'Browse the Community catalog and manage Hub installs', group: 'Harness', kind: 'page', methods: ['hub.list', 'hub.install', 'hub.uninstall'] },
     { name: 'components', description: 'Browse skills, prompts and rules for this Harness scope', group: 'Harness', kind: 'page' },
     { name: 'settings', description: 'Session, terminal and browser settings', group: 'Harness', kind: 'page' },
     { name: 'doctor', description: 'Check account, model, tools and runtime readiness', group: 'Harness', kind: 'page', methods: ['doctor.start', 'doctor.read'] },

package/dist/sdk/core/shell.d.ts

@@ -0,0 +1,20 @@
+export type ShellKind = 'bash' | 'powershell';
+export interface Shell {
+    kind: ShellKind;
+    executable: string;
+    /** Arguments placed before the command text. */
+    args: readonly string[];
+}
+export interface ShellLookup {
+    env?: NodeJS.ProcessEnv;
+    /** Whether a file exists at an absolute path. */
+    exists?: (path: string) => boolean;
+    /** The first match for an executable name on the search path. */
+    onPath?: (name: string) => string | null;
+}
+/** The shell for this machine, resolved once. Null when none was found. */
+export declare function hostShell(): Shell | null;
+export declare function resolveShell(platform: NodeJS.Platform, lookup?: ShellLookup): Shell | null;
+/** The full argument list that runs `command` in `shell`. */
+export declare function shellArguments(shell: Shell, command: string): string[];
+export declare function shellLabel(shell: Shell): string;

package/dist/sdk/core/shell.js

@@ -0,0 +1,73 @@
+// The shell the Bash tool runs commands in. POSIX systems use Bash. Windows uses Git Bash when it
+// is installed and PowerShell otherwise, so a fresh machine can run commands with nothing extra.
+import { accessSync, constants, statSync } from 'node:fs';
+import { win32 } from 'node:path';
+import { findBinary } from "./path.js";
+const POWERSHELL_ARGS = ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-Command'];
+// Windows PowerShell writes the console code page by default; ask for UTF-8 like Pi does.
+const POWERSHELL_UTF8 = 'try { [Console]::OutputEncoding=[System.Text.Encoding]::UTF8 } catch {}\n';
+let cached;
+/** The shell for this machine, resolved once. Null when none was found. */
+export function hostShell() {
+    if (cached === undefined)
+        cached = resolveShell(process.platform);
+    return cached;
+}
+export function resolveShell(platform, lookup = {}) {
+    const env = lookup.env ?? process.env;
+    const exists = lookup.exists ?? isFile;
+    const onPath = lookup.onPath ?? findBinary;
+    if (platform !== 'win32') {
+        const executable = ['/bin/bash', '/usr/bin/bash'].find((candidate) => exists(candidate));
+        return executable ? { kind: 'bash', executable, args: ['-c'] } : null;
+    }
+    const gitBash = [env.ProgramFiles, env['ProgramFiles(x86)']]
+        .filter((folder) => Boolean(folder))
+        .map((folder) => win32.join(folder, 'Git', 'bin', 'bash.exe'))
+        .find((candidate) => exists(candidate));
+    if (gitBash)
+        return { kind: 'bash', executable: gitBash, args: ['-c'] };
+    const bashOnPath = onPath('bash.exe');
+    if (bashOnPath && !isWslLauncher(bashOnPath, env))
+        return { kind: 'bash', executable: bashOnPath, args: ['-c'] };
+    const existing = (folder, ...parts) => {
+        if (!folder)
+            return null;
+        const candidate = win32.join(folder, ...parts);
+        return exists(candidate) ? candidate : null;
+    };
+    // PowerShell 7 first; Windows PowerShell ships with every supported Windows version.
+    const powershell = onPath('pwsh.exe')
+        ?? existing(env.ProgramFiles, 'PowerShell', '7', 'pwsh.exe')
+        ?? onPath('powershell.exe')
+        ?? existing(env.SystemRoot, 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe');
+    return powershell ? { kind: 'powershell', executable: powershell, args: POWERSHELL_ARGS } : null;
+}
+/** The full argument list that runs `command` in `shell`. */
+export function shellArguments(shell, command) {
+    return [...shell.args, shell.kind === 'powershell' ? `${POWERSHELL_UTF8}${command}` : command];
+}
+export function shellLabel(shell) {
+    if (shell.kind === 'powershell')
+        return 'PowerShell';
+    return /\\git\\/iu.test(shell.executable) ? 'Git Bash' : 'Bash';
+}
+// System32\bash.exe starts WSL, a separate Linux system that does not see Windows paths the same
+// way and needs its command on stdin. It is not a usable Bash for this tool.
+function isWslLauncher(path, env) {
+    const normalized = win32.normalize(path).toLowerCase();
+    const systemRoot = env.SystemRoot;
+    if (systemRoot) {
+        return ['System32', 'Sysnative'].some((folder) => normalized === win32.join(systemRoot, folder, 'bash.exe').toLowerCase());
+    }
+    return /^[a-z]:\\windows\\(?:system32|sysnative)\\bash\.exe$/u.test(normalized);
+}
+function isFile(path) {
+    try {
+        accessSync(path, constants.F_OK);
+        return statSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+}

package/dist/sdk/core/workspaceBashTool.d.ts

@@ -1,4 +1,20 @@
+import type { BashOperations } from '@earendil-works/pi-coding-agent';
+import { type Shell } from "./shell.js";
 /** Quotes command text and escapes terminal control/format characters for approval details. */
 export declare function formatBashCommandForApproval(command: string): string;
+interface ShellToolFactories<T> {
+    createBashTool: (cwd: string, options: {
+        operations: BashOperations;
+    }) => T;
+    createPowerShellTool: (cwd: string, options: {
+        operations: BashOperations;
+    }) => T;
+}
+/**
+ * The `bash` tool for this machine. The capability keeps the name `bash` on every platform; on a
+ * Windows machine without Git Bash it runs PowerShell and carries PowerShell's description.
+ */
+export declare function createWorkspaceShellTool<T>(pi: ShellToolFactories<T>, cwd: string, operations: BashOperations, shell?: Shell | null, platform?: NodeJS.Platform): T;
 /** Adds the explicit pre-execution escape request to Pi's native Bash tool. */
-export declare function withWorkspaceWriteScope<T>(tool: T): T;
+export declare function withWorkspaceWriteScope<T>(tool: T, note?: string): T;
+export {};

package/dist/sdk/core/workspaceBashTool.js

@@ -1,17 +1,31 @@
 import { Type } from 'typebox';
 import { COMMAND_TIMEOUT_CEILING_SECONDS, COMMAND_TIMEOUT_MAX_SECONDS, DEFAULT_COMMAND_TIMEOUT_SECONDS, resolveCommandTimeout } from "./commandBudget.js";
+import { hostShell, shellLabel } from "./shell.js";
 import { runWithWorkspaceWriteScope } from "./workspaceSandbox.js";
 /** Quotes command text and escapes terminal control/format characters for approval details. */
 export function formatBashCommandForApproval(command) {
     return JSON.stringify(command).replace(/[\u007f-\u009f\u200b-\u200f\u2028-\u202e\u2060-\u206f\ufeff]/gu, (character) => `\\u${character.charCodeAt(0).toString(16).padStart(4, '0')}`);
 }
+/**
+ * The `bash` tool for this machine. The capability keeps the name `bash` on every platform; on a
+ * Windows machine without Git Bash it runs PowerShell and carries PowerShell's description.
+ */
+export function createWorkspaceShellTool(pi, cwd, operations, shell = hostShell(), platform = process.platform) {
+    const native = shell?.kind === 'powershell'
+        ? { ...pi.createPowerShellTool(cwd, { operations }), name: 'bash' }
+        : pi.createBashTool(cwd, { operations });
+    const note = platform === 'win32' && shell
+        ? ` On this machine commands run in ${shellLabel(shell)}. Windows has no workspace sandbox, so each command asks for approval unless Full Permission is on, and plan mode cannot run commands.`
+        : '';
+    return withWorkspaceWriteScope(native, note);
+}
 /** Adds the explicit pre-execution escape request to Pi's native Bash tool. */
-export function withWorkspaceWriteScope(tool) {
+export function withWorkspaceWriteScope(tool, note = '') {
     const native = tool;
     const execute = native.execute.bind(tool);
     return {
         ...tool,
-        description: `${native.description} Workspace writes are the default. Set workspaceWriteScope to "outside" to request approval before broader writes. Commands run for ${DEFAULT_COMMAND_TIMEOUT_SECONDS} seconds unless timeout says otherwise; above ${COMMAND_TIMEOUT_CEILING_SECONDS} seconds a reason is required, and ${COMMAND_TIMEOUT_MAX_SECONDS} seconds is the maximum.`,
+        description: `${native.description}${note} Workspace writes are the default. Set workspaceWriteScope to "outside" to request approval before broader writes. Commands run for ${DEFAULT_COMMAND_TIMEOUT_SECONDS} seconds unless timeout says otherwise; above ${COMMAND_TIMEOUT_CEILING_SECONDS} seconds a reason is required, and ${COMMAND_TIMEOUT_MAX_SECONDS} seconds is the maximum.`,
         parameters: Type.Object({
             command: Type.String({ description: 'Shell command to execute' }),
             timeout: Type.Optional(Type.Number({ description: `Timeout in seconds (default ${DEFAULT_COMMAND_TIMEOUT_SECONDS})` })),

package/dist/sdk/core/workspaceSandbox.d.ts

@@ -1,4 +1,5 @@
 import type { BashOperations } from '@earendil-works/pi-coding-agent';
+import { type Shell } from "./shell.js";
 /** `read-only` (plan mode) permits no workspace writes, no network and no outside processes. */
 export type WorkspaceWriteScope = 'workspace' | 'outside' | 'read-only';
 export declare function runWithWorkspaceWriteScope<T>(scope: WorkspaceWriteScope, action: () => T): T;
@@ -21,11 +22,20 @@ export interface WorkspaceBashOptions {
     workspaceWriteScope?: () => WorkspaceWriteScope | undefined;
     /** Exposed for platform-specific tests; production uses the current operating system. */
     platform?: NodeJS.Platform;
+    /** Exposed for tests; production uses the machine's shell (`hostShell`). */
+    shell?: () => Shell | null;
 }
+/** Why a Windows command asks first: Windows has no write-boundary sandbox the harness can use. */
+export declare const WINDOWS_UNSANDBOXED_REASON = "Windows has no workspace write-boundary sandbox, so this command would run without one. It will not run until this one-call request is approved.";
 export interface WorkspaceSandboxCommand {
     executable: string;
     args: string[];
     marker: string;
 }
+/**
+ * The operating system's write-boundary sandbox for this platform, or null when it is not
+ * installed. Bash cannot run without it, so readiness diagnostics report it before a command runs.
+ */
+export declare function workspaceSandboxBackend(platform?: NodeJS.Platform): string | null;
 export declare function workspaceSandboxCommand(platform: NodeJS.Platform, workspaceRoot: string, cwd: string, command: string, additionalWriteRoots?: readonly string[], readOnlyTempRoot?: string | null): WorkspaceSandboxCommand;
 export declare function createWorkspaceBashOperations(workspaceRoot: string | (() => string | null), options?: WorkspaceBashOptions): BashOperations;