Skip to main content
A workflow node is about to post a summary to an external destination. Trust Fabric resolves the initiating principal, evaluates the current gates and policy, and returns hold. The protected provider is not called. After an authorized human approves the exact bound operation, the retry is reevaluated and one atomic claim permits one delivery. The audit feed records who acted, what was required, and why the decision changed. This page is for operators standing up Forge in production. It covers what the Trust Fabric evaluates on every dispatch, where coverage applies, and the four operating concerns you carry once governance is live: identity, lifecycle, autonomy, and the disposition you see when the pipeline returns. For the visual flow of every gate, read the Governance Pipeline. When something is wrong and you need to stop work fast, go to Emergency stops.
When to reach for something else. If you are debugging a single failed step, the audit feed is the faster surface — every block / hold carries a structured explanation with unblock hints. Use this page when you are setting up the platform, sizing budgets, or deciding which agents earn which autonomy rung. For policy-specific operating decisions (write the rule, scope it, choose enforcement), jump to Approvals & HITL. For budget-specific concerns, jump to Budgets & Cost.

Coverage — what runs through governance, and what does not

Trust Fabric runs on every surface that dispatches an agent. One gate engine serves them all; each surface hands it the context of its own dispatch, such as the run and step for a workflow, or the channel for a chat. Every dispatch above returns a governance decision and records server evidence. Reading a decision’s evidence needs the exact workflow run it belongs to; a tool decision linked only to a session, a trace or an ad hoc id cannot be read as run evidence.
What the pipeline does NOT cover. Trust Fabric governs dispatches. Building an agent’s configuration (agent composition) does not evaluate governance; each dispatch runs the gate sequence separately. An HTTP API request that does not dispatch an agent is decided by its route’s permission check, not by the gate sequence.

Identity — who is this agent, and should it be allowed to act

Every agent in a hybrid workforce acts for a resolved person or service principal; the agent owner is accountability metadata, not a fallback identity for a named unresolved caller. The runtime records whether identity came from a credential or the current owner/definition attestation. The provider abstraction is NhiProvider. Current workflow and native runners use OwnerAttestationNhiProvider, which validates the active named owner and current definition hash. Credential-consuming tool/procedure paths also resolve the exact configured credential and beneficiary/on-behalf-of grant before use; they do not synthesize a credential. The provider contract has three methods, called at three different points in the pipeline:
  • verifyIdentity(agentDoc) — runs in the identity gate (after agentStatus and before permission). Returns { verified, grantedScopes, expiresAt }.
  • checkScope(grantedScopes, requiredScope) — runs in the nhiEntitlement gate (after autonomyHoldTable and before policyRules). Confirms the agent’s granted scopes cover the action’s required scope, derived from the dispatch actionType.
  • getCredential(agentDoc, targetId) — called by the credential broker when a pass decision needs a dispatch credential.
An unconfigured provider/basis is recorded as unverified evidence, and identity verification refuses it: the check always enforces. A test provider or successful local fixture is not production identity evidence.

Lifecycle — how an agent enters, earns trust, and leaves

Every agent in Forge follows a governed lifecycle. Before an agent dispatches production workloads, it progresses through a structured sequence of phases — each with constraints, timelines, and promotion criteria. This is how the Trust Fabric prevents unvetted agents from accumulating risk and ensures every production agent has been explicitly approved. The four phases form a linear progression: The critical operating discipline is the POC clock. Agent intake stamps a POC agent with pocCreatedAt and a pocExpiresAt 60 days out, and a reminder goes out at day 30. A sweep runs every 6 hours and applies the promotion test to each expired POC agent: it must be in active status, carry a risk tier (T1 to T4), and have an accountable owner (ownerPersonId) who is an active person. An agent that passes is promoted to Staging (its definitionHash is recomputed, because lifecyclePhase is a hash input); an agent that fails is sunset, and the sunset notification names each failed condition. Legacy POC rows with no pocExpiresAt get a 60-day grace backfill on the first sweep. Promotion to Production remains an explicit operator action.

Agent trust — what an agent is allowed to do

