# Agent shapes (/docs/agent-shapes) Pleach is built for the multi-tenant production-agent shape. Below are the common shapes that show up in adopter conversations — pick the closest, then read the linked use case for the wiring. Each section names the pattern (what hurts), the mechanism (the primitive that handles it), the team shape (where it typically shows up), and the sharpest vertical (where the pain is loudest). ## 01 — Provider migration [#01--provider-migration] ### The pattern [#the-pattern] Anthropic to OpenAI, OpenRouter to BYOK, native to gateway — mid-session, without breaking the tool-call dialect or refusal handling. ### The mechanism [#the-mechanism] Family-lock freezes tokenizer, prompt-cache key, tool-call dialect, and refusal pattern at session start. The cascade walks in-family rungs only; `permittedFamilies` narrows it to a vetted set. ### The team shape [#the-team-shape] SaaS adding in-product chat. ### The sharpest vertical [#the-sharpest-vertical] Compliance-bound teams (HIPAA, SOC 2, PCI, FedRAMP, 21 CFR Part 11). ## 02 — Tool fan-out and subagent attribution [#02--tool-fan-out-and-subagent-attribution] ### The pattern [#the-pattern-1] One user message triggers a dozen tool calls and spawns three subagents that spawn their own. You need to know which tools ran, which subagents spawned, and where the tokens went. ### The mechanism [#the-mechanism-1] Every row carries `turnId`, `toolName`, and `subagentDepth`. A typed `SpawnTreeState` rolls child-session token spend back to the parent turn instead of stranding it under the child sessionId. ### The team shape [#the-team-shape-1] Internal platform teams exposing "AI for everything". ### The sharpest vertical [#the-sharpest-vertical-1] Coding-agent shops (Cursor-class, terminal-native, autonomous-PR). ## 03 — Portable, replayable state [#03--portable-replayable-state] ### The pattern [#the-pattern-2] Offline-first or sync-conflict-prone sessions — browser extensions, mobile-shaped web apps, multi-device editing. Two clients writing the same session can silently overwrite each other. ### The mechanism [#the-mechanism-2] The session is one append-only event log. IndexedDB + checkpointer + version-vector sync carry it across devices; conflicts surface at write time. `HarnessPlugin` events are first-class log entries. ### The team shape [#the-team-shape-2] Vertical AI startups (legal, radiology, accounting close, devtools security). ### The sharpest vertical [#the-sharpest-vertical-2] Eval and research labs running deterministic replay across model swaps. ## 04 — Per-axis cost attribution [#04--per-axis-cost-attribution] ### The pattern [#the-pattern-3] A `(family, callClass, model)` call has to roll up to whichever axis you're attributing on — your end customers in a SaaS, or your own employees, teams, and cost centers when Pleach runs under one Anthropic Workspace or OpenAI Project on an Enterprise contract. ### The mechanism [#the-mechanism-3] Every `AuditableCall` row carries `tenantId`, `turnId`, `toolName`, `subagentDepth`, `modelId`, and `tokenUsage`. `tenantId` is opaque — `customer-acme` and `cost-center-eng-platform` partition the same way. Finance reads the ledger directly — no parallel cost pipeline. See [Migrating from Anthropic Enterprise](/docs/migrating-from-anthropic-enterprise) and [Migrating from OpenAI Enterprise](/docs/migrating-from-openai-enterprise) for the contract-composition walk-through. ### The team shape [#the-team-shape-3] AI consultancies with per-engagement tenants; internal platform teams under one Enterprise contract attributing across business units. ### The sharpest vertical [#the-sharpest-vertical-3] ISVs embedding agents in a downstream SaaS (customer → end-user nesting); internal-AI platform teams in 500-100,000-person enterprises rolling up to cost-center budgets. ## 05 — Regulator-facing audit [#05--regulator-facing-audit] ### The pattern [#the-pattern-4] A regulator, auditor, or court asks which tools the session invoked, which subagents it delegated to, and proof neither the answer nor the PII gate were altered after the fact. ### The mechanism [#the-mechanism-4] Append-only ledger keyed by `(turnId, toolName, subagentDepth)` answers the first two questions in one query. `@pleach/compliance` ships four scrubbers (`SSN-US`, `Luhn`, `US-DL`, `KeyedRegex`) on the persistence boundary plus inherited CI gates that fail an untenanted write. ### The team shape [#the-team-shape-4] Public-sector deployments (FedRAMP, FOIA-bound, often air-gapped). ### The sharpest vertical [#the-sharpest-vertical-4] Edtech serving K-12 or higher-ed (FERPA-equivalent per-district isolation). ## 06 — Stuck-session debugging [#06--stuck-session-debugging] ### The pattern [#the-pattern-5] A user reports a bad turn. By the time you read the ticket, the session is twenty messages further along. You need to rewind to before the bad decision and try a different path. ### The mechanism [#the-mechanism-5] Per-channel `checkpoint()` / `restore()` under `window.__HARNESS_DEVTOOLS__`. Deterministic fingerprint stream means a support ticket replays byte-identically locally; the bad turn is a known offset, not a guess. ### The team shape [#the-team-shape-5] Founder teams answering their own support email. ### The sharpest vertical [#the-sharpest-vertical-5] Customer-support automation across thousands of live transcripts a day. ## 07 — Region-pinned routing under contract [#07--region-pinned-routing-under-contract] ### The pattern [#the-pattern-6] An enterprise already running AI in production needs procurement- visible routing discipline: region pinned per call class, family pinned per call class, failover constrained to a vetted list, and a parity-validation suite that proves the substitute behaves the same as the primary. ### The mechanism [#the-mechanism-6] `permittedFamilies` scopes the cascade; a per-call-class family pin keys on `(family, callClass)` against the resolution matrix. `@pleach/eval` records a fixture run against the primary and replays it against each family in the permitted list — the diff is what proves the failover is safe to take. ### The team shape [#the-team-shape-6] Direct-API enterprise buyers — Anthropic / OpenAI tier-4+ contracts with six-to-eight-figure annual spend, often with a named AI governance function. ### The sharpest vertical [#the-sharpest-vertical-6] EU-resident enterprises preparing for AI Act Article 12 attestation; financial services with a stated provider-switch clause. ## 08 — Cloud-mediated transport [#08--cloud-mediated-transport] ### The pattern [#the-pattern-7] API keys are forbidden by policy. Models must be reachable inside the customer's VPC. The buyer reaches Anthropic, OpenAI, or Google models through AWS Bedrock, Azure OpenAI Service, or Vertex AI — not the labs' direct APIs. ### The mechanism [#the-mechanism-7] Family stays the model's identity (`anthropic`, `openai`, `google`); transport names the route to it (`bedrock`, `azure-openai`, `vertex`). The credential is an IAM role, a managed identity, or a workload-identity binding — never a long-lived key. The audit row records the principal, the cloud, the region, and the model — joinable to the cloud invoice. ### The team shape [#the-team-shape-7] 1,000-100,000-person enterprises with $1M-$100M annual cloud commit, often with on-prem or VPC-mandate procurement policy. ### The sharpest vertical [#the-sharpest-vertical-7] Regulated financial services and healthcare systems whose existing committed cloud spend is the procurement substrate. ## 09 — Bounded subagent swarms [#09--bounded-subagent-swarms] ### The pattern [#the-pattern-8] One user turn fans out into dozens or hundreds of subagents, each of which may spawn its own. Deep sequential loops, parallel fan-out, supervisor / worker topologies, recursive delegation — different shapes, same runaway-loop risk: a buggy fan-out can spend a five-figure budget in one user turn. ### The mechanism [#the-mechanism-8] Every subagent inherits the originating turn's `turnId` and carries its own `subagentDepth`. The whole tree is one recursive CTE against the ledger. A per-root-turn cost ceiling aborts the turn when cumulative spend across the tree crosses the line; fan-out and depth caps bound the structural shape. ### The team shape [#the-team-shape-8] Builders of coding agents, deep-research products, supervisor- worker platforms, and Claude Code-style recursive delegation — where the topology has already been chosen and what's needed is a substrate that doesn't force a different one. ### The sharpest vertical [#the-sharpest-vertical-8] Agent-product builders adding governance after a runaway-loop incident; enterprise buyers wrapping an existing swarm consumer (Kimi, Deep Research, AutoGen) with cost ceilings and an audit walk. ## Where to go next [#where-to-go-next]