Add write tools and human approval: the gate the model cannot cross

1
CREATE TABLE agent.approvals (
2
    id              TEXT PRIMARY KEY,           -- approval id (also the opaque token)
3
    conversation_id TEXT NOT NULL REFERENCES agent.conversations(id),
4
    tenant_id       TEXT NOT NULL,
5
    user_id         TEXT NOT NULL,              -- requester
6
    tool            TEXT NOT NULL,
7
    args_json       TEXT NOT NULL,              -- normalized arguments as shown to the approver
8
    args_hash       TEXT NOT NULL,              -- sha256 of canonical args
9
    status          TEXT NOT NULL CHECK (status IN
10
                        ('PENDING','APPROVED','EXECUTED','DENIED','EXPIRED')),
11
    created_at      TIMESTAMPTZ NOT NULL DEFAULT now(),
12
    expires_at      TIMESTAMPTZ NOT NULL,
13
    decided_by      TEXT,
14
    decided_at      TIMESTAMPTZ
15
);
16

17
CREATE INDEX approvals_pending_idx ON agent.approvals (conversation_id) WHERE status = 'PENDING';

1
CREATE TABLE agent.audit_events (
2
    id             BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
3
    at             TIMESTAMPTZ NOT NULL DEFAULT now(),
4
    tenant_id      TEXT NOT NULL,
5
    actor          TEXT NOT NULL,              -- user sub or service account
6
    event_type     TEXT NOT NULL,              -- APPROVAL_REQUESTED | APPROVED | DENIED | TOOL_EXECUTED | ...
7
    tool           TEXT,
8
    conversation_id TEXT,
9
    approval_id    TEXT,
10
    args_hash      TEXT,
11
    detail         JSONB NOT NULL DEFAULT '{}'::jsonb
12
);
13
-- no UPDATE/DELETE grants: append-only by permission, not convention

1
package in.o612.eng.opsagent.agent.approval;
2

3
import in.o612.eng.opsagent.agent.audit.AuditService;
4
import in.o612.eng.opsagent.agent.security.CallerContext;
5
import in.o612.eng.opsagent.agent.tools.McpToolExecutor;
6
import in.o612.eng.opsagent.agent.tools.ToolPolicyRegistry;
7
import org.springframework.stereotype.Service;
8

9
import java.time.Duration;
10
import java.time.Instant;
11
import java.util.Map;
12
import java.util.UUID;
13

14
@Service
15
public class ApprovalService {
16

17
    public sealed interface Decision {
18
        record Pending(String approvalId, Instant expiresAt) implements Decision {}
19
        record Executed(String toolResult) implements Decision {}
20
        record Refused(String reason) implements Decision {}
21
    }
22

23
    private final ApprovalStore store;
24
    private final McpToolExecutor executor;
25
    private final ToolPolicyRegistry policies;
26
    private final AuditService audit;
27

28
    private static final Duration TTL = Duration.ofMinutes(5);
29

30
    /** Called from the agent loop when a HIGH/MEDIUM-risk tool is proposed. */
31
    public Decision requestApproval(String conversationId, CallerContext requester,
32
                                    String tool, Map<String, Object> args) {
33
        var canonical = ArgsCanonicalizer.canonical(args);
34
        var approval = store.insertPending(
35
                UUID.randomUUID().toString(), conversationId,
36
                requester.tenantId(), requester.userId(),
37
                tool, canonical, ArgsCanonicalizer.sha256(canonical),
38
                Instant.now().plus(TTL));
39
        audit.record("APPROVAL_REQUESTED", requester.tenantId(), requester.userId(),
40
                tool, conversationId, approval.id(), approval.argsHash(), Map.of());
41
        return new Decision.Pending(approval.id(), approval.expiresAt());
42
    }
43

44
    /** Called by POST /approvals/{id}. Enforces every binding in one transaction-shaped sequence. */
45
    public Decision decide(String approvalId, CallerContext approver, boolean approve) {
46
        var row = store.find(approvalId).orElse(null);
47
        if (row == null)                        return new Decision.Refused("unknown approval");
48
        if (row.status() != Approval.Status.PENDING)
49
                                                return new Decision.Refused("approval already consumed");
50
        if (row.expiresAt().isBefore(Instant.now())) {
51
            store.transition(approvalId, Approval.Status.EXPIRED, approver.userId());
52
            return new Decision.Refused("approval expired");
53
        }
54
        if (!row.tenantId().equals(approver.tenantId()))
55
                                                return new Decision.Refused("cross-tenant approval");
56
        if (!row.userId().equals(approver.userId()))
57
                                                return new Decision.Refused("approval bound to requester");
58
        if (!approver.scopes().contains(requiredScopeFor(row.tool())))
59
                                                return new Decision.Refused("approver lacks scope");
60

61
        if (!approve) {
62
            store.transition(approvalId, Approval.Status.DENIED, approver.userId());
63
            audit.record("DENIED", row.tenantId(), approver.userId(), row.tool(),
64
                    row.conversationId(), approvalId, row.argsHash(), Map.of());
65
            return new Decision.Refused("denied by operator");
66
        }
67

68
        // single-use transition: exactly one racer wins
69
        if (!store.transition(approvalId, Approval.Status.APPROVED, approver.userId())) {
70
            return new Decision.Refused("approval already consumed");
71
        }
72
        audit.record("APPROVED", row.tenantId(), approver.userId(), row.tool(),
73
                row.conversationId(), approvalId, row.argsHash(), Map.of());
74

75
        // TOCTOU: hash what we are ABOUT to send; compare to what was approved
76
        Map<String, Object> execArgs = ArgsCanonicalizer.parse(row.argsJson());
77
        String execHash = ArgsCanonicalizer.sha256(ArgsCanonicalizer.canonical(execArgs));
78
        if (!execHash.equals(row.argsHash())) {
79
            return new Decision.Refused("arguments changed after approval");
80
        }
81

82
        var policy = policies.find(row.tool()).orElseThrow();
83
        var idemKey = "ap-" + row.argsHash().substring(0, 32);
84
        execArgs.put("idempotency_key", idemKey);
85
        execArgs.put("tenant", row.tenantId());          // still ours, never the model's
86
        String result = executor.execute(row.tool(), execArgs, row.tenantId(),
87
                policy.perCallTimeout());
88

89
        store.transition(approvalId, Approval.Status.EXECUTED, approver.userId());
90
        audit.record("TOOL_EXECUTED", row.tenantId(), approver.userId(), row.tool(),
91
                row.conversationId(), approvalId, execHash,
92
                Map.of("idempotency_key", idemKey));
93
        return new Decision.Executed(result);
94
    }
95

96
    private String requiredScopeFor(String tool) {
97
        return policies.find(tool).map(p -> p.requiredScope()).orElse("__none__");
98
    }
99
}

