Repository navigation
Invoke‑Shp
Sends a prompt to GitHub Copilot and returns the response with usage and cost.
Invoke-Shp [-Model <String>] -Prompt <String> [-SystemPrompt <String>] [-AppendSystemPrompt <String>]
[-InstructionPath <String[]>] [-InstructionRoot <String[]>] [-SkillPath <String[]>] [-DisableBrowsing]
[-Mode <String>] [-Tool <String[]>] [-ExcludeTool <String[]>] [-DeferredToolLoading] [-ContextReport]
[-ToolResultSpillRoot <String>] [-ToolResultSpillThresholdChars <Int32>] [-SaveChatPath <String>]
[-AllowPrivateNetwork] [-DisableFileAccess] [-DisableTerminal] [-CommandEnvironmentVariable <String[]>]
[-DisableUserPrompts] [-DisableRedaction] [-NonInteractive] [-ShowThinking] [-DisableStreaming]
[-MaxToolIterations <Int32>] [-MaxContextWindowTokens <Int32>] [-MaxBudgetUSD <Double>] [-FailOn <String[]>]
[-ReasoningEffort <String>] [-MaxOutputTokens <Int32>] [-Temperature <Double>] [-TopP <Double>]
[-Seed <Int32>] [-History <Object[]>] [-Image <String[]>] [-Attachment <String[]>] [-ResponseFormat <String>]
[-JsonSchema <String>] [-DisableUserTools] [-DisableMcp] [-DisableTodoList] [-DisableProgressEvents]
[-EventStream <String>] [-TraceParent <String>] [-AsJob] [-UseServerSideState] [-ApiBase <String>]
[-TimeoutSec <Int32>] [-MaxRetryCount <Int32>] [-NoAutomaticRetry] [-RequestTransport <ScriptBlock>]
[-ToolCallControl <Hashtable>] [-ExecutionContract <ScriptBlock>] [-RequestLimits <Hashtable>]
[-RequestTokenCounter <ScriptBlock>] [-RequestBudgetMode <String>] [-RetryDelaySec <Int32>]
[-NetworkOutageToleranceSec <Int32>] [-TokenPath <String>] [-GitHubHost <String>] [-EditorVersion <String>]
[-PluginVersion <String>] [-UserAgent <String>] [-IntegrationId <String>]
[-WhatIf] [-Confirm] [<CommonParameters>]
Invoke-Shp [-Model <String>] -Prompt <String> [-AppendSystemPrompt <String>] [-SystemPromptPath <String[]>]
[-InstructionPath <String[]>] [-InstructionRoot <String[]>] [-SkillPath <String[]>] [-DisableBrowsing]
[-Mode <String>] [-Tool <String[]>] [-ExcludeTool <String[]>] [-DeferredToolLoading] [-ContextReport]
[-ToolResultSpillRoot <String>] [-ToolResultSpillThresholdChars <Int32>] [-SaveChatPath <String>]
[-AllowPrivateNetwork] [-DisableFileAccess] [-DisableTerminal] [-CommandEnvironmentVariable <String[]>]
[-DisableUserPrompts] [-DisableRedaction] [-NonInteractive] [-ShowThinking] [-DisableStreaming]
[-MaxToolIterations <Int32>] [-MaxContextWindowTokens <Int32>] [-MaxBudgetUSD <Double>] [-FailOn <String[]>]
[-ReasoningEffort <String>] [-MaxOutputTokens <Int32>] [-Temperature <Double>] [-TopP <Double>]
[-Seed <Int32>] [-History <Object[]>] [-Image <String[]>] [-Attachment <String[]>] [-ResponseFormat <String>]
[-JsonSchema <String>] [-DisableUserTools] [-DisableMcp] [-DisableTodoList] [-DisableProgressEvents]
[-EventStream <String>] [-TraceParent <String>] [-AsJob] [-UseServerSideState] [-ApiBase <String>]
[-TimeoutSec <Int32>] [-MaxRetryCount <Int32>] [-NoAutomaticRetry] [-RequestTransport <ScriptBlock>]
[-ToolCallControl <Hashtable>] [-ExecutionContract <ScriptBlock>] [-RequestLimits <Hashtable>]
[-RequestTokenCounter <ScriptBlock>] [-RequestBudgetMode <String>] [-RetryDelaySec <Int32>]
[-NetworkOutageToleranceSec <Int32>] [-TokenPath <String>] [-GitHubHost <String>] [-EditorVersion <String>]
[-PluginVersion <String>] [-UserAgent <String>] [-IntegrationId <String>]
[-WhatIf] [-Confirm] [<CommonParameters>]
Obtains a Copilot session token, sends -Prompt to the chat API (falling back to the responses API for models that require it), streams the reply to the host by default, and runs a tool-calling loop that lets the model fetch web pages, read/list/search/create/write/edit local files, run shell commands, and ask the user questions on the console. All four tool categories are on by default; turn them off individually with -DisableBrowsing (the fetch_url tool), -DisableFileAccess (read_file / list_directory / glob_files / grep_files / write_file / edit_file / create_directory), -DisableTerminal (run_command), and -DisableUserPrompts (ask_user). Pass -DisableStreaming for a single buffered reply instead of live token streaming.
For an unattended run, pass -NonInteractive (implied by a truthy $env:CI): it withdraws ask_user and turns any would-be prompt into a terminating error instead of a wait. In CI the call also has to name a backend - see Test-ShpCiReadiness.
Point -SkillPath at one or more skill roots and/or -InstructionRoot at one or more instruction roots to let the model discover skills and *.instructions.md files by name and description and pull the full body on demand (progressive disclosure).
The returned object includes the answer text, token usage, an estimated USD cost and credit count (from the module price table), the tool calls executed, timing, and the raw response. Every call is also appended to the per-session usage log (see Get-ShpUsage).
Nothing here is fatal by default: a budget stop, a truncated reply and an empty answer all come back as data on that object. Pass -FailOn to turn named outcomes into terminating errors instead, so an unattended pipeline step fails rather than shipping a half-finished artifact.
The -Model parameter supports tab-completion backed by Get-ShpModelName.
Invoke-Shp -Prompt 'Hello in one sentence.'
Sends a simple prompt using the default model.
Invoke-Shp -Model claude-haiku-4.5 -Prompt 'Summarise PowerShell splatting in 2 lines.'
Selects a specific (cheaper) model for the request.
Invoke-Shp -Prompt 'What changed on https://github.com/PowerShell/PowerShell today?'
Browsing is on by default, so the model can use the fetch_url tool to read the page before answering.
Invoke-Shp -Prompt 'Summarise PowerShell splatting in 2 lines.' -DisableBrowsing
Disables the fetch_url tool for a pure offline-style completion.
Invoke-Shp -Prompt 'Review the error handling in .\ShellPilot\ShellPilot.psm1 and suggest improvements.'
File access is on by default, so the model can call read_file (and list_directory to discover paths) to read the file before answering. The returned object's FilesRead lists what it actually read.
Invoke-Shp -Prompt 'Explain this prompt.' -DisableFileAccess
Disables the file tools (read_file / list_directory / glob_files / grep_files / write_file / edit_file / create_directory) for this call.
Invoke-Shp -Prompt 'Worum geht es in dieser Mail?' -Attachment '.\flight-delay.msg'
Attaches a file of any format. A .msg is an OLE2 compound file, so it is not decoded here: the model is told the path, the size, that the leading bytes are d0 cf 11 e0 a1 b1 1a e1, and that it should decode the file itself - which it can, using read_file and run_command.
Invoke-Shp -Prompt 'Fasse beide Belege zusammen.' -Attachment '.\boarding.jpg', '.\notes.md'
Mixes formats in one call. The image goes down the vision path and the Markdown is inlined into the prompt; the result's Attachments member reports how each one was classified and whether it was truncated.
Invoke-Shp -Prompt 'Refactor this loop.' -SystemPrompt 'You are a terse senior PowerShell engineer. Reply with code only, no prose.'
Adds an ad-hoc (literal) system instruction on top of the built-in persona.
Invoke-Shp -Prompt 'Refactor this loop.' -SystemPromptPath 'C:\Users\me\.copilot\agents\Software Engineer Agent.agent.md'
Reads the system prompt from a file (front-matter stripped) instead of passing literal text. Mutually exclusive with -SystemPrompt.
Invoke-Shp -Prompt 'Write a function to parse a CSV.' -InstructionPath .\.github\instructions\powershell.instructions.md, .\Skills\style\SKILL.md
Loads two customisation files - a VS Code instruction file and a skill - strips their YAML front-matter, and injects both bodies into the system prompt.
Invoke-Shp -Prompt 'Convert this docx to markdown.' -SkillPath C:\Users\me\.copilot\skills
Discovers every skill under the folder, shows the model their names and descriptions, and lets it call the load_skill tool to pull the full SKILL.md body of whichever skill is relevant (progressive disclosure).
Invoke-Shp -Model claude-opus-4.8 -Prompt 'Prove there are infinitely many primes.' -ReasoningEffort max
Requests maximum reasoning effort (the model picker's "Max") so the model thinks harder before answering. Pair with -MaxOutputTokens to cap the reply length.
Invoke-Shp -Model claude-opus-4.8 -Prompt 'Write a 2000-word essay on PowerShell.' -MaxOutputTokens 64000
Streaming is on by default, so the reply prints live to the host and the output ceiling is the model's streaming maximum (64000 tokens) rather than the 16000-token non-streaming cap. Add -DisableStreaming for a single buffered reply.
Invoke-Shp -Prompt "Score this answer 0-1 and reply with only the number.`n$answer" -Temperature 0 -DisableBrowsing -DisableFileAccess -DisableTerminal -DisableUserPrompts
Grades an answer reproducibly. -Temperature 0 makes the judgement near-deterministic, so rerunning the same grading call yields the same verdict and the grader itself stops contributing variance to the measurement.
1..5 | ForEach-Object { (Invoke-Shp -Prompt 'Name one PowerShell cmdlet.' -Temperature 0.7 -Seed 1234).Content }
Measures the spread of a prompt at a realistic operating temperature. -Temperature controls how much variation the model is allowed and -Seed asks for best-effort repeatability of the sequence, so the observed spread reflects the prompt rather than an unpinned sampler.
Invoke-Shp -Prompt 'Which files in this folder are larger than 1 MB? Use the terminal.'
Terminal access is on by default, so the model can call the run_command tool to run a shell command and read its output before answering. The returned object's CommandsRun lists what it executed. Pass -DisableTerminal to forbid shell access.
Invoke-Shp -Prompt 'Write a function following our standards.' -InstructionRoot ~/.copilot/instructions
Offers the model every *.instructions.md under the folder by name and description and lets it call load_instruction to pull the relevant ones itself (progressive disclosure), instead of forcing every file into the prompt with -InstructionPath.
Invoke-Shp -Prompt 'Rename my photos sensibly.'
Get-ShpUsage -Summary
The model may use the ask_user tool to ask a clarifying question on the console (answer it and it continues). Afterwards Get-ShpUsage -Summary reports the tokens, cost and credits the session has spent.
Invoke-Shp -Prompt 'What is 43 + 43?'
Invoke-Shp -Prompt 'What was the result of the last prompt?'
Continues a conversation: the second call automatically remembers the first because Invoke-Shp records every call into the running session chat and seeds the next call from it. To start over, run Clear-ShpChat.
$r1 = Invoke-Shp -Prompt 'Pick a number between 1 and 10.'
$r2 = Invoke-Shp -Prompt 'Now double it.' -History $r1.History
Continues a conversation explicitly, with no hidden state, by passing the prior result's History back in. -History bypasses the session chat entirely - handy in scripts and pipelines where each invocation must be self-contained.
try {
$r = Invoke-Shp -Prompt 'Summarise the release notes.' -MaxBudgetUSD 0.50 `
-FailOn BudgetExceeded, Truncated, NoContent -DisableTerminal -DisableUserPrompts
$r.Content | Set-Content summary.md
} catch {
Write-Host "::error::$($_.Exception.Message)"
Write-Host "condition: $($_.FullyQualifiedErrorId) spent: $($_.TargetObject.CostUSD)"
exit 1
}
The CI wrapper. ShellPilot raises a terminating error and stops there - it never calls exit and never sets $LASTEXITCODE, because a module that terminates its host cannot be composed - so the step's exit code is the caller's job. The error id tells the wrapper which condition fired and TargetObject still carries what the abandoned turn cost.
$env:SHELLPILOT_API_BASE = 'https://models.example.com/v1'
$env:SHELLPILOT_API_KEY = $secretFromTheVault
Invoke-Shp -Prompt 'Review the diff on stdin.' -NonInteractive
The supported unattended profile. The environment names an OpenAI-compatible endpoint, so the run never touches the Copilot backend and passes the CI gate; -NonInteractive is redundant on a runner that already sets $env:CI and is spelled out here for a scheduled task that does not. Check the whole profile first with Test-ShpCiReadiness.
Invoke-Shp -Prompt 'Audit the build log.' -EventStream ./shp-events.jsonl -NonInteractive
Get-Content ./shp-events.jsonl | ConvertFrom-Json | Where-Object type -eq 'tool.call'
The headless profile. Every step of the turn is appended to the stream as one JSON object per line, so a CI log collector reads what happened without parsing prose - and a run killed mid-turn still leaves a file that parses up to its last complete line.
$job = Invoke-Shp -Prompt 'Summarise the repository.' -AsJob -EventStream ./shp-events.jsonl
$r = Receive-Job -Job $job -Wait -AutoRemoveJob
$r.Content
The job model. Receive-Job hands back the very same ShellPilot.Result a synchronous call would have returned, and -AsJob does not turn the event stream off - the job writes it.
Let the fetch_url tool reach loopback, link-local and private (RFC 1918) addresses. Blocked by default, because any untrusted page or file the model has read could otherwise steer it into fetching cloud metadata (169.254.169.254), a loopback admin port, or an intranet host. Turn this on only when you are deliberately pointing the model at a trusted internal service.
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: FalseOverride the API base URL for this call (opt-in alternative backend). Falls back to the session context (Set-ShpContext) and then to the Copilot session endpoint. An alternative backend resolves no GitHub OAuth token and exchanges no Copilot Session token, so it needs no GitHub sign-in and can never be sent a Session token; supply its own credential with Set-ShpContext -ApiKey or $env:SHELLPILOT_API_KEY.
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: FalseExtra system instructions (literal text) added after -SystemPrompt or -SystemPromptPath. Unlike -SystemPrompt this belongs to no parameter set, so a file-driven system prompt can still be topped up with a line of inline guidance for a single call.
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: FalseRun the call in a background thread job and return the job object immediately. Receive-Job resolves it to the same ShellPilot.Result the synchronous call would have returned - a thread job runs in the same process, so nothing is serialised.
The job gets a copy of the session context, session defaults, cached model limits, tool policy, redaction policy and registered tools, but it runs STATELESS against the session conversation: it is seeded from a snapshot of the session chat and does not write back, because a job finishing at an arbitrary time must not race the caller's next call. The constituted conversation is still on the result's History member. Attached MCP servers do not travel into a job. -EventStream is honoured: the job writes the stream.
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: FalseOne or more files of ANY format to attach to the prompt. Each file is classified by its content rather than its extension and routed:
- An image joins the vision path, exactly as -Image would.
- A text file (any encoding) is decoded and inlined into the prompt, capped per file with a truncation marker.
- Anything else is described rather than decoded: the model is given the absolute path, the size, the format identified from the file's magic number, and a hex preview of the head - enough to recognise the format and decode the file itself with read_file and run_command.
ShellPilot deliberately converts nothing. A converter table would need a dependency and a new extractor per format, while the model already has the tools and only lacks the first bytes. A binary attachment therefore needs file or terminal access to be useful; a warning is emitted when both are disabled.
Attachment content is inserted into the USER message and framed as data, never as a system instruction, because a document is untrusted content. Use Set-ShpToolPolicy to bound what the model may then do.
Type: String[]
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: FalseAdditional parent environment variable names to pass to run_command. The child otherwise receives only a minimal platform base. Names are explicit, not wildcard patterns; passing a credential exposes it to the child. This reduces inheritance but does not provide containment.
Type: String[]
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: FalseAttach a Context report to the result, attributing the estimated outgoing Context tokens of the request this Turn actually made to the system content, the caller's instructions, the Skill and Instruction catalogs, the offered Tool schemas, attachments, the conversation, the prompt and the Tool results, under one documented estimator. Off by default and purely local: it adds no request and no round-trip. The result carries the report on ContextReport, which is $null without the switch. See Get-ShpContextReport for the same accounting before a call.
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: FalseOpt into Turn-local loading of eligible registered User and MCP schemas through search_tools. Fixed built-ins stay eager. With an explicitly bound Tool parameter, selected dynamic schemas also stay eager. ExcludeTool, Plan, disabled categories, and MCP Server state only narrow eligibility. Search reads the Frozen tool list without contacting a Server or invoking a User tool. Matches become callable on the next request, never later in the same model response, and are not retained across calls. Search accepts a nonblank query up to 512 characters and maxResult (default 5, capped at 20). Results expose DeferredToolLoading, DeferredToolsAvailable, and DeferredToolsLoaded; existing availability members still describe eligible registrations. Reduces schema cost; it is not authorization, containment, or prompt-injection defense.
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: FalseTurn off web browsing. By default the fetch_url tool is exposed to the model so it can retrieve web content; this switch disables it.
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: FalseTurn off local file access. By default the read_file, list_directory, glob_files, grep_files, write_file, edit_file and create_directory tools are exposed to the model so it can read, list, search, create, write and edit files and folders (with the caller's own privileges, no path sandboxing); this switch disables all of them.
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: FalseDo not offer the tools of MCP servers attached with Register-ShpMcpServer for this call. MCP tools appear only after a server is attached, so the default posture is already "no MCP"; this switch suppresses attached servers for one call, the same way -DisableUserTools does for registered commands.
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: FalseSuppress the structured ShpProgress Information-stream records that Invoke-Shp otherwise emits for every tool call (Kind 'ToolCall') and every todo-list update (Kind 'TodoList'). These records let a host render live tool activity without parsing the -ShowThinking host trace, and are silent on the console under the default InformationPreference. Pass this switch to turn them off. It does not affect -EventStream, which is a separate sink with its own switch.
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: FalseTurn off egress redaction. By default, immediately before each round-trip, the accumulated conversation - the prompt, any inlined -Attachment text, and every tool result (run_command / read_file / fetch_url output, an MCP or user-tool result) - is scanned for common secret shapes (GitHub tokens, AWS access key ids, PEM private-key blocks, JWTs, basic-auth URL credentials, and connection-string password fields) and a match is replaced with a stable, named placeholder such as [redacted:github-token]. The model's own reply is never touched. This switch sends the turn verbatim instead, exactly as before egress redaction existed. Use Set-ShpRedactionPolicy to add patterns rather than turning the control off entirely; see the result's Redactions member for what actually matched (pattern name and count only, never the matched value).
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: FalseTurn off live streaming. By default Invoke-Shp streams the reply token-by-token to the host over Server-Sent Events on /chat/completions, giving the live "typing" experience and lifting the output ceiling to the model's streaming maximum (for example claude-opus-4.8 allows 64000 output tokens streamed versus only 16000 non-streaming). Pass this switch to disable streaming and receive a single buffered reply instead; note this also lowers that output cap. The streamed text is host-only and never enters the pipeline; the full reply is always returned on the result's Content member. -ShowThinking now PREFERS streaming, because the streaming /chat/completions response carries the model's live reasoning trace; pass -DisableStreaming together with -ShowThinking only if you want the buffered /responses reasoning-summary path instead.
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: FalseTurn off terminal access. By default the run_command tool is exposed to the model so it can run shell commands in a child PowerShell (with the caller's own privileges and no sandboxing, in the session's current directory); this switch disables it. Disable it for untrusted prompts - full terminal access lets the model run arbitrary commands.
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: FalseDo not offer the model the built-in manage_todo_list tool. By default the tool is offered so the model can maintain a short ordered checklist of sub-tasks for a multi-step request (exactly one item in-progress at a time), the final normalised list is returned on the result's TodoList member, and a TodoList progress event is emitted on each update. Pass this switch to suppress the tool and its built-in planning guidance.
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: FalseTurn off interactive questions. By default the ask_user tool is exposed to the model so it can pause and ask you a clarifying question on the console (your answer is fed back into the conversation); this switch disables it. With no interactive console the tool reports that it could not get an answer instead of blocking, so this switch is mainly for forcing the model to proceed without ever asking.
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: FalseDo not offer the user-defined tools registered with Register-ShpTool for this call. By default any registered tool is exposed to the model.
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: FalseEditor-Version header value sent with the request.
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: $script:DefaultEditorVersion
Accept pipeline input: False
Accept wildcard characters: FalseWrite a headless JSONL event stream to this path - one JSON object per line, appended as it happens, covering the turn start, every model request, each streamed reasoning chunk under -ShowThinking, every tool call and result, usage, retries, errors and the final answer. Pass '-' to write the lines to the Information stream (tag 'ShpEvent') instead of a file.
Every record carries schemaVersion, a monotonic sequence, an ISO 8601 UTC timestamp, a type and a flat data object; see spec 027 for the type-to-data table. Because each line is appended whole, a run killed mid-turn still leaves a file that parses up to its last complete line. A later call appending to a valid stream continues its sequence. Use a distinct path for each concurrently running call.
Streamed reasoning boundaries are preserved, but their records flush after the model request finishes (successfully or with an error) so the complete available trace can be redacted before it is divided back into chunks. This catches secrets split by an SSE frame boundary.
Every string in every payload goes through the same redaction seam the request body does, so a secret in a tool result does not reach the stream verbatim (-DisableRedaction turns that off here too). A run_command tool-call event records the tool name and the policy decision but never the command line, which is where a credential passed on a command line would otherwise land.
Every record also carries the call's trace identity - traceId, spanId, parentSpanId, runId and turnId - so the stream translates into spans with ConvertTo-ShpOtelTrace without a correlation table.
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: FalseExact tool names to remove after Tool inclusion and category switches. Exclusion wins and never re-enables a disabled tool. A model attempting a withdrawn tool receives the existing disabled-tool denial.
Type: String[]
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: FalseCaller-supplied execution and containment contract for the four dispatch paths that act outside this process: the Terminal tool, a file mutation (write_file, edit_file, create_directory), a User tool and an MCP tool. Read-only tools stay on the native path.
The scriptblock receives one typed, versioned, detached request naming the kind of work, the resolved target and the effective arguments, and returns either @{ Executed = $true; Result = '' } or @{ Denied = $true; Reason = '...' }. It sees only work the Tool policy and any decision control already allowed, so it cannot widen either.
THIS IS A SEAM, NOT A SANDBOX. ShellPilot provides no process, file system or network isolation of its own; the contract is where a caller connects their own containment - a container, a constrained runspace, a broker process, a jump host. Unbound, dispatch stays exactly the native path it has always been. Bound, a contract that fails is a refused dispatch: there is deliberately no fallback to native execution.
Type: ScriptBlock
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: FalseTurn one or more disappointing outcomes into a TERMINATING error, so an unattended step fails instead of exiting 0 on an answer that never arrived. Omit it and nothing changes: a budget stop stays a warning plus the BudgetExceeded property, and every other condition below stays a plain result you inspect yourself.
Accepts any combination of:
- BudgetExceeded - the -MaxBudgetUSD cap stopped the tool-calling loop. Error id ShpBudgetExceeded.
- Truncated - the model hit its output cap (FinishReason 'length'). Error id ShpTruncated. This is a chat-shape finish reason; the responses shape reports a status instead, so pair it with the chat shape (the default) rather than -UseServerSideState.
- ToolIterationLimit - the loop hit -MaxToolIterations. Error id ShpToolIterationLimit. This case already threw; listing it only upgrades the opaque throw to a branchable error id.
- NoContent - the reply is empty. Error id ShpNoContent. Tested on the Content member you receive, so a turn that wrote files and returned no message does NOT trip it: the file-work summary counts as content.
- SchemaMismatch - -JsonSchema was supplied and the reply either did not parse, leaving ContentObject null, or parsed and then broke the schema. Error id ShpSchemaMismatch. Armed by -JsonSchema only; -ResponseFormat json_object on its own has no schema to mismatch. Conformance is checked locally against a documented subset of JSON Schema. A schema using keywords outside that subset is reported as unchecked on ContentSchemaChecked and never trips this condition, because no mismatch was established.
Conditions are tested in the order listed and the first match throws, so an empty reply under -FailOn NoContent, SchemaMismatch reports ShpNoContent.
FullyQualifiedErrorId is ',Invoke-Shp' - branch on that rather than on the message text. The turn's whole result is carried on the error's TargetObject, because a -FailOn stop happens after the turn was billed: the cost, the usage log entry, the session chat and any partial content are all unchanged, and only the OUTPUT becomes an error.
This module never calls exit and never sets $LASTEXITCODE - a module that terminates its host is a module you cannot compose. Wrap the call yourself; see the CI example below.
Type: String[]
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: FalseHTTPS GitHub.com or Enterprise Cloud GHE.com authentication origin. Explicit value wins over Session context, SHELLPILOT_GITHUB_HOST, and the GitHub.com default. The resolved host is fixed for this call and used on every Session-token exchange. RequestTransport refuses this native credential option; the CI backend gate remains unchanged.
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: FalseAn explicit conversation history to continue from, as returned on a previous result's History property (an array of objects with role and content members). Use this for stateless, scriptable multi-turn flows: when supplied it seeds this call (taking precedence over the module-scoped session chat) and the call does NOT read or write the session chat.
By default - when -History is not supplied - Invoke-Shp seeds each call from the running session conversation (see Get-ShpChat), so follow-up prompts remember earlier turns automatically. Reset the running conversation with Clear-ShpChat to start a fresh chat.
Type: Object[]
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: True (ByPropertyName)
Accept wildcard characters: FalseOne or more image file paths or http(s) URLs to send with the prompt for vision-capable models. Each local file is embedded as a base64 data URI; each URL is passed by reference. Forces the chat API shape.
Only image files are accepted (.bmp, .gif, .jpeg, .jpg, .png, .webp). For any other format use -Attachment, which takes a file of any kind.
The service refuses a whole request body over 5 MiB and base64 costs 4 bytes per 3, so an ordinary phone photo is already over the ceiling. Rather than fail the call, an oversized image is re-encoded to fit, and resolution is the LAST thing given up: JPEG quality is reduced first at full size, and dimensions only change when compression alone cannot reach the budget. A warning always says what it cost, and specifically warns about small text when the dimensions changed - measured, a scanned page that read correctly at full size returned a confidently WRONG reference number once scaled to 1568px. Re-encoding needs an in-box image codec, which exists on Windows only; elsewhere an oversized image is refused with its sizes named. An https URL is exempt entirely: it is sent by reference.
Type: String[]
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: FalseOne or more paths to Markdown instruction, agent, or skill files (*.instructions.md, *.agent.md, SKILL.md, or any *.md). The body of each file is read, its leading YAML front-matter is stripped, and the text is appended to the system prompt in the order given. This lets you reuse the same VS Code Copilot customisation files from the command line.
Note on skills: only the Markdown body of a SKILL.md is injected. VS Code's automatic skill selection, progressive disclosure, and any bundled scripts or resources referenced by the skill are client-side features and are NOT replicated here - point -InstructionPath at the SKILL.md you want and (if needed) at the extra files it references. For progressive-disclosure skill loading, use -SkillPath instead.
Type: String[]
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: FalseOne or more root folders to scan for VS Code instruction files (*.instructions.md, searched recursively). This enables progressive disclosure for instructions, mirroring -SkillPath: only each instruction's name, description and applyTo glob are injected into the system prompt, and the model is given a load_instruction tool that it calls (with an instruction name) to pull the full instruction body on demand. This lets you hand the model a whole library of instruction files and let it choose the relevant ones itself, instead of forcing every file into the prompt with -InstructionPath.
Type: String[]
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: FalseCopilot-Integration-Id header value sent with the request.
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: $script:DefaultIntegrationId
Accept pipeline input: False
Accept wildcard characters: FalseA JSON Schema (as a JSON string) that the reply must conform to. Implies a structured reply (parsed onto ContentObject) and takes precedence over -ResponseFormat. Uses the chat API shape.
The reply is checked LOCALLY against the schema, because a reply that parses as JSON is not the same thing as a reply that matches what was asked for. The result reports ContentSchemaChecked, ContentSchemaValid and ContentSchemaError. A schema using keywords outside the local validator's subset - $ref, composition, conditional - is reported as unchecked rather than as conforming.
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: FalseStop the tool-calling loop once this turn's estimated spend exceeds the given amount in USD. Checked after each round-trip, so the round-trip that crosses the cap is still billed - it is a ceiling on continuing, not a hard spend limit. Requires the model to have a price-table entry; with no entry no cost can be computed and the cap cannot apply. Omit it to run without a budget.
Type: Double
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: 0
Accept pipeline input: False
Accept wildcard characters: FalseEstimated-token budget for the accumulated conversation of this turn. Before each chat request, the oldest tool results are elided until the estimate fits, so a few large read_file, fetch_url or run_command results cannot overflow the model's context window.
The budget resolves in four steps, first match wins:
This parameter. 2. Set-ShpContext -MaxContextWindowTokens. 3. The model's own advertised limits, if Get-ShpModel has been called at least once this session. 4. The built-in 900000.
Step 3 is not simply the advertised window. That figure covers prompt plus completion - claude-haiku-4.5 advertises 200000 with a 64000 output cap and refuses a prompt at 136000, which is 200000 - 64000 exactly - so the output allowance is reserved first and a 10% margin is taken from what remains. The margin is there because the estimate counts message text only: the tool schemas and the JSON envelope are billed as prompt tokens too, so a guard set to the reported figure fires late. No pair on offer resolves above 900000, so step 3 can only tighten the guard.
Step 3 needs no request of its own: Get-ShpModel records every limit it reports, and this cmdlet only reads that cache, so no call is ever made slower to learn a window. Until something fills it, the guard runs on the fallback, which is no model's real window (claude-haiku-4.5 is 200000, gpt-4o is 128000) and is therefore too permissive for most models. Run Get-ShpModel once, or set this parameter, to fix that. Step 3 is skipped for an alternative backend (-ApiBase), where a Copilot window would be a wrong answer rather than a missing one.
The resolved figure and which step produced it are reported on the result as ContextBudget and ContextBudgetSource.
0 disables the guard. Note this bounds TOOL RESULTS only - the session conversation itself is never elided, because a user turn is something the user said rather than scaffolding the model produced for itself. A long-running loop of calls therefore still needs Compress-ShpChat (which drops the oldest exchanges and keeps the rest), Clear-ShpChat, or -History.
Type: Int32
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: 0
Accept pipeline input: False
Accept wildcard characters: FalseMaximum number of tokens the model may generate in its reply (the output side; the context window itself is a fixed model capability - see Get-ShpModel's MaxContextWindowTokens). Sent as max_tokens on /chat/completions and max_output_tokens on /responses. Note that in the non-streaming mode used by default some models cap output well below their streaming maximum (for example claude-opus-4.8 allows 16000 tokens non-streaming but 64000 when streamed) - add -Stream to lift the cap. Omit it to leave the limit to the service.
Type: Int32
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: 0
Accept pipeline input: False
Accept wildcard characters: FalseMaximum retries on a transient (429/5xx) HTTP failure, for buffered and streamed requests. Falls back to the session context and then the built-in default.
Type: Int32
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: 0
Accept pipeline input: False
Accept wildcard characters: FalseMaximum number of tool-calling iterations before aborting. Must be at least 1. Default: 25. This is a runaway-loop guard - each iteration is a billable API round-trip - so raise it for long tool-calling runs (for example scaffolding a whole module in one prompt), but be mindful of cost and time. The separate empty-tool-call circuit breaker still stops a model that signals a tool call without emitting one, independent of this cap.
Type: Int32
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: 25
Accept pipeline input: False
Accept wildcard characters: FalseDefault preserves ordinary behavior. Plan is a per-call read-only policy preset: read, list, search, fetch, and the in-memory todo tool remain eligible; writes, edits, directory creation, terminal execution, User tools, MCP tools, and ask_user are withheld. Caller tool filters and category switches can narrow it further. A preset is a convenience, not an enforcement boundary. It intersects existing Tool policy checks and never replaces or mutates session policy. MCP tools are withheld because an attached server is third-party dispatch, not because Tool policy cannot see them: a policy covering the Mcp kind gates them by alias and tool. Reads and fetches still run with caller privileges; there is no containment.
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: Default
Accept pipeline input: False
Accept wildcard characters: FalseModel id to use. If omitted, the session default set by Select-ShpModel is used, falling back to claude-opus-4.7 when no default is set. Tab-completion offers the ids returned by Get-ShpModelName (with a price-table fallback offline).
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: FalseWall-clock budget, in seconds, for riding out a connection-level network outage - a dropped connection that returns no HTTP response. The call is retried until this many seconds have elapsed since the first connection failure, then the error is rethrown. Applies to buffered and streamed requests. Falls back to the session context and then the built-in default (30). 0 disables outage tolerance.
All four connection options resolve identically - explicit parameter, then Set-ShpContext, then the built-in default - and apply to every request this call makes, including the session-token exchange that precedes it.
Type: Int32
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: 0
Accept pipeline input: False
Accept wildcard characters: FalseDisable every automatic resend, including HTTP retries, network-outage tolerance, Session-token recovery, API-shape fallback, and degraded reasoning or server-side state requests. Authentication also uses zero retries. The first failure is returned to the caller.
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: FalseRun unattended. Implies -DisableUserPrompts, and turns any would-be prompt into a terminating error instead of something that waits: a model that calls ask_user anyway fails the call with ShpNonInteractivePrompt rather than blocking on a console nobody is watching.
It is on automatically when $env:CI is truthy, because a runner is unattended whether or not the call said so. Pass -NonInteractive:$false to override that detection.
In CI it also arms the backend gate: with no alternative backend configured the call is refused, because the default backend reaches the Copilot endpoints on the token owner's personal entitlement. Set $env:SHELLPILOT_API_BASE (with $env:SHELLPILOT_API_KEY), or set SHELLPILOT_ALLOW_COPILOT_BACKEND_IN_CI to accept that. See Test-ShpCiReadiness.
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: FalseEditor-Plugin-Version header value sent with the request.
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: $script:DefaultPluginVersion
Accept pipeline input: False
Accept wildcard characters: FalseThe user prompt to send. Mandatory.
Type: String
Parameter Sets: (All)
Aliases:
Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: FalseReasoning (thinking) effort for the model, mirroring the effort control in the VS Code Copilot model picker. Accepted values are minimal, low, medium, high, xhigh and max, but the set a given model supports varies - the API rejects an unsupported value with a clear error listing what the model allows. Sent as the reasoning_effort field on /chat/completions and as reasoning.effort on /responses. Omit it to use the model default. Use Get-ShpModel to see a model's ReasoningEfforts.
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: FalseAdmission uses verified counts by default. Explicit provider-estimate mode requires RequestLimits and a counter returning Kind estimated. Token and Engine-priced cost budgets then govern estimates, not a guaranteed provider charge. Reported consumption can only increase a reservation. An overrun or unknown Usage stops before further Tool or provider dispatch. Strict invocation behavior remains unchanged.
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: Verified
Accept pipeline input: False
Accept wildcard characters: FalseOpt-in owned-transport admission limits: MaxInputTokens per request, MaxTotalTokens for cumulative input plus maximum output, and MaxCostUSD using frozen Engine pricing. Limits are copied at invocation startup. Every request reserves its full capacity before RequestTransport runs; reservations are retained even when transport fails or Usage is unknown. Requires RequestTransport and a verified RequestTokenCounter. The Engine currently ships no provider-specific complete-request counter.
Type: Hashtable
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: FalseTrusted complete-request counter used only with RequestLimits. Receives a detached request including RequestDigest and returns RequestId, RequestDigest, Model, Mode, InputTokens, Scope ('complete-request'), Kind ('exact' or 'upper-bound'), and a bounded Source identifier. The host must verify its provider-specific framing and counting contract; a declaration or deterministic fixture alone is not that evidence.
Type: ScriptBlock
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: FalseCaller-owned synchronous transport for a credentialless Tool-calling loop. Receives one detached, versioned request containing Model, messages, Tool schemas and generation options, never credentials, endpoints or headers. Returns one normalized Invoke-CopilotTurn result. Requires DisableStreaming and MaxOutputTokens, implies NoAutomaticRetry, and cannot combine with AsJob, ApiBase, TokenPath or UseServerSideState. The host must authenticate, admit and account for requests through a supported Engine transport implementation. This callback is a trusted host capability, not a Model-callable Tool or a filesystem or network containment mechanism.
Type: ScriptBlock
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: FalseAsk the model for a structured reply. 'json_object' requests a single valid JSON object, which is parsed and returned on the result's ContentObject member; 'text' (the default) leaves the format free. Uses the chat API shape.
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: FalseBase delay in seconds for the exponential backoff between retries (attempt n waits RetryDelaySec * 2^(n-1) seconds, with equal jitter under Invoke-ShpBatch). Falls back to the session context and then the built-in default. 0 disables waiting.
Type: Int32
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: 0
Accept pipeline input: False
Accept wildcard characters: FalseAppend the Session chat to a caller-named checkpoint store after the Turn succeeds, so the conversation can be resumed, rolled back, or forked later with Restore-ShpChat. Nothing is discovered or defaulted, the turns are redacted on the way to disk, and the store is never pruned - retention is yours.
Refused with -AsJob, whose Session chat is its own runspace's rather than yours, and with -History, which is a stateless call with no Session chat to checkpoint. Both refusals happen before any credential work.
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: FalseBest-effort determinism hint: repeated requests with the same seed, prompt and sampling settings aim to return the same reply. It is a hint, not a guarantee, so pair it with -Temperature 0 rather than relying on the seed alone. Sent as the seed field on /chat/completions and on /responses, and omitted from the request when you do not pass it.
Type: Int32
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: 0
Accept pipeline input: False
Accept wildcard characters: FalseStream the model's working to the host with Write-Host as the call progresses: a per-iteration banner, each tool call with its arguments, and the model's reasoning trace shown in dim italic under a 'thinking:' label so it is visually distinct from the answer. With streaming on (the default) the reasoning is read live from the /chat/completions stream - reasoning models on this backend (the Claude family) emit it as reasoning_text deltas, the same trace VS Code shows. If you also pass -DisableStreaming, the switch instead asks the /responses endpoint for a reasoning summary (models with no /responses API fall back to chat, and models that reject the summary retry without it). The trace is host-only colour output and does NOT enter the pipeline or the returned object; the full reasoning is also available afterwards on the result's Reasoning property. A model that exposes no reasoning at all still shows the iteration and tool-call trace, plus a one-line note that none was returned.
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: FalseOne or more parent folders to scan for Agent Skills (each skill is a sub-folder containing a SKILL.md). This enables progressive disclosure: only each skill's name and description are injected into the system prompt, and the model is given a load_skill tool that it calls (with a skill name) to pull the full SKILL.md body on demand - mirroring how VS Code Copilot selects and loads skills. Skills whose bodies are never requested cost almost no tokens.
Type: String[]
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: FalseCustom system instructions (literal text) appended to the built-in persona. Use this to give the model a role, tone, or task-specific guidance for a single call without editing the module. Belongs to the 'InlinePrompt' parameter set and is mutually exclusive with -SystemPromptPath.
Type: String
Parameter Sets: InlinePrompt
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: FalseOne or more paths to Markdown files whose bodies are read (leading YAML front-matter stripped) and appended to the built-in persona as the system instructions. Use this when your system prompt lives in a file - e.g. an *.agent.md or *.instructions.md. Belongs to the 'PromptFromFile' parameter set and is mutually exclusive with -SystemPrompt.
Type: String[]
Parameter Sets: PromptFromFile
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: FalseSampling temperature between 0 and 2. Lower values make the reply more deterministic, higher values more varied. Use 0 when a call must be reproducible - grading, judging, or classification in an evaluation harness - so a rerun yields the same verdict and the grader itself stops contributing variance; leave it unset for ordinary prose. Sent as the temperature field on /chat/completions and on /responses, and omitted from the request entirely when you do not pass it, so the model's own default applies. A value outside 0..2 is rejected before the request is sent rather than clamped.
Not every model accepts it: the field is honoured across the /chat/completions models, but some reasoning models reject it on /responses ("Unsupported parameter: 'temperature' is not supported with this model"). ShellPilot never drops the field to make such a call succeed - the request fails instead - because a silently dropped -Temperature 0 would promise a determinism you did not get. The failure quotes the service's own explanation, so the rejected field is named in the error. The models API advertises no capability flag for sampling, so support is validated by the service per model, exactly like -ReasoningEffort.
Type: Double
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: 0
Accept pipeline input: False
Accept wildcard characters: FalsePer-request HTTP timeout in seconds. Falls back to the session context and then to the built-in default of 0, meaning no explicit timeout - the shared HttpClient is deliberately built with an infinite timeout so a long streamed turn is not cut off mid-response.
Type: Int32
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: 0
Accept pipeline input: False
Accept wildcard characters: FalsePath to an OAuth token file to authenticate with. Omit it to resolve the token by the module's precedence: the session context (Set-ShpContext -GitHubToken), then $env:SHELLPILOT_GITHUB_TOKEN, then the default token file written by Initialize-Shp.
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: FalseExact tool names to offer, intersected with enabled categories and available registrations. Applies to built-in, User, and namespaced MCP tools. An empty array offers none; unknown names are refused before credential resolution. Wildcards are not supported.
Type: String[]
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: FalseCaller-supplied pre and post Tool-call decision controls. A hashtable with optional SchemaVersion, PreToolCall, PostToolCall, FailPosture and PolicyId; at least one hook is required. A hook is a scriptblock or the name of a command, never a file this module discovers.
The hook receives one typed, versioned, detached request carrying the phase, the run, turn, request and Tool-call identifiers, the Tool name with its origin and trust stamp, the original and effective arguments, and - in the post phase - the Tool result. It returns one record: @{ Decision = 'allow' }, @{ Decision = 'deny'; Reason = ... }, or @{ Decision = 'modify'; Arguments = ... } in the pre phase and @{ Decision = 'modify'; Result = ... } in the post phase.
A pre-call control is consulted only for a call the Tool policy has ALREADY allowed, so it can narrow what runs and never widen it. Rewritten arguments are re-checked against the Tool policy before dispatch. Anything the control cannot answer cleanly - a throw, no reply, several replies, an unknown decision, a modify with no payload - is a control failure and resolves by FailPosture: Closed (the default) denies the call, Open lets it proceed unchanged. Either way it is recorded. Every decision produces a bounded receipt on the result's ToolCallDecisions and a tool.decision Event record; receipts carry identities, the decision and argument hashes, never argument values.
Type: Hashtable
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: FalseAn existing, caller-owned directory to write oversized Tool results to instead of truncating them. Off by default; nothing is discovered, defaulted, or created, and the default cap and its "...[truncated, original N chars]" marker are unchanged when the parameter is unbound.
Bound, an oversized result from any producer - a file read, a fetched page, the Terminal tool, a User tool, an MCP tool, or an execution contract - is redacted, written atomically with a schema version and private permissions where the platform supports them, and replaced in the conversation by a handle carrying the path, the SHA-256, the full length and a bounded preview. Nothing is ever pruned: retention is yours. A failed write raises a terminating error rather than quietly truncating, and the message says the Tool already ran.
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: FalseThe length at which a result is spilled rather than sent whole. Defaults to the same figure as the built-in Tool result cap. Ignored without ToolResultSpillRoot.
Type: Int32
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: 0
Accept pipeline input: False
Accept wildcard characters: FalseNucleus-sampling cutoff between 0 and 1: the model considers only the tokens making up the top TopP of the probability mass. An alternative to -Temperature; the providers recommend tuning one or the other, not both. Sent as the top_p field on /chat/completions and on /responses, and omitted from the request when you do not pass it. A value outside 0..1 is rejected before the request is sent rather than clamped, and - like -Temperature - a model that rejects the field fails the call instead of having the field dropped.
Type: Double
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: 0
Accept pipeline input: False
Accept wildcard characters: FalseContinue an inbound W3C traceparent ('00-<32 hex trace>-<16 hex span>-<2 hex flags>') instead of starting a new trace. This is what puts a Batch item, a Job or a Subagent under the span that dispatched it. A malformed value is refused before the call spends anything, because a silently fresh trace produces an export that looks complete and is not.
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: FalseUser-Agent header value sent with the request.
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: $script:DefaultUserAgent
Accept pipeline input: False
Accept wildcard characters: FalseKeep the conversation state on the server (responses API): store each turn and continue the next one from it by id instead of replaying the whole history. Opt-in and off by default; reset with Clear-ShpChat. If the backend does not support server-side storage (the Copilot proxy is stateless and rejects it), the call automatically falls back to ordinary client-side history with a warning, so it still succeeds.
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: FalsePrompts you for confirmation before running the cmdlet.
Type: SwitchParameter
Parameter Sets: (All)
Aliases: cf
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: FalseShows what would happen if the cmdlet runs. The cmdlet is not run.
Type: SwitchParameter
Parameter Sets: (All)
Aliases: wi
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: FalseThis cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.
- Clear-ShpChat
- Clear-ShpContext
- Clear-ShpRedactionPolicy
- Clear-ShpToolPolicy
- Clear-ShpUsage
- Compress-ShpChat
- ConvertTo-ShpAnnotation
- ConvertTo-ShpOtelTrace
- ConvertTo-ShpTokenCount
- Get-ShpChat
- Get-ShpChatCheckpoint
- Get-ShpContext
- Get-ShpContextReport
- 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
- Invoke-ShpEval
- Invoke-ShpSubagent
- Register-ShpMcpServer
- Register-ShpTool
- Request-ShpEmbedding
- Resolve-ShpError
- Restore-ShpChat
- Save-ShpChat
- Select-ShpModel
- Set-ShpContext
- Set-ShpRedactionPolicy
- Set-ShpToolPolicy
- Start-ShpChat
- Test-ShpCiReadiness
- Unregister-ShpMcpServer
- Unregister-ShpTool