---
name: powershell-agent-harness-development
description: Build or review PowerShell orchestration for local or hosted AI models, coding agents, capability registries, evaluations, checkpoints, session exports, and provider switching.
---

# PowerShell Agent Harness Development

Use this skill when PowerShell controls a model endpoint, coding-agent CLI, capability registry, evaluation harness, provider profile, context checkpoint, or session export.

1. Read [references/agent-harness-patterns.md](references/agent-harness-patterns.md) for the applicable modes only.
2. Separate deterministic authority from model assistance. Paths, manifests, permissions, hashes, timestamps, approval state, and pass/fail decisions must be validated by code; model output may summarize or classify only after validation.
3. Bind evidence to model identifier and digest, provider/endpoint, host, context configuration, project profile, capability version, fixture hash, and timestamp. Do not generalize one successful run to another configuration.
4. Permit loopback endpoints by default. Treat remote endpoints, silent cloud fallback, credential transmission, and connector writes as separate capabilities requiring explicit authorization and evidence.
5. Make provider/config changes reversible: preflight, exact backup, scoped edit, post-check, explicit restore, and actionable failure state. Never leave a partially switched profile reported as ready.
6. Preserve raw evidence and produce structured JSON results before Markdown summaries. Reject empty output, malformed structured output, unsafe paths, stale evidence, and unknown status values.
7. Use mock/contract tests before live model calls. Live tests must have bounded repetitions, timeouts, no automatic destructive retries, and persisted failure classification.

## Packaged artifacts

- Use `../../scripts/Resolve-PowerShellWorkbenchCodexDesktop.ps1` to locate the deterministic Codex Desktop binary. Do not use a PATH/npm Codex installation unless a task explicitly supplies `-CodexPath`.
- Use `../../scripts/New-PowerShellWorkbenchLocalModelCatalog.ps1` to derive a local-model catalog from that binary's `debug models --bundled` schema.
  It prefers a legacy-compatible unified-exec template, removes unasserted Responses Lite/code-mode/multi-agent/cloud-service-tier transport claims,
  and fails closed if the serialized catalog retains an unsupported Ollama transport property. Omit `-ExpectedCodexSha256` for normal deterministic
  Desktop discovery, or supply it only when a separately certified executable digest is available. Supply certified model and context values; do not
  invent reasoning levels, speed tiers, modalities, or online-only tool claims.
- Use `../../scripts/Invoke-PowerShellWorkbenchCodexJson.ps1` to capture a bounded `codex exec --json` run. It requires PowerShell 7 because reliable argument passing, asynchronous waits, cancellation, and process-tree termination use modern .NET APIs. Supply `-CatalogManifestPath` when the run relies on a generated local model catalog.
- Use `../../scripts/Test-PowerShellWorkbenchCodexEvidence.ps1` separately to validate the capture. A process exit code of zero and a plausible final message are insufficient when any tool, policy, approval, schema, or turn event failed.
- Use `../../scripts/Invoke-PowerShellWorkbenchOllamaChat.ps1` to prepare a deterministic direct Ollama chat request.
  It remains `ANALYZE_ONLY` unless `-Execute` is explicit, permits only the credential-free literal loopback-IP HTTP `/api/chat` endpoint,
  disables streaming and thinking, and bounds prompt, request, response, timeout, and output tokens. Returned tool calls are evidence only and are never executed.
  Supply `-ContextTokens` when a frozen comparison requires an explicit `num_ctx`; the request binds that value, while effective runtime context remains `UNKNOWN` until independently observed.
- Use `../../scripts/Test-PowerShellWorkbenchOllamaEvidence.ps1` with an independently recorded metadata SHA-256. The response can attest the observed model id but not the model digest; accepting the caller-bound digest requires explicit `-AcceptUnverifiedModelDigest` and must not be reported as runtime attestation.
- Use `../../scripts/Compare-PowerShellWorkbenchOllamaEvidence.ps1` with
  [assets/templates/model-comparison-manifest.json.tmpl](assets/templates/model-comparison-manifest.json.tmpl) to compare
  frozen validated captures for one prompt and request configuration. Quality is decided by the manifest's exact UTF-8
  answer hash before performance ranking. Missing evidence or metrics is `UNKNOWN`; hash, path, prompt, identity, or
  configuration drift is `CONFLICT`. The comparator never retries, calls a model, writes output, or transports evidence.
