@uipath/skills 1.197.2 → 1.198.0

package/hooks/send-telemetry.sh

@@ -1,18 +1,25 @@
 #!/bin/bash
-# PostToolUse telemetry hook for the UiPath skills plugin.
+# Telemetry hook for the UiPath skills plugin (Claude Code).
 #
-# Reads the hook JSON payload from stdin, decides whether the tool call is
-# attributable to THIS plugin (skill gate), resolves the UiPath environment
-# (alpha / staging / prod), and pipes one flat JSON object to `uip track`,
-# which forwards it through the CLI's own telemetry tracker as a single
-# uip.skills.tool-use Application Insights event. Calls from other plugins or
-# bare Claude Code are dropped.
+# Registered on multiple Claude Code hook events (PostToolUse, SessionStart,
+# SessionEnd, Stop, StopFailure). Reads the hook JSON payload from stdin, maps
+# the event to a canonical eventName, and pipes one flat JSON object to
+# `uip track`, which forwards it through the CLI's own telemetry tracker as a
+# single uip.skills.<event> Application Insights event.
+#
+# tool-use is per-call and gated on plugin attribution (skill gate) — calls from
+# other plugins or bare Claude Code are dropped. Lifecycle events (session-start,
+# session-end, completion) are session-scoped and fire for every session where
+# this plugin is installed.
 #
 # The CLI (see UiPath/cli#2600) owns transport, the App Insights connection,
-# the event name, the authenticated cloud identity, and the `source:
-# "skills-plugin"` dimension. This hook only derives + sanitizes fields and
-# gates on the opt-out flag; value sanitization stays the hook's responsibility
-# because the CLI and skills ship co-versioned.
+# the event name, the authenticated cloud identity, the `source:
+# "skills-plugin"` dimension, and — since UiPath/cli#2806 — the
+# environment/base_url/region base dimensions stamped fresh on every event
+# from its own auth context (so this hook sends no environment info). This
+# hook only derives + sanitizes fields and gates on the opt-out flag; value
+# sanitization stays the hook's responsibility because the CLI and skills
+# ship co-versioned.
 #
 # REGION-SCOPED EXTRACTION (see extract_fields): the payload embeds free-form
 # customer content (prompts, command lines, stdout/stderr, file contents). A
@@ -20,8 +27,11 @@
 # contains JSON-shaped text (`"success":false`, `uip solution publish`,
 # `.flow"`, `"resolvedModel":"..."`). So a single string-aware awk pass walks
 # the JSON once and pulls each field ONLY from the region it lives in:
-#   ENVELOPE (top-level)  -> toolName, toolUseId, sessionId, permissionMode,
-#                            durationMs, effortLevel (effort.level), agentType
+#   ENVELOPE (top-level)  -> toolName, toolUseId, session_id, permissionMode,
+#                            durationMs, effortLevel (effort.level), agentType,
+#                            source (-> session_source), reason (session-end),
+#                            model (-> agent_model; Claude sends it on
+#                            SessionStart, Codex on every event)
 #   tool_input            -> skillName, uipSubcommand (command), fileExtension
 #                            (file_path), subagentType (subagent_type, or
 #                            agent_type for a Codex spawn_agent call)
@@ -39,11 +49,19 @@
 # interrupted / resolvedModel are absent and outcome is ok|unknown only.
 # Only derived, low-cardinality, PII-free values ever leave the machine.
 #
+# TWIN SCRIPT: hooks/send-telemetry.ps1 is the PowerShell twin of this file —
+# any behavioral change here MUST be mirrored there in the same PR (see
+# CLAUDE.md). hooks.json runs whichever twin matches the executing shell via a
+# bash/PowerShell polyglot command.
+#
 # Non-blocking by contract: registered as an async hook in hooks.json
-# ("async": true), so Claude Code runs it in the background and never waits for
-# it. Always exits 0, swallows every error, and pipes to `uip track` in a
-# detached subshell. Cross-platform (macOS, Linux, Windows via Git Bash /
-# MSYS). Pure bash + grep/sed/awk — no jq, node, or python.
+# ("async": true) on every event EXCEPT SessionEnd, so Claude Code runs it in
+# the background and never waits for it. SessionEnd is registered
+# SYNCHRONOUSLY (30s timeout): async hooks still running at session teardown
+# are killed after a short grace window, which would silently drop the
+# session-end event. Always exits 0, swallows every error, and pipes to
+# `uip track` in a detached subshell. Cross-platform (macOS, Linux, Windows
+# via Git Bash / MSYS). Pure bash + grep/sed/awk — no jq, node, or python.
 #
 # Structure: pure helpers + side-effecting procedures (below), driven by main()
 # (bottom). Configuration is env only:
@@ -55,8 +73,12 @@
 set +e
 
 # schemaVersion of the emitted event. Bump on ANY change to the key set so App
-# Insights can segment events emitted with older/churned schemas.
-SCHEMA_VERSION=1
+# Insights can segment events emitted with older/churned schemas. v2: adds the
+# eventName / session_source / reason / agent_model keys, renames
+# sessionId -> session_id (canonical casing, matches the CLI command stream,
+# UiPath/cli#2800), and drops environment/baseUrl (the CLI stamps fresh
+# environment/base_url/region base dimensions itself, UiPath/cli#2806).
+SCHEMA_VERSION=2
 
 # --- extraction ------------------------------------------------------------
 
