@m1a0rz/agent-identity 0.2.5 → 0.3.2

package/dist/src/utils/derive-session-key.js

@@ -64,6 +64,18 @@ export function isSubagentSessionKey(sessionKey) {
         return true;
     return raw.includes(":subagent:");
 }
+/**
+ * Check whether sessionKey represents a group/channel conversation.
+ * Examples:
+ * - agent:main:telegram:group:-1001
+ * - agent:main:slack:channel:C123456
+ */
+export function isGroupOrChannelSessionKey(sessionKey) {
+    const raw = (sessionKey ?? "").trim().toLowerCase();
+    if (!raw)
+        return false;
+    return raw.includes(":group:") || raw.includes(":channel:");
+}
 /**
  * Resolve workload name for GetWorkloadAccessToken when roleTrn is not set.
  * For subagent keys (agent:X:subagent:uuid or nested): use last segment (uuid) as workload name.
@@ -92,24 +104,81 @@ function normalizeAccountId(value) {
     return trimmed || DEFAULT_ACCOUNT_ID;
 }
 /**
- * Extract peer/chat id from from/to for group sessions.
- * Channel-specific heuristics (e.g. telegram:group:123 or telegram:123 for group chat).
- */
+   * Extract group peer id from channel-specific "from/to" shapes.
+   * Return null for direct messages.
+   */
 function extractGroupPeerId(channel, from, to) {
-    const raw = (to ?? from ?? "").trim();
-    if (!raw)
+    const ch = (channel ?? "").trim().toLowerCase();
+    if (!ch)
         return null;
-    const lower = raw.toLowerCase();
-    const channelPrefix = `${channel}:`;
-    if (lower.startsWith(channelPrefix)) {
-        const rest = raw.slice(channelPrefix.length);
-        const parts = rest.split(":");
-        if (parts[0] === "group" && parts[1])
-            return parts[1];
-        if (parts.length >= 1)
-            return parts[0];
+    const fromRaw = (from ?? "").trim();
+    const toRaw = (to ?? "").trim();
+    const pickByPrefix = (value, prefix) => {
+        if (!value)
+            return null;
+        if (!value.toLowerCase().startsWith(prefix.toLowerCase()))
+            return null;
+        const id = value.slice(prefix.length).trim();
+        return id || null;
+    };
+    const pickFirst = (...values) => {
+        for (const v of values) {
+            if (v)
+                return v;
+        }
+        return null;
+    };
+    switch (ch) {
+        case "feishu":
+            // Group: to="chat:oc_xxx"; DM: to="user:ou_xxx"
+            return pickByPrefix(toRaw, "chat:");
+        case "telegram": {
+            // Group/topic: telegram:group:<chatId>[:topic:<threadId>]
+            const g1 = pickByPrefix(fromRaw, "telegram:group:");
+            if (g1)
+                return g1;
+            const g2 = pickByPrefix(toRaw, "telegram:group:");
+            if (g2)
+                return g2;
+            // Legacy fallback: telegram:-100... is usually group/supergroup
+            const f = pickByPrefix(fromRaw, "telegram:");
+            if (f && f.startsWith("-"))
+                return f;
+            const t = pickByPrefix(toRaw, "telegram:");
+            if (t && t.startsWith("-"))
+                return t;
+            return null;
+        }
+        case "slack":
+            // Group/channel: slack:channel:<id> / slack:group:<id>, to=channel:<id>
+            return pickFirst(pickByPrefix(fromRaw, "slack:channel:"), pickByPrefix(fromRaw, "slack:group:"), pickByPrefix(toRaw, "channel:"));
+        case "discord":
+            // Guild/thread channel: discord:channel:<id>, to=channel:<id>; DM uses user:<id>
+            return pickFirst(pickByPrefix(fromRaw, "discord:channel:"), pickByPrefix(toRaw, "channel:"));
+        case "signal":
+            // Group: group:<id>; DM: signal:<recipient>
+            return pickFirst(pickByPrefix(fromRaw, "group:"), pickByPrefix(toRaw, "group:"));
+        case "imessage":
+            // Group: imessage:group:<id>, to=chat_id:<id>; DM: imessage:<sender>
+            return pickFirst(pickByPrefix(fromRaw, "imessage:group:"), pickByPrefix(toRaw, "chat_id:"));
+        case "whatsapp":
+            // Group JID ends with @g.us; DM is E.164-like
+            if (/@g\.us$/i.test(fromRaw))
+                return fromRaw;
+            return null;
+        case "line":
+            // Group/room: line:group:<id> / line:room:<id>
+            return pickFirst(pickByPrefix(fromRaw, "line:group:"), pickByPrefix(fromRaw, "line:room:"), pickByPrefix(toRaw, "line:group:"), pickByPrefix(toRaw, "line:room:"));
+        case "matrix":
+            // Group/channel: matrix:channel:<roomId>; DM: matrix:<userId>
+            return pickByPrefix(fromRaw, "matrix:channel:");
+        case "msteams":
+            // Group/channel: msteams:channel:<id> / msteams:group:<id>, to=conversation:<id>
+            return pickFirst(pickByPrefix(fromRaw, "msteams:channel:"), pickByPrefix(fromRaw, "msteams:group:"), pickByPrefix(toRaw, "conversation:"));
+        default:
+            // Safe generic fallback: only explicit group/channel markers.
+            return pickFirst(pickByPrefix(fromRaw, `${ch}:group:`), pickByPrefix(fromRaw, `${ch}:channel:`), pickByPrefix(toRaw, `${ch}:group:`), pickByPrefix(toRaw, `${ch}:channel:`));
     }
-    return null;
 }
 /**
  * Derive sessionKey from command context.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@m1a0rz/agent-identity",
-  "version": "0.2.5",
+  "version": "0.3.2",
   "description": "Agent Identity: UserPool (用户池) login, TIP token (工作负载令牌), credential hosting (凭据托管 OAuth2/API key), optional tool/skill permission control (CheckPermission) and risk approval. Integrates with Volcengine 智能体身份和权限管理平台.",
   "type": "module",
   "main": "dist/index.js",

package/skills/SKILL.md

@@ -16,59 +16,21 @@ metadata:
 
 # Agent Identity
 
-Use the agent-identity plugin for UserPool OIDC login (入站授权), TIP token (工作负载访问令牌), credential hosting (出站授权 OAuth2, API key), and optional tool risk approval (权限管控 AuthZ).
-
-**Volcengine terminology**: 用户池 (UserPool), 入站授权 (OIDC login), 出站授权 (credential fetch), 工作负载令牌 (TIP), 凭据托管 (credential hosting), 权限管控 (CheckPermission). Docs: [Volcengine 智能体身份和权限管理](https://www.volcengine.com/docs/86848).
-
-**Agent flow:** When the user asks to log in, add credentials, check status, bind env, etc., call the corresponding tools directly. Do not suggest slash commands for those. Slash commands below are for user-initiated use (e.g. `/identity approve <id>` when the user must approve in chat; agent must never call `identity_approve_tool`).
-
-## Slash commands (user-initiated)
-
-| Command | Purpose |
-| ------- | ------- |
-| `/identity` | Show help |
-| `/identity whoami` | Identity brief |
-| `/identity status` | Full status: session, TIP, credentials, bindings |
-| `/identity login` | Log in via OIDC (returns auth URL) |
-| `/identity logout` | Clear session and TIP |
-| `/identity list-credentials` or `/identity list [page]` | List providers and credentials |
-| `/identity list-tips` | List valid TIP tokens |
-| `/identity config` | Show plugin config (redacted) |
-| `/identity fetch <provider> [--flow=...]` | Add credential |
-| `/identity set <provider> <envVar>` | Bind credential to env var |
-| `/identity unset <provider>` | Remove env binding |
-| `/identity risk <command>` | Diagnose risk for a shell command |
-| `/identity risk-patterns` | List built-in risky patterns |
-| `/identity approve <approval_id>` | Approve high-risk tool call (user runs this; agent must not self-approve) |
-| `/identity reject <approval_id>` | Reject high-risk tool call |
-
-## Tools Overview
-
-| Tool                        | Params                                         | Purpose                                    |
-| --------------------------- | ---------------------------------------------- | ------------------------------------------ |
-| `identity_whoami`           | —                                              | Identity brief: sub, login time, TIP expiry |
-| `identity_status`           | —                                              | Full status: session/TIP (issued, expires, chain), credentials, bindings |
-| `identity_login`            | —                                              | Start OIDC login or refresh TIP            |
-| `identity_logout`           | —                                              | Clear session and TIP                      |
-| `identity_list_credentials` | `page?`                                        | List providers and credentials (paginated) |
-| `identity_list_tips`        | —                                              | List valid TIP tokens and bindings         |
-| `identity_config`           | —                                              | Show plugin config (secrets redacted)      |
-| `identity_config_suggest`  | `intent?`, `lang?`                             | Generate config snippets for openclaw.json |
-| `identity_fetch`            | `provider`, `flow?`, `redirectUrl?`, `scopes?` | Add credential                             |
-| `identity_set_binding`      | `provider`, `envVar`                           | Bind provider → env var for tool injection |
-| `identity_unset_binding`    | `provider`                                     | Remove env binding                         |
-| `identity_approve_tool`     | `approval_id`                                  | Approve a high-risk tool call              |
-| `identity_risk_check`       | `command?`, `toolName?`, `params?`             | Diagnose risk for command or tool call     |
-| `identity_list_risk_patterns` | —                                            | List built-in risky patterns and paths     |
-
-## Risk Detection and Approval
-
-When `authz.requireRiskApproval` is on, the plugin classifies tool calls (e.g. exec, write, apply_patch) by risk. User-provided commands and file paths are evaluated:
-
-- **Rule-based**: Destructive patterns (rm -rf, sudo, curl|bash), sensitive paths (/etc, ~/.ssh).
-- **LLM-based** (optional): When rules return "medium", an LLM re-evaluates for context (`authz.enableLlmRiskCheck`).
-
-High-risk calls require user approval. The approval message and block reason include the LLM risk explanation when available (e.g. "Pipe-to-shell: network fetch piped to shell execution").
+Use the agent-identity plugin for UserPool OIDC login, TIP token, credential hosting (OAuth2, API key), and optional tool risk approval (AuthZ).
+
+**Agent rules:**
+
+- Call tools directly. Never suggest slash commands to the user.
+- When any tool returns an `authUrl` field, **always display it as a markdown link** to the user, e.g. `[Click here to log in](https://...)` or `[Click here to authorize](https://...)`. Never paste the bare URL as plain text — long OAuth URLs with special characters get truncated by chat platforms.
+- Never call `identity_approve_tool` to self-approve. High-risk approval is a human action only.
+- **Critical — auto-login on AuthZ block:** When ANY tool call fails with an error containing "TIP token required" or "session has no valid identity", you MUST immediately call `identity_login` to initiate login, display the `authUrl` to the user, and wait for them to complete authentication. After login succeeds, retry the original tool call. Do NOT skip the blocked action, try alternative approaches, or tell the user to run commands manually.
+- **Critical — always report permission errors to the user:** When a tool call is blocked with errors like "CheckPermission denied", "permission denied", "requires approval", or any `[agent-identity]` prefixed error, you MUST:
+  1. **Tell the user clearly** what was blocked and why (include the tool/skill name and the error message).
+  2. **Never silently ignore** the error or skip to something else without informing the user.
+  3. For "CheckPermission denied for skill ..." — tell the user they do not have access to that skill and suggest contacting an administrator.
+  4. For "CheckPermission denied for tool ..." — tell the user the tool is restricted and they lack permission to use it.
+  5. For "High-risk tool requires approval" — relay the approval instructions (approval ID, timeout) and wait for the user to approve before retrying.
+  6. For "Failed to verify permission" — report a temporary error and suggest retrying later.
 
 ## Tool Parameters
 
@@ -76,44 +38,49 @@ High-risk calls require user approval. The approval message and block reason inc
 
 Starts OIDC login or refreshes TIP. **Call when:** "login", "登录", "sign in", "我需要先登录". Required before `identity_fetch`. No params.
 
+**Returns:**
+
+- Already logged in: `{ ok: true, sub, message }` — inform user they are already authenticated.
+- Needs login: `{ ok: false, authUrl, message }` — **you MUST display the `authUrl` as a markdown link** and tell them to open it in a browser. After they authorize, a success message will be sent to the chat automatically. Example response: "Please complete login in your browser: [Click here to log in](authUrl)"
+- Error: `{ error, authUrl: null }` — report the error.
+
 ### identity_whoami
 
-Brief identity check. **Call when:** "who am I", "查身份", "am I logged in", "当前登录状态"
+Brief identity check. **Call when:** "who am I", "查身份", "am I logged in", "当前登录状态". No params.
 
-Returns: `sub`, `hasTip`, `loggedIn`, `sessionLoginAt`, `sessionExpiresAt`, `tipIssuedAt`, `tipExpiresAt`, `tipExpiresInSeconds`, `tipChain`. No params.
+Returns: `sub`, `hasTip`, `loggedIn`, `sessionLoginAt`, `sessionExpiresAt`, `tipIssuedAt`, `tipExpiresAt`, `tipExpiresInSeconds`, `tipChain`.
 
 ### identity_status
 
-Full status including credentials and bindings. **Call when:** "status", "查看完整状态", "我的凭据和绑定", "show my credentials and bindings"
+Full status including credentials and bindings. **Call when:** "status", "查看完整状态", "我的凭据和绑定", "show my credentials and bindings". No params.
 
-Returns: `loggedIn`, `sub`, `hasTip`, `session` (loginAt, expiresAt), `tip` (issuedAt, expiresAt, chain), `credentialProviders`, `bindings`. No params.
+Returns: `loggedIn`, `sub`, `hasTip`, `session` (loginAt, expiresAt), `tip` (issuedAt, expiresAt, chain), `credentialProviders`, `bindings`.
 
-### identity_list_credentials
+### identity_logout
 
-Lists available credential providers and what the user has stored. **Call this when the user wants to see what they can connect or what credentials they have.**
+Clear session and TIP. **Call when:** "logout", "登出", "sign out". No params.
 
-**User prompts:** "有哪些服务可以连接", "what providers are available", "我添加了哪些凭据", "list my credentials", "show available providers"
+### identity_list_credentials
 
-| Param  | Type   | Required | Description              |
-| ------ | ------ | -------- | ------------------------ |
-| `page` | number | No       | Page number (default: 1) |
+Lists available credential providers and stored credentials. Supports filtering by name or flow to locate a specific provider without paging through all results. **Call when:** "有哪些服务可以连接", "what providers are available", "我添加了哪些凭据", "list my credentials", "查找某个 provider"
 
-```json
-{ "page": 2 }
-```
+| Param  | Type   | Required | Description                                                        |
+| ------ | ------ | -------- | ------------------------------------------------------------------ |
+| `page` | number | No       | Page number (default: 1)                                           |
+| `name` | string | No       | Filter providers by name (exact or prefix match)                   |
+| `flow` | string | No       | Filter providers by flow, e.g. `M2M` or `USER_FEDERATION`         |
+
+When looking for a specific provider (e.g. before `identity_fetch`), prefer passing `name` filter instead of paging through results.
 
 Returns: `providers`, `storedOnly`, `page`, `hasMore`.
 
 ### identity_fetch
 
-Adds a credential for a provider (OAuth2 or API key). **Call this when the user wants to add, get, or configure credentials.**
-
-**User prompts that mean "call identity_fetch":**
+Adds a credential for a provider (OAuth2 or API key). **Call when the user wants to add, get, or configure credentials:**
 
-- English: "add/google my Google token", "get credentials for OpenAI", "connect my GitHub", "I need to use Google API", "set up API key for X", "authorize access to Y", "I want to use [provider] but have no key"
-- 中文: "帮我添加/获取 Google 凭据", "配置 OpenAI 的 API key", "连接我的 GitHub", "我要用某某服务但没有密钥", "授权访问某平台", "添加某某的 token", "获取某某的凭证"
+- "帮我添加 Google 凭据", "get credentials for OpenAI", "connect my GitHub", "配置 API key", "授权访问某平台"
 
-First ensure user is logged in (`identity_whoami`); if not, use `identity_login`. Then call `identity_fetch` with the provider. Use `identity_list_credentials` to discover available providers.
+First ensure user is logged in (`identity_whoami`); if not, use `identity_login`. Then call `identity_fetch` with the provider.
 
 | Param         | Type     | Required | Description                                                                             |
 | ------------- | -------- | -------- | --------------------------------------------------------------------------------------- |
@@ -121,39 +88,26 @@ First ensure user is logged in (`identity_whoami`); if not, use `identity_login`
 | `flow`        | string   | No       | `oauth2-user` (default for 3LO), `oauth2-m2m`, or `apikey`. Auto-inferred when omitted. |
 | `redirectUrl` | string   | No       | OAuth redirect URL (when provider requires custom)                                      |
 | `scopes`      | string[] | No       | OAuth scopes (e.g. `["email", "profile"]`)                                              |
-| `returnValue` | boolean  | No       | When true and fetch succeeds, include credential `value` in result for same-turn automation. Default false. |
-
-```json
-{ "provider": "google" }
-```
-
-```json
-{ "provider": "openai", "flow": "apikey", "returnValue": true }
-```
+| `returnValue` | boolean  | No       | When true and fetch succeeds, include credential `value` in result. Default false.       |
 
 **Response:**
 
-- **OAuth2-user**: `authUrl` (user must open in browser). After authorization, success message sent to chat.
-- **OAuth2-m2m** / **apikey**: `success: true`, `message` (completes immediately). If `returnValue: true`, also includes `value` (credential string) for same-turn use.
+- **OAuth2-user (success: true)**: Server had a cached token — credential added immediately. No further action needed.
+- **OAuth2-user (authUrl)**: User must authorize. **Display as markdown link** `[Click here to authorize](authUrl)`. A background process will detect when authorization completes and trigger the agent to continue automatically. If that does not happen within a reasonable time, **call `identity_fetch` again with the same provider** to check status.
+- **OAuth2-m2m** / **apikey**: `success: true`, `message` (completes immediately). If `returnValue: true`, also includes `value`.
 
 ### identity_set_binding
 
-Binds a stored credential to an env var so tools can use it at runtime. **Call this when the user wants tools/agent to have access to a credential.**
-
-**User prompts:** "让工具能用我的 Google 凭据", "bind/google my credential for tools", "把 Google token 注入给 agent", "inject my OpenAI key for API calls", "配置某某凭据给工具用"
+Binds a stored credential to an env var for tool injection. **Call when:** "让工具能用我的凭据", "bind my credential for tools", "inject my key for API calls"
 
-Credential must exist first (`identity_fetch`). Common env vars: `GOOGLE_ACCESS_TOKEN`, `OPENAI_API_KEY`, `GITHUB_TOKEN`, etc.
+Credential must exist first (`identity_fetch`). Common env vars: `GOOGLE_ACCESS_TOKEN`, `OPENAI_API_KEY`, `GITHUB_TOKEN`.
 
 | Param      | Type   | Required | Description                                                                              |
 | ---------- | ------ | -------- | ---------------------------------------------------------------------------------------- |
 | `provider` | string | Yes      | Provider name (e.g. `google`)                                                            |
 | `envVar`   | string | Yes      | Env var for injection (e.g. `GOOGLE_ACCESS_TOKEN`). Must match `[A-Za-z_][A-Za-z0-9_]*`. |
 
-```json
-{ "provider": "google", "envVar": "GOOGLE_ACCESS_TOKEN" }
-```
-
-If credential exists: binds it. Else: imports from `process.env[envVar]` as api_key (gateway must have that env set).
+If credential exists: binds it. Else: imports from `process.env[envVar]` as api_key.
 
 ### identity_unset_binding
 
@@ -161,86 +115,57 @@ If credential exists: binds it. Else: imports from `process.env[envVar]` as api_
 | ---------- | ------ | -------- | --------------------------------------- |
 | `provider` | string | Yes      | Provider name to unbind (e.g. `google`) |
 
-```json
-{ "provider": "google" }
-```
-
-### identity_approve_tool
-
-| Param         | Type   | Required | Description                                                                 |
-| ------------- | ------ | -------- | --------------------------------------------------------------------------- |
-| `approval_id` | string | Yes      | ID from the approval prompt (e.g. after blocking a high-risk exec/write)   |
-
-Optional tool (not given to agent by default). For human approval, use `/identity approve <id>` or reply "approve" in chat. The agent must NOT call this tool to self-approve. The approval prompt includes the LLM risk reason when available.
-
-```json
-{ "approval_id": "abc123" }
-```
-
 ### identity_risk_check
 
-Evaluates risk of a command or tool call before execution. **Call when:** "这个命令安全吗", "is rm -rf dangerous", "check if this is risky", "帮我评估这个命令有没有风险"
+Evaluates risk of a command or tool call. **Call when:** "这个命令安全吗", "is this risky", "帮我评估风险"
 
-| Param      | Type     | Required | Description                                                                 |
-| ---------- | -------- | -------- | --------------------------------------------------------------------------- |
-| `command`  | string   | No*      | Shell command to evaluate (treated as exec). Use for quick diagnosis.      |
-| `toolName` | string   | No*      | Tool name (e.g. write, apply_patch). Use with params.                       |
-| `params`   | object   | No       | Tool params. For exec: `{command}`. For write: `{path, content}`.           |
+| Param      | Type     | Required | Description                                            |
+| ---------- | -------- | -------- | ------------------------------------------------------ |
+| `command`  | string   | No*      | Shell command to evaluate                              |
+| `toolName` | string   | No*      | Tool name (e.g. write, apply_patch). Use with `params`. |
+| `params`   | object   | No       | Tool params                                            |
 
-*Provide either `command` or `toolName`. Returns `risk`, `reason`, `source` (rules or llm). Uses LLM when `authz.enableLlmRiskCheck` is true and rules return medium.
-
-```json
-{ "command": "rm -rf /" }
-```
-
-```json
-{ "toolName": "write", "params": { "path": "/etc/hosts", "content": "..." } }
-```
+*Provide either `command` or `toolName`. Returns `risk`, `reason`, `source`.
 
 ### identity_list_risk_patterns
 
-Returns built-in dangerous command patterns and sensitive paths. No params. Use to query what triggers high-risk approval.
-
-```json
-{}
-```
+Returns built-in dangerous command patterns and sensitive paths. No params.
 
 ### identity_config_suggest
 
-Generates config snippets for the agent-identity plugin. **Call when:** user asks to configure identity, login, authz, risk approval, or "如何配置 identity 插件", "帮我配置登录", "怎么开启权限检查".
+Generates config snippets. **Call when:** "如何配置 identity 插件", "帮我配置登录", "怎么开启权限检查"
 
 | Param   | Type   | Required | Description                                                                 |
 | ------- | ------ | -------- | --------------------------------------------------------------------------- |
-| `intent`| string | No       | `identity` (AK/SK), `userpool` (OIDC login), `authz` (permission/approval), `llm_risk` (LLM re-eval), `full` (all). Default: full |
-| `lang`  | string | No       | `en` or `zh` for instructions. Default: en                                  |
+| `intent`| string | No       | `identity`, `userpool`, `authz`, `llm_risk`, or `full` (default)            |
+| `lang`  | string | No       | `en` or `zh`. Default: en                                                   |
 
-Returns: `configPath`, `config` (JSON to merge), `instructions`, `nextSteps`. When `intent` is `identity` or `full`, also returns `identityDefaults` (env vars, credential resolution order, config defaults, credential file format). User must manually add to openclaw.json and restart gateway.
+Returns: `configPath`, `config` (JSON to merge), `instructions`, `nextSteps`.
 
-```json
-{ "intent": "userpool", "lang": "zh" }
-```
+### identity_list_tips
 
-## Workflow: Adding a Credential
+List valid TIP tokens and bindings. No params.
 
-1. **Check login**: `identity_whoami` (brief) or `identity_status` (full). If not logged in, use `identity_login` first (user opens auth URL).
-2. **Add credential**: `identity_fetch` with `provider`. For OAuth2-user, tell user to open `authUrl`; success message sent when done.
-3. **Bind for tools** (optional): `identity_set_binding` so the credential is injected as an env var when tools run.
+### identity_approve_tool
 
-## Workflow: Checking Risk Before Running
+| Param         | Type   | Required | Description                                              |
+| ------------- | ------ | -------- | -------------------------------------------------------- |
+| `approval_id` | string | Yes      | ID from the approval prompt                              |
 
-1. **Diagnose**: `identity_risk_check` with `command` or `toolName`+`params`. Returns risk level and reason.
-2. **List patterns**: `identity_list_risk_patterns` to see what triggers high-risk approval.
+**Agent must NOT call this tool.** This is for human approval only — user runs `/identity approve <id>` or replies "approve" in chat.
 
-## Configuration
+## Workflow: Adding a Credential
+
+1. **Check login**: `identity_whoami`. If not logged in, call `identity_login`. When it returns `authUrl`, **display as markdown link** `[Click here to log in](authUrl)`.
+2. **Add credential**: `identity_fetch` with `provider`. If it returns `authUrl`, display the link. The agent will be notified automatically when the user completes authorization. If not resumed automatically, **call `identity_fetch` again** to check status.
+3. **Bind for tools** (optional): `identity_set_binding` so the credential is injected as an env var when tools run.
 
-Plugin config lives under `plugins.entries.agent-identity.config`:
+## Workflow: Checking Risk
 
-- `identity`: Identity API (endpoint, credentials, workloadPoolName, workloadName, roleTrn). When `roleTrn` is set (AssumeRole), workload name is omitted; backend uses roleName. When workload not found (404), plugin auto-creates via CreateWorkloadIdentity then retries.
-- `userpool`: OIDC (discoveryUrl, clientId, callbackUrl, or userPoolName+clientName)
-- `authz`: Optional AuthZ (toolCheck, skillReadCheck, requireRiskApproval, enableLlmRiskCheck, llmRiskCheck, namespaceName, lowRiskBypass). When `enableLlmRiskCheck` is true, rules returning "medium" are re-evaluated via LLM; the risk reason is shown in approval prompts and block messages.
+1. `identity_risk_check` with `command` or `toolName`+`params`. Returns risk level and reason.
+2. `identity_list_risk_patterns` to see what triggers high-risk.
 
 ## Notes
 
-- Requires the agent-identity plugin to be enabled.
-- `/identity` and tools require session context (channel + sender); use from an active chat.
-- `identity_risk_check` and `identity_list_risk_patterns` do not require login.
+- `identity_login`, `identity_logout`, `identity_whoami`, `identity_status`, and `identity_config_suggest` work without login.
+- `identity_risk_check` and `identity_list_risk_patterns` work without login.