Skip to main content
Machine credentials can create, edit, assign and move factory tasks, and Console task reads follow the factory home.
POST /api/v2/factories/createTask, PATCH /api/v2/factories/updateTask, POST /api/v2/factories/assignTask and POST /api/v2/factories/transitionTask write the tasks of a factory you may read. MCP adds forge_create_factory_task, forge_update_factory_task, forge_assign_factory_task and forge_transition_factory_task.Each write needs the key Console checks for the same operation, held at the task’s factory home. Creating and moving a task need factory:manage, under the new published scope factories:write:tasks; creating also needs it at the deployment root, where Console files the task. Editing and assigning need projects:manage, under the new published scope projects:write. Neither scope is given to the built-in apps. An agent assignee must be an active agent member of the task’s factory, and a person is never assigned. A task write schedules nothing and does not start an agent. See Factories.In Console, a task with no project is no longer shown to every signed-in person. A task that has a factory needs factory:read at the factory’s home, and a task with neither a project nor a factory needs projects:read. Either kind stays visible to the person it is assigned to.
Organization-owned External Apps can create and edit workflow drafts.
POST /api/v2/workflows/create, PATCH /api/v2/workflows/updateDraft, forge_create_workflow and forge_update_workflow_draft accept name, description and canonical typed inputs under workflows:write:draft, with read and write grants at the chosen home. Drafts are shared with Console; keyed retries recheck current draft visibility. Publishing, graph changes and live execution stay separate.
Machine credentials can read whether each agent is owned, reviewed and attested, and where a person fixes it.

Summary

GET /api/v2/governance/listAgentAccountability pages, and GET /api/v2/governance/getAgentAccountability reads, each agent’s accountability: whether it is owned by an active person, its owner review is on time, and its identity is attested for its current definition. Both need the existing governance:read bundle (grants:read, policies:read, audit:read), decided at each agent’s home together with agents:read. MCP adds forge_list_agent_accountability and forge_get_agent_accountability. See Agent accountability.

New

  • Each row carries the agent_ownership and identity_verification gates’ finding codes and, when there is a finding, a Console handoff (/trust-fabric/agent-trust?agent=…, requiredPermission: agents:manage). An inactive owner reads as unowned.
  • listAgentAccountability takes cursor, limit (1–50, default 25) and findings=only, with meta.partial; a page may be short or empty while meta.hasMore is true.
  • No owner identity, attesting person or definition hash is returned, and the reads do not say whether a dial enforces.
  • Repairs stay person-only: a person assigns an owner, acknowledges a review or attests an identity in the Console; no API key or External App can.
Machine credentials can read objectives and key-result progress without worker identity.

Summary

New objective list, get and key-result list routes and MCP tools use objectives:read at the deployment root. Objective paging is filter-bound and truthful; worker owner ids are withheld. Objective and key-result writes remain person-only. See Objectives.
Read the factory blueprint catalog over the API and MCP with factory read at the deployment root.

Summary

New GET /api/v2/factories/listBlueprints and GET /api/v2/factories/getBlueprint read the deployment’s factory blueprint catalog: name, factory type, version, status, default team, extra channels and budget defaults. Blueprints have no home org unit, so they need factory:read held at the deployment root; a grant only below the root, or at a partner root, is refused with 403 and requiredPermission: "factory:read". Factory configuration, manager prompt text, the creator, a channel’s external link and repository settings are not returned. See Factories.

New

  • listBlueprints lists ACTIVE blueprints newest first, or all of them with includeDeprecated=true, optionally of one factoryTypeId (with both, DEPRECATED blueprints come first), paged by cursor (1–50 per page).
  • MCP tools forge_list_factory_blueprints and forge_get_factory_blueprint in the factories group, read-only with structured results; ForgePlatformClient.listFactoryBlueprints and getFactoryBlueprint. GET /api/v2/actor lists the new operations, and the OpenAPI document gains FactoryBlueprint.
Machine credentials can inspect the tool and tool-set catalog without receiving secrets or invocation authority.

Summary