@@ -73,7 +95,7 @@ extract_fields() {
       if (d == 1)
         return (k=="tool_name"||k=="tool_use_id"||k=="session_id"|| \
                 k=="permission_mode"||k=="duration_ms"||k=="agent_type"|| \
-                k=="hook_event_name")
+                k=="hook_event_name"||k=="source"||k=="reason"||k=="model")
       if (d == 2 && c == "input")
         return (k=="skill"||k=="command"||k=="file_path"||k=="subagent_type"|| \
                 k=="agent_type")
@@ -173,7 +195,8 @@ read_fields() {
   event=""; tool=""; tool_use_id=""; session_id=""; permission_mode=""
   duration_ms=""; agent_type=""; skill=""; command=""; file_path=""
   subagent_type=""; interrupted=""; success=""; resolved_model=""
-  effort_level=""; response_seen=""
+  effort_level=""; response_seen=""; session_source=""; reason=""
+  agent_model=""
   local k v
   while IFS="$(printf '\t')" read -r k v; do
     case "$k" in
@@ -184,6 +207,9 @@ read_fields() {
       permission_mode)    permission_mode="$v" ;;
       duration_ms)        duration_ms="$v" ;;
       agent_type)         agent_type="$v" ;;
+      source)             session_source="$v" ;;
+      reason)             reason="$v" ;;
+      model)              agent_model="$v" ;;
       skill)              skill="$v" ;;
       command)            command="$v" ;;
       file_path)          file_path="$v" ;;
@@ -233,54 +259,6 @@ is_uipath_call() {
   return 1
 }
 
-# --- environment resolution ------------------------------------------------
-
-# cache_val <file> <key>: emit a cached value stripped to a safe charset. Parses
-# the cache as DATA — never `source` it, so a tampered cache can't execute
-# arbitrary shell in this hook's context.
-cache_val() {
-  grep -E "^$2=" "$1" 2>/dev/null | head -1 | cut -d= -f2- | tr -cd 'A-Za-z0-9:._/-'
-}
-
-# resolve_environment: set env_name + base_url from `uip login status` (~0.5s),
-# cached per-user for 1h so only one tool call per hour pays the cost. The cache
-# dir is per-user, owner-only (NOT world-writable /tmp), so another local user
-# can't pre-create the file. chmod is a no-op on Windows but harmless.
-resolve_environment() {
-  local cache_dir cache ttl now _ts status_json
-  cache_dir="${XDG_CACHE_HOME:-$HOME/.cache}/uipath-telemetry"
-  mkdir -p "$cache_dir" 2>/dev/null && chmod 700 "$cache_dir" 2>/dev/null
-  cache="$cache_dir/env.cache"
-  ttl=3600
-  now="$(date +%s 2>/dev/null || echo 0)"
-
-  env_name="unknown"; base_url=""; _ts=0
-  if [ -f "$cache" ]; then
-    _ts="$(cache_val "$cache" _ts)"
-    env_name="$(cache_val "$cache" env_name)"
-    base_url="$(cache_val "$cache" base_url)"
-    case "$_ts" in *[!0-9]*|"") _ts=0 ;; esac   # non-numeric -> treat as stale
-  fi
-
-  [ "$(( now - _ts ))" -ge "$ttl" ] || return 0
-
-  status_json="$(uip login status --output json 2>/dev/null)"
-  base_url="$(printf '%s' "$status_json" \
-    | grep -oE '"BaseUrl"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"\([^"]*\)"$/\1/')"
-  case "$base_url" in
-    *alpha.uipath.com*)   env_name="alpha" ;;
-    *staging.uipath.com*) env_name="staging" ;;
-    *cloud.uipath.com*)   env_name="prod" ;;
-    "")                   env_name="unknown" ;;
-    *)                    env_name="other" ;;
-  esac
-  {
-    echo "_ts=$now"
-    echo "env_name=$env_name"
-    echo "base_url=$base_url"
-  } > "$cache" 2>/dev/null
-}
-
 # --- field derivation ------------------------------------------------------
 
 # derive_fields: set skill_name, uip_subcommand, file_ext from the parsed
@@ -321,6 +299,36 @@ compute_outcome() {
   fi
 }
 
+# map_event_name: translate the agent hook event into the canonical eventName
+# token the CLI's `uip track` maps to a uip.skills.<event> event. An
+# unrecognized event prints empty so main() drops it. Stop and StopFailure both
+# map to `completion`, distinguished by outcome (see lifecycle_outcome).
+# CROSS-AGENT: Codex fires SessionStart and Stop under these SAME names with a
+# matching envelope (session_id/source/model; docs: developers.openai.com/
+# codex/hooks), so both map here unchanged. Codex has NO SessionEnd (completion
+# is its terminal signal) and no StopFailure (its API-error turns are not
+# distinguished). Gemini/Cursor use different hook names — separate follow-ups.
+map_event_name() {
+  case "$event" in
+    PostToolUse)      printf 'tool-use' ;;
+    SessionStart)     printf 'session-start' ;;
+    SessionEnd)       printf 'session-end' ;;
+    Stop|StopFailure) printf 'completion' ;;
+    *)                printf '' ;;
+  esac
+}
+
+# lifecycle_outcome: outcome for the non-tool events. A normal turn end (Stop)
+# is `ok`; an API-error turn end (StopFailure) is `failure`. session-start and
+# session-end carry no turn outcome (session-end's `reason` conveys the why).
+lifecycle_outcome() {
+  case "$event" in
+    Stop)        printf 'ok' ;;
+    StopFailure) printf 'failure' ;;
+    *)           printf '' ;;
+  esac
+}
+
 # model_family <resolvedModel>: print the low-cardinality family and drop the
 # context-window marker (e.g. claude-opus-4-8[1m] -> opus). Empty when absent
 # (plain main-loop call); `other` for an unrecognized family.
