Tool Connectors and Runtime Policy

{
  "runId": "run-identity",
  "actionId": "action-identity",
  "tool": { "key": "dependency.update", "version": "1.2" },
  "proposedArguments": {},
  "actor": "model-proposal",
  "objectiveReference": "external-objective",
  "riskClass": "reversible-write",
  "idempotencyKey": "stable-key",
  "expectedSideEffects": ["workspace manifest change"],
  "approvalState": "not_required",
  "expiresAtUtc": "2026-06-24T02:00:00Z"
}

using System.ComponentModel.DataAnnotations;

/// <summary>Contains a validated tool action proposal.</summary>
public sealed record ToolActionEnvelope
{
    /// <summary>Gets the stable action identifier.</summary>
    [Display(Name = "Action")]
    public required string ActionId { get; init; }

    /// <summary>Gets the stable tool key.</summary>
    [Display(Name = "Tool Key")]
    public required string ToolKey { get; init; }

    /// <summary>Gets the action expiration instant.</summary>
    [Display(Name = "Expires At Utc")]
    public required DateTimeOffset ExpiresAtUtc { get; init; }
}

/// <summary>Contains a typed connector result.</summary>
public sealed record ToolExecutionResult
{
    /// <summary>Gets whether the effect completed.</summary>
    [Display(Name = "Completed")]
    public required bool Completed { get; init; }

    /// <summary>Gets the effect receipt used for deduplication.</summary>
    [Display(Name = "Effect Receipt")]
    public required string? EffectReceipt { get; init; }
}

/// <summary>Executes one registered tool action.</summary>
public interface IToolConnector
{
    /// <summary>Executes a validated and authorized action.</summary>
    /// <param name="action">The action envelope.</param>
    /// <param name="cancellationToken">Signals cancellation of tool I/O.</param>
    /// <returns>The typed execution result.</returns>
    Task<ToolExecutionResult> ExecuteAsync(
        ToolActionEnvelope action,
        CancellationToken cancellationToken);
}

/// <summary>Represents a typed runtime policy outcome.</summary>
public sealed record PolicyDecision
{
    /// <summary>Gets the outcome key.</summary>
    [Display(Name = "Outcome")]
    public required string Outcome { get; init; }

    /// <summary>Gets the policy version used for the decision.</summary>
    [Display(Name = "Policy Version")]
    public required string PolicyVersion { get; init; }
}

/// <summary>Evaluates proposed runtime actions.</summary>
public interface IPolicyEngine
{
    /// <summary>Evaluates an action against immutable policy.</summary>
    /// <param name="action">The proposed action.</param>
    /// <param name="cancellationToken">Signals cancellation of policy I/O.</param>
    /// <returns>The typed decision.</returns>
    Task<PolicyDecision> EvaluateAsync(
        ToolActionEnvelope action,
        CancellationToken cancellationToken);
}

/// <summary>Obtains authorized approval decisions.</summary>
public interface IApprovalGateway
{
    /// <summary>Requests approval for a policy-gated action.</summary>
    /// <param name="action">The action requiring approval.</param>
    /// <param name="cancellationToken">Signals cancellation while waiting.</param>
    /// <returns>The approved policy decision.</returns>
    Task<PolicyDecision> RequestApprovalAsync(
        ToolActionEnvelope action,
        CancellationToken cancellationToken);
}