Investigations, drafts & escalation

Beyond the inbox tools, the server exposes Clad's AI-agent workflow itself, so an external agent can run the same playbook a human runs in the Clad panel.

Check the connection first. get_helpdesk_connection reports the provider (Pylon/Zendesk), status, and operating mode. In Observe mode Clad never writes to the helpdesk — drafts can still be generated and reviewed, but approve_draft (and reply_to_issue) will return FORBIDDEN until an admin switches the connection to Assist.

Investigations. start_investigation kicks off an asynchronous dig into the root cause of a ticket: kind: "code" works through the connected GitHub repo, kind: "billing" works through Stripe for the customer's billing state. Runs take a few minutes — poll get_investigation until status is complete (or failed), then read output (markdown findings), summary, and answerFound. Per-workspace in-flight and daily caps protect spend; when you hit one the tool returns RATE_LIMITED.

Drafts. Clad auto-drafts a suggested reply when a customer message comes in and the knowledge base has a confident answer. get_latest_draft reads the newest attempt for an issue — its status tells you whether it's generating, pending (awaiting review), discarded_* (the gate declined), approved, or rejected — and its sources list the knowledge-base articles and resolved tickets the answer was grounded in, so you can verify it before acting. generate_draft produces one on demand through the same gated pipeline (optionally steered with instructions); a declined gate returns withheld: true with the reason, not an error. generate_draft_from_investigation turns a completed investigation's findings into a pending draft.

Review. approve_draft sends the draft to the customer; deny_draft rejects it with a reason (which feeds regeneration and quality analytics). Approving requires a human-authorized credential — an OAuth grant from a signed-in teammate — because the send is attributed to the approving person; headless API keys can generate and deny drafts but not approve them. v1 delivers approvals on helpdesk-mirrored issues (Pylon/Zendesk); other channels approve in the Clad app.

Escalation. When a ticket needs engineering, file_tracker_ticket files a Linear ticket from the issue and links it — the Clad issue moves to On hold and the tracker ticket gets a back-link comment with the customer context. get_linked_tickets reads the linked tickets' live state and comment threads, and comment_on_linked_ticket posts follow-up context for the engineers. Check get_linked_tickets before filing to avoid duplicates.

A typical loop for a helpdesk ticket: get_issue → get_latest_draft (is there already a reviewed answer?) → if not, start_investigation → poll → generate_draft_from_investigation → review the body and sources → approve_draft — and file_tracker_ticket when the root cause needs a code fix. Everything is scope-gated (investigations:read / investigations:run / drafts:read / drafts:write), so a key can be limited to exactly the steps you want automated.