@@ -357,21 +365,23 @@ san() { printf '%s' "$1" | tr -c 'A-Za-z0-9:._/ -' '_' | cut -c1-120; }
 build_event_json() {
   local spec json sep fkey ftyp fval
   spec="schemaVersion|n|$SCHEMA_VERSION
+eventName|s|$event_name
 toolName|s|$tool
 skillName|s|$skill_name
 uipSubcommand|s|$uip_subcommand
 fileExtension|s|$file_ext
-environment|s|$env_name
-baseUrl|s|$base_url
 outcome|s|$outcome
 permissionMode|s|$permission_mode
 effortLevel|s|$effort_level
 skillsVersion|s|$skills_ver
 toolUseId|s|$tool_use_id
-sessionId|s|$session_id
+session_id|s|$session_id
 subagentModel|s|$subagent_model
 subagentType|s|$subagent_type
 agentType|s|$agent_type
+agent_model|s|$agent_model
+session_source|s|$session_source
+reason|s|$reason
 durationMs|n|$dur_json"
   json="{"; sep=""
   while IFS='|' read -r fkey ftyp fval; do
@@ -397,27 +407,46 @@ main() {
   payload="$(cat)"
   read_fields "$(printf '%s' "$payload" | extract_fields)"
 
-  [ "$event" = "PostToolUse" ] || exit 0
-  is_uipath_call || exit 0
+  # Map the hook event to a canonical eventName; drop unrecognized events.
+  event_name="$(map_event_name)"
+  [ -n "$event_name" ] || exit 0
 
-  resolve_environment
-  derive_fields
+  # Derived only on tool-use; keep defined so the fixed key set always assembles.
+  skill_name=""; uip_subcommand=""; file_ext=""; subagent_model=""
+
+  if [ "$event_name" = "tool-use" ]; then
+    # tool-use is per-call: gate on plugin attribution, then derive tool fields.
+    is_uipath_call || exit 0
+    derive_fields
+    outcome="$(compute_outcome)"
+    subagent_model="$(model_family "$resolved_model")"
+  else
+    # Lifecycle events are session-scoped — they fire for every session where
+    # this plugin is installed (the activation-rate denominator), so they skip
+    # the per-call attribution gate and tool-field derivation.
+    outcome="$(lifecycle_outcome)"
+  fi
+
+  # Enforce the per-event field scoping the contract documents: session_source
+  # only on session-start, reason only on session-end. The awk pass extracts
+  # `source`/`reason` from ANY event's envelope, so a future payload that adds
+  # either key to another event must not bleed into these dimensions.
+  [ "$event_name" = "session-start" ] || session_source=""
+  [ "$event_name" = "session-end" ]   || reason=""
+
+  skills_ver="$(read_skills_version)"
 
-  outcome="$(compute_outcome)"
   # durationMs is a JSON number. Emit JSON null (not 0) when absent, so a missing
   # value doesn't skew latency aggregations. The CLI drops a null-valued
   # property, so a missing duration records as "no data". Stays unquoted.
   case "$duration_ms" in ''|*[!0-9]*) dur_json="null" ;; *) dur_json="$duration_ms" ;; esac
-  subagent_model="$(model_family "$resolved_model")"
-  skills_ver="$(read_skills_version)"
 
   # Sanitize every string field before assembly.
+  event_name="$(san "$event_name")"
   tool="$(san "$tool")"
   skill_name="$(san "$skill_name")"
   uip_subcommand="$(san "$uip_subcommand")"
   file_ext="$(san "$file_ext")"
-  env_name="$(san "$env_name")"
-  base_url="$(san "$base_url")"
   outcome="$(san "$outcome")"
   permission_mode="$(san "$permission_mode")"
   effort_level="$(san "$effort_level")"
