Execution-outcome semantics after an ALLOW decision

[arpanghoshal]

Summary

steps/toolCallResult gives a Guardian exit_status: success | failure | timeout | blocked,
which describes the call. It does not describe the effect. For a tool with a side effect —
a payment, a message, a deletion — the question a control layer has to answer is not "did the
call return?" but "did the thing happen?", and v0.1.0 has no field that carries the difference.

The consequence is concrete, and it is the failure mode most likely to bite a production
deployment that has otherwise done everything ACS asks.

The concrete failure

1. An agent calls create_refund(payment_id="txn_1", amount=2000).
2. The Guardian answers allow at steps/toolCallRequest.
3. The payment provider commits the refund and the response is lost — a read timeout, a
   dropped connection, a load-balancer 502.
4. The platform fires steps/toolCallResult with exit_status: "timeout".
5. Nothing in v0.1.0 distinguishes this from "the call did not happen". A reasonable Guardian
   treats a non-success status as a failure; a reasonable agent retries.
6. The Guardian sees a fresh steps/toolCallRequest with a fresh request_id. There is no
   field linking it to the first call's effect, so it answers allow.
7. The customer is refunded twice.

Every step is conformant. The gap is that timeout and failure are statuses of a call, and
the decision that matters is about an effect.

Where the gap sits in the current schemas

• hooks/tool-call-result.json — exit_status has four values, none of which asserts whether
  a side effect landed. request_id_ref correlates a result to its request, which is a
  different relation from identifying the effect both concern.
• hooks/tool-call-request.json — tool, operation, capability, arguments,
  raw_command, intent. Nothing names the effect the call intends, so two calls intending the
  same effect are indistinguishable from two calls intending different ones. intent is about
  why the call is being made, which is a different question from which effect it would produce.
• ask-details.json — an ask carries a question and an approver, and intent_extension can
  widen a capability for this_request or session. Nothing binds the returned decision to a
  canonical form of the arguments that were asked about, so an approval obtained for
  refund(2000) does not, by the schema, refuse refund(5000).
• specification.md §6 — five dispositions, ALLOW, DENY, MODIFY, ASK and DEFER,
  all about whether a call proceeds. DEFER is the nearest thing and it is the Guardian saying
  I cannot decide yet, with a resolution method and a timeout. There is no way to record that
  an effect's outcome is unresolved, and that further calls against it must be refused until
  a human resolves it: that is a fact about the world, not about the Guardian's confidence.

Proposed extension shape

Offered as a shape, not a patch — the exact spelling belongs to the working group.

1. An optional effect identifier on toolCallRequest.

"effect_id": {
  "type": "string",
  "description": "Stable identifier for the real-world effect this call intends. Two calls
                  that would produce the same effect carry the same value. Producers derive
                  it deterministically from the tool, operation and the arguments that
                  identify the target."
}

Optional, because plenty of tools are reads. Where present, it lets any Guardian recognise a
repeat without knowing anything about the tool's semantics.

2. A three-state effect outcome on toolCallResult, beside exit_status.

"effect_outcome": {
  "enum": ["committed", "not_executed", "unknown"],
  "description": "What happened to the side effect, as distinct from what happened to the
                  call. `not_executed` is an assertion that the tool did nothing and the
                  call may be safely retried; it MUST NOT be inferred from a transport
                  failure. Absent means `unknown`."
}

The asymmetry is the point: committed and not_executed are claims a tool can make about
itself, and unknown is the honest default for everything else — including timeout. A
schema that defaults to unknown in the absence of an explicit claim is fail-closed; one that
defaults to not_executed produces the duplicate above.

3. A canonical action digest on ask_details, echoed by the approval.

"action_digest": {
  "type": "string",
  "description": "Digest over a canonical serialisation of the exact call the approver was
                  shown — tool, operation, arguments, principal, environment. An approval
                  authorizes that digest and no other."
}

