Invoke‑ShpSubagent

SYNOPSIS

Dispatches one bounded child agent from an explicit definition file and returns its answer with evidence.

SYNTAX

Invoke-ShpSubagent [-DefinitionPath] <String> [-Prompt] <String> [-Root <String>] [-Parent <Hashtable>]
 [-Capability <Hashtable>] [-Budget <Hashtable>] [-EventStream <String>]
 [-CancellationToken <CancellationToken>] [-Invoker <ScriptBlock>] 
 [<CommonParameters>]

DESCRIPTION

Runs a nested Invoke-Shp turn under a capability that is a STRICT SUBSET of the caller's, inside a budget shared by the whole Subagent tree, and returns the child's final answer plus a trace reference - never the child's transcript.

Returning an answer rather than a conversation is the design. A Subagent exists to keep work out of the parent's context window; handing back the transcript would put it straight back in, and would also put whatever the child read in front of the parent model without any of the gates the child ran under. What comes back is the answer, the counts, the cost and the span it ran in - enough to audit, too little to inject.

ATTENUATION. The child's tools, switches, Tool policy, network reach, redaction, execution contract and backend all come from Resolve-ShpSubagentCapability, which refuses any request to widen rather than dropping it. Those controls are then HANDED TO the child turn as the objects the parent runs under - the Tool policy as a per-call override, the decision control and the execution contract as the scriptblocks themselves - so the child is gated by them rather than merely described by them. Session state is never replaced to do it. A parent that requires an execution contract it cannot hand down refuses the dispatch instead of letting the child run natively. No credential travels: a Subagent inherits a boundary, not a secret, and the approved backend travels as its address only.

BUDGET. The tree's spend, iteration count and deadline live in ONE shared ledger. A child never gets a slice - it gets the smaller of what it asked for, what the tree has left, and the per-child cap - so a tree cannot recover budget by spawning more children. Depth, fan-out and concurrency are capped, and a refusal happens BEFORE any credential work or request.

NO BACKGROUND PROCESS. There is no -AsJob here and there will not be. A Subagent that outlives the call that started it is a budget nobody is watching and a cancellation nobody can deliver. The call is synchronous and cancellable.

The agent definition is an explicit path, validated and fingerprinted exactly like a Skill (spec 044). Nothing is discovered.

EXAMPLES

EXAMPLE 1

Invoke-ShpSubagent -DefinitionPath ./agents/reviewer.agent.md -Prompt 'Review the staged diff.'

Runs the reviewer under its declared tools and the default tree budget.

EXAMPLE 2

Invoke-ShpSubagent -DefinitionPath ./agents/reviewer.agent.md -Prompt $task -Budget @{ MaxTotalUSD = 0.10; MaxDepth = 1 }

Caps the whole tree at ten cents and forbids a grandchild.

PARAMETERS

-Budget

Tree-wide limits for a root call: MaxTotalUSD, MaxChildUSD, MaxTotalIterations, MaxChildIterations, MaxDepth, MaxFanOut, MaxConcurrency and MaxDurationSec.

Type: Hashtable
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: @{}
Accept pipeline input: False
Accept wildcard characters: False

-CancellationToken

Cancellation from the caller, checked before dispatch and handed to the child, which checks it before every model request and Tool dispatch. A request already in flight is not interrupted.

Type: CancellationToken
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: [System.Threading.CancellationToken]::None
Accept pipeline input: False
Accept wildcard characters: False

-Capability

Additional narrowing on top of the definition and the parent. It can only remove.

Type: Hashtable
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-DefinitionPath

The agent definition file. Explicit, always: nothing is discovered.

Type: String
Parameter Sets: (All)
Aliases:

Required: True
Position: 1
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-EventStream

Append the Subagent's own span records to this JSONL stream.

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Invoker

A caller-owned dispatcher used instead of the nested Invoke-Shp turn. Receives the fully attenuated request and returns the child result.

Type: ScriptBlock
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Parent

The dispatching context: Capability, Budget, Depth and TraceParent. A root call omits it and the caller's own limits apply; the Session Tool policy and redaction policy are inherited as the floor either way.

Type: Hashtable
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Prompt

The task the child is dispatched to carry out.

Type: String
Parameter Sets: (All)
Aliases:

Required: True
Position: 2
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Root

The source root the definition is fingerprinted against. Defaults to the definition's own folder.

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

CommonParameters

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.

INPUTS

OUTPUTS

System.Management.Automation.PSCustomObject

ShellPilot.SubagentResult: Answer, Refused, Cancelled, Reason, Depth,

Definition, Capability, Budget and Evidence.

NOTES

RELATED LINKS

Invoke-Shp

ConvertTo-ShpOtelTrace