@@ -427,12 +456,15 @@ main() {
   subagent_model="$(san "$subagent_model")"
   subagent_type="$(san "$subagent_type")"
   agent_type="$(san "$agent_type")"
+  agent_model="$(san "$agent_model")"
+  session_source="$(san "$session_source")"
+  reason="$(san "$reason")"
 
-  # Hand off to the CLI telemetry tracker. The CLI hard-codes the event name
-  # (uip.skills.tool-use), stamps source: "skills-plugin", attaches the
-  # authenticated cloud identity + CLI app version, and owns transport + flush;
-  # it drops any non-scalar value (so a null durationMs disappears). Send no
-  # `event` key, no envelope, and no `source` (the CLI overrides it).
+  # Hand off to the CLI telemetry tracker. The CLI maps our eventName token to
+  # the uip.skills.<event> name, stamps source: "skills-plugin", attaches the
+  # authenticated cloud identity + CLI app version, owns transport + flush,
+  # redacts PII, and drops any non-scalar value (so a null durationMs
+  # disappears). Send no envelope and no `source` (the CLI overrides it).
   #
   # Detached subshell ( cmd & ) survives this hook's exit so the agent never
   # waits. `uip track` is never-fail (exits 0, emits nothing when telemetry is

package/hooks/set-session-env.ps1

@@ -0,0 +1,72 @@
+# SessionStart step: export the agent's session id to the uip CLI.
+#
+# TWIN SCRIPT: hooks/set-session-env.sh is the bash twin of this file — any
+# behavioral change here MUST be mirrored there in the same PR (see CLAUDE.md).
+#
+# Reads the SessionStart payload on stdin, takes its top-level `session_id`,
+# and appends `export UIPATH_SESSION_ID='<id>'` to $env:CLAUDE_ENV_FILE so
+# every subsequent shell tool subprocess — and therefore every `uip` command
+# the agent runs — inherits it. The CLI stamps that value as the `session_id`
+# dimension on native command telemetry (UiPath/cli#2800), which joins the
+# command stream with the skills events emitted by send-telemetry.ps1: both
+# streams then carry the same session id.
+#
+# Registered SYNCHRONOUSLY in hooks.json (no "async": true): the write must
+# complete before the session's first shell call, or early `uip` commands
+# would miss the id. Costs a few ms (regex only, no network, no uip call).
+#
+# Deliberately NOT gated on UIPATH_TELEMETRY_DISABLED: writing a variable
+# transmits nothing — whether any event carrying it is ever sent stays
+# governed by the CLI's own telemetry gate.
+#
+# Safety:
+#   - host wins: no-op when UIPATH_SESSION_ID is already set in the env;
+#   - idempotent: no-op when the env file already exports it;
+#   - injection-safe: $env:CLAUDE_ENV_FILE is sourced by the agent, so the
+#     value is stripped to [A-Za-z0-9._-] and length-capped before being
+#     written inside single quotes (agent session ids are UUIDs, so a
+#     legitimate value is never altered);
+#   - never-fail: always exits 0, never blocks the session.
+#
+# Runs under Windows PowerShell 5.1 and PowerShell 7+ (pwsh).
+
+$ErrorActionPreference = 'SilentlyContinue'
+
+function Main {
+  $envFile = $env:CLAUDE_ENV_FILE
+  if (-not $envFile) { exit 0 }
+  if ($env:UIPATH_SESSION_ID) { exit 0 }
+
+  $existing = ''
+  if (Test-Path -LiteralPath $envFile -PathType Leaf) {
+    try { $existing = [System.IO.File]::ReadAllText($envFile) } catch { $existing = '' }
+    if ($existing -cmatch '(?m)^export UIPATH_SESSION_ID=') { exit 0 }
+  }
+
+  # Top-level `session_id` from the SessionStart payload. The payload for this
+  # event is small and carries no tool output, and the value is hard-sanitized
+  # anyway, so a plain regex is sufficient here (no full JSON parse needed).
+  $payload = ''
+  try { $payload = [Console]::In.ReadToEnd() } catch { exit 0 }
+  $sid = ''
+  $m = [regex]::Match($payload, '"session_id"\s*:\s*"([^"]*)"')
+  if ($m.Success) { $sid = $m.Groups[1].Value }
+  $sid = $sid -replace '[^A-Za-z0-9._-]', ''
+  if ($sid.Length -gt 64) { $sid = $sid.Substring(0, 64) }
+  if (-not $sid) { exit 0 }
+
+  # If the file exists but doesn't end with a newline (another hook's partial
+  # write), appending directly would concatenate onto its last line and could
+  # break the sourced env file for the whole session — repair it first.
+  $prefix = ''
+  if ($existing -and -not $existing.EndsWith("`n")) { $prefix = "`n" }
+
+  try {
+    [System.IO.File]::AppendAllText($envFile, "${prefix}export UIPATH_SESSION_ID='$sid'`n")
+  }
+  catch { }
+
+  exit 0
+}
+
+Main

package/hooks/set-session-env.sh

@@ -0,0 +1,64 @@
+#!/bin/bash
+# SessionStart step: export the agent's session id to the uip CLI.
+#
+# TWIN SCRIPT: hooks/set-session-env.ps1 is the PowerShell twin of this file —
+# any behavioral change here MUST be mirrored there in the same PR (see
+# CLAUDE.md).
+#
+# Reads the SessionStart payload on stdin, takes its top-level `session_id`,
+# and appends `export UIPATH_SESSION_ID='<id>'` to $CLAUDE_ENV_FILE so every
+# subsequent Bash tool subprocess — and therefore every `uip` command the
+# agent runs — inherits it. The CLI stamps that value as the `session_id`
+# dimension on native command telemetry (UiPath/cli#2800), which joins the
+# command stream with the skills events emitted by send-telemetry.sh: both
+# streams then carry the same session id.
+#
+# Registered SYNCHRONOUSLY in hooks.json (no "async": true): the write must
+# complete before the session's first Bash call, or early `uip` commands would
+# miss the id. Costs a few ms (grep/sed/tr only, no network, no uip call).
+#
+# Deliberately NOT gated on UIPATH_TELEMETRY_DISABLED: writing a variable
+# transmits nothing — whether any event carrying it is ever sent stays
+# governed by the CLI's own telemetry gate.
+#
+# Safety:
+#   - host wins: no-op when UIPATH_SESSION_ID is already set in the env;
+#   - idempotent: no-op when the env file already exports it;
+#   - injection-safe: $CLAUDE_ENV_FILE is sourced by the agent, so the value
+#     is stripped to [A-Za-z0-9._-] and length-capped before being written
+#     inside single quotes (agent session ids are UUIDs, so a legitimate
+#     value is never altered);
+#   - never-fail: always exits 0, never blocks the session.
+
+set +e
+
+main() {
+  [ -n "$CLAUDE_ENV_FILE" ] || exit 0
+  [ -z "$UIPATH_SESSION_ID" ] || exit 0
+  if [ -f "$CLAUDE_ENV_FILE" ] \
+    && grep -q '^export UIPATH_SESSION_ID=' "$CLAUDE_ENV_FILE" 2>/dev/null; then
+    exit 0
+  fi
+
+  # Top-level `session_id` from the SessionStart payload. The payload for this
+  # event is small and carries no tool output, and the value is hard-sanitized
+  # anyway, so a plain grep is sufficient here (no region-scoped pass needed).
+  sid="$(grep -oE '"session_id"[[:space:]]*:[[:space:]]*"[^"]*"' \
+    | head -1 | sed 's/.*"\([^"]*\)"$/\1/' | tr -cd 'A-Za-z0-9._-' | cut -c1-64)"
+  [ -n "$sid" ] || exit 0
+
+  # If the file exists but doesn't end with a newline (another hook's partial
+  # write), appending directly would concatenate onto its last line and could
+  # break the sourced env file for the whole session — repair it first.
+  # `tail -c 1` in a $() strips a trailing newline, so "" means the file is
+  # newline-terminated.
+  if [ -s "$CLAUDE_ENV_FILE" ] && [ -n "$(tail -c 1 "$CLAUDE_ENV_FILE" 2>/dev/null)" ]; then
+    printf '\n' >> "$CLAUDE_ENV_FILE" 2>/dev/null
+  fi
+
+  printf "export UIPATH_SESSION_ID='%s'\n" "$sid" >> "$CLAUDE_ENV_FILE" 2>/dev/null
+
+  exit 0
+}
+
+main