New GET /api/v2/tools/list, /get, and /listSets routes and MCP tools expose a read-only, platform-global tool catalog under tools:read. Responses include safe identity, effect, version and grant metadata plus optional stored JSON Schemas. Credential configuration, internal paths, sandbox commands, egress configuration and agent assignments remain private, and there is no invocation endpoint. See Tools.
Machine credentials can read the fiscal calendars used by workflow expressions.

Summary

New GET /api/v2/workflows/listFiscalCalendars and getFiscalCalendar routes, plus forge_list_fiscal_calendars and forge_get_fiscal_calendar, expose the deployment-wide calendar catalog under workflows:read. Responses omit row ids and creator/updater identities. Calendar writes remain person-only in Console.
Generate and check secret-free Forge MCP configurations for Claude Desktop and VS Code.

Summary

Forge MCP now publishes generated stdio configurations for Claude Desktop with a static MCP key and VS Code with External App client credentials. A checked fixture pins each host shape, allowed environment variables, credential placeholders, and the setup, rotation, revocation, and recovery lifecycle. See Forge MCP server.

New

  • Public buildStdioHostConfig and classifyCredentialRecovery helpers in @tangogroup/forge-mcp.
  • A checked two-host onboarding fixture that rejects credential values and configuration or lifecycle drift.
  • Protocol coverage proving static mode makes no token mint and External App mode mints once and reuses the cached token while MCP tools/list verifies local discovery. Operators prove a replacement credential separately with the authorized forge_list_agents read.

Availability

Interactive hosted OAuth sign-in remains unavailable. These configurations use service credentials and add no person delegation or new permission.
Machines can read whether Forge is stopped or global spend is frozen.

Summary

New GET /api/v2/health/stops and MCP tool forge_get_stop_state report the global kill switch and global spend freeze under health:read. The response contains no operator reason or identity, budget values, agent-specific freeze, or enforcement posture. Stop, freeze, and resume remain person-only Console actions with a named actor, reason, and audited rollback. See Stop state.
Machine credentials can inspect and control knowledge source syncs without receiving connection configuration.

Summary

New knowledge source routes and MCP tools list sources, get one, list its newest runs, and rename, retime, pause or resume it. Reads use knowledge:read and readable namespaces; changes use knowledge:manage and writable namespaces. Configuration, cursors, container ids, identity mappings, curation, trust weight and creators never leave the server. Connecting and removing sources remain person-only pending the credential-use policy.

New

  • GET /api/v2/knowledge/sources/list, /get and /listRuns; POST /api/v2/knowledge/sources/update with 24-hour idempotent response replay while the source remains writable.
  • MCP tools forge_list_knowledge_sources, forge_get_knowledge_source, forge_list_knowledge_source_runs and forge_update_knowledge_source.
  • Console source creation now decides knowledge:manage at the target namespace, and a removal is audited when requested rather than only after purge.
Platform actors read their organization's gate denial, trust policy and authorization surface reports with explicit coverage.

Summary

New GET /api/v2/governance/getGateDenyReport, /getPolicyFiredReport and /getAuthzSurfaceReport (scope governance:read) count the Trust Fabric decisions recorded for the credential’s acting organization in a window of at most 30 days: blocked decisions by failed gate, blocked and held decisions by trust policy id, and permission denials by dispatch surface. The population is the one listEvidence reads, and each report states its window, windowCap, resolutionRevision and coverage (complete, partial or unavailable). See Organization reports.

New

  • The actor must hold grants:read, policies:read and audit:read at its acting organization; a credential with no acting organization gets 403. Only startAt, endAt and windowCap (1-2,000, default 2,000) are accepted: an organization, person or other parameter returns 400.
  • The window cap counts every organization’s decisions in the window, so a busy deployment reports partial with reason window_cap until the window is narrowed.
  • MCP tool forge_get_governance_report in the governance group with a report selector; ForgePlatformClient.getGateDenyReport, getPolicyFiredReport and getAuthzSurfaceReport. The MCP server registers one more tool. GET /api/v2/actor lists the new operations, and the OpenAPI document gains GovernanceDecisionReport.
  • Reports that name people and the deployment-wide overview and policy effectiveness reports stay in the Forge Console.
Capability credential health points machines to the person action that resolves a connection.

Summary

