runtime-api.md

# Runtime API Notes

Hecate exposes a coding-runtime API surface under `/hecate/v1/tasks` for
client-orchestrated agents. The runtime is durable: a Run survives process
restarts, can be resumed from a terminal state, and is leased to one worker at
a time so two replicas can share a queue without stepping on each other. A
Task may also carry one durable Schedule that starts ordinary Runs.

For the high-level execution flow (lease semantics, sandbox boundary, event sequence), see [`architecture.md`](../contributor/architecture.md#task-runtime-flow). For the LLM-driven `agent_loop` execution kind specifically (tools, approval gating, cost tracking, retry-from-model-call semantics), see [`agent-runtime.md`](agent-runtime.md).

> Contributing here? Start at [`AGENTS.md`](../../AGENTS.md) for the codebase map and runtime invariants; conventions, workflow, and verification ladders live under [`docs-ai/`](../../docs-ai/README.md).

## API namespaces

Hecate serves three intentionally separate HTTP surfaces:

| Namespace      | Purpose                                                                                                                                                                                                                                                 |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/v1/*`        | Provider-compatible protocol ingress. These paths stay OpenAI- or Anthropic-shaped so existing SDKs can point at Hecate without learning Hecate-specific URLs. Today that means `GET /v1/models`, `POST /v1/chat/completions`, and `POST /v1/messages`. |
| `/hecate/v1/*` | Hecate-native product API: tasks, Hecate Chat sessions, External Agent integrations, settings, usage, traces, events, and system operations. Operator UI, MCP tools, and Hecate-aware clients should use this namespace.                                |
| `/healthz`     | Unversioned process liveness for local scripts, desktop sidecars, and load balancers. It is intentionally tiny and not wrapped in the normal `{object,data}` API envelope.                                                                              |

OTLP collector/export endpoints keep their standard protocol paths
(`/v1/traces`, `/v1/metrics`, `/v1/logs`) when Hecate is configured to export to
an OpenTelemetry collector. Those are not Hecate product resources. Hecate's
local trace lookup for the operator UI is `GET /hecate/v1/traces`.

Set `HECATE_RUNTIME_TOKEN` to require Hecate-aware clients to send
`X-Hecate-Runtime-Token` on `/hecate/v1/*`. This protects the Hecate-native
control plane, including Hecate-native chat and task routes that can spend
configured provider credentials. It does not apply to provider-compatible
`/v1/*` paths or `/healthz`. The operator UI sends the header when
`hecate.runtimeToken` is present in `sessionStorage` or `localStorage`; the MCP
server reads the same value from its `HECATE_RUNTIME_TOKEN` environment.

Set `HECATE_INFERENCE_TOKEN` to require a shared token on the
provider-compatible inference routes: `GET /v1/models`,
`POST /v1/chat/completions`, and `POST /v1/messages`. Clients may send it as
either `Authorization: Bearer <token>` or `x-api-key: <token>`, so standard
OpenAI- and Anthropic-shaped SDK configuration continues to work. This token
does not wrap `/hecate/v1/*`, `/healthz`, static UI assets, or OTLP collector
paths such as `/v1/traces`, `/v1/metrics`, and `/v1/logs`. The operator UI
sends it to local provider-compatible paths when `hecate.inferenceToken` is
present in `sessionStorage` or `localStorage`.

Provider-compatible inference bodies are bounded independently of Hecate Chat
attachments. `POST /v1/chat/completions` and `POST /v1/messages` accept one JSON
value, including inline rich-content data, up to 32 MiB of encoded request body.
They reject a larger body with `413`; a valid JSON prefix does not bypass the
limit because the decoder also requires EOF. The complete body must arrive
within the route-local 60-second read deadline or Hecate returns `408`, includes
`read_timeout_ms`. For HTTP/1.1, Hecate installs a route-local transport read
deadline and closes the expired connection. For HTTP/2, Hecate deliberately
does not set a connection-scoped transport read deadline: a route timer closes
only the stalled request body, then the handler returns the protocol-shaped
`408` envelope without disrupting unrelated streams. OpenAI ingress uses the
stable `request_too_large` / `request_body_timeout` error types. Messages
ingress keeps the Anthropic `{"type":"error","error":{...}}` envelope and uses
`request_too_large` / `invalid_request_error` respectively. Early malformed,
multi-value, oversized, and rate-limited requests commit their shaped error
before aborting unread bytes. HTTP/1.1 also marks the connection for close;
HTTP/2 flushes the response stream first and leaves the connection available
to other streams. This does not impose a global server timeout on SSE or other
long-lived responses.

OpenAI-shaped `image_url` blocks must include a non-empty HTTP(S) URL or valid
base64 image data URI. Optional `image_url.detail` is `auto`, `low`, or `high`; malformed
standard blocks and Hecate replay `content_blocks` return `400 invalid_request`
with the indexed `messages[n].content[n]` or `messages[n].content_blocks[n]`
field path before routing or any provider call.

When `HECATE_REMOTE_RUNTIME_MODE=1`, `/healthz` remains the unauthenticated
liveness probe and every other path requires trusted proxy headers:
`X-Hecate-Remote-Runtime-Secret`, `X-Hecate-Remote-Actor-ID`,
`X-Hecate-Remote-Org-ID`, and `X-Hecate-Remote-Runtime-ID`.
`X-Hecate-Remote-Project-ID` is optional; an omitted or empty value means
**No project**. Valid remote identity is attached to request
context, exposed from `GET /hecate/v1/whoami` as `data.remote_identity`, added to
the top-level HTTP span attributes, and accepted in place of the local
runtime/inference shared tokens. Remote mode rejects local-only endpoints for
workspace picker/open, reset-data, shutdown, MCP probe, plugin-registry
management, agent-adapter authenticate, and local provider and MCP registry
discovery. Executable-trust `PUT` and `DELETE` are remote-safe after trusted
identity is established: they approve or revoke the measured app on the
supervised runtime host, while `authenticate` remains local-only.
Hecate-native `/hecate/v1/*` routes are
explicitly classified for remote mode, and route coverage tests fail when a new
registered route is not marked remote-safe or local-only.

The native desktop app uses the same boundary without putting the whole
sidecar into remote runtime mode. It generates a new secret for each app
launch, passes it only to the loopback sidecar, and adds trusted identity only
to requests received through its outbound Cloud connection. Ordinary desktop
webview requests remain local. Once either ingress path attaches remote
identity, the same Go route policy blocks local-only and unclassified Hecate
endpoints; the Rust connector does not maintain a second endpoint allowlist.

`GET /hecate/v1/whoami` always identifies the Hecate runtime host in addition
to the operator session:

```json
{
  "object": "session",
  "data": {
    "role": "operator",
    "runtime_host": {
      "id": "runtime_00112233445566778899aabb",
      "label": "MacBook",
      "runtime_mode": "remote_runtime",
      "operator_access": "remote_supervision",
      "public_url": "https://hecate.example.com",
      "local_only_actions_available": false
    },
    "remote_identity": {
      "actor_id": "actor_1",
      "org_id": "org_1",
      "project_id": "",
      "runtime_id": "host_1"
    }
  }
}
```

Local requests report `runtime_mode: "local"`,
`operator_access: "local_operator"`, and
`local_only_actions_available: true`; `remote_identity` is omitted. Trusted
remote-runtime requests keep that same stable `runtime_host.id`, report
`operator_access: "remote_supervision"`, and set
`local_only_actions_available: false`. The separate
`remote_identity.runtime_id` identifies the trusted proxy or Cloud routing
target; it does not replace the host identity. `public_url` is present only
when `HECATE_PUBLIC_URL` is configured. The stable local runtime ID is
generated in `HECATE_DATA_DIR/hecate.runtime-host.json`; the operator-facing
label comes from `HECATE_RUNTIME_HOST_LABEL` or the machine hostname. Neither
field grants access.

Remote mode disables local model providers by default. In that default posture,
local presets are omitted, `kind=local` provider creates/updates are rejected,
env-preconfigured local providers are skipped, and existing local provider rows
are not loaded into the runtime provider registry. Set
`HECATE_REMOTE_ALLOW_LOCAL_PROVIDERS=1` only for a private hosted runtime whose
local model server is intentionally inside that runtime's isolation boundary.
This provider policy is kind-based: Hecate blocks providers marked
`kind=local`, but does not URL-filter custom `kind=cloud` `base_url`
destinations. Operators should enforce egress and private-endpoint policy
outside the runtime when they need destination-level controls.

Legacy Hecate-native `/v1/*` and `/admin/*` paths are intentionally not kept as
compatibility shims in this alpha branch. Unknown API-shaped paths return 404
rather than falling through to the embedded UI shell.

## Dictation API

These endpoints implement the provider-upload branch of Hecate's composer
dictation capability, separate from chat model routing:

- `GET /hecate/v1/dictation/options` returns only provider instances with an
  explicitly configured OpenAI-compatible transcription path and default
  transcription model. Available local routes sort before available cloud
  routes; unavailable routes include a bounded reason for operator repair.
- `POST /hecate/v1/dictation/transcriptions` accepts multipart form data with
  exactly one `provider`, one `file`, and at most one optional `model`. The
  response is
  `{object:"dictation_transcription",data:{provider,provider_kind,model,text}}`.

The upload accepts WebM, Ogg, M4A/MP4, MP3, or WAV audio. Hecate checks the
declared type against the file signature, permits at most 10 MiB of audio plus
bounded multipart overhead, applies a 60-second body-read deadline, admits at
most two dictation requests per process, and bounds the selected provider call
to five minutes. Both endpoints return `Cache-Control: no-store`.

The provider name is mandatory. Hecate captures that provider's opaque runtime
generation after reading and validating the upload, rechecks the same
generation immediately before the upstream call, and never fails over to a
different provider. This prevents a route replacement from silently changing
the audio destination. Audio and transcript bodies do not enter Hecate
persistence, usage events, traces, metrics, or logs; the UI inserts the returned
text into the editable composer draft and never submits it automatically.

Client Web Speech routes and operating-system dictation do not call these
endpoints. The explicit browser-managed route may use the browser vendor's
cloud service and does not send audio through Hecate or Tauri IPC. The composer
does not invoke experimental static on-device language-pack probes and does not
silently fail over between a client route and this provider API.

Stable dictation error types are `dictation.invalid`, `dictation.too_large`,
`dictation.unsupported_media`, `dictation.busy`, `dictation.body_timeout`,
`dictation.unavailable`, `dictation.route_unavailable`,
`dictation.route_changed`, `dictation.timeout`, and
`dictation.upstream_failure`.

## Error envelope

Hecate-native JSON errors use one stable envelope:

```json
{
  "error": {
    "type": "route_impossible",
    "message": "route request: no provider available",
    "user_message": "No configured provider can serve this request.",
    "operator_action": "Open Connections to inspect readiness checks, discover models, or enable a routable provider.",
    "request_id": "req_...",
    "trace_id": "..."
  }
}
```

- `type` is the stable machine code. Operator UI and automation should branch
  on this field, not raw text.
- `message` is the detailed gateway/runtime message. It may include provider or
  router wording.
- `user_message` is the short operator-facing summary.
- `operator_action` is the recommended next step.
- `request_id` and `trace_id` are included when the runtime has already created
  trace state. They mirror `X-Request-Id` / `X-Trace-Id` and let clients open
  `GET /hecate/v1/traces?request_id=...` directly from an error surface.
- Runtime-specific fields may be attached when they help repair the failure.
  Examples: `task_id`, `latest_run_id`, and `run_status` for a busy Hecate Chat
  task; `provider`, `model`, and `capabilities` for tool-capability failures;
  `limit_ms` / `turns_used` for session guardrails.

Common JSON error types:

| Type                                            |      Status | Meaning                                                                              |
| ----------------------------------------------- | ----------: | ------------------------------------------------------------------------------------ |
| `invalid_request`                               | 400/409/422 | Endpoint-specific request, precondition, or transition validation failed.            |
| `request_body_timeout`                          |         408 | A provider-compatible inference body missed its 60-second read deadline.             |
| `request_too_large`                             |         413 | A provider-compatible inference body exceeds the 32 MiB encoded limit.               |
| `not_found`                                     |         404 | The requested Hecate resource does not exist.                                        |
| `conflict`                                      |         409 | The resource changed state or the requested transition is not valid now.             |
| `gateway_error`                                 |         500 | Hecate failed before it could classify the failure more specifically.                |
| `rate_limit_exceeded`                           |         429 | The local gateway rate limiter rejected the request.                                 |
| `model_not_configured`                          |         422 | The selected model is stale or not currently reported by the selected provider.      |
| `chat.agent_session_busy`                       |         409 | A Hecate Chat task-backed loop is queued, running, or awaiting approval.             |
| `chat.model_capability_required`                |         422 | A task-backed Hecate Chat turn was requested, but the model is not tool-capable.     |
| `chat.image_capability_required`                |         422 | No matching routable provider/model route has effective image-input support.         |
| `chat.attachment_invalid`                       |         422 | The multipart upload is empty or malformed.                                          |
| `chat.attachment_too_large`                     |         413 | A file exceeds the per-file, multipart, or combined-message byte limit.              |
| `chat.attachment_unsupported`                   |         422 | The file format or requested chat runtime does not support attachments.              |
| `chat.attachment_not_found`                     |         404 | The attachment does not belong to the requested chat session.                        |
| `chat.attachment_in_use`                        |         409 | A persisted message already references the attachment.                               |
| `chat.attachment_draft_quota_exceeded`          |         409 | The chat has eight unlinked drafts or 40 MiB of staged file bodies.                  |
| `chat.attachment_session_quota_exceeded`        |         409 | The chat has reached 512 MiB of retained file bodies.                                |
| `chat.attachment_total_quota_exceeded`          |         409 | The backend-wide retained-attachment limit was reached.                              |
| `chat.attachment_upload_busy`                   |         429 | Both attachment validation slots are occupied; retry after the advertised delay.     |
| `chat.attachment_upload_timeout`                |         408 | The upload body could not be read within the route-local deadline.                   |
| `chat.attachment_content_busy`                  |         429 | All four bounded file download slots are occupied; retry after the advertised delay. |
| `chat.image_turn_busy`                          |         429 | Both image-turn slots are occupied; retry after the advertised delay.                |
| `chat.external_file_turn_busy`                  |         429 | Both External file-turn slots are occupied; retry after the advertised delay.        |
| `chat.workspace_required`                       |         400 | Task-backed Hecate Chat or External Agent chat needs a workspace path.               |
| `agent_adapter.executable_trust_required`       |         409 | The current External Agent app identity has not been approved.                       |
| `agent_adapter.executable_identity_changed`     |         409 | The app no longer matches its approved identity or approval used a stale token.      |
| `agent_adapter.executable_identity_unavailable` |         503 | Hecate could not measure or persist executable identity at the required boundary.    |
| `chat.session_limit_exceeded`                   |         422 | The chat turn limit was reached.                                                     |
| `chat.session_duration_limit_exceeded`          |         422 | The chat wall-clock limit was reached.                                               |
| `chat.session_idle_timeout`                     |         422 | The chat was idle beyond the configured timeout.                                     |

OpenAI-compatible and Anthropic-compatible ingress paths keep their protocol
shape, but gateway-classified failures also include the same
`user_message` / `operator_action` / correlation fields inside their `error`
object when available. The common error-type table names Hecate/OpenAI-shaped
codes; Anthropic-shaped endpoints map them to the corresponding Messages API
type while preserving the status and remediation fields.

## Contents

- [API namespaces](#api-namespaces)
- [Error envelope](#error-envelope)
- [Core resources](#core-resources)
  - [Task fields](#task-fields)
  - [Run fields](#run-fields)
  - [Schedule fields and endpoints](#schedule-fields-and-endpoints)
  - [Report-only QA workflow](#report-only-qa-workflow)
- [Lifecycle endpoints](#lifecycle-endpoints)
  - [Resume semantics](#resume-semantics)
  - [Retry-from-model-call-N semantics](#retry-from-model-call-n-semantics)
- [Execution detail endpoints](#execution-detail-endpoints)
- [Approval endpoints](#approval-endpoints)
  - [Approval kinds](#approval-kinds)
  - [Approval policy configuration](#approval-policy-configuration)
- [Event and stream endpoints](#event-and-stream-endpoints)
- [Queue execution model](#queue-execution-model)
- [Runtime backend and queue configuration](#runtime-backend-and-queue-configuration)
- [Usage endpoints](#usage-endpoints)
- [Health and discovery endpoints](#health-and-discovery-endpoints)
- [Plugin registry endpoints](#plugin-registry-endpoints)
- [Work policy endpoints](#work-policy-endpoints)
- [Project endpoints](#project-endpoints)
- [Project Assistant endpoints](#project-assistant-endpoints)
- [Chat session endpoints](#chat-session-endpoints)
- [Rate-limit headers on chat / messages](#rate-limit-headers-on-chat--messages)

## Core resources

- `task`
- `task_run`
- `task_schedule`
- `task_schedule_occurrence`
- `task_step`
- `task_artifact`
- `task_approval`
- `task_run_event`

### Task fields

The `task` resource accepts these fields on `POST /hecate/v1/tasks`:

- `execution_kind` — one of `shell`, `git`, `file`, `agent_loop`
- `workflow_mode` — optional built-in runbook selector. Omit for an ordinary
  task; the only accepted value today is `"qa"`, which requires
  `execution_kind="agent_loop"`. `workflow_version` is output-only and assigned
  by Hecate, not a client input.
- `agent_preset_id` — optional Hecate Work policy for a standard native
  `agent_loop` Task. The preset must have `surface="hecate_task"` or `"any"`.
  It is invalid for QA, non-`agent_loop` execution kinds, and External Agents.
  Hecate resolves it and freezes its runtime posture when the Task is created.
- `prompt` — the user-facing prompt; required for `agent_loop`, optional description for the others
- `project_id` — optional owning project id. Empty / omitted creates an unprojected task; `GET /hecate/v1/tasks?project_id=` lists only unprojected tasks
- `system_prompt` — per-task agent prompt (narrowest of the three-layer composition); `agent_loop` only
- `shell_command` / `git_command` / `file_path` / `file_content` / `file_operation` — execution-kind-specific
- `working_directory` — absolute path; required when `workspace_mode=in_place`
- `workspace_mode` — `""` / `"persistent"` / `"ephemeral"` (clone behavior, default) or `"in_place"` (run directly in `working_directory`); see [`agent-runtime.md`](agent-runtime.md#workspace-modes)
- `repo` / `base_branch` — alternate source for the workspace clone
- `sandbox_allowed_root` / `sandbox_read_only` / `sandbox_network` — sandbox policy for shell / git / file execution and native `agent_loop` workspace tools. Read-only agent loops omit broad process and direct-write tools. For Work-policy-backed native Tasks, the network snapshot also gates native HTTP/search; see [`sandbox.md`](sandbox.md) for the full policy and isolation model
- `requested_provider` / `requested_model` — pin the LLM for an `agent_loop`
  task. Omit both to let Hecate auto-route by eligible provider defaults and
  retain normal failover. Supplying a provider without a model is invalid at
  start time.
- `budget_micros_usd` — per-task cost ceiling in micro-USD; `0` disables
- `mcp_servers` — `agent_loop`-only array of external MCP server configs whose tools join the LLM's tool catalog under `mcp__<name>__<tool>` aliases. Each entry picks one transport (stdio: `command` + optional `args` / `env`; HTTP: `url` + optional `headers`), and may set `approval_policy` (`auto` / `require_approval` / `block`). Capped per-task by `HECATE_TASK_MAX_MCP_SERVERS_PER_TASK`. Full schema, secret handling, and lifecycle in [`mcp.md#hecate-as-mcp-client`](mcp.md#hecate-as-mcp-client).
- `priority` / `timeout_ms`

When `project_id` is non-empty, manual `POST /hecate/v1/tasks` creation holds
Hecate's process-local project mutation fence from the Cairnline-backed project
existence check through durable Hecate Task creation. Same-project deletion
therefore makes a competing create return `409 conflict`; another project can
continue. This coordinates Hecate execution state with Cairnline authority and
does not create a second project store.

Task responses may also include `workspace_system_prompt_policy`. Empty /
omitted means the normal workspace `CLAUDE.md` / `AGENTS.md` prompt layer is
eligible. `exclude` means the runner skips that compatibility layer for the
task; native project assignments set this so Agent Preset context-source policy
controls any workspace-instruction body inclusion.

`POST /hecate/v1/tasks` creates execution intent; it does not create or enqueue
a Run. The new Task therefore has canonical `status="not_started"` and no
`latest_run_id`. This is a breaking status contract: clients must not interpret
Task creation as queue admission, and Hecate does not emit a legacy `queued`
alias for a Task with no Runs. `POST /hecate/v1/tasks/{id}/start` creates the
first Run and atomically projects its initial `queued` or `awaiting_approval`
status and id onto the Task.

When `workflow_mode="qa"`, Hecate applies a report-only contract at create
time. It rejects `mcp_servers`, `sandbox_network=true`, a non-`agent_loop`
execution kind, and an explicitly requested workspace mode other than
`"ephemeral"`. It then persists `workspace_mode="ephemeral"`,
`sandbox_read_only=true`, `sandbox_network=false`, and the server-selected
`workflow_version="v0"`, and `workspace_system_prompt_policy="exclude"`.
A caller cannot widen this posture with task fields. The Task response exposes
the selected workflow fields and excluded workspace-prompt policy; ordinary
tasks omit the workflow fields. The task runtime independently enforces the
same tool boundary when the Run executes, rather than relying only on these
stored flags.

Task list/detail responses summarize the selected latest Run with
`latest_run_id`, `latest_model`, `latest_provider`,
`latest_run_step_count`, and `latest_run_artifact_count`. The count fields are
Run-local; Task responses do not expose cumulative `step_count` or
`artifact_count` aliases across the Task's complete Run history.

Task responses include `agent_preset_id` when a standalone native Task or a
project-work assignment selected a Work policy, or when a tools-on Hecate Chat
backing Task copied its frozen Chat-safe snapshot. Project-created Tasks also
include `work_item_id` and `assignment_id`. The latter are inspection links and
do not replace the task's generic `origin_kind` / `origin_id` fields. The
effective preset posture is snapshotted onto ordinary task fields (`sandbox_read_only`,
`sandbox_network`, provider/model hints, execution profile, and system prompt)
plus output-only optional `agent_preset_tools_enabled`,
`agent_preset_approval_policy`,
`agent_preset_browser_allowed`,
`agent_preset_browser_interactions_allowed`, and
`agent_preset_browser_allowed_origins` fields, so retries and resumes do not
change when the preset is later edited or deleted. The two browser grants are
independent and share the snapshotted exact-origin list. They are distinct from
`sandbox_network`: one controls static `browser_inspect`, and the other
controls approval-bound `browser_flow`. An omitted approval snapshot means that
there is no frozen Work policy approval layer; legacy Hecate Chat snapshots,
External Agent, QA, and non-preset Tasks all use that state. New tools-on
Hecate Chat backing Tasks carry the explicit value frozen with the session.
An omitted tools snapshot
preserves existing tool behavior, while explicit
`agent_preset_tools_enabled=false` is an all-tools denial. Omitted browser
snapshots grant no browser capability.
For `origin_kind="chat"`, every run-creation endpoint and approval-resolution
requeue validates that the owning chat still exists and participates in the
chat deletion fence. Start, retry, resume, continue, retry-from-model-call, and
approval resolution return `409 invalid_request` without creating or requeueing
a run when deletion owns that origin or the durable chat owner is already
missing. The retained Task and earlier run history remain readable.

Every run-creation action also passes one atomic task/run start transition.
Within a process, Hecate serializes the full preflight and workspace-provision
path per task. Isolated provisioning admits the planned destination before any
write, then uses stable root-relative filesystem handles, owner-writable private
staging, and atomic no-replace publication so a concurrent reservation, path
swap, or symlink swap cannot replace another directory or redirect clone/copy
output outside the managed root. Source directory modes are restored before
publication; identity-gated cleanup makes incomplete trees removable and
surfaces cleanup failures. The memory, SQLite, or Postgres task store then
authoritatively checks that no non-terminal run exists, preserves or raises
(never lowers) the current `budget_micros_usd`, assigns the next run number,
creates the run, and advances the task projection in one lock/transaction.
Concurrent actions can therefore create at most one active run; losers return
the existing active-run conflict, and a stale resume cannot overwrite a higher
committed ceiling.

`execution_profile` applies task-create defaults:

| Profile        | Defaults                                                                                                                                                              |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `repo_local`   | `execution_kind=agent_loop`, `workspace_mode=persistent`, `working_directory=.`, `timeout_ms=120000`                                                                  |
| `coding_agent` | Same as `repo_local`, plus `timeout_ms=300000` and a coding-oriented system prompt that nudges the model toward read-before-edit and `file_edit` for targeted changes |

### Run fields

`task_run` carries the cost figures the operator UI surfaces:

- `project_id` / `work_item_id` / `assignment_id` — project inspection links
  snapped onto new runs from the parent task. Older alpha rows may still derive
  these links from the parent task or run context-packet refs when the run
  payload predates direct run linkage.
- `total_cost_micros_usd` — this run's LLM spend (after routing).
- `prior_cost_micros_usd` — cumulative spend of every prior run in this run's resume chain. Cumulative-across-task = `prior + total`.
- `model_call_count` — completed provider model calls accounted to this Run. It is always present, including explicit `0`, and is distinct from `step_count` because Steps also include tools and control activity.
- `model` / `provider` / `provider_kind` — what was actually used (after routing). May differ from the task's `requested_*` when the operator picked auto. Agent-loop runs preserve these fields for both streaming and non-streaming model calls.
- `source_ref` — present when the Run carries a canonical source Chat Turn in
  its persisted context packet. `kind="chat_turn"` includes the exact
  `chat_session_id`, `turn_id`, and `message_id`. Retry and resume Runs retain
  that source while receiving their own new `run_id`, so clients can return to
  the originating Chat Turn without inferring provenance from transcript
  fields.
- `workflow_mode` / `workflow_version` — output-only snapshot of the built-in
  runbook contract selected on the parent Task. They are absent for ordinary
  Runs and let retry/resume history retain the exact QA contract that executed.
- `schedule_id` / `schedule_occurrence_id` / `scheduled_for` — output-only
  provenance for a Run created by a Schedule. Manual start, retry, resume, and
  continuation Runs omit these fields. `scheduled_for` is the trigger's
  nominal UTC instant and may precede `started_at` after runtime downtime.

### Schedule fields and endpoints

A Task may have at most one `task_schedule`. The Schedule is a trigger, not a
future Run: Hecate creates the Run only after an occurrence is durably claimed.
Replacing a Schedule preserves its `id`, `created_at`, and occurrence history;
removing it deletes that trigger history. Deleting the Task deletes both.
Chat-owned Tasks (`origin_kind="chat"`) cannot have a Schedule because a
scheduled occurrence starts without a submitted Chat Turn. Create a standalone
Task for one-time or recurring unattended work.

Schedule endpoints are:

- `GET /hecate/v1/task-schedules` — lists Schedules. Optional `task_id`,
  `enabled=true|false`, and `limit` query parameters are AND-combined. Repeat
  `task_id` to match any one of an exact Task-id set. Blank values are ignored,
  duplicate values are collapsed, and requests may contain at most 200 unique
  Task ids. `limit` defaults to 100 and is capped at 200.
- `GET /hecate/v1/tasks/{id}/schedule` — returns the Task's Schedule or
  `404 not_found`.
- `PUT /hecate/v1/tasks/{id}/schedule` — creates or completely replaces the
  Task's one Schedule and returns it with `200 OK`.
- `DELETE /hecate/v1/tasks/{id}/schedule` — removes the Schedule and its
  occurrence history with `204 No Content`.
- `GET /hecate/v1/tasks/{id}/schedule/occurrences` — returns newest first;
  optional `limit` defaults to 50 and is capped at 200.

Every GET uses the normal Hecate envelope. A single Schedule returns
`{"object":"task_schedule","data":{...}}`; list and occurrence responses use
`task_schedules` and `task_schedule_occurrences` object names with arrays in
`data`.

Malformed fields or query values return `400 invalid_request`. A missing Task
or per-Task Schedule returns `404 not_found`. Schedule replacement is
revision-fenced internally. If an edit repeatedly loses to another edit or to
the scheduler, it returns `409 conflict` with a reload/retry instruction. A
one-time Schedule that fires while its replacement is being saved also returns
`409 conflict`; choose a new future `run_at` rather than reviving the consumed
instant. If Task deletion wins while a Schedule is being saved, the save
returns the same stable `404 not_found` response as any other missing Task.
`PUT` for a Chat-owned Task returns `400 invalid_request` with
`chat-owned tasks cannot be scheduled`, whether the submitted Schedule is
enabled or paused.

`PUT` requires `kind`, `timezone`, and the boolean `enabled` field. Supported
kinds are:

- `once` — requires a future RFC3339 `run_at`. It fires at most once, then
  becomes disabled and omits `next_run_at`.
- `cron` — requires a standard five-field `cron_expression` (minute, hour, day
  of month, month, day of week). Seconds, descriptor forms, and expressions
  with no possible future occurrence are not accepted, even while disabled.

`timezone` must be an IANA name such as `Europe/Madrid` or `UTC`; the
process-local pseudo-zone `Local` is rejected. Cron evaluation follows that
zone, including daylight-saving transitions. A once Schedule stores `run_at`
as an exact instant. An enabled Schedule exposes its derived UTC
`next_run_at`; a paused Schedule keeps its authored configuration but omits
`next_run_at`. Re-enabling a cron Schedule derives its next future occurrence
from the current time.

One-time example:

```json
{
  "kind": "once",
  "timezone": "Europe/Madrid",
  "run_at": "2026-07-21T07:00:00Z",
  "enabled": true
}
```

Recurring example:

```json
{
  "kind": "cron",
  "timezone": "Europe/Madrid",
  "cron_expression": "0 9 * * 1-5",
  "enabled": true
}
```

An occurrence is durable trigger history with `id`, `task_id`, `schedule_id`,
`scheduled_for`, `status`, `claimed_at`, and optional `run_id`, `error`, and
`completed_at`. Status is `claimed`, `started`, `skipped`, or `failed`.
`started` links to the ordinary Run created for that occurrence. `skipped`
means another Run for the Task was already active; Hecate does not queue a
backlog behind it. `failed` means the trigger was claimed but Hecate could not
start the Run.

The scheduler runs inside the Hecate runtime process. The runtime host must be
running for a trigger to start promptly; explicitly quitting the desktop app or
stopping the gateway pauses dispatch. Closing only the main desktop window
keeps the runtime active in the tray. At the next start, an overdue one-time
Schedule produces one due occurrence, while multiple missed cron times coalesce
into one due occurrence and the next time advances beyond the current clock.
There is no per-interval backfill.

Scheduled Runs use the same task application, atomic active-Run guard, queue,
sandbox, approvals, model policy, workspace policy, and budget ceiling as a
manual start. An `awaiting_approval` Run therefore counts as active and causes
a simultaneous scheduled occurrence to be skipped.

### Report-only QA workflow

`workflow_mode="qa"` is a native Hecate Task contract, not an External Agent
or ACP capability and not a generic workflow scheduler. It permits file and
artifact inspection through `read_file`, `grep`, `glob`, `artifact_read`, and
`list_dir`. The `git_status` and `git_diff` tool names return an explicit
unavailable result in QA v0 without invoking Git because the source snapshot
excludes Git metadata. QA blocks shell and terminal commands, workspace/Git
writes, patch or proposal creation, external MCP tools, native HTTP requests,
web search, static browser inspection, and browser interaction. A tool call
returned by a model that is outside that set is denied before approval or
dispatch.

QA v0 blocks `browser_inspect` and `browser_flow`. Its public Task creation
surface has no assignment-launch selector for either browser grant, so it does
not claim a conditional capability operators cannot select. A future QA
contract may add constrained browser capability only with an explicit Hecate
runtime selection; it would not add a general URL checker, retained browser
state, or a shell test runner.

At execution time Hecate accepts only the canonical `qa` / `v0` contract.
Malformed, partial, unknown, or future persisted workflow values, or an
inherited workspace system-prompt policy, fail closed before workspace
provisioning or executor selection. QA Runs use the generated Hecate-managed
Task/Run workspace; retry, resume, and model-call retry create a fresh isolated
workspace rather than reusing a prior source path. For a local Git source,
Hecate snapshots the directory rather than performing a Git clone checkout and
excludes every `.git` entry, so host global Git filters cannot run and linked
worktree metadata cannot expose later source index/object changes. QA v0
therefore has no Git evidence: `git_status` and `git_diff` explain that
limitation without invoking Git.
An execution profile may contribute ordinary Task defaults, but QA overrides an
implicit profile workspace default to `ephemeral`; only a caller-supplied
non-ephemeral workspace mode is rejected.

At Run start Hecate creates a static JSON `workflow_manifest` artifact. It
contains the contract version and allowed/unavailable/blocked capability lists, but no
prompt, workspace path, credentials, or model output. When an agent produces a
final response, Hecate creates a JSON `workflow_report` artifact with a stable
envelope like:

```json
{
  "schema_version": "hecate.workflow_report.v0",
  "runbook_id": "builtin.qa.v0",
  "workflow": { "mode": "qa", "version": "v0", "report_only": true },
  "agent_reported": {
    "outcome": "reported",
    "summary_markdown": "Agent narrative goes here."
  },
  "hecate_observed": {
    "manifest_artifact_id": "workflow-manifest-run_...",
    "workspace_posture": "read_only",
    "native_network_posture": "blocked",
    "mcp_posture": "blocked",
    "git_evidence_posture": "unavailable_in_v0",
    "browser_evidence_posture": "unavailable_in_v0"
  }
}
```

`agent_reported` is agent prose, not verification that a test or browser check
ran. `hecate_observed` is Hecate-derived posture and artifact linkage. If no
agent final response exists—for example, the model is unavailable or the run
ends before a final answer—Hecate retains the manifest but does not fabricate a
workflow report. Both artifacts are retrieved through the ordinary Run artifact
endpoints and are also projected through task/run detail and SSE snapshots.

## Lifecycle endpoints

- `POST /hecate/v1/tasks`
- `GET /hecate/v1/tasks` — optional `project_id` query scopes the list. Pass an empty value (`?project_id=`) for unprojected tasks only.
- `GET /hecate/v1/tasks/{id}`
- `DELETE /hecate/v1/tasks/{id}`
- `POST /hecate/v1/tasks/{id}/start` — returns `422 model_not_configured` for
  an incomplete explicit route (for example, `requested_provider` without
  `requested_model`). An empty provider/model pair is Hecate auto-routing.
- `POST /hecate/v1/tasks/{id}/runs/{run_id}/retry`
- `POST /hecate/v1/tasks/{id}/runs/{run_id}/resume`
- `POST /hecate/v1/tasks/{id}/runs/{run_id}/continue`
- `POST /hecate/v1/tasks/{id}/runs/{run_id}/retry-from-model-call`
- `POST /hecate/v1/tasks/{id}/runs/{run_id}/cancel`

Task deletion returns `409 invalid_request` while any persisted Run is
non-terminal, even if the Task's latest-Run projection is stale. Deletion and
manual or scheduled Run admission share one storage lock/transaction, so a
race has one durable winner: either deletion completes and admission finds no
Task, or admission completes and deletion reports the active-Run conflict.

### Resume semantics

- resume is allowed when the source run is terminal (`completed`, `failed`, or `cancelled`)
- resume creates a new run attempt (new `run_id`) rather than mutating the original run
- the new run reuses the prior run workspace when available, so file state carries forward; the report-only `workflow_mode="qa"` contract is the exception: retry, resume, and retry-from-model-call create a fresh Hecate-managed workspace for the new run
- optional payload: `{"reason":"..."}` to annotate the resume request
- resumed executions include checkpoint context (source run id, last completed step, last event sequence) in step input so executors/tools can continue from the prior boundary
- for `agent_loop` runs, the saved `agent_conversation` artifact is hydrated as the starting message history — the loop continues from where it left off rather than repeating prior model calls
- the new run inherits the chain's cumulative cost via `PriorCostMicrosUSD`, so the per-task ceiling holds across the full chain

### Continue semantics

`POST /hecate/v1/tasks/{id}/runs/{run_id}/continue` body:

```json
{ "prompt": "follow-up instruction" }
```

- only valid for terminal `agent_loop` runs that produced an `agent_conversation` artifact
- creates a new run for the same task, hydrates the source conversation, appends the supplied user prompt, then resumes the loop
- used by ACP/editor sessions where one editor conversation maps to one durable Hecate task and each user prompt becomes the next Hecate run
- returns 409 when the source run is still active, and 400 for non-agent tasks, empty prompts, or missing/malformed conversation artifacts

### Retry-from-model-call-N semantics

`POST /hecate/v1/tasks/{id}/runs/{run_id}/retry-from-model-call` body:

```json
{ "model_call_index": 2, "reason": "explore alternative" }
```

- only valid on `agent_loop` runs that produced an `agent_conversation` artifact
- `model_call_index` is 1-based within the selected source Run and must be in `[1, source_run.model_call_count]`; out-of-range values return 400
- inherited assistant responses remain prior-Run context and are not addressable from the descendant Run; select the Run that produced an older response to branch there
- creates a new Run whose conversation is truncated immediately before the selected Run-local response; the model re-issues that call from the preserved context
- model-call and Step indices on the new Run restart at 1 (semantically a fresh Run that shares prior context, not a continuation)
- see [`agent-runtime.md`](agent-runtime.md#retry-and-resume) for the full flow

## Execution detail endpoints

- `GET /hecate/v1/tasks/{id}/runs`
- `GET /hecate/v1/tasks/{id}/runs/{run_id}`
- `GET /hecate/v1/tasks/{id}/runs/{run_id}/context`
- `GET /hecate/v1/tasks/{id}/runs/{run_id}/steps`
- `GET /hecate/v1/tasks/{id}/runs/{run_id}/steps/{step_id}`
- `GET /hecate/v1/tasks/{id}/runs/{run_id}/artifacts`
- `GET /hecate/v1/tasks/{id}/runs/{run_id}/artifacts/{artifact_id}`
- `GET /hecate/v1/tasks/{id}/artifacts`
- `GET /hecate/v1/tasks/{id}/runs/{run_id}/patches`
- `GET /hecate/v1/tasks/{id}/runs/{run_id}/patches/{artifact_id}`
- `POST /hecate/v1/tasks/{id}/runs/{run_id}/patches/{artifact_id}/apply`
- `POST /hecate/v1/tasks/{id}/runs/{run_id}/patches/{artifact_id}/revert`

`patches` is a review-focused projection over `patch` artifacts. File-writing
tools create patches with `status=applied`; `file_edit` and `apply_patch` can
also create `status=proposed` patches when called with `propose=true`. The apply
endpoint writes the proposed after-content only when the current file still
matches the captured before-content, then emits `tool.file.applied`. The revert
endpoint restores the before-content captured in Hecate's patch artifact and
updates the patch to `status=reverted`. Before reverting, Hecate verifies that
the current file still matches the artifact's after-content (or is still
present/absent as expected for create/delete patches). If it drifted, the
endpoint returns `409 conflict`, leaves the workspace unchanged, keeps the
artifact `applied`, and emits no `tool.file.reverted` event. Reverting an
already-reverted artifact also returns `409`. Reverting a new-file patch removes
the file; a successful revert emits `tool.file.reverted` on the run-event
stream.

Both patch mutation endpoints hold a writer lease from the shared process-local
workspace registry across the final content precondition, filesystem change,
and artifact/event update. They return `409 conflict` without touching the file
when an overlapping chat workspace discard currently owns the exclusive
closure.

`GET /hecate/v1/tasks/{id}/runs/{run_id}/context` returns the context packet
snapshot for a task run. Hecate first returns a run-owned packet when the run
persisted one directly, then falls back to a linked Hecate Chat assistant
message packet for task-backed Chat turns. Native project-assignment starts now
persist a run-owned packet, and resume/retry chains carry the latest stored
packet forward onto the new run with updated task/run refs. Older or unrelated
runs can still return `404 not_found` when no stored or linked packet exists.

## Approval endpoints

- `GET /hecate/v1/tasks/{id}/approvals`
- `GET /hecate/v1/tasks/{id}/approvals/{approval_id}`
- `POST /hecate/v1/tasks/{id}/approvals/{approval_id}/resolve`

### Approval kinds

The `kind` field on a `task_approval` is one of:

- `shell_command` — pre-execution gate for `execution_kind=shell` tasks
- `git_exec` — pre-execution gate for `execution_kind=git` tasks
- `file_write` — pre-execution gate for `execution_kind=file` tasks
- `network_egress` — pre-execution gate when `sandbox_network=true`, except for an `agent_loop` task whose Agent Preset snapshot explicitly disables tools
- `agent_loop_tool_call` — mid-loop gate when an `agent_loop` run calls a gated tool (`shell_exec`, `http_request`, etc.). The reason text lists the tools the agent wants to use. See [`agent-runtime.md`](agent-runtime.md#approval-gating) for the full flow.

Approval responses may also include `action_summary`, an ordered, sanitized
description of the complete pending tool-call bundle covered by that decision.
This includes calls that would not independently require approval because
approving one gated call authorizes dispatch of the whole model response. The
summary is bounded to 16 lines, 512 UTF-8 bytes per line, and 4 KiB total.
`action_summary_incomplete=true` means at least one call or detail was omitted,
truncated, unrecognized, or deliberately withheld. Command bodies, file
contents, patches, HTTP headers and bodies, web queries, and MCP arguments are
not copied verbatim; the API exposes safe operational fields and byte/count
shapes instead. These fields are present on approval resources and SSE
snapshots, but are intentionally absent from public `approval.requested` and
`approval.resolved` event payloads so events do not become a second input-data
telemetry channel.

Resolve payload: `{"decision": "approve" | "reject", "note": "..."}`.

Approval resolution is owned by the task runtime so approval, run, task, step, and run-event state transition together:

- `approve` marks the pending approval `approved`, emits `approval.resolved`, requeues the same run (`queued`) and task (`queued`), and emits `run.queued`. For `agent_loop_tool_call`, the loop dispatches the approved tool calls without re-calling the LLM.
- `reject` marks the pending approval `rejected`, emits `approval.resolved`, and terminalizes the run/task as `cancelled` with `last_error: "approval rejected"`. Any awaiting approval step is cancelled, and the runtime emits `run.cancelled` and `task.updated`.
- Cancelling an `awaiting_approval` run cancels the run/task, cancels pending approvals with `resolved_by: "system"`, cancels the awaiting approval step, and emits the same terminal run/task events. Resolving that approval afterward returns `409 conflict`.
- Resolving a non-pending approval returns `409 conflict`; cancelling an already-terminal run is a no-op and returns the current terminal run.

### Approval policy configuration

`HECATE_TASK_APPROVAL_POLICIES` (default `shell_exec,git_exec,file_write`) is a comma-separated allowlist of which approval gates are active across the task runtime. It controls both pre-execution gates on `shell` / `git` / `file` tasks **and** mid-loop gates inside `agent_loop` runs — same env var, same names. Recognized values:

| Value            | Effect                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `shell_exec`     | Gate `execution_kind=shell` task creates and `agent_loop` `shell_exec` tool calls.                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `git_exec`       | Gate `execution_kind=git` task creates and `agent_loop` `git_exec` / `git_status` / `git_diff` tool calls, except QA v0 Git evidence: it returns an unavailable result without invoking Git or asking for approval.                                                                                                                                                                                                                                                                                                   |
| `file_write`     | Gate `execution_kind=file` task creates and `agent_loop` `file_write` / `file_edit` / `apply_patch` tool calls.                                                                                                                                                                                                                                                                                                                                                                                                       |
| `network_egress` | Gate task creates that opt into `sandbox_network=true` and `agent_loop` `http_request` / configured `web_search` tool calls. A tools-disabled Agent Preset snapshot creates no approval in either path; any unexpected mid-loop call is hard-denied instead.                                                                                                                                                                                                                                                          |
| `read_file`      | Gate each `agent_loop` `read_file` / `grep` / `glob` / `code_intelligence` / `artifact_read` call. Useful when operators want visibility into direct reads and search/intelligence calls, not just writes; a trusted language server may inspect multiple workspace/build files behind one approved call.                                                                                                                                                                                                             |
| `all_tools`      | Gate every otherwise-permitted agent tool call (`shell_exec`, `git_exec`, `git_status`, `git_diff`, `file_write`, `file_edit`, `apply_patch`, `read_file`, `grep`, `glob`, `code_intelligence`, `artifact_read`, `list_dir`, `http_request`, `web_search`, `draft_project_proposal`) and every applicable pre-execution gate. QA v0 Git evidence remains unavailable without an approval. Tools-disabled Agent Preset snapshots remain non-approvable hard denials and skip the redundant network pre-execution gate. |

`browser_inspect` and `browser_flow` are not approval-policy values. Every
otherwise-permitted browser call is approval-gated independently, including
when this variable is empty or lacks `all_tools`. A flow approval includes the
complete ordered action list because scripts, same-origin `GET`/`HEAD`
requests, and approved clicks may change the application. Unknown policy names
are rejected at startup with a clear error. Empty value disables every listed
gate (use only in trusted environments). For per-MCP-server gating in
`agent_loop` runs, see
`approval_policy` on `mcp_servers` entries in
[`mcp.md#approval-policy`](mcp.md#approval-policy). Eligible
Work-policy-backed native Tasks—including standalone Tasks, project
assignments, and tools-on Hecate Chat backing Tasks with an explicit frozen
posture—may add the Agent Preset layer documented under [Work policy
endpoints](#work-policy-endpoints). It affects only mid-loop tool calls and
never changes these pre-execution gates.

## Event and stream endpoints

### Per-run events

- `GET /hecate/v1/tasks/{id}/runs/{run_id}/events?after_sequence=<n>`
- `POST /hecate/v1/tasks/{id}/runs/{run_id}/events`
- `GET /hecate/v1/tasks/{id}/runs/{run_id}/stream?after_sequence=<n>`

The JSON list returns agent event protocol v1 envelopes:
`schema_version`, `event_id`, `task_id`, `run_id`, `sequence`,
`occurred_at`, `type`, and `data`.

Stream resume also supports `Last-Event-ID`. Each per-run SSE frame carries the
current run state, steps, artifacts, activity, and approvals scoped to that run
so the operator UI can drive approval banners and progress surfaces without a
separate refetch (`TaskRunStreamEventData.Approvals`). The frame's `event_type`
mirrors the persisted event that produced the state refresh.
The frame is a read-time projection over the append-only run-event log and live
run storage. When the stream emits a projected live snapshot without a newer
persisted event, the SSE `id` and `data.sequence` stay on the latest persisted
cursor instead of creating a new `run_event` row.

The frame also includes a normalized `activity` array for clients that want a
coding-agent-style timeline without reconstructing it from raw steps and
artifacts. Activity item types include `thinking`, `tool_call`, `patch`,
`changed_files`, `final_answer`, `project_assistant_proposal`, `approval`, and
`run_result`. Approval
activities carry `approval_id` and `needs_action` when a user decision is
pending. Their `summary` also carries the approval resource's `action_summary`
and `action_summary_incomplete` values; the task-backed Chat projection promotes
those values onto its compact activity record. This lets Task Detail and Chat
show the same ordered review bundle under the same bounded and sanitized
contract described above. Compact clients must not accept inline approval when
the summary is absent or `action_summary_incomplete=true`; they should send the
operator to the backing Task for the fuller review surface.
Policy-denied tool steps are normalized to activity `status=denied`
and carry the operator-facing denial `reason` in their summary, even though the
raw audit step remains `status=completed`, `phase=policy`, `result=denied`. The
operator UI uses this same array in both Task Detail and Hecate
Chat transcript projections; clients should treat it as the compact timeline
surface and use raw steps/artifacts/events only for deeper inspection. Task
Detail may expose the raw `TaskActivityItem` fields behind an advanced
disclosure, but Chats should favor the compact projection. For MCP Apps tool
calls, task-backed chat activities may include `mcp_app` with the captured
`ui://` resource URI, MIME type, HTML, resource/tool metadata, tool arguments,
and MCP `CallToolResult`; clients can render it inline or ignore it and fall
back to the normal text activity.

`mcp_app` is optional and appears only when Hecate could associate a tool call
with an MCP Apps HTML resource:

```json
{
  "resource_uri": "ui://weather/dashboard",
  "mime_type": "text/html;profile=mcp-app",
  "html": "<!doctype html>...",
  "html_truncated": false,
  "tool_name": "mcp__weather__get_weather",
  "tool_input": { "city": "Lisbon" },
  "tool_result": {
    "content": [{ "type": "text", "text": "72F" }],
    "structuredContent": { "temperature": "72F" }
  },
  "resource_meta": {
    "ui": {
      "csp": { "resourceDomains": ["https://cdn.example.com"] },
      "prefersBorder": true
    }
  },
  "tool_meta": {
    "ui": {
      "resourceUri": "ui://weather/dashboard",
      "visibility": ["model", "app"]
    }
  }
}
```

The operator UI renders the iframe directly in the assistant message body and
keeps the normal collapsed activity row below it as audit metadata. `ui://`
values are MCP resource identifiers, not browser URLs; clients that render apps
should treat `html` as the captured resource body and apply their own sandboxing
and CSP policy. If app resource capture fails, `error` may be present and `html`
may be absent.

### Public events feed

For external dashboards (Grafana, Slack notifiers, audit log shippers) that want one subscription instead of per-run polling:

- `GET /hecate/v1/events?event_type=<csv>&task_id=<id>&after_sequence=<n>&limit=<n>` — paginated JSON list with cursor-based pagination
- `GET /hecate/v1/events/stream?event_type=<csv>` — long-lived SSE feed; reconnect via `Last-Event-ID`

Both endpoints emit the same v1 event envelopes as the per-run event list.
Filters AND together; within a slice (`event_type` is comma-separated) the match
is OR. `after_sequence` is the event sequence cursor, strictly greater.

### Event types

The full catalog of event types — including payload shapes, when each fires, and per-event extras — lives in [`events.md`](events.md). Highlights:

- `run.*` lifecycle (`run.created` / `run.queued` / `run.started` / `run.finished` / `run.failed` / `run.cancelled`)
- typed `tool.*` events for in-run tool lifecycle detail
- `approval.requested` / `approval.resolved` for human-gating flows
- `model.call.completed` for per-model-call cost/tokens summaries in `agent_loop` runs
- `run.resumed_from_event` for resume / retry-from-model-call chains

## Queue execution model

When a run is queued, workers consume it through a claim/lease protocol:

1. enqueue `task_id` + `run_id`
2. worker claims with a time-bound lease
3. worker heartbeats to extend lease while work is running
4. worker `ack`s on success/terminal handling or `nack`s to requeue
5. expired leases can be reclaimed by another worker

Scheduled admission happens before this queue protocol. The scheduler polls
for due rows, atomically inserts an occurrence keyed by
`(schedule_id, scheduled_for)`, and advances the Schedule's next time in the
same store transaction. A claim-owner-fenced transition then atomically does
one of three things: returns the Run already linked to that occurrence, records
an active-Run overlap as skipped, or inserts the new Run while projecting its
parent Task, marking the occurrence started, appending `run.created` plus the
initial queued/approval lifecycle events, and creating any required pending
approval. A stale claim is reclaimable after five minutes; a live dispatcher
renews it at no more than one-third of that window while workspace provisioning
is still in progress. Definition edits and claims also compare and advance one
internal Schedule revision, preventing either side from applying a stale
`next_run_at` calculation. Queue insertion is the only post-commit side effect:
it is duplicate-safe, enters targeted reconciliation on failure, and is
covered by boot recovery after a crash. This handoff prevents a second runtime replica
from creating a duplicate Run, reviving a skipped occurrence, stranding an
approval-gated Run, or wedging a consumed Schedule back in the due set.

Before workers start on gateway boot, Hecate scans every durable `queued` or
`running` run in stable id-cursor pages and re-enqueues recoverable work. The
500-row page size bounds each read; it is not a recovery cap. A page failure is
retried, and per-run failures remain in the targeted reconciliation set.

Cancellation first commits the `cancelled` terminal winner so operators see it
without waiting for a slow executor, then cancels and drains every process-local
executor registered for that run. After drain, Hecate reapplies step, streaming
artifact, and pending-approval cleanup without emitting a second
`run.cancelled` event. This final sweep also runs when deletion retries find an
already-cancelled run, preserves any newer run's parent-task projection, and
ensures executor output racing with the first cleanup cannot leave an
actionable approval behind.

```mermaid
sequenceDiagram
    participant Caller
    participant API
    participant Queue
    participant Worker
    participant Store
    Caller->>API: POST /hecate/v1/tasks/:id/start
    API->>Queue: enqueue(task_id, run_id)
    Worker->>Queue: claim(worker_id, lease)
    Queue-->>Worker: claim_id, run_id
    Worker->>Store: set run status=running
    loop while running
      Worker->>Queue: extend_lease(claim_id)
    end
    alt completed
      Worker->>Queue: ack(claim_id)
    else retryable / throttled
      Worker->>Queue: nack(claim_id, reason)
    end
```

## Runtime backend and queue configuration

- `HECATE_BACKEND=memory|sqlite|postgres` controls Hecate-owned durable state
  such as tasks, task schedules and their occurrence ledger, the task queue,
  chats, runtime overlays, usage events, and settings.
- Portable Projects coordination always uses Hecate's embedded Cairnline SQLite store at `{HECATE_DATA_DIR}/cairnline/embedded/projects.db`. There is no Projects backend selector, migration switch, or standalone connector configuration in the current runtime.
- `HECATE_POSTGRES_URL=postgres://...` or `DATABASE_URL=postgres://...` is
  required when `HECATE_BACKEND=postgres`. Optional Postgres knobs:
  `HECATE_POSTGRES_TABLE_PREFIX`, `HECATE_POSTGRES_MAX_OPEN_CONNS`, and
  `HECATE_POSTGRES_MAX_IDLE_CONNS`.
- `HECATE_TASK_QUEUE_WORKERS=<int>`
- `HECATE_TASK_QUEUE_BUFFER=<int>`
- `HECATE_TASK_QUEUE_LEASE_SECONDS=<int>`
- `HECATE_TASK_MAX_CONCURRENT_PER_TENANT=<int>` (`0` disables the limit)
- `HECATE_TASK_RECONCILE_INTERVAL=<duration>` (default `30s`; Go duration string — e.g. `"1m"`; how often the periodic reconciler scans for stalled runs; runs stuck in `running` longer than 3× `HECATE_TASK_QUEUE_LEASE_SECONDS` are automatically re-queued and emit `gap.run_disconnected` with `reason=worker_lease_expired`)
- `HECATE_TASK_MAX_MCP_SERVERS_PER_TASK=<int>` (default `16`; caps `mcp_servers` entries on `agent_loop` task creates; `0` disables the check)
- `HECATE_TASK_MCP_CLIENT_CACHE_MAX_ENTRIES=<int>` (default `256`; soft cap on the gateway-wide MCP client cache; LRU-idle eviction kicks in at the cap, with fail-open when every entry is in use)
- `HECATE_TASK_MCP_CLIENT_CACHE_PING_INTERVAL=<duration>` (default `60s`; how often the cache pings each idle cached upstream to detect wedged subprocesses; `0` disables the proactive health check, leaving only reactive eviction in `Pool.Call`)
- `HECATE_TASK_MCP_CLIENT_CACHE_PING_TIMEOUT=<duration>` (default `5s`; per-ping deadline; failure or timeout evicts the entry)
- `HECATE_TASK_BROWSER_EXECUTABLE=<absolute path>` enables the optional local
  native browser runtime used by static evidence and separately granted
  interaction, overriding the host-scoped selection in Settings. The path must
  name an existing executable; an invalid override fails closed without
  fallback. Empty uses the saved selection, or leaves browser tools disabled
  when none exists. Settings passively discovers supported installations, but
  Hecate never downloads or bundles a browser and neither tool is available in
  remote-runtime mode.
- `HECATE_TASK_BROWSER_TIMEOUT=<duration>` (default `20s`; must be positive
  when the browser runtime is enabled; one deadline spans preflight, startup,
  and the complete capture or interaction flow)
- `HECATE_TASK_BROWSER_ALLOW_PRIVATE_IPS=true|false` (default `false`; opts
  into local/private browser destinations after initial resolution preflight).
  Hecate pins hostname origins to their preflight-selected numeric address for
  the browser call, but this is not an OS-level browser network sandbox or
  egress firewall.

When `HECATE_BACKEND=sqlite` or `postgres`, Tasks, Runs, Schedules, schedule
occurrences, Steps, approvals, artifacts, and Run events are persisted and the
stream replay cursor is durable across restarts. Workers claim queue items with
renewable leases, so pending Runs survive process restarts and can be recovered
when a lease expires. Schedule and occurrence behavior has the same memory,
SQLite, and Postgres contract; memory remains process-lifetime state.

For `agent_loop`-specific knobs (maximum model calls, system-prompt layers, HTTP policy
for the `http_request` tool, optional native `web_search`, and optional local
browser evidence), see [`agent-runtime.md`](agent-runtime.md#configuration-knobs).

`GET /hecate/v1/system/stats` also reports queue health fields including queue depth, queue capacity, worker count, and `queue_backend`.

The response also surfaces `agent_adapter_approval_mode` — the configured mode for the external-agent approval coordinator: `"auto"`, `"prompt"`, or `"deny"`. Operators surface a danger banner in the UI when this is `"auto"` since every agent `RequestPermission` is permitted without review. Empty when the gateway was built without an approval coordinator (legacy configs / test fixtures).

The same payload includes `rtk_available` and optional `rtk_path` so the UI can offer the per-chat **Compact command output** toggle only when the optional `rtk` helper is installed in the gateway process `PATH`. Hecate never enables RTK automatically; new chats default to compact output off.

`GET /hecate/v1/system/mcp/cache` returns a snapshot of the shared MCP client cache:

```json
{
  "object": "mcp_cache_stats",
  "data": {
    "checked_at": "2026-04-29T01:00:00.123Z",
    "configured": true,
    "entries": 4,
    "in_use": 1,
    "idle": 3
  }
}
```

`configured: false` means no cache is wired (the deploy explicitly disabled it via `Handler.SetMCPClientCache(nil)`); the counter fields are present but zero so operator UIs can render a "no cache" cell instead of error-handling. `in_use` is the **sum** of refcounts across all entries (an entry held by two concurrent runs counts as 2), not the number of entries with at least one acquirer; `idle` is the count of entries with refcount=0. See [`mcp.md`](mcp.md#lifecycle-and-caching) for the underlying contract.

`GET /hecate/v1/mcp/registry/servers` searches an MCP Registry server list. It defaults to the official registry at `https://registry.modelcontextprotocol.io`; pass `registry_url` to target a private registry. Supported query parameters mirror the read-only registry API: `search`, `cursor`, `limit` (default 30, capped at 100), `updated_since` (RFC3339), `version`, and `include_deleted`. The endpoint is local-only: non-loopback sockets and forwarded-client headers are rejected before the outbound registry request.

```json
GET /hecate/v1/mcp/registry/servers?search=weather&limit=10

→ 200
{
  "object": "mcp_registry_servers",
  "data": {
    "registry_url": "https://registry.modelcontextprotocol.io",
    "servers": [
      {
        "server": {
          "name": "io.github/example/weather",
          "title": "Weather",
          "description": "Forecasts",
          "version": "1.0.0",
          "remotes": [
            {
              "type": "streamable-http",
              "url": "https://weather.example/mcp",
              "headers": [
                {"name": "Authorization", "isRequired": true, "isSecret": true}
              ]
            }
          ],
          "packages": [
            {
              "registryType": "npm",
              "identifier": "@example/weather",
              "runtimeHint": "npx",
              "transport": {"type": "stdio"}
            }
          ],
          "_meta": {"publisher": "example"}
        },
        "_meta": {"rank": 1},
        "install_hints": [
          {
            "source": "remote",
            "transport": "streamable-http",
            "supported": true,
            "url": "https://weather.example/mcp",
            "required_secrets": ["MCP_AUTHORIZATION"],
            "hecate_config": {
              "name": "weather",
              "url": "https://weather.example/mcp",
              "headers": {"Authorization": "$MCP_AUTHORIZATION"}
            }
          },
          {
            "source": "package",
            "transport": "stdio",
            "supported": false,
            "registry_type": "npm",
            "identifier": "@example/weather",
            "runtime_hint": "npx",
            "unsupported_reason": "package entries require an operator-chosen local runtime command before Hecate can probe them"
          }
        ]
      }
    ],
    "next_cursor": "cursor-2",
    "count": 1
  }
}
```

Registry discovery does not install packages, spawn servers, or call `tools/list`; it only returns catalog metadata and Hecate-specific connection hints. Use `POST /hecate/v1/mcp/probe` on a selected config to inspect the live tool catalog before committing it to a task.

`POST /hecate/v1/mcp/probe` is the dry-run discovery surface for an MCP server config. It accepts a single MCP server entry (same shape as one item in the task-create `mcp_servers` array — `name` defaults to `probe` when omitted), brings the server up the way an `agent_loop` run would (same secret resolution, same uncached spawn path), calls `tools/list`, and tears it down. Returns the upstream's initialize `serverInfo` plus tool catalog so operators can confirm the config before committing it to a task. The endpoint is local-only: non-loopback sockets and forwarded-client headers are rejected before command handling.

```json
POST /hecate/v1/mcp/probe
{
  "command": "bunx",
  "args": ["--bun", "@modelcontextprotocol/server-filesystem", "/workspace"]
}

→ 200
{
  "object": "mcp_probe",
  "data": {
    "server_name": "filesystem",
    "server_version": "0.6.2",
    "tools": [
      {
        "name": "get_weather",
        "description": "...",
        "input_schema": {...},
        "_meta": {
          "ui": {
            "resourceUri": "ui://weather/dashboard",
            "visibility": ["model", "app"]
          }
        },
        "ui_resource_uri": "ui://weather/dashboard",
        "ui_visibility": ["model", "app"],
        "model_visible": true
      },
      {
        "name": "refresh_dashboard",
        "input_schema": {...},
        "_meta": {
          "ui": {
            "resourceUri": "ui://weather/dashboard",
            "visibility": ["app"]
          }
        },
        "ui_resource_uri": "ui://weather/dashboard",
        "ui_visibility": ["app"],
        "model_visible": false
      }
    ]
  }
}
```

Tool names come back un-namespaced — the operator wants to see what the upstream itself calls them, not the gateway's runtime alias. MCP Apps metadata is preserved when present: `_meta` is the raw upstream object, `ui_resource_uri` and `ui_visibility` are derived convenience fields, and `model_visible: false` means the tool is app-only and will not be shown to the agent-loop model. Bounded by a 10-second deadline; a stuck upstream surfaces as a 400 with the diagnostic rather than wedging the request.

`POST /hecate/v1/system/reset-data` is reserved but intentionally unavailable.
The running process cannot yet prove that task workers/reconcilers, retention,
External Agent callbacks, gateway finalizers, and writer-capable Cairnline opens
have all stopped. It therefore returns a stable `409 conflict` before acquiring
a mutation fence or deleting any state; it never reports a partial reset as
successful.

```json
→ 409
{
  "error": {
    "type": "conflict",
    "message": "in-process data reset is unavailable until runtime-wide write quiescence is implemented; stop the runtime before clearing its configured state",
    "user_message": "In-process data reset is unavailable.",
    "operator_action": "Stop the runtime completely, then follow the deployment-specific state reset procedure."
  }
}
```

The route remains local-only and blocked in remote runtime mode: non-loopback
sockets and forwarded-client headers are rejected before this response. Stop
Hecate completely and follow the deployment-specific procedure: SQLite-backed
deployments clear the configured data directory, while Postgres deployments
must clear their configured database state plus any local Cairnline/bootstrap
files they intend to reset. Restarting a memory-backed runtime clears only
Hecate-owned in-memory state; embedded Cairnline Projects remain persistent
until their stopped-runtime data is cleared. Do not remove a live
SQLite/Cairnline data directory or treat this endpoint as a shutdown request.

`POST /hecate/v1/system/shutdown` requests an orderly process shutdown. The desktop app uses this from its explicit Quit flow, and from the safe fallback when background mode is unavailable, so the gateway runs the same drain path `SIGINT`/`SIGTERM` take instead of being SIGKILL'd by the child-process handle. The task runner, External Agent sessions, and operator terminals begin draining concurrently within the bounded shutdown window; new terminal admission is fenced immediately, while each terminal watcher retains its workspace writer lease until process exit and output drain are observed. The MCP cache closes after the task runner returns, then the HTTP server drains. Empty body, returns `202` and an `object: "system_shutdown"` ack; the signal fires asynchronously after a short delay so the response can flush before the listener tears down. Clients that need to observe the gateway actually exiting should poll `/healthz` until it stops responding (the desktop app uses a 12-second deadline). The endpoint is local-only: non-loopback sockets and forwarded-client headers are rejected.

The shipped `cmd/hecate` binary wires `Handler.SetQuitFunc` unconditionally, so the endpoint is available in every standard deployment (Tauri sidecar, Docker, systemd) from the gateway's local network namespace. In Docker, call it from inside the container or use the normal orchestrator stop path (`docker stop`, Compose, systemd, Kubernetes); requests through a published port usually arrive from a non-loopback bridge address and are rejected. Returns `503` with `error.code = "gateway_error"` when the endpoint is not wired; this path is reached only by test harnesses or custom embedders that build a `Handler` without calling `SetQuitFunc`.

## Usage endpoints

Hecate records usage for operator visibility, not global spend enforcement.
Cloud-provider calls may include measured tokens and known or provider-reported
cost. Local-provider rows are still recorded as usage events, but the Usage UI
hides them from the cloud-spend table because they do not consume cloud-provider
tokens. External-agent usage remains agent-reported and is surfaced on chat
messages when the agent provides it.

### `GET /hecate/v1/usage/summary`

Returns the cumulative known/reported spend for a usage bucket. In the local
single-operator shape, clients usually call this without query parameters and
read the global bucket.

Query parameters:

| Name       | Meaning                                                                   |
| ---------- | ------------------------------------------------------------------------- |
| `scope`    | `global` (default) or `provider`. Unknown values fall back to `global`.   |
| `provider` | Provider id when `scope=provider`.                                        |
| `key`      | Explicit internal usage key. Intended for diagnostics, not normal UI use. |

```json
GET /hecate/v1/usage/summary
→ 200
{
  "object": "usage_summary",
  "data": {
    "key": "global",
    "scope": "global",
    "backend": "sqlite",
    "used_micros_usd": 1600,
    "used_usd": "$0.001600"
  }
}
```

### `GET /hecate/v1/usage/events`

Returns recent append-only usage rows, newest first. The UI uses these rows to
show cloud-provider tokens and known/reported cost. The endpoint is intentionally
read-only.

Query parameters:

| Name    | Meaning                                                                 |
| ------- | ----------------------------------------------------------------------- |
| `limit` | Maximum rows to return. Defaults to the configured usage history limit. |

```json
GET /hecate/v1/usage/events?limit=20
→ 200
{
  "object": "usage_events",
  "data": [
    {
      "type": "usage",
      "scope": "provider",
      "provider": "openai",
      "model": "gpt-5.4-mini",
      "request_id": "req_...",
      "amount_micros_usd": 1600,
      "amount_usd": "$0.001600",
      "prompt_tokens": 920,
      "completion_tokens": 280,
      "total_tokens": 1200,
      "timestamp": "2026-05-14T10:00:00Z"
    }
  ]
}
```

## Health and discovery endpoints

### `GET /healthz`

Liveness probe. Returns `200` with the gateway's current time and version. Suitable for sidecar health checks, Kubernetes `livenessProbe` / `readinessProbe`, and Docker Compose `healthcheck`.

```json
GET /healthz
→ 200
{
  "status": "ok",
  "time": "2026-04-29T12:34:56Z",
  "version": "0.0.0-dev"
}
```

The endpoint is intentionally cheap: it doesn't touch the database, providers, or queue. A `200` here means "the process is up and serving HTTP," not "every backend is healthy." For deeper signal use `GET /hecate/v1/system/stats`.

### `GET /hecate/v1/providers/presets`

Provider catalog the UI's task-create form uses to render the provider picker. Each entry carries the operator-facing display name, the kind (`cloud` / `local`), the protocol Hecate speaks to it, the `BASE_URL` / `API_KEY` env-var pattern (so the UI can show which `PROVIDER_<NAME>_*` variables to set), and a short `env_snippet` ready to paste into `.env`.

```json
GET /hecate/v1/providers/presets
→ 200
{
  "object": "provider_presets",
  "data": [
    {
      "id": "openai",
      "name": "OpenAI",
      "kind": "cloud",
      "protocol": "openai",
      "base_url": "https://api.openai.com/v1",
      "api_key_env": "OPENAI_API_KEY",
      "docs_url": "https://platform.openai.com/docs",
      "description": "OpenAI's Responses + Chat Completions API.",
      "env_snippet": "OPENAI_API_KEY=your_api_key_here"
    },
    ...
  ]
}
```

The list is built from `config.BuiltInProviders()` — see [`docs/operator/providers.md`](../operator/providers.md) for the full catalog and OpenAI-compatible custom-endpoint flow.

### `GET /hecate/v1/providers/status`

Runtime provider readiness snapshot. The UI uses this endpoint to explain
whether a configured provider can receive traffic right now and why it may be
skipped by routing.

Pass `refresh=true` or `refresh=1` when the operator explicitly asks to
refresh provider discovery. Normal reads keep using the provider capability
cache; explicit refresh bypasses the completed cache while still sharing any
same-provider discovery request already in flight.

```json
GET /hecate/v1/providers/status
→ 200
{
  "object": "provider_status",
  "data": [
    {
      "name": "ollama",
      "kind": "local",
      "status": "healthy",
      "healthy": true,
      "base_url": "http://127.0.0.1:11434/v1",
      "models": ["llama3.1:8b"],
      "model_count": 1,
      "credential_state": "not_required",
      "credential_ready": true,
      "routing_ready": true,
      "auto_route_ready": true,
      "readiness": {
        "status": "ok",
        "reason": "ready",
        "message": "Provider \"ollama\" is ready for routing."
      },
      "readiness_checks": [
        {
          "name": "credentials",
          "status": "ok",
          "reason": "not_required",
          "message": "No credentials are required for this provider."
        },
        {
          "name": "models",
          "status": "ok",
          "reason": "models_discovered",
          "message": "1 model discovered."
        },
        {
          "name": "health",
          "status": "ok",
          "reason": "healthy",
          "message": "Provider health checks are passing."
        },
        {
          "name": "routing",
          "status": "ok",
          "reason": "routable",
          "message": "Provider is eligible for routing."
        }
      ]
    }
  ]
}
```

`readiness` is the compact provider-level answer for cards and tables:
`status` is `ok`, `warning`, `blocked`, or `unknown`; `reason` is stable enough
for UI branching; `message` is safe to show directly to the operator; and
`operator_action` appears when there is a repair step.

`readiness_checks` is the canonical operator-facing checklist. It prevents
clients from guessing readiness by combining unrelated raw fields. Check names
are currently `credentials`, `models`, `health`, and `routing`; statuses use the
same `ok` / `warning` / `blocked` / `unknown` set. `reason` is stable enough for
UI branching, while `message` is safe to show directly to the operator.
When a check needs operator action, `operator_action` carries the canonical
repair step; clients should prefer it over deriving their own copy from
`reason`. For example `credential_missing` includes "add or rotate
credentials", `no_models` includes "start the provider and load at least one
model", and `provider_rate_limited` includes "wait for cooldown or route
elsewhere".

`routing_ready=false` means the router currently skips the provider.
`auto_route_ready=true` means an unpinned, model-less Hecate request can use
this provider through its configured provider default or a matching gateway
default; it does not select the provider or model. The
matching `routing_blocked_reason` and the `reason` on the
`readiness_checks[]` item whose `name` is `routing` use the same vocabulary as
route diagnostics: `credential_missing`, `provider_disabled`,
`provider_rate_limited`, `circuit_open`, `provider_unhealthy`, and `no_models`.
Other checks use reason values scoped to that check, such as
`default_model_only` for model-discovery fallback, `discovery_failed` when the
provider could not return a model list, `self_referential` when a provider URL
points back to Hecate, `provider_slow` when a latency-degraded provider remains
routable, or `not_required` for local providers that do not need credentials.

The trace inspector reuses the same vocabulary in route candidates. A selected
candidate is paired with the route reason (`requested_model`, `pinned_provider`,
`provider_default_model`, etc.); skipped candidates carry `skip_reason` values
such as `policy_denied`, `provider_rate_limited`,
`provider_less_stable`, or `provider_unavailable`. This keeps the operator
debugging path consistent: Connections explains whether a route is possible now,
and Observability explains how a specific request moved through the candidates.

### `GET /hecate/v1/settings`

The settings response includes path-free readiness for the optional native
browser runtime. The existing `browser_evidence` wire field covers both static
evidence and separately granted interaction because one configured runtime
backs both tools. `browser_evidence.available` says whether this gateway can
currently offer that local runtime; `status` is `configured`, `working`,
`not_configured`, `local_only`, or `unavailable`. `configured` is available but
unverified; `working` records a successful approved call for the current
selection in this process. Neither is a capability grant or security verdict.
`message` and optional `operator_action` are safe to display directly. The
response never exposes the configured executable path, local probe diagnostics,
or host filesystem details. Reading readiness never launches the browser.

```json
{
  "object": "settings",
  "data": {
    "browser_evidence": {
      "available": false,
      "status": "not_configured",
      "message": "Choose and enable an installed browser to use browser tools.",
      "operator_action": "Open Settings → Browser setup."
    }
  }
}
```

### `GET`, `PUT`, `DELETE /hecate/v1/settings/browser`

One-time browser setup for a local runtime. These routes are local-only and
require a loopback connection; they are unavailable in remote-runtime mode.
Unlike general Settings readiness, their response contains local installation
paths. Responses use `Cache-Control: private, no-store`. Do not forward those
details to model prompts, logs, or telemetry.

`GET` passively lists supported installed browsers and the current selection.
It does not launch, probe, or automatically enable any candidate. `PUT` accepts
`{"candidate_id":"<id from GET>"}`, rechecks the candidate, and enables that
installation for future eligible calls without restarting Hecate. The id binds
passive path/metadata observations, not executable bytes or publisher identity.
Stale candidates must be refreshed and selected again. There is no Check or
self-test prerequisite; the first successful approved call provides working
evidence. `DELETE` clears the saved choice and blocks future browser admissions;
already-admitted calls are not cancelled.

All three operations return the same envelope:

```json
{
  "object": "browser_settings",
  "data": {
    "readiness": {
      "available": true,
      "status": "configured",
      "message": "Browser enabled. Its first approved use will confirm that it works."
    },
    "source": "settings",
    "selected": {
      "id": "opaque-candidate-id",
      "name": "Google Chrome",
      "path": "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
    },
    "candidates": [
      {
        "id": "opaque-candidate-id",
        "name": "Google Chrome",
        "path": "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
      }
    ],
    "backend": "sqlite"
  }
}
```

`source` is `none`, `settings`, or `environment`; `selected` is omitted when no
selection exists. `backend` identifies `memory`, `sqlite`, or `postgres`. Saved
choices are keyed by runtime host in that backend; memory choices do not survive
restart. Working evidence is never persisted. At each use Hecate revalidates
the selected regular executable and canonical path. Installation metadata
changes clear working evidence, while a changed symlink target requires
reselection. Enabling an installation permits updates at the same path; it does
not checksum-pin the executable or certify it as malware-free.

An explicit `HECATE_TASK_BROWSER_EXECUTABLE` has precedence over saved settings
and makes `PUT`/`DELETE` unavailable. An invalid override fails closed, never
falling back to the saved choice or discovered candidates. Clear the override
and restart Hecate to manage the selection here. Enabling a browser does not
change Work policies: native Tasks and tools-on Chat still need frozen grants,
exact origins, and approval for each browser call.

`PUT` accepts one strict JSON object up to 4 KiB; malformed, empty, or unknown
fields return `400 invalid_request`. A changed or missing candidate returns
`409 browser.candidate_changed`; an environment-managed mutation returns
`409 browser.environment_managed`. Non-loopback clients and remote runtime
receive `403`. A settings read/write failure returns a fixed path-free `500`
message; refresh before retrying because a write may have completed before a
response failed.

### `GET /hecate/v1/settings/providers/local-discovery`

Advisory discovery for the Connections view's **Add provider → Local** catalog.
The gateway checks whether the expected provider command is on `PATH` and
probes each unique default local endpoint once. Shared endpoints, such as the
`llama.cpp` / `LocalAI` default `127.0.0.1:8080/v1`, are only called once and
then reused for every matching preset card.

This endpoint is local-only and returns `403` in remote runtime mode. Hosted
runtimes also disable local provider presets and `kind=local` providers unless
launched with `HECATE_REMOTE_ALLOW_LOCAL_PROVIDERS=1`.

```json
GET /hecate/v1/settings/providers/local-discovery
→ 200
{
  "object": "local_provider_discovery",
  "data": [
    {
      "preset_id": "ollama",
      "name": "Ollama",
      "base_url": "http://127.0.0.1:11434/v1",
      "probe_url": "http://127.0.0.1:11434/api/tags",
      "status": "running",
      "command": "ollama",
      "command_available": true,
      "command_path": "/opt/homebrew/bin/ollama",
      "http_available": true,
      "model_count": 2,
      "models": ["llama3.1:8b", "qwen2.5:7b"]
    }
  ]
}
```

`status` is one of:

- `running` — the HTTP probe returned 2xx.
- `installed` — the command is present on `PATH`, but the default HTTP
  endpoint did not respond.
- `not_detected` — neither the command nor the default HTTP endpoint was found.

This endpoint does not create or mutate provider records. It is a UX helper for
the picker and is local-only: non-loopback sockets, forwarded-client headers,
and remote runtime mode are rejected. Routing readiness still comes from
`GET /hecate/v1/providers/status` after the operator adds a provider.

### `GET /v1/models`

Lists models currently known to configured providers. Each row includes Hecate
metadata under `metadata`, including the effective model capability snapshot
used by the Chats target picker.

Pass `refresh=true` or `refresh=1` for an explicit operator refresh. Without
that query parameter, the endpoint keeps normal provider discovery cache
behavior.

```json
GET /v1/models
→ 200
{
  "object": "list",
  "data": [
    {
      "id": "vision-model:latest",
      "object": "model",
      "owned_by": "ollama",
      "metadata": {
        "provider": "ollama",
        "provider_kind": "local",
        "default": false,
        "discovery_source": "provider",
        "capabilities": {
          "tool_calling": "unknown",
          "image_input": "supported",
          "streaming": true,
          "max_context_tokens": 32768,
          "source": "provider"
        },
        "readiness": {
          "provider": "ollama",
          "matched_provider": "ollama",
          "model": "vision-model:latest",
          "ready": true,
          "status": "ok",
          "reason": "model_available",
          "message": "Provider \"ollama\" reports model \"vision-model:latest\".",
          "routing_ready": true,
          "provider_status": "healthy"
        }
      }
    }
  ]
}
```

`capabilities.tool_calling` is one of `unknown`, `none`, `basic`, or
`parallel`. Task-backed Hecate Chat requires a known tool-capable value
(`basic` or `parallel`). When tools are on but the selected model is
`unknown` or `none`, the operator UI keeps normal chat available by sending the
turn as direct model chat and showing a compact capability hint. Local/custom
OpenAI-compatible providers often report `unknown`; Ollama models are enriched
from the native `/api/show` capability list when available. Tool usage is a
per-chat setting; model capability metadata is observed from provider/catalog
data rather than edited globally. An optional
`capabilities.tool_verification` records a manual, safe observation for an
otherwise unknown model:

```json
{
  "status": "supported",
  "checked_at": "2026-07-21T12:00:00Z",
  "expires_at": "2026-08-20T12:00:00Z"
}
```

`status` is `testing`, `supported`, `unsupported`, or `inconclusive`.
`reason`, when present, is a bounded diagnostic classification rather than raw
provider output. For an otherwise unknown effective capability, `supported`
projects `tool_calling` to `basic`, and an explicit tool-schema rejection
projects it to `none`; `testing` and `inconclusive` leave it `unknown`.
Provider-native and catalog-known values stay authoritative, so a verification
never overrides an effective `none`, `basic`, or `parallel` value. The opaque
provider configuration identity that binds this observation is intentionally
not exposed here.

`capabilities.image_input` is one of `unknown`, `none`, or `supported`.
Image-bearing Hecate Chat turns require `supported`; both `unknown` and `none`
fail closed. Provider-native Fireworks and Ollama metadata override static
catalog inference when available. `capabilities.source` is `catalog`,
`provider`, `mixed`, or `unknown`; provider model discovery alone does not make
catalog-inferred capabilities provider-native, and `mixed` identifies a
snapshot whose dimensions came from both sources. For Auto, the pre-route
snapshot exposes only guarantees shared by routable matching routes; completed
direct turns replace it with the actual route's provider/model capability
snapshot.

Hecate image-bearing attachment turns set an internal image-input requirement. The router
admits only an initial route with explicit support. Any request that actually
contains hydrated file bytes (images or UTF-8 text) is bound to that provider name and opaque
configuration generation: same-instance retries remain available, but
cross-provider failover is disabled. The executor revalidates both values
against the live registry immediately before dispatch, so removal, alias
reassignment, or same-name provider replacement fails closed. Legacy history
without a generation is omitted. The generation is internal-only and is never
accepted from clients or rendered in model/chat responses, errors, logs, or
telemetry. Failed calls retain attempted provider/model and trace metadata when
the provider received the request.

For every task-backed Hecate Chat tools-on turn, a current
`tool_verification.status` of `supported` can satisfy an otherwise-unknown tool
requirement only through the same exact provider/model/generation fence before
the proof expires. An image-bearing turn still independently requires image
support. The proof does not permit a different provider, make an Auto route
eligible, or survive a policy model rewrite. Hecate rechecks those fences at
every final dispatch, including a queued run, retry, or delayed stream.
Ordinary
provider-compatible `/v1/chat/completions` and `/v1/messages` rich-content
requests do not opt into this Hecate runtime requirement and preserve upstream
passthrough for custom providers whose discovery metadata is incomplete. They
still disable cross-provider failover whenever normalized content contains an
image, so a retryable failure cannot disclose that image to a second configured
provider; same-provider retries remain available. Their encoded JSON body is
limited to 32 MiB and must finish arriving within 60 seconds.

`metadata.readiness` is the backend-owned provider/model readiness snapshot for
that discovered row. Chats should use it before sending instead of inferring
routability from model names alone: a model can appear in discovery while its
provider is credential-blocked, circuit-open, disabled, or otherwise not
routable. When `ready=false`, show `message` and `operator_action` directly and
use `reason`, `provider_status`, `provider_blocked_reason`, and
`suggested_models` for compact diagnostics.

### `POST /hecate/v1/model-capabilities/tool-probes`

Performs an explicit, bounded verification of tool support for one configured,
routable provider/model route. This is the API behind **Connections → Verify
tool support**. It accepts neither Auto routing nor a workspace, prompt,
attachment, tool definition, or provider generation from the caller.

```json
POST /hecate/v1/model-capabilities/tool-probes
{
  "provider": "local-runtime",
  "model": "custom-tool-model"
}

→ 200
{
  "object": "model_tool_capability_probe",
  "data": {
    "provider": "local-runtime",
    "model": "custom-tool-model",
    "capabilities": {
      "tool_calling": "basic",
      "source": "mixed",
      "tool_verification": {
        "status": "supported",
        "checked_at": "2026-07-21T12:00:00Z",
        "expires_at": "2026-08-20T12:00:00Z"
      }
    },
    "verification": {
      "status": "supported",
      "checked_at": "2026-07-21T12:00:00Z",
      "expires_at": "2026-08-20T12:00:00Z"
    },
    "trace_id": "trace_...",
    "performed": true
  }
}
```

Hecate itself supplies one static one-message request, one harmless forced
function schema, and the exact configured provider/model route. It observes a
returned call to that function but never parses or executes its arguments,
starts a task, or accesses a workspace, Chat content, attachment, or ACP
session. The request makes no provider retry or failover attempt. It can incur
the selected provider's normal model-request charge.

Hecate persists only the safe verification status, times, and bounded reason;
it does not retain the static prompt, model response, tool arguments, provider
endpoint, opaque provider identity, or credentials in the API result or
verification record. A matching active result is reused, and concurrent
requests coalesce, so `performed=false` means this response reused a current
result or the model already had a known capability rather than sending another
provider request. Reconfiguring or replacing the provider makes prior
verification inapplicable.

The endpoint is limited to models whose current effective `tool_calling` value
is `unknown`. Known provider/catalog values are returned unchanged without a
probe. A `supported` result makes only that unknown capability eligible as
`basic`; an explicit tool-schema rejection makes it `none`; all other failures
are `inconclusive` and leave it `unknown`.

- `400 invalid_request` — provider or model is missing, or `provider` is
  `auto`.
- `409 provider_ambiguous` or `model_not_configured` — the provider identity is
  ambiguous, the model is not ready, or the exact route changed during the
  verification.
- `503 model_tool_probe_unavailable` — this runtime cannot perform the
  verification.

### `GET /hecate/v1/agent-adapters`

External coding-agent catalog. This is the first discovery surface for
External Agent chats: it reports the agent runtimes Hecate knows how to
supervise and whether their command can be found. This endpoint is deliberately
passive so the app can render startup state without spawning coding-agent CLIs.
It also measures the current executable identity without executing it. An
eligible discovered command is **Available**, but cannot run until the operator
approves that exact identity. The catalog does not claim that auth, ACP
initialization, publisher identity, or the app's behavior is trustworthy.
Connections does not probe on open; an explicit **Check** may execute an
approved app to refresh live version, auth, capability, and launch-control
details, but it does not create a durable chat or authorize a later launch.

Discovery checks the Hecate process's `PATH` followed by allowlisted standard
vendor, Homebrew, Volta, npm, pnpm, and WinGet locations for the selected
adapter. Environment-derived roots must be absolute. The returned `path` is the
absolute invocation path Hecate selected. If it is a symlink, Hecate validates
the canonical target but preserves the invocation path for version-manager
`argv[0]` dispatch. Discovery performs path and regular-file checks, opens and
hashes the canonical target, then rechecks its file identity and selected path.
It does not run the launcher. An unavailable adapter row means the command was
absent from both `PATH` and the recognized locations or its launcher form was
rejected. A measurement failure instead appears as
`executable_trust.state="unavailable"` on an otherwise discovered row.

On Windows, every external-agent provider selects only native `.exe` files.
Hecate rejects `.cmd`, `.bat`, `.ps1`, and other launchers instead of invoking a
command shell and accepting an unmeasured wrapper/interpreter chain. Native
direct peers start suspended and enter Hecate's kill-on-close Job Object before
provider code runs. A rejected launcher does not prevent discovery from
continuing to a recognized native installation. The current Cursor Windows CLI
is wrapper-only and therefore not yet supported.

```json
GET /hecate/v1/agent-adapters
→ 200
{
  "object": "agent_adapters",
  "data": [
    {
      "id": "codex",
      "name": "Codex",
      "kind": "acp",
      "command": "codex",
      "embedded": true,
      "available": true,
      "status": "available",
      "path": "/Users/alice/.local/bin/codex",
      "executable_trust": {
        "schema_version": "hecate.external-agent-executable.v1",
        "state": "unapproved",
        "reason": "approval_required",
        "current": {
          "schema_version": "hecate.external-agent-executable.v1",
          "identity_token": "sha256:7df96b45fd44c69ebcd96d93f34c92aa5c978b21dc1e7ca1b5cc3775d09ed843",
          "invocation_path": "/Users/alice/.local/bin/codex",
          "canonical_path": "/Users/alice/.local/bin/codex",
          "sha256": "5c68f775eb44c4ff87caeea1b0409b850ef3cae109b161083225f352f11796e1",
          "coverage": "binary",
          "file_id": "unix:16777233:88021719",
          "mode": 493,
          "size_bytes": 42177312,
          "publisher": {
            "status": "unavailable",
            "platform": "darwin"
          }
        }
      },
      "cost_mode": "external",
      "supported_range": ">=0.1.0",
      "version_outside_range": false,
      "supports_authenticate": true,
      "supports_logout": true,
      "auth_status": "unknown",
      "capabilities": [
        {
          "id": "prompt_session",
          "name": "sessions",
          "status": "supported"
        },
        {
          "id": "permissions",
          "name": "permissions",
          "status": "supported"
        },
        {
          "id": "terminal_rpc",
          "name": "terminal RPC",
          "status": "operator_opt_in"
        }
      ],
      "credential_modes": [
        {
          "id": "local_login",
          "name": "Local CLI login",
          "remote_allowed": false
        },
        {
          "id": "api_key",
          "name": "API key",
          "remote_allowed": true,
          "env_keys": ["OPENAI_API_KEY", "CODEX_API_KEY"]
        }
      ]
    },
    {
      "id": "grok_build",
      "name": "Grok Build",
      "kind": "acp",
      "command": "grok",
      "args": ["agent", "stdio"],
      "available": true,
      "status": "available",
      "path": "/Users/alice/.local/bin/grok",
      "cost_mode": "external",
      "docs_url": "https://docs.x.ai/build/cli/headless-scripting#acp",
      "supported_range": ">=0.1.0",
      "supports_authenticate": false,
      "supports_logout": false,
      "auth_status": "unknown"
    },
    {
      "id": "cursor_agent",
      "name": "Cursor Agent",
      "kind": "acp",
      "command": "cursor-agent",
      "args": ["acp"],
      "available": true,
      "status": "available",
      "path": "/Users/alice/.local/bin/cursor-agent",
      "cost_mode": "external",
      "supported_range": ">=0.1.0",
      "version_outside_range": false,
      "supports_authenticate": false,
      "supports_logout": false,
      "auth_status": "unknown"
    },
    {
      "id": "claude_code",
      "name": "Claude Code",
      "kind": "acp",
      "command": "claude",
      "embedded": true,
      "available": false,
      "status": "missing",
      "error": "exec: \"claude\": executable file not found in $PATH",
      "cost_mode": "external",
      "supported_range": ">=0.1.0",
      "supports_authenticate": true,
      "supports_logout": true,
      "auth_status": "unknown",
      "capabilities": [
        {
          "id": "prompt_session",
          "name": "sessions",
          "status": "supported"
        },
        {
          "id": "permissions",
          "name": "permissions",
          "status": "supported"
        },
        {
          "id": "terminal_rpc",
          "name": "terminal RPC",
          "status": "operator_opt_in"
        }
      ],
      "claude_code_cli": {
        "available": true,
        "command": "/Users/alice/.local/bin/claude",
        "executable_path": "/Users/alice/.local/bin/claude"
      }
    }
  ]
}
```

For readability, the example expands `executable_trust` only on the first row.
The shipped runtime returns that object for every registered adapter row,
including `state="unavailable"` when no current identity can be measured.

`adapter_version` and `agent_version` are omitted from the catalog response.
They are populated by the Connections check after Hecate starts the ACP adapter.
`version_outside_range` remains `false` until a checked version is known to fall
outside `supported_range`.

`embedded=true` means the ACP server implementation is compiled into Hecate;
`command` and `path` then identify the vendor CLI that implementation launches.
When `embedded=false`, `command`, `args`, and `path` identify the direct ACP
process Hecate supervises.

`executable_trust.state` is `unavailable`, `unapproved`, `approved`, or
`changed`. `current` is the identity Hecate just measured; `approved` is the
stored identity and remains present when the current app is unavailable or has
changed. An identity includes the invocation path, canonical path, bytes'
SHA-256, file id, file mode and size, coverage, launcher chain when present, and publisher
evidence. V1 always reports publisher evidence as `status="unavailable"`.
`mode` is the unsigned Go `os.FileMode` bitset captured at measurement time;
its low nine bits are the familiar Unix permission bits, while special mode
bits also participate in the opaque identity token.
`coverage="binary"` covers the selected native executable bytes;
`launcher_only` covers only the measured wrapper, not every interpreter or
downstream program it can dispatch. Neither state nor approval is a malware or
safety claim.

Approvals are keyed by runtime host plus adapter. They use the configured chat
storage backend: memory approvals end with the process, while SQLite and
Postgres approvals persist. Every process-start path remeasures and compares
the identity, including probe/version/auth/help/model diagnostics, direct ACP
session startup, and provider commands spawned later by embedded adapters.
Revocation blocks future launches but does not terminate an already-running
direct ACP process.

`auth_status` is `unknown` on the passive catalog path unless a dev or remote
runtime override can classify it without spawning a CLI. **New chat** prepares
the fresh ACP session. An embedded bridge may run bounded provider discovery
during setup; the first message checks prompt-time auth when the bridge defers
its prompt-serving vendor invocation. An explicit Connections **Check** calls
`POST /hecate/v1/agent-adapters/{id}/probe`; **Check again** repeats that
standalone login / billing check. Do not infer verified vendor auth
from `health.status=ready` alone.

`supports_authenticate` and `supports_logout` tell clients whether Hecate can
call ACP `authenticate` or `logout` for this adapter. UIs should use these
catalog fields instead of hard-coding adapter IDs; the actions are currently
enabled for the built-in Go Codex and Claude Code adapters.

`capabilities` is Hecate's catalog-level ACP contract for the row. It describes
the features Hecate knows how to supervise for that adapter family, such as
sessions, structured activity, cancellation, permission approvals, MCP server
handoff, config options, terminal callbacks, authenticate, and logout. Capability
`status` is one of:

| Status              | Meaning                                                                   |
| ------------------- | ------------------------------------------------------------------------- |
| `supported`         | Hecate supports the surface for this adapter family.                      |
| `adapter_dependent` | Hecate will use the surface only when the live ACP adapter advertises it. |
| `operator_opt_in`   | Hecate supports the surface only behind an explicit operator setting.     |
| `not_supported`     | Hecate should not show or invoke this surface.                            |

Check results describe the live ACP `Initialize` features of the disposable
session they created. For example, a check can turn
`supports_authenticate` or `supports_logout` off for its result even when the
catalog expected them. It does not authorize or block a later chat; the real
session's fresh initialization is authoritative for that session.

`credential_modes` describes how the adapter can authenticate. `local_login`
means operator-local CLI/browser login state and is not sufficient for remote
runtime requests by default. Remote runtime mode normally accepts only rows where
`remote_allowed=true` and one listed `env_keys` value is present in the runtime
environment. A single-user personal remote runtime may opt into runtime-local
login state with `HECATE_PERSONAL_REMOTE_EXTERNAL_AGENT_LOGINS=1`; then
`remote_credential_mode` may report `local_login`, but the `hecate_remote` build
tag still strips local-login modes entirely. In remote runtime mode, catalog rows
include `remote_credential_mode`, `remote_credential_ok`, and
`remote_credential_hint` when applicable; adapters without allowed credentials
are reported as `available=false`, `auth_status="unauthenticated"` before
Hecate attempts command discovery.

These are **external agents**, not model providers. They run ACP-compatible
coding agents under Hecate supervision; cost is reported as `external`
until an agent can supply structured usage.

ACP terminal callbacks are not advertised by default. Operators must set
`HECATE_AGENT_ADAPTER_TERMINALS=1` before External Agent sessions include
`clientCapabilities.terminal=true`; remote runtime mode also requires
`HECATE_REMOTE_ALLOW_ACP_TERMINALS=1`. Approved `terminal/create` requests are
scoped to the selected workspace and routed through the External Agent approval
coordinator before command spawn. Each live terminal retains its own shared
workspace writer admission after the creating turn settles and releases it only
after its Unix process group or Windows Job Object and output pipes are observed
drained, so current-workspace discard returns `409` while an ACP terminal can
still write. Unix requests that statically use known session/process-group
detachers are rejected before spawn; interactive shell/interpreter code receives
the same best-effort check on input. Explicit shell stdin and force-interactive
interpreter modes remain code-scanned; ordinary script and inline-command stdin
is data. Shell writes may retain up to 64 KiB of syntactically incomplete input
before failing closed. This is not hard sandboxing of arbitrary wrappers,
generated code, custom binaries, or external supervisors.

`config_options` are omitted from the passive catalog response. Hecate returns
Hecate-managed launch controls on explicit Connections check projections and
returns agent-owned controls on prepared chat sessions, where it is acceptable
to run the adapter's help/model discovery or consume the ACP session's own controls.
Values prefixed with `__hecate_no_` are explicit "not selected" sentinels. No
current built-in requires a pre-session launch control. The request validator
can return `400 chat.model_required` for a registered required launch option,
but a built-in must not introduce one until Hecate exposes its schema through a
passive endpoint; a completed Connections check cannot be a prerequisite for use.
Agent-owned ACP model state appears on the prepared chat session and is updated
with ACP `session/set_model`.

### `PUT /hecate/v1/agent-adapters/{id}/executable-trust`

Approves the exact executable identity the operator reviewed in the passive
catalog. The client sends only the opaque current identity token:

```json
PUT /hecate/v1/agent-adapters/codex/executable-trust
{
  "expected_identity": "sha256:7df96b45fd44c69ebcd96d93f34c92aa5c978b21dc1e7ca1b5cc3775d09ed843"
}
→ 200
{
  "object": "agent_adapter_executable_trust",
  "data": {
    "schema_version": "hecate.external-agent-executable.v1",
    "state": "approved",
    "reason": "identity_approved",
    "current": {
      "schema_version": "hecate.external-agent-executable.v1",
      "identity_token": "sha256:7df96b45fd44c69ebcd96d93f34c92aa5c978b21dc1e7ca1b5cc3775d09ed843",
      "invocation_path": "/Users/alice/.local/bin/codex",
      "canonical_path": "/Users/alice/.local/bin/codex",
      "sha256": "5c68f775eb44c4ff87caeea1b0409b850ef3cae109b161083225f352f11796e1",
      "coverage": "binary",
      "file_id": "unix:16777233:88021719",
      "mode": 493,
      "size_bytes": 42177312,
      "publisher": {
        "status": "unavailable",
        "platform": "darwin"
      }
    },
    "approved": {
      "schema_version": "hecate.external-agent-executable.v1",
      "identity_token": "sha256:7df96b45fd44c69ebcd96d93f34c92aa5c978b21dc1e7ca1b5cc3775d09ed843",
      "invocation_path": "/Users/alice/.local/bin/codex",
      "canonical_path": "/Users/alice/.local/bin/codex",
      "sha256": "5c68f775eb44c4ff87caeea1b0409b850ef3cae109b161083225f352f11796e1",
      "coverage": "binary",
      "file_id": "unix:16777233:88021719",
      "mode": 493,
      "size_bytes": 42177312,
      "publisher": {
        "status": "unavailable",
        "platform": "darwin"
      }
    },
    "approved_by": "operator",
    "approved_at": "2026-09-24T10:00:00Z"
  }
}
```

`current` and `approved` use the complete identity shape returned by the
catalog. Hecate never accepts a client-supplied path or digest as observed fact.
It resolves and measures the adapter again while serializing approval against
launches and revocation in the current Hecate process. `expected_identity` is a
compare-and-swap token; if the app changed after the catalog read, approval
fails rather than approving unreviewed bytes. The route is remote-safe after
trusted runtime identity has been established, so it approves the executable on
that supervised runtime host, not on the browser device.

Status codes:

- `200 OK` after persistence, with a freshly re-read trust status. If the
  filesystem changes again immediately afterward, the response can already be
  `changed` or `unavailable`; clients must render the returned state rather than
  assuming `approved`.
- `400 invalid_request` when `expected_identity` is missing or the request JSON
  is invalid.
- `404 not_found` when the adapter id is not registered.
- `409 agent_adapter.executable_identity_changed` when the expected token is
  stale.
- `503 agent_adapter.executable_identity_unavailable` when Hecate cannot
  resolve, measure, or persist the identity.

### `DELETE /hecate/v1/agent-adapters/{id}/executable-trust`

Revokes the runtime-host-and-adapter approval. The operation is idempotent and
returns `204 No Content`. It blocks future process starts, including deferred
provider launches from embedded adapters, but does not terminate an already
running direct ACP peer. Stop or close that session separately when needed.
This route is also remote-safe after trusted runtime identity is established.

Status codes:

- `204 No Content` after the approval is absent.
- `404 not_found` when the adapter id is not registered.
- `503 agent_adapter.executable_identity_unavailable` when the trust store
  cannot revoke the record.

### `POST /hecate/v1/agent-adapters/{id}/probe`

Runs a disposable ACP session check after the app identity has been approved.
Connections calls it only when the operator chooses **Check** or **Check again**.
It re-runs discovery for one adapter, starts a direct peer or embedded bridge,
performs ACP `Initialize`, and creates a temporary session without sending a
prompt. Provider-specific version or auth-status classification may also
execute the discovered app, but an embedded bridge may still defer its
prompt-serving vendor invocation beyond this check. Hecate revalidates the
approved identity immediately before each process start. `data.health` is
evidence from the disposable ACP attempt;
`health.path` is the path that attempt used. `data.adapter` is a separately
re-resolved diagnostic projection that combines full status, versions, launch
controls, and the probe's auth/capability classification. Its `path`, `status`,
or `error` can differ if discovery changes during the request and must not be
treated as process-bound evidence. Hecate's UI then re-reads the passive catalog
with `GET /hecate/v1/agent-adapters` before changing any launch gate or
last-discovered path, so the check itself never becomes launch authority. It
can retain check-only versions, auth/capability evidence, and `config_options`
beside the cached check while replacing launch
availability, status, error, path, and remote-credential fields from the passive
response. Operators can also trigger that passive refresh without starting an
agent.

This endpoint is not required before use and its cached result is never launch
authority. Starting an External Agent chat independently resolves the current
executable, performs a fresh `Initialize`, and creates the real session. Direct
ACP peers start during setup. An embedded bridge may run bounded provider
discovery, while the first message remains authoritative for a prompt-serving
vendor invocation or auth result deferred by that bridge. Clients may expose
**Check again** after a repair and should show the catalog identity before execution.
Treat that path as last-discovered evidence rather than a pinned launch target:
chat creation resolves the executable again.

```json
POST /hecate/v1/agent-adapters/codex/probe
→ 200
{
  "object": "agent_adapter_probe",
  "data": {
    "adapter": {
      "id": "codex",
      "name": "Codex",
      "kind": "acp",
      "command": "codex",
      "embedded": true,
      "available": true,
      "status": "available",
      "supports_authenticate": true,
      "supports_logout": true,
      "auth_status": "unauthenticated",
      "auth_error": "Run codex login, or set OPENAI_API_KEY for the adapter environment."
    },
    "health": {
      "adapter_id": "codex",
      "status": "ready",
      "stage": "ready",
      "capabilities_known": true,
      "supports_authenticate": true,
      "supports_logout": true,
      "supports_load_session": true,
      "auth_methods": [
        {
          "id": "agent-login",
          "kind": "agent",
          "name": "Agent login"
        }
      ],
      "duration_ms": 412
    }
  }
}
```

Status codes:

- `200 OK` when the adapter id is registered; `health.status` carries
  `ready`, `not_installed`, `auth_required`, or `error`.
- `404 not_found` when the adapter id is not registered.
- `409 agent_adapter.executable_trust_required` when no identity is approved.
- `409 agent_adapter.executable_identity_changed` when the current identity no
  longer matches the approval.
- `503 agent_adapter.executable_identity_unavailable` when Hecate cannot
  measure the identity at the launch boundary.

When ACP `Initialize` succeeds, `health.capabilities_known` is true and the
diagnostic response uses the live capabilities advertised by that session to
refresh `data.adapter.supports_authenticate` and
`data.adapter.supports_logout`. Catalog discovery remains the passive fallback
before diagnostics run. Hecate only marks `supports_authenticate` true for ACP
auth method `agent-login`, because that is the method the local
`/authenticate` endpoint invokes. `health.status=ready` means ACP initialization
and temporary session creation completed; it does not itself promote
`data.adapter.auth_status` to `ok` or prove that a deferred prompt-serving
vendor process can authenticate and answer a prompt. Any non-`unknown` auth
classification in `data.adapter` comes from a separate provider-specific
heuristic or status check, not from the ready health status.

The probe creates and immediately abandons a fresh ACP session, so agents that
bill on session creation may record one no-op session per call. Agents that bill
on prompt completion see no prompt from this check.

### `GET /hecate/v1/agent-adapters/{id}/health`

Compatibility read for one adapter's passive discovery state. It performs the
same non-executing path inspection as the catalog and never starts the selected
app. **New chat** re-resolves it and prepares the real ACP session; the first
message checks any deferred prompt-serving vendor invocation and auth. Use the
Connections check or **Check again** for live version, auth classification, and
ACP capabilities. It may execute the selected app, while this read never does.

```json
GET /hecate/v1/agent-adapters/codex/health
→ 200
{
  "object": "agent_adapter_health",
  "data": {
    "adapter_id": "codex",
    "status": "unverified",
    "stage": "lookup",
    "path": "/Users/alice/.local/bin/codex",
    "hint": "App found. Review its current executable approval status in Connections before Hecate runs a check or starts a chat.",
    "supports_authenticate": false,
    "supports_logout": false,
    "supports_load_session": false,
    "duration_ms": 0
  }
}
```

This compatibility response reuses the probe result type. When
`capabilities_known` is absent or false, its false capability fields are zero
values, not claims that the installed app lacks those features.

`status` is one of:

- `unverified` — an eligible app path was found but has not been executed.
- `not_installed` — the command was absent from `PATH` and recognized standard
  locations, or its launcher form was rejected.
- `auth_required` — remote-runtime credential policy blocks discovery before
  execution. Local auth remains intentionally unknown on this passive
  compatibility response. Chat launch, diagnostics, authentication, and logout
  classify only their own attempt or session; they do not mutate later passive
  health reads.

Status codes:

- `200 OK` with the passive classification (`unverified`, `not_installed`, or
  `auth_required`).
- `404 not_found` when the adapter id is not registered.

### `POST /hecate/v1/agent-adapters/{id}/authenticate`

Asks one registered ACP adapter to start its own local login flow. Hecate
starts the adapter runtime, performs ACP `Initialize`, verifies that the adapter
advertised agent auth method id `agent-login`, calls ACP `authenticate` with
that method id, and then stops the runtime. This is an adapter-account
action: it does not create or mutate Hecate chat sessions, approvals, or
transcripts. Remote runtime mode treats this as local-only; hosted deployments
should use the adapter's declared remote-safe env-key credential modes instead.

```json
POST /hecate/v1/agent-adapters/codex/authenticate
→ 200
{
  "object": "agent_adapter_authenticate",
  "data": {
    "adapter_id": "codex",
    "status": "authenticated",
    "method_id": "agent-login",
    "path": "/Users/alice/.local/bin/codex",
    "duration_ms": 328
  }
}
```

Status codes:

- `200 OK` when the adapter accepted ACP `authenticate`.
- `404 not_found` when the adapter id is not registered.
- `409 agent_adapter.executable_trust_required` when no identity is approved.
- `409 agent_adapter.executable_identity_changed` when the current identity no
  longer matches the approval.
- `503 agent_adapter.executable_identity_unavailable` when Hecate cannot
  measure the identity at the launch boundary.
- `502 chat.adapter_unavailable` when the adapter runtime cannot start,
  initialize, does not advertise ACP `agent-login`, or cannot complete ACP
  `authenticate`.

### `POST /hecate/v1/agent-adapters/{id}/logout`

Asks one registered ACP adapter to clear its own account/session state. Hecate
starts the adapter runtime, performs ACP `Initialize`, verifies that the adapter
advertised ACP `auth.logout`, calls ACP `logout`, and then stops the runtime.
This is an adapter-account action: it does not delete Hecate chat
sessions, close live adapter sessions, revoke approvals, or mutate transcripts.

```json
POST /hecate/v1/agent-adapters/codex/logout
→ 200
{
  "object": "agent_adapter_logout",
  "data": {
    "adapter_id": "codex",
    "status": "logged_out",
    "path": "/Users/alice/.local/bin/codex",
    "duration_ms": 328
  }
}
```

Status codes:

- `200 OK` when the adapter accepted ACP `logout`.
- `404 not_found` when the adapter id is not registered.
- `409 agent_adapter.executable_trust_required` when no identity is approved.
- `409 agent_adapter.executable_identity_changed` when the current identity no
  longer matches the approval.
- `503 agent_adapter.executable_identity_unavailable` when Hecate cannot
  measure the identity at the launch boundary.
- `502 chat.adapter_unavailable` when the adapter runtime cannot start,
  initialize, does not advertise ACP `auth.logout`, or cannot complete ACP
  `logout`.

## Plugin registry endpoints

The plugin registry is a local catalog and policy-review surface. Registry rows
store a raw Hecate-native manifest plus normalized capabilities, requested
permissions, auth-binding requests, and validated MCP-server mount candidates.
They do not run plugin code, start MCP servers, mount tools, call external
providers, or grant secrets.
`manifest_digest` is a SHA-256 digest of Hecate's canonicalized manifest JSON,
so semantically equivalent manifests share the same digest even when caller
formatting differs.

The initial routes are local-only in remote-runtime mode:

- `GET /hecate/v1/plugins`
- `GET /hecate/v1/plugins/{id}`
- `POST /hecate/v1/plugins/install-local`
- `PATCH /hecate/v1/plugins/{id}`
- `GET /hecate/v1/plugins/{id}/health`

`POST /hecate/v1/plugins/install-local` accepts either a manifest directly or
an object with `manifest` and optional `source_ref`. The current slice records
the manifest JSON sent by the operator/client; it does not read arbitrary local
paths or execute package lifecycle hooks.

```json
POST /hecate/v1/plugins/install-local
{
  "source_ref": "/plugins/github/plugin.json",
  "manifest": {
    "schema_version": "hecate.plugin.v0",
    "id": "github",
    "name": "GitHub",
    "version": "0.1.0",
    "permissions": ["network:github.com", "secret:github_token"],
    "capabilities": {
      "connectors": [
        {
          "id": "issues",
          "display_name": "Issues",
          "auth": [{ "name": "github_token", "kind": "token" }]
        }
      ],
      "mcp_servers": [
        {
          "id": "github-mcp",
          "name": "github",
          "display_name": "GitHub MCP",
          "transport": "stdio",
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-github"],
          "env": { "GITHUB_TOKEN": "$GITHUB_TOKEN" },
          "approval_policy": "require_approval"
        }
      ],
      "slash_commands": [{ "name": "github" }]
    }
  }
}
```

MCP server capabilities may use the inline shape above or place the same fields
inside `config`. The registry normalizes either shape into an `mcp_server`
response object. Exactly one of `command` or `url` must be set; `transport`, if
present, must match (`stdio` for `command`, `http` for `url`). `env` and
`headers` values must be whole `$VAR_NAME` references; `env` keys must be valid
process environment names and `headers` keys must be valid HTTP header names.
Literal values and manifest-provided encrypted blobs are rejected so plugin
registry records do not become a credential store. Unknown MCP server
capability fields are rejected in this native v0 schema; compatibility
importers should translate or drop host-specific fields such as `cwd` or
`timeout` before installing a Hecate manifest.

`approval_policy` is recorded as requested mount metadata only. When explicit
mounting into Agent Presets or task/chat starts lands, Hecate's own approval policy
remains authoritative; a plugin-declared `auto` value must not downgrade a
Hecate-owned requirement for approval.

```json
→ 200
{
  "object": "plugin",
  "data": {
    "id": "github",
    "name": "GitHub",
    "version": "0.1.0",
    "source_kind": "local_path",
    "source_ref": "/plugins/github/plugin.json",
    "manifest_schema_version": "hecate.plugin.v0",
    "manifest_digest": "sha256:...",
    "requested_permissions": [
      { "value": "network:github.com", "classification": "advisory" },
      { "value": "secret:github_token", "classification": "advisory" }
    ],
    "registry_state": "valid",
    "enabled": false,
    "capabilities": [
      {
        "id": "issues",
        "kind": "connector",
        "display_name": "Issues",
        "enabled": true
      },
      {
        "id": "github-mcp",
        "kind": "mcp_server",
        "display_name": "GitHub MCP",
        "enabled": true,
        "mcp_server": {
          "name": "github",
          "transport": "stdio",
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-github"],
          "env": { "GITHUB_TOKEN": "$GITHUB_TOKEN" },
          "approval_policy": "require_approval"
        }
      },
      {
        "id": "github",
        "kind": "slash_command",
        "display_name": "/github",
        "enabled": true
      }
    ],
    "auth": [
      {
        "capability_id": "issues",
        "requested_name": "github_token",
        "kind": "token",
        "status": "unknown"
      }
    ],
    "installed_at": "2026-06-18T10:00:00Z",
    "updated_at": "2026-06-18T10:00:00Z"
  }
}
```

`PATCH /hecate/v1/plugins/{id}` currently toggles only registry metadata:

```json
{
  "enabled": true,
  "capabilities": {
    "issues": { "enabled": false }
  }
}
```

`GET /hecate/v1/plugins/{id}/health` reports manifest review status:
unsupported permissions, unresolved secret-binding requests, disabled
capabilities, and slash-command collisions. It does not call external services.

## Work policy endpoints

Work policies are reusable Hecate launch postures for standalone native Tasks,
project work, Hecate Chat, Chat-origin Task Runs, and External Agent launches.
The stable API uses the `agent_presets` resource name, but operators use a work policy to select
instructions, intended surface, provider/model hints, and the allowed tool,
workspace-write, network, browser, approval, memory, context, skill,
and External Agent posture. `skill_ids` resolve against the selected project's
skills registry when project work starts. Hecate snapshots resolved/skipped
skill metadata and warnings into the context packet, but it does not install
skills, execute scripts, grant tools, or inject `SKILL.md` bodies from a work
policy.

Hecate also exposes an immutable built-in preset catalog. Built-ins are
returned by list/get requests with `built_in: true`, can be selected directly
or by project and role defaults, and are resolved without being persisted
as `agent_profiles` rows. `POST`, `PATCH`, and `DELETE` against built-in ids
return `409 conflict`.
If an older persisted row uses a now-reserved built-in id, list/get responses
prefer the immutable built-in and suppress the stored duplicate.

Built-in preset ids:

```text
project_assignment
planning
architecture
implementation
frontend_implementation
design_review
reliability_ops
documentation
review_qa
safe_external_review
```

Built-in presets are portable runtime postures and intentionally avoid
project-specific `skill_ids`. Bind discovered project skills through roles or
custom presets so missing project-local skills do not create warnings in every
project.

Preset responses use the normal Hecate envelope:

```json
GET /hecate/v1/agent-presets
→ 200
{
  "object": "agent_presets",
  "data": [
    {
      "id": "prof_...",
      "name": "Backend implementer",
      "description": "Go runtime work",
      "instructions": "Prefer narrow, tested patches.",
      "surface": "hecate_task",
      "provider_hint": "anthropic",
      "model_hint": "claude-sonnet-4",
      "execution_profile": "coding_agent",
      "tools_enabled": true,
      "writes_allowed": true,
      "network_allowed": false,
      "browser_allowed": true,
      "browser_interactions_allowed": true,
      "browser_allowed_origins": ["https://qa.example.test"],
      "approval_policy": "require",
      "project_memory_policy": "visible_only",
      "context_source_policy": "include_enabled",
      "skill_ids": ["backend", "providers"],
      "external_agent_kind": "codex",
      "external_agent_options": { "effort": "high" },
      "built_in": false,
      "created_at": "2026-06-08T12:00:00Z",
      "updated_at": "2026-06-08T12:00:00Z"
    }
  ]
}
```

Supported endpoints:

- `GET /hecate/v1/agent-presets`
- `POST /hecate/v1/agent-presets`
- `GET /hecate/v1/agent-presets/{id}`
- `PATCH /hecate/v1/agent-presets/{id}`
- `DELETE /hecate/v1/agent-presets/{id}`

Enums:

| Field                   | Values                                                  |
| ----------------------- | ------------------------------------------------------- |
| `surface`               | `hecate_chat`, `hecate_task`, `external_agent`, `any`   |
| `approval_policy`       | `inherit`, `require`, `block`, `allow`                  |
| `project_memory_policy` | `inherit`, `include`, `visible_only`, `exclude`         |
| `context_source_policy` | `inherit`, `include_enabled`, `visible_only`, `exclude` |

Hecate Chat session creation accepts only presets whose `surface` is
`hecate_chat` or `any`. This is a narrow Hecate-owned Chat contract, distinct
from native Task resolution: `hecate_task` presets are available to standalone
and project-assignment Tasks, while `external_agent` presets remain for
External Agent launch paths. Hecate Chat copies the independent browser grants,
exact allowed origins, and explicit `approval_policy` from its frozen Chat
snapshot to tools-on backing Tasks;
External Agent permission requests continue through the ACP approval/grant
path.

`POST /hecate/v1/tasks` accepts `agent_preset_id` only for a standard native
`agent_loop` Task with no `workflow_mode`. The selected preset must have
`surface="hecate_task"` or `"any"`. Hecate resolves the preset during Task
creation and freezes its effective execution posture: the preset execution
profile is authoritative (falling back to the preset id when blank), explicit
request provider/model values win over the corresponding hints, and preset
model hints are not paired with an explicitly different provider. An effective
provider without a model is rejected during creation. Preset instructions are
prepended to an optional per-Task `system_prompt`. The Task
also snapshots tools, write/read-only, network, approval, and both browser
grants plus their exact origins. A tools-disabled preset rejects a create that
also supplies `mcp_servers`; it never silently stores unreachable MCP config.

When `project_id` is supplied, this standalone path resolves the Project only
to validate that reference. It does not resolve or activate a Project
assignment, Cairnline coordination state, project memory, context-source
bodies, or project skills, even when the preset names policies or skill ids for
those concepts. Start, Schedule dispatch, Retry, Resume, Continue, and
retry-from-model-call use the stored Task snapshot and never re-resolve the
mutable preset. A missing preset returns `404 not_found`; an incompatible
surface or Task shape returns `400 invalid_request`.

Project assignment starts resolve presets in this order: role default,
project default, built-in `project_assignment` fallback. The start path
snapshots the resolved preset, provider/model hints, runtime profile,
memory policy, context-source policy, skill ids, and warnings into the task/run
context packet. Launch readiness and start both reject a resolved preset whose
surface does not match the assignment driver: native task assignments accept
`hecate_task` or `any`, while External Agent assignments accept
`external_agent` or `any`.

For Work-policy-backed native Tasks, `writes_allowed=false` sets the Task's
`sandbox_read_only=true`; `writes_allowed=true` leaves workspace writes
available within the normal sandbox boundary. `network_allowed` becomes the
task's `sandbox_network` value. When that preset snapshot disables network,
Hecate omits native `http_request` and `web_search` definitions from the model
request and rejects either call if an upstream still returns one. The preset id
marks this native-network policy as present, preserving the prior behavior of
non-preset Tasks whose zero-valued sandbox flag did not govern
native HTTP/search.

For Work-policy-backed native Tasks, `tools_enabled` is snapshotted as the Task's
output-only `agent_preset_tools_enabled` field. Explicit `false` keeps the
execution as a supervised `agent_loop` Task/Run but sends an empty native/MCP
catalog, starts no MCP host, and rejects every unexpected tool call before
approval or dispatch. The runtime emits a denied policy step and
`policy.tool_blocked` with `policy=agent_preset_tools`, then lets the model
finish from supplied context. Older tasks without this snapshot keep
their prior catalog behavior.

Browser capabilities are separate from generic network posture. A preset may
set `browser_allowed=true` for static `browser_inspect`,
`browser_interactions_allowed=true` for `browser_flow`, either, or both. The
grants are independent: static evidence never grants interaction and
interaction never grants static evidence. Either grant is valid only when the
preset is usable by native execution (`surface="hecate_task"`, `"hecate_chat"`,
or `"any"`), tools
are enabled, and `browser_allowed_origins` contains at least one exact HTTP(S)
origin. Hecate normalizes and deduplicates the shared list; credentials, paths,
query strings, and fragments are rejected rather than broadened.

At native Task creation, Hecate copies the grants and shared list
to the output-only `agent_preset_browser_allowed`,
`agent_preset_browser_interactions_allowed`, and
`agent_preset_browser_allowed_origins` Task fields. Later preset edits cannot
alter a queued, running, retried, or resumed Task. Partial updates clear both
grants and the list when tools are disabled or the surface stops being
`any`/`hecate_task`/`hecate_chat`. Disabling only one browser grant preserves the other grant
and its origins; disabling the last grant clears the list. Creation remains
strict and rejects either grant without valid exact origins.

The snapshots expose only Hecate's local browser tools when a local executable
is configured. They do not grant `http_request`, `web_search`, sandbox network,
or any capability to an External Agent. Tools-off Chat, External Agent, QA,
non-preset Tasks, and remote-runtime Tasks receive neither tool. A preset may list
multiple origins, but each approved call passes only its selected exact origin
to the browser. Another configured origin is not available as a cross-origin
subresource destination.

Both tools accept a page path but reject credentials, query strings, and
fragments so those values cannot enter Task conversation or evidence records.
Each call creates a normal `agent_loop_tool_call` approval even when the global
approval-policy list is empty. `browser_inspect` disables scripts and service
workers and emits a bounded `browser_evidence` plain-text artifact.
`browser_flow` enables scripts only for one fully declared approval-bound flow
of 1–6 exact accessibility actions:

```json
{
  "url": "https://qa.example.test/review",
  "actions": [
    { "kind": "wait_for", "role": "button", "name": "Run checks" },
    { "kind": "click", "role": "button", "name": "Run checks" },
    { "kind": "wait_for", "role": "status", "name": "Checks complete" }
  ]
}
```

`kind` is `click` or `wait_for`; both match one exact computed accessibility
`role` and accessible `name`. Click roles are limited to `button`, `link`,
`checkbox`, `radio`, `tab`, `menuitem`, and `switch`. The entire URL and action
sequence must validate before approval and before the browser starts. The agent
loop accepts at most one `browser_flow` in a model tool-call batch. Scripts,
same-origin `GET`/`HEAD` requests, and approved clicks may change the
application, so the approval shows and authorizes the complete ordered flow.

Each browser call starts a fresh process/profile, imports no profile-stored
authentication, and retains no call state for reuse. The tools do not type,
upload, download, capture screenshots, import saved logins, or expose
cookies/storage/raw protocol/request or response bodies. Host-managed browser
policy can still supply integrated authentication or client certificates
outside profile storage; see the
[operator security contract](../operator/security.md#native-browser-capability-boundary).
A successful flow emits bounded `browser_flow_evidence` plain text with ordered action outcomes,
initial/final accessibility snapshots, and network counters.
If a later action fails after a click, Hecate retains bounded partial evidence
with a warning that the approved application may already have changed.

When `writes_allowed=false`, Hecate also omits `shell_exec`, `git_exec`,
`file_write`, and all interactive terminal tools, and rejects an unexpected
call before spawning a process. Structured read/search/Git inspection remains
available. Structured Git inspection is fixed and passive: optional index
locks, lazy fetch, repository fsmonitor helpers, external diff/text conversion,
global/system Git configuration and attributes, and submodule recursion are
disabled, with read-only/offline OS isolation where available. The actual Git
process reads an immutable temporary gitdir containing only allowlisted core
settings and snapshotted HEAD/ref/info metadata, never mutable source config.
Nested task workspaces use the repository top-level metadata while status
paths and diffs remain workspace-scoped. Bounded NUL-safe attribute resolution
fails closed when a scoped tracked path has an effective or ambiguous
content-conversion filter rather than execute a helper or report unnormalized
state. `file_edit` and `apply_patch` remain visible because they can create
proposal artifacts without writing; their apply paths still enforce the
read-only policy.
External Agent CLIs remain trusted subprocesses, so their write/network posture
is visible launch metadata rather than a Hecate sandbox guarantee.

For Work-policy-backed native Tasks, Hecate also copies the resolved preset
`approval_policy` to the output-only `agent_preset_approval_policy` Task field.
The snapshot applies only to mid-loop tool calls on that standard native
agent-loop Task; it does not change any pre-execution gate. Retries and resumes
keep the snapshot instead of resolving
the mutable preset again:

| Value     | Work-policy-backed native Task behavior                                                                                                                                                                                                                                          |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `inherit` | Adds no gate. `HECATE_TASK_APPROVAL_POLICIES`, mandatory browser approval, and each MCP server's approval policy remain authoritative.                                                                                                                                           |
| `allow`   | Adds no gate and never auto-approves or bypasses a stricter runtime, browser, or MCP-server policy.                                                                                                                                                                              |
| `require` | Requires the normal `agent_loop_tool_call` approval for every otherwise-permitted tool call selected from the exact catalog advertised for that model call, including normally ungated native tools and tools from an MCP server whose own policy is `auto`.                     |
| `block`   | Denies only calls that a runtime-wide policy, mandatory browser gate, or `require_approval` MCP-server policy would otherwise gate. Other ungated calls remain dispatchable; denied calls create no approval and emit `policy.tool_blocked` with `policy=agent_preset_approval`. |

Workflow, tools, read-only, network, browser capability/runtime, and
per-MCP-server `block` denials take precedence and cannot be converted into an
approval by this snapshot. An empty snapshot is the compatibility state for
non-preset Tasks and preserves their existing approval behavior; an invalid
non-empty stored value fails safely as `require`. Hecate does not accept this
output-only field directly on Task creation. It is derived while resolving the
supplied `agent_preset_id`, a project assignment's resolved preset, or a
tools-on Hecate Chat's explicit frozen Chat-safe snapshot. Legacy Chat
snapshots without the field retain runtime defaults. It does not apply to
External Agent or QA Tasks.

Because every otherwise-permitted browser call requires approval, a native
preset that combines `approval_policy=block` with either browser grant retains
its configured grant and origins but cannot use that browser capability.
Project-assignment launch readiness reports a warning, and the standalone New
Task preview shows the same ineffective combination. A missing local browser
runtime remains an independent hard-unavailability condition.

For native project assignments, `project_memory_policy=include`
marks enabled project memory active and includes bounded memory bodies in the
assignment task system prompt. `visible_only` and `inherit` keep enabled memory
as inspect-only context, and `exclude` omits memory records from the packet. For
context sources, `context_source_policy=include_enabled` marks enabled source
metadata active and includes bounded portable `AGENTS.md` workspace-instruction
bodies. `visible_only` and `inherit` keep sources inspect-only, and `exclude`
omits them. Host-specific guidance files remain metadata-only for Hecate prompt
context, and `SKILL.md` bodies are never included by these policies. If the
assignment route uses a cloud provider, included project memory and `AGENTS.md`
bodies are sent to that provider as normal task prompt content.

## Project endpoints

Projects are the durable Hecate identity for a work area: code, research,
writing, design, ops, planning, support, or any other operator-coordinated
effort. A project can exist without a workspace root. When local files or code
matter, it can remember one or more concrete workspace roots and future defaults
such as provider, model, agent preset, tools posture, workspace mode, system
prompt, compact command-output preference, and trusted context-source metadata.

The Hecate Projects facade is backed by an embedded Cairnline SQLite store under Hecate's data directory. Cairnline owns portable coordination state; Hecate stores runtime defaults, execution references, chats, tasks, approvals, and traces separately. The public Hecate routes remain `/hecate/v1/projects*`, so the operator UI does not depend on Cairnline's transport. There is no selectable Hecate-native coordination backend or migration API. Chat sessions can carry an optional
`project_id` so the operator UI can group history by project. Opening chat from
a project-work assignment creates a project-scoped Hecate Chat session and
pre-fills the editable composer with a concise launch-context draft; the draft
is not submitted automatically. Projects can also remember context-source
metadata (`path`, `kind`, `title`, `format`, `scope`, `trust_label`,
`source_category`, arbitrary string metadata, and whether the source is
enabled). Chat message context packets include enabled sources as itemized
`workspace_guidance` metadata for inspection, but Hecate does not inject those
files into prompts yet. Projects also have a project-scoped skills registry
for local `SKILL.md` metadata discovered from `.agents/skills`,
`.cairnline/skills`, `.claude/skills`, `.gemini/skills`, `.hecate/skills`,
and enabled guidance-linked local skill roots. The registry stores ids,
title/description metadata, path, root, status, trust label, and warnings; it
does not store or return skill bodies. Project work-coordination
endpoints can persist roles, work items, assignments, and collaboration
artifacts under a project. Assignments may record links to existing task runs
or chat messages, but creating an assignment does not start a task, open a
chat, inject context, or dispatch any agent. Project handoffs are structured
project-scoped records for passing context and a recommended next action from
one assignment/run/chat to another role or assignment. They can link artifacts,
memory entries, and context references, but they do not launch follow-up work
by themselves. Work-item `reviewer_role_ids` are follow-through hints for
review handoffs: the Projects cockpit can prefill a request-review handoff to a
reviewer role, but creating the target assignment and starting it remain
explicit operator actions.
Project memory entries are structured project-scoped records with
Markdown-compatible `body` text; they are not Markdown files, and they are
written only through explicit operator API/UI actions. Enabled project memory
entries appear as itemized chat context-packet metadata with their
`trust_label`, but Hecate still does not perform automatic memory extraction,
embeddings, retrieval ranking, or source-content injection.
Project setup readiness, project health, and Project Operations are read-only
cockpit projections over these existing records. They help the operator choose
the next surface to open, but they do not create durable project records or
start supervised work.

### `GET /hecate/v1/projects`

```json
GET /hecate/v1/projects
→ 200
{
  "object": "projects",
  "data": [
    {
      "id": "proj_...",
      "read_backend": "cairnline",
      "name": "Hecate",
      "description": "Gateway and agent runtime",
      "roots": [
        {
          "id": "root_...",
          "path": "/Users/alice/src/hecate",
          "kind": "git",
          "git_remote": "git@github.com:hecatehq/hecate.git",
          "git_branch": "master",
          "active": true,
          "created_at": "2026-05-20T12:00:00Z",
          "updated_at": "2026-05-20T12:00:00Z"
        }
      ],
      "context_sources": [
        {
          "id": "ctxsrc_...",
          "kind": "doc",
          "title": "README",
          "path": "README.md",
          "enabled": true,
          "format": "",
          "scope": "",
          "trust_label": "",
          "source_category": "",
          "metadata": {},
          "created_at": "2026-05-20T12:00:00Z",
          "updated_at": "2026-05-20T12:00:00Z"
        }
      ],
      "default_root_id": "root_...",
      "default_provider": "ollama",
      "default_model": "qwen2.5-coder",
      "default_agent_profile": "implementation",
      "default_tools_enabled": true,
      "default_workspace_mode": "in_place",
      "default_system_prompt": "Prefer small, reviewable patches.",
      "default_compact_tool_output": false,
      "created_at": "2026-05-20T12:00:00Z",
      "updated_at": "2026-05-20T12:00:00Z",
      "last_opened_at": "2026-05-20T12:30:00Z"
    }
  ]
}
```

### `POST /hecate/v1/projects`

Creates a project. `name` is required. Root `id` values are optional; Hecate
generates `root_...` IDs for roots that omit them. If `default_root_id` is
empty and at least one root is supplied, the first root becomes the default.
When supplied, `default_root_id` must match one of the supplied roots.
Context source `id` values are optional; Hecate generates `ctxsrc_...` IDs for
sources that omit them. Context sources are project source metadata:
workspace guidance discovered from roots, operator-added URLs, local paths,
notes, tickets, design files, source docs, or other external references.
Their `path` field is the source locator. For note-style sources, clients may
use a stable locator such as `note:research-goals` and store the note text in
`metadata.note`. Source metadata is visible to Project Assistant and context
inspectors, but Hecate does not fetch URLs, execute sources, or blindly inject
source bodies into prompts. Assignment prompt inclusion is still governed by
Agent Preset context-source policy and currently only includes bounded portable
workspace guidance (`kind: "workspace_instruction"`, `format: "agents_md"`).
Clients that render `path` as a link must validate the scheme first; Hecate
stores operator-provided locators as-is.
Project names are unique across the local project catalog, and root/workspace
paths are unique across all projects. Duplicate project names or root paths
return `409 conflict`.

Projects may be created without a workspace by omitting both `workspace_path`
and `roots`; this is the normal shape for planning, research, writing, ops, or
design projects that do not start from local files. For the common
one-workspace case, send `workspace_path` and optionally `workspace_kind`;
Hecate creates one active root and makes it the default root. For advanced
multi-root setup, send `roots` directly.
`workspace_path` cannot be combined with `roots` or an explicit
`default_root_id`.

```json
POST /hecate/v1/projects
{
  "name": "Hecate",
  "description": "Gateway and agent runtime",
  "workspace_path": "/Users/alice/src/hecate",
  "workspace_kind": "git",
  "context_sources": [
    {
      "kind": "url",
      "title": "Design brief",
      "path": "https://example.invalid/design",
      "enabled": true,
      "format": "url",
      "trust_label": "operator_source",
      "source_category": "operator_source",
      "metadata": { "note": "Reviewed by the operator." }
    },
    {
      "kind": "note",
      "title": "Research goals",
      "path": "note:research-goals",
      "enabled": true,
      "format": "text",
      "trust_label": "operator_source",
      "source_category": "operator_source",
      "metadata": { "note": "Prioritize sources with concrete user evidence." }
    }
  ],
  "default_provider": "ollama",
  "default_model": "qwen2.5-coder",
  "default_tools_enabled": true,
  "default_workspace_mode": "in_place"
}

→ 201
{
  "object": "project",
  "data": {
    "id": "proj_...",
    "name": "Hecate",
    "roots": [
      {
        "id": "root_...",
        "path": "/Users/alice/src/hecate",
        "kind": "git",
        "active": true
      }
    ],
    "default_root_id": "root_..."
  }
}
```

### `GET /hecate/v1/projects/{id}`

Returns one project or `404 not_found`.

### `PATCH /hecate/v1/projects/{id}`

Updates project metadata and defaults. Fields are optional. When `roots` is
present, it replaces the full root list; this remains available for
compatibility and admin-style bulk replacement. Operator root edits should use
the root-specific endpoints below so a single root create, update, or delete is
typed and auditable.
When `context_sources` is present, it replaces the full source-metadata list;
this remains available for compatibility and admin-style bulk replacement.
Operator source edits should use the source-specific endpoints below so a
single source create, update, or delete is typed and auditable.
When `default_root_id` is supplied, it must match the replacement root list or,
if `roots` is omitted, one of the existing roots. Renames and root replacements
preserve the same catalog uniqueness rules as creation: duplicate project names
or root paths return `409 conflict`.

```json
PATCH /hecate/v1/projects/proj_...
{
  "name": "Hecate runtime",
  "last_opened_at": "2026-05-20T12:45:00Z",
  "default_compact_tool_output": true
}
```

### `POST /hecate/v1/projects/{id}/roots`

Creates one project-root metadata record and returns the updated project. This
does not create a directory, create a Git worktree, scan the workspace, or
launch work. Use `POST /roots/worktrees` when Hecate should explicitly create a
Git worktree.

If `id` is omitted, the server generates one. Duplicate root IDs return
`409 conflict`; invalid root metadata returns `400 invalid_request`.

```json
POST /hecate/v1/projects/proj_.../roots
{
  "path": "/Users/alice/src/hecate",
  "kind": "git",
  "git_branch": "main",
  "active": true
}

→ 201
{
  "object": "project",
  "data": {
    "id": "proj_...",
    "roots": [
      {
        "id": "root_...",
        "path": "/Users/alice/src/hecate",
        "kind": "git",
        "git_branch": "main",
        "active": true
      }
    ],
    "default_root_id": "root_..."
  }
}
```

### `PATCH /hecate/v1/projects/{id}/roots/{root_id}`

Replaces one project-root metadata record and returns the updated project. The
path `root_id` is authoritative; any `id` in the request body is ignored for
the updated record. The payload is the full replacement metadata, so omitted
optional fields clear or default through the normal project-root validation
rules.

Missing projects or roots return `404 not_found`; invalid root metadata returns
`400 invalid_request`.

```json
PATCH /hecate/v1/projects/proj_.../roots/root_...
{
  "path": "/Users/alice/src/hecate/.worktrees/feature-a",
  "kind": "git_worktree",
  "git_branch": "feature/a",
  "active": true
}
```

### `DELETE /hecate/v1/projects/{id}/roots/{root_id}`

Deletes one project-root metadata record and returns the updated project so
clients can reconcile against the server state. Deleting a root only removes
the project metadata reference; it does not delete local folders, Git
worktrees, branches, files, work items, assignments, Chats, Tasks, or External
Agent turns. If the deleted root was the default root, the store
normalizes the updated project to the first remaining root or to no default
when no roots remain.

```json
DELETE /hecate/v1/projects/proj_.../roots/root_...
→ 200
{
  "object": "project",
  "data": {
    "id": "proj_...",
    "roots": []
  }
}
```

### `POST /hecate/v1/projects/{id}/context-sources`

Creates one context-source metadata record and returns the updated project. The
request is explicit metadata only: Hecate does not read file bodies, fetch URLs,
promote memory, inject prompt context, or change Agent Preset policy.

If `id` is omitted, the server generates one. Duplicate source IDs return
`409 conflict`; invalid source metadata returns `400 invalid_request`.

```json
POST /hecate/v1/projects/proj_.../context-sources
{
  "kind": "url",
  "title": "Launch brief",
  "path": "https://example.invalid/brief",
  "enabled": true,
  "format": "url",
  "trust_label": "operator_source",
  "source_category": "operator_source",
  "metadata": {
    "note": "Reviewed source for launch planning."
  }
}

→ 201
{
  "object": "project",
  "data": {
    "id": "proj_...",
    "context_sources": [
      {
        "id": "ctxsrc_...",
        "kind": "url",
        "title": "Launch brief",
        "path": "https://example.invalid/brief",
        "enabled": true
      }
    ]
  }
}
```

### `PATCH /hecate/v1/projects/{id}/context-sources/{source_id}`

Replaces one context-source metadata record and returns the updated project.
The path `source_id` is authoritative; any `id` in the request body is ignored
for the updated record. The payload is the full replacement metadata, so
omitted optional fields clear or default through the normal project-source
validation rules.

Missing projects or sources return `404 not_found`; invalid source metadata
returns `400 invalid_request`.

```json
PATCH /hecate/v1/projects/proj_.../context-sources/ctxsrc_...
{
  "kind": "doc",
  "title": "Architecture notes",
  "path": "docs/architecture.md",
  "enabled": true,
  "format": "markdown",
  "trust_label": "operator_source",
  "source_category": "operator_source"
}
```

### `DELETE /hecate/v1/projects/{id}/context-sources/{source_id}`

Deletes one context-source metadata record and returns the updated project so
clients can reconcile against the server state. Deleting a source only removes
the project metadata reference; it does not delete local files, remote content,
memory records, work items, assignments, Chats, Tasks, or External Agent turns.

```json
DELETE /hecate/v1/projects/proj_.../context-sources/ctxsrc_...
→ 200
{
  "object": "project",
  "data": {
    "id": "proj_...",
    "context_sources": []
  }
}
```

### `POST /hecate/v1/projects/{id}/roots/discover`

Refreshes Git metadata for active project roots and discovers linked Git
worktrees for the same repository. This is an explicit operator action. It
does not create branches, create worktrees, delete roots, change
`default_root_id`, or start work.

Discovered linked worktrees are appended to `roots` with:

- `kind: "git_worktree"`
- `git_branch` from `git worktree list --porcelain`
- `git_remote` from `origin` when configured
- `active: false` by default

Inactive discovered roots are visible to the operator but are not scanned for
workspace guidance or used for assignment launch until the operator enables
them or makes one the default root. Existing roots are matched by path; their
IDs and active state are preserved while branch/remote metadata is refreshed.

```json
POST /hecate/v1/projects/proj_.../roots/discover
→ 200
{
  "object": "project",
  "data": {
    "id": "proj_...",
    "roots": [
      {
        "id": "root_main",
        "path": "/Users/alice/src/cynic",
        "kind": "git",
        "git_remote": "git@github.com:owner/cynic.git",
        "git_branch": "main",
        "active": true
      },
      {
        "id": "root_...",
        "path": "/Users/alice/src/cynic/.claude/worktrees/fix-array-sort",
        "kind": "git_worktree",
        "git_remote": "git@github.com:owner/cynic.git",
        "git_branch": "fix-array-sort",
        "active": false
      }
    ],
    "default_root_id": "root_main"
  }
}
```

### `POST /hecate/v1/projects/{id}/roots/worktrees`

Creates a linked Git worktree from an existing project root and appends the
created checkout as a project root. This is an explicit operator action. V1
constrains the target path to a direct child of the selected base root's
`.worktrees/` directory so Hecate does not create sibling, nested, or arbitrary
filesystem workspaces through this endpoint.

Request fields:

- `branch` is required and becomes the new worktree branch.
- `base_root_id` selects the Git root to run `git worktree add` from; omitted
  means project default root, then first active root, then first root.
- `start_point` is optional and is passed to Git after the target path.
- `path` is optional. Relative paths resolve under the base root and must be a
  direct child of `.worktrees/`.
- `active` defaults to `true`.
- `set_default` makes the new root the project's `default_root_id`.

```json
POST /hecate/v1/projects/proj_.../roots/worktrees
{
  "base_root_id": "root_main",
  "branch": "feature/project-roots",
  "start_point": "origin/main",
  "active": true,
  "set_default": true
}

→ 201
{
  "object": "project",
  "data": {
    "id": "proj_...",
    "default_root_id": "root_...",
    "roots": [
      {
        "id": "root_...",
        "path": "/Users/alice/src/hecate/.worktrees/feature-project-roots",
        "kind": "git_worktree",
        "git_branch": "feature/project-roots",
        "active": true
      }
    ]
  }
}
```

### `POST /hecate/v1/projects/{id}/context-sources/discover`

Discovers workspace guidance metadata from active absolute project roots and
merges it into `context_sources`. Discovery is an explicit operator action: it
does not read discovered file bodies into prompts and does not change Hecate
policy, approvals, sandboxing, or Agent Preset settings.

V1 enables portable `AGENTS.md` sources as `kind=workspace_instruction`,
`format=agents_md`, and `trust_label=workspace_guidance`. Host-specific files
are labelled for visibility but remain metadata-only: `CLAUDE.md`,
`.claude/CLAUDE.md`, `GEMINI.md`, `.cursor/rules`, `.github/instructions`,
`.devin/rules`, `.windsurf/rules`, and `.gemini/commands`.

Discovery skips common vendor/build directories such as `.git`, `node_modules`,
`vendor`, `dist`, `build`, `.next`, `.turbo`, `.cache`, `target`, and
`coverage`. It also skips nested Git checkouts plus `.worktrees` and
`.claude/worktrees` under an active root. Linked worktrees should be added as
explicit project roots through root discovery; their guidance is discovered only
when that root is active.
Existing sources are matched by `(kind,path)` plus root metadata so operator
disabled state and source IDs are preserved on rediscovery.

```json
POST /hecate/v1/projects/proj_.../context-sources/discover
→ 200
{
  "object": "project",
  "data": {
    "id": "proj_...",
    "context_sources": [
      {
        "id": "ctxsrc_...",
        "kind": "workspace_instruction",
        "title": "AGENTS.md",
        "path": "AGENTS.md",
        "enabled": true,
        "format": "agents_md",
        "scope": "workspace",
        "trust_label": "workspace_guidance",
        "source_category": "workspace_guidance",
        "metadata": { "root_id": "root_..." }
      }
    ]
  }
}
```

### `DELETE /hecate/v1/projects/{id}`

Deletes the project catalog entry, its roots, and chat sessions scoped to that
project. It also deletes project memory entries, memory candidates, project
work-coordination rows, and Hecate-owned project runtime overlay rows for
that project. Project-scoped External Agent chats are deleted through
the normal chat-delete path, so Hecate asks the adapter to delete the native ACP
session where supported. This does not delete workspace files. Unprojected
chats and chats scoped to other projects stay untouched. Assignment links to
task/chat IDs are metadata only; the linked tasks or unprojected chat sessions
are not deleted through assignment cleanup.

The project facade admits every mutation through its complete set of affected
process-local project keys. Ordinary mutations may remain concurrent, and a
multi-project operation acquires its normalized key set atomically. Deletion
closes its key, waits for admitted mutations, and holds the closure from
Cairnline identity removal through Hecate-owned cleanup and any rollback. A new
same-project mutation during deletion returns `409 conflict`, so a stale
rollback import cannot overwrite an acknowledged facade write. Mutations whose
project sets do not overlap remain concurrent. This fence coordinates one
Hecate process; it is not a distributed revision or CAS mechanism for direct
Cairnline writers.

The response reports the scoped records Hecate cleaned up:

```json
{
  "object": "project_delete",
  "data": {
    "project_id": "proj_...",
    "project_name": "Launch operations",
    "chat_sessions_deleted": 2,
    "project_work_rows_deleted": 8,
    "project_runtime_rows_deleted": 2,
    "project_skills_deleted": 1,
    "memory_entries_deleted": 3,
    "memory_candidates_deleted": 4
  }
}
```

### Project Memory

Project memory is explicit operator-approved context. Hecate never writes these
entries automatically from chat, task, handoff, or generated output; generated
or external text must be reviewed and saved by the operator before it becomes
memory. Agents, chats, tasks, and project-work surfaces may create memory
candidates, but candidates are review records only. They do not participate in
context packets and do not create durable memory until the operator explicitly
promotes one.

Memory entry fields:

| Field         | Meaning                                                                |
| ------------- | ---------------------------------------------------------------------- |
| `id`          | Stable `mem_...` entry id.                                             |
| `scope`       | `"project"` in this release.                                           |
| `project_id`  | Owning project id.                                                     |
| `title`       | Operator-facing label.                                                 |
| `body`        | Markdown-compatible text stored on the structured record.              |
| `trust_label` | Context trust label such as `operator_memory` or `generated_summary`.  |
| `source_kind` | Provenance category such as `operator`, `handoff`, or `runtime_state`. |
| `source_id`   | Optional source artifact/chat/message/handoff id.                      |
| `enabled`     | Disabled entries remain saved but are excluded from active context.    |
| `created_at`  | UTC RFC3339Nano timestamp.                                             |
| `updated_at`  | UTC RFC3339Nano timestamp.                                             |

#### `GET /hecate/v1/projects/{id}/memory`

```json
GET /hecate/v1/projects/proj_.../memory?include_disabled=true
→ 200
{
  "object": "project_memory",
  "data": [
    {
      "id": "mem_...",
      "scope": "project",
      "project_id": "proj_...",
      "read_backend": "cairnline",
      "title": "Commit style",
      "body": "Use conventional commits.",
      "trust_label": "operator_memory",
      "source_kind": "operator",
      "enabled": true,
      "created_at": "2026-06-04T10:00:00Z",
      "updated_at": "2026-06-04T10:00:00Z"
    }
  ]
}
```

#### `POST /hecate/v1/projects/{id}/memory`

Creates a project memory entry. `title` and `body` are required. `trust_label`
defaults to `operator_memory`, `source_kind` defaults to `operator`, and
`enabled` defaults to `true`. A duplicate generated entry id returns
`409 conflict`.

```json
POST /hecate/v1/projects/proj_.../memory
{
  "title": "Review posture",
  "body": "Keep generated summaries labelled.",
  "trust_label": "operator_memory",
  "source_kind": "operator"
}

→ 201
{
  "object": "project_memory_entry",
  "data": {
    "id": "mem_...",
    "scope": "project",
    "project_id": "proj_...",
    "read_backend": "cairnline",
    "title": "Review posture",
    "body": "Keep generated summaries labelled.",
    "trust_label": "operator_memory",
    "source_kind": "operator",
    "enabled": true,
    "created_at": "2026-06-04T10:00:00Z",
    "updated_at": "2026-06-04T10:00:00Z"
  }
}
```

#### `PATCH /hecate/v1/projects/{id}/memory/{memory_id}`

Updates title, body, trust/provenance fields, or enabled state. `id`, `scope`,
and `project_id` are immutable.

#### `DELETE /hecate/v1/projects/{id}/memory/{memory_id}`

Deletes the memory entry. Historical chat context packets that already
snapshotted the entry are not rewritten.

#### `GET /hecate/v1/projects/{id}/memory/candidates`

Candidates are review artifacts, not durable memory. Operators should inspect
the candidate body, suggested trust/source fields, and `source_refs` before
promotion. `source_refs` point back to evidence such as task runs, handoffs,
chat messages, or artifacts so the UI can show where the candidate came from
without injecting unapproved text into future context packets.

```json
GET /hecate/v1/projects/proj_.../memory/candidates
→ 200
{
  "object": "project_memory_candidates",
  "data": [
    {
      "id": "memcand_...",
      "project_id": "proj_...",
      "read_backend": "cairnline",
      "title": "Generated summary",
      "body": "Keep generated context labelled until reviewed.",
      "suggested_kind": "note",
      "suggested_trust_label": "generated_summary",
      "suggested_source_kind": "task_output",
      "suggested_source_id": "run_...",
      "source_refs": [{ "kind": "task_run", "id": "run_..." }],
      "status": "pending",
      "created_at": "2026-06-04T10:00:00Z",
      "updated_at": "2026-06-04T10:00:00Z"
    }
  ]
}
```

#### `POST /hecate/v1/projects/{id}/memory/candidates`

Creates a review candidate from a manual payload or a known source reference.
`title` and `body` are required. Candidates default to
`suggested_trust_label="generated_summary"` and
`suggested_source_kind="generated"` so generated/external text stays
lower-trust unless the operator changes it during promotion.

#### `POST /hecate/v1/projects/{id}/memory/candidates/{candidate_id}/promote`

Promotes a pending candidate into a durable project memory entry. The request
may include edited `title`, `body`, `trust_label`, `source_kind`, `source_id`,
and `enabled`; omitted fields use the candidate's suggested values. Promotion
sets the candidate status to `promoted` and records `promoted_memory_id`.
Only the created memory entry participates in future project-memory context
selection; the candidate remains a provenance/audit record.
Promoting an already-promoted candidate is idempotent when the linked
`promoted_memory_id` still exists and returns the existing promoted candidate.
Promoting a rejected candidate returns `409 conflict`.

The response is `{ "object": "project_memory_candidate", "data": ... }`. The
created memory entry is returned by the normal project memory list/get flows.

#### `POST /hecate/v1/projects/{id}/memory/candidates/{candidate_id}/reject`

Rejects or dismisses a pending candidate without creating durable memory. The
optional request body is `{ "reason": "..." }`. Rejecting an already resolved
candidate returns `409 conflict`.

### Project Work Coordination

Project work coordination is the durable substrate for future project-team
orchestration. It records project-scoped agent roles, work items, assignment
metadata, and collaboration artifacts. It does not add a new execution runtime:
existing Tasks and Chats remain the execution surfaces. Assignment creation
records intended or already-linked execution metadata; the separate native
assignment start endpoint can create and start a Hecate-owned `agent_loop` task
for `driver_kind="hecate_task"` assignments.
Create requests that supply an existing project-scoped ID return `409 conflict`
instead of overwriting the existing record.

Role list responses merge built-in roles with project custom roles. Built-ins
are listable but immutable and are not seeded as duplicate project rows. The
built-in role ids and default preset mappings are:

| Role id              | Default driver | Default preset            |
| -------------------- | -------------- | ------------------------- |
| `product_manager`    | `hecate_task`  | `planning`                |
| `architect`          | `hecate_task`  | `architecture`            |
| `software_developer` | `hecate_task`  | `implementation`          |
| `frontend_engineer`  | `hecate_task`  | `frontend_implementation` |
| `designer`           | `hecate_task`  | `design_review`           |
| `sre`                | `hecate_task`  | `reliability_ops`         |
| `tech_writer`        | `hecate_task`  | `documentation`           |
| `reviewer_qa`        | `hecate_task`  | `review_qa`               |

Supported work-item statuses are `backlog`, `ready`, `running`, `review`,
`blocked`, `done`, and `cancelled`. Supported assignment statuses are `queued`,
`running`, `awaiting_approval`, `completed`, `failed`, and `cancelled`.
Supported assignment driver kinds are `manual`, `hecate_task`, and
`external_agent`. The facade exposes `manual` as Human work and maps it to
Cairnline's portable manual execution mode. Assignment start claims Human work
without creating a runtime, dispatches `hecate_task` assignments through the
native task runtime, and prepares `external_agent` assignments as supervised
External Agent chat sessions.
Work items and assignments may carry `root_id` to select a concrete project
root. Launch workspace resolution uses assignment `root_id`, then work-item
`root_id`, then project `default_root_id`, then the first active project root.
Work items may also carry `reviewer_role_ids`; these identify roles that are
appropriate targets for review handoffs and do not grant permissions, enforce
policy, or auto-dispatch review work.
Supported collaboration artifact kinds are `brief`, `handoff`, `review`,
`decision_note`, and `evidence_link`.
Supported structured handoff statuses are `pending`, `accepted`, `superseded`,
and `dismissed`.

Assignment responses are projected from linked canonical task/run state when
`execution_ref.kind="task_run"` and `execution_ref.task_id` /
`execution_ref.run_id` point at a Hecate task run. If
`execution_ref.task_id` is present and `execution_ref.run_id` is empty, Hecate
uses that task's `latest_run_id` when available. Run statuses map directly into
assignment statuses:

| Task/run status     | Project assignment status |
| ------------------- | ------------------------- |
| `queued`            | `queued`                  |
| `running`           | `running`                 |
| `awaiting_approval` | `awaiting_approval`       |
| `completed`         | `completed`               |
| `failed`            | `failed`                  |
| `cancelled`         | `cancelled`               |

If the linked task/run is missing, Hecate keeps the stored assignment status
and marks the nested `execution` summary as `missing`. If a linked run is older
than a newer explicit terminal assignment update, the assignment keeps that
explicit project-work terminal status instead of being overwritten by stale
runtime state. The `execution` summary may include `task_status`, `run_status`,
projected `status`, pending approval count, step/approval/artifact counts,
model/provider, last error, run timestamps, and trace ID.

In strict embedded assignment-authority mode, Projects reads also reconcile a
linked, present task run into the Cairnline assignment before computing work,
activity, operations, readiness, health, chat context, or Project Assistant
projections. Cairnline's claim, progress, and completion transitions record
`running`, `awaiting_approval`, `completed`, `failed`, or `cancelled` plus the
portable execution ref. A missing or queued host execution never moves the
portable row backwards, and Cairnline's first terminal outcome remains final
if a stale host event later reports another outcome. Outside strict embedded
authority mode, task/run state remains a read-only response projection.
Before any reconciliation write, Hecate requires the linked Task and selected
Run to carry the same project, work-item, and assignment ids as the portable
row. A mismatched link is stale evidence and cannot mutate Cairnline. If a Task
has been resumed, reconciliation follows its matching `latest_run_id` and moves
the portable execution ref forward instead of closing work from the obsolete
terminal run.

External Agent assignments use the linked project-scoped chat session as their
canonical execution state when `execution_ref.kind="chat_session"` and
`execution_ref.chat_session_id` points at a Chat in the same project.
Assignment reads project the latest assistant-message status first, then the
session status, so a stale session summary cannot keep a completed assistant
turn in the active bucket. Chat-backed projections update
`execution_ref.status`, `execution_ref.message_id`, `execution_ref.trace_id`,
and assignment `completed_at` when available; they do not include a task-run
`execution` summary. Missing chats, chat-store lookup errors, or cross-project
chat links are treated as missing execution refs instead of exposing foreign
chat metadata.

When an External Agent chat turn reaches `completed`, `failed`, or
`cancelled`, Hecate also performs a best-effort reconciliation pass that
updates linked project assignment rows. This makes the durable assignment
status catch up with the chat outcome without making the chat response fail if
project metadata reconciliation is temporarily unavailable.

Assignments include `execution_ref`, the canonical compact execution link for
UI clients and API callers. It prefers projected execution data when available
and falls back to stored links, with `kind` set to `task_run`, `chat_session`,
or `context_snapshot`. The richer `execution` summary remains for detail views;
raw top-level assignment link fields are not part of the alpha contract.

Work-item list and detail responses apply a conservative operational projection
over assignment statuses without fabricating work-item closure. A `running` or
`awaiting_approval` assignment, or a queued assignment with a present linked
execution, makes open work appear `running`. A failed or cancelled assignment
makes open work appear `blocked`. Completed assignments leave the stored
work-item status unchanged, because evidence, review follow-up, or handoff work
may still remain. Stored `done` and `cancelled` statuses are terminal and are
never overwritten by assignment projection.

The Projects UI also exposes an operator closeout action for selected work
items. The read-only
`GET /hecate/v1/projects/{id}/work-items/{work_item_id}/readiness` contract is
the shared closeout authority for Project Operations, selected-work detail, and
`PATCH` requests that set `status="done"`: it derives blockers from
assignments, completion evidence, handoffs, and review follow-up without
mutating project state. The guided action still uses the normal work-item
`PATCH` path only after the operator reviews closeout and confirms **Mark work
done**. Hecate does not
auto-mutate stored work-item status from review verdicts, handoffs, or
assignment rollups without an explicit operator update. Updates that do not mark
the work item done continue to use the normal edit flow while closeout blockers
remain. A readiness response with `status="done"` therefore reflects a persisted
operator closeout decision, not a client inference from completed assignments.
The Projects UI also treats stored work-item `done` and `cancelled` status as a
terminal read-only signal if readiness cannot be refreshed; a transient read
failure must not make terminal work mutable again.

#### `GET /hecate/v1/projects/{id}/activity`

Returns a read-only project activity inbox for the operator cockpit. The
response is bounded and deterministic: Hecate composes existing project work
items, assignments, projected task/run execution summaries, linked chat/task
identifiers, and recent collaboration artifact signals without mutating any
project-work or task rows.

Activity Inbox stays focused on live assignment buckets. The compact
Needs Attention header uses the server-owned project health endpoint below so
clients do not rederive a second attention cascade from activity, memory,
skills, and project defaults.

The top-level envelope follows the Hecate-native convention:

```json
{
  "object": "project_activity",
  "data": {
    "project_id": "proj_...",
    "read_backend": "cairnline",
    "summary": {
      "work_item_count": 3,
      "assignment_count": 5,
      "active_count": 1,
      "blocked_count": 2,
      "completed_count": 2,
      "recent_count": 1
    },
    "buckets": {
      "blocked": [
        {
          "id": "asgn_...",
          "project_id": "proj_...",
          "work_item": {
            "id": "work_...",
            "title": "Backend substrate",
            "status": "running",
            "priority": "high"
          },
          "assignment": {
            "id": "asgn_...",
            "project_id": "proj_...",
            "work_item_id": "work_...",
            "role_id": "software_developer",
            "driver_kind": "hecate_task",
            "status": "awaiting_approval",
            "task_id": "task_...",
            "run_id": "run_...",
            "execution": {
              "task_id": "task_...",
              "run_id": "run_...",
              "task_status": "running",
              "run_status": "awaiting_approval",
              "status": "awaiting_approval",
              "pending_approval_count": 1
            },
            "created_at": "2026-06-03T12:00:00Z",
            "updated_at": "2026-06-03T12:01:00Z"
          },
          "role": {
            "id": "software_developer",
            "project_id": "proj_...",
            "name": "Software Developer",
            "built_in": true
          },
          "status": "awaiting_approval",
          "blocking_signal": "awaiting_approval",
          "status_summary": "1 approval pending",
          "linked_task_id": "task_...",
          "linked_run_id": "run_...",
          "linked_chat_id": "chat_...",
          "linked_chat": {
            "id": "chat_...",
            "title": "Backend substrate - External implementer",
            "agent_id": "codex",
            "agent_title": "Codex ACP Adapter",
            "agent_version": "0.1.0-alpha.33",
            "available_command_count": 3,
            "driver_kind": "acp",
            "native_session_id": "native_...",
            "status": "running",
            "latest_message_id": "msg_...",
            "latest_role": "assistant",
            "latest_status": "completed",
            "message_count": 2,
            "updated_at": "2026-06-03T12:02:00Z"
          },
          "artifact_summary": {
            "count": 1,
            "latest_kind": "handoff",
            "latest_title": "Backend handoff",
            "latest_at": "2026-06-03T12:03:00Z",
            "assignment_id": "asgn_..."
          },
          "handoff_summary": {
            "count": 1,
            "pending_count": 1,
            "accepted_count": 0,
            "latest_status": "pending",
            "latest_title": "QA handoff",
            "latest_at": "2026-06-03T12:04:00Z",
            "assignment_id": "asgn_...",
            "target_role_id": "reviewer_qa"
          },
          "recent_artifacts": [
            {
              "id": "art_...",
              "project_id": "proj_...",
              "work_item_id": "work_...",
              "assignment_id": "asgn_...",
              "kind": "handoff",
              "title": "Backend handoff",
              "body": "Ready for review.",
              "created_at": "2026-06-03T12:03:00Z",
              "updated_at": "2026-06-03T12:03:00Z"
            }
          ],
          "recent_handoffs": [
            {
              "id": "handoff_...",
              "project_id": "proj_...",
              "work_item_id": "work_...",
              "source_assignment_id": "asgn_...",
              "source_chat_session_id": "chat_...",
              "source_message_id": "msg_...",
              "target_role_id": "reviewer_qa",
              "title": "QA handoff",
              "summary": "Implementation is ready for review.",
              "recommended_next_action": "Create a queued QA assignment.",
              "status": "pending",
              "provenance_kind": "agent_draft",
              "trust_label": "operator_reviewed",
              "created_at": "2026-06-03T12:04:00Z",
              "updated_at": "2026-06-03T12:04:00Z",
              "status_changed_at": "2026-06-03T12:04:00Z"
            }
          ],
          "updated_at": "2026-06-03T12:04:00Z"
        }
      ],
      "active": [],
      "completed": [],
      "recent": []
    },
    "recent": []
  }
}
```

`blocking_signal` is the compact V1 operator signal. Known values are
`awaiting_approval`, `failed`, `cancelled`, `not_started`, `running`,
`completed`, and `stale_unknown`. `not_started` means a queued assignment has
no linked task, run, or chat identifiers. `stale_unknown` covers missing linked
task/run/chat records, run-only links without enough task context, unknown
status values, wrong-project linked chats, and transient linked-chat lookup
failures.
Rows are sorted by most recent assignment/work/artifact update, then assignment
ID. Each bucket is capped at 20 rows; `recent` mirrors
`buckets.recent`. The example above leaves the mirrored recent arrays empty for
brevity; real responses include the same item shape there when `recent_count`
is non-zero. `artifact_summary.assignment_id` is present only when the latest
summarized artifact is assignment-scoped; work-item-level artifacts omit it.
`linked_chat` is present when an assignment points at a Chat or External Agent
session. It is a compact activity projection, not a full chat transcript:
clients use it for session status, last-message status/error,
adapter/session identity, ACP implementation summary, advertised command count,
and missing linked-session diagnostics, then open the chat endpoint for full
transcript state. When a handoff is created from an
assignment, clients may copy the assignment, run, chat, message, and context
refs into the handoff source fields so later follow-up assignments preserve
provenance without auto-dispatching work.
An `idle` linked chat with a running/queued external assignment is a prepared
session waiting for the operator's first or next turn, not stale execution.
`handoff_summary` and `recent_handoffs` are activity projections over
structured handoff records attached to the same work item and, when present,
the same source or target assignment. Handoffs that are not assignment-linked
are still available from the handoff list/detail endpoints; V1 does not create
standalone activity rows for them.

#### `GET /hecate/v1/projects/{id}/health`

Returns a read-only Project attention summary for the selected project. The
endpoint derives compact operator rows from existing project state: missing
provider/model defaults, missing active roots, missing agent preset refs,
project skill registry conflicts or unresolved/disabled referenced skills,
pending handoffs, review artifacts that need a follow-up path, stale or missing
linked assignment execution, failed/cancelled External Agent assignments,
empty memory/context posture, and pending memory candidates.

The five-item cap is applied after the server's attention derivation order. The
summary reports returned, available, omitted, and limit counts so clients can
show when lower-priority attention rows are hidden.

```json
{
  "object": "project_health",
  "data": {
    "project_id": "proj_...",
    "generated_at": "2026-06-20T12:00:00Z",
    "read_backend": "cairnline",
    "summary": {
      "attention_count": 2,
      "available_attention_count": 2,
      "omitted_attention_count": 0,
      "attention_limit": 5,
      "missing_defaults": true,
      "missing_project_root": false,
      "enabled_memory_count": 0,
      "saved_memory_count": 1,
      "enabled_context_source_count": 0,
      "pending_memory_candidate_count": 1,
      "promoted_memory_candidate_count": 0,
      "rejected_memory_candidate_count": 0,
      "pending_handoff_count": 1,
      "accepted_handoff_count": 0,
      "superseded_handoff_count": 0,
      "dismissed_handoff_count": 0,
      "review_follow_up_count": 0,
      "blocked_review_count": 0,
      "changes_requested_review_count": 0,
      "stale_or_unknown_assignment_count": 0
    },
    "attention": [
      {
        "id": "proj_...:defaults",
        "project_id": "proj_...",
        "title": "Provider/model defaults missing",
        "detail": "Native project starts and assignment chats need a default provider and model.",
        "status": "awaiting_approval",
        "action": {
          "type": "open_project_settings",
          "project_id": "proj_..."
        }
      },
      {
        "id": "memcand_...:memory-candidate",
        "project_id": "proj_...",
        "title": "Memory candidate pending review",
        "detail": "Remember project convention - generated_summary",
        "status": "awaiting_approval",
        "action": {
          "type": "review_memory_candidate",
          "project_id": "proj_...",
          "candidate_id": "memcand_..."
        },
        "candidate_id": "memcand_..."
      }
    ]
  }
}
```

Attention rows route to existing surfaces through a typed `action` object.
Supported action types are shared with Project Operations where they overlap:
`open_project_settings`, `open_memory_review`, `open_agent_presets`, `open_roles`,
`open_skills`, `open_work_item`, `open_task`, `open_activity_bucket`, and
`review_memory_candidate`. The top-level `work_item_id`, `task_id`, `run_id`,
`chat_id`, `candidate_id`, and `bucket` fields remain row metadata for compact
buttons and labels; clients should use `action` as the authority for row
activation. Clients should not mutate project state directly from a row; they
open the referenced surface and use that surface's explicit typed mutation.

#### `GET /hecate/v1/projects/{id}/setup-readiness`

Returns a read-only Project setup readiness projection for the selected
project. The endpoint decides whether the project should show first-run
onboarding, whether setup has started, and whether the empty project is ready
for first-work creation. It derives those flags from existing project roots,
defaults, context sources, custom roles, skills metadata, project memory, memory
candidates, and work items.

```json
{
  "object": "project_setup_readiness",
  "data": {
    "project_id": "proj_...",
    "generated_at": "2026-06-20T12:00:00Z",
    "read_backend": "cairnline",
    "show_onboarding": true,
    "setup_started": false,
    "first_work_ready": false,
    "summary": {
      "work_item_count": 0,
      "role_count": 0,
      "skill_count": 0,
      "enabled_context_source_count": 0,
      "saved_memory_count": 0,
      "pending_memory_candidate_count": 0,
      "has_purpose": true,
      "has_active_root": true,
      "missing_defaults": false
    },
    "primary_action": {
      "type": "bootstrap_project",
      "project_id": "proj_...",
      "label": "Set up project"
    },
    "checks": [
      {
        "id": "workspace_source",
        "label": "Workspace source",
        "detail": "/Users/alice/src/hecate",
        "status": "ready"
      },
      {
        "id": "first_work_item",
        "label": "First work item",
        "detail": "Create the first reviewable work item.",
        "status": "todo",
        "action": {
          "type": "create_work_item",
          "project_id": "proj_...",
          "label": "Create work"
        }
      }
    ]
  }
}
```

Known setup action types are `bootstrap_project`, `create_work_item`, and
`open_project_settings`. Clients should dispatch on `action.type` and validate
`project_id` before routing the operator. A stale or unsupported action should
surface a refresh error rather than performing a guessed fallback.
For a zero-work project, `primary_action` is `create_work_item` when setup is
already ready or when no active workspace can provide local setup inputs;
otherwise it is `bootstrap_project`.

#### `GET /hecate/v1/projects/{id}/operations/brief`

Returns a read-only Project Operations brief for the selected project. The
brief is an operator-facing triage layer over existing project state: launch
defaults, the project activity buckets, work items without assignments, pending
handoffs, pending memory candidates, review artifacts that need follow-up,
missing completion evidence, and work items ready for closeout. When none of
those operations exists, the server may return a low-priority `open_latest_work`
orientation item so the operator can reopen the most recently updated work item
without clients deriving their own fallback cascade. It is bounded and
deterministic; it does not create tasks, runs, chats, assignments, handoffs,
proposals, memory entries, or memory candidates, and it never starts queued
work.
The eight-item cap is applied after sorting by priority, explicit operation
kind urgency, recency, and stable ID, so truncation is part of the operator
priority policy. The summary reports the returned item count, available item
count before the cap, omitted item count, and current item limit so clients can
show when lower-priority operations are hidden.

Each item has a `kind` that explains why it appears and an `action` that is the
typed client routing contract. Clients should dispatch on `action.type`, not on
`kind` or `target.surface`. `target` remains descriptive context for existing
Hecate surfaces (`project_settings`, `work`, or `memory`) and for summaries
copied from the existing project APIs. For `open_work_item`, `action` may carry
`assignment_id`, `artifact_id`, or `handoff_id` so the client can open the work
item and focus the exact assignment, review artifact, or handoff. `target` may
mirror those fields for display compatibility, but it is never an alternate
routing source. Clients should fail closed and request a refresh if a populated
descriptive target disagrees with the typed action. These identifiers are
routing targets, not permission to mutate the record.
When several operations target one work item, clients may pin the exact item
the operator selected. Once a later, successfully loaded brief removes that
item, clients should continue with the next operation in server order rather
than preserving a local priority or a dead selection.

Known action types are:

- `open_project_settings`
- `open_work_item`
- `open_assignment_preflight`
- `open_memory_review`
- `open_agent_presets`
- `open_roles`
- `open_skills`
- `open_task`
- `open_activity_bucket`
- `review_memory_candidate`
- `draft_project_proposal`

Actions do not directly mutate project state. `open_assignment_preflight` opens
the existing assignment launch preflight before any start. `draft_project_proposal`
uses `action.request` and the normal Project Assistant draft/propose/apply flow,
where the operator reviews the typed proposal before any durable mutation.

For example, a review follow-up operation preserves its artifact target in both
places used by current clients:

```json
{
  "kind": "review_follow_up",
  "target": {
    "surface": "work",
    "project_id": "proj_...",
    "work_item_id": "work_...",
    "artifact_id": "artifact_..."
  },
  "action": {
    "type": "open_work_item",
    "project_id": "proj_...",
    "work_item_id": "work_...",
    "artifact_id": "artifact_..."
  }
}
```

```json
{
  "object": "project_operations_brief",
  "data": {
    "project_id": "proj_...",
    "generated_at": "2026-06-20T12:00:00Z",
    "read_backend": "cairnline",
    "summary": {
      "item_count": 2,
      "available_item_count": 2,
      "omitted_item_count": 0,
      "item_limit": 8,
      "high_count": 1,
      "medium_count": 1,
      "low_count": 0,
      "pending_memory_candidate_count": 3,
      "pending_handoff_count": 1
    },
    "items": [
      {
        "id": "approve_assignment:proj_...:asgn_...",
        "kind": "approve_assignment",
        "priority": "high",
        "title": "Review pending approval: Backend substrate",
        "detail": "1 approval pending",
        "action_label": "Open approval",
        "status": "awaiting_approval",
        "target": {
          "surface": "work",
          "project_id": "proj_...",
          "work_item_id": "work_...",
          "assignment_id": "asgn_...",
          "activity_bucket": "blocked"
        },
        "action": {
          "type": "open_work_item",
          "project_id": "proj_...",
          "work_item_id": "work_...",
          "assignment_id": "asgn_...",
          "activity_bucket": "blocked"
        }
      },
      {
        "id": "review_memory_candidates:proj_...",
        "kind": "review_memory_candidates",
        "priority": "medium",
        "title": "Review memory candidates",
        "detail": "Promote, edit, or reject pending memory candidates before they become stale.",
        "action_label": "Review memory",
        "status": "pending",
        "target": {
          "surface": "memory",
          "project_id": "proj_..."
        },
        "action": {
          "type": "open_memory_review",
          "project_id": "proj_..."
        },
        "metadata": {
          "candidate_count": "3"
        }
      }
    ]
  }
}
```

#### `GET /hecate/v1/projects/{id}/skills`

```json
{
  "object": "project_skills",
  "data": [
    {
      "id": "backend",
      "project_id": "proj_...",
      "read_backend": "cairnline",
      "title": "Backend",
      "description": "Build backend changes.",
      "path": ".hecate/skills/backend/SKILL.md",
      "root_id": "root_...",
      "format": "skill_md",
      "suggested_tools": ["git.diff", "file.read"],
      "required_permissions": {
        "tools": true,
        "writes": false,
        "network": false
      },
      "enabled": true,
      "status": "available",
      "trust_label": "workspace_skill",
      "source_context_source_ids": ["ctx_agents"],
      "warnings": [],
      "discovered_at": "2026-06-10T12:00:00Z",
      "created_at": "2026-06-10T12:00:00Z",
      "updated_at": "2026-06-10T12:00:00Z"
    }
  ]
}
```

#### `POST /hecate/v1/projects/{id}/skills/discover`

Refreshes the project skills registry from active absolute project roots.
In native-authoritative mode, Hecate's native scanner scans:

- `.agents/skills/*/SKILL.md`
- `.cairnline/skills/*/SKILL.md`
- `.claude/skills/*/SKILL.md`
- `.gemini/skills/*/SKILL.md`
- `.hecate/skills/*/SKILL.md`
- local skill roots explicitly linked from enabled guidance context sources,
  including `AGENTS.md`, `CLAUDE.md`, and `GEMINI.md`.

Discovery ignores nested worktree containers such as `.worktrees` and
`.claude/worktrees` when reading guidance-linked skill roots. Add a linked
worktree as its own project root when the operator wants it represented.

Only safe metadata is parsed from bounded `SKILL.md` files: frontmatter
`name`/`title`, `description`, optional `hecate.suggested_tools`, optional
`hecate.required_permissions.{tools,writes,network}`, then H1/title fallback and
directory id. Skill IDs are derived from the skill directory name using the same
portable form as Cairnline: lowercase, hyphen-separated separators, with
underscores preserved. Suggested-tool lists are normalized, de-duplicated,
capped before storage/API exposure, and summarized in operator-facing text.
Duplicate ids become `status: "conflict"` records with warnings. Previously
persisted skills not found in the latest discovery become `status: "missing"`.
Operator edits to `enabled`, `title`, `description`, and `trust_label` are
preserved across rediscovery.

Skill capability metadata is advisory. Skills do not grant tools, writes,
network access, approval bypasses, script execution, or memory writes. During
assignment launch planning, Hecate compares resolved project skills with the
resolved agent preset and surfaces mismatches as launch-readiness and
context-inspector warnings for operator review.

#### `PATCH /hecate/v1/projects/{id}/skills/{skill_id}`

Updates operator-owned skill metadata:

```json
{
  "enabled": false,
  "title": "Backend Lead",
  "description": "Operator-curated backend posture.",
  "trust_label": "workspace_skill"
}
```

Returns `{ "object": "project_skill", "data": { ... } }`.

Skill status values are `available`, `missing`, `invalid`, and `conflict`.

#### `GET /hecate/v1/projects/{id}/roles`

Lists built-in roles plus custom roles for the project.

```json
{
  "object": "project_roles",
  "data": [
    {
      "id": "architect",
      "project_id": "proj_...",
      "name": "Architect",
      "description": "Owns technical direction, boundaries, and system trade-offs.",
      "default_driver_kind": "hecate_task",
      "default_agent_profile": "architecture",
      "built_in": true,
      "read_backend": "cairnline"
    },
    {
      "id": "role_...",
      "project_id": "proj_...",
      "name": "Release captain",
      "description": "Coordinates release work.",
      "instructions": "Keep release notes current.",
      "default_driver_kind": "hecate_task",
      "default_provider": "ollama",
      "default_model": "ministral-3:latest",
      "default_agent_profile": "implementation",
      "skill_ids": ["release"],
      "built_in": false,
      "read_backend": "cairnline",
      "created_at": "2026-06-03T12:00:00Z",
      "updated_at": "2026-06-03T12:00:00Z"
    }
  ]
}
```

#### `POST /hecate/v1/projects/{id}/roles`

Creates a custom role. `name` is required. `id` is optional; Hecate generates a
`role_...` ID when omitted. Built-in role IDs cannot be created, updated, or
deleted as custom roles. Role defaults are execution hints: `default_driver_kind`
can seed new assignment driver kind, and `default_provider`, `default_model`,
and `default_agent_profile` can seed native task/chat launches before project
defaults are used. Provider, model, and preset hints are stored as supplied
and are not validated against the live provider catalog when the role is saved;
stale or unroutable values fail later when an assignment or chat launch uses
them. `skill_ids` are references to the project skills registry. Missing,
disabled, or conflicting skills warn at assignment start; they do not block the
assignment.

```json
{
  "name": "Release captain",
  "description": "Coordinates release work.",
  "instructions": "Keep release notes current.",
  "default_driver_kind": "hecate_task",
  "default_provider": "ollama",
  "default_model": "ministral-3:latest",
  "default_agent_profile": "implementation",
  "skill_ids": ["release"]
}
```

Returns `{ "object": "project_role", "data": { ... } }`.
Create and update responses are labelled with `read_backend: "cairnline"`
because Cairnline is the project-role authority.

#### `PATCH /hecate/v1/projects/{id}/roles/{role_id}`

Updates a custom role's `name`, `description`, `instructions`, `skill_ids`, or
role default execution hints. Built-in roles return `409 conflict`.

#### `DELETE /hecate/v1/projects/{id}/roles/{role_id}`

Deletes a custom role. Built-in roles return `409 conflict`.

#### `GET /hecate/v1/projects/{id}/work-items`

#### `POST /hecate/v1/projects/{id}/work-items`

Creates a project-scoped work item. `title` is required. `status` defaults to
`backlog`; `priority` defaults to `normal` and accepts `low`, `normal`, `high`,
or `urgent`.

```json
{
  "title": "Backend substrate",
  "brief": "Persist coordination metadata only.",
  "status": "ready",
  "priority": "high",
  "owner_role_id": "software_developer",
  "root_id": "root_...",
  "reviewer_role_ids": ["architect", "reviewer_qa"]
}
```

Returns:

```json
{
  "object": "project_work_item",
  "data": {
    "id": "work_...",
    "project_id": "proj_...",
    "read_backend": "cairnline",
    "title": "Backend substrate",
    "brief": "Persist coordination metadata only.",
    "status": "ready",
    "priority": "high",
    "owner_role_id": "software_developer",
    "root_id": "root_...",
    "reviewer_role_ids": ["architect", "reviewer_qa"],
    "created_at": "2026-06-03T12:00:00Z",
    "updated_at": "2026-06-03T12:00:00Z"
  }
}
```

Create and update responses are labelled with `read_backend: "cairnline"`
because Cairnline is the portable work-item authority.

#### `GET /hecate/v1/projects/{id}/work-items/{work_item_id}`

Returns one work item from embedded Cairnline or `404 not_found`, enriched with
Hecate assignment-runtime projection where execution references exist.

#### `GET /hecate/v1/projects/{id}/work-items/{work_item_id}/readiness`

Returns the read-only closeout readiness contract for one work item. This is
the same server-side decision path used by Project Operations when it surfaces
review follow-up, missing completion evidence, or closeout-ready items.

```json
{
  "object": "project_work_item_readiness",
  "data": {
    "project_id": "proj_...",
    "work_item_id": "work_...",
    "read_backend": "cairnline",
    "ready": false,
    "status": "blocked",
    "title": "Closeout is blocked",
    "detail": "Resolve the listed assignment, evidence, handoff, or review follow-up items before marking this work done.",
    "blockers": [
      "1 completed assignment is missing evidence",
      "Review follow-up \"Architecture review\" is not triaged"
    ],
    "warnings": [],
    "assignment_count": 1,
    "completed_assignments": 1,
    "review_follow_up_count": 1,
    "review_follow_ups": [
      {
        "artifact_id": "artifact_...",
        "title": "Architecture review",
        "status": "needs_path",
        "blocker": "Review follow-up \"Architecture review\" is not triaged",
        "reviewed_assignment_id": "asgn_...",
        "review_verdict": "changes_requested",
        "review_risk": "medium"
      }
    ],
    "open_handoff_ids": ["handoff_..."],
    "missing_evidence_assignment_ids": ["asgn_..."]
  }
}
```

`review_follow_ups` lists review artifacts that still need an explicit
follow-up path. Clients should use this server field for closeout notices and
Project Assistant draft shortcuts instead of deriving readiness from raw
artifact fields. `review_follow_up_artifact_ids` may also be present for compact
artifact-id consumers. `open_handoff_ids` lists pending handoff records that
still require an operator decision. Clients should use these structured IDs,
together with `missing_evidence_assignment_ids`, to focus follow-through
controls; blocker strings remain display copy and must not be parsed as routing
or business logic.

#### `PATCH /hecate/v1/projects/{id}/work-items/{work_item_id}`

Updates `title`, `brief`, `status`, `priority`, `owner_role_id`, `root_id`, or
`reviewer_role_ids`. An empty `root_id` clears the work-item root override.
When `status` is set to `done`, the server validates the same closeout readiness
contract returned by
`GET /hecate/v1/projects/{id}/work-items/{work_item_id}/readiness`. If blockers
remain, the update returns `409 conflict` with a `readiness` object in the error
body. Other work-item edits are not blocked by closeout readiness. A successful
`status="done"` update is the authoritative closeout transition; clients should
render completed work read-only while preserving its assignments, reviews,
evidence, handoffs, and runtime links for inspection.

#### `DELETE /hecate/v1/projects/{id}/work-items/{work_item_id}`

Deletes the work item and its assignments and collaboration artifacts.

#### `GET /hecate/v1/projects/{id}/work-items/{work_item_id}/assignments`

#### `POST /hecate/v1/projects/{id}/work-items/{work_item_id}/assignments`

Creates an assignment metadata record. `role_id` is required. `driver_kind`
defaults to `hecate_task`. Optional execution links are stored under
`execution_ref` only.

```json
{
  "role_id": "software_developer",
  "root_id": "root_...",
  "driver_kind": "hecate_task",
  "execution_ref": {
    "kind": "task_run",
    "task_id": "task_...",
    "run_id": "run_...",
    "context_snapshot_id": "ctx_..."
  }
}
```

Returns:

```json
{
  "object": "project_assignment",
  "data": {
    "id": "asgn_...",
    "project_id": "proj_...",
    "work_item_id": "work_...",
    "role_id": "software_developer",
    "root_id": "root_...",
    "driver_kind": "hecate_task",
    "status": "queued",
    "execution_ref": {
      "kind": "task_run",
      "task_id": "task_...",
      "run_id": "run_...",
      "status": "queued"
    },
    "execution": {
      "task_id": "task_...",
      "run_id": "run_...",
      "task_status": "queued",
      "run_status": "queued",
      "status": "queued"
    },
    "created_at": "2026-06-03T12:00:00Z",
    "updated_at": "2026-06-03T12:00:00Z"
  }
}
```

#### `PATCH /hecate/v1/projects/{id}/work-items/{work_item_id}/assignments/{assignment_id}`

Updates assignment status, role, `root_id`, link fields, `started_at`, or
`completed_at`. An empty `root_id` clears the assignment root override. It does
not mutate or start the linked Task or Chat.
For a `manual` assignment, terminal status changes use Cairnline's completion
transition so authoritative start/completion timestamps remain portable. A
queued-to-running PATCH returns `409 conflict`; the dedicated `/start` action is
the sole queued-start path and claims the assignment before recording progress.
Running Human work can move to `awaiting_approval` and resume to `running`
through status-only PATCH requests. Human assignment details are editable only
while the portable row remains queued, unclaimed, and free of execution links.
The UI saves a queued Human progress change separately from destination edits;
selecting cancellation resets and locks unsaved responsibility, destination,
and workspace changes before confirmation.
`failed` and `cancelled` are terminal Cairnline outcomes and currently remain
closeout blockers; this API does not invent a local retry or supersession state.

#### `DELETE /hecate/v1/projects/{id}/work-items/{work_item_id}/assignments/{assignment_id}`

Deletes the assignment metadata record and collaboration artifacts attached to
that assignment. It does not delete or cancel a linked Task, Run, Chat session,
or external-agent execution.

#### `GET /hecate/v1/projects/{id}/work-items/{work_item_id}/assignments/{assignment_id}/context`

Returns the best available context packet for the assignment. Hecate resolves
linked Task/Run packets first, then falls back to the assignment-stored packet
created by an External Agent start, then to a linked Chat `chat_session_id` +
`message_id` from `execution_ref` when present.

The endpoint first checks Hecate's assignment runtime overlay for a persisted
task/chat execution context packet whose refs match the requested project, work
item, and assignment. When that snapshot exists, it is returned so assignment
context matches the launched execution. Before start, the endpoint returns the
inspect-only assignment context assembled from embedded Cairnline. Older
executions that predate context snapshots may return `404 not_found`. The
Projects cockpit uses this endpoint for the assignment
`Inspect context` action so operators can inspect the resolved Agent Preset, launch
instructions, memory, project sources, work context, runtime refs, and skipped
or inspect-only items without reopening the raw task or chat transcript.

#### `GET /hecate/v1/projects/{id}/work-items/{work_item_id}/assignments/{assignment_id}/launch-readiness`

Returns a typed, read-only assignment launch readiness projection. The endpoint
does not create a Task, Run, Chat session, memory entry, artifact, or assignment
update. Hecate verifies the same launch shape used by preflight/start: project,
work item, assignment, and role identity; queued/startable status; stored driver
support; active execution; workspace/root resolution; Agent Preset and skill
resolution; native provider/model readiness; and External Agent adapter/options
resolution, passive app availability, and exact executable identity approval.

In strict embedded mode, the endpoint reads the launch packet directly from the
embedded Cairnline database and does not require a matching Hecate-native
project, work item, assignment, or role row.

Human (`manual`) assignments do not have launch configuration. The Projects UI
does not call this endpoint for them; callers receive a blocked projection that
directs the operator to start work from the work item.

The response envelope is:

```json
{
  "object": "project_assignment_launch_readiness",
  "data": {
    "project_id": "proj_123",
    "work_item_id": "work_123",
    "assignment_id": "asgn_123",
    "read_backend": "cairnline",
    "ready": false,
    "status": "blocked",
    "title": "Launch is blocked",
    "detail": "Resolve the listed launch blockers before starting or preparing this assignment.",
    "blockers": ["No routable provider reports model \"dogfood-model\"."],
    "warnings": [],
    "driver_kind": "hecate_task",
    "workspace": "/Users/alice/dev/hecate",
    "root_id": "root_main",
    "provider": "",
    "model": "dogfood-model",
    "execution_profile": "implementation",
    "profile_posture": {
      "id": "implementation",
      "name": "Implementation",
      "source": "role_default",
      "tools_enabled": true,
      "writes_allowed": true,
      "network_allowed": false,
      "browser_evidence_status": "enabled",
      "browser_allowed": true,
      "browser_interaction_status": "enabled",
      "browser_interactions_allowed": true,
      "browser_allowed_origins": ["https://qa.example.test"],
      "browser_runtime_readiness": {
        "available": true,
        "status": "working",
        "message": "Browser worked successfully during this Hecate session. Each call still requires a Work policy and approval."
      },
      "approval_policy": "require",
      "project_memory_policy": "include",
      "context_source_policy": "include_enabled"
    },
    "model_readiness": {
      "ready": false,
      "status": "blocked",
      "reason": "model_not_discovered",
      "message": "No routable provider reports model \"dogfood-model\".",
      "operator_action": "Pick one of the discovered models."
    }
  }
}
```

Native Hecate Task assignments may include `model_readiness`, using the same
reason and repair vocabulary as `metadata.readiness` on `/v1/models`. External
Agent assignments include `external_agent_id`, `external_agent`, and
`session_title` when the adapter/options resolve. They are blocked when a
required remote-runtime credential is missing, the app is missing, its identity
cannot be measured, approval is absent, or its current identity no longer
matches the approved identity; readiness inspection never executes the app.
Assignments with a resolved
Agent Preset include `profile_posture`, a read-only summary of the selected
preset's tools, writes, network, browser, approval, memory, and context-source
posture. Native Hecate tasks report `browser_evidence_status` and
`browser_interaction_status` independently as `enabled`, `disabled`, or
`unavailable`. `unavailable` means the preset grants that tool but the current
runtime will omit it because the local browser is unconfigured, invalid, or the
gateway is running in remote-runtime mode. In that case,
`browser_runtime_readiness` carries the same path-free `status`, `message`, and
`operator_action` repair contract as Settings, and `warnings` names the omitted
`browser_inspect` and/or `browser_flow` tool. Browser runtime unavailability is
a warning rather than an assignment-launch blocker; the task may still start
with the rest of its effective catalog.
`browser_allowed` and `browser_interactions_allowed` expose the corresponding
immutable preset grants even when the runtime will omit the tool. When either
is granted, `browser_allowed_origins` contains the shared exact origins that
will be copied into the Task snapshot. When `approval_policy=block` accompanies
a browser grant, `warnings` explains that otherwise-available browser calls
will be denied because every browser call requires approval; the UI presents
the configured capability as blocked rather than treating the status field
alone as effective permission. External Agent
assignments always report both statuses as `not_applicable` with neither grant
nor origins and omit `browser_runtime_readiness`, even if the reusable `any`
preset permits native-task browser capabilities. An incompatible preset surface
is a launch blocker. For native Hecate tasks, the displayed write/network
values, browser grant/origin values, and approval value are also the values that
will be snapshotted into the created Task's runtime policy; the browser status
fields describe whether this runtime can expose the corresponding tools before
the additive approval layer is considered. An approval value returned for an
External Agent profile is inspection metadata only: Hecate does not apply it
to the vendor process or replace the ACP permission controls.
`ready=false` is the UI gate for **Start assignment** and **Prepare chat**;
operators must still confirm the separate start mutation after reviewing
preflight.

#### `GET /hecate/v1/projects/{id}/work-items/{work_item_id}/assignments/{assignment_id}/preflight`

Returns a launch context packet for a queued assignment without creating or
mutating a Task, Run, Chat session, memory entry, artifact, or assignment
record. Hecate performs the same launch-shape validation used by assignment
start: project/work/assignment/role lookup, stored driver support, active
execution checks, workspace resolution, resolved Agent Preset, provider/model hints
for native assignments, External Agent adapter/options for external-agent
assignments, skill metadata resolution, and prompt-context policy metadata.
Human (`manual`) assignments return `409 conflict` because they start directly
and have no runtime launch packet.
The packet includes a `project_work` / `project_root` item describing the
selected root, path, Git branch/remote when known, and whether the root came
from an assignment override, work-item default, or project default/fallback.

The response is a normal `context_packet` envelope with assignment refs only;
task, run, chat session, and message refs remain empty because preflight is
inspect-only. The packet includes a `runtime` / `launch_preflight` item with
`included=false` describing what will be created on confirm. For native Hecate
task assignments, the packet can also include a `runtime` / `launch_readiness`
item when the gateway is wired. That item is operator evidence, not the UI
authority; clients should gate launch confirmation with the typed
`/launch-readiness` projection rather than parsing context item copy.

In strict embedded mode, preflight reads the launch packet directly from the
embedded Cairnline database and does not require a matching Hecate-native
project, work item, assignment, or role row to inspect coordination metadata.
Hecate-task launch and preflight still require Hecate-owned provider/model
defaults from the project runtime overlay; Cairnline desired-agent and skill
hints are not interpreted as provider/model configuration.

The Projects cockpit uses this endpoint before **Start assignment** and
**Prepare chat** so the operator can review the effective launch context before
dispatch. A handoff can focus its linked assignment, but it does not provide a
second launch control. The UI disables confirmation when
`/launch-readiness` reports blockers and offers repair actions for Project
Settings, Roles, Agent Presets, and Connections. Project-local actions repair
defaults that feed assignment resolution; Connections remains the
provider/model readiness surface. `POST /start` remains the authoritative
mutation path and the task runner/gateway still performs the actual route
checks during execution.

Unqueued, terminal, already-linked, unsupported, misconfigured, or invalid
assignments return the same operator-facing error classes as start would use,
without causing launch side effects.

#### `POST /hecate/v1/projects/{id}/work-items/{work_item_id}/assignments/{assignment_id}/start`

Starts a project assignment through its stored driver. The request body is
optional. When present, `driver_kind` must match the stored assignment driver.

```json
{
  "driver_kind": "hecate_task"
}
```

For `driver_kind="hecate_task"`, starting verifies that the project, work item,
assignment, and role exist, then
creates a normal Task with `execution_kind="agent_loop"`,
`origin_kind="project_work_item"`, and `origin_id` set to the work item ID. The
task response also exposes `work_item_id`, `assignment_id`, and
`agent_preset_id` for direct inspection. It snapshots the preset's effective
tools posture into `agent_preset_tools_enabled`, approval posture into
`agent_preset_approval_policy`, and write/network posture into
`sandbox_read_only` and `sandbox_network`. The approval snapshot is the
Work-policy-backed additive mid-loop policy described under
[Work policy endpoints](#work-policy-endpoints); it does not modify
pre-execution approval. The
created run snapshots `project_id`, `work_item_id`, and `assignment_id`
directly on the run payload. The
task title, prompt, and system prompt are composed from a visible launch-context
block covering project, work item, assignment, role, execution hints, role
defaults, project defaults, and any preset-activated prompt context. Project
assignment tasks set `workspace_system_prompt_policy="exclude"` so the legacy
root `CLAUDE.md` / `AGENTS.md` compatibility layer cannot bypass preset
context-source policy. Role default provider/model/preset override
project defaults for the backing task when configured; project
provider/model/workspace settings remain the fallback. Provider and model
defaults are route hints, so catalog/routing validation happens during task
start instead of role save. Preflight snapshots the selected model's current
readiness so the operator can fix stale provider/model defaults before a task
and run are created. The workspace root must
resolve to an absolute existing project root before a task is created; missing
or defaultless roots return `400 invalid_request`. A missing model returns
`422 model_not_configured`.

The endpoint then starts the task through the canonical task runner, so normal
task approvals, queueing, run events, artifacts, and SSE inspection apply. On
success it also persists a structured context packet on the created run, updates
`execution_ref.context_snapshot_id` to that packet id, then updates the
assignment with `execution_ref.task_id`, latest `execution_ref.run_id`, status,
and timestamps before returning the updated assignment:

The persisted context packet records the resolved Agent Preset and applies its
project memory/context-source policies. For Hecate task assignments, it also
records the same `runtime` / `launch_readiness` metadata captured by preflight
so later run-context inspection can show what provider/model readiness looked
like when the assignment was started. The packet also includes the same
inspect-only `runtime` / `cairnline_launch_packet` evidence captured by
preflight. Hecate owns task creation, route checks, approvals, and execution;
Cairnline owns the coordinated assignment lifecycle. `include` /
`include_enabled` make the
enabled project records active in the packet and add a `prompt_context`
instructions item summarizing what was loaded into the native assignment prompt.
`visible_only` / `inherit` keep records inspect-only, and `exclude` omits them
so memory bodies are not snapshotted. Prompt context is capped at 12 KiB total,
2 KiB per memory entry, and 8 KiB per source body. Only enabled
`workspace_instruction` sources with `format="agents_md"` are body-loaded through
WorkspaceFS; host-specific sources remain metadata-only and produce inspector
warnings when skipped. If the resolved provider is a cloud route, included
memory and workspace-instruction bodies leave the local machine as part of the
model request.

```json
{
  "object": "project_assignment",
  "data": {
    "id": "asgn_...",
    "project_id": "proj_...",
    "work_item_id": "work_...",
    "role_id": "software_developer",
    "driver_kind": "hecate_task",
    "status": "queued",
    "execution_ref": {
      "kind": "task_run",
      "task_id": "task_...",
      "run_id": "run_...",
      "context_snapshot_id": "ctx_...",
      "status": "queued"
    },
    "execution": {
      "task_id": "task_...",
      "run_id": "run_...",
      "task_status": "queued",
      "run_status": "queued",
      "status": "queued"
    },
    "created_at": "2026-06-03T12:00:00Z",
    "updated_at": "2026-06-03T12:00:01Z",
    "started_at": "2026-06-03T12:00:01Z"
  }
}
```

For `driver_kind="external_agent"`, starting prepares a supervised External
Agent chat session without sending the assignment prompt. The resolved Agent
Preset must name an `external_agent_kind` such as `codex`, `claude_code`,
`cursor_agent`, or `grok_build`; preset `external_agent_options` may set
Hecate-owned launch controls for that adapter. Hecate validates the project
workspace root, creates and prepares the chat session through the External Agent
supervisor, stores a project assignment context packet on the assignment, and
links `execution_ref.chat_session_id` plus
`execution_ref.context_snapshot_id`. Task-run fields and `message_id` remain
empty until the operator sends a turn in the linked chat. Project deletion uses
the same chat-creation admission gate as direct chat creation: an admitted
start finishes linking before cleanup proceeds, while a start that
predates or overlaps cleanup but has not been admitted returns
`409 chat.session_create_conflict`. Refresh project, work, and chat state before
an explicit retry.

```json
{
  "object": "project_assignment",
  "data": {
    "id": "asgn_...",
    "project_id": "proj_...",
    "work_item_id": "work_...",
    "role_id": "software_developer",
    "driver_kind": "external_agent",
    "status": "running",
    "execution_ref": {
      "kind": "chat_session",
      "chat_session_id": "chat_...",
      "context_snapshot_id": "ctx_...",
      "status": "running"
    },
    "created_at": "2026-06-03T12:00:00Z",
    "updated_at": "2026-06-03T12:00:01Z",
    "started_at": "2026-06-03T12:00:01Z"
  }
}
```

For `driver_kind="manual"`, starting uses Cairnline's claim and progress
transitions with claimant `hecate_operator`, returns the running assignment,
and creates no Task, Run, Chat, context snapshot, or execution reference. The
project and work item may be rootless. Repeated or conflicting starts return
`409` without duplicating lifecycle state. A pristine interrupted claim by the
same operator may be finished safely; a claim with an execution ref or context
snapshot is treated as prepared elsewhere and still returns `409`.
Start revalidation compares the claimed row with the assignment's portable
coordination snapshot, including desired skills. Later role-skill edits do not
rewrite that snapshot or make an existing assignment unstartable.

Repeated starts for an assignment that already has an active execution return
`409` with the current assignment envelope and do not create another task/run.
Assignments in terminal states (`completed`, `failed`, `cancelled`) also return
`409`. If task creation succeeds but task start fails, Hecate keeps the
assignment's `execution_ref.task_id`, marks the assignment `failed`, and returns
an error so the operator can inspect the linked task instead of losing the
partial state.

#### `GET /hecate/v1/projects/{id}/handoffs`

#### `GET /hecate/v1/projects/{id}/work-items/{work_item_id}/handoffs`

Lists structured Cairnline handoff records for one work item, sorted by latest
update time, newest first.

```json
{
  "object": "project_handoffs",
  "data": [
    {
      "id": "handoff_...",
      "project_id": "proj_...",
      "work_item_id": "work_...",
      "source_assignment_id": "asgn_...",
      "source_run_id": "run_...",
      "source_chat_session_id": "chat_...",
      "source_message_id": "msg_...",
      "target_role_id": "reviewer_qa",
      "target_assignment_id": "asgn_review_...",
      "target_work_item_id": "work_followup_...",
      "title": "QA handoff",
      "summary": "The implementation is ready for review.",
      "recommended_next_action": "Review the changed files and run the focused checks.",
      "linked_artifact_ids": ["art_..."],
      "linked_memory_ids": ["mem_..."],
      "context_refs": ["ctx_..."],
      "status": "pending",
      "provenance_kind": "agent_draft",
      "trust_label": "operator_reviewed",
      "created_by_role_id": "software_developer",
      "created_at": "2026-06-03T12:00:00Z",
      "updated_at": "2026-06-03T12:00:00Z",
      "status_changed_at": "2026-06-03T12:00:00Z"
    }
  ]
}
```

#### `POST /hecate/v1/projects/{id}/work-items/{work_item_id}/handoffs`

Creates a handoff. `title`, `summary`, and `recommended_next_action` are
required. `status` defaults to `pending`, `provenance_kind` defaults to
`operator`, and `trust_label` defaults to `operator_reviewed`. A source
assignment, if supplied, must belong to the handoff's work item. A target
assignment can belong to another work item when `target_work_item_id` names
that work item. Linked artifact IDs, memory IDs, and context refs are stored as
references only; creating a handoff does not write memory, inject context,
start a task, or open a chat.
The Projects UI can use a handoff's target role/work-item hints with the
dedicated atomic accept-with-follow-up endpoint below. That operation remains
operator-controlled and never starts the assignment. Source assignment,
run, chat, message, and context refs remain on the handoff as provenance rather
than being copied into the follow-up assignment as if they were its own
execution links.

```json
{
  "source_assignment_id": "asgn_...",
  "target_role_id": "reviewer_qa",
  "title": "QA handoff",
  "summary": "The implementation is ready for review.",
  "recommended_next_action": "Create a queued QA assignment and run focused UI tests.",
  "linked_artifact_ids": ["art_..."],
  "linked_memory_ids": ["mem_..."],
  "context_refs": ["ctx_..."],
  "provenance_kind": "agent_draft",
  "trust_label": "operator_reviewed",
  "created_by_role_id": "software_developer"
}
```

Returns `{ "object": "project_handoff", "data": { ... } }`.

#### `PATCH /hecate/v1/projects/{id}/work-items/{work_item_id}/handoffs/{handoff_id}`

Updates handoff refs, target hints, text fields, linked IDs, provenance/trust
metadata, or `status`. The body must include `expected_updated_at` with the
exact `updated_at` revision that was read; omitted fields are preserved. Status
changes update `status_changed_at`. In the supported Cairnline-backed Projects
configuration, a stale revision returns `409` without overwriting a newer
handoff. The revision field remains required in legacy compatibility
configurations, but those configurations are not a concurrency-authority
contract and should not be used for operator coordination.

#### `POST /hecate/v1/projects/{id}/work-items/{work_item_id}/handoffs/{handoff_id}/status`

Transitions only the handoff status. The body is
`{ "status": "accepted", "expected_updated_at": "..." }`, where status is
one of `pending`, `accepted`, `superseded`, or `dismissed` and the revision is
the exact handoff `updated_at` that was read. Accepting a handoff records
operator intent; it does not automatically start a linked assignment. A stale
revision returns `409` for Cairnline-backed Projects.

#### `POST /hecate/v1/projects/{id}/work-items/{work_item_id}/handoffs/{handoff_id}/accept-with-follow-up`

Explicitly accepts a handoff and ensures one linked follow-up assignment in one
Cairnline transaction:

```json
{
  "expected_updated_at": "2026-06-03T12:00:00Z",
  "idempotency_key": "9bcf9f16-9b28-4da5-987f-9c602ac46a38",
  "intent": "accept_and_ensure_follow_up"
}
```

The handoff must name a target role. When no assignment is linked, Cairnline
derives the target work item, root, execution mode, and role skills from the
portable project graph and creates a pristine queued assignment. An existing
linked assignment is returned in its current authoritative state, including a
state that has already progressed or finished. The command never claims,
prepares, or launches work.

Use one stable `idempotency_key` for retries of the same operator action. The
response preserves the original outcome and assignment identity while returning
the current authoritative handoff and assignment:

```json
{
  "object": "project_handoff_follow_up",
  "data": {
    "handoff": { "id": "handoff_...", "status": "accepted" },
    "assignment": { "id": "asgn_...", "status": "queued" },
    "outcome": "created",
    "replayed": false
  }
}
```

`outcome` is `created`, `linked_existing`, or `already_satisfied`. A stale
revision, a closed or later-relinked handoff, or reuse of the key for another
request returns `409`. Hecate updates its runtime-facing projections only after
the portable transaction succeeds, so this endpoint does not expose a partially
linked result.

#### `DELETE /hecate/v1/projects/{id}/work-items/{work_item_id}/handoffs/{handoff_id}`

Deletes the handoff record. The JSON body must contain
`{ "expected_updated_at": "..." }` with the exact revision that was read; a
stale revision returns `409` for Cairnline-backed Projects. Deletion does not
delete linked artifacts, memory entries, tasks, runs, chats, work items, or
assignments.

#### `GET /hecate/v1/projects/{id}/work-items/{work_item_id}/artifacts`

#### `POST /hecate/v1/projects/{id}/work-items/{work_item_id}/artifacts`

Creates a collaboration artifact. `kind` and `body` are required.
`assignment_id` is optional; when supplied it must refer to an assignment on
the same work item.

The Projects cockpit uses `kind="review"` artifacts to record reviewer outcomes
after a review assignment. In V1 the cockpit exposes this action only for
assignments whose role appears in the work item's `reviewer_role_ids`; callers
can still create any collaboration artifact through this endpoint. The current
V1 body is Markdown-compatible text with verdict, risk, summary, verification,
and follow-up sections, and review artifacts may also carry structured review
metadata:

The review verdict/risk enum values are validated by the runtime and mirrored
by the Projects UI picker.

Hecate records these fields for filtering and operator triage, but does not
mutate work-item status or auto-dispatch follow-up work from the verdict.
Operators can create a separate handoff from the review artifact when follow-up
is needed. The UI can prefill that handoff from the review and then offer the
explicit atomic accept-with-follow-up action; neither step starts the assignment
automatically.

The Projects cockpit uses `kind="evidence_link"` artifacts to attach generic
external or local evidence to a work item. Evidence links are intentionally not
GitHub- or code-specific: a link can point at a source document, research
artifact, ticket, deployment, pull request, design file, meeting note, or any
other operator-provided reference. Evidence link metadata is stored only as
project provenance; Hecate does not fetch the URL, grant access to the external
system, or treat the provider as policy authority. Evidence links may carry:

- `evidence_source_kind` — free-form source category such as `source_document`,
  `pull_request`, `ticket`, `deployment`, `design_file`, or `meeting_note`.
- `evidence_url` — optional URL or locator string. Hecate stores this
  operator-provided value as-is; clients must validate the scheme before
  rendering it as a clickable link.
- `evidence_external_id` — optional external identifier when a URL is not the
  best reference.
- `evidence_provider` — optional source system label such as `github`, `figma`,
  `jira`, `docs`, or `local`.
- `evidence_trust_label` — provenance/trust label, defaulting to
  `operator_provided`.

An evidence link requires `body` plus either `evidence_url` or
`evidence_external_id`. Non-evidence artifacts clear these evidence fields on
write.

```json
{
  "kind": "handoff",
  "assignment_id": "asgn_...",
  "title": "Backend handoff",
  "body": "Store and API are ready for UI wiring.",
  "author_role_id": "software_developer"
}
```

## Project Assistant endpoints

Project Assistant is the API-first assistant-action foundation for project
operations. It does not expose an open-ended chat persona. Clients can ask the
server to draft a reviewable proposal from project context, or submit a typed,
allowlisted proposal directly. Operators inspect the exact changes, then
explicitly apply the proposal. Apply revalidates current server state before
mutating projects, chats, project work, or memory candidates.

Apply is a human-gated operation. Do not wire it as a direct model-callable tool
without an explicit blocking operator confirmation. Before mutating durable
stores, apply preflights the remaining typed actions against current project,
work, handoff, memory-candidate, and chat targets, including explicit resources
created earlier in the same proposal. Multi-action apply is sequential and
resumable within the current process: on a failure the error includes
`apply_status`, `failed_action_index`, `total_action_count`,
`committed_action_count`, `resume_action_index`, and `partial_result`.
`apply_status` matches `partial_result.status`: `blocked_before_apply` or
`partial_due_to_runtime_failure`. Successful apply results use `status:
applied`. A `blocked_before_apply` result means preflight blocked the current
apply attempt before writing another action. A
`partial_due_to_runtime_failure` result means the unchanged proposal id can
resume after the committed actions. Changing the action set or reapplying a
fully applied proposal returns `409 conflict`.

Draft, propose, and apply derive every affected portable project before the
first write. Hecate atomically admits that complete process-local key set and
retains it through action and proposal-ledger writes, compatibility mirrors,
and the response decision. For `move_chat_session`, the set includes both the
chat's current project and the requested project. A concurrent deletion of any
affected project returns `409 conflict` before admission. The proposal record's
primary `project_id` is derived from and validated against its first typed
action scope rather than trusted from the HTTP request.
For a `create_project` action with no `patch.id`, Hecate uses
`target.project_id` when present; if the action is pathless, it derives a stable
id from the proposal id and action index before gate admission. The propose
response and ledger contain that canonical typed action. Clients should apply
the returned proposal unchanged. A direct apply retry with the same proposal id
derives the same project id even when a prior attempt was rejected before a
ledger write.

Endpoints:

- `POST /hecate/v1/project-assistant/context`
- `POST /hecate/v1/project-assistant/draft`
- `POST /hecate/v1/project-assistant/propose`
- `POST /hecate/v1/project-assistant/apply`
- `GET /hecate/v1/project-assistant/proposals/{id}`
- `POST /hecate/v1/chat/sessions/{id}/project-assistant/draft`

A bootstrap `draft` with no eligible workspace-guidance sources or available
project skills returns `422 project_setup_no_inputs`. Clients may offer the
server-provided first-work action as the recovery for that typed outcome. Other
draft failures retain their normal error type and should not be interpreted as
permission to replace the server-owned setup primary action.

`GET /hecate/v1/project-assistant/proposals/{id}` returns the durable proposal
record for reload/recovery flows: typed proposal, project/source metadata,
latest apply result, and apply attempts. Proposal records follow the project
operations backend and are read-only through this endpoint. Applying still
requires `POST /hecate/v1/project-assistant/apply` with `confirm: true`; the
record endpoint does not grant model-callable mutation authority.

`POST /hecate/v1/chat/sessions/{id}/project-assistant/draft` is the Chat
handoff variant for project-linked Hecate Chat sessions. The request body
accepts the deterministic draft fields `request`, optional `work_item_id`,
optional `role_id`, and optional `driver_kind`; Hecate derives the project from
the chat session and rejects unprojected or external-agent sessions. The
endpoint always uses deterministic drafting and returns
`project_assistant.proposal` data only. The operator UI exposes it through the
compact `Draft proposal` composer action and the Hecate-owned
`/proposal <request>` slash command. It does not call the model-backed draft
path, append chat messages, create project records, or apply the proposal; UI
clients should hand the response to the Projects Project Assistant review/apply
surface. Clients may carry local source metadata, such as the request text and
chat session id, for review UI navigation; that metadata is not part of the
proposal apply payload.

Task-backed project-linked Hecate Chat may also produce
`project_assistant_proposal` artifacts when the model calls the
`draft_project_proposal` agent-loop tool. The artifact content is JSON with the
linked `project_id`, optional `source_chat_session_id`, original request, and
embedded Project Assistant `proposal`. The normalized chat activity may carry
proposal title/action-count detail so clients can render a compact review row.
It is a review handoff only; clients open it in Projects and still apply through
`/hecate/v1/project-assistant/apply`.

## Chat session endpoints

### `GET /hecate/v1/chat/sessions`

Lists chat sessions. Chat sessions use the process-wide storage backend
selected by `HECATE_BACKEND`. They are the alpha transcript surface for Hecate
Chat and External Agent sessions. A session has a stable `agent_id` that
chooses the chat owner:

- `agent_id="hecate"` — Hecate owns the chat. Individual turns set
  `execution_mode="hecate_task"` and `tools_enabled` to choose between a normal
  provider/model call (`tools_enabled=false`) and a visible `agent_loop` task
  with Hecate tools, task approvals, artifacts, and OTel
  (`tools_enabled=true`). Hecate Chat sessions may opt into
  RTK command-output compaction with `rtk_enabled=true`; shell and git tool
  calls then launch as `rtk sh -lc <command>` while keeping Hecate approvals,
  policy validation, sandboxing, limits, and timeouts in place.
- `agent_id="codex"`, `"claude_code"`, `"cursor_agent"`, `"grok_build"`, or another
  registered adapter id — the external adapter owns the native session while
  Hecate supervises lifecycle, transcript, diagnostics, and external-agent
  approvals. Turns use `execution_mode="external_agent"`.

`HECATE_BACKEND=sqlite` or `postgres` selects matching persistent backends for
sessions/messages, attachment bodies, and the operator-facing approval
rows + grants documented under `/hecate/v1/chat/sessions/{id}/approvals` and
`/hecate/v1/chat/grants`. Transcript, attachment, and approval operations are
separate persistence boundaries rather than one cross-store transaction. Before
serving traffic, startup reconciliation resolves ambiguous attachment claims
against the authoritative transcript, purges attachment sessions whose owner is
gone, and flips approvals left `pending` by a prior process to
`status=timed_out` with `path=startup_reconcile`. Process-local waiters cannot
be resurrected, so the operator UI never sees an actionable pending approval
that nothing is actually blocked on.

Resolved approvals are pruned by the retention worker
(`HECATE_RETENTION_CHAT_APPROVALS_*`, default 30d / 10k). Operator-
authored grants are NOT subject to that retention — only their own
`expires_at` drives deletion, so explicit operator intent outlives normal
retention windows.

The same per-session SSE stream (`GET /hecate/v1/chat/sessions/{id}/stream`)
also carries approval lifecycle events so frontends don't have to poll. Two
event types are emitted in addition to normal chat session updates:

```
event: approval.requested
data: {
  "approval_id":   "appr_01JX...",
  "session_id":    "chat_01JX...",
  "adapter_id":    "codex",
  "tool_kind":     "file_write",
  "tool_name":     "Edit src/foo.go",
  "scope_choices": ["once","session","workspace_tool","adapter_tool"],
  "created_at":    "2026-05-04T10:23:45.123Z",
  "expires_at":    "2026-05-04T10:28:45.123Z"
}

event: approval.resolved
data: {
  "approval_id":     "appr_01JX...",
  "session_id":      "chat_01JX...",
  "status":          "approved",
  "decision":        "approve",
  "scope":           "session",
  "path":            "operator",
  "selected_option": "allow_always_for_session",
  "resolved_at":     "2026-05-04T10:24:01.000Z"
}
```

Frontends switch on the `path` field of `approval.resolved` to render the
disposition: `operator` (explicit decision), `grant` (pre-existing grant
short-circuited the prompt), `default_mode` (`auto`/`deny` mode resolved
without operator), `timeout` (prompt-mode timeout fired), or
`request_cancelled` (the owning approval/turn context ended through Stop,
session shutdown, adapter teardown, or process stop). `request_cancelled` is
operationally distinct from an explicit approval decision. Losing the
originating message POST or session SSE connection does not resolve an approval
for an already-admitted External Agent turn; a reconnecting client refetches
pending approvals.

Backpressure: per-subscriber buffers are bounded (16 events). On overflow,
approval events are **dropped** rather than blocking the coordinator. A
slow operator UI catches up by re-fetching `/approvals?status=pending` on
reconnect. Replay across restart is not supported in this slice.

```json
GET /hecate/v1/chat/sessions
→ 200
{
  "object": "chat_sessions",
  "data": [
    {
      "id": "chat_...",
      "title": "Hecate Chat",
      "project_id": "proj_...",
      "agent_id": "hecate",
      "provider": "ollama",
      "model": "qwen2.5-coder",
      "capabilities": {
        "tool_calling": "basic",
        "streaming": true,
        "source": "provider"
      },
      "agent_preset": {
        "id": "prof_...",
        "name": "Focused reviewer",
        "provider_hint": "anthropic",
        "model_hint": "claude-sonnet-4",
        "instructions": "Explain findings with evidence.",
        "execution_profile": "reviewer",
        "tools_enabled": true,
        "writes_allowed": false,
        "network_allowed": false,
        "browser_allowed": false,
        "browser_interactions_allowed": false,
        "approval_policy": "require"
      },
      "status": "completed",
      "rtk_enabled": true,
      "workspace": "/tmp/hecate-workspaces/task_.../run_...",
      "workspace_mode": "persistent",
      "turns_used": 3,
      "max_turns_per_session": 50,
      "session_started_at": "2026-05-03T12:00:00Z",
      "max_session_duration_ms": 7200000,
      "idle_timeout_ms": 1800000,
      "message_count": 2,
      "created_at": "2026-05-03T12:00:00Z",
      "updated_at": "2026-05-03T12:00:08Z"
    }
  ]
}
```

### `POST /hecate/v1/chat/sessions`

Creates a chat session. `agent_id` chooses the session owner:

- `hecate` (default) creates a Hecate Chat. Subsequent turns send
  `execution_mode="hecate_task"` with `tools_enabled` set per turn
  (`tools_enabled=true` for tool-backed runs, `tools_enabled=false` for
  direct model chat).
- Any registered external-agent id, such as `codex`, `claude_code`,
  `cursor_agent`, or `grok_build`, creates an External Agent chat and requires
  `workspace`.

Hecate Chat sessions may be created as empty shells before a model or workspace
is chosen. Hecate validates the selected model when the first message is sent.
When `provider` is omitted on a model-backed turn, Hecate routes across
configured providers that expose the selected model.

For `agent_id="hecate"`, an optional `agent_preset_id` selects a saved Agent
Preset whose `surface` is `hecate_chat` or `any`. Hecate copies the narrow
Chat-safe subset into the session at creation time: id, name, provider/model
hints, instructions, execution profile, tools/write/network posture,
approval posture, `browser_allowed`, `browser_interactions_allowed`, and
`browser_allowed_origins`.
The `agent_preset` object returned on list and detail responses is that frozen
snapshot, not a live preset lookup. Later preset edits or deletion therefore do
not change historical chat behavior or a Task created from the chat. Explicit
`provider` and `model` request fields take precedence; preset hints fill only
omitted values.

`agent_preset_id` is invalid for an External Agent session. Hecate does not
translate this Chat selection into ACP configuration, project roles,
Cairnline coordination, project memory/source policy, project skills,
MCP-server selection, or other
adapter-specific options. Those surfaces retain their own explicit contracts.

`project_id` is optional. When supplied, it must reference an embedded
Cairnline project or Hecate returns `404 not_found`. Project-linked Hecate Chat
prelude/context assembly reads project identity, role, skill, work, and
accepted-memory metadata from Cairnline. The chat transcript itself remains
Hecate chat state.
Project-scoped sessions are still normal chat sessions, but deleting the
project later deletes those project-scoped transcripts as part of the project
cleanup.

Chat creation is server-coordinated with project deletion. The
project-existence check and durable chat create hold one reservation. The same
reservation covers the supervised
External Agent chat created by a project-assignment start. A destructive
mutation closes admission, waits for an already reserved create, and then
cleans up that completed session; not-yet-reserved requests whose request epoch
predates or overlaps the destructive interval fail with
`409 chat.session_create_conflict` instead of creating after cleanup. Refresh
projects and chats before explicitly retrying. The process-wide gate is
deliberately conservative: any project deletion also pauses project-free and
other-project chat creates for its duration. This guarantee applies to both
Hecate and embedded Cairnline project authority. The reserved system-reset
endpoint does not enter this flow because it fails before mutation.

`title` is optional session metadata. The Projects UI uses it when launching a
chat from a project-work assignment so the empty chat shell is named after the
work item and role before the first turn. The launch-context draft itself lives
only in the client composer until the operator edits and submits it through
`POST /hecate/v1/chat/sessions/{id}/messages`; creating the session does not
create a user message or turn.

For Hecate Chat sessions, `rtk_enabled` records the chat's command-output
compaction preference. It is only applied when a future turn runs through the
task-backed `hecate_task` execution mode; direct model turns never execute
local commands.

For a preset-backed Hecate Chat, frozen `instructions` are included in both
direct-model and task-backed Hecate prompt composition. A frozen
`tools_enabled=false` setting rejects an explicit `tools_enabled=true` message
and makes an omitted message flag default to the direct-model path. A
tools-enabled setting permits the normal per-turn tools choice; it does not
force an `agent_loop` Task. When a permitted tools-on turn creates a backing
Task, Hecate copies the frozen preset id and tools setting to the Task, uses the
frozen execution profile when present, maps `writes_allowed=false` to
`sandbox_read_only=true`, maps `network_allowed` to `sandbox_network`, and
copies the frozen `approval_policy` into the Task's additive mid-loop approval
layer. `require` gates every otherwise-permitted advertised tool call;
`block` refuses calls that another runtime or MCP policy would otherwise gate;
`inherit` and `allow` add no gate or override. Direct turns have no tools to
approve. Normal Hecate policy and model-capability checks still apply.

New Chat preset snapshots include explicit `browser_allowed` and
`browser_interactions_allowed` booleans plus `browser_allowed_origins` when
either grant is enabled. These output-only session fields are copied into a new
backing Task's corresponding `agent_preset_browser_*` fields. Callers select a
policy by id; they do not supply snapshot fields. Legacy snapshots with absent
browser fields remain ungranted. Continuing or retrying a Task uses its stored
snapshot; changing provider/model or creating another task-backed segment does
not re-resolve the mutable policy.

Browser execution still requires the configured local runtime, tools-on mode,
the corresponding explicit grant and exact origin, and mandatory per-call
approval. `approval_policy="allow"` does not bypass that approval;
`"block"` makes otherwise-available browser calls unusable. Neither ordinary
Tools nor network permission grants browser authority. External Agents and
remote runtimes retain their existing exclusion. The API adds no new browser
endpoint or browser session: Chat uses the existing Task tools, approvals, and
bounded evidence artifacts.

`workspace_mode` records the execution posture for future task-backed turns:

- `persistent` and `ephemeral` use a separate Hecate-managed workspace. They
  remain distinct stored settings, although both currently use the same
  isolated clone/copy provisioning path. Operator clients may render them as
  one Managed choice until the lifecycles differ.
- `in_place` runs in the selected `workspace`, so tools write directly to that
  folder.

For API compatibility, an omitted `workspace_mode` is stored and returned as
`in_place`. The operator UI sends an explicit mode and defaults new
project-free Hecate chats to `persistent`; project-linked chat creation uses
the linked Cairnline Project's default as coordination intent. Once the first
task-backed segment has been created, the mode is locked for that chat. Direct
Direct-model turns store the posture but do not provision a workspace. A new task
segment within an existing managed chat reuses the already-provisioned root
instead of cloning away uncommitted or untracked work.

External Agent sessions always use `workspace_mode=in_place` because the ACP
session owns the selected workspace directly. Clients normally omit the field
for External Agent creation; any explicit non-`in_place` value is rejected.

When `workspace` is provided, it must be an operator-controlled local
directory. Hecate validates and canonicalizes the path before a tool-backed or
External Agent turn starts, so later turns use the resolved directory instead of
failing only after execution starts.

For external-agent `agent_id` values, session creation is the authoritative ACP
session-preparation attempt: Hecate resolves the executable again, performs a
fresh ACP `Initialize`, and starts or restores the native ACP session
immediately. Direct ACP peers launch during this setup. Embedded command bridges
may run bounded provider discovery while deferring their prompt-serving vendor
invocation and prompt-time auth result until the first message. A prior
Connections check is neither required nor trusted as launch authority. Clients
may include `config_options` selected from the latest check projection when it
exposes Hecate-managed launch controls; the passive catalog does not expose
those controls. No current built-in requires one before session creation. A
future required launch control must have a passive schema path before adoption
so a check never becomes prerequisite.
Hecate validates that any required Hecate-managed launch selection is present,
then uses matching launch-option values when starting the agent process. After
the ACP session exists, agent-owned `config_options` are returned
with the session so clients can render them before the first prompt. If the agent
reports ACP `initialize.agentInfo`, Hecate returns the trimmed implementation
metadata as `agent_info` on the chat session and on assistant messages produced
by that session. If the selected command is missing, a required launch option is
absent, or the ACP session handshake fails, session creation fails and Hecate
removes the empty chat record. For an embedded bridge, prompt-serving vendor
process or auth failure can instead surface on the first message because no
vendor prompt is sent during session creation.

External Agent session creation may also include `mcp_servers`, using the same
stdio/HTTP server shape as task-create `mcp_servers`. Hecate stores the server
list on the chat session and passes it to the adapter during ACP `session/new`
or `session/load`; support beyond transport propagation depends on the selected
adapter and upstream agent. Hecate-owned chats do not accept session-level
`mcp_servers`; pass them on `POST /hecate/v1/chat/sessions/{id}/messages` so
the backing Task segment records the exact server set for that Task Run.
If an ACP agent advertises native slash commands with
`available_commands_update`, Hecate stores the latest complete provider-owned
replacement snapshot on the session as `available_commands`. An explicit empty
snapshot clears previous hints, and a live notification takes precedence over
an older create, prompt, or configuration result. Clients send those commands
back as ordinary prompt text, for example `/web agent client protocol`; there
is no separate ACP execute-command RPC.

```json
POST /hecate/v1/chat/sessions
{
  "agent_id": "hecate",
  "agent_preset_id": "prof_...",
  "project_id": "proj_...",
  "provider": "anthropic",
  "model": "claude-sonnet-4",
  "title": "Hecate Chat",
  "workspace": "/Users/alice/src/my-app",
  "workspace_mode": "persistent"
}

→ 200
{
  "object": "chat_session",
  "data": {
    "id": "chat_...",
    "title": "Hecate Chat",
    "project_id": "proj_...",
    "agent_id": "hecate",
    "provider": "anthropic",
    "model": "claude-sonnet-4",
    "capabilities": {
      "tool_calling": "basic",
      "streaming": true,
      "source": "provider"
    },
    "agent_preset": {
      "id": "prof_...",
      "name": "Focused reviewer",
      "provider_hint": "anthropic",
      "model_hint": "claude-sonnet-4",
      "instructions": "Explain findings with evidence.",
      "execution_profile": "reviewer",
      "tools_enabled": true,
      "writes_allowed": false,
      "network_allowed": false,
      "browser_allowed": false,
      "browser_interactions_allowed": false,
      "approval_policy": "require"
    },
    "status": "idle",
    "rtk_enabled": false,
    "workspace": "/Users/alice/src/my-app",
    "workspace_mode": "persistent",
    "turns_used": 0,
    "session_started_at": "2026-05-03T12:00:00Z",
    "messages": []
  }
}
```

External Agent creation with ACP session controls:

```json
POST /hecate/v1/chat/sessions
{
  "agent_id": "grok_build",
  "workspace": "/Users/alice/src/my-app",
  "mcp_servers": [
    {
      "name": "filesystem",
      "command": "node",
      "args": ["./mcp-filesystem-server.js"],
      "approval_policy": "require_approval"
    }
  ],
  "config_options": [
    {
      "id": "model",
      "name": "Model",
      "category": "model",
      "type": "select",
      "source": "acp_model",
      "current_value": "chosen-model-id"
    }
  ]
}

→ 200
{
  "object": "chat_session",
  "data": {
    "id": "chat_...",
    "agent_id": "grok_build",
    "workspace": "/Users/alice/src/my-app",
    "workspace_mode": "in_place",
    "driver_kind": "acp",
    "agent_info": {
      "name": "grok-build-acp-adapter",
      "title": "Grok Build ACP Adapter",
      "version": "0.1.0-alpha.1"
    },
    "status": "idle",
    "mcp_servers": [
      {
        "name": "filesystem",
        "command": "node",
        "args": ["./mcp-filesystem-server.js"],
        "approval_policy": "require_approval"
      }
    ],
    "config_options": [
      {
        "id": "model",
        "name": "Model",
        "category": "model",
        "type": "select",
        "source": "acp_model",
        "current_value": "chosen-model-id"
      }
    ],
    "available_commands": [
      {
        "name": "web",
        "description": "Search the web",
        "input_hint": "query"
      }
    ],
    "messages": []
  }
}
```

### `GET /hecate/v1/chat/sessions/{id}`

Returns the full session transcript, including user messages and assistant
messages produced by the backing runtime. Hecate-owned sessions include
`provider`, `model`, and the current capability snapshot; once a tools-on turn
creates a backing task, they also include `task_id` and `latest_run_id`.
When one was selected at creation, Hecate-owned sessions also include the
immutable `agent_preset` snapshot described above. Clients must render it as
historical execution provenance rather than re-resolving its id through
`/hecate/v1/agent-presets`.
Individual chat messages carry the durable runtime snapshot:
`turn_id`, `execution_mode`, derived `turn_kind`, `segment_id`, optional
`task_id`, optional `run_id`, provider/model, and capabilities. The user and
assistant messages for one submitted Chat turn carry the same `turn_id`.
`run_id` is present only for a task-backed `hecate_task` turn and identifies its
backing Task Run; direct-model and External Agent messages do not use it.
Frontends must not treat `run_id` as a Chat Turn identity or fall back from a
missing `turn_id` to `run_id`. Frontends should prefer
message-level `turn_kind` (`direct_model`, `hecate_task`, or `external_agent`)
for UI routing; `execution_mode` and `tools_enabled` are lower-level immutable
runtime snapshot fields. If tools are re-enabled after a direct model segment,
Hecate creates a new task-backed segment in the same transcript; older messages
keep their original runtime/model/task snapshots.

User messages with files also carry an `attachments` array containing only
`id`, `session_id`, `filename`, `media_type`, `size_bytes`, `sha256`,
`created_at`, and the session-scoped `content_url`. File bytes and base64 are
not part of the session response or stream snapshots. The normalized filename
and raw SHA-256 digest are operator-visible metadata: filenames can disclose
sensitive wording, and the stable digest reveals content equality and permits
known-file comparison to any client that can read the session. Neither field is
a confidentiality control or proof of ownership.

The response also includes a derived `segments` array. Messages remain the
durable source of truth; segments are a render helper that groups contiguous
turns with the same `segment_id` so clients can show transcript boundaries such
as "tools off with smollm2" → "tools on with qwen2.5-coder". Each segment
contains its derived `turn_kind`, `execution_mode`, provider/model snapshot,
optional `task_id`, latest Task Run id, status, message count, and first/last
timestamps.

Hecate-owned sessions may include `context_summary` after automatic or manual
context compaction. The summary is operator-visible metadata for older
transcript context and includes `content`, `message_count`,
`through_message_id`, `compacted_at`, and `strategy`. `strategy` is
`semantic_transcript_summary` when Hecate used the session provider/model to
summarize the older transcript window, and `deterministic_transcript_summary`
when it used the bounded transcript-line fallback. Original messages remain in
`messages`; future direct model turns inject the summary as background context
and send newer messages in full.

External Agent sessions may also include `config_options`, a normalized
projection of ACP session configuration options reported by the agent during
`session/new`, `session/load`, or `session/set_config_option`, merged with any
Hecate-managed launch controls that affected the agent process. Because
Hecate starts the ACP session during chat creation, clients can usually show
session controls before the first prompt. Catalog launch controls can be shown
even earlier from `GET /hecate/v1/agent-adapters`. Common `category` values
include `model`, `mode`, and `thought_level`, but clients must handle missing
or custom categories.

External Agent sessions may also include `available_commands`, the latest ACP
available slash command replacement snapshot advertised by the agent. Each
item has `name`, optional `description`, and optional `input_hint`. The `name`
is agent-owned; clients should render it as a slash command hint but submit the
chosen command as normal prompt text. Clients must not treat the field as a
Hecate-maintained catalog: provider updates may replace it with aliases,
workspace-provided commands, or an explicit empty list.

External Agent sessions and assistant messages may include `agent_info`, the
adapter-reported ACP implementation metadata from `initialize.agentInfo`.

Hecate-owned sessions may include `context_summary` when older direct-model
chat transcript turns have been compacted. The original messages remain in the
durable transcript; `context_summary` tells clients and later model calls how
many older messages were summarized, the last summarized message id, and when
the summary was produced. Hecate injects that summary as system context before
the retained recent transcript on later direct-model turns.

### `PATCH /hecate/v1/chat/sessions/{id}`

Renames a chat session. This is shared by Hecate Chat
(`agent_id="hecate"`) and External Agent sessions. The title is
metadata only; it does not change the prompt history, workspace, provider/model,
or ACP native session.

```json
PATCH /hecate/v1/chat/sessions/chat_...
{
  "title": "Review release notes"
}

→ 200
{
  "object": "chat_session",
  "data": {
    "id": "chat_...",
    "title": "Review release notes",
    "agent_id": "hecate",
    "status": "completed",
    "messages": []
  }
}
```

### `POST /hecate/v1/chat/sessions/{id}/config-options/{config_id}`

Updates one ACP session configuration option for an active External Agent
session. Body:

```json
{
  "value": "smart"
}
```

`value` may be a string select value or a boolean. Hecate forwards the change to
the active adapter with ACP `session/set_config_option`, persists the adapter's
returned full `config_options` list on the chat session, publishes a session
snapshot, and returns the updated session response. If the native ACP session
has been closed or is not active, the endpoint returns
`409 chat.session_not_running`; create a new External Agent chat or retry
after the session has been restored.

### `PATCH /hecate/v1/chat/sessions/{id}/settings`

Updates Hecate-owned chat settings for future turns. This endpoint currently
accepts `rtk_enabled` and/or `workspace_mode` for `agent_id="hecate"` sessions.
External Agent sessions reject it with `chat.runtime_mismatch` because their
ACP adapters own command execution and use the selected workspace in place.

When an existing Hecate Chat session already has a backing task, the task
record is updated too so later continued Task Runs inherit the same setting.
Running turns are not mutated mid-flight. Every non-empty settings PATCH,
including an RTK-only update, uses exclusive per-session admission and returns
`409 chat.agent_session_busy` when a turn is active.

`workspace_mode` may be changed while the Hecate Chat is still an empty or
direct-model-only shell. Once `task_id` is present, changing to a different
mode returns `409 conflict`; sending the already-selected value remains
idempotent. A concurrent active turn returns `409 chat.agent_session_busy`;
settings mutation and turn admission are exclusive so creation cannot snapshot
one posture while the session persists another. The mutation is not a Chat turn,
so the Cancel endpoint does not report or cancel it. When a managed Task Run
starts, Hecate atomically updates the session and launching message pair to the
actual generated execution path. SQL session updates serialize with that link;
PostgreSQL operations lock the session row before any message rows. An
ambiguous link result is reread with a bounded persistence context before
Hecate decides to cancel. A confirmed
link failure terminalizes the assistant, retains chat-origin cancellation
recovery, rejects new Turn admission while an unlinked origin Task Run remains
active, and makes an idempotent replay return the failed transcript without
redispatch. Workspace review and file browsing fail closed if a durable
chat-origin task exists without that link; otherwise later task-backed turns
and message snapshots point at the files the agent actually changed rather
than the untouched source folder.

```json
PATCH /hecate/v1/chat/sessions/chat_.../settings
{
  "rtk_enabled": true,
  "workspace_mode": "persistent"
}

→ 200
{
  "object": "chat_session",
  "data": {
    "id": "chat_...",
    "agent_id": "hecate",
    "rtk_enabled": true,
    "workspace_mode": "persistent"
  }
}
```

### `POST /hecate/v1/chat/sessions/{id}/compact`

Compacts older transcript context for a Hecate-owned chat session and returns
the updated session. This endpoint is deterministic and local to Hecate; it
does not call a model. It summarizes older user/assistant turns into
`context_summary` while retaining the newest messages in full for later turns.

External Agent sessions reject this endpoint with `409 chat.runtime_mismatch`
because their native runtimes own their own context windows. If there are not
enough older messages to compact, Hecate returns `400 invalid_request`.

```json
POST /hecate/v1/chat/sessions/chat_.../compact

→ 200
{
  "object": "chat_session",
  "data": {
    "id": "chat_...",
    "agent_id": "hecate",
    "context_summary": {
      "content": "- User: previous request\n- Assistant: previous answer",
      "message_count": 2,
      "through_message_id": "msg_...",
      "compacted_at": "2026-06-16T10:00:00Z"
    }
  }
}
```

### `POST /hecate/v1/chat/sessions/{id}/attachments`

Stages one file for a future message. Send `multipart/form-data` with exactly
one part named `file`. Uploading does not append a transcript message or contact
a provider or External Agent.

Hecate-owned chats accept PNG, JPEG, WebP, and UTF-8 text/code for both Tools-off
and Tools-on turns. Text/code is canonicalized to `text/plain`, limited to
5 MiB per file, and must have no binary control characters except tab, newline,
and carriage return. The server validates the entire byte payload rather than
trusting a filename or MIME declaration. Recognized binary formats, PDF/DOCX,
and archives are unsupported; no extraction or execution occurs.
External Agent chats also accept arbitrary file media types. Images and
External Agent files are limited to 5 MiB. Native rasters are additionally limited to 8000 pixels
per axis and 16 megapixels and are fully decoded before storage. A supported
raster uploaded to an External Agent chat receives image treatment only when
that bounded decode succeeds; malformed or over-dimension image-like bytes are
stored as an opaque `application/octet-stream` file instead of being rejected.
Hecate normalizes
the display filename to 128 bytes and computes a SHA-256 digest. Oversized input
returns `413 chat.attachment_too_large`; malformed, mismatched, or unsupported
input returns a stable `422 chat.attachment_*` error.

Each Hecate process admits at most two upload body-read and attachment-validation
paths concurrently. When both slots are occupied, the endpoint rejects the
request before reading its body with `429 chat.attachment_upload_busy`, a
`Retry-After: 1` header, and `max_concurrent_uploads` plus
`retry_after_seconds` error fields. Clients may retry that upload after the
advertised delay; no draft was created by the rejected request. The bounded
body guard starts before session lookup and admission, so missing-session and
busy responses also abort unread upload bytes after
the JSON error is committed.

The upload body-read phase has a route-local 60-second deadline. HTTP/1.1 uses
a transport read deadline and closes the expired connection. HTTP/2 avoids a
connection-scoped read deadline; the route timer closes only the stalled
request body so Hecate can return and flush the JSON `408` envelope while other
streams remain usable. Successful HTTP/1.1 body reads clear the transport
deadline before decode and storage. A deadline rejection returns
`408 chat.attachment_upload_timeout` with `read_timeout_ms: 60000`; no draft is
created, and the client may retry the original file in a new request. These
route guards do not add a global HTTP server read timeout that would affect
streaming endpoints.

Each session may hold at most eight unlinked drafts totaling 40 MiB. Before
applying that limit, a staging request reclaims unlinked drafts older than 24
hours. Exceeding the limit returns
`409 chat.attachment_draft_quota_exceeded` with `max_draft_attachments`,
`max_draft_bytes`, and `draft_ttl_seconds` fields. Once a draft is linked to a
persisted message, it no longer consumes draft quota and does not expire.
Draft and linked bodies together are capped at 512 MiB per chat; exceeding the
cap returns `409 chat.attachment_session_quota_exceeded` with
`max_session_attachment_bytes`. Across all chats, the memory backend is capped
at 512 MiB and SQLite/Postgres are capped at 4 GiB; exceeding the active
backend's cap returns
`409 chat.attachment_total_quota_exceeded` with
`max_total_attachment_bytes`. Any upload also reclaims eligible stale drafts
across all sessions, rather than only the session receiving that upload. The
24-hour age is a reclamation threshold, not a scheduled expiry time.

After a definite message rejection, the operator console deletes the uploaded
drafts and retries each failed deletion once. If cleanup still fails, it
restores the local Files and preserves the typed submission error with a
warning that the retained server copies can consume quota until a later upload
reclaims them after they are at least 24 hours old. Chat deletion releases them
immediately; there is no wall-clock expiry worker. If an upload response is
ambiguous, the console restores the exact prompt and Files without automatically
retrying, deletes only acknowledged drafts, preserves typed error metadata, and
warns that one unlinked copy may remain hidden. These warnings never include
attachment ids.

The draft-to-message transition uses a durable user-message-id fence. Before
serving requests after restart, Hecate reconciles any pending fence against the
transcript: exact committed metadata links the bodies, an absent message
releases them, a deleted owner purges the attachment session, and conflicting
metadata remains claimed and non-deletable. The same startup pass performs a
metadata-only sweep for ordinary draft or linked bodies whose chat was deleted
before cleanup completed.

```json
→ 201
{
  "object": "chat_attachment",
  "data": {
    "id": "att_...",
    "session_id": "chat_...",
    "filename": "diagram.png",
    "media_type": "image/png",
    "size_bytes": 42137,
    "sha256": "8de7...",
    "created_at": "2026-07-13T10:00:00Z",
    "content_url": "/hecate/v1/chat/sessions/chat_.../attachments/att_.../content"
  }
}
```

### `GET /hecate/v1/chat/sessions/{id}/attachments/{attachment_id}/content`

Returns the session-scoped file body with its exact `Content-Type` and
`Content-Length`. Supported raster images use `Content-Disposition: inline`;
other files use `Content-Disposition: attachment`. Every response includes
`X-Content-Type-Options: nosniff`, and `Cache-Control: private, no-store`.
It also includes `Content-Security-Policy: sandbox; default-src 'none'` so an
arbitrary uploaded document cannot become active same-origin content.
Remote-runtime clients must use the same authenticated request path as other
Hecate-native routes; the operator UI fetches a Blob and creates a temporary
object URL rather than putting the API URL directly in an image element.
An id from another session returns `404 chat.attachment_not_found`.

Each Hecate process admits at most four attachment content responses at once.
The permit spans the session-scoped body lookup, integrity validation, and
response write, so stalled readers cannot create an unbounded set of hydrated
5 MiB bodies. Saturation returns `429 chat.attachment_content_busy` before the
attachment store is read, with `Retry-After: 1`, `max_concurrent_downloads: 4`,
and `retry_after_seconds: 1`. An admitted response has a route-local 30-second
socket write deadline; the permit is released when the write completes or the
deadline aborts it, without imposing a global write timeout on SSE endpoints.
If the HTTP transport or a response wrapper cannot establish that deadline,
Hecate closes the connection and returns a fixed `500 gateway_error` before
committing the file `200`; it never performs an unbounded fallback body write
while holding the download permit.
Session deletion waits for an admitted body lookup/write to finish before it
removes the transcript and attachment rows.

### `DELETE /hecate/v1/chat/sessions/{id}/attachments/{attachment_id}`

Deletes an unused staged attachment and returns `204`. Once a persisted message
references the attachment, deletion returns `409 chat.attachment_in_use` so a
transcript never silently loses its file. Deleting the owning chat session
deletes all of its attachment bodies. Draft deletion is admitted against the
same session lifecycle as upload and content access: an already-admitted delete
drains before session teardown, while a request arriving after teardown closes
admission returns `409 chat.session_stopping` without reaching attachment storage.

### `POST /hecate/v1/chat/sessions/{id}/messages`

Sends the submitted prompt to the session's backing runtime and appends both
the user message and assistant output.

`POST` also accepts per-turn overrides:

- `client_request_id` — optional session-scoped idempotency key for a durable
  client queue item. It must contain 1-128 ASCII letters, digits, dots,
  underscores, colons, or hyphens. Reuse the exact key and payload when
  retrying an ambiguous submission. Hecate reserves the key before admission
  and atomically commits it with the user transcript row before the submitted
  turn's provider, task, or ACP dispatch. Admission-time semantic compaction is
  separate provider work and may precede that commit. Hecate renews the pending
  reservation through that pre-commit work and conditionally verifies its
  ownership and payload fingerprint immediately before commit; renewal loss
  fails the send before backing-turn dispatch. Concurrent or later requests
  with the same key and payload return `200` with the latest
  authoritative session and do not dispatch duplicate backing-turn work. That replay may return while the original turn's
  assistant is still running. Reusing the key with any changed request field
  fails closed with `409 chat.client_request_conflict`. Review the authoritative
  transcript, remove the conflicting item, and use a new `client_request_id`
  only if another turn is still needed; a changed payload can never succeed
  under the committed key. Omitting the field preserves the ordinary
  non-idempotent endpoint behavior.

  For an attachment-bearing request, replay also idempotently repairs the committed
  user message's durable attachment claim before returning success. If the
  original response failed after the atomic message commit and both immediate
  claim-finalization attempts failed, retry the exact payload and key; Hecate
  links the already-committed metadata without redispatching the provider turn.
  A repair that cannot confirm the original claim fails closed with a fixed
  `500` rather than exposing storage details.

  Every successful response to a request carrying `client_request_id` also
  carries privacy-safe reconciliation metadata outside `data`:

  ```json
  {
    "message_request": {
      "replay": true,
      "committed_message_id": "msg_..."
    }
  }
  ```

  The original keyed request returns `replay=false`; a same-payload retry
  returns `replay=true` with the exact already-committed user message id. The
  field is omitted for unkeyed sends and ordinary session or stream snapshots.
  It never contains the client key, request fingerprint or payload copy, or the
  internal lease token.

  Once admission reaches that atomic keyed commit, Hecate gives the user-row/key
  write a bounded server-owned persistence window. An unkeyed user-message write
  retains ordinary request cancellation until it succeeds. Immediate assistant
  creation, task/run linkage, and terminal assistant/session updates then use
  separate bounded persistence windows. A client disconnect therefore cannot
  turn a successful keyed commit into an apparent failure or leave the committed
  turn permanently `running`.

  Direct-model execution remains tied to the request and terminalizes as
  `cancelled` after a disconnect. An External Agent turn becomes server-owned
  once its user message and running assistant are durable. The connected `POST`
  still waits for the terminal result, but losing that response or the session
  SSE connection ends only the client waiter: ACP execution, prompt-mode
  approvals, partial-output persistence, and terminal settlement continue. The
  operator can still cancel through the Chat API; chat close/delete, Hecate
  shutdown also cancel the ACP turn. The 30-minute Chat Turn ceiling instead
  ends and terminalizes the turn as failed. Reconnecting clients read the
  authoritative snapshot through this API and subscribe to the session stream
  without dispatching another prompt.

  The tools-on Hecate task watcher is server-owned after commit and continues
  across browser disconnect until the Task reaches a terminal state, the
  operator cancels it, or the 30-minute Chat Turn watcher ceiling expires. That
  ceiling ends the chat watcher and terminalizes the Chat Turn; it does not
  cancel the orchestrator-owned Task. A Task that remains active, including one
  awaiting approval, stays visible and independently cancellable through the
  Task API. In-flight External Agent turns are not resumed after a Hecate process
  restart; startup reconciliation marks the running assistant interrupted.
  Same-key replay only reads the resulting durable turn; it never redispatches
  it.

  The operator UI keeps a replayed queue item at the FIFO head until the exact
  committed user message is followed, before the next user turn, by a terminal
  assistant. It observes the live session stream and polls this API as a
  fallback. Without that terminal proof, the item remains blocked for explicit
  reconciliation rather than allowing later queued work to overtake it.

- `execution_mode` — `hecate_task` or `external_agent`. Hecate Chat sessions
  use `hecate_task` (tools-on/off is set separately via `tools_enabled`);
  External Agent sessions always use `external_agent`.
- `tools_enabled` (boolean) — per-turn tools-on/off signal for Hecate Chat
  sessions. `true` opts into the tool-backed `agent_loop` path; `false`
  dispatches the prompt directly to the selected model without creating a
  task. When omitted, Hecate treats Hecate-owned turns as tools-on unless model
  capabilities require a tools-off direct model fallback.
- `provider` / `model` — used for tools-off turns and new task-backed
  Hecate Chat segments. Existing task-backed segments continue with their
  saved model snapshot until the operator turns tools off or starts a new
  task-backed segment. Provider keys resolve an exact configured runtime name
  first, then a unique normalized runtime name, then a unique stable alias;
  ambiguous aliases are rejected instead of selecting by catalog order.
  Configured providers still participate when they currently report no model
  rows.
- `attachment_ids` — up to four ids returned by the staging endpoint. The ids
  must belong to this session and total no more than 12 MiB. Hecate-owned
  turns accept UTF-8 text/code and supported raster images with tools on or off.
  Text files require no vision support. Tools-on supplies metadata and scoped
  `read_attachment` / `search_attachment` tools instead of eagerly inlining
  bodies. Tools-off admits whole text files against the selected model's
  conservative inline budget (one byte per token, conversation/framing deducted,
  a quarter of the context window plus 4096 tokens reserved; unknown windows
  use 64 KiB before overhead). Current text overflow is rejected; older text
  outside the history budget receives explicit omission markers. This estimate
  is not a vendor-tokenizer guarantee. Actual images require a currently routable matching route whose
  effective capability is `image_input="supported"`. A tools-on Task Run persists only an opaque input
  reference, revalidates scoped access immediately before agent-loop execution,
  and replaces private excerpts/images with omission markers in its conversation
  artifact. File metadata remains available; completed reads are not replayed on
  resume, and later turns without a new input do not inherit file-read authority.
  A matching manual tool-support verification can satisfy only an otherwise
  unknown tool requirement on the exact pinned route, including a tools-on
  Task Run without an attachment; it never substitutes for image support or
  enables Auto/failover routing.
  Same-input resumes and retries inherit the reference. External Agent
  turns accept the staged files; text may be empty when at least one attachment
  is present. Hecate persists only immutable attachment metadata on the user
  message and hydrates the binary bodies transiently for the selected provider
  or ACP session. ACP rich
  blocks share a cumulative 768 KiB encoded wire budget below the supported
  adapters' 1 MiB JSON-RPC line limit. Actual serialized prompt text, base64
  expansion, and JSON escaping consume that budget; a file that would overflow
  it uses a private per-turn `resource_link` even when a rich capability is
  advertised. Payload size is preflighted before Hecate allocates base64 or
  serialized rich-block copies, and prompt text that exceeds the budget fails
  before ACP dispatch. The 12 MiB combined attachment limit remains available through
  this staged fallback and is not an inline-payload allowance.
  Attachment-bearing requests may retry on that provider but never fail over to a
  different provider. Historical files are included only when the active
  configured provider name and opaque generation match the route recorded on
  their original user message; legacy rows without a generation, provider
  switches, recreated runtime-only providers, and unresolved Auto boundaries
  receive a text omission marker instead of the bytes. After hydration,
  dispatch revalidates the exact canonical runtime name and generation resolved
  during admission. Removing or replacing that provider, even under the same
  name, or reassigning its normalized name/alias fails without sending the
  bytes to the replacement. The generation is internal persisted metadata and
  is not part of this API's response schema. An attempted provider/model and
  trace remain on a failed Auto-routed turn when that provider received the
  request.
  Each Hecate process admits at most two attachment-bearing direct-model turns at a
  time. The permit covers attachment claim, historical body reads, base64
  expansion, provider serialization, and the provider call. Saturation fails
  before attachment claim or transcript mutation with
  `429 chat.image_turn_busy`, `Retry-After: 1`, and
  `max_concurrent_image_turns` plus `retry_after_seconds` error fields. Turns
  that cannot send current or historical file bodies do not use this gate.
  The legacy `chat.image_turn_busy` code applies to native text files too.
  Hydrated text-file calls suppress provider error details that could echo file
  contents; status and retry classification remain available. Model-generated
  answers and tool output can still quote the supplied text.
  Exceeding the overall 12 MiB message limit returns
  `413 chat.attachment_too_large` with `max_message_attachment_bytes`.
  Exceeding the Tools-off inline text budget returns
  `413 chat.text_context_too_large` with `inline_text_budget_bytes` and guidance
  to enable Tools or attach a smaller excerpt. The rejected claim is released;
  no transcript message or file-bearing provider call is committed. A second
  check at final provider dispatch accounts for policy-driven model rewrites.
  Failure there settles the already-committed turn as failed, without file
  disclosure; its linked attachments remain downloadable rather than becoming
  drafts again.
- `system_prompt` — applied to tools-off turns and new task-backed Hecate Chat
  segments. When the chat is linked to a project, Hecate prepends hidden
  project workflow guidance and bounded project context before the operator
  prompt. That guidance uses the same project/role/skill/active-work/memory
  vocabulary as project assignment launch context and keeps Chat conversational
  while telling the model to treat project-planning intent as proposal-only
  Project Assistant work; it does not grant direct project mutation rights.
  Task-backed project-linked Hecate Chat exposes the bounded
  `draft_project_proposal` tool for that proposal-only path; direct model turns
  receive the guidance but cannot call tools.
  Skill entries are metadata only and do not inject `SKILL.md` bodies. If the
  selected model routes to a cloud provider, the bounded project prompt context
  is sent through the normal model gateway route like any other chat prompt.
- `workspace` — required when starting a task-backed Hecate Chat turn
  (`tools_enabled=true`) on a session that does not already have a workspace.
- `mcp_servers` — optional per-turn external MCP server configs for Hecate
  Chat tool-backed turns. Same shape and validation as task-create
  `mcp_servers`; when present, Hecate starts a fresh task-backed segment so the
  server set is explicit for that backing Task Run. MCP Apps resources returned by those
  tools render through `activities[].mcp_app`.

For `tools_enabled=false` on a Hecate Chat session, Hecate calls the normal
gateway path and stores the user/assistant messages without creating a Task.
Project-linked direct model turns receive the same project workflow guidance
in their system prompt, but they still cannot run tools or mutate project
state.
For `execution_mode="external_agent"`, Hecate sends the prompt to the
session's native ACP session. Attachment blocks are resolved against that
session's live ACP Initialize capabilities at dispatch: a supported raster uses
`image` only when advertised; otherwise `resource` is used only when embedded
context is advertised. The baseline fallback is a `resource_link` to an exact
read-only file in a private per-turn staging directory. Hecate attempts to
remove that directory when `session/prompt` settles. ACP filesystem callbacks
can read only the exact staged path while the turn is live; every other read or
write in that namespace is rejected before workspace fallback. Body-free deny
namespaces cover both the advertised and quarantine paths across later
callbacks and turns until cleanup proves removal. Absolute paths, file URIs, and
workspace-relative paths are compared under lexical and canonical roots. The
namespace fence spans the full WorkspaceFS fallback so a quarantine rename
cannot cross an already-admitted read or write.
Darwin/Linux builds retain and verify the temporary parent, ancestors, stage,
and children, reject unsafe ownership, writable non-sticky ancestors, and
extended ACLs, and create entries relative to retained handles. Darwin requires
`MNT_LOCAL` on every verified handle. Linux accepts only ext2/3/4, XFS, Btrfs,
tmpfs, overlayfs, ramfs, or F2FS from `fstatfs`; every other model, including
NFS, SMB/CIFS, FUSE, ZFS, AUFS, eCryptfs, and 9p, fails closed before an
unsupported POSIX ACL operation can be treated as ACL-free. They remove and read back ACL state before bytes, verify
`0700` directory and `0600` empty-file modes, then seal the file/directory as
`0400`/`0500`. The canonical temporary path and each ancestor mount must pass
the platform check; launch Hecate with `TMPDIR` on an allowlisted local
filesystem when the default path does not. Other Unix builds fail the fallback closed. Windows builds
reject remote/reparse resolution and unsafe parent/ancestor owners or
delete/DACL-control grants. Existing managed parents and ancestors may be
controlled by the current user, LocalSystem, Administrators, or the fixed
TrustedInstaller service SID; that service is not granted access to the new
stage. Hecate atomically creates the directory relative to
the retained parent with a current-user owner and protected
current-user-plus-LocalSystem DACL, read back that exact inheritable shape, then
create children relative to the stage with an explicit current-user owner and
protected current-user-plus-LocalSystem DACL. Each empty child is verified
before writing. Protected read-only DACLs are verified after sealing; the
sealed directory DACL is explicitly non-inheritable because every child already
has its own protected DACL.
Write-capable Windows construction handles are then replaced with
read/identity-only retained handles whose share mode remains compatible with
ordinary read-only-sharing opens. Cleanup reacquires mutation access to the
exact parent-relative directory only after prompt settlement and identity
verification. It first verifies the sealed DACL through a share-compatible
owner-`WRITE_DAC` handle and restores a non-inheritable private full-control
DACL, retaining that state across retries, before opening the mutation handle.
After re-verifying each child, Hecate closes its own retained child handles
immediately before the same-parent quarantine rename because Windows forbids
renaming a directory with open descendants. Incompatible external readers
cause bounded cleanup retry/failure.

Hecate clears body references at prompt settlement, quarantines the retained
directory under a fresh random parent-relative name, and removes children
relative to retained handles. Four bounded attempts cover the complete
quarantine, preparation, and removal transition. Identity drift fails closed
without changing permissions through an unverified pathname and preserves the
retained identity for retry. Successful removal enters a separate bounded
proof-only state; retries never restart pathname work after the name may be
gone. After exhausted synchronous cleanup, the turn reports an error and
transfers the stage to one runtime-owned background janitor that outlives the
ACP session. The janitor accepts at most four failed stages per session and 16
file-turn reservations or failed stages process-wide, and is woken again after
agent-runtime termination. File-bearing turns fail closed when either bound is
full while text-only turns remain available. A protected remnant can still
remain while another same-user process holds it. Body-free alias redactors mask
complete staged path/URI aliases and ordinary accumulated ACP chunking from
operator-visible output, activities, approvals, stop reasons, errors,
command/config display metadata, and late terminal activity. They remain
session-owned after cleanup proof so delayed typed updates stay covered; entries
whose protocol identifiers or values would change are dropped, and the original
typed-control wire records are withheld. Staged-turn raw ACP diagnostics are
withheld when present.
The ACP receive loop is gated until a structural SDK logger is installed; SDK
diagnostics discard peer-controlled lines, identifiers, methods, and error
values before local or exported logging while retaining fixed events and
bounded queue counters. Native close/delete RPC failures retain only a fixed
classification and numeric code, never peer message or data.
The redactor is not DLP against a selected agent deliberately transforming the
path or segmenting it into unrelated short records. This is not an isolation
boundary from another process running as the same OS user; such a process may
change owner-controlled permissions/DACLs or inspect a discovered stage. A
separate two-slot process-wide gate bounds
attachment claim, hydration, staging, and synchronous ACP prompt lifetime; saturation returns
`429 chat.external_file_turn_busy` with `Retry-After: 1` before claim or
transcript mutation. Hecate rejects an already-cancelled External Agent Turn before prompt
construction and rechecks cancellation immediately before ACP dispatch. The
turn holds shared workspace-writer admission
from before user-message append and ACP dispatch through terminal assistant
persistence; an overlapping destructive closure rejects admission with
`409 conflict` without appending or dispatching the turn. For
`tools_enabled=true` on a Hecate Chat session, the first tool-enabled prompt
creates a visible `agent_loop` Task and starts it; follow-up prompts continue
the latest terminal Task Run when the
immediately previous segment was also task-backed. If the previous segment was
direct model chat (tools off), Hecate starts a fresh task-backed segment in
the same transcript.

Only one task-backed segment can be active in a Hecate Chat session at a time.
If the latest backing task is queued, running, or awaiting approval, **all** new
turns on that chat are rejected with `409 chat.agent_session_busy`,
including tools-off (`tools_enabled=false`) turns. Operators should wait for the
backing Task Run to finish, resolve the pending approval, or cancel/stop that Run
before sending another prompt. The operator UI layers a local composer queue on
top of that API contract: prompts submitted while a backing Task Run is busy
are held in a client-side FIFO and posted only after the active Task reaches a
terminal state. Queue entries carry the Chat and project ownership that created
them, including an explicit empty project-free sentinel, so a prompt cannot
drain into a different transcript and project deletion can target its durable
record. Verified cleanup removes matching prompts; failures quarantine retained
records and make deletion report an operator-visible error.
The UI writes each entry through to browser-local storage before dispatch. Each
mutation writes a new immutable record under a reset-generation, random-revision,
and item-id key; the exact previous revision is removed only after the new value
is verified. Same-origin tabs in the same browser profile merge the logical
snapshot through storage events instead of replacing the whole queue, and
duplicate live revisions quarantine every queued row until the handoff becomes
unambiguous. Project deletion first records a generation-scoped tombstone and
verifies both the marker and matching prompt cleanup. Single-chat deletion does
the same with a prompt-free session tombstone, which later reads, writes,
storage events, and reload migration use to reject or purge stale work. A durable
`submitting` record created by another tab or recovered after reload is shown
locally as `reconcile_required` without rewriting the fence; only explicit
status reconciliation may claim an exact matching keyed record for replay.
This survives a reload in that profile, but it is not server-owned or
synchronized to another profile, browser, or device until the user transcript
row commits.

Queue mutations fail closed when browser storage cannot verify the exact item.
The UI preserves the latest visible text, blocks FIFO drain, warns before
unload, and best-effort removes an older ready record rather than allowing stale
content to auto-send after reload. Existing `submitting` records remain intact
for reconciliation. Chat/project deletion verifies queue cleanup and reports
when the operator must clear site data manually. Item revisions,
project/session tombstones, exact-payload deletion tombstones, and
legacy-migration fingerprints prevent cleanup of an older physical key from
erasing a fresh same-ID record. An exact-payload tombstone is SHA-256 over the
canonical queue payload without its storage revision. A matching late rewrite
stays consumed, while a different same-ID ready payload is a local
remove-and-resubmit conflict and a different `submitting` payload remains
fenced. Hashes reveal equality even though they contain no prompt.

Migration of a previous mutable unscoped/revisionless record keeps
the original prompt as a fingerprint-suppressed shadow because local storage has
no safe compare-and-delete operation. A matching shadow does not resurrect after
its immutable revision is delivered or removed; a changed shadow is blocked.
The shadow prompt and its equality-revealing migration fingerprint can persist
until explicit browser-queue cleanup or manual site-data cleanup. Explicit
all-session queue cleanup snapshots and post-audits all four keyed queue
namespaces plus the prompt-bearing legacy whole-array key before removing
old-generation artifacts; the disabled server reset endpoint does not invoke
this browser action.

Clients can block obvious stale selections by combining `/v1/models` with
`/hecate/v1/providers/status`, but the server remains authoritative. If a stale
provider/model selection slips through, Hecate Chat returns
`422 model_not_configured` with provider readiness fields, suggested replacement
models, and an `operator_action` repair hint in the error details.

The response returns after the backing turn finishes, times out, is cancelled,
or fails, except an idempotent replay can return the already committed current
session while the original turn is still running. For live output while the turn is running, subscribe to the session
stream before posting the message. Task-backed Hecate Chat turns update the running
assistant message's `content` when the backing task's model route supports
streaming; non-streaming providers still publish the final assistant content
when the Task Run finishes. External Agent turns continue to publish normalized
adapter output as it arrives.

If an adapter proves that a provider-native conversation is missing before it
emits output, Hecate still fails closed by default. It retries once only when
the current ACP update stream is exactly the command bridge's outer
start/failed-finish pair, with no provider or inner-tool update, and when
the persisted transcript contains no successful or otherwise ambiguous agent
turn, and only after storing the replacement `native_session_id`. The running
assistant row receives exactly one completed `session_recovery` activity; the
same type is used by terminal fallback if a streaming activity write was lost. Established
history is never silently reset; the failed assistant row instead explains that
the native conversation could not be restored and tells the operator to start
a new External Agent chat. Attachments on an authorized retry pass through the
same live ACP capability checks, size limits, private staging, and cancellation
checks as the original attempt.
Process-scoped adapters may also replace an id that cannot be loaded after the
adapter runtime restarts. That catalog-declared path uses the same durable-id
callback and `session_recovery` activity before the first fresh-session prompt;
durable or unknown scopes fail closed on `session/load` errors.

Before starting the adapter, Hecate enforces optional chat guardrails:
`HECATE_CHAT_MAX_TURNS_PER_SESSION`,
`HECATE_CHAT_MAX_SESSION_DURATION`, and
`HECATE_CHAT_IDLE_TIMEOUT`. Each returns HTTP 422 with a stable
`error.type` when exceeded:
`chat.session_limit_exceeded`,
`chat.session_duration_limit_exceeded`, or
`chat.session_idle_timeout`.

```json
POST /hecate/v1/chat/sessions/chat_.../messages
{
  "content": "Review the current diff and suggest fixes."
}

→ 200
{
  "object": "chat_session",
  "data": {
    "id": "chat_...",
    "status": "completed",
    "messages": [
      {
        "id": "msg_...",
        "turn_id": "turn_...",
        "turn_kind": "external_agent",
        "role": "user",
        "content": "Review the current diff and suggest fixes."
      },
      {
        "id": "msg_...",
        "turn_id": "turn_...",
        "turn_kind": "external_agent",
        "request_id": "req_...",
        "trace_id": "d4c5...",
        "span_id": "8f3a...",
        "role": "assistant",
        "content": "...",
        "raw_output": "...",
        "agent_id": "codex",
        "agent_name": "Codex",
        "driver_kind": "acp",
        "native_session_id": "session_...",
        "agent_info": {
          "name": "codex-acp-adapter",
          "title": "Codex ACP Adapter",
          "version": "0.1.0-alpha.28"
        },
        "status": "completed",
        "cost_mode": "external",
        "workspace": "/Users/alice/project",
        "diff_stat": "...",
        "started_at": "2026-05-03T12:00:01Z",
        "completed_at": "2026-05-03T12:00:08Z",
        "duration_ms": 7000,
        "activities": [
          {
            "type": "started",
            "status": "completed",
            "title": "Starting external agent",
            "detail": "Codex in /Users/alice/project",
            "created_at": "2026-05-03T12:00:01Z"
          },
          {
            "type": "files_changed",
            "status": "completed",
            "title": "Files changed",
            "detail": "2 files changed",
            "created_at": "2026-05-03T12:00:08Z"
          },
          {
            "type": "completed",
            "status": "completed",
            "title": "Final answer",
            "created_at": "2026-05-03T12:00:08Z"
          }
        ]
      }
    ]
  }
}
```

Each submitted External Agent turn gets a stable `turn_id`, shared by its user
and assistant messages, plus start/end timestamps and duration so clients can
correlate streamed updates, final output, and future artifacts without treating
the assistant message id as the Turn identity. External Agent messages do not
carry `run_id`; that field is reserved for a backing Task Run on task-backed
Hecate Chat turns.
It also stores `request_id`, `trace_id`, and `span_id`; use
`GET /hecate/v1/traces?request_id=<request_id>` to inspect the OTel-shaped
`chat.turn` span for that prompt.
Task-backed Hecate Chat messages also include a `timing` object derived from
the backing Task Run's Steps, approvals, and Run events:

```json
{
  "total_ms": 12400,
  "queue_ms": 120,
  "model_ms": 8500,
  "tool_ms": 700,
  "approval_wait_ms": 2000,
  "overhead_ms": 1080,
  "model_call_count": 2,
  "tool_count": 1,
  "bottleneck": "model",
  "bottleneck_ms": 8500
}
```

`overhead_ms` is the remainder after queue/model/tool/approval buckets and
covers gateway orchestration, artifact projection, polling cadence, and final
transcript rendering. It is intentionally named as overhead rather than a fake
artifact duration because Hecate does not yet record artifact-write spans for
every task artifact.
`content` is the normalized transcript that should be shown by default.
`raw_output` preserves raw ACP update JSON for diagnostics when an adapter emits
surprising structured output. For a turn with private resource-link staging,
Hecate instead returns a fixed withheld marker when raw data exists; arbitrary
ACP chunk boundaries cannot be redacted safely. `driver_kind` and
`native_session_id` identify the
underlying ACP session reused across turns in the Hecate chat. `activities` is
the structured progress model for the Chats UI: it records lifecycle markers
such as starting, running, output, files changed, failed, cancelled, and final
answer. Task-backed MCP Apps tool calls can include `activities[].mcp_app` so
the UI can render the captured `text/html;profile=mcp-app` resource inline
while retaining the text fallback. Failures from the ACP adapter are still
represented as assistant
messages with `"status": "failed"` and `error` so the transcript stays intact.
Transport or request validation failures still use the normal Hecate error
envelope.

Chat execution errors:

| Status | `error.type`                                    | Meaning                                                                                                                                                                                     |
| ------ | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `chat.workspace_required`                       | Task-backed Hecate Chat turns and External Agent sessions need a selected workspace path before the first turn.                                                                             |
| `400`  | `chat.model_required`                           | Hecate Chat needs an explicit selected model before direct model or task-backed turns, or an External Agent adapter requires a launch model before session start.                           |
| `400`  | `chat.agent_id_invalid`                         | The requested session owner is not `hecate` and does not match a registered external-agent adapter.                                                                                         |
| `400`  | `chat.execution_mode_invalid`                   | The requested turn execution mode is not one of `hecate_task` or `external_agent`.                                                                                                          |
| `400`  | `chat.runtime_mismatch`                         | The request tried to run a turn through a runtime that does not match the existing session type.                                                                                            |
| `400`  | `chat.adapter_not_found`                        | The selected external-agent adapter is not registered.                                                                                                                                      |
| `409`  | `agent_adapter.executable_trust_required`       | The selected External Agent app has a measured identity but no matching approval for this runtime host.                                                                                     |
| `409`  | `agent_adapter.executable_identity_changed`     | The selected app changed after approval and must be reviewed and approved again.                                                                                                            |
| `503`  | `agent_adapter.executable_identity_unavailable` | Hecate could not measure the app identity at the process-start boundary.                                                                                                                    |
| `409`  | `conflict`                                      | An External Agent turn cannot acquire workspace-writer admission because an overlapping destructive workspace operation currently owns the process-local closure.                           |
| `409`  | `chat.agent_session_busy`                       | The backing Task Run is queued, running, or awaiting approval. Resolve or cancel that Run before sending another prompt, even for tools-off Turns in the same Chat.                         |
| `409`  | `chat.session_stopping`                         | The session is still cancelling or closing; retry after it settles.                                                                                                                         |
| `409`  | `chat.session_not_running`                      | A stop request was issued when no Chat Turn was active.                                                                                                                                     |
| `422`  | `model_not_configured`                          | The selected model is not currently reported by the selected provider. Choose a discovered model or refresh/fix provider discovery.                                                         |
| `422`  | `provider_ambiguous`                            | The supplied provider alias matches multiple configured providers. Choose the provider by its canonical runtime name or remove the conflicting alias.                                       |
| `422`  | `chat.model_capability_required`                | A task-backed Hecate Chat turn was explicitly requested, but the selected model is not known to support tools. Continue with direct model chat or choose a model that reports tool support. |

Client note: browser/operator clients may queue a prompt locally when they
receive or predict `chat.agent_session_busy`, but the server still
accepts only one active task-backed turn per Hecate Chat session.

### `GET /hecate/v1/chat/sessions/{id}/messages/{message_id}/context`

Returns the persisted context packet snapshot for an assistant message:
operator UIs render project-linked Hecate Chat packets with an explicit
project-prelude note, while the wire packet remains the same itemized
`context_packet` shape.

```json
GET /hecate/v1/chat/sessions/chat_.../messages/msg_.../context
→ 200
{
  "object": "context_packet",
  "data": {
    "id": "ctx_...",
    "version": "chat.context.v1",
    "execution_mode": "hecate_task",
    "provider": "ollama",
    "model": "llama3.1:8b",
    "execution_profile": "chat_agent",
    "workspace": "/workspace/hecate",
    "system_prompt_included": true,
    "message_count": 3,
    "refs": {
      "session_id": "chat_...",
      "message_id": "msg_...",
      "turn_id": "turn_...",
      "project_id": "proj_...",
      "task_id": "task_...",
      "run_id": "run_..."
    },
    "sources": [
      {
        "kind": "project",
        "label": "Hecate",
        "detail": "proj_...",
        "trust": "project"
      },
      {
        "kind": "transcript",
        "label": "Chat transcript",
        "detail": "3 chat messages including this turn",
        "trust": "operator"
      }
    ],
    "items": [
      {
        "section": "project",
        "kind": "project",
        "trust_level": "runtime_state",
        "origin": "proj_...",
        "title": "Hecate",
        "included": true,
        "inclusion_reason": "Project linked to this chat session"
      },
      {
        "section": "runtime",
        "kind": "transcript",
        "trust_level": "runtime_state",
        "origin": "chat.transcript",
        "title": "Chat transcript",
        "body": "3 chat messages including this turn",
        "included": true,
        "inclusion_reason": "Visible terminal transcript count for this turn"
      }
    ]
  }
}
```

Existing top-level fields and `sources` remain for older clients. Newer clients
should prefer `items` plus `refs` for trust-labelled, provenance-aware
inspection. Each item carries a stable `section` value so later inspectors can
group without inferring from `kind`. Current packets intentionally avoid storing
full system prompts, raw transcript text, source file contents, or
external-agent private prompt packing. Project assignment packets may include
project memory bodies because memory entries are first-class inspectable
context; source file bodies are represented by `BodyRef` plus `prompt_context`
summaries rather than copied into the packet.

Operator UI note: the current React console renders these packets as a compact
"what the agent saw" inspector. Chats expose it inline on assistant transcript
rows; Task Detail and Project assignment detail expose it behind an
`Inspect context` modal. The UI groups rows by `section` using labels such as
Agent preset, Instructions, Skills, Memory, Project sources, Work context, and
Runtime evidence; keeps trust labels on each item; falls back to legacy `sources` when
`items` are absent; and uses operator-facing copy such as `Not captured` when a
snapshot does not expose the full system prompt text.

Section values currently used by the runtime are:

- `profile` for resolved Hecate Agent Preset metadata and preset-resolution warnings
- `instructions` for system-prompt, prompt-context, and instruction-layer metadata
- `skills` for resolved, skipped, or chat-visible project skill metadata; `SKILL.md` bodies are not included
- `memory` for project memory entries
- `workspace` for the selected workspace path
- `project` for project identity metadata
- `project_work` for chat-visible active work metadata and assignment launch work-item, assignment, role, execution-hint, handoff, and artifact-reference metadata
- `sources` for enabled project context-source metadata such as `workspace_doc` and `project_notes`
- `runtime` for transcript counts, task-runtime metadata, and external-agent session metadata

`included=true` means the item was part of the prepared context for that
message or Task Run. `included=false` means the item is related inspectable metadata
that V1 did not inject into the runtime context. Hecate-owned project chat
packets use explicit `prompt_context` items to distinguish bounded project
prelude content from visible-only project source metadata. External Agent chat
and External Agent project-assignment packets mark project memory/source
records as visible-only because Hecate records metadata for inspection but does
not inject those bodies into adapter prompts. Native project-assignment packets
can mark project memory and eligible source metadata included only when the
resolved Agent Preset policy activated bounded prompt inclusion; handoffs and
artifact refs remain metadata-only.

Legacy packets can omit `id`, `execution_profile`, `refs`, or `section`. The
server backfills obvious request-scoped refs and default sections where it can,
but clients should render missing fields defensively.

### `GET /hecate/v1/chat/sessions/{id}/messages/{message_id}/files`

Returns a structured file list for a chat assistant message that captured
a workspace diff. The data is derived from the stored `diff` first, then falls
back to `diff_stat` when only the stat text is available.

```json
GET /hecate/v1/chat/sessions/chat_.../messages/msg_.../files
→ 200
{
  "object": "chat_changed_files",
  "data": [
    {
      "path": "src/foo.go",
      "additions": 12,
      "deletions": 3,
      "status": "modified"
    }
  ]
}
```

`status` is best-effort: `modified`, `added`, `deleted`, `renamed`, or
`binary`. Messages without a captured diff return an empty list.

### `GET /hecate/v1/chat/sessions/{id}/messages/{message_id}/files/{path}`

Returns the stored unified diff block for one changed file. Encode the path as
a URL path component (`encodeURIComponent(path)` in browser clients).

```json
GET /hecate/v1/chat/sessions/chat_.../messages/msg_.../files/src%2Ffoo.go
→ 200
{
  "object": "chat_changed_file_diff",
  "data": {
    "path": "src/foo.go",
    "additions": 12,
    "deletions": 3,
    "status": "modified",
    "diff": "diff --git a/src/foo.go b/src/foo.go\n..."
  }
}
```

Status codes:

- `200 OK` with the per-file diff.
- `404 not_found` when the session, message, or file path is unknown.

The message file endpoints are read-only historical evidence. A captured
message diff can be stale relative to the working tree, so it never authorizes
a workspace mutation. The revision-bound current workspace discard endpoint
below is the only chat file-revert surface.

### `GET /hecate/v1/chat/sessions/{id}/workspace-diff`

Returns a live, read-only review of the chat session's selected Git workspace.
The `layers` array always contains `staged`, `working_tree`, and `untracked`, in
that order, even when a layer is empty. This is current workspace state, not a
captured diff from an assistant message.

```json
GET /hecate/v1/chat/sessions/chat_.../workspace-diff
→ 200
{
  "object": "chat_workspace_diff",
  "data": {
    "workspace": "/Users/alice/project",
    "revision": "sha256:6cc8...",
    "diff_stat": "README.md | 1 +",
    "diff": "diff --git a/README.md b/README.md\n...",
    "has_changes": true,
    "review_complete": true,
    "files": [
      {
        "path": "README.md",
        "additions": 1,
        "deletions": 0,
        "status": "modified"
      }
    ],
    "layers": [
      {
        "kind": "staged",
        "complete": true,
        "files": []
      },
      {
        "kind": "working_tree",
        "complete": true,
        "files": [
          {
            "id": "review-entry-48a6...",
            "layer": "working_tree",
            "path": "README.md",
            "additions": 1,
            "deletions": 0,
            "status": "modified",
            "preview": {
              "kind": "text_diff",
              "content": "diff --git a/README.md b/README.md\n..."
            }
          }
        ]
      },
      {
        "kind": "untracked",
        "complete": true,
        "files": [
          {
            "id": "review-entry-a73c...",
            "layer": "untracked",
            "path": "notes.txt",
            "additions": 0,
            "deletions": 0,
            "status": "untracked",
            "size_bytes": 12,
            "preview": {
              "kind": "text",
              "content": "draft notes\n"
            }
          }
        ]
      }
    ],
    "discard": {
      "available": true,
      "revision": "workspace-sha256:6cc8..."
    }
  }
}
```

Each layer has its own `complete` flag and may carry `omitted_count`. Each file
has an opaque `id` that distinguishes the same path across layers; clients must
use that id for review-row state rather than treating `path` as globally unique.
The id is not a mutation token. `review_complete` is true only when every layer
and the represented Git state are complete. `review_issues`, when present,
contains `{kind, path}` records for state that Git's ordinary patches cannot
represent safely; `review_issues_omitted_count` reports any additional issues
beyond the bounded returned list. Issue kinds include `intent_to_add`,
`assume_unchanged`, `skip_worktree`, `skip_worktree_assume_unchanged`, and
`unmerged`.

Every file includes one inline `preview` state:

| `preview.kind`      | Meaning                                                                                   |
| ------------------- | ----------------------------------------------------------------------------------------- |
| `text_diff`         | Bounded unified diff for a staged or working-tree tracked file.                           |
| `text`              | Bounded UTF-8 body of an untracked regular file.                                          |
| `binary`            | Binary content was detected and not returned.                                             |
| `too_large`         | Body was omitted because of a per-file, layer, or total limit; `reason` identifies which. |
| `symlink`           | The entry is a symlink; Hecate did not follow it.                                         |
| `special`           | The entry is not a safely readable regular file.                                          |
| `nested_repository` | The entry is an embedded repository or tracked Gitlink; Hecate did not open its contents. |
| `conflict`          | Git reports an unmerged path.                                                             |
| `unavailable`       | A stable preview could not be proved; `reason` gives a bounded classification.            |

For a tracked Gitlink, `nested_repository` carries `reason=gitlink`; that
working-tree entry is read-only because a root patch cannot safely restore the
nested repository state.

Untracked preview sources are capped at 256 KiB per file. Tracked inline bodies
and the source bytes inspected for untracked previews share one 4 MiB preview
budget with the duplicated legacy projection. Binary source bytes consume the
budget even though their bodies are not returned, bounding classification
work. Reaching the shared budget leaves later entries visible with
`preview.kind=too_large` and `reason=total_limit`. A truncated tracked layer,
omitted entry list, or omitted tracked text
preview marks that layer incomplete; an intentionally metadata-only untracked
entry can remain inventory-complete. Hecate snapshots effective external Git
excludes before inventory and omits paths ignored by those rules. It opens
untracked previews relative to a pinned workspace root, refuses symlinks and
non-regular or unstable entries, and verifies identity again after the bounded
read. Linux/macOS passive Git review rejects recognized unsupported descendant
mounts beneath the selected scope and canonical Git metadata/object trees, and
rejects non-empty object alternates. Initial bounded Git discovery still occurs
before those canonical paths are known; Windows Git traversal can also encounter
a nested junction on an otherwise supported fixed drive. Keep the selected
repository, its config includes, and Git object storage on trusted local media.

`discard` is the only mutation-capability projection. `available=true` means
Hecate separately captured the exact, complete raw **unstaged tracked** patch
(index → worktree), including its final newline, and `discard.revision` is the
opaque concurrency token binding those bytes to the identity of the reviewed
workspace root. Staged changes and untracked
files remain fully reviewable but are never discardable. Staged state,
intent-to-add, assume-unchanged, skip-worktree, unmerged paths, incomplete or
truncated working-tree previews, tracked Gitlinks, or a discard-capture failure leave
`available=false` with a bounded `reason` such as `staged_changes`,
`review_incomplete`, `working_tree_too_large`,
`working_tree_preview_incomplete`, or `discard_capture_failed`. A binary tracked
layer can be inventory-complete but non-exact, so it remains reviewable metadata
while `working_tree_preview_incomplete` closes discard. Persistent snapshot drift
returns HTTP `409` rather than becoming a discard reason. A discard response
can additionally close a subsequent mutation with `refresh_required`,
`cleanup_failed`, or `mutation_outcome_unknown`; refresh and inspect Git before
continuing in those states.

The top-level `revision`, `diff_stat`, `diff`, and `files` fields are a
working-tree-only compatibility projection for older clients. They never add
authority: `revision`, when present, is a legacy patch-only `sha256:` display
digest, while the root-bound `discard.revision` uses the distinct
`workspace-sha256:` scheme and is the only mutation precondition. `diff`
contains only safe text patches, and `files` does not include staged or
untracked entries. New clients must read `layers` for review and
`discard.available` / `discard.revision` for mutation; never submit the
top-level revision. Do not log or persist either revision field. Someone who
already knows a complete patch can use the display digest to test equality, so
both values are sensitive operational metadata.

Staged-only and mixed staged/working-tree workspaces return `200` with all
visible layers; staged state closes discard instead of making GET fail. A
session without a workspace returns a clean three-layer review with no
top-level revision. A clean Git workspace may retain the exact empty-patch
compatibility revision, but `discard.available=false` because there are no
working-tree changes. Non-Git workspaces return `400 invalid_request`. An
inventory too large to enumerate safely or an unsafe path representation
returns `422 invalid_request`; a workspace that keeps changing during both
capture attempts returns `409 conflict`.

Responses set `Cache-Control: private, no-store`. In remote runtime mode, an
authorized caller can therefore receive raw bounded text from untracked files;
protect this route with the same operator authentication and transport controls
as the rest of the runtime. Hecate records only low-cardinality counts,
completeness, and discard-reason telemetry for review—never paths, preview
content, or revision values.

### `GET /hecate/v1/chat/sessions/{id}/workspace-diff/files/{path}`

Returns the live unified diff for one file in the legacy top-level
working-tree compatibility projection. Encode the path as a URL path component.
Layered clients already receive tracked diffs inline and should not use this
path-keyed endpoint for staged or untracked entries.

```json
GET /hecate/v1/chat/sessions/chat_.../workspace-diff/files/README.md
→ 200
{
  "object": "chat_workspace_file_diff",
  "data": {
    "path": "README.md",
    "additions": 1,
    "deletions": 0,
    "status": "modified",
    "diff": "diff --git a/README.md b/README.md\n..."
  }
}
```

The path must be a current tracked working-tree change; Hecate rejects arbitrary
paths. This compatibility lookup performs a dedicated, literal-path capture
with a 256 KiB patch limit. It does not capture unrelated tracked patches or
open untracked bodies. A binary, oversized, Gitlink, conflict, or otherwise
metadata-only tracked entry returns `422 invalid_request` instead of
misreporting a snapshot race; only an actual concurrent capture change returns
`409 conflict`. The response also uses the private, no-store `Cache-Control`
policy.

### `GET /hecate/v1/chat/sessions/{id}/workspace-files`

Returns a current, curated file tree for the chat session's selected workspace.
This surface is intentionally separate from `workspace-diff`: clients can browse
and search unchanged workspace metadata without mixing it into the changed-file
review flow. It returns metadata, not unchanged file contents, and omits Hecate,
Git, dependency, cache, and build-output directories from traversal.

The operator UI renders this as a **Files** tab. The tree is collapsed by
default, while search expands matching directories.

```json
GET /hecate/v1/chat/sessions/chat_.../workspace-files
→ 200
{
  "object": "chat_workspace_files",
  "data": {
    "workspace": "/Users/alice/project",
    "files": [
      {
        "path": "docs",
        "name": "docs",
        "kind": "directory"
      },
      {
        "path": "README.md",
        "name": "README.md",
        "kind": "file",
        "status": "modified",
        "size_bytes": 2048
      }
    ]
  }
}
```

Sessions without a workspace return an empty file list. The response is
`private, no-store`. The optional `truncated` field is omitted when false. It is
true when traversal stops after 5,000 returned entries or cannot enter a nested
filesystem safely. Browsing is limited to supported local filesystem classes.
Linux/macOS do not recurse into recognized nested network, FUSE, or unknown
mounts and set `truncated: true` when such traversal is blocked. Windows requires
a fixed or RAM-backed drive, but nested junction/reparse traversal remains a
host-policy boundary. Hecate fails the request closed when the selected root
itself cannot be classified safely. An
entry whose type cannot be inspected without crossing that boundary uses
`kind: "unavailable"` rather than being mislabeled as a regular file.
Classification gates tree traversal and content reads; establishing the selected
root's canonical identity may first resolve an operator-selected symlink and
inspect root metadata. Workspace roots and symlink targets must therefore be on
healthy local storage.

### `POST /hecate/v1/chat/sessions/{id}/workspace-diff/revert`

Discards selected unstaged tracked changes by conditionally reverse-applying
the exact index-to-worktree Git patch the operator reviewed. Pass a non-empty
`paths` array to discard selected files, or an explicit empty array to discard
every unstaged tracked file in that patch. Omitted or `null` `paths` fail closed;
they are never interpreted as discard-all. This endpoint does not discard staged
index changes or untracked files. It is the only chat endpoint that mutates
workspace files; stored per-message diffs and all three review layers remain
read-only evidence. The body must be one JSON object, may contain only the
documented fields, and is capped at 1 MiB.
The response uses the private, no-store `Cache-Control` policy.

```json
POST /hecate/v1/chat/sessions/chat_.../workspace-diff/revert
{
  "paths": ["README.md"],
  "expected_revision": "workspace-sha256:6cc8..."
}

→ 200
{
  "object": "chat_workspace_diff",
  "discard_result": {
    "outcome": "applied"
  },
  "data": {
    "workspace": "/Users/alice/project",
    "revision": "sha256:e3b0...",
    "review_complete": true,
    "has_changes": false,
    "files": [],
    "layers": [
      { "kind": "staged", "complete": true, "files": [] },
      { "kind": "working_tree", "complete": true, "files": [] },
      { "kind": "untracked", "complete": true, "files": [] }
    ],
    "discard": {
      "available": false,
      "reason": "no_working_tree_changes"
    }
  }
}
```

`expected_revision` is required and must be copied from
`data.discard.revision` in the exact layered review the operator confirmed.
Entry ids, read-only review layers, and legacy top-level diff fields do not
authorize this endpoint. Before mutation, Hecate:

1. validates the strict request body, captures a fresh exact discard snapshot,
   restricts `paths` to that snapshot, and compares `expected_revision`;
2. closes and drains the owning chat's per-session lifecycle;
3. acquires an exclusive closure from the one process-local workspace registry,
   using canonical paths and treating parent and child roots as overlapping;
4. rereads the authoritative session and scans durable non-terminal task runs
   plus other active chat sessions for overlapping workspace roots through
   bounded, paginated active-owner projections; and
5. verifies the canonical workspace identity, hidden index flags, and staged
   state again, recaptures the complete raw scoped unstaged tracked patch, and
   compares its workspace-bound discard revision with `expected_revision`.

Task provisioning/start admission/execution, External Agent ACP turns and live
ACP terminals, task-patch apply/revert, and operator terminals use writer leases
from the same registry. A live overlapping writer, a durable active owner, or an
owning session in an active status such as `pending`, `queued`, `running`,
`in_progress`, or `awaiting_approval` returns `409 chat.agent_session_busy`, even
if a caller bypasses the UI. Unknown non-empty durable chat session or message
statuses also fail closed. The operator console disables discard controls during
known active work.

With the closures still held, Hecate pins and rechecks the selected workspace
directory identity, reserves Git's conventional real-index lock, rechecks
hidden flags and staged state, proves that the reviewed patch's old side still
applies to the live index baseline, and runs a non-mutating reverse-apply
preflight. Index contention, a committed or staged baseline change, a replaced
workspace root detected by those checks, or an ordinary overlapping edit
returns `409 conflict` before mutation. Hecate then reverse-applies selected
paths from the exact reviewed bytes under a server-owned 30-second context, so
a browser or proxy disconnect cannot cancel the destructive subprocess.
Unrelated and non-overlapping later edits are preserved. Only paths present in
the exact unstaged tracked snapshot can be discarded.

`discard_result.outcome` is `applied` when Git completed the mutation or
`outcome_unknown` when the mutating subprocess itself failed after the safe
preflight (for example an I/O failure, deadline, or late external race). The
latter is deliberately not reported as a clean conflict: selected files may be
partially restored. `cleanup_failed=true` means releasing the Git index
reservation failed; it does not by itself prove whether mutation completed.
Only `outcome=applied` confirms the apply completed, while
`outcome=outcome_unknown` can be combined with the cleanup warning.
`refresh_required=true` accompanies either warning and also appears when Hecate
could not capture a fresh layered review after a completed apply. In every such
case discard remains unavailable in the returned review and the operator must
refresh, inspect every selected file, and check Git before continuing. These
fixed fields never expose a path, patch, revision, or raw process error.

Staged changes are visible in GET Review but block discard. Intent-to-add,
assume-unchanged, skip-worktree, unmerged state, an incomplete working-tree
snapshot, or an oversized exact patch also prevents Hecate from issuing or
accepting discard authority. Refresh after resolving that Git state; do not
derive a token from display content.

The shared registry coordinates one Hecate process and is not a distributed
lock. The transient Git index reservation coordinates with well-behaved Git
index writers only; it does not exclude direct worktree edits or non-cooperating
index writes. The durable-owner scan, index reservation, and conditional reverse
apply are independent fail-closed protections, not a guarantee of replica-wide
atomic exclusion.

Status codes:

- `200 OK` with `discard_result` and the refreshed layered workspace review,
  or an explicitly incomplete `refresh_required` review when post-mutation
  state could not be recaptured. `outcome_unknown` is still `200` because a
  mutation may already have occurred; it is never presented as a no-op error.
- `400 invalid_request` when the JSON is malformed, has unknown fields or
  trailing values, `paths` is omitted or null, `expected_revision` is missing,
  a requested path is not present in the exact discard snapshot, or the selected
  workspace is missing or is not a Git worktree.
- `404 not_found` when the chat session does not exist.
- `409 conflict` when the workspace revision changed after review, Git's index
  is busy, hidden or staged state appears after the final snapshot, or the exact
  patch no longer applies because a later edit overlaps a selected hunk.
- `409 chat.agent_session_busy` while the selected chat or another overlapping
  workspace owner has active work.
- `413 invalid_request` when the request body exceeds 1 MiB.
- `422 invalid_request` when the initial discard snapshot is unavailable
  because the scoped workspace has staged or hidden index state, unsafe path
  representation, or an exact unstaged tracked patch above the safe limit.
- `500 gateway_error` when Hecate cannot capture or apply the snapshot for an
  unclassified internal failure, cannot verify durable ownership, or cannot
  release a pre-mutation Git index reservation safely.

### `GET /hecate/v1/chat/sessions/{id}/stream`

Streams live chat session snapshots as Server-Sent Events. This is an
in-process live feed, not the durable task-event log: session history remains in
the configured chat-session backend, while the stream fans out updates from the
currently running gateway process.

```text
event: snapshot
data: {"object":"chat_session","data":{...}}

event: done
data: {"object":"chat_session","data":{"status":"completed",...}}
```

Clients should subscribe before sending a message so they can receive live
updates. A client that loads or reconnects to an authoritatively busy External
Agent session should subscribe again, apply the stream's initial full snapshot,
and follow later updates until the exact turn is terminal. Losing an SSE
connection does not cancel an admitted External Agent turn; clients may reopen
the stream with bounded backoff and poll the session snapshot as a fallback.
The server treats live notifications as low-latency hints and rereads the
durable session for every session notification and on its 15-second heartbeat.
A delayed buffered notification therefore cannot overwrite a newer durable
snapshot, and a committed terminal state still emits the final snapshot and
`done` if its immediate publication was lost. During an External Agent turn,
the assistant's terminal row may commit before session metadata and turn
counters finish settling; a reconnecting stream and heartbeat defer unmarked
terminal notifications until a final settlement publication bound to the exact
terminal assistant message, or until the live turn clears and a later heartbeat
confirms the fully settled durable state. A delayed settlement marker from an
older turn cannot authorize a newer terminal row. A stream that attaches inside
that narrow settlement window can
therefore receive a heartbeat comment before its first full snapshot.
If an External Agent session has a durable trailing user message but no live
turn, the stream request returns `409 chat.session_not_running`. Passive
observers should surface the interrupted admission rather than reconnecting
indefinitely. A stream paired with a replacement message submit should retry
until that POST is admitted or settles, because the stream can observe the
previous orphan immediately before the new POST registers its turn.
If that reconciliation fails after streaming headers were sent, the server
emits a fixed operator-safe `error` event and closes the stream; clients should
reconnect or use the session GET rather than treating the last snapshot as
terminal.
For External Agent sessions, snapshots include partial ACP output from the
adapter. For task-backed Hecate Chat turns, snapshots can include partial
assistant text from the backing task's streamed model call plus projected task
activity.
Projected task activity uses the same compact vocabulary as Task Detail:
tool calls, approvals, changed files, final-answer artifacts, terminal state,
and a low-level Details group. The stream stays open for an idle or previously
completed session and closes after it observes a new running message reach a
terminal status (`completed`, `failed`, or `cancelled`).

### `POST /hecate/v1/chat/sessions/{id}/cancel`

Cancels the currently running ACP turn for the session.

```json
POST /hecate/v1/chat/sessions/chat_.../cancel
{}
```

Returns `202` when a running turn was signalled. If the session is not
currently running, the endpoint returns `409 invalid_request`.

The session snapshot in a `202` response is an acknowledgement, not terminal
proof: cancellation is asynchronous and the returned snapshot may still show
the pre-signal `running` or `awaiting_approval` state. Clients must retain a
session-and-turn-scoped terminal fence, reject reordered non-terminal snapshots
and approval requests for that stopped turn, and release it only after the
matching SSE stream, original message POST, or a GET started after the accepted
Stop reports a terminal turn (`completed`, `failed`, or `cancelled`). A bounded
UI wait may release interaction ownership, but must not remove that terminal
fence or let stale approval controls reappear. If a later cancellation retry
fails, clients must restore any earlier accepted fence and keep the original
turn's terminal path alive for a renewed bounded settlement window.

### `POST /hecate/v1/chat/sessions/{id}/close`

Closes the native ACP agent session while keeping the Hecate chat history.
If a turn is currently running, Hecate cancels and waits briefly before closing
the external session. This uses ACP `session/close` and does not delete the
provider-side native session from the adapter's session list.
The close advances and owns a per-session lifecycle generation until the native
close returns. Lifecycle snapshots are leased only while their requests remain
in flight. Destructive owners execute serially, wait for already-admitted
attachment/config mutations, reread the authoritative session, and cancel an
already-registered turn. A request whose session snapshot predates the close,
including one delayed until after admission reopens, receives
`409 chat.session_stopping` before transcript mutation or runtime dispatch;
inactive lifecycle state is reclaimed after every lease and operation drains.

### `DELETE /hecate/v1/chat/sessions/{id}`

Deletes a chat session from the configured chat-session backend.
If the session has an active native ACP agent process, Hecate asks the adapter
to delete the native session with ACP `session/delete` and terminates the owned
process as part of deletion. If the adapter does not support `session/delete`,
Hecate falls back to `session/close` before tearing down the process.
If the session is a task-backed Hecate Chat, Hecate first cancels its linked
backing Task Run, waits for the live Chat handler, then cancels every remaining
non-terminal Task Run durably owned by that Chat origin. This final ownership
scan catches a task created before its session link persisted. Before scanning,
deletion closes the process-scoped origin-run gate and waits for every admitted
start, retry, resume, continue, retry-from-model-call, and approval-resolution
mutation to finish. It holds that fence through durable session deletion; later
run creation and approval requeue also validate durable chat ownership so a
process restart cannot reopen retained history and validator-backed in-memory
fence state can be reclaimed. The backing Task records and Run history remain
available from Tasks; cancellation uncertainty fails the delete closed with
`409`.
Deletion advances per-session lifecycle admission before cancellation and holds
that guard through transcript and attachment cleanup. Overlapping destructive
requests run one at a time and reread the session after acquiring ownership, so
none dispatches from stale task or native-session fields. A turn or attachment
write that registered first is cancelled or drained before cleanup; a delayed
request whose earlier lifecycle snapshot is stale receives
`409 chat.session_stopping` before message append, attachment persistence or
deletion, claim/body access, or provider, task, or ACP dispatch. Project
deletion uses the
same guarded session-delete path. The reserved system-reset endpoint does not
call session deletion because it fails before mutation.
Deletion is idempotent: an already-missing session still runs session-scoped
attachment cleanup and returns `204`. Project deletion also sweeps attachment
bodies whose transcript owner is already gone before project chat cleanup, so a
retry repairs a partial cross-store session delete. In Cairnline-authoritative
mode, a later cleanup failure attempts to restore only the deleted project's
portable snapshot; unrelated project state is not rolled back.

### `POST /hecate/v1/workspace-dialog`

Opens a local folder picker from the gateway process and returns the selected
workspace path. The browser cannot safely expose absolute folder paths on its
own, so this endpoint is intentionally local-runtime-oriented.

```json
POST /hecate/v1/workspace-dialog
{}

→ 200
{
  "object": "workspace_dialog",
  "data": {
    "path": "/Users/alice/project",
    "branch": "main"
  }
}
```

The local gateway uses a cross-platform native-dialog helper for folder
selection. If the host has no usable dialog backend, the endpoint returns
`501` and the UI falls back to a manual path entry. If the operator cancels
the dialog, the endpoint returns `200` with an empty path and the UI keeps the
workspace unchanged. Hecate allows only one folder picker at a time; concurrent
requests return `409 conflict`.

### `POST /hecate/v1/workspace-open`

Opens a validated local workspace directory in an editor, terminal, or file
manager from the gateway process. This is the browser fallback for the Chats
header open-workspace menu; the Tauri app uses its native command path instead.

```json
POST /hecate/v1/workspace-open
{
  "path": "/Users/alice/project",
  "target": "cursor"
}

→ 200
{
  "object": "workspace_open",
  "data": {
    "path": "/Users/alice/project",
    "target": "cursor"
  }
}
```

`target` is one of `vscode`, `vscode_insiders`, `cursor`, `zed`, `finder`,
`terminal`, `iterm2`, or `xcode`. The endpoint accepts only loopback clients,
canonicalizes `path`, requires it to be a directory, and returns `403` for
non-local callers so a remotely hosted Hecate cannot unexpectedly launch apps
on the server machine.

### Operator terminals

Operator terminal sessions are disabled by default. Set
`HECATE_OPERATOR_TERMINALS=1` to enable them on a local runtime. Remote runtime
mode rejects this flag and the endpoints are local-only: non-loopback sockets
and forwarded-client headers are rejected.

```json
POST /hecate/v1/terminals
{
  "workspace": "/Users/alice/project",
  "working_directory": ".",
  "command": "npm",
  "args": ["test"],
  "output_byte_limit": 1048576
}

→ 201
{
  "object": "terminal",
  "data": {
    "id": "term_8a7f...",
    "workspace": "/Users/alice/project",
    "working_directory": "/Users/alice/project",
    "command": "npm",
    "args": ["test"],
    "output": "",
    "truncated": false,
    "running": true,
    "created_at": "2026-06-22T10:00:00Z",
    "updated_at": "2026-06-22T10:00:00Z"
  }
}
```

Hecate canonicalizes `workspace`, resolves relative `working_directory` inside
that workspace, rejects escapes, sanitizes the child environment, applies the
same static command checks and OS sandbox wrapper path used by shell tasks where
available, and retains bounded merged stdout/stderr. A live terminal holds
workspace-writer admission until its owned Unix process group or Windows Job
Object and output pipes are observed drained, including for overlapping parent
or child workspace roots. A close deadline can return before drain without
releasing that admission. A
destructive workspace discard therefore reports `409` while such a terminal is
live, and terminal creation reports `409` while a destructive discard owns the
workspace closure.

On Unix, creation returns `400 invalid_request` before spawn for literal known
session/process-group detachers, shell job-control escapes, and unsafe dynamic
command forms. Hecate also checks writes when stdin is executable interactive
shell/interpreter code; it does not scan ordinary stdin data for a script or
inline command unless a force-interactive option keeps executable stdin active.
Explicit shell stdin such as `sh -` and `bash -` is always code-scanned. Shell
writes retain at most 64 KiB of syntactically incomplete input and fail closed
at that bound; validated complete commands leave no cumulative history.
Interpreter input retains only fixed-size token tails. The check is static and
best effort: sourced/generated/encoded code, arbitrary execution wrappers,
custom binaries/syscalls, and delegation to an external service manager remain
outside this guarantee. Windows terminal lifecycle uses a Job Object, while its
filesystem/network posture remains the documented trusted-subprocess boundary.

Use `GET /hecate/v1/terminals/{terminal_id}/output` to read retained output,
`POST /hecate/v1/terminals/{terminal_id}/input` with `{"input":"...\n"}` to
write stdin, `POST /hecate/v1/terminals/{terminal_id}/wait` to wait for exit,
`POST /hecate/v1/terminals/{terminal_id}/kill` to terminate without releasing,
and `DELETE /hecate/v1/terminals/{terminal_id}` to release resources. Released
terminal IDs become invalid for all other terminal endpoints.

`GET /hecate/v1/whoami` also reports
`capabilities.local_providers_allowed`. Local mode reports `true`; cloud
runtime mode reports `false` by default and `true` only when
`HECATE_REMOTE_ALLOW_LOCAL_PROVIDERS=1` is explicitly set.

The operator console does not embed a terminal UI. The opt-in local terminal API
is for trusted operator clients that need a workspace-scoped process with the
documented checks and output bounds. Operators who need unrestricted host
access should use their normal local terminal or the deployment platform's
administrative shell (`ssh`, `docker exec`, `kubectl exec`, a provider console,
or equivalent).

## Rate-limit headers on chat / messages

Every response from `POST /v1/chat/completions` and `POST /v1/messages` carries three rate-limit headers, regardless of whether rate limiting is enabled (the headers are zero-value when off):

| Header                  | Type         | Meaning                                                       |
| ----------------------- | ------------ | ------------------------------------------------------------- |
| `X-RateLimit-Limit`     | int          | Steady-state refill rate (`HECATE_RATE_LIMIT_RPM`).           |
| `X-RateLimit-Remaining` | int          | Tokens still available in the bucket. Decrements per request. |
| `X-RateLimit-Reset`     | Unix seconds | When the bucket will be full again.                           |

Over-limit requests get `429 Too Many Requests` with the standard error envelope and `code: "rate_limit_exceeded"`. See [Deployment: Rate limiting](../operator/deployment.md#rate-limiting) for the env-var knobs.