package/hooks/suggest-permissions.ps1

@@ -0,0 +1,45 @@
+# Detects whether Claude Code has an allowlist for `uip` subcommands.
+# If none is found, prints a one-line nudge pointing at /uipath:install-permissions.
+# Non-blocking — never fails the session, even if detection fails.
+# Runs under Windows PowerShell 5.1 and PowerShell 7+ (pwsh).
+#
+# TWIN SCRIPT: hooks/suggest-permissions.sh is the bash twin of this file —
+# any behavioral change here MUST be mirrored there in the same PR (see
+# CLAUDE.md).
+
+$ErrorActionPreference = 'SilentlyContinue'
+
+# Only run inside a Claude Code plugin context.
+if (-not $env:CLAUDE_PLUGIN_ROOT) { exit 0 }
+
+# Codex exposes Claude-compatible plugin environment variables for hook
+# compatibility. This nudge is Claude-specific, so keep Codex sessions silent.
+if ($env:PLUGIN_ROOT) { exit 0 }
+
+# Candidate settings files, most-to-least specific.
+$candidates = @()
+if ($env:CLAUDE_PROJECT_DIR) {
+  $candidates += Join-Path $env:CLAUDE_PROJECT_DIR '.claude/settings.local.json'
+  $candidates += Join-Path $env:CLAUDE_PROJECT_DIR '.claude/settings.json'
+}
+$cwd = (Get-Location).Path
+$candidates += Join-Path $cwd '.claude/settings.local.json'
+$candidates += Join-Path $cwd '.claude/settings.json'
+$candidates += Join-Path $HOME '.claude/settings.json'
+
+# If any candidate already mentions Bash(uip...) in its permissions, stay silent.
+# Intentional simplification: this matches `allow`, `ask`, AND `deny` blocks.
+# Any explicit `uip` rule means the user has made a decision about this CLI —
+# we don't second-guess by nudging them toward a permissive allowlist.
+foreach ($f in $candidates) {
+  if (-not (Test-Path -LiteralPath $f -PathType Leaf)) { continue }
+  try {
+    if (Select-String -LiteralPath $f -Pattern 'Bash(uip' -SimpleMatch -Quiet) { exit 0 }
+  }
+  catch { }
+}
+
+# No allowlist detected — print a one-line nudge to stderr (the Claude Code
+# SessionStart convention for status messages).
+[Console]::Error.WriteLine('uipath: To skip 25+ approval prompts per uip build, run: /uipath:install-permissions')
+exit 0

package/hooks/suggest-permissions.sh

@@ -3,6 +3,10 @@
 # If none is found, prints a one-line nudge pointing at /uipath:install-permissions.
 # Non-blocking — never fails the session, even if detection fails.
 # Cross-platform (macOS, Linux, Windows via Git Bash / MSYS / Cygwin).
