@qilin-agent/tool-pwsh 0.0.0-stage → 3.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kkutysllb
+
+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.i18n.yaml

@@ -0,0 +1,121 @@
+# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/shell/tool-pwsh/README.md
+/:
+  en: 83e748b077469aac
+  zh: f858d23ea8c1c6ba
+/qilin-tool-pwsh:
+  en: 7c96246d95d566d4
+  zh: 3753177f123b2ab4
+/qilin-tool-pwsh/summary:
+  en: c41ec1fbfa215c94
+  zh: 314e5d3265be3d6d
+/qilin-tool-pwsh/table-of-contents:
+  en: d152484eb41ac6b4
+  zh: 09388d293f9be9cb
+/qilin-tool-pwsh/use-this-package:
+  en: 1b4216447cd42de2
+  zh: 76280937fc3e7b26
+/qilin-tool-pwsh/use-this-package/when-to-choose-it:
+  en: c9cfb8651fc9558f
+  zh: 21ad622a9d50bd4e
+/qilin-tool-pwsh/use-this-package/minimal-configuration:
+  en: bd6629bd8397b329
+  zh: f1dc3bb067d951e4
+/qilin-tool-pwsh/use-this-package/running-a-command:
+  en: 02b18286e7ae41a8
+  zh: 377624e32d370cce
+/qilin-tool-pwsh/use-this-package/windows-specific-sandbox-behavior:
+  en: a2d3592afd0c5678
+  zh: dc9ef914149c3604
+/qilin-tool-pwsh/use-this-package/what-can-go-wrong:
+  en: 0db3e3f9fc823853
+  zh: 7196d080d76babee
+/qilin-tool-pwsh/understand-the-implementation:
+  en: 8d94a7381bca3fa9
+  zh: f4bd2866fff6fa8d
+/qilin-tool-pwsh/understand-the-implementation/design-philosophy:
+  en: d03cc8af1c9c1315
+  zh: 202bea78d0bcdea6
+/qilin-tool-pwsh/understand-the-implementation/source-map:
+  en: 02d3f9c1a49f9c31
+  zh: 5a59a787a37bd9cb
+/qilin-tool-pwsh/understand-the-implementation/rendering-and-exit-markers:
+  en: 35818fa611875c4a
+  zh: 7a0fc35fa0a72b78
+/qilin-tool-pwsh/further-exploration:
+  en: 24d79bef5d6e6648
+  zh: 518eb32cea322bc4
+/qilin-tool-pwsh/model-experience:
+  en: 215e7ba838619b7b
+  zh: a311da3843709f90
+/qilin-tool-pwsh/model-experience/system-prompt:
+  en: cf78b9dd5596495f
+  zh: bd44560f8c2435e8
+/qilin-tool-pwsh/model-experience/system-prompt/what-the-model-sees:
+  en: ed8a75117d71cc5d
+  zh: 7b9119a5246d096e
+/qilin-tool-pwsh/model-experience/system-prompt/what-the-model-sees/pwsh-guidance:
+  en: de907562b460fc1b
+  zh: 2a398555cc929dd3
+/qilin-tool-pwsh/model-experience/system-prompt/token-effect:
+  en: 4fea242a5deec6d2
+  zh: 8dcbe863eb960a4d
+/qilin-tool-pwsh/model-experience/system-prompt/kv-cache-effect:
+  en: 3959f5f66ff2f4be
+  zh: 66636c0d90becdb1
+/qilin-tool-pwsh/model-experience/tool-schemas:
+  en: 3039bc5e7a796b21
+  zh: 6b7a9eaf69c9ea53
+/qilin-tool-pwsh/model-experience/tool-schemas/what-the-model-sees:
+  en: 0f994a8c1382cc63
+  zh: d1d18fcee5735073
+/qilin-tool-pwsh/model-experience/tool-schemas/token-effect:
+  en: 97cce067584eadff
+  zh: 54b1f5cd5899e7f3
+/qilin-tool-pwsh/model-experience/tool-schemas/kv-cache-effect:
+  en: a6768b4fdc27de21
+  zh: 6d1d9b8357441af8
+/qilin-tool-pwsh/model-experience/foreground-result:
+  en: d83f1f25a3719c54
+  zh: 445ca808e28dc936
+/qilin-tool-pwsh/model-experience/foreground-result/what-the-model-sees:
+  en: 790fd2ecc7e1fd38
+  zh: 76b3da098b1b5cf8
+/qilin-tool-pwsh/model-experience/foreground-result/token-effect:
+  en: b2018adbda15b8a7
+  zh: efa06f083800a36b
+/qilin-tool-pwsh/model-experience/foreground-result/kv-cache-effect:
+  en: f5d5f97a153f7c70
+  zh: 31911b4f3506d6c8
+/qilin-tool-pwsh/model-experience/background-result:
+  en: 3f23f9211197b0b9
+  zh: 8cff3c78249b66ff
+/qilin-tool-pwsh/model-experience/background-result/what-the-model-sees:
+  en: a471e423bb4fd271
+  zh: 8949b37acf642e0c
+/qilin-tool-pwsh/model-experience/background-result/token-effect:
+  en: 1480a7a9ec4e3a96
+  zh: c7ec0cee960c8c99
+/qilin-tool-pwsh/model-experience/background-result/kv-cache-effect:
+  en: f5d5f97a153f7c70
+  zh: 31911b4f3506d6c8
+/qilin-tool-pwsh/model-experience/tool-errors:
+  en: 2d4f2c8605eccab3
+  zh: 67f1f0218f73c6bf
+/qilin-tool-pwsh/model-experience/tool-errors/what-the-model-sees:
+  en: efc765cc65699edb
+  zh: 072fe15a1979148e
+/qilin-tool-pwsh/model-experience/tool-errors/token-effect:
+  en: 243bad012dd99c7f
+  zh: 5ee74905020bd49a
+/qilin-tool-pwsh/model-experience/tool-errors/kv-cache-effect:
+  en: f5d5f97a153f7c70
+  zh: 31911b4f3506d6c8
+/qilin-tool-pwsh/known-limitations-and-deferred-work:
+  en: 8414f06d98e2be52
+  zh: 64a484b891053be9
+/qilin-tool-pwsh/known-limitations-and-deferred-work/dev-note:
+  en: e67f633dc6fe7773
+  zh: 3bb0c20c93f16f98