This closes the mutation path without ACS having to define an authority model: the approver's
answer is bound to what they were shown.

Why this is worth specifying rather than leaving to implementers

Every Guardian that fronts a consequential tool has to answer these questions, and each will
answer them differently and privately. Effect identity in particular is not something an
implementer can add on their own side without cooperation, because the agent is what retries
and the platform is what mints request_ids. If ACS does not name the concept, two
conformant Guardians in one system will disagree about whether a retry is a repeat.

Not the same as #119

#119 asks the
hooks documentation to state that exit_status is a four-value classification and not a numeric
process exit code, with normalization examples. That is worth doing and it is a different point.
This one is that no value of that field, however well documented, answers whether the side
effect landed: timeout is a statement about the call, and a committed-then-timed-out refund
and a refund that never ran produce the same one.

Prior art / reference implementation

CTRLRun implements all three concepts today — an effect
key derived from a policy template, a three-state outcome with AMBIGUOUS as a terminal state
only a human or a reconciliation hook can leave, and approvals bound to a hash covering the
principal, arguments, resource and environment. Its ACS adapter is written against the v0.1.0
schemas and documents this gap at
docs/ACS.md.

It is offered as one reference implementation, not as the shape the standard should take.
Idempotency keys in payments APIs (Stripe, Adyen), exactly-once semantics in message brokers,
and two-phase commit all solve the same problem with different vocabulary, and the working
group should draw on whichever fits ACS's model best. The concepts matter; the spelling does
not have to be ours.

Happy to help

I can open a PR against the schemas with a concrete diff, write the conformance cases, or just
leave this as a discussion. Whichever is most useful.

[noqt]

A released host-containment example may add one distinction here: the requested control, the observed effect, and durable evidence of that effect are separate facts.

In noqt/Lumi-Eggcracker at public main a73a67b, a successful containment receipt cannot be created until the owned cgroup is proven empty (source). If cgroup.kill is attempted but emptiness is not proven, the run becomes CONTAINMENT_FAILED; if containment and terminal state are established but the receipt cannot be persisted, it becomes CONTAINED_RECEIPT_FAILED (source).

That implementation suggests wording along these lines:

• an effect must not be called committed from the tool-call return alone;
• not_executed needs affirmative evidence that the target-side effect did not occur;
• otherwise the external result stays unknown, including when the effect may be complete but its durable evidence is unavailable.

One limitation is important: Eggcracker's event_id is generated after containment, so it is not an idempotency/effect key and does not solve retry correlation. This is implementation prior art, not a claim of ACS compatibility.

Would a small conformance case that separates "effect not confirmed" from "effect confirmed but durable evidence unavailable" be useful for #128, or is that distinction intentionally deployment-specific?

[gokuljayaprakash8]

A data point from a small public lab that tested these states against a real service (GitHub issue comments via the official GitHub MCP server). I'm an independent researcher working from a phone, and my work is developed with substantial LLM assistance. I have not run ACS itself.

Repo: github.com/gokuljayaprakash8/kalpang-effect-boundary-lab

An authorization was bound by SHA-256 to the exact add_issue_comment request (similar to the action_digest idea in point 3). Three cases, each checked by an independent GitHub REST read:

1. Normal run: the effect matched the authorized comment.
2. Simulated compromised transport (my harness swapped the body after authorization): the call returned only a comment id and URL, and the REST read showed a different body.
3. Observer made unavailable on purpose: the call succeeded but nothing could confirm the effect, so the result was unknown, not a pass.

Case 2 raises a question for #128: if effect_id is derived from the target (here, the issue), a different body could still look like "committed". Is content or value divergence meant to be in scope for effect_outcome, or left to deployments? Also, whose claim is effect_outcome: the tool's own, or an independent observer's?

If useful, I can contribute these three cases as conformance vectors. Limits: one platform, unsigned authorization, shared credential domain, simulated substitution.