> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gloo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Trust Fabric in production

> Operate with the governance pipeline live: coverage, identity, lifecycle, agent trust, what each disposition means, and the emergency stops.

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](https://docs.gloo.com/forge/architecture/flows/governance-pipeline.md). When something is wrong and you need to stop work fast, go to [Emergency stops](#emergency-stops).

> [!NOTE]
>
> **When to reach for something else.** If you are debugging a single failed step, the [audit feed](https://docs.gloo.com/forge/run/audit.md) 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](https://docs.gloo.com/forge/run/approvals-and-hitl.md). For budget-specific concerns, jump to [Budgets & Cost](https://docs.gloo.com/forge/run/budgets-and-cost.md).

***

## 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.

| Dispatch surface | Pipeline |
| - | - |
| Workflow Agent node / delegated run | Full gate sequence |
| Chat dispatch | Full gate sequence |
| Factory worker dispatch | Full gate sequence |
| Factory manager dispatch | Full gate sequence |
| PA (personal agent) dispatch | Full gate sequence |
| Architect dispatch | Full gate sequence |
| Copilot run-analysis | Full gate sequence |
| Judge, coding-agent, external-inference, builder dispatch | Full gate sequence |
| Workflow run launch | Shorter launch sequence (`actionType: workflow_run_launch`) |

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.

> [!WARNING]
>
> **What the pipeline does NOT cover.** Trust Fabric governs dispatches. Building an agent's configuration ([agent composition](https://docs.gloo.com/forge/architecture/flows/workflow-execution.md#2-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:

| Phase | Window | What it allows | Auto-sunset |
| - | - | - | - |
| **POC** | 60-day trial | Agent active but time-bounded — for validation against real traffic | At expiry: an `active` agent with a risk tier and an active accountable owner is auto-promoted to Staging; any other agent is sunset |
| **Staging** | Intermediate | Pre-production validation, and the auto-promotion target when a POC clock expires on a healthy agent. | None |
| **Production** | Indefinite | Full dispatch, full autonomy bounds | Operator-initiated retirement |
| **Sunset** | Terminal | Agent retired. Definition preserved for audit. | — |

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](https://docs.gloo.com/forge/concepts/trust-fabric.md#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.

| Disposition | Meaning | Operator action |
| - | - | - |
| **pass** | All gates passed. Step proceeds to dispatch. | None — read the audit if you want to know which gates fired |
| **block** | A gate failed. Step marked failed with structured error code. | Read `blockedBy` (gate name + error code) and `explanation.unblockHints` |
| **hold** | Approval required. Execution pauses for human decision. | Resolve through the [approval surface](https://docs.gloo.com/forge/run/approvals-and-hitl.md) |

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.

> [!WARNING]
>
> 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.

| Switch | What it stops | Where to flip it |
| - | - | - |
| **Platform kill switch** (Stop everything) | New governed work on every path; not Console edits | Trust Fabric → Emergency stops |
| **People door** | Console writes and governed actions, Slack messages, email hold replies, and person-token inference chat | Trust Fabric → Emergency stops |
| **API keys door** | Platform API and MCP requests from an External App or a Personal key, reads included | Trust Fabric → Emergency stops |
| **Agents door** | Agent dispatch, platform-native runs, procedures, tool calls, model-routed steps, output delivery, and new HTTP and email admissions | Trust Fabric → Emergency stops |
| **Agent pause** | One agent, everywhere it is dispatched | The agent in Workforce → Agents |
| **Workflow pause** | New runs of one workflow; running runs continue | The workflow in Production → Workflows |

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](https://docs.gloo.com/forge/console/trust-fabric/emergency-stops.md) 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](#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](https://docs.gloo.com/forge/run/audit.md).
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](https://docs.gloo.com/forge/quickstart.md). The pause and resume calls accept that token; the kill-switch calls refuse an External App token, so send a [Personal key](https://docs.gloo.com/forge/console/settings/personal-keys.md#choose-a-credential) or a platform API key for those. Pause one agent, with a reason for the audit trail:

```bash theme={null}
curl -sS -X POST "$FORGE_BASE/api/v3/agents/$AGENT_ID/pause" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pause-$AGENT_ID-v1" \
  -d '{"reason": "Prompt regression confirmed by eval; rolling back"}' \
  | jq '.data | {agentId, status, changed}'
```

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`:

```bash theme={null}
curl -sS "$FORGE_BASE/api/v3/trust-fabric-kill-switch" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  | jq '.data'
```

`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`:

```json theme={null}
{
  "operationId": "pauseAgent",
  "input": { "id": "<agent slug>", "reason": "Prompt regression confirmed by eval; rolling back" },
  "idempotencyKey": "pause-<agent slug>-v1"
}
```

and read the kill switch with `forge_call_read_operation`:

```json theme={null}
{ "operationId": "getGlobalKillStateAdmin", "input": {} }
```

***

## Related

* [Governance Pipeline flow](https://docs.gloo.com/forge/architecture/flows/governance-pipeline.md)
* [Approvals and HITL](https://docs.gloo.com/forge/run/approvals-and-hitl.md)
* [Budgets and cost](https://docs.gloo.com/forge/run/budgets-and-cost.md)
* [Audit](https://docs.gloo.com/forge/run/audit.md)
* [Scheduling and triggers](https://docs.gloo.com/forge/run/scheduling-and-triggers.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.