Trust Fabric governs what an agent can do, not just whether it can execute. Every agent operates within a trust envelope defined by two interlocking concepts:
  • Rung — one of four autonomy levels stored on the agent. The Autonomy holds gate, 13th in the gate sequence, compares it with what each action declares about itself and allows, holds or blocks the action. A workflow run also launches under one rung, and Console shows it on the run.
  • Authority bounds — hard limits on spend, duration, concurrency, and handoffs derived from the agent’s role and overrides.
The four rungs, the table of what each allows, holds and blocks, and the rung an agent gets when none is stored are defined once, in The four rungs. Setting a Production agent at Rung 4 permits writes within its grants and bounds. Every dispatch still passes permission, Credential, budget, policy, and kill-switch checks. A financial action has no automatic two-agent hold; add an explicit policy or workflow review step when people must review it. Autonomy is not unrestricted access.

What GovernanceDecision tells you

Every governance evaluation produces a GovernanceDecision. This is what every dispatch site sees when the pipeline returns. The decision record carries everything you need to debug a block or hold without opening a console:
  • blockedBy — gate name, error code, message, retryable flag
  • heldBy — policy name, policy ID, trigger that caused the hold
  • budgetSnapshot — current spend and limits for the agent and all envelopes
  • trustSnapshot — a retained compatibility field with no enforcement meaning; agents carry no trust level and no gate reads one
  • scopeConstraints — the role limits (environments, tool allow/deny lists, data access)
  • explanation — structured reasons + unblock hints
The explanation.unblockHints field is the most useful. For a block on budgetEnvelopes, the hint is concrete: “raise the team monthly cap from $500 to $600, or wait until the envelope resets in 4 days.” Operators can act on it without code-level knowledge of the engine.

Emergency stops

Forge has several stop buttons at different blast radii. Knowing which one to flip — and how fast it takes effect — is the difference between containing an incident in seconds and chasing it through hours of cleanup.
Emergency stops are for emergencies — a regression you cannot triage in the moment, a leaking secret, a runaway loop, evidence of compromise. They are not for reducing dispatch volume (use budgets and concurrency limits) or for retiring one agent permanently (archive it). Every flip is a documented operator action in the audit trail.

The switches

Forge has two kinds of stop. Emergency stops are platform-wide and live in Forge Console under Trust Fabric → Emergency stops: the platform kill switch and three doors. Pauses are narrow: one agent or one workflow. Every emergency stop needs switches:use, a written reason and a confirmation. The full coverage map of what each one stops is on the Emergency stops Console page.

Platform kill switch — gate 1

The platform kill switch is checked by the first gate in the governance sequence. The agents door is the second gate; the people and API keys doors are checked where those requests enter Forge (Console, Slack, email and the API). When the kill switch is engaged:
  • New governed work is refused with the error code platform_killed, whatever any door says. A stopped door refuses with governance_door_stopped.
  • A Platform API or MCP caller receives 403 with the code operator_stopped and a fixed message; the operator’s reason and name never reach it. The recorded decision carries platform_killed.
  • The refusal is not retryable. Resuming the switch is the only way to admit work again.
  • If Forge cannot read the switch state, the request fails before any effect rather than treating the platform as running.
The kill switch stops new work. A step that is already running finishes; the next governed tool call or model-routed step is refused. It does not refund spend, delete outputs or undo external effects. When in-flight work is itself the problem, the switch buys time by preventing more work while the running steps drain. Each refusal is recorded as a Trust Fabric decision, and each flip is audited with the operator and the reason. Reconstructing what was blocked while the switch was engaged is one filter on Trust Fabric → Decisions.

Agent pause — a surgical stop

When the problem is one agent — a prompt regression, a model swap that went wrong, a misconfiguration — pause that agent. A paused agent can no longer be composed for dispatch:
  • Every dispatch site that uses the agent — chat, factory, copilot and workflow nodes — fails when it tries to compose the agent.
  • The pause is separate from gate 1: pausing one agent does not affect other agents.
  • Resume it in the Console or with POST /api/v3/agents/{agentId}/resume (switches:use, with a reason); it can be composed again on the next dispatch. A PATCH that sets status: "active" does not resume an operator-paused agent: it answers 409 and writes nothing.
Prefer this when you can name the agent. It keeps the rest of the fleet running.

Workflow pause — one workflow

