iit-mcp-autotask 0.14.0 → 0.26.0

package/.env.example

@@ -50,14 +50,18 @@ MCP_TRANSPORT=stdio
 
 # --- Profile and toolsets (0.6.0) ---
 # readonly (default): reads only, no state. operator: adds autotask_write (preview) and
-# autotask_apply (execute the previewed plan), governed by a policy file; needs the four below.
+# autotask_apply (execute the previewed plan), governed by AUTOTASK_WRITE; needs the state dir and run scope below.
 AUTOTASK_PROFILE=readonly
-# operator: the write policy (closed JSON schema, default deny; see examples/policy.time-entries.json).
-# AUTOTASK_POLICY_FILE=/etc/autotask-mcp/policy.json
+# operator: which writes are served: allow, gate (a person confirms) or deny per operation; unlisted is read-only.
+# Grammar, dedup, limits and trusted host prompts: docs/write-gate.md.
+# AUTOTASK_WRITE=*:gate,tickets.*:allow,time_entries.create:allow,companies.update:deny
+# AUTOTASK_DEDUP=companies.create:companyName
+# AUTOTASK_WRITE_LIMITS=50/h,200/d
+# AUTOTASK_TRUSTED_HOST_PROMPT=stdio
 # operator: the state dir (mode 0700; plans, ledger, audit log, lock; one process per dir).
 # AUTOTASK_STATE_DIR=/var/lib/autotask-mcp
-# operator on stdio: the run scope (required), {"companyIds":[...]} or {"all":true} (= the policy's
-# own scope). It only narrows the policy. On HTTP set runScope per token instead.
+# operator on stdio: the run scope (required), {"companyIds":[...]} or {"all":true} (any
+# company). On HTTP set runScope per token instead.
 # AUTOTASK_RUN_SCOPE={"companyIds":[12345]}
 # operator on stdio: the principal plans and the audit log are bound to (default stdio).
 # AUTOTASK_PRINCIPAL=nightly-time-entries

package/README.md

@@ -40,17 +40,18 @@ its contract, `autotask_read` runs it.
   `include_api_users: true`; `by: "email"` narrows to the email field; a numeric identifier is looked up
   as a Resource id); compact rows carry `apiUser` and the licence label when the tenant's labels tell it, never an email. Every match carries `ref`, its human reference. A sweep returns compact matches (`resource`, `ref`, `id`, the human fields) unless `expand: true` (the full record under `record`); `limit` caps the TOTAL matches across resources (resource order, then the SDK's order) and a contains sweep reports `truncated` and per-resource `counts {returned, found}`.
 - `autotask_query` is the bounded filtered list over `resource`: `tickets`, `time_entries`,
-  `service_calls`, `contracts`, `time_off_requests` (limit default 50, max 2500).
+  `service_calls`, `contracts`, `time_off_requests` (limit default 50, max 2500). The served filter
+  schema declares each condition as `{field, op, value}` strings, so a client that builds one type
+  per array column writes `"29"`, `"true"`, `"2026-10-22"`; numbers, `in` arrays and and/or groups are
+  still accepted and passed through unchanged.
 - `autotask_read` runs any read by exact key, or up to 10 at once (`items`). Unbilled work
   (`companies.unbilledWork`), contract profitability (`contracts.profitability`), aggregates
   (`operations.aggregate`) and SLA health (`tickets.slaHealthCheck`) run here; `autotask_guide`
-  holds their recipes. The two time-entry window keys (`time_entries.dateWorkedWindow`,
-  `time_entries.postedWithin`) also take flat named inputs instead of `args`, for clients that cannot
-  send a mixed-type array (Copilot Studio): `{operation, from, to, posted?, limit?, ticketID?,
-  resourceID?}`, `from`/`to` as inclusive `YYYY-MM-DD` dateWorked days (never UTC-converted),
-  `ticketID`/`resourceID` as numbers, no `tz` (it does not shift dateWorked). The SDK's
-  `foldFlattenedOpts` maps them onto its named invoke form, so the result and `truncated` flag are
-  the positional call's. `autotask_read` and `autotask_fetch_many` answer ONE envelope (the next minor,
+  holds their recipes. Its inputs are generic (`operation`, `args`, `items`): no operation-specific
+  fields, because form-filling clients (Copilot Studio) fill every optional input they are shown. A
+  client that cannot send a mixed-type array asks for a time entry window over a resource with
+  `autotask_query` `time_entries` (`resourceID` eq, `dateWorked` gte/lte, every value a string: the
+  served filter schema types `value` as a string). `autotask_read` and `autotask_fetch_many` answer ONE envelope (the next minor,
   breaking): `data = { results: Slot[], ok, failed, budget?, budgetWarning? }`, an array in input
   order even for a single read (`data.results[0].result`). A slot is `{ ok: true, operation, result,
   windowNote? }` or `{ ok: false, operation, error }`; fetch_many slots also echo `resource` and `id`
@@ -85,7 +86,7 @@ part miss never fails the call (typed `absent`); only a missing root record fail
 **Every result is one envelope** (`structuredContent`, mirrored as JSON in the first text block):
 
 ```
-{ status: ok|needs_input|ambiguous|needs_approval|denied|error,
+{ status: ok|needs_input|ambiguous|denied|error,
   data, next: proceed|supply_input|choose_candidate|...|retry|stop,
   reasons: [{ code, field?, detail }], retryable, correlationId, summary }
 ```
@@ -119,7 +120,7 @@ server metadata: [`server.json`](server.json) · per-workflow mapping:
 
 | Variable | Default | Effect |
 |----------|---------|--------|