GET /api/v2/capabilities/get, GET /api/v2/providers/get, forge_get_capability, and forge_get_provider now include a strict Console handoff on each credential-health row. It names approve, connect, or rotate, the Console page, and the permission a person needs. Credential administration remains person-only, and the handoff never contains a Credential id, name, scope, requester, field, or value.

Changed

  • Provider detail shows nested Credential rows only where the Console reader holds credentials:read at that Credential’s scope.
  • Credential lifecycle writes record value-free audit events, and provider options refuse secret-shaped keys and values.
  • The unused public deploymentConfig.updateConfig and settingsInternal.updateConfig whole-object overwrites are removed.
Read a factory's token spend over the API and MCP with factory read and cost read at its home.

Summary

New GET /api/v2/factories/getSpend returns one factory’s token spend over a window of at most 30 days: totals, and breakdowns by source, model, agent worker and task. It needs factory:read and cost:read — your credential’s scopes must reach both (factories:read and cost:read), and your role grants must hold both at the factory’s home org unit; without cost:read it answers 403 with requiredPermission: "cost:read". Spend is factory token-event attribution, not the deployment cost rollup. Codebase browsing stays Console-only. See Factories.

New

  • At most 10,000 events are summed, newest first; meta.partial is always present; when it is true, every event from coveredFrom through endTime was summed and none older. Each breakdown holds at most 100 entries and says truncated when more existed.
  • Spend is summed in micro-dollars and rounded to cents once. With taskId, only this factory’s events for that task are summed. Agent workers are itemized; every human worker’s spend is one humanWorkers row with no worker ID. The provider, project, workflow run, org-unit columns and micro-dollar cost are not returned.
  • MCP tool forge_get_factory_spend in the factories group, read-only with a structured result; ForgePlatformClient.getFactorySpend. GET /api/v2/actor lists the new operation, and the OpenAPI document gains FactorySpend.
Machine credentials can read the tasks of factories they may read.

Summary

GET /api/v2/factories/listTasks and GET /api/v2/factories/getTask (scope factories:read) read a factory’s tasks: status, priority, kind, tags, and whether an agent or a person holds each one. A task is visible only through its factory, under factory:read at the factory’s home org unit; a task with no factory is never returned. Creating, editing, assigning and moving tasks, and starting factory work, are done by a person in Console. See Factories.

New

  • listTasks takes a required factoryId, an optional status, and the usual limit/cursor paging; rows come in index order (by status, then newest first).
  • getTask adds the task’s description.
  • No creator, person assignee identity, project, GitHub link or other task link is returned; a person holder is reported as { "type": "person" }.
  • MCP tools forge_list_factory_tasks and forge_get_factory_task in the factories group.
The governance compliance export pages to the end of any window and the three compliance exports are documented.

Summary

GET /api/v2/compliance/export/governance now reads a bounded number of records per page and pages any window to its end. Before, a window holding more than 20,000 records of one disposition ended early with no signal. The three compliance exports are documented in the OpenAPI document and under Compliance.

Changed

  • When more governance records share one millisecond than a page can read, the page adds partial: true and saturatedAt to data: the rest of that millisecond is skipped and cursor continues below it. A page without skipped records is unchanged, and a cursor issued earlier keeps working.
  • Exported records keep their stored shape, including principal and person-resource audit events: the exports are for a deployment-root auditor. No MCP tool exposes them.
  • The OpenAPI document gains the Compliance tag, exportAuditEvents, exportGovernanceDecisions, exportComplianceSummary, and ComplianceRecordPage, ComplianceGovernancePage and ComplianceSummary. GET /api/v2/actor lists the three exports; their permissionSatisfied reflects the acting-unit check only, since the exports also require the deployment root.
Compliance exports require audit:read at the deployment root.

Summary

GET /api/v2/compliance/export/audit, /export/governance and /export/summary export the whole deployment’s audit and governance records. Compliance exports cover the whole deployment, so they require audit:read granted at the deployment root; a credential granted only below it receives 403. See Compliance exports over the Platform API.

Breaking

  • Narrowing. Before, a key or app holding audit:read (scope compliance:read) where it acts, including at a tenant org unit or at a partner organization’s own root, exported every organization’s records. It now gets 403 forbidden with requiredPermission: "audit:read", recorded as an authorization denial, before any record is read. Platform-scope grants and every migrated key’s root compatibility grant keep the exports, with unchanged responses.
