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.
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 isNhiProvider. 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 theidentitygate (afteragentStatusand beforepermission). Returns{ verified, grantedScopes, expiresAt }.checkScope(grantedScopes, requiredScope)— runs in thenhiEntitlementgate (afterautonomyHoldTableand beforepolicyRules). Confirms the agent’s granted scopes cover the action’s required scope, derived from the dispatchactionType.getCredential(agentDoc, targetId)— called by the credential broker when apassdecision needs a dispatch credential.
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.
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 flagheldBy— policy name, policy ID, trigger that caused the holdbudgetSnapshot— current spend and limits for the agent and all envelopestrustSnapshot— a retained compatibility field with no enforcement meaning; agents carry no trust level and no gate reads onescopeConstraints— the role limits (environments, tool allow/deny lists, data access)explanation— structured reasons + unblock hints
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.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 withgovernance_door_stopped. - A Platform API or MCP caller receives
403with the codeoperator_stoppedand a fixed message; the operator’s reason and name never reach it. The recorded decision carriesplatform_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.
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 areason); it can be composed again on the next dispatch. APATCHthat setsstatus: "active"does not resume an operator-paused agent: it answers409and writes nothing.
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.
Which switch to flip
- Is the problem in one agent’s outputs? Pause that agent.
- Is the problem in one workflow’s behavior? Pause that workflow.
- Is the problem one way in — a leaked API key, a misbehaving integration, a flood of Slack messages? Stop that door.
- Is the problem fleet-wide — a model regression, a security incident, a compromised credential? Engage the platform kill switch.
- 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.
Emergency stop runbook
- 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.
- Page the right team. An engaged kill switch means production agents are stopped. Page whoever owns the incident the switch is containing.
- 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(orgovernance_door_stoppedfor a door). - 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.
- 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:- 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.
- 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.
- 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. - Wire the audit retention.
auditEventsretains for 365 days by default. Compliance requirements may demand longer; if so, configure the retention sweep accordingly. See Audit. - 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:useand a written reason, and is audited. A stopped door refuses new work withgovernance_door_stopped; a door with no row is open. The publish judge keeps its own advisory setting (off,warn, orenforce, seeded atwarn), changed through the auditedsetPosturecall.
Do it over the API
These calls use theFORGE_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:
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:
forge_call_read_operation:

