Cases, tasks, and records

A case is one real matter. It can be pinned to an immutable playbook version or started ad hoc with a title. A playbook-backed case stores the playbook ID and version ID; it does not track step progress. Every case receives an internal UUID id and an immutable, pronounceable case code (e.g. PANDA-317). Case detail and access reads accept either identifier. When another operation asks for a case ID, use the UUID.

Input and playbook selection

Editors can attach or replace a readable, non-archived playbook version on an open case. Set versionId to null through the API or MCP to remove the playbook, or omit it to preserve the current selection.

Attaching, replacing, or removing a playbook creates a system activity identifying the previous and selected versions as applicable. Existing tasks, records, and reports are preserved; tasks keep their original step references.

Every title, input, or playbook update validates the resulting input against the selected version's input schema, when a playbook is selected. Supplied input replaces the complete object; omission reuses the current input. Playbook selection and optional input replacement commit together; a validation failure saves neither change. Removing the playbook preserves input without applying the old schema.

Case lifecycle

A case has a status of open, completed, or cancelled. Moving a case to completed requires every task to be closed; moving to cancelled sets remaining open tasks to cancelled as part of the case transition. Reopening a case sets its status back to open but does not reopen its tasks.

Archiving is separate from closing. Editors and owners can archive through Web, CLI, API, or MCP. Archived cases disappear from active views, counts, and handoff graphs and cannot be opened, but their work is retained. List with archived=true (case list --archived) to obtain the UUID and latest lock version, then restore without changing status, assignment, or sharing. Only an owner may permanently delete an archived case, with the latest expectedLockVersion; this removes its tasks, records, sources, and handoff links. Other cases and external provider content remain.

A case may finish with no tasks and no records. Use that lightweight form when only the fact of the case needs to be retained.

Public cases publish tasks and records

Public cases publish the current title, input, tasks, records, and readable handoffs, including later additions. Public account references for authors and assignees remain visible; private grants, linked sources, review reports and summaries, and private configuration are omitted. Public visibility grants reading only. Explicit viewers can also read private cases and their linked sources; writes require editing.

Case and task mutations require the latest expectedLockVersion (the read response contains lockVersion). On conflict, read current state and reconsider the change. Case editors may assign, retitle, close, reopen, change all sharing, archive, and restore. Assignment grants no access; the selected assignee must already be able to edit. Clearing sharing does not change assignment. startedBy, creators, and completed approvals remain history.

Playbooks and cases have an owning user or workspace account (ownerId), which is also the billing home. A personal owner has full rights; current owners and admins exercise ownership rights for a workspace. Other members need explicit user or team grants, or public visibility for published reads. Workspace membership alone grants no resource access. Removing a workspace member clears their direct grants on items owned by that workspace, including archived and completed items. If removal would leave any affected item without an explicit editor, add another user or team editor first, including on completed and archived items. Personal and other-workspace shares remain unchanged. Team and management authority follow current membership. Required SSO applies to members; non-member direct shares use normal Epismo authentication. Cross-workspace team sharing verifies the participation workspace's SSO. Lists use explicit access and supported public visibility; ownership alone does not include an item.

Tasks are created on demand

A task is explicit work within a case. Its kind is work or approval; it may be assigned to a user, linked to a source step, and, for approval work, point to the exact subject record. An approval task is a human or agent judgment of that record. It is distinct from case evaluation, which queues an AI assessment across the case's shared evidence.

Starting a case does not create one task per step. Create a task only when responsibility, handoff, approval, or a separately tracked piece of work should be visible. Multiple tasks can be open and closing one does not advance the case automatically.

A work task has status open, completed, or cancelled. An approval task has status open, approved, rejected, or cancelled. Status carries the result; supporting details and reasons belong in records.

Task updates also use lockVersion. Any case editor may update an open task, including its assignee. A closed task can be reopened only while its parent case is open.

Directed handoffs connect cases

Cases can be linked into a directed acyclic graph (DAG) using handoffs (fromCaseId -> toCaseId). Handoffs model multi-stage or cross-team continuations while preserving individual case ACLs and lifecycles. Creating or removing a handoff requires read access on the source and work access on the destination: a public case can be continued into a case the caller can edit, but a reader cannot attach work into a public case.

• Cycle prevention: handoff creation enforces cycle-free graphs using transactional reachability checks. Self-links and cyclic paths are rejected.
• Candidate discovery: Query eligible upstream or downstream cases to discover valid connection targets without trial-and-error.
• Handoff graph: View the connected DAG around a root case across configurable scopes (self, ancestors, descendants, neighbors, connected). Traversal continues through every readable case, including public cases, and stops at cases the caller cannot read. A public reader can therefore see other published branches of the same connected graph.

Records are the handoff surface

Records are shared context entries on a case timeline and may also belong to a task or source step. kind is closed: clients write note (commentary, a decision, or a handoff), output (a durable deliverable), or agreement (a shared decision or commitment). The server writes activity (a coordination event). Records also include optional human-readable content, structured data, origin (user, agent, or system), creator, client identity, and creation time. Human- and agent-authored records can be updated or redacted by their creator; task and provenance fields stay fixed. A delete leaves a tombstone (deleted_at) so references keep working.

Records use note, output, server-authored activity, or agreement. New records and kind changes accept note, output, or agreement. Human and agent assessments can be saved as notes; AI Review saves separate reports.

Good records include outcomes, evidence, decisions, file or object references, handoff summaries, and meaningful errors. Do not automatically store chain-of-thought, every tool call, raw shell output, credentials, retry history, heartbeat, or the runtime graph.

Case evaluation

Understand where work stands, what needs attention, and what to do next. AI review brings evidence and proposed actions into one report. Record the outcome and reevaluate to carry the judgment forward.

Any case editor can request an AI review assessment with POST /v1/cases/{caseId}/report (epismo report case generate or epismo_report_case_generate). That call queues the assessment and returns immediately with job metadata. Review uses built-in evaluation instructions; custom home guidance and per-request prompts are not supported. Web search during evaluation may be enabled if allowed by workspace policy.

Once processed, the latest synthesized report and actionable proposals can be read with GET /v1/cases/{caseId}/report (epismo report case get or epismo_report_case_get). Case editors can act on proposed actions using POST /v1/cases/{caseId}/report/actions (epismo report case act or epismo_report_case_act), confirming actions such as creating follow-up tasks or dismissing proposals. Review the full saved proposal, then send reportId, proposalId, and action (create or dismiss), with optional dismissal feedback. Creation uses the saved contents unchanged to create a task, a case with a directed handoff, a suggestion, or a playbook with its first version. Do not send title, content, definition overrides, or idempotencyKey; retries use the proposal identity. Decisions are retained per proposal, so repeating a handled proposal returns the current saved report without creating more work.

New cases and playbooks use the acting caller’s active billing home with restricted creator access; source sharing and external sources are not copied. Starting a case adds a directed handoff from the reviewed case and does not close it. Playbook creation is proposed sparingly, for evidenced recurring patterns with likely future reuse; handled Playbook-creation recommendations are not proposed again for that case. A stale report shows an advisory reevaluation notice and does not block actions; live permissions and domain validation still apply.

The creator of an ordinary client-authored record can update its kind, content, or data, or redact it. Anyone covered by the case ACL can still append a new record. Records are listed within a case, with stable cursor pagination and optional task, author, kind, origin, ACL, and sort-order filters. Passing a handoff scope (such as ancestors or connected) expands the query across connected handoffs while evaluating caller access for each case independently.

External sources

Link a Slack thread, Discord message/thread, or native Google Docs, Sheets, or Slides file using your connected account in the active space. Slack and Discord require a workspace; Google Drive supports personal and workspace spaces. Connect Google Drive and select the file with Google Picker in Web first; a URL alone does not grant file access. Google Drive sources use provider key gdrive. Link and unlink cost 2 credits each, with the initial capture included in linking. Each completed manual or automatic refresh costs 1 credit to that case’s billing account. Closed cases refresh only on explicit requests. Queuing, failures, pagination, and retries are free; requests coalesced into one capture incur one refresh charge for that case. case get includes sources for work collaborators only. Reads use saved captures; check status and timestamps before relying on them. When content is omitted, retrieve the latest complete source with its source ID. Historical content is not retained. Sources are separate from records and are never included in public-only responses. See Slack, Discord, and Google Drive for sharing, automatic updates, and capture removal.

Transfer case ownership with epismo_case_owner_transfer, case owner transfer <case-id> --owner-id <account-id> --lock-version <n>, or PATCH /v1/cases/{caseId}/owner (ownerId, expectedLockVersion, idempotencyKey). Current ownership is required. A personal case may move into the connected workspace; a public case also requires destination workspace management rights. A workspace case may move to its creator or a workspace owner. User-to-user and workspace-to-workspace moves are rejected. The transfer preserves assignment and sharing, changes the billing home, and clears derived case evaluation reports. Reassignment alone does none of these ownership changes.