DECISIONS

Ask a person before the agent acts

Some steps need a human to say yes: shipping a release, paying an invoice, sending a message to a customer. A plan stops at that point, asks the people who hold the right role, and carries on down the path their answer chose.

A decision is a step in a plan where the run stops, asks a person a question with fixed answers, and continues only once someone who holds the right role has answered.

This page is for plan authors who want a person in the loop, and for the administrators who choose who answers.

A plan never names a person. It names a role, such as release-approver, and your organization decides who holds it, so the same plan works in any organization and its author cannot appoint their own approver.

The answer is recorded against the name of the person who gave it, and the first valid answer is the one that counts.

ekka decide list    # the decisions waiting on you

How does a plan ask a person?

An operation of kind wait with a decision. Its one step is ekka.human.decide.v1, and its transitions cover every answer and the timeout.

{
  "plan": { "code": "myapp.release", "name": "Ask before a release ships" },
  "definition": {
    "schema_version": "ekka.plan.v2",
    "operations": [
      {
        "id": "approve-release",
        "display_name": "A person approves the release",
        "kind": "wait",
        "decision": {
          "decider": "release-approver",
          "decider_label": "Release approver",
          "question": "Release 2.4.0 passed every check. Ship it to production now?",
          "choices": ["ship", "hold"],
          "choice_labels": { "ship": "Ship it now", "hold": "Hold this release" },
          "reminders": "default"
        },
        "execution": { "preferred": { "mode": "async", "runtime": "node" } },
        "steps": [
          {
            "id": "ask",
            "action_ref": "ekka.human.decide.v1",
            "feature": "human.decision.request",
            "inputs": {}, "action_input": {},
            "step_input_contract": { "type": "object" },
            "step_output_contract": { "type": "object" },
            "identity": { "requires_user_context": false }
          }
        ],
        "transitions": {
          "output.payload.choice == 'ship'": "end",
          "output.payload.choice == 'hold'": "end",
          "output.status == 'timeout'": "fail"
        }
      }
    ]
  }
}

• choices: two to eight answers. The person picks exactly one of them.
• decider: the role, never a person.
• reminders: none, default or frequent.
• expires_in_ms: how long the question stays open. Without it, a year.

In a real plan, each answer leads to a different next operation: ship to the step that deploys, hold to the end.

Who may answer?

Whoever your organization gives the role to. They have to be a member first.

ekka decide grant [email protected] release-approver
ekka decide approvers

✓ [email protected] can now answer "release-approver" decisions.

ekka decide roles lists the roles your plans ask for and how many people hold each one. A role nobody holds is the usual reason a run sits paused.

What does the person see?

The run stops and says who it is waiting for:

ekka plan run "[email protected]"

⏸ Waiting on a person (run e984ee79-40e7-41c6-9124-635eb507a563).
  Somebody who holds "Release approver" has to answer before it continues.
  It runs out on 2027-10-12.

The person lists what waits on them, reads it in full, and answers:

ekka decide list
ekka decide show 2d0638cd
ekka decide answer 2d0638cd ship --note "Checked the release notes with the team"

✓ Recorded: ship. The plan carries on from here.

ekka decide show prints the question, the answers on offer, when it runs out, and what the plan's earlier steps found, each with its fingerprint, so the person knows what they are approving. The note is kept with the decision for whoever reads it later and is never written into the audit chain.

What if two people answer?

The first valid answer counts. A later one is refused and says what was chosen:

ekka decide answer: This was already decided: "ship". Your answer was not recorded.

An answer is never edited. A plan that needs a second look asks again, in a later operation.

Limits

• A decision offers between two and eight fixed answers.
• The question and its details are written into the plan. They do not change per run.
• A question with no expires_in_ms stays open for one year.

Asking a person is included in every edition: see Pricing. Every ekka decide command is in the CLI reference.