-| `AUTOTASK_PROFILE` | `readonly` | `readonly`: reads only (approval mode `off`), no state. `operator`: adds `autotask_write` and `autotask_apply` (approval mode `policy`); see [Operator profile](#operator-profile-writes). On HTTP it requires `AUTOTASK_HTTP_AUTH=tokens`. |
+| `AUTOTASK_PROFILE` | `readonly` | `readonly`: reads only, no state. `operator`: adds `autotask_write` and `autotask_apply`; see [Operator profile](#operator-profile-writes). On HTTP it requires `AUTOTASK_HTTP_AUTH=tokens` or `gateway`. |
 | `AUTOTASK_TOOLSETS` | — (core only) | comma list of `service`, `records`, `finance`, or `all`; an unknown name fails boot |
 
 Every write and delete is refused on the read path (`autotask_read`) before any request
@@ -142,65 +143,44 @@ An operator deployment needs:
 | Variable | Meaning |
 |----------|---------|
 | `AUTOTASK_PROFILE=operator` (or an operator token) | the profile |
-| `AUTOTASK_POLICY_FILE` | the write policy: a closed JSON schema, default deny ([example](examples/policy.time-entries.json)) |
+| `AUTOTASK_WRITE` | which writes are served and how: `allow`, `gate` or `deny` per operation, unlisted is read-only (grammar in [docs/write-gate.md](docs/write-gate.md)) |
 | `AUTOTASK_STATE_DIR` | mode 0700; holds encrypted plans, the idempotency ledger, the hash-chained audit log, the primary lock and the holder registry (many processes may share one dir — see below) |
-| `AUTOTASK_RUN_SCOPE` | stdio: `{"companyIds":[...]}` or `{"all":true}` (the policy's own scope); it can only narrow the policy. On HTTP each operator token carries `runScope` instead |
+| `AUTOTASK_RUN_SCOPE` | `{"companyIds":[...]}` or `{"all":true}`: the run scope on stdio and in gateway mode (one scope shared by every gateway principal). In tokens mode each operator token carries `runScope` instead |
 | `AUTOTASK_PRINCIPAL` | stdio: the name plans and the audit log are bound to (default `stdio`) |
 | `AUTOTASK_KILL_FILE` | optional: while this file exists every preview and apply is denied (default `<state dir>/KILL`) |
 
-What the policy can and cannot do:
-
-- An operation the policy does not list is `OP_NOT_ALLOWED`. Per operation: `approval`
-  (`none`/`required`), `maxPerHour`, `maxPerDay`, `maxDistinctTargetsPerDay`, a `fields` allowlist,
-  `forbidRemovals`, `requireReason`, UTC `windows`, `duplicateCheck` (required for creates) and
-  `allowUnattended`. Globally: `write.scope.companyIds`, `createdHereWithinDays`, and
-  `limits.writesPerHour`/`writesPerDay`.
-- Moving a time entry or ticket charge to another ticket (#107): list `time_entries.moveToTicket` or
-  `ticket_charges.moveToTicket` with an `owner` block, e.g. `{"approval": "none", "allowUnattended": true,
-  "owner": {"mode": "createdHere", "days": 7}}` (`createdHere`: this server created the source for this
-  principal within 1-14 days; or `{"mode": "resourceIDs", "ids": [..]}` for time entries, whose `resourceID`
-  must be listed; a charge has no owning resource). Preview `autotask_write {operation, args: [sourceId,
-  toTicketId]}`, then apply. The server creates the copy on the target ticket, verifies it and deletes the
-  original (the vendor ignores an update of `ticketID`): the new record gets a new id, create date and
-  creator, and notifications may fire. A move into another company or contract always needs a signed
-  approval grant; an unfinished earlier move of the same source blocks another until its ledger entry ages
-  out (14 days) or a person clears it: in a terminal, as the server's OS user, with `AUTOTASK_STATE_DIR` set,
-  `autotask-mcp moves list` shows the blocked sources and `autotask-mcp moves resolve <resource>:<id>` (after you
-  checked both tickets in Autotask; you type the source id, and the copy's id when the ledger names one) closes the
-  ledger lines as `MOVE_RESOLVED` and audits it (`move_resolved`). It refuses within 10 minutes of the move being sent
-  (its engine may still be running) and, while the engine may still run, when the sending server is still registered or alive. A plan previewed
-  before the resolve cannot apply after it. It is not an
-  MCP tool; like the approvals CLI it is a guardrail, not a boundary against an agent with a same-user shell. Billed, attached, approved, closed-target and older-than-14-days sources are refused.
-- Hard rules no policy overrides: `authenticate.*` is never served; operations the SDK flags
-  `requiresApproval`, and non-read sensitive ones (webhooks, `resources.transferOwnership`), always
-  need approval; destructive and account-wide operations need it, and `allowUnattended` cannot waive
-  that for an operation the hard rules cover. In approval mode `policy` no approver
-  exists: an approval-required write answers `needs_approval` with `next: manual_action` (no plan
-  handle) and is never executed. Approval mode `external` (`approvalMode: "external"` plus an `approvals`
-  block listing ed25519 approver keys, each scoped to operations) is being added in stages (#106): a gated
-  preview stores a pending plan (`next: await_approval`, handle, hash, expiry of grant window + 5 minutes) that
-  executes only with a valid ed25519 grant file `approvals/grants/<handle>.json` signed by a listed approver
-  (apply verifies it; deny rules still win; one use per plan). A human decides with the CLI, run in their own
-  terminal as the server's OS user with `AUTOTASK_STATE_DIR` and `AUTOTASK_POLICY_FILE` set as the server has them:
-  `autotask-mcp keygen <approver-id> --ops <op,op|*>` (creates a passphrase-sealed ed25519 key, mode 0600, default
-  `~/.config/iit-mcp-autotask/approver.key` or `$AUTOTASK_APPROVER_KEY_FILE`, and prints the entry for
-  `approvals.approvers`), then `autotask-mcp approvals list|show|approve|reject <handle>`. `show` and `approve`
-  recompute the plan hash and snapshot hash from the stored plan and refuse on a mismatch or a changed policy; they
-  print only verified fields, and every agent-supplied string (arguments, the agent's reason) is JSON-encoded behind
-  `| ` inside a labelled untrusted block with control and bidi characters stripped. `approve` and `reject` need you to
-  type the first 8 characters of the plan hash and the key passphrase; the passphrase is read from `/dev/tty` only
-  (never the environment, arguments, a pipe or a file; there is no `--yes`), so the command refuses without a
-  terminal and on Windows. `approve` and `reject` refuse while any shown value was cut for display (it would be signed in full): review with `show <handle> --full`, then pass `--full`. The first decision per plan is final. This stops accidents, not an agent that can drive a
-  pty, and on stdio the sealed key file can be attacked offline by anything running as the same user. On HTTP run it
-  where the state dir lives (for example `docker exec -it` as the server's user). On stdio this is a
-  guardrail against a mistaken agent, not a boundary against an adversarial agent running as the same OS
-  user; it is a real boundary only on HTTP with the server, its key material and the policy file isolated
-  from the agent. Any edit to the policy file (including `approvals`) changes the policy hash and voids
-  every outstanding plan. `data.manual` carries a fingerprint of the record (ids, ticket,
-  start time, hours, resource — numbers and instants only, never vendor text) and, when the pinned
-  SDK provides `operations.uiLink`, a clickable Autotask deep link; a person finishes the job in
-  Autotask. A policy that sets `approval: "none"` on such an operation changes nothing: boot logs a
-  warning and `doctor` prints it. There is no `autotask_delete` (D-12): deletes preview through `autotask_write`.
+What the write access can and cannot do (full reference: [docs/write-gate.md](docs/write-gate.md)):
+
+- `AUTOTASK_WRITE` lists operations, families (`tickets.*`) or `*`, each `allow` (applies without a
+  person), `gate` (a person confirms the apply) or `deny`. An operation not listed is `OP_NOT_ALLOWED`.
+  `AUTOTASK_DEDUP` names the duplicate-check fields for a create, `AUTOTASK_WRITE_LIMITS` caps writes
+  (`50/h,200/d`) and `AUTOTASK_TRUSTED_HOST_PROMPT` names the clients whose own permission prompt counts
+  as the confirmation. A bad entry fails boot.
+- A gated apply is confirmed by a trusted host's own prompt, else by one confirm form (MCP elicitation);
+  a client that can do neither gets `GATE_UNSUPPORTED`, and a decline or dismissal `GATE_DECLINED`.
+  Nothing is sent in either case.
+- Moving a time entry or ticket charge to another ticket (#107): `time_entries.moveToTicket` and
+  `ticket_charges.moveToTicket`. Preview `autotask_write {operation, args: [sourceId, toTicketId]}`, then
+  apply. The server creates the copy on the target ticket, verifies it and deletes the original (the
+  vendor ignores an update of `ticketID`): the new record gets a new id, create date and creator, and
+  notifications may fire. A move into another company or contract is always gated. An unfinished earlier
+  move of the same source blocks another until its ledger entry ages out (14 days) or a person clears it:
+  in a terminal, as the server's OS user, with `AUTOTASK_STATE_DIR` set, `autotask-mcp moves list` shows
+  the blocked sources and `autotask-mcp moves resolve <resource>:<id>` (after you checked both tickets in
+  Autotask; you type the source id, and the copy's id when the ledger names one) closes the ledger lines
+  as `MOVE_RESOLVED` and audits it (`move_resolved`). It refuses within 10 minutes of the move being sent
+  and, while the engine may still run, when the sending server is still registered or alive. A plan
+  previewed before the resolve cannot apply after it. It is not an MCP tool, and it is a guardrail, not a
+  boundary against an agent with a same-user shell. Billed, attached, approved, closed-target and
+  older-than-14-days sources are refused.
+- Hard rules no setting overrides: `authenticate.*` is never served; operations the SDK flags
+  `requiresApproval` or sensitive (webhooks, `resources.transferOwnership`, `contacts.create`) can only
+  be `gate` or `deny`. An exact `allow` entry for one is a boot error; a family or `*` entry resolves it
+  to `gate`. Destructive and move operations can be `allow`ed (see the trust model in the doc).
+- When a person must finish a job by hand (a move whose source delete the vendor refused), the result is
+  `next: manual_action` and `data.move.manualAction` carries what to do and, when the pinned SDK
+  provides `operations.uiLink`, a clickable Autotask deep link. There is no `autotask_delete` (D-12):
+  deletes preview through `autotask_write`.
 - The company scope is read from the live records the write touches (the target, its parent, the
   ticket, project, task or contract it references, and any `companyID` it sets), never from names
   or titles. A reference that cannot be read is refused.
@@ -214,7 +194,7 @@ precomposed form after NFC (for example a lone U+0301) is refused `INPUT_INVALID
 precomposed character.
 
 Outcomes the caller acts on: `ok`/`proceed`; `needs_input`/`supply_input` (`missing` names the
-field); `needs_approval`/`await_approval`; `denied`/`stop`; `STATE_DRIFT` or `PLAN_EXPIRED` →
+field); `denied`/`stop`; `STATE_DRIFT` or `PLAN_EXPIRED` →
 `repreview`; a failed write: `WRITE_FAILED` with `stop` (a deterministic rejection; it replays,
 fix the input and use a new key) or `RATE_LIMITED` with `retry` (nothing was written: apply the
 same plan again after the wait); a vendor that accepted an update but kept the old value (`FIELD_NOT_PERSISTED` with `stop`: the apply reads the stored record back and compares every field you sent; the write itself is `succeeded`, `data.record` shows what is stored and `data.notPersisted` names the fields — do not repeat the update, the vendor does not support changing them; a replay answers the same); an unknown outcome (`WRITE_OUTCOME_UNKNOWN`,
@@ -472,7 +452,7 @@ No aliases: old names fail as unknown tools.
 | `quote_get`, `contact_full_profile`, `contract_full_profile`, `project_get_context`, `resource_workload` | same names (toolsets) |
 | `configurationItem_profile`, `serviceCall_full_profile` | `configuration_item_profile`, `service_call_full_profile` |
 | `write`, `delete`, `timeEntry_create` | `write {operation, args, idempotency_key?}` then `apply {plan}` (operator profile) |
-| env `READ_ONLY` / `WRITE_POLICY` / `WRITE_ALLOW` / `SECRET_READS` | `AUTOTASK_PROFILE` + `AUTOTASK_POLICY_FILE` + `AUTOTASK_STATE_DIR` + `AUTOTASK_RUN_SCOPE`; boot fails if an old variable is set |
+| env `READ_ONLY` / `WRITE_POLICY` / `WRITE_ALLOW` / `SECRET_READS` | `AUTOTASK_PROFILE` + `AUTOTASK_WRITE` + `AUTOTASK_STATE_DIR` + `AUTOTASK_RUN_SCOPE`; boot fails if an old variable is set |
 | CLI default stdio, bind on all interfaces | http on `127.0.0.1` by default; local clients pass `--transport stdio` |
 | results: per-tool shapes, errors as a text JSON payload | one envelope; the old payload is the envelope `data` |
 
@@ -487,12 +467,11 @@ No aliases: old names fail as unknown tools.
    `tokens`); a server-held credential on HTTP needs `tokens`.
 4. Read-only use needs nothing else. Pick toolsets with `AUTOTASK_TOOLSETS` if the agent used the
    service, records or finance tools.
-5. Writes (the operator profile): write a policy file (start from
-   `examples/policy.time-entries.json`: a time entry there needs `startDateTime` for its duplicate
+5. Writes (the operator profile): set `AUTOTASK_WRITE` (see [docs/write-gate.md](docs/write-gate.md)) and `AUTOTASK_DEDUP` (a time entry needs `startDateTime` for its duplicate
    check, Service tickets need `startDateTime` and `endDateTime`, and `billingCodeID` must be an active
    general allocation code), create the state dir's parent, and set
-   `AUTOTASK_PROFILE=operator`, `AUTOTASK_POLICY_FILE`, `AUTOTASK_STATE_DIR` and a run scope
-   (`AUTOTASK_RUN_SCOPE` on stdio, `runScope` per token on HTTP). The first boot creates the state
+   `AUTOTASK_PROFILE=operator`, `AUTOTASK_WRITE`, `AUTOTASK_STATE_DIR` and a run scope
+   (`AUTOTASK_RUN_SCOPE` on stdio and in gateway mode, shared by every principal; `runScope` per token in tokens mode). The first boot creates the state
    dir (0700), its key and its lock. There is nothing to migrate: 0.5.x kept no write state.
 6. Update agent prompts and playbooks to the new tool names (table above) and to the envelope's
    `status`/`next`.
@@ -512,7 +491,7 @@ preview/apply path; a plan previewed under 0.6.0 cannot be applied after a rollb
 | `GET /health` | process alive — pre-auth, **no vendor call** (container healthcheck) | none |
 | `GET /ready` | config valid, SDK plan-hash pin checked, server initialised, client factory ready — **no live vendor call** (credentials are request-scoped). In an operator deployment the payload also carries `lock` (the state lock's age, holder id, lease freshness and the holder count — see "The state lock: recovery") | none |
 | `GET /doctor` | zero-wire credential/config preflight: per credential field `present`/`len`/`prefix2`/`shapeOk` (`AUTOTASK_SECRET`'s prefix is masked to `[REDACTED]` — no character of a secret is ever emitted; identifiers keep their format prefix), the base-url + allow-list resolution (`default_only` / `allow_list` / `default_and_list` / `any`), the SDK plan-hash gate status and the host-policy mode — **no vendor call, by construction** | Host/Origin validated; a bearer token in `tokens` mode |
-| `GET /metadata` | server identity + the MCP protocol **era pair** (baseline `2026-07-28` + legacy fallback `2025-11-25`) + capability-manifest pointer + the `deployment` block (profile, toolsets, approval mode, caller auth, rate limiting) — the served payload is the repo's `server.json` + build stamp | Host/Origin validated; a bearer token in `tokens` mode |
+| `GET /metadata` | server identity + the MCP protocol **era pair** (baseline `2026-07-28` + legacy fallback `2025-11-25`) + capability-manifest pointer + the `deployment` block (profile, toolsets, caller auth, rate limiting) — the served payload is the repo's `server.json` + build stamp | Host/Origin validated; a bearer token in `tokens` mode |
 
 ## Configuration
 
@@ -523,9 +502,12 @@ non-zero on an invalid config (fail-fast) instead of failing at the first tool c
 |----------|----------|---------|---------|
 | `MCP_TRANSPORT` | no | `http` | `stdio` or `http`; the CLI `--transport` flag overrides |
 | `AUTOTASK_PROFILE` | no | `readonly` | `readonly` or `operator` (see [Profiles and writes](#profiles-and-writes)) |
-| `AUTOTASK_POLICY_FILE` | operator | — | the write policy file (see [Operator profile](#operator-profile-writes)) |
+| `AUTOTASK_WRITE` | operator | — | per-operation `allow`/`gate`/`deny` (see [docs/write-gate.md](docs/write-gate.md)) |
+| `AUTOTASK_DEDUP` | no | — | create duplicate-check fields, e.g. `companies.create:companyName` |
+| `AUTOTASK_WRITE_LIMITS` | no | — | write caps, e.g. `50/h,200/d` |
+| `AUTOTASK_TRUSTED_HOST_PROMPT` | no | — | `stdio` and client ids whose own prompt confirms a gated apply |
 | `AUTOTASK_STATE_DIR` | operator | — | the operator state dir (0700) |
-| `AUTOTASK_RUN_SCOPE` | operator on stdio | — | `{"companyIds":[...]}` or `{"all":true}` |
+| `AUTOTASK_RUN_SCOPE` | operator on stdio or gateway | — | `{"companyIds":[...]}` or `{"all":true}` |
 | `AUTOTASK_PRINCIPAL` | no | `stdio` | the stdio operator principal |
 | `AUTOTASK_KILL_FILE` | no | `<state dir>/KILL` | the kill switch file |
 | `AUTOTASK_USER_TIMEZONE` | no | `UTC` | IANA time zone of the people asking (their local "today"), not the Autotask tenant's or the server's zone; region/city names only (e.g. `Australia/Melbourne`), kept as written with only the case of a listed name fixed (`Europe/Kyiv` stays `Europe/Kyiv`); `utc`, `Etc/UTC` and `GMT` mean `UTC`; fixed offsets (`+10:00`, `Etc/GMT-10`) and names without a region (`EST`, `Japan`) fail boot. Autotask stores UTC; the zone is told to clients (`autotask_tenant_status` `time` part: zone, local time, UTC time, offset; one line in the server instructions when not UTC) so "today" and "yesterday" become UTC bounds in the right zone for moment fields such as ticket creation and due times. Time entries are calendar days: `dateWorked` and `time_entries.dateWorkedWindow` take plain `YYYY-MM-DD`, not UTC bounds. Filter values are never converted. |
@@ -548,7 +530,7 @@ non-zero on an invalid config (fail-fast) instead of failing at the first tool c
 | `MCP_HOST` | no | `127.0.0.1` | http bind address (`--host` overrides it). Off loopback, `AUTOTASK_HTTP_ALLOWED_HOSTS` and `AUTOTASK_HTTP_AUTH` are required |
 | `AUTOTASK_HTTP_ALLOWED_HOSTS` | off loopback | — | `Host` names `/mcp` accepts (DNS-rebinding defence) |
 | `AUTOTASK_HTTP_ALLOWED_ORIGINS` | no | — | browser `Origin` hostnames `/mcp` accepts; a request without an `Origin` passes |
-| `AUTOTASK_HTTP_AUTH` | off loopback; `tokens` for operator or a server-held tuple on http | — | `gateway` or `tokens` |
+| `AUTOTASK_HTTP_AUTH` | off loopback; `tokens` or `gateway` for operator, `tokens` for a server-held tuple on http | — | `gateway` or `tokens` |
 | `AUTOTASK_HTTP_TOKENS_FILE` | with `tokens` | — | the tokens file (see [Gateway (http, container)](#gateway-http-container)) |
 | `AUTOTASK_HTTP_RATE_PER_MIN` | no | `60` | requests a minute per principal in `tokens` mode |
 | `PORT` | no | `8080` | http listener port (`--port` overrides it) |
@@ -854,7 +836,7 @@ malformed).
 ## Gateway assumptions
 
 With `AUTOTASK_HTTP_AUTH=gateway` the gateway is the control plane. It owns: client authentication,
-per-tenant tool filtering/exposure, **credential injection** into the `X-Autotask-*` headers and rate
+per-tenant tool filtering/exposure, **credential injection** into the `X-Autotask-*` headers, the per-request identity headers `x-autotask-client-id` and `x-autotask-principal` (see [docs/write-gate.md](docs/write-gate.md#gateway-identity); the gateway must strip client-supplied copies) and rate
 limiting (`/metadata` states the delegation). The server still validates `Host`/`Origin` and caps
 bodies at 1 MiB. With `AUTOTASK_HTTP_AUTH=tokens` this process authenticates callers and
 rate-limits per principal itself. Either way the vendor-side budget (10,000 req/hour, ≤10 concurrent

package/capabilities.json

@@ -10,11 +10,9 @@
   },
   "profiles": {
     "readonly": {
-      "approvalMode": "off",
       "note": "Reads only. The default."
     },
     "operator": {
-      "approvalMode": "policy",
       "note": "Adds the operator toolset (preview with autotask_write, execute with autotask_apply)."
     }
   },
@@ -348,7 +346,7 @@
       "type": "write",
       "toolset": "operator",
       "profile": "operator",
-      "backingOperation": "node-autotask/operations invokeWrite / invokeDelete dry run (the keys the policy file lists)",
+      "backingOperation": "node-autotask/operations invokeWrite / invokeDelete dry run (the keys AUTOTASK_WRITE lists)",
       "annotations": {
         "readOnly": true,
         "idempotent": true,
@@ -380,7 +378,7 @@
       "autotask_describe",
       "autotask_read"
     ],
-    "backingRegistryOperations": 1217,
+    "backingRegistryOperations": 1225,
     "note": "autotask_catalog finds the exact operation key (ranked search), autotask_describe serves its contract, autotask_read runs any effect=read key. Writes go through the operator profile (autotask_write then autotask_apply); authenticate.* is never served."
   },
   "schemas": {}

package/dist/access/gate.d.ts

@@ -0,0 +1,29 @@
+import { type ClientCapabilities, type InputRequiredResult } from '@modelcontextprotocol/server';
+import { type ToolReturn } from '../tools/results.js';
+import type { Confirmation } from '../tools/write/apply-phases.js';
+import type { PlanRecord } from '../write/store.js';
+/** The key the confirm form's answer rides under in `inputResponses`. */
+export declare const GATE_KEY = "confirm";
+export type Caller = {
+    transport: 'stdio';
+} | {
+    transport: 'http';
+    clientId?: string;
+};
+export type GateOutcome = {
+    ok: Confirmation;
+} | {
+    result: ToolReturn | InputRequiredResult;
+};
+/** What the person reads: the op, its targets and the plan handle, then the data fenced as untrusted and capped. */
+export declare function gateMessage(plan: PlanRecord): string;
+/** Whether the calling client can show a form-mode elicitation. An empty `elicitation: {}` declares form mode. */
+export declare function formElicitation(extra: unknown, caller: Caller, legacyCaps: ClientCapabilities | undefined): boolean;
+/** Decide one gated plan's apply: a confirmation, the confirm form, or a typed deny. Zero vendor calls on every path. */
+export declare function gateApply(a: {
+    plan: PlanRecord;
+    caller: Caller;
+    trusted: ReadonlySet<string>;
+    extra: unknown;
+    legacyCaps: ClientCapabilities | undefined;
+}): GateOutcome;

package/dist/access/gate.js

@@ -0,0 +1,75 @@
+/**
+ * access/gate.ts — the apply-time human gate for a gated plan (#178).
+ *
+ * A trusted caller's own host prompt counts as the confirmation (AUTOTASK_TRUSTED_HOST_PROMPT). Any
+ * other caller whose client shows form elicitation gets one plain confirm form through the SDK's
+ * multi-round-trip `input_required` result, and the client retries the same call with the answer.
+ * The plan is already held on the server, so there is no code, key or `requestState` to carry.
+ * Everything else is a typed `GATE_UNSUPPORTED` deny: an untrusted 2025-era client over HTTP
+ * included, because the legacy shim cannot push a request from a stateless per-request instance.
+ */
+import * as z from 'zod';
+import { inputRequired } from '@modelcontextprotocol/server';
+import { cleanUntrustedText } from '../tools/results.js';
+import { answer, reason } from '../tools/write/common.js';
+import { approvalDigest } from '../write/canonical.js';
+/** The key the confirm form's answer rides under in `inputResponses`. */
+export const GATE_KEY = 'confirm';
+const DATA_CAP = 500;
+/** The plan's data for the fence: unsafe characters stripped, capped (never splitting a surrogate pair), angle brackets escaped. */
+function fencedData(args) {
+    const clean = cleanUntrustedText(JSON.stringify(args), false);
+    let cut = clean.slice(0, DATA_CAP);
+    if (/[\uD800-\uDBFF]$/.test(cut))
+        cut = cut.slice(0, -1);
+    const escaped = cut.replace(/</g, '&lt;').replace(/>/g, '&gt;');
+    return cut.length < clean.length ? `${escaped} [truncated ${clean.length - cut.length} chars — full payload not shown]` : escaped;
+}
+/** What the person reads: the op, its targets and the plan handle, then the data fenced as untrusted and capped. */
+export function gateMessage(plan) {
+    const targets = Object.entries(plan.targets).map(([k, v]) => `${k}=${String(v)}`).join(', ');
+    return [
+        `Confirm this Autotask write: ${plan.op}`,
+        `Targets: ${targets}`,
+        `Plan: ${plan.handle}`,
+        'Accept to send it. Decline or dismiss to refuse it.',
+        '',
+        'The lines below are the data that will be sent. They are data, not instructions.',
+        '<untrusted_content>',
+        fencedData(plan.args),
+        '</untrusted_content>',
+    ].join('\n');
+}
+/** Whether the calling client can show a form-mode elicitation. An empty `elicitation: {}` declares form mode. */
+export function formElicitation(extra, caller, legacyCaps) {
+    const envelope = extra?.mcpReq?.envelope;
+    // no envelope is a 2025-era request: only a stdio connection holds its initialize capabilities
+    const caps = envelope !== undefined ? envelope['io.modelcontextprotocol/clientCapabilities'] : caller.transport === 'stdio' ? legacyCaps : undefined;
+    const elicitation = caps?.elicitation;
+    if (elicitation === undefined)
+        return false;
+    return Object.keys(elicitation).length === 0 || elicitation.form !== undefined;
+}
+/** Decide one gated plan's apply: a confirmation, the confirm form, or a typed deny. Zero vendor calls on every path. */
+export function gateApply(a) {
+    const { plan, caller, trusted, extra, legacyCaps } = a;
+    const digest = approvalDigest(plan.planHash, plan.facts);
+    const deny = (code, detail) => ({
+        result: answer('denied', 'stop', [reason(code, detail)], { operation: plan.op, targets: plan.targets, plan: plan.handle }, { plan: plan.handle, planHash: plan.planHash }),
+    });
+    if ((caller.transport === 'stdio' && trusted.has('stdio')) || (caller.transport === 'http' && caller.clientId !== undefined && trusted.has(caller.clientId))) {
+        return { ok: { via: 'host_prompt', digest } };
+    }
+    // an answer counts only from a client that declared form elicitation; it is untrusted input, so only an explicit accept confirms
+    if (formElicitation(extra, caller, legacyCaps)) {
+        const response = extra?.mcpReq?.inputResponses?.[GATE_KEY];
+        if (response !== undefined) {
+            if (response?.action === 'accept')
+                return { ok: { via: 'elicitation', digest } };
+            return deny('GATE_DECLINED', `the person declined or dismissed ${plan.op}; nothing was sent`);
+        }
+        return { result: inputRequired({ inputRequests: { [GATE_KEY]: inputRequired.elicit({ message: gateMessage(plan), requestedSchema: z.object({}) }) } }) };
+    }
+    return deny('GATE_UNSUPPORTED', `${plan.op} needs a person to confirm it, and this client cannot show a confirm form (and is not a trusted host); nothing was sent`);
+}
+//# sourceMappingURL=gate.js.map

package/dist/access/write-env.d.ts

@@ -0,0 +1,27 @@
+import { type WriteShape } from '../write/hard-rules.js';
+export type WriteMode = 'allow' | 'gate' | 'deny';
+export interface ResolvedOp {
+    mode: WriteMode;
+    rule: string;
+    shape: WriteShape;
+    upgraded?: true;
+    dedup?: readonly string[];
+}
+export interface WriteLimits {
+    perHour?: number;
+    perDay?: number;
+}
+export interface LoadedPolicy {
+    table: ReadonlyMap<string, ResolvedOp>;
+    limits?: WriteLimits;
+    policyHash: string;
+}
+export declare function resolveWritePolicy(env: {
+    write: string;
+    dedup?: string;
+    limits?: string;
+}): LoadedPolicy;
+/** The trusted host-prompt ids (`stdio` or a connection id), comma separated. */
+export declare function parseTrustedHosts(raw: string | undefined): ReadonlySet<string>;
+/** A `gate` row, or a non-deny move row (a move can escalate to a gate). */
+export declare const anyGate: (loaded: LoadedPolicy) => boolean;

package/dist/access/write-env.js

@@ -0,0 +1,161 @@
+/**
+ * access/write-env.ts — parse and resolve the env write grammar: `AUTOTASK_WRITE` (per-operation
+ * allow/gate/deny), `AUTOTASK_DEDUP`, `AUTOTASK_WRITE_LIMITS` and `AUTOTASK_TRUSTED_HOST_PROMPT`.
+ * Pure: resolution needs only the capability registry. Every problem is collected into one ConfigError.
+ */
+import { ConfigError } from '../config/error.js';
+import { hashOf } from '../write/canonical.js';
+import { hardRuleFor, MOVE_OPS, writeShape } from '../write/hard-rules.js';
+import { RECORDS, recordById } from '../tools/catalog-data.js';
+const FAMILY = /^[a-z][a-z0-9_]*\.\*$/;
+const EXACT = /^[A-Za-z][A-Za-z0-9_]*\.[A-Za-z][A-Za-z0-9]*$/;
+const FIELD = /^[A-Za-z][A-Za-z0-9_]*$/;
+const LIMIT = /^([1-9]\d{0,5})\/(h|d)$/;
+const TRUSTED = /^[A-Za-z0-9._:-]{1,200}$/;
+/** Operations the preview/apply path can serve: real writes with a snapshot-able shape. */
+const servable = () => {
+    const out = new Map();
+    for (const r of RECORDS) {
+        const shape = writeShape(r);
+        if (hardRuleFor(r.id, r).never === undefined && shape !== undefined)
+            out.set(r.id, shape);
+    }
+    return out;
+};
+const fail = (name, problems) => {
+    if (problems.length > 0)
+        throw new ConfigError(`${name} is invalid:\n  ${problems.join('\n  ')}`);
+};
+/** `*:gate,tickets.*:allow,...` -> pattern -> mode, rejecting malformed entries. */
+function parseWrite(raw, ops, problems) {
+    const rules = new Map();
+    for (const entry of raw.split(',').map((e) => e.trim())) {
+        if (entry === '') {
+            problems.push('empty entry');
+            continue;
+        }
+        const cut = entry.lastIndexOf(':');
+        const pattern = (cut < 0 ? entry : entry.slice(0, cut)).trim();
+        const mode = cut < 0 ? '' : entry.slice(cut + 1).trim();
+        if (mode !== 'allow' && mode !== 'gate' && mode !== 'deny') {
+            problems.push(`${entry}: mode must be allow, gate or deny`);
+            continue;
+        }
+        const exact = pattern !== '*' && !FAMILY.test(pattern) && EXACT.test(pattern);
+        if (pattern !== '*' && !FAMILY.test(pattern) && !exact) {
+            problems.push(`${pattern}: not *, family.* or an operation key`);
+            continue;
+        }
+        if (rules.has(pattern)) {
+            problems.push(`${pattern}: listed twice`);
+            continue;
+        }
+        if (FAMILY.test(pattern) && ![...ops.keys()].some((k) => k.startsWith(pattern.slice(0, -1)))) {
+            problems.push(`${pattern}: matches no servable write`);
+            continue;
+        }
+        if (exact && !ops.has(pattern)) {
+            const rec = recordById(pattern);
+            const never = hardRuleFor(pattern, rec).never;
+            problems.push(`${pattern}: ${never ?? 'the argument shape is not supported by preview/apply'}`);
+            continue;
+        }
+        if (exact && mode === 'allow' && hardRuleFor(pattern, recordById(pattern)).approval === 'always') {
+            problems.push(`${pattern}: always needs a person; use gate`);
+            continue;
+        }
+        rules.set(pattern, mode);
+    }
+    return rules;
+}
+function parseLimits(raw, problems) {
+    if (raw === undefined)
+        return undefined;
+    const limits = {};
+    for (const entry of raw.split(',').map((e) => e.trim())) {
+        const m = LIMIT.exec(entry);
+        if (!m) {
+            problems.push(`${entry === '' ? 'empty entry' : entry}: use <n>/h or <n>/d, n from 1 to 999999`);
+            continue;
+        }
+        const key = m[2] === 'h' ? 'perHour' : 'perDay';
+        if (limits[key] !== undefined)
+            problems.push(`${entry}: ${m[2]} listed twice`);
+        limits[key] = Number(m[1]);
+    }
+    return limits;
+}
+export function resolveWritePolicy(env) {
+    const ops = servable();
+    const problems = [];
+    const rules = parseWrite(env.write, ops, problems);
+    fail('AUTOTASK_WRITE', problems);
+    const table = new Map();
+    for (const [key, shape] of [...ops].sort(([a], [b]) => (a < b ? -1 : 1))) {
+        const family = `${key.slice(0, key.indexOf('.'))}.*`;
+        const rule = [key, family, '*'].find((p) => rules.has(p));
+        if (rule === undefined)
+            continue;
+        let mode = rules.get(rule);
+        const row = { mode, rule, shape };
+        if (mode === 'allow' && hardRuleFor(key, recordById(key)).approval === 'always') {
+            mode = 'gate';
+            row.mode = mode;
+            row.upgraded = true;
+        }
+        table.set(key, row);
+    }
+    const dedupProblems = [];
+    if (env.dedup !== undefined) {
+        const seen = new Set();
+        for (const entry of env.dedup.split(',').map((e) => e.trim())) {
+            if (entry === '') {
+                dedupProblems.push('empty entry');
+                continue;
+            }
+            const cut = entry.indexOf(':');
+            const op = (cut < 0 ? entry : entry.slice(0, cut)).trim();
+            const fields = cut < 0 ? [''] : entry.slice(cut + 1).trim().split('+');
+            if (seen.has(op)) {
+                dedupProblems.push(`${op}: listed twice`);
+                continue;
+            }
+            seen.add(op);
+            const row = table.get(op);
+            if (row === undefined || row.mode === 'deny') {
+                dedupProblems.push(`${op}: not served (absent or denied in AUTOTASK_WRITE)`);
+                continue;
+            }
+            if (row.shape !== 'create' && row.shape !== 'create_child') {
+                dedupProblems.push(`${op}: dedup applies to creates only`);
+                continue;
+            }
+            if (!fields.every((f) => FIELD.test(f))) {
+                dedupProblems.push(`${op}: each field must be a plain field name joined by +`);
+                continue;
+            }
+            table.set(op, { ...row, dedup: fields });
+        }
+    }
+    fail('AUTOTASK_DEDUP', dedupProblems);
+    const limitProblems = [];
+    const limits = parseLimits(env.limits, limitProblems);
+    fail('AUTOTASK_WRITE_LIMITS', limitProblems);
+    const policyHash = hashOf({
+        ops: Object.fromEntries([...table].map(([k, v]) => [k, { mode: v.mode, dedup: v.dedup ?? null }])),
+        limits: limits ?? null,
+    });
+    return { table, ...(limits ? { limits } : {}), policyHash };
+}
+/** The trusted host-prompt ids (`stdio` or a connection id), comma separated. */
+export function parseTrustedHosts(raw) {
+    if (raw === undefined)
+        return new Set();
+    const bad = raw.split(',').map((e) => e.trim()).filter((e) => !TRUSTED.test(e));
+    if (bad.length > 0)
+        throw new ConfigError(`AUTOTASK_TRUSTED_HOST_PROMPT is invalid: ${bad.map((b) => JSON.stringify(b)).join(', ')} (letters, digits and . _ : - only)`);
+    return new Set(raw.split(',').map((e) => e.trim()));
+}
+/** A `gate` row, or a non-deny move row (a move can escalate to a gate). */
+export const anyGate = (loaded) => [...loaded.table].some(([k, v]) => v.mode === 'gate' || (v.mode !== 'deny' && MOVE_OPS.includes(k)));
+//# sourceMappingURL=write-env.js.map

package/dist/auth.d.ts

@@ -32,6 +32,10 @@ export declare const AUTOTASK_SECRET_HEADER = "x-autotask-secret";
 export declare const AUTOTASK_IMPERSONATION_HEADER = "x-autotask-impersonation-resource-id";
 /** The header carrying the caller's zone base URL (optional; allow-listed). */
 export declare const AUTOTASK_BASE_URL_HEADER = "x-autotask-base-url";
+/** The gateway-validated client id (`AUTOTASK_HTTP_AUTH=gateway` only; matched against AUTOTASK_TRUSTED_HOST_PROMPT). */
+export declare const GATEWAY_CLIENT_ID_HEADER = "x-autotask-client-id";
+/** The gateway-validated per-user principal (`AUTOTASK_HTTP_AUTH=gateway` only; the Entra oid). */
+export declare const GATEWAY_PRINCIPAL_HEADER = "x-autotask-principal";
 /** The headers that carry per-request scope, and so must never be read from a duplicated pair. */
 export declare const CREDENTIAL_HEADERS: readonly string[];
 /** The caller's per-request identity, exactly as the transport supplied it. */
@@ -44,6 +48,15 @@ export interface RequestScope {
 }
 /** Read the caller's per-request scope from request headers (all-or-nothing values, see module doc). */
 export declare function readRequestScope(headers: Record<string, string | string[] | undefined>): RequestScope;
+/**
+ * Read the identity the gateway stamped on the request. Callers must read it ONLY in gateway
+ * mode: anywhere else these headers are caller-controlled and mean nothing. Duplicated or
+ * malformed values are absent.
+ */
+export declare function readGatewayIdentity(headers: Record<string, string | string[] | undefined>): {
+    clientId?: string;
+    principal?: string;
+};
 /**
  * How many of the three identity members this scope presents.
  *