The coarse Trust Fabric policy simulator is retired; policy simulation replays recorded decisions only.

Summary

The coarse reactive queries opsInternal.simulateGovernancePolicy and simulatePolicy are removed. They read every organization’s recorded decisions, treated a fact the record does not hold as a non-match, and listed “would block” runs whatever the policy’s action or enforcement. No Console page called them, and no API route or MCP tool exposed them.

Removed

  • simulateGovernancePolicy and simulatePolicy. Use policySimulation.simulate in Forge Console, or POST /api/v2/governance/simulateTrustPolicy and forge_simulate_trust_policy from a machine credential. Both report a missing fact as unknown rather than as a non-match.
Read a run's structural milestone timeline over the API and MCP.

Summary

New GET /api/v2/runs/listEvents pages a run’s structural timeline, oldest first: checkpoints, handoffs, guardrail trips, interventions, cost milestones, errors and completion. It needs runs:read at the run’s home and at every company it carries, the rule GET /api/v2/runs/get uses; any other run is a 404. Milestones only: tool calls, model messages, error payloads, agent identity and cost amounts are never returned (cost stays on GET /api/v2/cost/summary). See List a run’s structural timeline.

New

  • listEvents takes runId, cursor and limit (1–100, default 25); a page may be short while meta.hasMore is true, and an unreadable cursor is a 400.
  • MCP tool forge_list_run_events in the runs group, read-only with a strict structured result; ForgePlatformClient.listRunEvents. The MCP server registers one more tool. GET /api/v2/actor lists the new operation, and the OpenAPI document gains RunEvent.
Machine credentials can author evaluation sets for agents they may write and compare runs they may read.

Summary

POST /api/v2/evals/create, PATCH /api/v2/evals/update and POST /api/v2/evals/archive (scope agents:write) author evaluation sets: a set bound to an agent needs agents:write at that agent’s home org unit, and an unbound catalog set needs it at the deployment root. GET /api/v2/evals/compareRuns (scope agents:read) compares 2-10 runs you may read, computed on read and never stored, with an explicit comparable verdict. Authoring starts no run and spends nothing: sets created through the API are never run by the weekly regression evals. Starting or cancelling a run is not available over the API. See Evals.

New

  • Strict bodies with published limits (1-200 test cases with unique ids, 20,000-character inputs, weights above 0 up to 100); dimensions and goldenDatasetId are refused because the eval runner never reads them.
  • All test cases of a set together are at most 800,000 bytes as JSON.
  • expectedUpdatedAt on update refuses a stale edit with 409 conflict; an archived set cannot be edited, and archiving is one-way. The test cases of a set created in the Console or seeded, which the weekly regression evals run, can only be changed in the Console.
  • A same-key retry replays the recorded answer only while you may still read and write the set (the eval_set replay policy).
  • MCP tools forge_create_eval_set, forge_update_eval_set, forge_archive_eval_set and forge_compare_eval_runs in the agents group.
Read the knowledge review queue and Learning feed over the API and MCP; a person still decides each item in Console.

Summary

New GET /api/v2/knowledge/listReviews, /getReview and /listLearning read the knowledge review queue and the Learning feed for the namespaces a credential can read, with knowledge:read held at the deployment root. Items never name the reviewer, the reviewer’s note, the assignee, the run or the decision, and a source-restricted item never appears. Every pending item carries a Console handoff naming requiredPermission: "knowledge:manage": a person decides it in Console, and no API or MCP operation approves, dismisses, merges or verifies a review item. See Review queue and Learning feed.

New

  • listReviews filters by repeatable status and kind and one readable namespace, pages by cursor (1–100 per page) and sets meta.partial when its bounded read stopped with items left. getReview answers 404 for an item the credential cannot see.
  • listLearning pages a window of at most 90 days, filtered by repeatable kind and scopeType; its items drop the actor, agent, run and reason.
  • MCP tools forge_list_knowledge_reviews, forge_get_knowledge_review and forge_list_knowledge_learning in the knowledge group, read-only with structured results; ForgePlatformClient.listKnowledgeReviews, getKnowledgeReview and listKnowledgeLearning. The MCP server registers three more tools. GET /api/v2/actor lists the new operations, and the OpenAPI document gains KnowledgeReviewItem, KnowledgeReviewHandoff and KnowledgeLearningItem.