package/README.md

@@ -1,3 +1,212 @@
-# Temporary Holding Version
+---
+description: "The model-facing pwsh tool for users and maintainers choosing, configuring, or debugging one-shot PowerShell execution, background jobs, and sandbox escalation on Windows."
+kind: "package-reference"
+---
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @qilin-agent/tool-pwsh
+
+English | [中文](README.zh.md)
+
+## Summary
+
+`qilin-tool-pwsh` gives the agent a `pwsh` tool that runs PowerShell commands through the mounted shell executor — the Windows counterpart of `qilin-tool-bash`, mirroring it call-for-call. Each call runs in a fresh pwsh process, so no state survives; `run_in_background` turns long-running commands into background jobs. Commands are PowerShell-dialect: native `C:\...` paths and `$env:NAME` variables, with no dialect translation. Every call runs with the managed `QILIN_*` environment, and under a sandboxing executor the tool teaches and enforces the Windows-specific language-mode and named-pipe contracts. Mount it with a PowerShell executor such as `qilin-pwsh-local` and the `qilin-shell-env` plugin.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+Load this plugin in any composition where the agent should run PowerShell commands — typically a Windows composition whose `ctx.shell` is backed by a PowerShell executor. It registers the `pwsh` tool once the executor provider and the `qilin-shell-env` registry are mounted.
+
+### When to choose it
+
+Choose the pwsh tool when commands must be written in PowerShell — native paths and `$env:` variables — or when the deployment is Windows-native. Choose `qilin-tool-bash` when the command set is bash-dialect; there is no translation between the two. When work needs cross-call state (cwd, variables), the persistent counterpart [`qilin-tool-pwsh-persistent`](../tool-pwsh-persistent/README.md) keeps one owner-scoped shell alive.
+
+### Minimal configuration
+
+The common path is a PowerShell executor provider, the environment registry, and this tool.
+
+```yaml
+- name: '@qilin-agent/pwsh-local'
+- name: '@qilin-agent/shell-env'
+- name: '@qilin-agent/tool-pwsh'
+```
+
+The single config field toggles background support.
+
+| Field | Default | Meaning |
+|---|---|---|
+| `enableRunInBackground` | `true` | Expose `run_in_background`; when `false`, forced background calls are rejected |
+
+The generated [configuration catalog](../../../docs/config-catalog.md#qilin-agenttool-pwsh) is the exhaustive source for every accepted field and its JSDoc; the generated [tool catalog](../../../docs/tool-catalog.md#qilin-agenttool-pwsh) carries the full argument schema.
+
+### Running a command
+
+The tool executes `pwsh -Command <command>` and returns the combined output. Commands run in a fresh pwsh process every call, so state never persists — pass `workdir` instead of `cd`. Paths use native Windows form and environment variables are read with `$env:NAME`. A non-zero exit is reported as `[exit code: N]`; on Windows a force-killed command settles as `[exit code: 1]` without a signal marker, so the agent treats a bare exit 1 after an interruption as a termination, not a command failure. The description tells the agent to verify the resolved absolute target path before any delete or move and not to assign to automatic variables such as `$HOME`. Background runs, output truncation, and the `description`/`timeoutMs`/`workdir` arguments behave exactly as in [`qilin-tool-bash`](../tool-bash/README.md#running-long-commands-in-the-background), including job-owned cancellation during asynchronous shell preparation.
+
+### Windows-specific sandbox behavior
+
+Under a sandboxing executor, denied commands report `[sandbox: file access denied under <mode> mode]`, and the same one-shot escalation path applies: retry the exact command once with `sandbox_permissions` plus a `justification` through user approval. The tool also teaches two Windows-restricted-token contracts in its description: read-only pwsh runs in ConstrainedLanguage (`.NET` static calls, `Add-Type`, COM, and reflection fail with "only core types" errors), and in both confined modes programs cannot open named pipes, so a command that captures another program's output through piped stdio fails with EPERM — escalate the exact command once or restructure it to avoid capturing output.
+
+### What can go wrong
+
+A composition with no PowerShell executor never activates the tool, and the injected services (`tools`, `shell`, `systemPrompt`, `shellEnv`) must all exist. Background calls without the job runtime fail with `background jobs unavailable: load @qilin-agent/jobs and @qilin-agent/tool-jobs`, and `sandbox_permissions` without a sandboxing executor fails with `sandbox_permissions is not available in this composition (no sandboxing executor to escalate)`.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+This section explains the design decisions behind the tool and points at the code that realizes them; the observable behavior is fully covered in [Use this package](#use-this-package).
+
+### Design philosophy
+
+- **A deliberate twin of `qilin-tool-bash`.** Foreground and background execution, the managed environment, the sandbox escalation surface, and the marker/truncation rendering mirror the bash tool call-for-call, so consumers of one accept the other's wire shape ([pwsh tool bash parity Agent Note](../../../.agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.md)).
+- **PowerShell-dialect contract.** The tool contract is PowerShell: native paths and `$env:` variables, executed via `pwsh -Command` with no intermediate shell.
+- **Windows sandbox facts taught in the description.** The ConstrainedLanguage and named-pipe contracts are Windows-restricted-token behavior; the gate for teaching them is "any confining executor is mounted", which is safe because every shipped pairing is win32-only.
+- **Non-zero exits are reported, not errored.** Only infrastructure failures (spawn errors, aborts) surface as tool errors, matching the bash story.
+
+### Source map
+
+| File | Role |
+|---|---|
+| [`src/index.ts`](src/index.ts) | Plugin entry: tool registration, prompt section, arg validation, escalation, request assembly |
+| [`src/background.ts`](src/background.ts) | Map a settled background process onto generic job outcome vocabulary |
+| [`src/render.ts`](src/render.ts) | Model-facing result text: streams, markers, truncation notices (bash twin) |
+
+### Rendering and exit markers
+
+The renderer shares the bash tool's structure and the `parseExitStatus` marker contract from `qilin-shell`: a clean exit (0, no signal) produces no marker; the UI card consumes the exit marker as its exit-status pill. Windows forced termination settles as exit 1 without a signal, so `[killed by signal: …]` is POSIX-only there. The `tool:pwsh` prompt section (first-party order 1010) teaches the exit-marker convention and the Windows exit-1-after-interruption reading.
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+Read these pages when the package-level contract is not enough. They move from the shell family to the executor seam and the design notes behind the Windows behavior.
+
+- [shell package map](../README.md) — the bash capability family and its roles.
+- [Bash executor subsystem](../../../docs/subsystems/shell.md) — request/spec vocabulary, results, and background processes.
+- [shell-env](../shell-env/README.md) — the managed `QILIN_*` environment every call receives.
+- [tool-jobs](../../jobs/tool-jobs/README.md) — `job_output`, `job_list`, and `job_kill` controls for background runs.
+- [pwsh tool bash parity Agent Note](../../../.agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.md) — why the tool mirrors the bash tool.
+- [Windows ACL restricted-token sandbox Agent Note](../../../.agents/notes/implemented/feature/2026-08-08-windows-acl-restricted-token-sandbox.md) — the language-mode and named-pipe contracts.
+- [Generated tool catalog](../../../docs/tool-catalog.md#qilin-agenttool-pwsh) — the exact `pwsh` argument schema.
+- [Generated configuration catalog](../../../docs/config-catalog.md#qilin-agenttool-pwsh) — every accepted config field and its source declaration.
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+### System prompt
+
+#### What the model sees
+
+Every request in this plugin's registration scope contains the pwsh guidance below at first-party order 1010. 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#qilin-agenttool-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-or-(unavailable)>]`, `[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>`, the escalation pairing failures, `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 @qilin-agent/jobs and @qilin-agent/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
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+These limits define when the tool is a poor fit or needs special care. They are current package constraints, not a task backlog.
+
+- **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 [`@qilin-agent/tool-pwsh-persistent`](../tool-pwsh-persistent/README.md), which keeps one owner-scoped pwsh alive across calls.
+- **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.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>

package/README.zh.md

@@ -0,0 +1,212 @@
+---
+description: "面向模型的 pwsh 工具，供选择、配置或排查 Windows 上一次性 PowerShell 执行、后台任务与沙箱升权的使用者与维护者阅读。"
+kind: "package-reference"
+---
+
+# @qilin-agent/tool-pwsh
+
+[English](README.md) | 中文
+
+## 概述
+
+`qilin-tool-pwsh` 为 agent（智能体）提供 `pwsh` 工具，通过已挂载的 shell 执行器运行 PowerShell 命令——它是 `qilin-tool-bash` 的 Windows 对应物，逐调用镜像。每次调用都运行在全新 pwsh 进程中，因此状态不会保留；`run_in_background` 把长时间运行的命令变成后台任务。命令是 PowerShell 方言：原生 `C:\...` 路径与 `$env:NAME` 变量，不做方言翻译。每次调用都运行在受管 `QILIN_*` 环境中；在沙箱执行器下，工具会向模型说明并强制执行 Windows 特有的语言模式与命名管道约定。请与 `qilin-pwsh-local` 等 PowerShell 执行器以及 `qilin-shell-env` 插件一起挂载。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+在 agent 需要运行 PowerShell 命令的任何组合中加载本插件——通常是 `ctx.shell` 由 PowerShell 执行器支撑的 Windows 组合。一旦挂载执行器提供方与 `qilin-shell-env` 注册表，它就注册 `pwsh` 工具。
+
+### 何时选择
+
+当命令必须用 PowerShell 编写——原生路径与 `$env:` 变量——或部署是 Windows 原生时，选择 pwsh 工具。当命令集是 bash 方言时选择 `qilin-tool-bash`；两者之间没有翻译。当工作依赖跨调用状态（cwd、变量）时，持久对应物 [`qilin-tool-pwsh-persistent`](../tool-pwsh-persistent/README.zh.md) 会保持一个按所有者隔离的 shell 存活。
+
+### 最小配置
+
+常用路径是 PowerShell 执行器提供方、环境注册表与本工具。
+
+```yaml
+- name: '@qilin-agent/pwsh-local'
+- name: '@qilin-agent/shell-env'
+- name: '@qilin-agent/tool-pwsh'
+```
+
+唯一的配置字段用于开关后台支持。
+
+| 字段 | 默认值 | 含义 |
+|---|---|---|
+| `enableRunInBackground` | `true` | 暴露 `run_in_background`；为 `false` 时拒绝强制后台调用 |
+
+生成的[配置目录](../../../docs/config-catalog.zh.md#qilin-agenttool-pwsh)是每个受支持字段及其 JSDoc 的穷尽式真源；生成的[工具目录](../../../docs/tool-catalog.zh.md#qilin-agenttool-pwsh)携带完整参数 schema。
+
+### 运行命令
+
+工具执行 `pwsh -Command <command>` 并返回合并后的输出。命令每次调用都运行在全新 pwsh 进程中，因此状态从不保留——请传 `workdir` 而不是 `cd`。路径使用原生 Windows 形式，环境变量用 `$env:NAME` 读取。非零退出以 `[exit code: N]` 报告；在 Windows 上，强制终止的命令以 `[exit code: 1]` 结算且没有信号标记，因此 agent 把中断后的裸 exit 1 当作终止而非命令失败。工具描述要求 agent 在任何删除或移动前校验解析后的绝对目标路径，并且不要给 `$HOME` 等自动变量赋值。后台运行、输出截断以及 `description`／`timeoutMs`／`workdir` 参数的行为与 [`qilin-tool-bash`](../tool-bash/README.zh.md#running-long-commands-in-the-background) 完全一致，包括异步 shell 准备过程中由任务负责的取消。
+
+### Windows 特有的沙箱行为
+
+在沙箱执行器下，被拒绝的命令会报告 `[sandbox: file access denied under <mode> mode]`，并适用相同的单次升权路径：用 `sandbox_permissions` 加一句 `justification`，经用户审批后重试完全相同的命令一次。工具还会在其描述中教授两条 Windows 受限令牌约定：只读 pwsh 运行在 ConstrainedLanguage 中（`.NET` 静态调用、`Add-Type`、COM 与反射会以 "only core types" 错误失败）；两种受限模式下程序都无法打开命名管道，因此通过管道 stdio 捕获另一程序输出的命令会以 EPERM 失败——请升权该确切命令一次，或重构命令以避免捕获输出。
+
+### 可能出什么问题
+
+没有 PowerShell 执行器的组合永远不会激活该工具，且注入的服务（`tools`、`shell`、`systemPrompt`、`shellEnv`）必须全部存在。没有任务运行时的后台调用会以 `background jobs unavailable: load @qilin-agent/jobs and @qilin-agent/tool-jobs` 失败；没有沙箱执行器时的 `sandbox_permissions` 会以 `sandbox_permissions is not available in this composition (no sandboxing executor to escalate)` 失败。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现细节——点击展开</summary>
+
+本节解释工具背后的设计决策，并指出实现它们的代码位置；可观察行为已在[使用本包](#use-this-package)中完整说明。
+
+### 设计理念
+
+- **`qilin-tool-bash` 的刻意孪生。** 前台与后台执行、受管环境、沙箱升权面以及标记／截断渲染都逐调用镜像 bash 工具，因此其中之一的消费方也能接受另一个的协议形状（[pwsh 工具与 bash 对齐 Agent Note](../../../.agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.zh.md)）。
+- **PowerShell 方言约定。** 工具约定是 PowerShell：原生路径与 `$env:` 变量，经由 `pwsh -Command` 执行，没有中间 shell。
+- **Windows 沙箱事实写进描述。** ConstrainedLanguage 与命名管道约定是 Windows 受限令牌行为；教授它们的条件是「已挂载任意约束执行器」，之所以安全，是因为每个已发布的配对都是 win32-only。
+- **非零退出只报告、不失败。** 只有基础设施故障（spawn 错误、中止）才会作为工具错误暴露，与 bash 的故事一致。
+
+### 源码地图
+
+| 文件 | 职责 |
+|---|---|
+| [`src/index.ts`](src/index.ts) | 插件入口：工具注册、提示词区段、参数校验、升权、请求组装 |
+| [`src/background.ts`](src/background.ts) | 把已结算的后台进程映射为通用任务结果词汇 |
+| [`src/render.ts`](src/render.ts) | 模型侧结果文本：流、标记、截断通知（bash 孪生） |
+
+### 渲染与退出标记
+
+渲染器共享 bash 工具的结构与来自 `qilin-shell` 的 `parseExitStatus` 标记约定：干净退出（0、无信号）不产生标记；UI 卡片把退出标记消费为退出状态 pill。Windows 强制终止以 exit 1 结算且没有信号，因此 `[killed by signal: …]` 仅适用于 POSIX。`tool:pwsh` 提示词区段（first-party 顺序 1010）教授退出标记约定与「中断后 exit 1」的 Windows 解读。
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+当包级约定不够用时阅读以下页面。它们从 shell 家族逐步进入执行器 seam，以及 Windows 行为背后的设计笔记。
+
+- [shell 包映射](../README.zh.md)——bash 能力家族及其角色。
+- [Bash 执行器子系统](../../../docs/subsystems/shell.zh.md)——请求／spec 词汇、结果与后台进程。
+- [shell-env](../shell-env/README.zh.md)——每次调用都会收到的受管 `QILIN_*` 环境。
+- [tool-jobs](../../jobs/tool-jobs/README.zh.md)——后台运行的 `job_output`、`job_list` 与 `job_kill` 控制。
+- [pwsh 工具与 bash 对齐 Agent Note](../../../.agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.zh.md)——为什么工具镜像 bash 工具。
+- [Windows ACL 受限令牌沙箱 Agent Note](../../../.agents/notes/implemented/feature/2026-08-08-windows-acl-restricted-token-sandbox.zh.md)——语言模式与命名管道约定。
+- [生成的工具目录](../../../docs/tool-catalog.zh.md#qilin-agenttool-pwsh)——`pwsh` 参数 schema 的确切内容。
+- [生成的配置目录](../../../docs/config-catalog.zh.md#qilin-agenttool-pwsh)——每个受支持配置字段及其源声明。
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+### 系统提示词
+
+#### 模型看到什么
+
+该插件注册作用域内的每次请求都在 first-party 顺序 1010 处包含以下 pwsh 指引。按作用域实施的工具限制可以隐藏 schema，却不会移除这个独立注册的区段。
+
+##### Pwsh 指引
+
+```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 影响
+
+插件激活期间，每次请求都会产生少量固定的输入 token 开销。
+
+#### KV Cache 影响
+
+只要注册作用域与提示词文本不变，前缀就保持稳定。插件激活或释放可能使从该提示词区段起的复用失效。
+
+### 工具 schema
+
+#### 模型看到什么
+
+模型会看到生成的 [`pwsh` schema](../../../docs/tool-catalog.zh.md#qilin-agenttool-pwsh)。按 agent 作用域实施的工具限制可以移除该 agent 的定义。
+
+#### Token 影响
+
+工具可见的每个请求都会产生固定 schema 开销。
+
+#### KV Cache 影响
+
+只要可见性与工具定义不变，前缀就保持稳定。限制或配置变化可能从首个变化的 token 开始使复用失效。
+
+### 前台结果
+
+#### 模型看到什么
+
+渲染器输出依数据而定的 stdout 尾部，再输出可选的 `[stderr]` 和 stderr 尾部。条件行精确为 `[output truncated; full output: <path-or-(unavailable)>]`、`[sandbox: file access denied under <mode> mode]` 加升权提示 `[sandbox: escalation available — …]`（仅在组合声明升权时）、`[timed out after <timeoutMs>ms]`、`[killed by signal: <signal>]` 与 `[exit code: <exitCode>]`（仅非零退出）；空正文渲染为 `(no output)`。
+
+#### Token 影响
+
+调用前的结果 token 为零。输出按流设界，而每行已发出的内容在压缩（compaction）前保留于历史。
+
+#### KV Cache 影响
+
+仅追加；新可见内容位于可复用请求前缀之后，不会使现有 KV-cache 条目失效。
+
+### 后台结果
+
+#### 模型看到什么
+
+后台启动精确渲染为 `started background job <id>`；随后的读取与状态经由通用 `job_output`／`job_kill` 工具流转，包括内存截断丢弃未读字节时的有损读取 spill 通知。
+
+#### Token 影响
+
+确认是一行固定的短文本；任务输出按每次读取设界。
+
+#### KV Cache 影响
+
+仅追加；新可见内容位于可复用请求前缀之后，不会使现有 KV-cache 条目失效。
+
+### 工具错误
+
+#### 模型看到什么
+
+验证与基础设施失败统一为 `Error: <message>`。本包的稳定消息包括 `invalid command: expected a non-empty string`、`invalid description: expected a non-empty string`、`invalid timeoutMs: expected a positive number, got <value>`、升权配对失败、`sandbox_permissions is not available in this composition (no sandboxing executor to escalate)`、共享升权失败（未严格加宽／无审批服务／无 agent 可路由／无审批通道／用户拒绝／已取消）、`run_in_background is disabled for this deployment (enableRunInBackground: false)`、`background jobs unavailable: load @qilin-agent/jobs and @qilin-agent/tool-jobs`，以及 `tool call aborted`。
+
+#### Token 影响
+
+只有失败调用会增加这些保留 token；被中止的调用不会添加命令输出。
+
+#### KV Cache 影响
+
+仅追加；新可见内容位于可复用请求前缀之后，不会使现有 KV-cache 条目失效。
+
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+这些限制说明工具何时不合适或需要特别小心。它们是当前包约束，不是任务积压。
+
+- **Windows 沙箱下的语言模式与命名管道捕获**——在 [Windows ACL 沙箱](../../sandbox/sandbox-windows-acl/README.zh.md)下，只读 pwsh 以 ConstrainedLanguage 启动，因为其临时目录写入被拒绝，导致 PowerShell 的 AppLocker 探测失败并按拒绝处理：`Add-Type`、非核心 .NET 静态调用（`[System.IO.*]::`、`[math]::`）、COM 对象与反射会以 "only core types" 错误失败，且该模式无法从内部解除。workspace-write 的私有临时目录让探测完成，因此除非宿主策略另有规定，它保持 FullLanguage。两种受限模式都拒绝命名管道打开，因此受限命令内部的管道 stdio spawn 会以 EPERM 失败。工具描述把两条约定都教给模型；完整限制以后端 README 为准。
+- **没有持久 shell**——每次调用都启动全新的 `pwsh -Command`；持久 shell 对应物是 [`@qilin-agent/tool-pwsh-persistent`](../tool-pwsh-persistent/README.zh.md)，它跨调用保持一个按所有者隔离的 pwsh 存活。
+- **PowerShell 方言约定**——模型必须编写 PowerShell（原生路径、`$env:` 变量），而不是 bash；没有方言翻译。
+- **会话 cwd 身份未规范化**——workdir 基准就是会话头部 cwd 原样，不像 bash 工具那样以沙箱根规范化身份为准。在约束执行器下，策略的 workspace root 确实被规范化（由共享策略服务完成），因此当原始会话 cwd 与其规范形式不同时，workdir 与约束根可能分叉——这是推迟到共享 shell 工具基座抽取的对齐差距。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
+
+无。
+
+</details>

package/lib/index.js

@@ -0,0 +1,540 @@
+import { isAbsolute, resolve } from "node:path";
+import z from "@qilin-agent/schemastery";
+import { TOOL_ABORTED, defineTool } from "@qilin-agent/tools";
+import { HarnessError } from "@qilin-agent/llm";
+import { ESCALATION_TARGETS, approveEscalation, escalationHintMarker, sandboxDenialMarker, validateEscalationArgs } from "@qilin-agent/sandbox";
+import { parseExitStatus } from "@qilin-agent/shell";
+//#region lib/types/render.js
+/**
+* Model-facing result rendering for the pwsh tool — the PowerShell twin of
+* `qilin-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 @qilin-agent/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/background.js
+/**
+* Generic-job adaptation for pwsh process handles: the terminal outcome the
+* registry records and the pull source it pumps into the job's output ring.
+*
+* @module @qilin-agent/tool-pwsh/background
+*/
+/**
+* Sandbox facts worth the terminal detail: a runner that never ran the
+* command, or a denial (with the escalation hint this composition offers).
+* @param sandbox - settled sandbox facts, when this was a confined process.
+* @param escalationModes - escalation targets advertised by this composition.
+* @returns the markers to append, oldest first.
+*/
+function sandboxNotes(sandbox, escalationModes) {
+	if (sandbox?.runnerFailed) return [`[sandbox: the sandbox runner itself failed under ${sandbox.mode} mode — the command did not run; this is a sandbox problem, not a command failure]`];
+	if (sandbox?.denied) {
+		const notes = [sandboxDenialMarker(sandbox.mode)];
+		if (escalationModes.length > 0) notes.push(escalationHintMarker("command"));
+		return notes;
+	}
+	return [];
+}
+/**
+* Map a settled background process onto the generic job-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. Sandbox facts
+* join the detail, since a job's terminal reason is the one line every
+* reader — the model's status line, the roster row — shows.
+* @param proc - the settled process handle.
+* @param escalationModes - escalation targets advertised by this composition.
+* @returns the outcome for the `ctx.jobs` registration.
+*/
+function processOutcome(proc, escalationModes = []) {
+	const base = proc.status === "killed" ? {
+		status: "killed",
+		detail: proc.signal !== null ? `signal: ${proc.signal}` : "killed before exit"
+	} : {
+		status: "completed",
+		detail: `exit code: ${proc.exitCode ?? 0}`
+	};
+	const notes = sandboxNotes(proc.sandbox, escalationModes);
+	return notes.length === 0 ? base : {
+		...base,
+		detail: `${base.detail}; ${notes.join(" ")}`
+	};
+}
+/**
+* The process's captured output as a registry pull source. It binds lazily
+* because the process is spawned inside the starter, after the registry
+* admitted the job; a read before the spawn yields nothing.
+*
+* The shell handle's own reader is consuming — each call hands over what
+* arrived since the previous one — so this source counts the bytes it
+* delivered to keep the registry's cursor monotonic, exactly as the terminal
+* tool adapts its own consuming send reader. Truncation is reported in-band by
+* the read rendering, which names the spill files, so the source has no
+* separate spill path to advertise.
+* @param proc - the started process, once the starter has spawned it.
+* @param escalationModes - escalation targets advertised by this composition.
+* @returns the single source over the process's captured streams.
+*/
+function processSources(proc, escalationModes = []) {
+	return [{ read: (fromByte) => {
+		const live = proc();
+		if (live === void 0) return {
+			text: "",
+			nextOffset: fromByte,
+			lossy: false
+		};
+		const text = renderPwshProcessRead(live.readOutput(), live.sandbox, escalationModes);
+		return {
+			text,
+			nextOffset: fromByte + Buffer.byteLength(text, "utf8"),
+			lossy: false
+		};
+	} }];
+}
+/**
+* Adapt asynchronous shell preparation after job admission without exposing a partial process.
+* @param start - starts the process with job-owned cancellation.
+* @param outcome - projects the settled process into the job outcome.
+* @returns synchronous job hooks whose completion includes preparation and process settlement.
+*/
+function processJob(start, outcome) {
+	const controller = new AbortController();
+	let process;
+	return {
+		cancel: (reason) => {
+			if (controller.signal.aborted) return;
+			controller.abort(reason);
+			process?.kill();
+		},
+		done: (async () => {
+			try {
+				process = await start(controller.signal);
+				try {
+					if (controller.signal.aborted) process.kill();
+				} finally {
+					await process.done;
+				}
+				return outcome(process);
+			} catch (error) {
+				return {
+					status: controller.signal.aborted && process === void 0 ? "killed" : "failed",
+					detail: error instanceof Error ? error.message : String(error)
+				};
+			}
+		})()
+	};
+}
+//#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.
+* `@qilin-agent/pwsh-local`) backs `ctx.shell`; the tool contract is
+* PowerShell-dialect: native `C:\...` paths and `$env:NAME` variables.
+*
+* Behavior mirrors `qilin-tool-bash` call-for-call: foreground and
+* `run_in_background` execution (background handles register with the
+* generic `ctx.jobs` runtime), the managed `QILIN_*` 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 `@qilin-agent/shell`.
+*
+* @module @qilin-agent/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);
+}
+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:QILIN_*` 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. Before any delete or move, verify that the resolved absolute target path is the intended one; never run it against a computed path you have not checked. Do not assign to automatic variables such as `$HOME`; variable names are case-insensitive, so `$home` is the same read-only variable. 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: ctx.systemPrompt.getSectionOrder("TOOL_PWSH"),
+		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."
+			},
+			...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. Use the language of the user’s current request."
+				}
+			} : {}
+		},
+		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 } : {},
+				qilinEnv: 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 @qilin-agent/jobs and @qilin-agent/tool-jobs");
+				if (exec.signal.aborted) {
+					const error = new HarnessError("tool call aborted", TOOL_ABORTED);
+					error.name = "AbortError";
+					throw error;
+				}
+				let proc;
+				return {
+					kind: "background",
+					jobId: jobs.start({
+						kind: "pwsh",
+						label: args.command,
+						...exec.agent ? { owner: exec.agent.id } : {},
+						output: processSources(() => proc, escalationModes),
+						run: () => processJob(async (signal) => {
+							proc = await ctx.shell.start(ctx.shell.resolve({
+								...request,
+								signal
+							}));
+							return proc;
+						}, (started) => processOutcome(started, 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/types/background.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Generic-job adaptation for pwsh process handles: the terminal outcome the
+ * registry records and the pull source it pumps into the job's output ring.
+ *
+ * @module @qilin-agent/tool-pwsh/background
+ */
+import type { SandboxMode } from '@qilin-agent/sandbox';
+import type { ShellProcess } from '@qilin-agent/shell';
+import type { JobHooks, JobOutcome, JobOutputSource } from '@qilin-agent/jobs';
+/**
+ * Map a settled background process onto the generic job-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. Sandbox facts
+ * join the detail, since a job's terminal reason is the one line every
+ * reader — the model's status line, the roster row — shows.
+ * @param proc - the settled process handle.
+ * @param escalationModes - escalation targets advertised by this composition.
+ * @returns the outcome for the `ctx.jobs` registration.
+ */
+export declare function processOutcome(proc: ShellProcess, escalationModes?: readonly SandboxMode[]): JobOutcome;
+/**
+ * The process's captured output as a registry pull source. It binds lazily
+ * because the process is spawned inside the starter, after the registry
+ * admitted the job; a read before the spawn yields nothing.
+ *
+ * The shell handle's own reader is consuming — each call hands over what
+ * arrived since the previous one — so this source counts the bytes it
+ * delivered to keep the registry's cursor monotonic, exactly as the terminal
+ * tool adapts its own consuming send reader. Truncation is reported in-band by
+ * the read rendering, which names the spill files, so the source has no
+ * separate spill path to advertise.
+ * @param proc - the started process, once the starter has spawned it.
+ * @param escalationModes - escalation targets advertised by this composition.
+ * @returns the single source over the process's captured streams.
+ */
+export declare function processSources(proc: () => ShellProcess | undefined, escalationModes?: readonly SandboxMode[]): JobOutputSource[];
+/**
+ * Adapt asynchronous shell preparation after job admission without exposing a partial process.
+ * @param start - starts the process with job-owned cancellation.
+ * @param outcome - projects the settled process into the job outcome.
+ * @returns synchronous job hooks whose completion includes preparation and process settlement.
+ */
+export declare function processJob(start: (signal: AbortSignal) => Promise<ShellProcess>, outcome: (process: ShellProcess) => JobOutcome): JobHooks;
+//# 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.
+ * `@qilin-agent/pwsh-local`) backs `ctx.shell`; the tool contract is
+ * PowerShell-dialect: native `C:\...` paths and `$env:NAME` variables.
+ *
+ * Behavior mirrors `qilin-tool-bash` call-for-call: foreground and
+ * `run_in_background` execution (background handles register with the
+ * generic `ctx.jobs` runtime), the managed `QILIN_*` 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 `@qilin-agent/shell`.
+ *
+ * @module @qilin-agent/tool-pwsh
+ */
+import type { Context } from '@qilin-agent/kylin';
+import z from '@qilin-agent/schemastery';
+declare module '@qilin-agent/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/render.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Model-facing result rendering for the pwsh tool — the PowerShell twin of
+ * `qilin-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 @qilin-agent/tool-pwsh/render
+ */
+import type { ShellProcessRead, ShellSandboxInfo, CollectedOutput } from '@qilin-agent/shell';
+import type { SandboxMode } from '@qilin-agent/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

@@ -1,6 +1,69 @@
 {
   "name": "@qilin-agent/tool-pwsh",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Model-facing pwsh tool over the bash executor seam",
+  "version": "3.1.3",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kkutysllb/QiLin.git",
+    "directory": "packages/shell/tool-pwsh"
+  },
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@qilin-agent/kylin": "~4.0.3",
+    "@qilin-agent/agent": "3.1.3",
+    "@qilin-agent/jobs": "3.1.3",
+    "@qilin-agent/llm": "3.1.3",
+    "@qilin-agent/sandbox": "3.1.3",
+    "@qilin-agent/sandbox-policy": "3.1.3",
+    "@qilin-agent/shell": "3.1.3",
+    "@qilin-agent/shell-env": "3.1.3",
+    "@qilin-agent/system-prompt": "3.1.3",
+    "@qilin-agent/tools": "3.1.3",
+    "@qilin-agent/user-approval": "3.1.3"
+  },
+  "dependencies": {
+    "@qilin-agent/schemastery": "~3.18.3"
+  },
+  "devDependencies": {
+    "@qilin-agent/kylin": "~4.0.3",
+    "@qilin-agent/agent-loop": "3.1.3",
+    "@qilin-agent/agent": "3.1.3",
+    "@qilin-agent/jobs": "3.1.3",
+    "@qilin-agent/app-boot": "3.1.3",
+    "@qilin-agent/jobs-local": "3.1.3",
+    "@qilin-agent/llm": "3.1.3",
+    "@qilin-agent/loader-smoke": "3.1.3",
+    "@qilin-agent/sandbox": "3.1.3",
+    "@qilin-agent/pwsh-local": "3.1.3",
+    "@qilin-agent/sandbox-policy": "3.1.3",
+    "@qilin-agent/shell-env": "3.1.3",
+    "@qilin-agent/system-prompt": "3.1.3",
+    "@qilin-agent/subprocess-local": "3.1.3",
+    "@qilin-agent/tool-jobs": "3.1.3",
+    "@qilin-agent/shell": "3.1.3",
+    "@qilin-agent/session-projection": "3.1.3",
+    "@qilin-agent/tools": "3.1.3",
+    "@qilin-agent/user-approval": "3.1.3"
+  }
 }