Human In the Loop

Not every step in an automation can be handled by AI. When a workflow hits a point that requires human judgment — an approval, a triage call, a compliance check — CableKnit pauses the run and routes a structured Decision to the right person.

The human reviews the context, picks an option, and the workflow resumes automatically. No code required on the human side. No custom UI to build.

Why human-in-the-loop matters

AI is good at extraction, classification, and drafting. But there are situations where you need a human:

• Approvals — spending above a threshold, contract terms, vendor onboarding
• Triage — routing an incoming request to the right team or category
• Escalation — the AI assessment flagged something unusual and a manager needs to weigh in
• Compliance — regulatory requirements mandate a human sign-off before proceeding
• Edge cases — the automation hit a condition it wasn’t designed to handle automatically

CableKnit makes this a first-class part of the workflow, not an afterthought.

How it works

1. The automation requests a decision

When your workflow reaches a state that needs human input, the entry action request_decision pauses the run and creates a Decision:

{
  "type": "request_decision",
  "title": "Approve vendor invoice: ",
  "description": "",
  "decision_options": [
    { "key": "approve", "label": "Approve" },
    { "key": "reject", "label": "Reject", "requires_input": true },
    { "key": "escalate", "label": "Escalate to finance director" }
  ],
  "assigned_role": "manager",
  "priority": "high",
  "expires_in": 24
}

The run stays paused until someone resolves it — or it times out.

2. The human gets notified

When a Decision is created, CableKnit notifies the assigned person through multiple channels:

• CableKnit Mac app — appears in the Decision Queue
• CableKnit iOS app — push notification with the decision summary
• CableKnit Android app — push notification with the decision summary
• Email — structured email with context and action links

The person doesn’t need to be at their desk. Critical decisions push to mobile immediately.

3. The human reviews and decides

The Decision Queue shows all pending decisions sorted by priority. critical decisions appear at the top, low priority items at the bottom.

Each decision displays:

• Title and description — what the automation is asking
• AI assessment — any context the automation gathered before pausing
• Attached artifacts — documents, reports, or drafts the automation produced
• Decision options — the specific choices available

The reviewer picks an option. If an option has requires_input: true, they must provide a written explanation (useful for rejections and escalations).

4. The workflow resumes

Once resolved, the decision outcome is stored in case_context.decision_outcome and the workflow transitions based on the selected option:

{
  "from_state": "pending_approval",
  "to_state": "approved",
  "condition": { "type": "decision_outcome", "matches": "approve" }
}

Different outcomes can route to different states — approve goes one way, reject goes another, escalate routes to a senior reviewer.

Escalation and timeouts

Automatic escalation on timeout

If nobody resolves a decision within the expires_in window, CableKnit triggers a timeout transition. Use this to escalate automatically:

{
  "from_state": "pending_approval",
  "to_state": "escalated_to_director",
  "condition": { "type": "timeout" }
}

The escalated state can create a new decision assigned to a more senior role, send urgent notifications, or take a default action.

Multi-level escalation

Chain escalation states to build multi-tier approval workflows:

1. First reviewer gets 24 hours → times out
2. Manager gets 12 hours → times out
3. Director gets 4 hours → times out
4. Auto-reject with notification to all parties

Each level is just another state with its own request_decision and timeout transition.

Priority levels

Set priority at the automation level or override per-decision:

Notification-only pattern

Sometimes you don’t need a decision — you just need to inform someone. Use a single “Acknowledge” option:

{
  "decision_options": [
    { "key": "acknowledged", "label": "Acknowledge" }
  ]
}

This still creates a Decision Queue entry with an audit trail, but the only action is to confirm receipt. Keeps everything auditable without requiring a real choice.

Alternatively, use the notify action to send a non-blocking notification that doesn’t pause the workflow:

{
  "type": "notify",
  "channels": ["email", "in_app"],
  "to_role": "manager",
  "title": "Weekly compliance report ready",
  "body": "The report has been generated and is available in the artifacts tab."
}

Where decisions are resolved

Users can resolve decisions from any of these:

All platforms show the same context: AI assessment, attached artifacts, and decision options. The experience is consistent regardless of where the human responds.

Best practices

• Be specific in decision titles — “Approve PO #4821 for $12,400” is better than “Approval needed”
• Include AI context in the description — give the reviewer what they need to decide without digging through raw data
• Use requires_input for rejections — forces an explanation that gets stored in the audit trail
• Set realistic timeouts — 24-48 hours for routine approvals, 4-8 hours for urgent items
• Attach artifacts — if the automation produced a report or draft, attach it so the reviewer sees the full picture
• Use the acknowledge pattern for FYI notifications that still need an audit trail
• Use notify for truly informational messages that shouldn’t block the workflow