- For one controlled file-slice proposal, add `-EnableReadFileSliceProposal` to the bounded Ollama request and require `-ExpectReadFileSliceProposal` during evidence validation. The model only proposes `read_file_slice`; it never authorizes or executes it.
- Use `../../scripts/New-PowerShellWorkbenchReadOnlyToolProposal.ps1` to extract exactly one validated call into deterministic JSON, then `../../scripts/New-PowerShellWorkbenchReadOnlyToolApproval.ps1` to bind a separately reviewed target snapshot. Approval remains preview-only unless `-Approve` is explicit.
- Use `../../scripts/Resolve-PowerShellWorkbenchReadOnlyToolChain.ps1` for the read-only decision and
  `../../scripts/Invoke-PowerShellWorkbenchReadOnlyTool.ps1` for the bounded read. Missing, stale, or unknown evidence is
  `UNKNOWN`; hash, path, binding, reparse, target, or observation drift is `CONFLICT`. Execution requires `-Execute`, writes
  only new evidence under an explicit scoped evidence root, and never performs transport, process launch, target writes,
  provider switching, Desktop lifecycle, or clipboard access.
- Use `../../scripts/Test-PowerShellWorkbenchHealth.ps1` before relying on installed plugin or catalog evidence. Supply explicit distribution source/cache pairs and catalog manifests; require catalog evidence when a downstream run depends on it. Unknown versions, duplicate roots, tree drift, stale manifests, missing artifacts, and hash drift fail closed without changing the installation.
- Use `../../scripts/Invoke-PowerShellWorkbenchDoctor.ps1` for one read-only overview of explicitly supplied project and distribution evidence. Its default runtime state is `SKIPPED`; use `-IncludeRuntimeProbe` only when a child-PowerShell version/architecture probe is desired. It never discovers a marketplace source by guessing and never launches quality or model operations.
- Use `../../scripts/Get-PowerShellWorkbenchStatusDashboard.ps1` with an independently hashed
  [release-provenance template](assets/templates/release-provenance.json.tmpl) to distinguish declared version, found
  source/cache trees, and validated release identity. It reuses health gates, binds every source tree to one commit/ref
  provenance record, returns `UNKNOWN` for missing state and `CONFLICT` for drift, and performs no write, execution, or
  transport.
- Use `../../scripts/Get-PowerShellWorkbenchCatalogMigrationPreview.ps1` to assess a schema 1.0 catalog before migration.
  Supply the expected manifest hash, an explicit destination, a scoped allowed write root, and an authoritative reference
  time. The previewer requires fully qualified paths and exact transport scalar types, and rejects stale, future, drifted,
  unknown, unsafe-transport, and reparse-ambiguous evidence. It never
  writes or launches Codex: verified schema 1.0 evidence returns a generator- and policy-hash-bound regeneration plan,
  schema 1.1 returns `NO_CHANGE`, and failures preserve exact blocking gates. Applying the plan remains separately authorized.
- `-AllowedAdvisoryRegex` is an opt-in, exact advisory mechanism for known host notices only. It can never allow tool, policy, approval, schema, or turn failures; keep each pattern as narrow as the observed advisory text.
- Use `../../scripts/Resolve-PowerShellWorkbenchGateGroups.ps1` to evaluate named gate groups without collapsing safe runtime preparation into host certification. Consumers must select the exact group required for an action and preserve the returned failed-gate names.
- Copy and adapt [assets/templates/provider-switch-transaction.ps1.tmpl](assets/templates/provider-switch-transaction.ps1.tmpl) for reversible provider configuration changes.
  Its read-only resume decision verifies phase, freshness, paths, hashes, provider/model/context identity, loopback endpoint, wire API, local-model catalog,
  owned keys, canonical owned state, managed-state absence, and restore evidence before allowing apply, managed commit, post-check, or restore continuation.
  `ProviderProfileWritten` and `DesktopLifecycleInterrupted` return `ManagedCommitRequired` without repeating the provider edit or invoking Desktop lifecycle work.
- Use `../../scripts/New-PowerShellWorkbenchHandoff.ps1` with [assets/templates/handoff-input.json.tmpl](assets/templates/handoff-input.json.tmpl) to create schema-bound JSON and Markdown handoffs. The generator writes local non-executable artifacts only; task, Drive, GitHub, or connector transport is always a separate explicitly authorized action.
- Windows PowerShell 5.1 can run the evidence validator, contract tests, and provider-switch template, but it must not be used for the bounded runner.