/service-itsm-agentic-setup-agent-runtime-access-assign

name: service-itsm-agentic-setup-agent-runtime-access-assign
description: "Grant a user the runtime permissions an activated ITSM agent's actions need so the actions do not fail on permission errors. After a Fulfiller or Employee agent is activated, this skill detects which platform feature permission sets are provisioned (Prompt Templates, Data Cloud, Unified Catalog), lets you pick a tier (user/agent vs admin) per feature and which user(s) to assign, then assigns them (license first when license-gated). It also creates a custom \"Agent Access\" permission set granting the activated agents you choose and assigns it to the user — all via the Salesforce CLI. Use to grant a user access to an activated agent, to assign prompt-template, data-cloud, or unified-catalog access, or to create an Agent Access permission set. DO NOT TRIGGER for enabling Agentforce for IT Service toggles, creating or activating an agent, the Fulfiller activation action-surfacing gap (service-itsm-agentic-setup-itsm-agentforce-permset-assign), CMDB access, or generic permission-set assignment."
metadata:
  version: "1.1"
  domains: ["Service", "Agentforce"]
  minApiVersion: "67.0"
  relatedSkills:
    - "service-itsm-agentic-setup-agentforce-studio-configure"
    - "service-itsm-agentic-setup-cmdb-access-assign"
    - "service-itsm-agentic-setup-employee-agent-configure"
    - "service-itsm-agentic-setup-fulfiller-agent-configure"
    - "service-itsm-agentic-setup-itsm-agentforce-permset-assign"
  cliTools:
    - tool: ["node"]
      semver: ">=18.0.0"
    - tool: ["sf"]
      semver: ">=2.0.0"
  accessCheck:
    - type: "license"
      value: "Agentforce"
allowed-tools: |
  Bash
  Read
  AskUserQuestion

Grant Runtime Access for an Activated ITSM Agent

An ITSM agent (Fulfiller or Employee) can be created and activated, yet **fail the moment it's opened** — its actions call platform features the **user** can't execute. This skill closes that gap after activation via two write-capable steps behind one confirmation:

1. **Runtime action-execution permissions.** Detect which **feature permission sets** are provisioned, let the user pick a **tier per feature** (user/agent vs admin) and which **user(s)** to grant, then assign — **license first** when license-gated. 2. **A custom "Agent Access" permission set.** Create (or reuse) **Agent Access**, grant the **activated agents** the user chooses (one `SetupEntityAccess` per agent), then assign it to the same user(s).

The verified feature → tier → permset matrix lives in `references/permset-topology.md`. **No org has all three features** — assign only what is provisioned and report the rest as unavailable, never failing on an absent feature.

Every read and write runs through the **Salesforce CLI (`sf`)** — no metadata XML, no token extraction, no MCP.

Scope

• **In scope**: detecting which platform feature permsets are provisioned; per-feature tier selection; asking which user(s) to grant (running user offered, never silent) and resolving them; PSL-then-permset assignment (license-gated tiers) idempotently; creating/reusing the custom `Agent_Access` permission set; adding a `SetupEntityAccess` grant per chosen **activated** agent; assigning `Agent_Access` to the user(s); verifying assignments by read-back.
• **Out of scope** (owning skill parenthesized): the *Agentforce for IT Service* Go toggles / Studio config (`service-itsm-agentic-setup-agentforce-studio-configure`); creating or activating the Employee (`service-itsm-agentic-setup-employee-agent-configure`) or Fulfiller (`service-itsm-agentic-setup-fulfiller-agent-configure`) agent; the **Fulfiller activation** action-surfacing gap (create/activate-time, not this runtime one — `service-itsm-agentic-setup-itsm-agentforce-permset-assign`); CMDB access (`service-itsm-agentic-setup-cmdb-access-assign`); generic non-ITSM permission-set assignment; authoring/editing feature permsets.

Helper scripts (all invoked via `Bash`) hold every deterministic decision (A9)

Full I/O contracts in `references/helper-contracts.md`.

• `scripts/classify-platform-permset-availability.mjs` — which features are provisioned, each tier's `present` + `needsPsl`, and the org's own display label per tier.
• `scripts/resolve-target-user.mjs` — running-user Id from the API-root `identity` URL (fails closed on a malformed shape).
• `scripts/rank-candidate-users.mjs` — up to five real, non-service candidate users to offer, ranked by audience (standard-license first for a Fulfiller agent, Unified Employee first for an Employee agent).
• `scripts/gate-unified-catalog-tiers.mjs` — per target user, which Unified Catalog tiers to offer (Community User → Unified Employee; Admin → System Administrator), else omit UC for that user.
• `scripts/classify-activated-agents.mjs` — the activated-agent candidate list (BotDefinition `InternalCopilot` with ≥1 `Active` BotVersion).
• `scripts/classify-agent-access-state.mjs` — whether `Agent_Access` must be created and which chosen agents still need a grant (idempotency).
• `scripts/classify-assignment-state.mjs` — per user+permset idempotency; pass the sentinel `NO-PSL` when the selected tier's `needsPsl:false`.

---

Preconditions

1. **`sf` CLI installed and authenticated to the target org** (`sf org display -o <alias>` shows Connected). All calls use `--target-org <alias>`; never extract or pass the access token by hand. 2. **API v67.0+**. 3. **`node` ≥ 18** on PATH.

If a precondition fails, `sf` surfaces an auth or `401`/`403`/`404`; report the raw response verbatim and stop — do not fabricate state.

---

Clarifying questions

Ask only what cannot be inferred from conversation:

• **Target org** — the `sf` alias. Default to `sf config get target-org` if unset.
• **Target user(s)** — never a silent default: if unnamed, **ASK** via `AskUserQuestion` (see Phase 2); if named, honor it.
• **Tier per provisioned feature** — for EACH provisioned feature, ask which tier (lighter **user/agent** vs