Know exactly
what runs.

One runtime, one project

1. Create

   SquadRuntime.CreateAsync(IChatClient, SquadRuntimeOptions, SquadArtifactSource?, CancellationToken) snapshots options, resolves artifacts, loads the release catalog, validates the roster, and checks existing state. It does not own your chat client's lifetime.

2. Confirm initialization and routing

   The host confirms single-squad scope, profile/packs, roster, names, and channel before squad state or model calls are created. Routing approval confirms scope, producing owner, all input paths, and council/RAI coverage. Model classification is a proposal, not authorization.

3. Execute the bounded workflow

   Delivery with inputs runs intake first, then research, approved planning with separate phase details, conditional council, approved production by one owner, and independent review. Each consequential host call has its own approval.

4. Inspect the result and dispose

   Read status and verified evidence, not just response prose. Await the active run before disposing the runtime. Retain the original release and roster to continue its project-bound sessions.

Express the intended scope in the request and check the routing proposal. Research-only and review-only requests cannot bypass a required council: council needs a planning stage, so that combination is blocked.

Select the release's actual roster

Profiles and packs come from squad-roster.instructions.md, not an embedded role map. The following names are from the exercised v0.16.2 catalog. The inspector prints the catalog for the release you actually acquire.

Each released profile includes the methodology spine. Role presence does not install a web-search service, cloud credentials, a shell, or any other execution tool.

Optional additive packs

Packs select roles; they do not automatically install their external primary agents. Follow the pinned upstream catalog's Registered External Cast instructions in a host-managed artifact installation. Selected absent or disabled agents fail validation. full is not a workaround for missing opt-in dependencies.

Complete configuration reference

These defaults are from SquadRuntimeOptions. The DI binder accepts the data settings below and rejects unknown or host-only configuration keys. Lists must be contiguous indexed scalar lists; MemberNames maps roles to scalar names.

Options and collections are snapshotted at creation. Changing the original options object is not live reconfiguration. Catalog tier preferences are not actual model IDs, prices, or proof that a provider supports a model.

Approvals are a host responsibility

Requests include a description and may include role, tool name, arguments, initialization, evidence, and routing. Render these as data in your UI. Never treat model text, project files, or a notification file as an approval source. Questions carry Role and Question; only real host answers are recorded as confirmed.

A web or desktop host may implement the callbacks using its own UI. There is no shipped remote callback endpoint or durable suspended-approval protocol. Honor cancellation and timeout while waiting.

Make real effects explicit

Native tools read project files and write allocated methodology artifacts. They are not a general source editor. Register actual host capabilities through SquadToolRegistration; permissions in a charter do not provide an implementation.

options.Tools.Add(new SquadToolRegistration(
    function,                    // Your actual AIFunction.
    "edit",                      // A permission allowed by the role's charter.
    ["developer"],               // Explicit roster role allowlist.
    SquadToolEffect.ProjectWrite,
    OutputEvidence: result => ExtractSuccessfulOutputs(result),
    RequireOutputForCompletion: true));

This is a registration pattern, not a bundled executor. function and ExtractSuccessfulOutputs must be supplied by the host. For a concrete contained writer, read ProjectFileWriter.cs and its registration in the sample.

The evidence contract

• OutputEvidence is Func<object?, SquadToolOutput>, called on the actual returned function result. It must attest only successful outputs, not model arguments or intended effects.
• SquadToolOutput(ProjectPaths, Receipt) lists existing project-relative output files and/or a meaningful successful external receipt. Failed operations and dry runs must not attest an applied effect.
• Host effectful integrations need actual tools, explicit approvals, successful results, and honest output evidence. A call receipt without required output evidence does not complete an effect-producing role.
• RequireOutputForCompletion defaults to false. Set true when a host-specific producing role must demonstrate its configured effect. Optional tools do not make unrelated external actions mandatory.
• Output files are hashed as raw bytes, including binary files, with a 64 MiB per-file limit. Repeated approved edits within one dispatch keep all receipts and verify the last content. Overlapping ownership across distinct dispatches fails closed.
• Tools need unique names, valid effects, charter permissions, and nonempty role allowlists. Native tool names cannot be shadowed. Enforce path/resource/tenant limits inside every host function; never mutate the Scribe's state or .git.

Treat status as part of the API

SquadRunResult contains RunId, Status, ResponseText, Evidence, and Scope. A non-success result may contain useful, verified partial work. There is no separate Partial status enum.

Cancellation and timeout save the active run as failed with partial evidence, then rethrow OperationCanceledException. Acquisition, invalid options, state mismatch, and lock errors can also throw before the execution result handler. Host code must handle exceptions as well as result statuses.

What a dispatch record proves

