@hydraharness/harness-tool-pwsh 0.1.1-rc.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,127 @@
+# @hydraharness/harness-tool-pwsh
+
+The model-facing `pwsh` tool registered over the `ctx.shell` executor seam. Intended for Windows compositions where a PowerShell executor (e.g. `@hydraharness/harness-pwsh-local`) backs `ctx.shell`; the tool contract is PowerShell-dialect: native `C:\...` paths and `$env:NAME` variables. Behavior mirrors `@hydraharness/harness-tool-bash` call-for-call — foreground and `run_in_background` execution through the generic job runtime, the managed `HYDRA_*` environment through the shared `shell-env` registry, the sandbox denial rendering with the same-turn `sandbox_permissions` escalation surface, and the bash marker/truncation rendering story (a clean exit produces no marker).
+
+Requires a loaded executor implementation and the `shell-env` plugin; the tool stays pending until both exist (`inject: ['tools', 'bash', 'systemPrompt', 'bashEnv']`).
+
+The package root exposes only the Cordis plugin contract (`name`, `inject`, `Config`, `apply`); result rendering (`src/render.ts`) and background-job adaptation (`src/background.ts`) mirror the bash tool's structure and stay reachable through the package's `./src/*` export.
+
+The plugin also contributes the `tool:pwsh` prompt section (order 105): non-zero exits are reported as `[exit code: N]` markers, and Windows interruption settles as exit 1 without a signal marker.
+
+## Tools
+
+### `pwsh`
+
+| Arg | Type | Notes |
+|---|---|---|
+| `command` | string (required) | Run via `pwsh -Command`. No state persists between calls — use `workdir`, not `cd`. |
+| `description` | string (required) | One-line, active-voice summary of the command (5-10 words), for UI/log display only — no effect on execution. |
+| `timeoutMs` | number | Timeout override in milliseconds. The executor applies its configured default and cap. |
+| `workdir` | string | Working directory for this call. Defaults to the calling agent's session cwd (`session.header.cwd`) so each session runs in its own workspace; a relative `workdir` is resolved against that same identity. |
+| `changed_paths` | string[] | Optional explicit paths changed by a successful foreground command; used only to refresh workspace instructions, never inferred from PowerShell text. |
+| `run_in_background` | boolean | Return a job id immediately; no timeout applies. |
+| `sandbox_permissions` | string enum | Advertised only when a sandboxing executor is mounted (`ctx.shell.sandboxMode` defined). The wider sandbox mode for a one-shot retry of a command the sandbox just denied — the narrowest wider mode that suffices, requiring `justification` and user approval through `ctx.approval` BEFORE execution. A non-widening or unapprovable request fails closed without running anything. |
+| `justification` | string | Required with `sandbox_permissions`: one sentence for the user explaining why this exact command needs the wider access. |
+
+`command`, `workdir`, and `timeoutMs` are resolved against the executor's config defaults via `ctx.shell.resolve()` before execution. The workdir default is applied in the tool layer from the calling agent's `session.header.cwd` BEFORE `resolve()` — the per-session cwd must come from `exec.agent`, since N sessions share one executor; only when no session cwd is available does the executor fall back to its own config / `process.cwd()`.
+
+### Managed shell environment
+
+Every foreground and background model pwsh call receives a freshly collected trusted `HYDRA_*` environment through the shared [`@hydraharness/harness-shell-env`](../shell-env/) registry: `HYDRA_HOME` (the absolute Harness home), `HYDRA_SHELL=1`, the agent's `HYDRA_SESSION_ID`, and `HYDRA_SESSION_JSONL` when the active persistence backend locates one. Plugins contributing `HYDRA_*` facts to `ctx.shellEnv` apply to pwsh calls exactly as they do to bash calls. The snapshot passes through the dedicated `ShellExecRequest.hydraEnv` channel; `process.env` is never modified. The description teaches the generic `$env:HYDRA_*` convention rather than naming persistence-specific variables.
+
+Result text contains stdout, an optional `[stderr]` section, then applicable truncation, sandbox-denial (with the same-turn escalation hint when the composition advertises escalation), timeout, signal, and exit markers. A clean exit (0, no signal) produces no marker; an empty body renders as `(no output)`. Truncation links a safe complete spill file or reports it unavailable. Timeout is reported independently of final exit status; nonzero exit remains a model-interpreted result rather than `isError`. Windows reports forced termination as exit 1 without a signal, so `[killed by signal: …]` is POSIX-only there. Only infrastructure failures — spawn errors and aborts (`tool call aborted`) — produce `isError`.
+
+The canonical success is `{ kind: 'foreground', ...ShellRunResult }` for a completed foreground process (with the executor's `sandbox` facts — `mode`/`denied`, optional `enforcement`/`runnerFailed` — projected when present) or `{ kind: 'background', jobId }` for a published task. The renderer preserves exactly `started background job <id>` for background acks; programmatic consumers use the typed fields without parsing the rendered text.
+
+A foreground call may declare `changed_paths`. After a successful foreground result, `agent-instructions` resolves those exact strings against the effective workdir and uses them as context-refresh hints; it never infers paths from PowerShell text. Failed, aborted, and background calls do not refresh instructions, and these hints are not mutation records.
+
+When `run_in_background` is true, this plugin preflights `ctx.jobs.start()` before spawning, registers the calling agent as owner, and adapts the returned `ShellProcess` handle into generic cancel/done/incremental-output hooks. The job runtime owns ids, cross-session isolation, completion notices, waiting, and disposal cleanup; this plugin only maps pwsh exit facts into job output and outcome detail. `enableRunInBackground: false` removes the parameter and rejects a forced background call at execution time.
+
+## UI presentation
+
+The tool owns its `presentCall`/`presentResult` render intent. A foreground call is a `terminal` card carrying command, description, and optional cwd; a `run_in_background` call is a `generic` card with the raw command, mirroring the bash tool's background presentation. A completed foreground result is a `terminal` card too: the exit marker becomes the card's exit-status pill (`exitCode`/`signal`), and the marker-free body is the card's output — exactly the bash tool's terminal-card story, via the shared exit-status parse from `@hydraharness/harness-shell`. Background acks and execution errors stay `generic` cards with the rendered output in a `console` fence. These presenters are pure and replay-safe.
+
+## Model Experience
+
+### System prompt
+
+#### What the model sees
+
+Every request in this plugin's registration scope contains the pwsh guidance below. Scoped tool restrictions can hide the schema without removing this independently registered section.
+
+##### Pwsh guidance
+
+```markdown
+Non-zero exits are reported as `[exit code: N]` markers; investigate failures before moving on. On Windows a killed process settles as `[exit code: 1]` without a signal marker; treat a bare exit 1 after an interruption as a termination, not a command failure.
+```
+
+#### Token effect
+
+Small fixed input cost per request while the plugin is active.
+
+#### KV Cache effect
+
+Prefix-stable while the registration scope and prompt text are unchanged. Plugin activation or disposal may invalidate reuse from this prompt section.
+
+### Tool schemas
+
+#### What the model sees
+
+The model sees the generated [`pwsh` schema](../../../docs/tool-catalog.md#hydraharness-tool-pwsh). Agent-scoped tool restrictions can remove the definition for that agent.
+
+#### Token effect
+
+Fixed schema cost on every request where the tool is visible.
+
+#### KV Cache effect
+
+Prefix-stable while visibility and the tool definition are unchanged. A restriction or config change may invalidate reuse from the first changed token.
+
+### Foreground result
+
+#### What the model sees
+
+The renderer emits the data-dependent stdout tail, then optional `[stderr]` and the stderr tail. Conditional lines are exactly `[output truncated; full output: <path>]`, `[sandbox: file access denied under <mode> mode]` plus the escalation hint `[sandbox: escalation available — …]` (only when the composition advertises escalation), `[timed out after <timeoutMs>ms]`, `[killed by signal: <signal>]`, and `[exit code: <exitCode>]` (nonzero exits only); an empty body renders as `(no output)`.
+
+#### Token effect
+
+Zero result tokens before a call. Output is bounded per stream, while each emitted line remains in history until compaction.
+
+#### KV Cache effect
+
+Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
+
+### Background result
+
+#### What the model sees
+
+A background start renders exactly `started background job <id>`; subsequent reads and status flow through the generic `job_output`/`job_kill` tools, including the lossy-read spill notice when in-memory truncation dropped unread bytes.
+
+#### Token effect
+
+The ack is a fixed short line; job output is bounded per read.
+
+#### KV Cache effect
+
+Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
+
+### Tool errors
+
+#### What the model sees
+
+Validation and infrastructure failures are normalized as `Error: <message>`. This package's stable messages are `invalid command: expected a non-empty string`, `invalid description: expected a non-empty string`, `invalid timeoutMs: expected a positive number, got <value>`, `invalid escalation: sandbox_permissions requires a justification`, `invalid escalation: justification is only valid together with sandbox_permissions`, `invalid justification: expected a non-empty sentence`, `sandbox_permissions is not available in this composition (no sandboxing executor to escalate)`, the shared escalation failures (not strictly wider / no approval service / no agent to route / no approval channel / user rejected / was cancelled), `run_in_background is disabled for this deployment (enableRunInBackground: false)`, `background jobs unavailable: load @hydraharness/harness-jobs and @hydraharness/harness-tool-jobs`, and `tool call aborted`.
+
+#### Token effect
+
+Only the failing call adds these retained tokens; an aborted call adds no command output.
+
+#### KV Cache effect
+
+Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
+
+## Known Limitations and Deferred Work
+
+- **Language mode and named-pipe capture under the Windows sandbox** — under the [Windows ACL sandbox](../../sandbox/sandbox-windows-acl/README.md), read-only pwsh starts in ConstrainedLanguage because its temp write denial makes PowerShell's AppLocker probe fail closed: `Add-Type`, non-core .NET statics (`[System.IO.*]::`, `[math]::`), COM objects, and reflection fail with "only core types" errors, and the mode cannot be lifted from inside. Workspace-write's private temp lets the probe complete, so it stays in FullLanguage unless host policy says otherwise. Both confined modes deny named-pipe opens, so a piped-stdio spawn inside a confined command fails with EPERM. The tool description teaches both contracts to the model; the backend README owns the full limitations.
+- **No persistent shell** — every call starts a fresh `pwsh -Command`; the persistent-shell counterpart is [`@hydraharness/harness-tool-pwsh-persistent`](../tool-pwsh-persistent/README.md), which keeps one owner-scoped pwsh alive across calls on Windows (ConPTY) and POSIX hosts with pwsh.
+- **PowerShell-dialect contract** — the model must write PowerShell (native paths, `$env:` variables), not bash; there is no dialect translation.
+- **Session-cwd identity is not canonicalized** — the workdir base is the session header cwd as-is, unlike the bash tool's sandbox-root-canonicalized identity. Under a confining executor the policy's workspace root IS canonicalized (by the shared policy service), so the workdir and the confinement root can diverge when the raw session cwd differs from its canonical form — a parity gap deferred to the shared shell-tool base extraction.

package/lib/index.js

@@ -0,0 +1,458 @@
+import { isAbsolute, resolve } from "node:path";
+import z from "@hydraharness/schemastery";
+import { TOOL_ABORTED, defineTool } from "@hydraharness/harness-tools";
+import { HarnessError } from "@hydraharness/harness-llm";
+import { ESCALATION_TARGETS, approveEscalation, escalationHintMarker, sandboxDenialMarker, validateEscalationArgs } from "@hydraharness/harness-sandbox";
+import { parseExitStatus } from "@hydraharness/harness-shell";
+//#region lib/types/background.js
+/**
+* Generic-task adaptation for background pwsh process handles — the shell-agnostic
+* twin of `@hydraharness/harness-tool-bash`'s background adaptation.
+*
+* @module @hydraharness/harness-tool-pwsh/background
+*/
+/**
+* Map a settled background process onto the generic task-outcome vocabulary:
+* `killed` stays `killed` (detail: the signal when one is known), everything
+* else is `completed` with the exit code as detail. A nonzero command exit is
+* reported, not failed, exactly like the foreground rendering.
+* @param proc - the settled process handle.
+* @returns the outcome for the `ctx.jobs` registration.
+*/
+function processOutcome(proc) {
+	if (proc.status === "killed") return {
+		status: "killed",
+		detail: proc.signal !== null ? `signal: ${proc.signal}` : "killed before exit"
+	};
+	return {
+		status: "completed",
+		detail: `exit code: ${proc.exitCode ?? 0}`
+	};
+}
+//#endregion
+//#region lib/types/render.js
+/**
+* Model-facing result rendering for the pwsh tool — the PowerShell twin of
+* `@hydraharness/harness-tool-bash`'s renderer: stdout, a marked stderr section, sandbox
+* denial/runner-failure markers (with the same-turn escalation hint), and
+* truncation notices with spill paths, then exit-status markers. Non-zero
+* exits are reported, not errored — the model decides how to react; only
+* infrastructure failures (spawn errors, aborts) surface as isError
+* results.
+*
+* @module @hydraharness/harness-tool-pwsh/render
+*/
+/** Append the truncation notice (with the full-output spill path) to a stream's text. */
+function streamText(output) {
+	if (!output.truncated) return output.text;
+	return `${output.text}\n[output truncated; full output: ${output.spillPath ?? "(unavailable)"}]`;
+}
+/**
+* Shape one finished run into the text the model sees: stdout, then a marked
+* stderr section, then exit-status markers, matching the bash tool's story —
+* a clean exit (0, no signal) produces no marker.
+* @param result - the completed foreground run from the executor.
+* @param escalationModes - the escalation targets this composition advertises;
+*   non-empty adds the same-turn escalation hint after a denial marker
+*   (default `[]`: no hint).
+* @returns the model-facing text: output body (or `(no output)`), then any timeout/signal/exit markers, each on its own line.
+*/
+function renderPwshResult(result, escalationModes = []) {
+	const out = streamText(result.stdout);
+	const err = streamText(result.stderr);
+	let body = out;
+	if (err.length > 0) {
+		if (body.length > 0 && !body.endsWith("\n")) body += "\n";
+		body += `[stderr]\n${err}`;
+	}
+	if (body.length === 0) body = "(no output)";
+	const markers = [];
+	if (result.sandbox?.denied) {
+		markers.push(sandboxDenialMarker(result.sandbox.mode));
+		if (escalationModes.length > 0) markers.push(escalationHintMarker("command"));
+	}
+	if (result.timedOut) markers.push(`[timed out after ${result.timeoutMs}ms]`);
+	if (result.signal !== null) markers.push(`[killed by signal: ${result.signal}]`);
+	else if (result.exitCode !== 0) markers.push(`[exit code: ${result.exitCode}]`);
+	if (markers.length === 0) return body;
+	if (!body.endsWith("\n")) body += "\n";
+	return body + markers.join("\n");
+}
+/**
+* Shape one background-process read into the `job_output` delta the model
+* sees: the incremental delta, plus the lossy-read notice (with full-stream
+* spill paths) when in-memory truncation dropped unread bytes.
+* @param read - one incremental read from the process handle.
+* @param sandbox - settled sandbox facts, when this was a confined process.
+* @param escalationModes - escalation targets advertised by this composition.
+* @returns the delta text with any loss or sandbox notice appended.
+*/
+function renderPwshProcessRead(read, sandbox, escalationModes = []) {
+	const notices = [];
+	if (read.lossy) {
+		const paths = [read.stdoutSpillPath, read.stderrSpillPath].filter((path) => path !== void 0);
+		notices.push(`[some output was dropped from memory; full output: ${paths.length > 0 ? paths.join(", ") : "(unavailable)"}]`);
+	}
+	if (sandbox?.runnerFailed) notices.push(`[sandbox: the sandbox runner itself failed under ${sandbox.mode} mode — the command did not run; this is a sandbox problem, not a command failure]`);
+	else if (sandbox?.denied) {
+		notices.push(sandboxDenialMarker(sandbox.mode));
+		if (escalationModes.length > 0) notices.push(escalationHintMarker("command"));
+	}
+	if (notices.length === 0) return read.delta;
+	return `${read.delta}${read.delta.length > 0 && !read.delta.endsWith("\n") ? "\n" : ""}${notices.join("\n")}`;
+}
+//#endregion
+//#region lib/types/index.js
+/**
+* Model-facing PowerShell Consumer of the `ctx.shell` capability seam. Intended for
+* Windows compositions where a PowerShell executor (e.g.
+* `@hydraharness/harness-pwsh-local`) backs `ctx.shell`; the tool contract is
+* PowerShell-dialect: native `C:\...` paths and `$env:NAME` variables.
+*
+* Behavior mirrors `@hydraharness/harness-tool-bash` call-for-call: foreground and
+* `run_in_background` execution (background handles register with the
+* generic `ctx.jobs` runtime), the managed `HYDRA_*` environment through the
+* shared `shell-env` registry, the per-call sandbox policy resolution (the
+* calling session's mode and cwd travel to the confining executor), the
+* sandbox-denial rendering with the same-turn escalation surface
+* (`sandbox_permissions` + `justification` resolved through
+* `ctx.approval`), and the bash marker/truncation rendering story. UI
+* presentation mirrors the bash tool's too: a completed foreground call is
+* a terminal card with the parsed exit-status pill, using the shared
+* exit-status parse from `@hydraharness/harness-shell`.
+*
+* @module @hydraharness/harness-tool-pwsh
+*/
+const name = "tool-pwsh";
+const inject = [
+	"tools",
+	"shell",
+	"systemPrompt",
+	"shellEnv"
+];
+/** Runtime configuration schema for the pwsh tool plugin. */
+const Config = z.object({ enableRunInBackground: z.boolean().default(true) });
+function validatePwshArgs(args) {
+	if (args.command.trim().length === 0) throw new Error("invalid command: expected a non-empty string");
+	if (args.description.trim().length === 0) throw new Error("invalid description: expected a non-empty string");
+	if (args.timeoutMs !== void 0 && (!Number.isFinite(args.timeoutMs) || args.timeoutMs <= 0)) throw new Error(`invalid timeoutMs: expected a positive number, got ${JSON.stringify(args.timeoutMs)}`);
+	validateEscalationArgs(args.sandbox_permissions, args.justification);
+	if (args.changed_paths?.some((path) => path.length === 0)) throw new Error("invalid changed_paths: expected non-empty file paths");
+}
+function pwshDescription(backgroundEnabled, escalationModes) {
+	const base = "Execute a PowerShell command (`pwsh -Command`) and return its stdout/stderr. Each call runs in a fresh pwsh process: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Paths use native Windows form (`C:\\...`); read environment variables with `$env:NAME`. Non-zero exits are reported as `[exit code: N]`. Current harness environment facts are exposed through managed `$env:HYDRA_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under <mode> mode]` — a policy denial, not a bug in the command; do not retry another way. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. On Windows a force-killed command settles as `[exit code: 1]` without a signal marker — treat it as an interruption, not a command failure. " + (backgroundEnabled ? "Set `run_in_background: true` for long-running commands: the call returns a job id immediately; read its output with `job_output` and stop it with `job_kill`." : "Background execution is not available; long-running commands must finish within the timeout.");
+	if (escalationModes.length === 0) return base;
+	return base + " Under the Windows sandbox, read-only pwsh runs in PowerShell ConstrainedLanguage mode, while workspace-write stays in FullLanguage unless host policy says otherwise. In read-only, prefer cmdlets and core types (`[string]`, `[datetime]`, `[regex]`, `[guid]`); .NET static calls (`[System.IO.*]::`, `[math]::`), `Add-Type`, COM objects, and reflection fail with \"only core types\" errors. `-f` formatting, property access, and core cmdlets work. In both confined modes, programs cannot open named pipes, so a command that captures another program's output through piped stdio (Node.js `child_process.spawn`/`exec` with the default `stdio: 'pipe'`) fails with EPERM, while `stdio: 'inherit'` and `stdio: 'ignore'` spawns work and PowerShell's own pipelines are unaffected. That EPERM is the documented boundary: do not retry the command another way — escalate the exact command once or restructure it to avoid capturing output. Attempting a command the sandbox may deny is safe and expected: run it and read the marker rather than assuming the denial. When a command is denied and a wider mode would let it succeed, escalate immediately in the same turn — the one sanctioned exception to a denial: retry the exact same command once with `sandbox_permissions` (the narrowest wider mode that suffices) plus a one-sentence `justification`. Do not detour through chat to ask permission first — the approval prompt raised by that retry is how the user consents. If the session states approval prompts are disabled, there is no exception: a denial is final — do not set `sandbox_permissions`. Never escalate speculatively: ground the request in a real denial — normally the one this command just hit; escalating up front is fine only when this session already denied the same access. A rejected escalation is final for that command — stop and explain, never work around it — but it does not forbid attempting or escalating other commands later.";
+}
+/**
+* Resolve an explicit workdir first, making a relative one session-workspace-relative;
+* otherwise use the session header cwd and leave executor defaulting as the fallback.
+*/
+function resolveWorkdir(modelWorkdir, exec) {
+	const headerCwd = exec.agent?.session.header.cwd;
+	if (modelWorkdir === void 0) return headerCwd;
+	if (headerCwd !== void 0 && !isAbsolute(modelWorkdir)) return resolve(headerCwd, modelWorkdir);
+	return modelWorkdir;
+}
+/** Detach the executor DTO from readonly Service Definition types into plain JSON data. */
+function canonicalPwshResult(result) {
+	const output = (stream) => ({
+		text: stream.text,
+		truncated: stream.truncated,
+		...stream.spillPath !== void 0 ? { spillPath: stream.spillPath } : {}
+	});
+	return {
+		kind: "foreground",
+		exitCode: result.exitCode,
+		signal: result.signal,
+		timedOut: result.timedOut,
+		aborted: result.aborted,
+		timeoutMs: result.timeoutMs,
+		stdout: output(result.stdout),
+		stderr: output(result.stderr),
+		...result.sandbox !== void 0 ? { sandbox: {
+			mode: result.sandbox.mode,
+			denied: result.sandbox.denied,
+			...result.sandbox.enforcement !== void 0 ? { enforcement: result.sandbox.enforcement } : {},
+			...result.sandbox.runnerFailed !== void 0 ? { runnerFailed: result.sandbox.runnerFailed } : {}
+		} } : {}
+	};
+}
+/** Canonical background-handle properties shared by the pwsh output union. */
+const BACKGROUND_OUTPUT_PROPERTIES = {
+	kind: {
+		type: "string",
+		required: true,
+		const: "background"
+	},
+	jobId: {
+		type: "string",
+		required: true
+	}
+};
+function apply(ctx, config = {}) {
+	const backgroundEnabled = config.enableRunInBackground ?? true;
+	const defaultMode = ctx.shell.sandboxMode;
+	const escalationModes = defaultMode === void 0 ? [] : ESCALATION_TARGETS;
+	const sandboxPolicy = defaultMode === void 0 ? void 0 : ctx.get("sandboxPolicy");
+	if (defaultMode !== void 0 && sandboxPolicy === void 0) throw new Error("tool-pwsh: the mounted bash executor confines but ctx.sandboxPolicy is missing");
+	/** Resolve the complete standing policy for this call when a confining executor is mounted. */
+	const resolveSandboxPolicy = (exec) => sandboxPolicy?.resolve(exec.agent === void 0 ? {} : { session: exec.agent.session });
+	/**
+	* Resolve a sandbox-escalation request through `ctx.approval` BEFORE
+	* anything executes, delegating the shared fail-closed sequence (strict
+	* widening, channel resolution, outcome mapping) to
+	* {@link approveEscalation}. This tool contributes only the composition
+	* guard (the fields are unadvertised without a sandboxing executor, yet
+	* schema validation checks advertised keys only, so an unadvertised
+	* `sandbox_permissions` still reaches execute) and the approval
+	* ingredients. The shared policy resolver is required whenever the
+	* executor advertises confinement, so a split composition fails at
+	* tool-plugin load.
+	*/
+	const approvePwshEscalation = (mode, justification, exec, standingPolicy) => {
+		if (escalationModes.length === 0) throw new Error("sandbox_permissions is not available in this composition (no sandboxing executor to escalate)");
+		const effectiveMode = standingPolicy.mode;
+		return approveEscalation({
+			requestedMode: mode,
+			justification,
+			effectiveMode,
+			subject: "command"
+		}, {
+			approver: ctx.get("approval"),
+			agent: exec.agent,
+			callId: exec.callId,
+			toolName: "pwsh",
+			signal: exec.signal
+		});
+	};
+	ctx.systemPrompt.section({
+		name: "tool:pwsh",
+		order: 105,
+		text: "Non-zero exits are reported as `[exit code: N]` markers; investigate failures before moving on. On Windows a killed process settles as `[exit code: 1]` without a signal marker; treat a bare exit 1 after an interruption as a termination, not a command failure."
+	});
+	ctx.tools.register(defineTool({
+		name: "pwsh",
+		description: pwshDescription(backgroundEnabled, escalationModes),
+		parameters: {
+			command: {
+				type: "string",
+				required: true,
+				description: "The PowerShell command to execute."
+			},
+			description: {
+				type: "string",
+				required: true,
+				description: "Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"Get-Process\" → \"List running processes\"."
+			},
+			timeoutMs: {
+				type: "number",
+				description: "Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."
+			},
+			workdir: {
+				type: "string",
+				description: "Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."
+			},
+			changed_paths: {
+				type: "array",
+				items: { type: "string" },
+				description: "Foreground files this command changed, declared explicitly for workspace instruction refresh."
+			},
+			...backgroundEnabled ? { run_in_background: {
+				type: "boolean",
+				description: "Run in the background and return a job id immediately (collect with job_output, stop with job_kill). No timeout applies."
+			} } : {},
+			...escalationModes.length > 0 ? {
+				sandbox_permissions: {
+					type: "string",
+					enum: [...escalationModes],
+					description: "The wider sandbox mode this command needs. Only valid as a one-shot retry of a command the sandbox just denied; requires justification and user approval."
+				},
+				justification: {
+					type: "string",
+					description: "Required with sandbox_permissions: one sentence for the user explaining why this exact command needs the wider access."
+				}
+			} : {}
+		},
+		output: {
+			schema: { oneOf: [{
+				type: "object",
+				additionalProperties: false,
+				properties: BACKGROUND_OUTPUT_PROPERTIES
+			}, {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					kind: {
+						type: "string",
+						required: true,
+						const: "foreground"
+					},
+					exitCode: {
+						required: true,
+						oneOf: [{ type: "integer" }, { type: "null" }]
+					},
+					signal: {
+						required: true,
+						oneOf: [{ type: "string" }, { type: "null" }]
+					},
+					timedOut: {
+						type: "boolean",
+						required: true
+					},
+					aborted: {
+						type: "boolean",
+						required: true
+					},
+					timeoutMs: {
+						type: "number",
+						required: true
+					},
+					stdout: {
+						type: "object",
+						additionalProperties: false,
+						required: true,
+						properties: {
+							text: {
+								type: "string",
+								required: true
+							},
+							truncated: {
+								type: "boolean",
+								required: true
+							},
+							spillPath: { type: "string" }
+						}
+					},
+					stderr: {
+						type: "object",
+						additionalProperties: false,
+						required: true,
+						properties: {
+							text: {
+								type: "string",
+								required: true
+							},
+							truncated: {
+								type: "boolean",
+								required: true
+							},
+							spillPath: { type: "string" }
+						}
+					},
+					sandbox: {
+						type: "object",
+						additionalProperties: false,
+						properties: {
+							mode: {
+								type: "string",
+								required: true
+							},
+							denied: {
+								type: "boolean",
+								required: true
+							},
+							enforcement: { type: "string" },
+							runnerFailed: { type: "boolean" }
+						}
+					}
+				}
+			}] },
+			render: (_args, value) => [{
+				type: "text",
+				text: value.kind === "background" ? `started background job ${value.jobId}` : renderPwshResult(value, escalationModes)
+			}]
+		},
+		async execute(args, exec) {
+			validatePwshArgs(args);
+			const standingPolicy = resolveSandboxPolicy(exec);
+			const approvedMode = args.sandbox_permissions !== void 0 && args.justification !== void 0 ? await approvePwshEscalation(args.sandbox_permissions, args.justification, exec, standingPolicy) : void 0;
+			const policy = approvedMode === void 0 ? standingPolicy : {
+				...standingPolicy,
+				mode: approvedMode
+			};
+			const workdir = resolveWorkdir(args.workdir, exec);
+			const request = {
+				command: args.command,
+				...workdir !== void 0 ? { workdir } : {},
+				...args.timeoutMs !== void 0 ? { timeoutMs: args.timeoutMs } : {},
+				hydraEnv: ctx.shellEnv.collect(exec),
+				...policy !== void 0 ? { sandboxPolicy: policy } : {}
+			};
+			if (args.run_in_background === true) {
+				if (!backgroundEnabled) throw new Error("run_in_background is disabled for this deployment (enableRunInBackground: false)");
+				const jobs = ctx.get("jobs");
+				if (jobs === void 0) throw new Error("background jobs unavailable: load @hydraharness/harness-jobs and @hydraharness/harness-tool-jobs");
+				if (exec.signal.aborted) {
+					const error = new HarnessError("tool call aborted", TOOL_ABORTED);
+					error.name = "AbortError";
+					throw error;
+				}
+				return {
+					kind: "background",
+					jobId: jobs.start({
+						kind: "pwsh",
+						label: args.command,
+						...exec.agent ? { owner: exec.agent } : {},
+						run: () => {
+							const proc = ctx.shell.start(ctx.shell.resolve(request));
+							return {
+								cancel: () => void proc.kill(),
+								done: proc.done.then(() => processOutcome(proc)),
+								readOutput: () => renderPwshProcessRead(proc.readOutput(), proc.sandbox, escalationModes)
+							};
+						}
+					})
+				};
+			}
+			const result = await ctx.shell.run(ctx.shell.resolve({
+				...request,
+				signal: exec.signal
+			}));
+			if (result.aborted) {
+				const error = new HarnessError("tool call aborted", TOOL_ABORTED);
+				error.name = "AbortError";
+				throw error;
+			}
+			return canonicalPwshResult(result);
+		},
+		presentCall: (args) => {
+			if (args.run_in_background === true) return {
+				card: "generic",
+				title: args.command,
+				kind: "execute",
+				rawInput: args.command,
+				content: [{
+					type: "text",
+					text: args.description
+				}]
+			};
+			return {
+				card: "terminal",
+				title: args.command,
+				description: args.description,
+				...args.workdir !== void 0 ? { cwd: args.workdir } : {}
+			};
+		},
+		presentResult: (args, result) => {
+			const block = result.content.length === 1 ? result.content[0] : void 0;
+			if (block === void 0 || block.type !== "text") return void 0;
+			const raw = block.text;
+			if (typeof args === "object" && args !== null && args.run_in_background === true || result.isError) return {
+				card: "generic",
+				content: [{
+					type: "text",
+					text: `\`\`\`console\n${raw.replace(/\n+$/, "")}\n\`\`\``
+				}]
+			};
+			const { body, ...exit } = parseExitStatus(raw);
+			return {
+				card: "terminal",
+				output: body,
+				...exit
+			};
+		}
+	}));
+}
+//#endregion
+export { Config, apply, inject, name };

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@hydraharness/harness-tool-pwsh`.
+* @module @hydraharness/harness-tool-pwsh/invariant
+*/
+const PACKAGE_NAME = "@hydraharness/harness-tool-pwsh";
+/** Cordis companion plugin name. */
+const name = "tool-pwsh-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: this package exposes no independent event sequence or mutable data relation
+* beyond contracts enforced at its owning seam.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/background.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Generic-task adaptation for background pwsh process handles — the shell-agnostic
+ * twin of `@hydraharness/harness-tool-bash`'s background adaptation.
+ *
+ * @module @hydraharness/harness-tool-pwsh/background
+ */
+import type { ShellProcess } from '@hydraharness/harness-shell';
+/**
+ * Map a settled background process onto the generic task-outcome vocabulary:
+ * `killed` stays `killed` (detail: the signal when one is known), everything
+ * else is `completed` with the exit code as detail. A nonzero command exit is
+ * reported, not failed, exactly like the foreground rendering.
+ * @param proc - the settled process handle.
+ * @returns the outcome for the `ctx.jobs` registration.
+ */
+export declare function processOutcome(proc: ShellProcess): {
+    status: 'completed' | 'killed';
+    detail: string;
+};
+//# sourceMappingURL=background.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Model-facing PowerShell Consumer of the `ctx.shell` capability seam. Intended for
+ * Windows compositions where a PowerShell executor (e.g.
+ * `@hydraharness/harness-pwsh-local`) backs `ctx.shell`; the tool contract is
+ * PowerShell-dialect: native `C:\...` paths and `$env:NAME` variables.
+ *
+ * Behavior mirrors `@hydraharness/harness-tool-bash` call-for-call: foreground and
+ * `run_in_background` execution (background handles register with the
+ * generic `ctx.jobs` runtime), the managed `HYDRA_*` environment through the
+ * shared `shell-env` registry, the per-call sandbox policy resolution (the
+ * calling session's mode and cwd travel to the confining executor), the
+ * sandbox-denial rendering with the same-turn escalation surface
+ * (`sandbox_permissions` + `justification` resolved through
+ * `ctx.approval`), and the bash marker/truncation rendering story. UI
+ * presentation mirrors the bash tool's too: a completed foreground call is
+ * a terminal card with the parsed exit-status pill, using the shared
+ * exit-status parse from `@hydraharness/harness-shell`.
+ *
+ * @module @hydraharness/harness-tool-pwsh
+ */
+import type { Context } from '@hydraharness/cordis';
+import z from '@hydraharness/schemastery';
+declare module '@hydraharness/harness-jobs' {
+    interface JobKindMap {
+        pwsh: 'pwsh';
+    }
+}
+export declare const name = "tool-pwsh";
+export declare const inject: string[];
+/** Configuration for the pwsh tool. */
+export interface Config {
+    /** Expose `run_in_background` (default true); disabled calls are also rejected. */
+    enableRunInBackground?: boolean;
+}
+/** Runtime configuration schema for the pwsh tool plugin. */
+export declare const Config: z<Config>;
+export declare function apply(ctx: Context, config?: Config): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@hydraharness/harness-tool-pwsh`.
+ * @module @hydraharness/harness-tool-pwsh/invariant
+ */
+import type { Context } from '@hydraharness/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "tool-pwsh-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/render.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Model-facing result rendering for the pwsh tool — the PowerShell twin of
+ * `@hydraharness/harness-tool-bash`'s renderer: stdout, a marked stderr section, sandbox
+ * denial/runner-failure markers (with the same-turn escalation hint), and
+ * truncation notices with spill paths, then exit-status markers. Non-zero
+ * exits are reported, not errored — the model decides how to react; only
+ * infrastructure failures (spawn errors, aborts) surface as isError
+ * results.
+ *
+ * @module @hydraharness/harness-tool-pwsh/render
+ */
+import type { ShellProcessRead, ShellSandboxInfo, CollectedOutput } from '@hydraharness/harness-shell';
+import type { SandboxMode } from '@hydraharness/harness-sandbox';
+/** The renderable foreground result shape (the schema-derived value, no `kind`). */
+export interface RenderablePwshResult {
+    exitCode: number | null;
+    signal: string | null;
+    timedOut: boolean;
+    timeoutMs: number;
+    stdout: CollectedOutput;
+    stderr: CollectedOutput;
+    sandbox?: ShellSandboxInfo;
+}
+/**
+ * Shape one finished run into the text the model sees: stdout, then a marked
+ * stderr section, then exit-status markers, matching the bash tool's story —
+ * a clean exit (0, no signal) produces no marker.
+ * @param result - the completed foreground run from the executor.
+ * @param escalationModes - the escalation targets this composition advertises;
+ *   non-empty adds the same-turn escalation hint after a denial marker
+ *   (default `[]`: no hint).
+ * @returns the model-facing text: output body (or `(no output)`), then any timeout/signal/exit markers, each on its own line.
+ */
+export declare function renderPwshResult(result: RenderablePwshResult, escalationModes?: readonly SandboxMode[]): string;
+/**
+ * Shape one background-process read into the `job_output` delta the model
+ * sees: the incremental delta, plus the lossy-read notice (with full-stream
+ * spill paths) when in-memory truncation dropped unread bytes.
+ * @param read - one incremental read from the process handle.
+ * @param sandbox - settled sandbox facts, when this was a confined process.
+ * @param escalationModes - escalation targets advertised by this composition.
+ * @returns the delta text with any loss or sandbox notice appended.
+ */
+export declare function renderPwshProcessRead(read: ShellProcessRead, sandbox?: ShellSandboxInfo, escalationModes?: readonly SandboxMode[]): string;
+//# sourceMappingURL=render.d.ts.map

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@hydraharness/harness-tool-pwsh",
+  "description": "Model-facing pwsh tool over the bash executor seam",
+  "hydra": {
+    "plugin": {
+      "application": "Let the agent run PowerShell commands and collect their output."
+    }
+  },
+  "version": "0.1.1-rc.6",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MaiHongPhong1902/Hydra-Harness.git",
+    "directory": "packages/shell/tool-pwsh"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@hydraharness/harness-shell": "^0.1.1-rc.6",
+    "@hydraharness/harness-shell-env": "^0.1.1-rc.6",
+    "@hydraharness/harness-llm": "^0.1.1-rc.6",
+    "@hydraharness/harness-sandbox": "^0.1.1-rc.6",
+    "@hydraharness/harness-agent": "^0.1.1-rc.6",
+    "@hydraharness/harness-invariants": "^0.1.1-rc.6",
+    "@hydraharness/harness-sandbox-policy": "^0.1.1-rc.6",
+    "@hydraharness/harness-system-prompt": "^0.1.1-rc.6",
+    "@hydraharness/harness-user-approval": "^0.1.1-rc.6",
+    "@hydraharness/cordis": "^4.0.2",
+    "@hydraharness/harness-jobs": "^0.1.1-rc.6",
+    "@hydraharness/harness-tools": "^0.1.1-rc.6"
+  },
+  "dependencies": {
+    "@hydraharness/schemastery": "^3.18.2"
+  },
+  "devDependencies": {
+    "@hydraharness/harness-shell": "^0.1.1-rc.6",
+    "@hydraharness/harness-agent": "^0.1.1-rc.6",
+    "@hydraharness/harness-llm": "^0.1.1-rc.6",
+    "@hydraharness/harness-invariants": "^0.1.1-rc.6",
+    "@hydraharness/harness-shell-env": "^0.1.1-rc.6",
+    "@hydraharness/harness-loader-smoke": "^0.1.1-rc.6",
+    "@hydraharness/harness-pwsh-local": "^0.1.1-rc.6",
+    "@hydraharness/harness-sandbox-policy": "^0.1.1-rc.6",
+    "@hydraharness/harness-subprocess-local": "^0.1.1-rc.6",
+    "@hydraharness/harness-system-prompt": "^0.1.1-rc.6",
+    "@hydraharness/harness-jobs": "^0.1.1-rc.6",
+    "@hydraharness/harness-jobs-local": "^0.1.1-rc.6",
+    "@hydraharness/harness-tool-jobs": "^0.1.1-rc.6",
+    "@hydraharness/harness-tools": "^0.1.1-rc.6",
+    "@hydraharness/cordis": "^4.0.2",
+    "@hydraharness/harness-user-approval": "^0.1.1-rc.6",
+    "@hydraharness/harness-sandbox": "^0.1.1-rc.6"
+  }
+}