1
package `in`.o612.eng.opsagent.mcp.tools
2

3
import `in`.o612.eng.opsagent.mcp.errors.ToolError
4
import `in`.o612.eng.opsagent.mcp.security.TenantPolicy
5
import `in`.o612.eng.opsagent.mcp.simulator.SimulatorClient
6
import org.springframework.ai.mcp.annotation.McpTool
7
import org.springframework.ai.mcp.annotation.McpTool.McpAnnotations
8
import org.springframework.ai.mcp.annotation.McpToolParam
9
import org.springframework.security.core.context.SecurityContextHolder
10
import org.springframework.security.oauth2.server.resource.authentication.JwtAuthenticationToken
11
import org.springframework.stereotype.Component
12

13
@Component
14
class WriteTools(
15
    private val simulator: SimulatorClient,
16
    private val tenantPolicy: TenantPolicy,
17
) {
18

19
    @McpTool(
20
        name = "create_incident",
21
        description = "Create an incident ticket. Mutating: requires ops:incident:write.",
22
        annotations = McpAnnotations(readOnlyHint = false, destructiveHint = false,
23
                                     idempotentHint = true, openWorldHint = false),
24
        generateOutputSchema = true,
25
    )
26
    fun createIncident(
27
        @McpToolParam(required = true, description = "Tenant scope") tenant: String,
28
        @McpToolParam(required = true, description = "Short incident title") title: String,
29
        @McpToolParam(required = true, description = "SEV1..SEV4") severity: String,
30
        @McpToolParam(required = true, description = "Owning service id") serviceId: String,
31
        @McpToolParam(description = "What is known so far") description: String? = null,
32
        @McpToolParam(required = true, description = "Caller-supplied idempotency key")
33
        idempotencyKey: String,
34
    ): Any = guardWrites {
35
        tenantPolicy.enforce(jwt(), tenant, "ops:incident:write")
36
        require(idempotencyKey.matches(Regex("[A-Za-z0-9_-]{8,64}"))) { "invalid idempotency key" }
37
        simulator.createIncident(tenant, idempotencyKey, title, severity, serviceId, description)
38
    }
39

40
    @McpTool(
41
        name = "append_incident_note",
42
        description = "Append a note to an existing incident. Mutating: requires ops:note:write.",
43
        annotations = McpAnnotations(readOnlyHint = false, destructiveHint = false,
44
                                     idempotentHint = false, openWorldHint = false),
45
    )
46
    fun appendIncidentNote(
47
        @McpToolParam(required = true) tenant: String,
48
        @McpToolParam(required = true) incidentId: String,
49
        @McpToolParam(required = true) note: String,
50
        @McpToolParam(required = true) idempotencyKey: String,
51
    ): Any = guardWrites {
52
        tenantPolicy.enforce(jwt(), tenant, "ops:note:write")
53
        require(note.length <= 4000) { "note too long" }
54
        simulator.appendNote(tenant, incidentId, note, idempotencyKey)
55
    }
56

57
    private fun jwt() =
58
        (SecurityContextHolder.getContext().authentication as JwtAuthenticationToken).token
59

60
    private fun guardWrites(block: () -> Any): Any = try {
61
        block()
62
    } catch (e: IllegalArgumentException) {
63
        ToolError.of("FORBIDDEN_OR_INVALID", e.message ?: "rejected")
64
    } catch (e: org.springframework.web.client.RestClientException) {
65
        ToolError.of("UPSTREAM_UNAVAILABLE", "operations backend unreachable")
66
    }
67
}

1
POST http://localhost:8080/api/v1/approvals/apr-01H...
2
Authorization: Bearer <priya token>
3
Content-Type: application/json
4

5
{"approve": true}