# v0.5 - Read-Only PowerShell Helper

Release date: 2026-07-02

## Summary

V0.5 adds a constrained PowerShell cmdlet helper for agents that need structured output from read-only PowerShell operations. It does not change the Application-only boundary of `Invoke-AgentCommand.ps1`.

The package is published on npm as `@agent-shells/powershell-skills`.

## Added

- `core/scripts/Invoke-AgentPowerShell.ps1`.
- Structured JSON spec support:

```json
{
  "cmdlet": "Test-Path",
  "parameters": {
    "LiteralPath": "C:\\path with space\\file.txt"
  },
  "cwd": "C:\\workspace",
  "timeout_seconds": 15,
  "risk": "normal"
}
```

- Allowlisted read-only cmdlets:
  - `Test-Path`
  - `Resolve-Path`
  - `Get-Item`
  - `Get-ChildItem`
  - `Get-Content`
  - `Get-Command`
  - `Get-Location`
  - `Get-Process`
  - `Get-Service`
  - `Select-String`

## Safety Boundaries

- Rejects aliases such as `gci`.
- Rejects functions and non-cmdlet commands.
- Rejects cmdlets outside the read-only allowlist.
- Rejects parameters outside each cmdlet's parameter allowlist.
- Rejects destructive risk.
- Uses timeout handling for bounded execution.
- Produces JSON with status, stdout, stderr, output, timeout, duration, and classification fields.
- Handles Windows npm `.cmd` dispatch in the CLI so `doctor` and `update` can run without shell deprecation warnings.

## Verification

```powershell
npm test
npm pack --dry-run
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\verify-v0.1.ps1
pwsh -NoProfile -ExecutionPolicy Bypass -File .\scripts\verify-v0.1.ps1 -PowerShellExe pwsh
```

## Install

```powershell
npm install -g @agent-shells/powershell-skills
powershell-skills install all
powershell-skills doctor
```

## Boundaries

- This is not an unrestricted PowerShell runner.
- It does not execute free-form script text.
- It does not execute destructive commands.
- It does not bypass agent, OS, workspace, or user permission rules.