SquadDispatchEvidence records dispatch ID, stage, role, agent, artifact path/hash, history path, summary, verdict, risk, blocking issues, model identity/source/tier, and provider-reported tokens. It may also contain companion artifacts, executed-host-tool receipts, and a structured return.

EvidenceKind is Artifact or StructuredReturn. For a return-only role, the primary path is a deterministic Scribe receipt, not a fabricated agent-authored document. Tool execution records contain name, effect, argument hash, outputs, and receipt. Unknown tokens, model identities, costs, and credits stay unknown; they are not recorded as zero or inferred from a tier.

Follow the release, not main

1. Published stableGitHub release API
2. Tag → commitExact resolved SHA
3. APM installationMatched dependency graph
4. InventoryAgents, rules, skill resources

Version = "latest" resolves /repos/Peter-N91/hve-squad/releases/latest, validates a published, non-draft, non-prerelease stable semantic-version tag, resolves the tag to a commit, and asks APM to install that commit. It never uses target_commitish, main, or a branch head.

The exercised release is v0.16.2, commit a941195c36dfb6181453f51ec4638b085ca3b3ad, using APM 0.18.0 in CI. The upstream APM manifest supplies the matched HVE Core dependency pin. A new default runtime checks the published release; an existing runtime retains its resolved artifacts and rejects hot swaps.

The APM cache normally lives under local application data at hve-squad-maf\artifacts, in a source-and-target-specific directory. Complete deployed agents, instructions, and skill resources are inventoried. Missing or changed files invalidate the cache and trigger acquisition. API authentication, rate-limit, and network errors are explicit; no silent alternative version or branch fallback is used.

Prepare a host-managed offline installation

On a connected machine, install the exact known commit into a dedicated artifact workspace. Keep this workspace separate from the consumer project and do not initialize Copilot squad state in the consumer.

New-Item -ItemType Directory -Force C:\SquadArtifacts\v0.16.2 | Out-Null
Set-Location C:\SquadArtifacts\v0.16.2
apm install "Peter-N91/hve-squad#a941195c36dfb6181453f51ec4638b085ca3b3ad" --target copilot

Preserve the complete installed directory, including .github, .agents, and the acquisition metadata. Transfer it through your approved artifact process. Verify its contents and retain the release/commit record before making it available to an offline host.

using HveSquad.AgentFramework.Sources;
using HveSquad.AgentFramework.Runtime;

var source = new ProjectArtifactSource(@"C:\SquadArtifacts\v0.16.2");
using var squad = await SquadRuntime.CreateAsync(
    chatClient, options, source, cancellationToken);

This snippet uses the existing client/options from the setup guide. ProjectArtifactSource searches at or above the supplied directory for deployed agents. Check that it selected the intended root. Directory sources are host-managed overrides, not proof of published-release provenance, and can have Provenance.Release == null. Version does not relabel or validate an override as that release.

Offline artifact loading does not make a hosted model provider offline. You still need a reachable model and any explicitly registered external services. For authenticated release API access, provide a host-configured HttpClient to ReleaseArtifactSource; it does not automatically consume your application's provider credentials.

Advanced acquisition seams

ReleaseArtifactSource(version, target, httpClient, acquisitionFactory) accepts a stable tag or null for latest, defaults the APM target to copilot, and passes the exact pinned package spec to its acquisition factory. ApmArtifactSource additionally allows cacheDirectory, timeout (default 10 minutes), installer, and apmExecutable. These are host code options, not runtime JSON properties. Direct APM or directory overrides put provenance verification in the host's hands.

Persistence has an owner

The deterministic native Scribe owns .copilot-tracking\squad, including state.json, native.lock, roster/routing records, decisions, notifications, consumption, dispatch histories, and structured returns. Native MAF conversation sessions and confirmed answers are persisted with release, artifact fingerprint, and roster/configuration binding.

• Turns serialize within one runtime. An exclusive project file lock prevents simultaneous native state writers; it is not a distributed scheduler.
• Do not put horizontal replicas on the same project state and assume coordination, failover, or shared-filesystem lock semantics will work. Route each project to one active owner.
• Do not edit the state or invent receipts through host tools. Methodology outputs are allocated and checked; companion files and history are verified before advancing.
• Native state is versioned and distinct from Copilot state. Existing non-native state is rejected, even though the directory naming is similar.
• A new release, changed artifacts, profile, packs, names, or roster binding cannot silently resume an old conversation. Preserve the original setup, choose a fresh project, or implement an explicit reviewed migration. No automatic migration or reseeding is implemented.
• After interruption, a surviving active-run record is marked failed on the next turn. This is not automatic continuation of an interrupted external operation.

When the run stops, keep the boundary