Alignement et effets

Vérifiez une action matérielle contre la tâche active avant l'exécution. Suivre le retour verdict et next_action, puis signaler les effets réels lorsque la déclaration des effets est activée.

Vérifiez une action#

Utilisation POST /v1/task-guard/tasks/{taskId}/checks.

Nécessaire task_guard:checks:write.

curl -X POST "https://api.maetra.io/v1/task-guard/tasks/tgt_01JY8S/checks" \
  -H "Authorization: Bearer $MAETRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "Edit the refund approval API route",
    "action_type": "edit",
    "target": "apps/api/src/routes/refunds.ts",
    "effect": "MODIFY",
    "effects": ["Add validation and approval checkpoint handling"],
    "rationale": "The route is explicitly included in the active task.",
    "current_step": "Implement API route",
    "contract_version": 1,
    "external_action_id": "action-01JY8V",
    "idempotency_key": "alignment-01JY8V",
    "provenance": "HOST_VERIFIED",
    "reversible": true
  }'

Au minimum, fournir actionC'est vrai. Le chemin fournit task_idC'est vrai. Vous pouvez plutôt appeler le paramètre d'outil générique avec session_ref ou task_id.

Verdicts et comportement requis#

Verdict	`next_action`	Comportement de l'hôte
`ALIGNED`	`PROCEED`	L'action sert directement la tâche active.
`SUPPORTING`	`PROCEED_AND_RECORD_EXPANSION`	Procéder à la dépendance limitée et conserver l'expansion enregistrée.
`NEEDS_EXPLANATION`	`REQUEST_AGENT_EXPLANATION`	Appelez le point d'arrêt de l'explication avec une preuve limitée avant de procéder.
`USER_CONFIRMATION_REQUIRED`	`ASK_SESSION_USER`	Demandez à l'utilisateur en ligne et soumettez la réponse de confiance.
`CONTEXT_REFRESH_REQUIRED`	`REFRESH_TASK_CONTEXT`	Renseignez-vous sur le contexte de tâche actuel et revérifiez-le.
`REFOCUS`	`REPLAN_TO_CURRENT_TASK`	Ne pas exécuter l'action proposée; replanifier vers l'objectif actif.
`STOPPED`	`DO_NOT_EXECUTE`	Ne pas exécuter l'action.
`OBSERVED_DRIFT`	`PROCEED`	Observez le mode seulement : la dérive est enregistrée mais l'exécution n'est pas bloquée.

Un résultat aligné ou de soutien peut inclure une courte durée de vie alignment_token, expires_atet external_action_idC'est vrai. Un résultat de confirmation de l'utilisateur comprend : proposal avec la question, l'ID de la proposition, l'expiration et le nonce requis par le paramètre de confirmation.

Expliquez une relation ambiguë#

Quand le verdict est NEEDS_EXPLANATION, utiliser:

POST /v1/task-guard/checks/{checkId}/explanation

Nécessaire task_guard:checks:write.

{
  "relationship": "This compatibility repair is required for the approval route tests to compile.",
  "evidence": [
    "The changed type is imported by the in-scope route.",
    "The failing test references the same request contract."
  ]
}

Task Guard réévalue la vérification et retourne la même forme de résultat qu'une vérification d'alignement. Suivez le nouveau verdict.

Demander un changement de portée explicite#

Utilisation POST /v1/task-guard/tasks/{taskId}/changes évaluer un objectif proposé ou un changement de portée.

{
  "objective": "Also deploy the change to production.",
  "rationale": "Deployment was not included in the active task."
}

Cette route évalue la demande en tant que OBJECTIVE_CHANGEC'est vrai. Elle revient normalement. USER_CONFIRMATION_REQUIRED avec une proposition pour l'utilisateur de la session.

Soumettre la confirmation de l'utilisateur#

Utilisation:

POST /v1/task-guard/changes/{proposalId}/confirmation

Nécessaire task_guard:confirmations:write et une clé API marquée comme un titre de confirmation Task Guard de confiance.

{
  "accepted": true,
  "direct_user_event_id": "user-event-01JY91",
  "host_signature_id": "host-signature-01JY91",
  "nonce": "nonce-returned-with-the-proposal",
  "host_user_ref": "user_42",
  "response": "Yes, include the production deployment."
}

Une confirmation acceptée crée une nouvelle version du contrat et renvoie REFRESH_TASK_CONTEXTC'est vrai. Un rejet revient REPLAN_TO_CURRENT_TASK.

Important Cela confirme si le travail appartient à la tâche Task Guard. Il ne remplace pas un point de contrôle Govern pour un déploiement, un achat, un transfert, un message ou toute autre mesure consécutive.

Vérifier un jeton d'alignement imposé#

Un hôte forcé peut lier l'exécution à l'action exacte vérifiée par Task Guard :

POST /v1/task-guard/alignment/verify

Nécessaire task_guard:checks:write.

{
  "task_id": "tgt_01JY8S",
  "external_action_id": "action-01JY8V",
  "alignment_token": "eyJ…",
  "action": "Edit the refund approval API route",
  "effect": "MODIFY",
  "tool_name": "apply_patch",
  "resource": {
    "type": "file",
    "id": "apps/api/src/routes/refunds.ts"
  }
}

Le jeton n'est accepté que lorsque la tâche est active, la révision du contrat est toujours en cours et la signature de l'action correspond. La réponse retourne allowed: true, la tâche et vérifier les ID, l'ID de révision du contrat, l'ID de l'espace de travail et l'expiration.

Signaler les effets effectifs#

Après une action contrôlée, utilisez :

POST /v1/task-guard/checks/{checkId}/effects

Nécessaire task_guard:effects:write.

{
  "actual_effect": "MODIFY",
  "actual_effects": [
    "Updated the refund route validation",
    "Added approval checkpoint handling"
  ],
  "affected_resources": [
    { "type": "file", "id": "apps/api/src/routes/refunds.ts" }
  ],
  "summary": "The action changed only the checked route.",
  "validation_outcome": "Integration tests passed."
}

Si l'effet réel diffère sensiblement de l'action cochée, Task Guard retourne effect_aligned: false, révoque les subventions d'alignement correspondantes, et demande à l'hôte de demander à l'utilisateur de la session avant d'élargir davantage.