Read trust policies and their revisions, and replay one historically against recorded decisions.

Summary

New GET /api/v2/governance/listTrustPolicies and /listTrustPolicyRevisions read the Trust Fabric gate policies (trust policies) and each policy’s revision chain at the deployment root, without the author. New POST /api/v2/governance/simulateTrustPolicy replays a candidate, or a stored revision, against the decisions recorded for the credential’s acting organization in a window of at most 30 days. A historical simulation replays facts recorded on past decisions. It is not an authorization, does not predict today’s gates, and reports any fact the record does not hold as unknown. See Trust policies.

New

  • listTrustPolicies lists each policy once at its newest revision; listTrustPolicyRevisions returns one chain oldest first, with meta.partial past 200 revisions. Both need grants:read, policies:read and audit:read at the platform scope or the deployment root.
  • simulateTrustPolicy evaluates only decisions recorded for exactly the acting organization with no private fence, never client-reported ones. Each item is match, none or unknown, with the missing recorded fields named; a page states coverage and carries historical: true. A condition on principal.personId or principal.servicePrincipalId returns 400. It is a read carried in a body: no Idempotency-Key.
  • MCP tools forge_list_trust_policies, forge_list_trust_policy_revisions and forge_simulate_trust_policy in the governance group, read-only with structured results; ForgePlatformClient.listTrustPolicies, listTrustPolicyRevisions and simulateTrustPolicy. The MCP server registers three more tools. GET /api/v2/actor lists the new operations, and they are in the OpenAPI document.

Changed

  • listPolicies and forge_list_policies are described as approval policies, apart from trust policies. Their behavior is unchanged.
  • No machine route creates or changes a policy: that stays person-only, in the Console.
Retry a stuck knowledge entry and request a source sync, over the API and MCP.

Summary

Two knowledge health remedies the Console offers are now in the API and MCP, under knowledge:manage and only for knowledge in the caller’s writable namespaces: retrying a stuck pending entry and asking a source to sync now. See Remedies.

New

  • POST /api/v2/knowledge/retryPendingEntry ({entryId} → {entryId, scheduled}) and POST /api/v2/knowledge/sources/requestSync ({sourceId} → {sourceId, outcome}, scheduled | running | inactive). The OpenAPI document gains strict RetryKnowledgeEntryResult and RequestKnowledgeSourceSyncResult schemas.
  • A same-key repeat returns the recorded result only while the entry or source is still writable by the caller (see Knowledge remedy replay).
  • MCP tools forge_retry_knowledge_entry and forge_request_knowledge_source_sync in the knowledge group, with structured results and an optional idempotencyKey.
Read a workflow's schedules and other triggers over the API and MCP.

Summary

New GET /api/v2/workflows/listTriggers and GET /api/v2/workflows/getTrigger read a workflow’s triggers: kind (cron, one_shot, ingress, email), timing, whether each follows the active version or pins one, the org unit its fires run at, and when it fires next. A trigger is visible only when the caller holds workflows:read at both the workflow’s home and the trigger’s orgUnitId. The owner, creator, stored inputs and ingress material are never returned. See listTriggers.

New

  • GET /api/v2/workflows/listTriggers?workflowId= (workflows:read, scope workflows:read) pages newest first with limit (at most 50) and cursor, and meta.hasMore. GET /api/v2/workflows/getTrigger?id= returns one trigger. A trigger the caller cannot read is left out or answers 404.
  • MCP tools forge_list_workflow_triggers and forge_get_workflow_trigger in the workflows group, read-only with structured results; ForgePlatformClient.listWorkflowTriggers and getWorkflowTrigger. The MCP server registers two more tools. GET /api/v2/actor lists both operations, and the OpenAPI document gains the strict WorkflowTrigger schema.
  • Changing a trigger stays person-only (Console): workflows:manage can never be held by an API key, External App or agent.
An API key reaches an agent's memory only at the agent's home.

Summary

The memory routes (GET /api/v2/memory/list and /get, POST /api/v2/memory/create and /delete, PATCH /api/v2/memory/update) and the Forge MCP memory tools now decide an API key’s access at the home of the agent a memory names: the key’s role grants must hold memory:read at the agent’s home org unit to read its memory and memory:write there to write it. External Apps keep their owner-scope chain. See Which agents’ memory the API reaches.

Breaking

  • Narrowing. Before, an API key with no External App reached every non-personal agent’s memory, whatever org unit its grants were at. A key granted only below the deployment root no longer reaches other organizations’ agents, and no key reaches the memory of an agent with no home. Keys granted at the deployment root or the platform scope keep reaching every homed agent.
  • An unreachable agent’s memory lists empty, is left out of a listing by channelId alone, and answers 404 to get, update and delete; create answers 403 “agentId’s home does not grant this credential memory:write”. A key holding memory:read but not memory:write at the agent’s home reads its memory and gets 403 on update and delete.
  • A same-key repeat of a memory write returns the recorded response only while the key may still write that agent’s memory at its home; otherwise the non-disclosing 409.
External Apps write only the agents they own, at each agent's home; operator pauses and terminations hold, and delete archives.

Summary

POST /api/v2/agents/create, PATCH /api/v2/agents/update and DELETE /api/v2/agents/delete, and the Forge MCP forge_create_agent, forge_update_agent and forge_delete_agent tools, decide every write at the agent’s home. Create homes the agent at the calling App’s owning org unit, so the App can read what it creates. See Who may write which agent and Agent write replay.

Fixed

  • An External App could set a paused or terminated agent back to active through PATCH /api/v2/agents/update. A status change on an agent whose status is paused, deprecated (terminated) or archived is now 409 conflict and nothing is written; resume a paused agent in the Console.
  • DELETE /api/v2/agents/delete hard-deleted the agent, skipping the Console’s archive step. It now archives the agent and its versions and keeps its memory and knowledge.

Breaking

  • Creating an agent needs an External App owned by an org unit, holding agents:write and agents:read at that unit; otherwise 403 forbidden. The agent’s worker role is granted at that unit’s company root, no longer at the deployment root’s.
  • Update and delete need agents:write at the agent’s home. An agent the App may not read at its home is 404 not_found.
  • Bodies are strict: unknown fields, a status outside draft/active (create) or draft/active/deprecated (update), and a malformed model or prompt are 400 bad_request instead of being ignored. A missing update or delete id is 400, not 404.
  • DELETE /api/v2/agents/delete answers {ok, agentId, status: "archived"}; deleting an archived agent is 409 conflict. Permanent deletion is Console-only.

Migration

  • Agents an App created before 2026-10-01 stay homed at the deployment root; they are not re-homed.
  • Send agentId, name and description on create, and only the documented fields on update.
  • MCP write tools now return structured { data, meta } and accept idempotencyKey.
Read the health of the knowledge you can read, over the API and MCP.

Summary

GET /api/v2/knowledge/health (scope knowledge:read) returns the health the Console’s Knowledge › Health page shows, for the knowledge the credential can read: stuck pending entries, failing and overdue sources, failing and quarantined source items, embedding staleness and open review items, plus the deployment’s latest re-embed run, integrity audit, knowledge cron runs and learning settings. Each section names its scope, readable or deployment. See Knowledge health.

New

  • GET /api/v2/knowledge/health, with an optional namespace that must be readable (else 403). The OpenAPI document gains a strict KnowledgeHealth schema.
  • MCP tool forge_get_knowledge_health in the knowledge group, read-only with a structured result.
  • No source configuration, cursor or case key is returned; source and item errors are redacted, an item whose case you may not read is restricted with no error, and the re-embed run’s error text is withheld (hasError).
Machine credentials can read the Trust Fabric role catalog and the role grants of API keys, External Apps and agents.

Summary

GET /api/v2/governance/listRoles returns the system roles of the Trust Fabric catalog, and GET /api/v2/governance/listGrants pages the role grants held by API keys, External Apps and agents that the caller may see. Both need the existing governance:read bundle (grants:read, policies:read, audit:read). The catalog is decided at the deployment root; each grant is decided at its own scope, and an agent’s grant also needs agents:read at the agent’s home. MCP adds forge_list_roles and forge_list_grants. See Roles and grants.

New

  • listRoles (403 naming grants:read when your grants do not reach the platform scope or the deployment root) and listGrants (cursor, limit 1–50, actorKind of api_key, external_app or agent), each with meta.partial.
  • Person grants are never returned, and no grant carries who gave it, a name or an email; actorKind=person is 400. Compatibility roles are never listed.
  • Giving or revoking roles stays person-only (Console): grants:manage and roles:manage can never be held by an API key, External App or agent.
Six new published scopes prepare project, workforce, tool, objective, workflow-draft and agent-management APIs.

Summary

The published scope catalog now includes projects:read, workforce:read, tools:read, objectives:read, workflows:write:draft and agents:manage. Each scope only narrows an existing role grant; it grants no authority by itself. The built-in Magellan and Code Red Intake apps receive the four read scopes and explicitly exclude the two mutating scopes.
An External App can remove its own link to a customer.

Summary

New POST /api/v2/external/customers/unlink and MCP forge_unlink_customer remove only the calling External App’s link to a customer, with body exactly {id}, and return {id, unlinked: true}. They never archive or change the shared customer, other apps’ links or the customer’s organization home. A customer that is missing or not linked to the app is 404. See Removing your app’s link.

New

  • POST /api/v2/external/customers/unlink (customers:manage, scope customers:write, External App credential only). Afterwards the app can no longer read, update, cost-query or dispatch for that customer until findOrCreate links it again.
  • With a management JWT, a same-key repeat of a completed unlink returns the recorded {id, unlinked: true} to the same app while it holds customers:manage (see External App customer writes).
  • forge_unlink_customer (destructive, optional idempotencyKey) in the customers MCP group; ForgePlatformClient.unlinkCustomer. The MCP server registers one more tool. GET /api/v2/actor lists the new operation, and it is in the OpenAPI document.
Read the procedure catalog at each procedure's home: families, versions, usage and retirement blockers, over the API and MCP.

Summary

GET /api/v2/procedures/list, /get and the new /listVersions return only the procedure versions the caller may read, with procedures:read held at each version’s home org unit. The list pages procedure families with an opaque family cursor; get returns an allowlisted ProcedureDetail with dispatch usage, hard-delete blockers and a family-level current-workflow reference flag. See Procedure catalog.

New

  • GET /api/v2/procedures/listVersions?procedureId= lists every visible version, highest first, with status and dispatch usage.
  • ProcedureDetail gains retirement.blockers (builtin, active, approved, non_provisional_tier, recorded_usage), familyReferencedByCurrentWorkflow (null when undecided) and immutable: true. The OpenAPI document gains strict Procedure, ProcedureDetail and ProcedureVersion schemas.
  • MCP tools forge_list_procedures, forge_get_procedure and forge_list_procedure_versions in the workflows group, read-only with structured results.

Breaking

  • The list cursor is an opaque family cursor; a numeric offset cursor is 400. The list returns one item per family and drops the snapshot build fields and operationContract.binding.
  • get no longer returns row ids, creator, synthesis request, lifecycle actors, sandbox, image digest, repository or draft state, connection bindings or usage.totalReferences.
  • Procedures are homed at the deployment root, so a credential whose grants are scoped only to org units below the root no longer sees them.

Migration

  • Restart a list walk without cursor, then follow meta.nextCursor while meta.hasMore is true.
  • Read familyReferencedByCurrentWorkflow instead of usage.totalReferences.
Knowledge add and delete report their outcome, and a same-key retry returns the original result.

Summary

POST /api/v2/knowledge/delete now answers alreadyDeleted, false only for the call that deleted the entry and wrote its audit event. A refused company add names the permission that would allow it. A same-key repeat of a completed add or delete returns the recorded response instead of 409 idempotency_result_unavailable, while the caller still holds knowledge:read and may still read (add) or delete (delete) the entry. forge_add_knowledge and forge_delete_knowledge return structured results and accept an idempotencyKey. See Add a knowledge entry, Delete a knowledge entry and Knowledge write replay.

