Replace a run plan
/api/v1/runs/{run_id}/replanCreate a new governance plan from the run's admitted configuration, current policy, and an optional exact tool-selection override.
This is not a natural-language dynamic-agent planner: it does not add specialists, rewrite the objective, or extend a timeline. Omit configured_tools to retain the existing stable tool selectors, or provide the complete replacement selection.
Copy expected_policy_version and expected_replay_generation from the latest plan response's replan_fence. A 409 means the fence is stale; retrieve the plan and review it again instead of blindly retrying.
The run must be paused in a replannable governance state. The new plan remains paused for review and may itself require approval.
Required access
Credentials: delegated token, user session
Scope: runs:edit
Only the user identity persisted as the run's execution principal may replan it. An organization administrator cannot replan another user's run, and service principals cannot call this operation.
Authorization
DelegatedToken A token issued to an external application acting for a specific user, prefixed gsmc_dt_. Carries that user's identity for attribution and ownership, and stays capped at member role however privileged the user is.
In: header
Path Parameters
Header Parameters
Selects the active organization for a credential that belongs to more than one. Service-principal keys are bound to a single organization and ignore it.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
CAS fences, operator reason, and optional domain-tool replacement.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/api/v1/runs/0/replan" \ -H "Authorization: Bearer $GUEST_MACHINES_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "expected_policy_version": 3, "expected_replay_generation": 2, "reason": "Replace the denied plan with the reviewed tool set.", "configured_tools": [ { "origin": "builtin", "source_id": "fetch_url" } ] }'{ "enforcement_state": { "source": "string", "strict_action_index": 0, "current_strict_action": { "index": 0, "kind": "string", "action": { "kind": "domain_tool", "domain_tool": { "origin": "builtin", "source_id": "string", "canonical_name": "string", "display_name": "string", "enabled": true, "owned_by_caller": true }, "title": "string", "summary": "string" }, "allowed_inputs": [ "string" ], "success_signal": "string" }, "remaining_strict_actions": [ { "index": 0, "kind": "string", "action": { "kind": "domain_tool", "domain_tool": { "origin": "builtin", "source_id": "string", "canonical_name": "string", "display_name": "string", "enabled": true, "owned_by_caller": true }, "title": "string", "summary": "string" }, "allowed_inputs": [ "string" ], "success_signal": "string" } ], "completed_strict_actions": 0, "adaptive_step_index": 0, "active_adaptive_step": { "index": 0, "title": "string", "intent": "string", "expected_activities": [ { "kind": "domain_tool", "domain_tool": { "origin": "builtin", "source_id": "string", "canonical_name": "string", "display_name": "string", "enabled": true, "owned_by_caller": true }, "title": "string", "summary": "string" } ], "success_signal": "string" }, "remaining_adaptive_steps": [ { "index": 0, "title": "string", "intent": "string", "expected_activities": [ { "kind": "domain_tool", "domain_tool": { "origin": "builtin", "source_id": "string", "canonical_name": "string", "display_name": "string", "enabled": true, "owned_by_caller": true }, "title": "string", "summary": "string" } ], "success_signal": "string" } ], "completed_adaptive_steps": 0, "last_progress_at": "string", "is_stalled": false, "latest_warning_type": "string" }, "plan": { "id": 0, "run_id": 1, "version": 1, "planning_mode": "adaptive", "status": "active", "goal": "string", "done_checks": [ "string" ], "risk_summary": { "risk_mode": "high", "allowed_capabilities": [ "artifact_write" ], "execution_environment": "guest_vm", "privileged_capabilities": [ "artifact_write" ], "requires_approval": true }, "expected_activities": [ { "kind": "domain_tool", "domain_tool": { "origin": "builtin", "source_id": "string", "canonical_name": "string", "display_name": "string", "enabled": true, "owned_by_caller": true }, "title": "string", "summary": "string" } ], "actions": [ { "index": 0, "kind": "string", "action": { "kind": "domain_tool", "domain_tool": { "origin": "builtin", "source_id": "string", "canonical_name": "string", "display_name": "string", "enabled": true, "owned_by_caller": true }, "title": "string", "summary": "string" }, "allowed_inputs": [ "string" ], "success_signal": "string" } ], "steps": [ { "index": 0, "title": "string", "intent": "string", "expected_activities": [ { "kind": "domain_tool", "domain_tool": { "origin": "builtin", "source_id": "string", "canonical_name": "string", "display_name": "string", "enabled": true, "owned_by_caller": true }, "title": "string", "summary": "string" } ], "success_signal": "string" } ], "approved_at": "2019-08-24T14:15:22Z", "created_at": "2019-08-24T14:15:22Z" }, "replan_fence": { "expected_policy_version": 1, "expected_replay_generation": 1 }}{ "detail": "string", "error_code": "string", "request_id": "string"}{ "detail": "string", "error_code": "string", "request_id": "string"}{ "detail": "string", "error_code": "string", "request_id": "string"}{ "detail": "string", "error_code": "string", "request_id": "string"}{ "detail": "string", "error_code": "string", "request_id": "string"}{ "detail": "string", "error_code": "string", "request_id": "string"}{ "detail": "string", "error_code": "string", "request_id": "string"}{ "detail": "string", "error_code": "string", "request_id": "string"}Deny a run plan POST
Deny the active governance plan and leave the run durably paused for a replacement plan.
Stream run events GET
Server-Sent Events stream for real-time run execution events. Connection stays open until the run reaches a terminal state (completed, failed, cancelled) or the client disconnects. Supports reconnection via the Last-Event-ID header.