+#
+# TWIN SCRIPT: hooks/suggest-permissions.ps1 is the PowerShell twin of this
+# file — any behavioral change here MUST be mirrored there in the same PR (see
+# CLAUDE.md).
 
 # Only run inside a Claude Code plugin context.
 if [ -z "${CLAUDE_PLUGIN_ROOT:-}" ]; then

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/skills",
-  "version": "1.197.2",
+  "version": "1.198.0",
   "description": "UiPath agent skills for Claude Code, Codex, Cursor, Copilot, Gemini and OpenCode — RPA, UI automation, UI testing, coded agents/apps/workflows, and troubleshooting. Distributed as the UiPath Claude Code plugin.",
   "author": {
     "name": "UiPath"

package/skills/uipath-admin/references/audit-commands.md

@@ -200,8 +200,8 @@ uip admin audit tenant export \
 **Implementation notes (worth knowing for diagnostic conversations):**
 
 - Both formats share the same fetch: the CLI issues **one HTTP call per UTC day** inside `[from, to]` and aggregates the per-day responses. Mirrors the `audit-dowload-from-longterm-store.sh` pattern in the AuditService repo.
-- **JSON (default):** a uniquely-named `audit_<from>_<to>_<generated-at>` **folder** is created under `--output-path`, holding one file per UTC day named `<YYYY-MM-DD>.json` (nested-ZIP entries from the server are flattened to `<inner>_<outer>.json`; same-name collisions get an iso-day suffix). The server names the per-day payloads `.txt`; the CLI writes them with a `.json` extension since each is a JSON array of events with PascalCase keys (`Id`, `CreatedOn`, `EventType`, …). Entry names are validated as safe basenames and confirmed to resolve inside the folder before any write (no path traversal / Zip-Slip).
-- **CSV:** the same per-day JSON arrays are parsed and merged into **one** RFC 4180 CSV (CRLF line endings, header row first). Columns follow the long-term-store field order — `Id, CreatedOn, OrganizationId, TenantId, ActorId, ActorName, ActorEmail, ActorDetails, EventType, EventSource, EventTarget, EventDetails, Status, ClientInfo` — with any extra server fields appended (union across events) so no data is dropped. `Status` is the numeric enum (`0`=Success, `1`=Failure); nested objects (e.g. `ClientInfo`) are JSON-stringified into the cell. String cells beginning with `= + - @` (or TAB/CR) are prefixed with a single quote to neutralize spreadsheet formula injection.
+- **JSON (default):** a uniquely-named `audit_<from>_<to>_<generated-at>` **folder** is created under `--output-path`, holding one file per UTC day named `<YYYY-MM-DD>.json` (nested-ZIP entries from the server are flattened to `<inner>_<outer>.json`; same-name collisions get an iso-day suffix). The server names the per-day payloads `.txt`; the CLI writes them with a `.json` extension since each is a JSON array of events with LTS-schema keys (`Identifier`, `DateCreatedUtc`, `Action`, …). Entry names are validated as safe basenames and confirmed to resolve inside the folder before any write (no path traversal / Zip-Slip).
+- **CSV:** the same per-day JSON arrays are parsed and merged into **one** RFC 4180 CSV (CRLF line endings, header row first). Columns follow the long-term-store field order — `OrganizationId, TenantId, ActorId, ActorEmail, ActorDetails, EventDetails, Status, Identifier, DateCreatedUtc, User, Action, Source, Category, ClientInformation` — with any extra server fields appended (union across events) so no data is dropped. `Status` is the numeric enum (`0`=Success, `1`=Failure); nested objects (e.g. `ClientInformation`) are JSON-stringified into the cell. String cells beginning with `= + - @` (or TAB/CR) are prefixed with a single quote to neutralize spreadsheet formula injection.
 - On any single-day HTTP failure (or, for CSV, a day whose payload is not valid JSON), **nothing is written** — for `json` the output folder isn't even created — and the error message identifies which day failed. Earlier successful chunks are not preserved (atomic export).
 - `Days` reports the total number of UTC days requested; `NonEmptyDays` reports how many actually had data. A long export with `NonEmptyDays: 0` means the window was entirely idle, not that the export failed. For `json`, `Files` counts the day-wise files written; for `csv`, `Events: 0` yields a header-only file.
 

package/skills/uipath-admin/references/audit-workflow-guide.md

@@ -226,17 +226,17 @@ audit-exports/
     └── 2026-01-31.json
 ```
 
-Each `.json` file is a JSON array of audit events with **PascalCase** keys (`Id`, `CreatedOn`, `OrganizationId`, `ActorId`, `ActorName`, `EventType`, …) — different from the camelCase shape returned by the live `events` endpoint. Note this in the user's hand-off if they're going to feed the dump into other tooling.
+Each `.json` file is a JSON array of audit events with **LTS-schema** keys (`Identifier`, `DateCreatedUtc`, `OrganizationId`, `ActorId`, `User`, `Action`, …) — different from the camelCase shape returned by the live `events` endpoint. Note this in the user's hand-off if they're going to feed the dump into other tooling.
 
 **CSV** — find the generated file, then inspect the header and row count:
 
 ```bash
 csv=$(ls ./audit-exports/audit_*.csv | head -1)   # the generated audit_<from>_<to>_<generatedAt>.csv
-head -1 "$csv"                                      # shared header (PascalCase columns)
+head -1 "$csv"                                      # shared header (LTS-schema columns)
 python3 -c "import csv,sys; print(sum(1 for _ in csv.reader(open(sys.argv[1]))) - 1, 'rows')" "$csv"
 ```
 
-One header row, then every event across all days as a data row (same PascalCase column names as the JSON files' keys). The row count should match `Events` in the result envelope.
+One header row, then every event across all days as a data row (same LTS-schema column names as the JSON files' keys). The row count should match `Events` in the result envelope.
 
 Edge cases the CLI handles automatically — surface in your hand-off only if they appear:
 
@@ -302,7 +302,7 @@ Two or more signals? Run them in sequence and stitch the results in the final re
 - **`tenant` events without an active tenant fail loudly.** If `uip login` has no tenant selected, every tenant-scoped command throws. Either re-`uip login` and pick a tenant, or pass `--tenant-id <guid>` on every call.
 - **`events` cursor pagination is chronologically reversed from intuition.** `next` = newer (often null), `previous` = older (the typical "load more"). The CLI tool follows `previous` automatically when you bump `--limit > 200` — don't re-implement this in the agent.
 - **Date-only ISO strings are interpreted as UTC midnight.** `--from-date 2026-01-01` means `2026-01-01T00:00:00Z`. To capture the full final day in `--to-date`, use `2026-02-01` (exclusive next day) or `2026-01-31T23:59:59.999Z`.
-- **Export format depends on `--file-format`.** The default `json` writes one **JSON** file per UTC day (named `<YYYY-MM-DD>.json`) into a generated subfolder under `--output-path`, with **PascalCase** keys; `--file-format csv` produces a single merged **CSV** whose header uses those same PascalCase field names. Both differ from the camelCase live `events` endpoint — don't paste an export into a parser expecting the live shape. In the CSV, `Status` is numeric (`0`/`1`) and `ClientInfo` is a JSON-stringified cell.
+- **Export format depends on `--file-format`.** The default `json` writes one **JSON** file per UTC day (named `<YYYY-MM-DD>.json`) into a generated subfolder under `--output-path`, with **LTS-schema** keys; `--file-format csv` produces a single merged **CSV** whose header uses those same LTS-schema field names. Both differ from the camelCase live `events` endpoint — don't paste an export into a parser expecting the live shape. In the CSV, `Status` is numeric (`0`/`1`) and `ClientInformation` is a JSON-stringified cell.
 - **Org sources and tenant sources are different sets.** Don't reuse a GUID from `org sources` in a `tenant events` query — the filter will silently match nothing.
 
 ## Output Etiquette — after an audit query or export

package/skills/uipath-agents/references/coded/capabilities/batch-transform/planning.md

@@ -11,7 +11,7 @@ Pick this when:
 
 Confirm BatchTransform is the right mode first — see [../../../context-grounding-patterns.md](../../../context-grounding-patterns.md).
 
-For Studio Web Agent Builder → [../../lowcode/capabilities/built-in-tools/batch-transform/planning.md](../../lowcode/capabilities/built-in-tools/batch-transform/planning.md).
+For Studio Web Agent Builder → [../../../lowcode/capabilities/built-in-tools/batch-transform/planning.md](../../../lowcode/capabilities/built-in-tools/batch-transform/planning.md).
 
 ## Inputs You Need Before Building
 

package/skills/uipath-agents/references/coded/capabilities/deeprag/planning.md

@@ -11,7 +11,7 @@ Pick this when:
 
 Confirm DeepRAG is the right mode first — see [../../../context-grounding-patterns.md](../../../context-grounding-patterns.md).
 
-For Studio Web Agent Builder → [../../lowcode/capabilities/built-in-tools/deeprag/planning.md](../../lowcode/capabilities/built-in-tools/deeprag/planning.md).
+For Studio Web Agent Builder → [../../../lowcode/capabilities/built-in-tools/deeprag/planning.md](../../../lowcode/capabilities/built-in-tools/deeprag/planning.md).
 
 ## Inputs You Need Before Building
 

package/skills/uipath-agents/references/coded/capabilities/guardrails/guardrails-recommend.md

@@ -191,6 +191,9 @@ Map catalog parameter shapes to Python:
 | `enum-list` (e.g. `entities`) | List of enum members (e.g. `[PIIDetectionEntityType.EMAIL, PIIDetectionEntityType.PHONE_NUMBER]`) — names taken from SDK docs |
 | `map-enum` (e.g. `entityThresholds`) | Dict from enum member → number (e.g. `{PIIDetectionEntityType.EMAIL: 0.5}`) — keys must exactly match the `enum-list` parameter's values |
 | `number` (e.g. `threshold`) | Plain `float` / `int` constructor argument |
+| `text` (e.g. `guardrailText`) | Plain `str` constructor argument |
+| `enum` (e.g. `model`) | `str` value from the allowed options list. When the catalog shows an empty options list (as with `llm_as_judge`'s `model`), ask the user which model ID to use — the available values depend on the LLM Gateway configuration in their tenant. |
+| `text-list` (e.g. `positiveExamples`, `negativeExamples`) | `List[str]` constructor argument |
 
 Use `BlockAction(...)`, `LogAction(severity_level=...)`, or `EscalateAction(app_name=..., app_folder_path=..., recipient=...)` for human-in-the-loop review — or any other action the SDK docs expose. Never invent action class names. For `EscalateAction`, the fetched SDK docs must expose the class/parameters, and the Action App must be deployed and declared in `bindings.json` using [../../lifecycle/bindings-reference.md](../../lifecycle/bindings-reference.md) (see [guardrails.md § Escalation action (HITL)](guardrails.md#escalation-action-human-in-the-loop)).
 
@@ -204,7 +207,7 @@ Write the recommended guardrails into the Python file using the patterns from [g
    ```bash
    python3 -c "import ast; ast.parse(open('graph.py').read())"
    ```
-2. **Runtime wiring (mandatory)** — the guardrails are actually attached. A guardrail whose symbols were imported from the wrong module parses fine but **silently never fires**. Run the adapter-registration and `_GuardedLLM` / `_GuardedTool` wrap checks from [guardrails.md § Verify Guardrails Are Actually Wired](guardrails.md#verify-guardrails-are-actually-wired-mandatory-after-writing). Do not report the guardrails as added until these pass.
+2. **Runtime wiring (mandatory)** — the guardrails are actually attached. A guardrail whose symbols were imported from the wrong module parses fine but **silently never fires**. Run the adapter-registration and `_GuardedLLM` / `_GuardedTool` wrap checks from [guardrails.md § Verify Guardrails Are Actually Wired](guardrails.md#verify-guardrails-are-actually-wired-mandatory-after-writing-for-langchain-ml-guardrails). Do not report the guardrails as added until these pass.
 
 (Replace `graph.py` with the actual entrypoint file from Step 1.)
 
@@ -279,7 +282,7 @@ python3 -c "import ast; ast.parse(open('graph.py').read())"
 5. **Never recommend two validators with the same `security_category` at the same scope and stage** (e.g. `prompt_injection` + `user_prompt_attacks` at LLM PRE). De-duplicate per Step 3: drop catalog-deprecated entries, keep the best fit, mention the alternative. Derive the grouping and deprecation from the catalog's own fields — do not hardcode validator names.
 6. **Default the action to the catalog example's `action_type`; never silently downgrade Block → Log.** Security-critical guardrails (`adversarial_input`, `content_safety`) default to `Block`. If you use `LogAction` for a guardrail whose catalog default is `Block`, state it and the reason in the report (Step 6).
 7. **Block as early as possible — pick the outermost scope the validator allows.** For input protection (PII, jailbreak, injection) prefer `GuardrailScope.AGENT` · PRE over Llm over Tool, so the run halts before the LLM call. PII meant to stop the agent handling personal data goes at **Agent**, not Llm. Only narrow when the validator is scope-restricted (e.g. `prompt_injection` / `user_prompt_attacks` are Llm-only) or the user asks for a narrower scope. See Step 5.
-8. **For LangChain / LangGraph agents, import guardrail symbols from `uipath_langchain.guardrails`, not `uipath.platform.guardrails`.** Only `uipath_langchain.guardrails` registers the LangChain adapter as an import side effect; the platform module exposes identical names but registers nothing, so guardrails silently no-op. For any other framework (LlamaIndex, OpenAI Agents, plain Python), no UiPath framework adapter is published yet — use `uipath.platform.guardrails` (the framework-agnostic SDK) directly. After writing for LangChain, verify runtime wiring (adapter registered + `_GuardedLLM`/`_GuardedTool` wrap), not just `ast.parse`. See [guardrails.md § Imports Pattern](guardrails.md#imports-pattern) and [§ Verify Guardrails Are Actually Wired](guardrails.md#verify-guardrails-are-actually-wired-mandatory-after-writing).
+8. **For LangChain / LangGraph agents, import guardrail symbols from `uipath_langchain.guardrails`, not `uipath.platform.guardrails`.** Only `uipath_langchain.guardrails` registers the LangChain adapter as an import side effect; the platform module exposes identical names but registers nothing, so guardrails silently no-op. For any other framework (LlamaIndex, OpenAI Agents, plain Python), no UiPath framework adapter is published yet — use `uipath.platform.guardrails` (the framework-agnostic SDK) directly. After writing for LangChain, verify runtime wiring (adapter registered + `_GuardedLLM`/`_GuardedTool` wrap), not just `ast.parse`. See [guardrails.md § Imports Pattern](guardrails.md#imports-pattern) and [§ Verify Guardrails Are Actually Wired](guardrails.md#verify-guardrails-are-actually-wired-mandatory-after-writing-for-langchain-ml-guardrails).
 9. **For Tool scope**: verify the tool exists as a `@tool` function in the agent code before adding the guardrail. If the agent has no tools, do not add a Tool-scoped guardrail.
 10. **For LLM-scope decorator**: the LLM must be inside a named factory function. If it is assigned directly (`llm = UiPathChat(...)`), refactor into a factory first — never decorate a module-level assignment.
 11. **For Agent-scope decorator**: `create_agent(...)` must be inside a named factory function. If it is called at module level, refactor into a factory first.