When one workflow is producing bad runs — its schedule fires too aggressively, a service it depends on is degraded, or it has a logic error you have not diagnosed — pause the workflow:
  • Manual triggers for the workflow are rejected.
  • Scheduled triggers are skipped, but the schedule still advances to its next run time, so it stays alive and resumes firing when you unpause.
  • In-flight runs continue, and their steps still pass through the gate sequence. A workflow pause does not halt running runs.
This is the right tool when the schedule is the source of the problem: it stops new runs while existing ones drain.

Which switch to flip

  1. Is the problem in one agent’s outputs? Pause that agent.
  2. Is the problem in one workflow’s behavior? Pause that workflow.
  3. Is the problem one way in — a leaked API key, a misbehaving integration, a flood of Slack messages? Stop that door.
  4. Is the problem fleet-wide — a model regression, a security incident, a compromised credential? Engage the platform kill switch.
  5. Not sure yet? Engage the platform kill switch, then triage. An unnecessary global stop is loud and auditable; a fleet-wide incident left running is not.
Reaching for the kill switch first is a defensible discipline when you do not know the blast radius: it is loud, it is audited, and it is the cheapest thing to undo.

Emergency stop runbook

  1. Write a real reason. Every flip carries a reason — “model regression confirmed by eval X”, “leaked secret in agent prompt, rotating now”. It is the audit record.
  2. Page the right team. An engaged kill switch means production agents are stopped. Page whoever owns the incident the switch is containing.
  3. Confirm the stop is working. The Emergency stops page changes only after the server confirms the switch. New governed work then appears under Trust Fabric → Decisions as blocked, with platform_killed (or governance_door_stopped for a door).
  4. Plan the resume. A stop is containment, not resolution. Confirm the underlying issue is fixed before you resume; the resume is audited and will be read in the post-incident review.
  5. Review what was refused. After resuming, filter Trust Fabric → Decisions to blocked decisions between the stop and the resume. That list is every piece of work that was prevented — the baseline for an impact assessment.

Operator runbook

When you stand up Trust Fabric for the first time:
  1. Establish identity and credential authority. Confirm every representative agent has a current active owner, matching definition attestation, resolved principal, required permission keys, and exact credential/on-behalf-of grant where needed. Unresolved evidence is a blocker, not an implied pass.
  2. Place every agent on a rung and role explicitly. Verify the principal and role permission layers carry the intended permissions and constraints; the permission gate always enforces, so a missing permission is a deny.
  3. Know your kill switch. The platform kill switch is gate 1 — engaging it refuses new governed work everywhere. Make sure you know how to flip it, and who holds switches:use. See Emergency stops.
  4. Wire the audit retention. auditEvents retains for 365 days by default. Compliance requirements may demand longer; if so, configure the retention sweep accordingly. See Audit.
  5. Know the three doors. Every governance control enforces; there is no per-control shadow mode to promote. For an incident, the Console’s Emergency stops page offers three stop controls beside the kill switch: people (stops mutations and actions authorized for a person; reads and the switch controls themselves stay available), API keys (stops API-key requests), and agents (stops agent dispatch, checked right after the kill switch). Stopping or resuming a door requires switches:use and a written reason, and is audited. A stopped door refuses new work with governance_door_stopped; a door with no row is open. The publish judge keeps its own advisory setting (off, warn, or enforce, seeded at warn), changed through the audited setPosture call.

Do it over the API

These calls use the FORGE_BASE and ACCESS_TOKEN set up in the Raw HTTP tab of the quickstart. The pause and resume calls accept that token; the kill-switch calls refuse an External App token, so send a Personal key or a platform API key for those. Pause one agent, with a reason for the audit trail:
This needs switches:use at the agent’s home and agents:read there to see it; no Forge agent holds switches:use, so give it to a Personal key as a short-expiry scope. POST /api/v3/agents/{agentId}/resume takes a reason the same way. Read the platform kill switch, which also needs switches:use:
POST /api/v3/trust-fabric-kill-switch/engage engages it with a reason; releasing it stays in Console. A workflow pause has no HTTP operation: use the workflow in Production → Workflows. Over MCP, pause the agent with forge_call_operation:
and read the kill switch with forge_call_read_operation: