Cases and handoffs

Start and inspect a case

For workspace creation, including a saved default workspace, choose exactly one of --private, --team-ids "$TEAM_ID" (comma-separated IDs or a JSON array), or --access with complete settings. The same choices are private, teamIds, and access in --request JSON; do not combine them. Personal creation may omit sharing. Team selection grants editor access without adding redundant direct creator access.

epismo case start --version-id "$VERSION_ID" --input '{"customer":"Acme"}' --private
epismo case start --title "Review contract exception" --private
epismo case get <case-id-or-code>
epismo case list --status open
epismo case list --assigned-to <user-id>
epismo case list --sharing-scope anyone

Use a version-backed case when the guidance matters for reproducibility; use an ad hoc case when the matter is useful to share but no playbook exists. Neither form creates tasks automatically.

Case detail and access-get accept a UUID or immutable case code such as PANDA-317. Other operations use the UUID. Case get includes the latest ten records. Continue with its records_next_cursor and records_scope (self) in the CLI, or recordsNextCursor and recordsScope on API/MCP.

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.

Public case reads cost 0 credits without login on Web, CLI, API, and MCP. Work-detail reads on API / CLI / MCP bundle supporting reads into one 1-credit case get; ordinary Web reads remain free.

Assign and coordinate

epismo case access get <case-id>
epismo case access set <case-id> --access '{"visibility":"restricted","grants":{"<user-or-team-uuid>":"editor"}}' --lock-version <n>
epismo case assign <case-id> --assigned-to <user-id> --lock-version <n>
epismo case task create <case-id> --kind work --title "Verify totals" \
  --instructions "Use the latest invoice" --assigned-to <user-id>
epismo case task create <case-id> --kind approval --title "Approve recommendation" \
  --subject-record-id <record-id> --assigned-to <user-id>
epismo task list --status open

Add a user to the case ACL before assignment. Assign the case for whole-matter responsibility and a task for one explicit piece of work or approval. An approval task should identify its exact subject record. Top-level task list defaults to tasks assigned to the current user; pass --assigned-to only for another assignee.

Connect case handoffs

epismo case handoff create <from-case-id> --to-case-id <to-case-id>
epismo case handoff create <to-case-id> --from-case-id <from-case-id>
epismo case handoff remove <case-id> <handoff-id>
epismo case handoff graph get <case-id> --scope connected
epismo case handoff candidates list <case-id> --direction outgoing

Connect sequential or dependent cases using directed handoffs (fromCaseId -> toCaseId). Creating or removing a handoff requires read access on its source and work access on its destination, so a public case can be continued into a case you can edit, but a reader cannot attach work into a public case. Loops and cycles are strictly rejected. Inspect the DAG around any case using epismo case handoff graph get.

Append, update, and read records

epismo case record append <case-id> --kind output --origin agent --content "..."
epismo case record append <case-id> --kind note --origin agent --content "..."
epismo case record append <case-id> --task-id <task-id> --request @evidence.json
epismo case record update <record-id> --content "..."
epismo case record delete <record-id>
epismo case record list <case-id> --scope ancestors --order asc

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.

Clients write record kinds note, output, or agreement. activity is server-written. AI review creates reports rather than review records. Creators may edit or redact their non-system records while they can edit the open parent case. Use --scope (self, ancestors, descendants, neighbors, connected) for connected timelines; filters narrow authorized results and cursors preserve pagination.

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.

Update and close

epismo task update <task-id> --title "Verify totals and tax" \
  --instructions "Use the signed invoice" --assigned-to <user-id> --lock-version <n>
epismo task set status <task-id> --status approved --lock-version <n>
epismo task set status <task-id> --status open --lock-version <n>
epismo case update <case-id> --title "Updated title" --lock-version <n>
epismo case update <case-id> --input '{"customer":"Acme"}' --lock-version <n>
epismo case update <case-id> --version-id <version-id> \
  --input '{"customer":"Acme"}' --lock-version <n>
epismo report case get <case-id>
epismo report case generate <case-id>
epismo report case act <case-id> --report-id <report-id> --proposal-id <proposal-id> \
  --action create
epismo report case act <case-id> --report-id <report-id> --proposal-id <proposal-id> --action dismiss
epismo case close <case-id> --status completed --lock-version <n>
epismo case reopen <case-id> --lock-version <n>

Use completed or cancelled for work tasks, and approved, rejected, or cancelled for approval tasks. Use open to reopen a terminal task while its case is open. Put result details and reasons in records.

Use --version-id to attach or replace a readable, non-archived playbook version on an open case. Omit the field to preserve the current selection. To remove the playbook, use epismo case update CASE_ID --request '{"version_id":null,"expected_lock_version":3}'. Omit --input to reuse the current input, or supply the complete replacement object in the same update. The resulting input must satisfy the selected version's schema, if any; validation failures save no changes. Playbook changes create system activity and preserve existing tasks, records, and reports. Tasks retain their original step references.

You may append final records atomically while closing a task or case by providing the records array through --request or the relevant flag. Completion requires all tasks closed. Cancellation sets remaining open tasks to cancelled; reopening the case leaves them closed.

Case editors can use epismo report case generate <case-id> (or alias epismo case report generate; POST /v1/cases/{caseId}/report) to queue an asynchronous AI review assessment across the case's evidence and records. Generation 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 permitted by workspace policy.

Once processed, inspect the report and proposed actions with epismo report case get <case-id> (GET /v1/cases/{caseId}/report). The response includes report status, synthesized findings, and actionable proposals. Editors can confirm or dismiss proposals with epismo report case act <case-id> --report-id <report-id> --proposal-id <proposal-id> --action <create|dismiss> (POST /v1/cases/{caseId}/report/actions). 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.

External sources

epismo case source link <case-id> --url "https://acme.slack.com/archives/C123/p1234567890123456"
epismo case source link "$CASE_ID" --url "https://docs.google.com/document/d/FILE_ID/edit"
epismo case get <case-id>
epismo case source refresh <case-id> <source-id>
epismo case source get <case-id> <source-id>
epismo case source unlink <case-id> <source-id>

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.

Explicit creation settings and sharing updates use access: { visibility, grants }: restricted/public visibility and user/team UUID or registered user email keys with viewer/editor values. Emails resolve to user UUIDs before saving; responses contain UUID keys. An unregistered email or conflicting roles for the same resolved user rejects the entire write. Updates replace the whole object; preserve unrelated grants and include your own grant if you want to retain it. Owners retain management independently of grants. Assignees and maintainers receive no implicit access. Editors can inspect and replace sharing, retain at least one explicit editor when changing grants, and archive or restore. Ordinary resource JSON omits private grant maps; editors can retrieve the complete settings with access-get. See Access and identity.

Ownership, responsibility, and lifecycle

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.

Omit ownerId on creation or copy to use the active workspace, or your personal account when no workspace is selected. Supplying it explicitly chooses the home subject to authorization. When a workspace is selected, including a saved connection default, creation requires exactly one of private: true, non-empty teamIds, or access. Personal creation may omit sharing. Team editor access covers the creator without adding a redundant direct grant; an explicitly requested creator grant is preserved. Maintenance and assignment do not replace sharing.

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.

epismo case list --archived
epismo case archive <case-id> --lock-version <n>
epismo case restore <case-id> --lock-version <n>
epismo case delete <case-id> --lock-version <n>

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.

epismo case owner transfer <case-id> --owner-id <account-id> --lock-version <n>

Discover public cases with epismo case list --sharing-scope anyone; login is optional for public listing. Results use update-time order and include cases without records. Filter a source playbook with --playbook-id. With login, omit --sharing-scope to include all readable cases, or choose only_me, shared, or anyone. Filters never grant access; see Access and identity.

Browse saved evaluations

The case detail response includes the latest readable report and generation job without loading history or running AI. Use report case list (or alias case report list) for newest-first summaries, --page-size and --cursor for pagination, and report case get --report-id for a full saved evaluation.

History reads require current case work access and match the current sharing audience. Public-only readers cannot see reports or summaries. Superseded reports have historical: true and are read-only: creating or dismissing an unhandled proposal from one returns HTTP 409. Read the latest report and reconsider its proposal before acting. Changes to evidence alone still show an advisory reevaluation notice.

epismo report case list CASE_ID --page-size 20
epismo report case list CASE_ID --cursor NEXT_CURSOR
epismo report case get CASE_ID --report-id REPORT_ID

Personal and team reports

Personal reports are private to the generating user in the active billing home. Team reports and proposal handling are shared with current team members in the active workspace. See AI review for work selection, health diagnoses, history and sharing behavior.

epismo report personal generate --idempotency-key UUID
epismo report personal get --job-id JOB_ID
epismo report personal list --page-size 20
epismo report personal get --report-id REPORT_ID
epismo report personal act REPORT_ID --proposal-id PROPOSAL_ID --action create

epismo -w acme report team generate TEAM_ID --idempotency-key UUID
epismo -w acme report team get TEAM_ID --job-id JOB_ID
epismo -w acme report team list TEAM_ID --page-size 20
epismo -w acme report team get TEAM_ID --report-id REPORT_ID
epismo -w acme report team act REPORT_ID --proposal-id PROPOSAL_ID --action dismiss

Generation returns a job. Poll with --job-id, or select a saved report with --report-id; choose only one. Paginate history with --page-size and --cursor. Reuse --idempotency-key UUID on generation retries. Read the full saved proposal before act; action retries use its identity, so omit --idempotency-key. Output uses snake_case, including subject_type and evaluated_at, and the shared health field.