ShellPilot

Author(s)

• raandree

Tags

GitHubCopilot Copilot AI LLM Chat Agent

Functions

Clear-ShpChat Clear-ShpContext Clear-ShpRedactionPolicy Clear-ShpToolPolicy Clear-ShpUsage Compress-ShpChat ConvertTo-ShpAnnotation ConvertTo-ShpTokenCount Get-ShpChat Get-ShpContext Get-ShpCosineSimilarity Get-ShpCostEstimate Get-ShpDefault Get-ShpMcpServer Get-ShpModel Get-ShpModelName Get-ShpRedactionPolicy Get-ShpTool Get-ShpToolPolicy Get-ShpUsage Initialize-Shp Invoke-Shp Invoke-ShpBatch Register-ShpMcpServer Register-ShpTool Request-ShpEmbedding Resolve-ShpError Select-ShpModel Set-ShpContext Set-ShpRedactionPolicy Set-ShpToolPolicy Start-ShpChat Test-ShpCiReadiness Unregister-ShpMcpServer Unregister-ShpTool

PSEditions

Core

Dependencies

This module has no dependencies.

Release Notes

## [0.4.0-preview0014] - 2026-09-07

### Security

- Correct embedding backend precedence and prevent a Copilot Session token
 from reaching a keyless alternative backend. Environment-selected backends
 now use the shared resolver. See [embeddings](README.md#embeddings-and-similarity).
- Apply protected environment-assignment checks to colon-bound PowerShell
 parameter arguments as well as separate arguments.

- Limit `run_command` to a minimal environment and refuse execution-sensitive
 literal environment assignments before child startup, even without a Tool
 policy. See [command environment](README.md#command-environment).

- **Protect Unix `edit_file` staging from creation.** Apply the source file
 mode when creating the empty temporary file, before any content is copied,
 so a private source is not temporarily exposed through default permissions.

- **Keep `edit_file` on the target approved by the tool policy.** Repointing
 the original directory alias after authorization no longer redirects the
 edit to a different file. Confirmation names the authorized target. Refuse
 special files again after staging so a named-pipe swap cannot block the
 final content check. External filesystem races remain outside the tool's
 guarantees.

- **Tool policy refuses paths when link resolution fails.** A missing runtime
 API or filesystem error no longer leaves an unresolved path eligible for
 Read or Write access. This prevents a junction inside an allowed directory
 from bypassing rules for its destination on an unsupported runtime.

- **A disabled tool can no longer be executed.** `-DisableTerminal`,
 `-DisableFileAccess`, `-DisableBrowsing`, `-DisableUserPrompts` and
 `-DisableTodoList` removed a tool from the set offered to the model, but the
 dispatch switch matched built-in tool names unconditionally — so a model that
 named a disabled tool anyway, from its own priors or from a replayed history,
 had it run. `-DisableTerminal` bounded what was advertised and nothing about
 what executed.

 Dispatch now refuses any built-in that this call did not offer, before the
 tool runs. The refusal reuses the existing tool-policy path: the `tool.call`
 event carries `policy = denied`, the reason names the disabled tool, the call
 appears on `ToolCallsDenied`, and the model receives `{"denied": "..."}` so it
 can choose another route instead of failing the turn. The offered set is
 derived from the assembled tool list rather than re-tested against each
 switch, so a tool added later cannot be offered under one condition and
 dispatched under another.

- **`Register-ShpTool` refuses a built-in tool name.** Dispatch matches built-in
 names before it consults the user tool table, so registering `run_command`,
 `read_file` or any other built-in produced a tool that was advertised to the
 model and then silently ignored while the built-in ran instead — with the
 caller believing it had replaced it. An attached MCP server has always been
 refused a colliding name; a local registration now fails the same way, loudly
 and at registration time. Choose a distinct `-ToolName`.

### Added

- Add opt-in `-DeferredToolLoading` to `Invoke-Shp` and `Invoke-ShpBatch` for
 Turn-local User/MCP schema search with `search_tools`. Keep fixed built-ins
 and explicit `-Tool` selections eager, with exclusion winning. Reserve the
 `search_tools` registration name and add deferred availability/loading result
 members. This is a schema-cost option, not authorization, containment, or
 prompt-injection defense. See [deferred loading](specs/031-deferred-tool-loading.md).

- Add explicit `-GitHubHost`, Session context, and `SHELLPILOT_GITHUB_HOST`
 routing for GitHub Enterprise Cloud on GHE.com, with validated HTTPS origins,
 host-specific Session-token caching, and readiness reporting. Preserve
 GitHub.com defaults and the bounded child transport allowlist. See
 [enterprise host configuration](README.md#enterprise-cloud-host).

- Add the per-call `Invoke-Shp -Mode Plan` read-only preset, intersecting caller
 filters and the unchanged session Tool policy. Withhold mutation, terminal,
 User, MCP, and interactive-question tools. See
 [Plan mode and its limits](README.md#read-only-plan-mode).

- Add exact `-Tool` and `-ExcludeTool` visibility filters to `Invoke-Shp` and
 `Invoke-ShpBatch`, covering built-in, User, and MCP names with exclusion
 winning. Withdrawn tools retain the existing denial contract. See
 [tool visibility](README.md#tool-visibility).

- Add `Set-ShpRedactionPolicy -SecretEnvironmentVariable` for current literal
 values in outgoing text and Event records, with names-only reporting and
 batch/job replay. See [named secret redaction](README.md#named-secret-redaction).

- Add the maintainer-selected [MIT license](LICENSE) and document stable and
 prerelease [Gallery installation](README.md#install). Bundle the same license
 text in built modules and packages.

- **Add explicit estimated budgets for trusted owned requests.** Opt into
 `RequestBudgetMode provider-estimate` for non-refundable reservations and
 upward reconciliation; default verified counters keep their meaning.
 Add the bounded Claude child provider/counting path, pre-generation host
 admission, and secret-free reported/partial Usage. No automatic retries,
 Model substitution, or invoice guarantee is implied. See
 [the transport contract](specs/030-host-request-transport.md).

- **Add conditional admission limits to owned `Invoke-Shp` transport.**
 `RequestLimits` and a trusted `RequestTokenCounter` reserve input, maximum
 output, and Engine-priced cost before dispatch. Unknown or failed Usage
 retains its reservation and stays explicitly unknown in results, events,
 and summaries. No verified Copilot counter or complete child runtime is
 supplied; ordinary calls are unchanged. See
 [the contract and limitations](specs/030-host-request-transport.md).

- **Add optional host transport groundwork to `Invoke-Shp`.** Use
 `NoAutomaticRetry` to disable transport and API-shape resends, or
 `RequestTransport` for a credentialless Tool-calling loop with a trusted
 caller-owned transport. Ordinary calls are unchanged. Hard request admission,
 process isolation, and a trusted transport process are not supplied by these
 options. See [the contract and limitations](specs/030-host-request-transport.md).

- **Add `edit_file` for targeted changes to existing files.** Replace one
 exact, case-sensitive `oldString` with `newString`, refusing zero matches or
 multiple matches with recovery guidance. Preserve the BOM, encoding and
 unchanged line endings for UTF-8 and BOM-marked UTF-16/UTF-32; refuse
 malformed or unsupported text instead of converting it. The tool is disabled
 by `-DisableFileAccess`, and reports the intended edit without writing under
 `-WhatIf`.

 When a tool policy is set, an edit needs both a `Read()` and a `Write()` rule
 covering the target, and a deny in either kind refuses it. Match counts
 disclose file content even when the replacement is identical, so `Write()`
 alone would turn the tool into a way to confirm guesses about a file the
 policy never granted read access to. `write_file` and `create_directory` are
 unchanged and still need only `Write()`.

 Only regular, seekable files are eligible, and input and output are each
 capped at 8 MiB including the BOM. Unix file types are checked directly,
 avoiding a hang when formatted permissions misidentify a named pipe as a
 regular file. The edit is staged in the target's own
 directory, flushed, checked against the file's current bytes, and then put in
 place with a backup of the original. A native replacement failure that moves
 the original away retains the backup and reports `recoveryPath` for manual
 recovery instead of deleting the remaining copy. Cleanup is best effort.
 Detected concurrent changes are refused; the final check and replacement
 are not a compare-and-swap guarantee.
 See [README.md](README.md#agent-tools-on-by-default).

- **`glob_files` and `grep_files` let the model search without a shell.**
 `glob_files` finds files by name pattern under a directory; `grep_files`
 searches their contents and returns only the path, line number and matching
 line, leaving `read_file` to read around a hit. Both are offered with the
 other file tools and withdrawn by `-DisableFileAccess`.

 Both are governed by the existing `Read()` rules of `Set-ShpToolPolicy`, and
 that is the point: until now the only way to make the model *find* something
 was `run_command`, so a policy tight enough to be worth setting had to grant
 `Shell(...)` — far more reach than searching needs. `Set-ShpToolPolicy -Rule
 'Read(./**)'` is now enough to let the model locate a file by name or by
 content while `run_command` stays denied.

 Every returned hit is policy-checked, not just the search root, because a
 glob rooted at an allowed directory can still match a path that resolves,
 through a link, to somewhere no rule covers. An excluded hit is counted in
 `excludedByPolicy` rather than dropped silently. Both results are bounded —
 files examined, matches returned, and characters returned — and set
 `truncated` when any cap bites, so the model narrows the pattern instead of
 overflowing the context window.

- **`ConvertTo-ShpAnnotation` surfaces structured findings in CI.** Pipe a
 `ShellPilot.Result` from `Invoke-Shp -JsonSchema`, or any plain finding
 object, into the cmdlet to produce GitHub Actions annotations, Azure DevOps
 `task.logissue` commands, or readable text. `Level`, `Path`, `Line`,
 `Column`, `Title`, and `Message` are matched case-insensitively and can be
 redirected with `-PropertyMap`; an unknown or missing level is always a
 warning. Vendor-specific escaping keeps newlines and delimiters from
 corrupting a workflow command. Output stays on the success stream unless
 `-Emit` writes it to the host, and `-Summ