Changed

  • Delete outcome. The delete’s 200 body gains alreadyDeleted ({ id, status: "deleted", alreadyDeleted }). The decision is made inside the delete’s transaction: of two racing deletes of one entry, exactly one answers false.
  • Company refusal. A 403 for an add to company by a caller without knowledge:manage carries error.requiredPermission: "knowledge:manage". A refusal for any other namespace, or for company to a caller that already holds knowledge:manage, names no permission, because none would allow it.
  • Replay. A same-key repeat of a completed add returns its stored 201, or 200 with deduplicated: true; of a completed delete, its stored 200. Both need the route’s permission and knowledge:read; a missing knowledge:read answers 403, and an added entry deleted since, an entry that left the caller’s writable namespaces, a delete response stored before this change (it has no alreadyDeleted), or a repeat of a refused request answers 409 idempotency_result_unavailable. Nothing is written twice.
  • De-duplication scope, documented. An add de-duplicates on an active entry with the same externalRef, namespace and principal. Every platform and MCP key shares one principal per namespace; an External App has its own.
  • MCP. forge_add_knowledge and forge_delete_knowledge return { data, meta } with strict output schemas, carry write annotations (delete is destructive and idempotent), accept idempotencyKey, and explain an unknown outcome and its same-key recovery.
Credential health resolves a connection only where the deployment's providers resolve it.

Summary

CredentialHealth.resolved, in GET /api/v2/capabilities/get, GET /api/v2/providers/get and the matching Forge MCP tools, is now the credential resolver’s own answer at the deployment scope, the scope a provider resolves at when no run names an organization. See Credential health.

Fixed

  • A connection whose only approved credential is homed at one organization reported resolved: true although a deployment-scope dispatch finds no credential for it. It now reports resolved: false; the credential still counts in approvedCount. The response shape is unchanged.
Trust Fabric policy authoring acts on each policy's newest revision only.

Summary

Console Trust Fabric policy authoring keeps one live revision per policy. Only a policy’s newest revision can be enabled, edited or deleted; an earlier revision can still be disabled. An edit keeps the policy’s enabled state, the policy table shows each policy once at its newest revision, and deleting a revision never strands the rest of its history. See Policies.

Fixed

  • An earlier revision of an edited policy could be re-enabled and was then enforced beside the newest one, while GET /api/v2/governance/listTrustPolicies reported only the newest. Enabling an earlier revision is now refused.
  • Editing an earlier revision created a second live revision with a duplicate revision number, and editing a disabled policy enabled it. Editing an earlier revision is now refused, and an edit keeps the enabled state.
  • Deleting a policy’s first revision hid the policy’s live revision from listTrustPolicies. A delete now acts on the newest revision only.

Removed

  • The unused reactive policy mutation update, which rewrote a revision’s content in place. Use opsInternal.editGovernancePolicy (a new revision) or toggleGovernancePolicy.

Changed

  • listTrustPolicies, listTrustPolicyRevisions and the matching Forge MCP tools state that trust policy writes are person-only. Responses are unchanged.
While Forge is stopped by an operator, machine writes, knowledge answers and inference calls are refused before any effect.

Summary

When a person engages the global kill switch (“stop everything”) in the Console, every /api/v2 write, POST /api/v2/knowledge/ask and POST /api/v2/knowledge/getChunks answer 403 forbidden, and /api/inference/v1/chat/completions and the inference file writes answer 403 platform_killed, each with the fixed message “Forge is stopped by an operator. A person resumes it in the Console.” Before, these requests ran while Forge was stopped. A refused request records no Idempotency-Key, so the same key sent after Forge resumes executes once. Reads keep working. The operator’s reason is never returned. See Errors and Idempotency.

Changed

  • Writes over the API and the Forge MCP write tools are refused while Forge is stopped, including credential rotation and External App deactivation: during a stop, a person revokes a credential in the Console.
  • The inference proxy’s chat refusal while stopped no longer includes the operator’s reason.
Workforce org-unit and position reads for machines.
Four workforce GET routes and four MCP tools now read org units and positions under workforce:read. Org-unit grants include descendants, outputs use safe allowlists and legacy IDs, and list continuation remains truthful through empty filtered pages. Raw worker/person directory reads remain separate. Component faults remain server failures rather than becoming missing rows or empty enrichment.