@hybridaione/hybridclaw 0.1.21 → 0.1.22

package/CHANGELOG.md

@@ -8,6 +8,26 @@
 
 ### Fixed
 
+## [0.1.22](https://github.com/HybridAIOne/hybridclaw/tree/v0.1.22)
+
+### Added
+
+- **Skills trust scanner**: Added `src/skills-guard.ts` with Hermes-derived regex threat detection (exfiltration, prompt injection, destructive ops, persistence, reverse shells, obfuscation, supply chain, credential exposure), structural checks (file count/size limits, binary blocking, symlink escape checks), and invisible-unicode detection.
+- **Skill scan cache**: Added mtime-signature + content-hash scanner caching to skip re-scan on unchanged skills.
+- **Extended SKILL frontmatter**: Added support for `always`, `requires.bins`, `requires.env`, and `metadata.hybridclaw.{tags,related_skills}` while preserving backward compatibility for existing fields.
+
+### Changed
+
+- **Skill discovery tiers**: Expanded skill discovery precedence to `extra < bundled < codex < claude < agents-personal < agents-project < workspace`, including `config.skills.extraDirs[]` and `.agents/skills` interop paths.
+- **Skill prompt embedding modes**: Implemented Always/Summary/Hidden behavior via frontmatter flags (`always`, `disable-model-invocation`) with `maxAlwaysChars=10000`, `maxSkillsPromptChars=30000`, and `maxSkillsInPrompt=150`.
+- **Skill eligibility gating**: Skills with unmet `requires` are now silently excluded from both prompt availability and slash-command resolution.
+- **Skill slash commands**: Added command-name sanitization (32-char max), reserved built-in command blocking, and deterministic collision deduplication (`-2`, `-3`, ...), while keeping `/skill name`, `/skill:name`, and `/<name>` invocation compatibility.
+- **Web tool routing guidance**: Tool descriptions and runtime prompt guidance now include explicit `web_fetch` vs browser decision rules, concrete SPA/auth/app categories, and quantified cost asymmetry.
+- **web_fetch escalation signaling**: `web_fetch` now emits structured escalation hints (`javascript_required`, `spa_shell_only`, `empty_extraction`, `boilerplate_only`, `bot_blocked`) and surfaces them in tool output for browser fallback routing.
+- **Browser extraction steering**: `browser_navigate` responses now include text preview metadata and explicit next-step hints (`browser_snapshot` with `mode="full"`), and docs/prompts now clarify that `browser_pdf` is export-only (not text extraction).
+
+### Fixed
+
 ## [0.1.21](https://github.com/HybridAIOne/hybridclaw/tree/v0.1.21)
 
 ### Added

package/README.md

@@ -87,6 +87,7 @@ HybridClaw uses typed runtime config in `config.json` (auto-created on first run
 
 - Start from `config.example.json` (reference)
 - Runtime watches `config.json` and hot-reloads most settings (model defaults, heartbeat, prompt hooks, limits, etc.)
+- `skills.extraDirs` adds additional enterprise/shared skill roots (lowest precedence tier)
 - `proactive.*` controls autonomous behavior (`activeHours`, `delegation`, `autoRetry`)
 - `observability.*` controls push ingest into HybridAI (`events:batch` endpoint, batching, identity metadata)
 - Some settings require restart to fully apply (for example HTTP bind host/port)
@@ -178,13 +179,25 @@ HybridClaw supports `SKILL.md`-based skills (`<skill-name>/SKILL.md`).
 
 You can place skills in:
 
-- `./skills/<skill-name>/SKILL.md` (project-level)
-- `<agent workspace>/skills/<skill-name>/SKILL.md` (agent-specific)
-- `$CODEX_HOME/skills/<skill-name>/SKILL.md`, `~/.codex/skills/<skill-name>/SKILL.md`, or `~/.claude/skills/<skill-name>/SKILL.md` (managed/shared)
+- any directory listed in `config.skills.extraDirs[]` (enterprise/shared)
+- bundled package skills (`<hybridclaw install>/skills/<skill-name>/SKILL.md`)
+- `$CODEX_HOME/skills/<skill-name>/SKILL.md` or `~/.codex/skills/<skill-name>/SKILL.md`
+- `~/.claude/skills/<skill-name>/SKILL.md`
+- `~/.agents/skills/<skill-name>/SKILL.md`
+- `./.agents/skills/<skill-name>/SKILL.md` (project)
+- `./skills/<skill-name>/SKILL.md` (workspace)
 
 Load precedence is:
 
-- managed/shared < project < agent workspace
+- `extra < bundled < codex < claude < agents-personal < agents-project < workspace`
+- skills are merged by `name`; higher-precedence sources override lower-precedence ones
+
+Security scanning is trust-aware:
+
+- `bundled` sources are treated as `builtin` and not scanned
+- `workspace` sources (`./skills/`, `./.agents/skills/`) are scanned; `caution` is allowed, `dangerous` is blocked
+- `personal` sources (`~/.codex/skills/`, `~/.claude/skills/`, `~/.agents/skills/`) are scanned and blocked on `caution`/`dangerous`
+- scanner includes Hermes-derived regex checks, structural limits (50 files, 1MB total, 256KB/file, binary/symlink checks), invisible-unicode detection, and mtime+content-hash cache reuse
 
 ### Required format
 
@@ -196,6 +209,14 @@ name: repo-orientation
 description: Quickly map an unfamiliar repository and identify where a requested feature should be implemented.
 user-invocable: true
 disable-model-invocation: false
+always: false
+requires:
+  bins: [docker, git]
+  env: [GITHUB_TOKEN]
+metadata:
+  hybridclaw:
+    tags: [devops, docker]
+    related_skills: [kubernetes]
 ---
 
 # Repo Orientation
@@ -208,16 +229,25 @@ Supported frontmatter keys:
 - `description` (required)
 - `user-invocable` (optional, default `true`)
 - `disable-model-invocation` (optional, default `false`)
+- `always` (optional, default `false`; embeds full skill body in the system prompt up to `maxAlwaysChars=10000`, then demotes to summary)
+- `requires.bins` / `requires.env` (optional; skill is excluded unless requirements are met)
+- `metadata.hybridclaw.tags` / `metadata.hybridclaw.related_skills` (optional metadata namespace)
 
 ### Using skills
 
-Skills are listed to the model as metadata (`name`, `description`, `location`), and the model reads `SKILL.md` on demand with the `read` tool.
+Skills are listed to the model as metadata (`name`, `description`, `location`), and the model reads `SKILL.md` on demand with the `read` tool. Skills with `always: true` are embedded directly in the system prompt.
+
+Prompt embedding modes:
+
+- `Always`: `always: true` embeds full body in `<skill_always ...>` (budgeted by `maxAlwaysChars=10000`)
+- `Summary`: default mode, emits only XML metadata under `<available_skills>`
+- `Hidden`: `disable-model-invocation: true` excludes the skill from model prompt metadata (still invocable by slash command when `user-invocable: true`)
 
 Explicit invocation is supported via:
 
 - `/skill <name> [input]`
 - `/skill:<name> [input]`
-- `/<name> [input]` (when `user-invocable: true`)
+- `/<name> [input]` (when `user-invocable: true`; command names are sanitized to lowercase `a-z0-9-`, max 32 chars, with `-2`/`-3` dedup and built-in command-name blocking)
 
 Example skill in this repo:
 
@@ -233,8 +263,8 @@ The agent has access to these sandboxed tools inside the container:
 - `memory` — durable memory files (`MEMORY.md`, `USER.md`, `memory/YYYY-MM-DD.md`)
 - `session_search` — search/summarize historical sessions from transcript archives
 - `delegate` — push-based background subagent tasks (`single`, `parallel`, `chain`) with auto-announced completion (no polling)
-- `web_fetch` — fetch a URL and extract readable content (HTML → markdown/text)
-- `browser_*` (optional) — interactive browser automation (`navigate`, `snapshot`, `click`, `type`, `press`, `scroll`, `back`, `screenshot`, `pdf`, `close`)
+- `web_fetch` — plain HTTP fetch + extraction for static/read-only content (docs, articles, READMEs, JSON/text APIs, direct files)
+- `browser_*` (optional) — full browser automation for JS-rendered or interactive pages (`navigate`, `snapshot`, `click`, `type`, `press`, `scroll`, `back`, `screenshot`, `pdf`, `close`)
 
 `delegate` mode examples:
 
@@ -244,6 +274,12 @@ The agent has access to these sandboxed tools inside the container:
 
 Browser tooling notes:
 
+- Routing default: prefer `web_fetch` first for read-only retrieval.
+- Use browser tools for SPAs/web apps/auth flows/interaction tasks, or when `web_fetch` returns escalation hints (`javascript_required`, `spa_shell_only`, `empty_extraction`, `boilerplate_only`, `bot_blocked`).
+- Cost profile: browser calls are typically ~10-100x slower/more expensive than `web_fetch`.
+- Browser read flow: after `browser_navigate`, use `browser_snapshot` with `mode="full"` to extract content, then `browser_scroll` + `browser_snapshot` for additional lazy-loaded sections.
+- `browser_pdf` is for export artifacts, not text extraction.
+
 - The shipped container image preinstalls `agent-browser` and Chromium (Playwright).
 - You can override the binary via `AGENT_BROWSER_BIN` if needed.
 - User-directed authenticated browser-flow testing is supported (including filling/submitting login forms on the requested site).

package/config.example.json

@@ -6,6 +6,9 @@
     "trustModelVersion": "",
     "trustModelAcceptedBy": ""
   },
+  "skills": {
+    "extraDirs": []
+  },
   "discord": {
     "prefix": "!claw"
   },

package/container/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "hybridclaw-agent",
-  "version": "0.1.21",
+  "version": "0.1.22",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "hybridclaw-agent",
-      "version": "0.1.21",
+      "version": "0.1.22",
       "dependencies": {
         "@mozilla/readability": "^0.6.0",
         "agent-browser": "^0.15.1",

package/container/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hybridclaw-agent",
-  "version": "0.1.21",
+  "version": "0.1.22",
   "type": "module",
   "scripts": {
     "build": "tsc",

package/container/src/browser-tools.ts

@@ -56,6 +56,24 @@ const EXTRACT_IFRAMES_SCRIPT = `(() => {
   }));
 })()`;
 
+const EXTRACT_TEXT_PREVIEW_SCRIPT = `(() => {
+  const bodyText = document.body ? String(document.body.innerText || '') : '';
+  const normalized = bodyText
+    .replace(/\\r/g, '')
+    .replace(/[ \\t]+\\n/g, '\\n')
+    .replace(/\\n{3,}/g, '\\n\\n')
+    .trim();
+  const previewLimit = 6000;
+  return {
+    text_length: normalized.length,
+    preview: normalized.slice(0, previewLimit),
+    preview_truncated: normalized.length > previewLimit,
+    has_noscript: Boolean(document.querySelector('noscript')),
+    root_shell: Boolean(document.querySelector('div#root:empty, div#app:empty, div#__next:empty')),
+    ready_state: String(document.readyState || ''),
+  };
+})()`;
+
 const NETWORK_TIMINGS_SCRIPT = `(() => {
   const entries = performance.getEntriesByType('resource');
   return entries
@@ -563,6 +581,19 @@ function buildBotDetectionWarning(titleValue: unknown): Record<string, unknown>
   };
 }
 
+function buildReadExtractionHint(params: {
+  contentLength: number;
+  hasNoscript: boolean;
+  rootShell: boolean;
+}): string {
+  const base =
+    'For content extraction, call browser_snapshot with {"mode":"full"} next. For long or lazy-loaded pages, run browser_scroll then browser_snapshot again.';
+  if (params.hasNoscript || params.rootShell || params.contentLength < 200) {
+    return `${base} This page currently looks dynamic/app-shell-like; do not conclude "inaccessible" before snapshot attempts.`;
+  }
+  return `${base} Avoid browser_pdf for text extraction; PDF export is for artifact output.`;
+}
+
 function extractVisionTextContent(content: unknown): string {
   if (typeof content === 'string') return content.trim();
   if (!Array.isArray(content)) return '';
@@ -754,12 +785,31 @@ export async function executeBrowserTool(name: string, args: Record<string, unkn
         const data = (result.data || {}) as Record<string, unknown>;
         const title = String(data.title || '');
         const botWarning = buildBotDetectionWarning(title);
+        const textEval = await runBrowserEval(effectiveSessionId, EXTRACT_TEXT_PREVIEW_SCRIPT, 20_000);
+        const textData = textEval.success ? asRecord(textEval.result) : null;
+        const contentPreview = typeof textData?.preview === 'string' ? textData.preview : '';
+        const contentLength =
+          typeof textData?.text_length === 'number' && Number.isFinite(textData.text_length)
+            ? Math.max(0, Math.floor(textData.text_length))
+            : 0;
+        const contentPreviewTruncated = textData?.preview_truncated === true;
+        const hasNoscript = textData?.has_noscript === true;
+        const rootShell = textData?.root_shell === true;
+        const readyState = typeof textData?.ready_state === 'string' ? textData.ready_state : '';
+        const extractionHint = buildReadExtractionHint({ contentLength, hasNoscript, rootShell });
         // Best-effort priming so browser_network has request listeners active quickly.
         await runAgentBrowser(effectiveSessionId, 'network', ['requests']).catch(() => undefined);
         return success({
           url: data.url || parsed.toString(),
           title,
           session_id: effectiveSessionId,
+          content_text_length: contentLength,
+          ...(contentPreview ? { content_preview: contentPreview } : {}),
+          ...(contentPreview ? { content_preview_truncated: contentPreviewTruncated } : {}),
+          ...(readyState ? { ready_state: readyState } : {}),
+          ...(hasNoscript ? { has_noscript: true } : {}),
+          ...(rootShell ? { root_shell: true } : {}),
+          read_extraction_hint: extractionHint,
           ...(botWarning ? { bot_detection_warning: botWarning } : {}),
         });
       }
@@ -1000,7 +1050,7 @@ export const BROWSER_TOOL_DEFINITIONS: ToolDefinition[] = [
     function: {
       name: 'browser_navigate',
       description:
-        'Navigate to an HTTP/HTTPS URL in a browser session. Private/loopback hosts are blocked by default (SSRF guard).',
+        'Navigate to a URL in a full browser session with JavaScript execution and dynamic rendering. Use for SPAs (React/Vue/Angular/Svelte), auth/login flows, dashboards/web apps (Notion, Google Docs, Airtable, Jira, etc.), interaction tasks (click/type/submit/scroll), bot/captcha/consent flows, or when web_fetch returns escalation hints (javascript_required, spa_shell_only, empty_extraction, boilerplate_only, bot_blocked). Prefer web_fetch instead for static docs/articles/wikis, direct API JSON/XML/text endpoints, and simple read-only retrieval. Important: browser_navigate opens the page but does not replace content extraction; for read/summarize tasks call browser_snapshot with mode="full" next. Browser usage is typically ~10-100x slower/more expensive than web_fetch. Private/loopback hosts are blocked by default (SSRF guard).',
       parameters: {
         type: 'object',
         properties: {
@@ -1015,7 +1065,7 @@ export const BROWSER_TOOL_DEFINITIONS: ToolDefinition[] = [
     function: {
       name: 'browser_snapshot',
       description:
-        'Return an accessibility-tree snapshot of the current page with element refs usable by browser_click/browser_type.',
+        'Return an accessibility-tree snapshot of the current page with element refs usable by browser_click/browser_type. Use this to actually read page content after browser_navigate; for extraction tasks prefer mode="full" and repeat after browser_scroll on long/lazy-loaded pages.',
       parameters: {
         type: 'object',
         properties: {
@@ -1134,7 +1184,7 @@ export const BROWSER_TOOL_DEFINITIONS: ToolDefinition[] = [
     function: {
       name: 'browser_pdf',
       description:
-        'Save the current page as PDF. Output path is constrained under /workspace/.browser-artifacts for safety.',
+        'Save the current page as PDF artifact. Output path is constrained under /workspace/.browser-artifacts for safety. Use for export/sharing only, not for text extraction or summarization.',
       parameters: {
         type: 'object',
         properties: {

package/container/src/tools.ts

@@ -879,7 +879,14 @@ export async function executeTool(name: string, argsJson: string): Promise<strin
         });
         const header = result.title ? `# ${result.title}\n\n` : '';
         const meta = `[${result.extractor}] ${result.finalUrl} (${result.status}, ${result.tookMs}ms)`;
-        return `${meta}\n\n${header}${result.text}`;
+        const lines = [meta];
+        if (result.escalationHint) {
+          lines.push(`Escalation hint: ${result.escalationHint} (retry with browser_navigate for this URL).`);
+        }
+        if (result.warning) {
+          lines.push(`Warning: ${result.warning}`);
+        }
+        return `${lines.join('\n')}\n\n${header}${result.text}`;
       }
 
       case 'browser_navigate':
@@ -1207,7 +1214,7 @@ export const TOOL_DEFINITIONS: ToolDefinition[] = [
     function: {
       name: 'web_fetch',
       description:
-        'Fetch a URL and extract its readable content as markdown or plain text. Works with HTML pages, JSON APIs, and markdown URLs. Use for reading web pages, documentation, API responses, etc.',
+        'Fetch a URL via plain HTTP GET and extract readable content (HTML to markdown/text). No JavaScript execution, no clicks, no form interaction. Use for static read-only retrieval: articles, docs, wikis, READMEs, API JSON/text endpoints, and direct files/PDFs. Avoid for SPAs (React/Vue/Angular/Next client routes), auth/login-gated pages, dashboards/web apps, bot/challenge flows, or content loaded after render via XHR/fetch. Cost: typically ~10-100x cheaper/faster than browser tools. Default to web_fetch for read-only retrieval, then escalate to browser_navigate when output is empty/boilerplate, JavaScript-required, SPA shell-only, or bot-blocked.',
       parameters: {
         type: 'object',
         properties: {

package/container/src/web-fetch.ts

@@ -19,6 +19,25 @@ const TIMEOUT_MS = 30_000;
 const CACHE_TTL_MS = 15 * 60_000; // 15 min
 const CACHE_MAX_ENTRIES = 100;
 const READABILITY_MAX_HTML_CHARS = 1_000_000;
+const ESCALATION_MIN_TEXT_CHARS = 200;
+const ESCALATION_MIN_HTML_CHARS = 5_000;
+const BOT_BLOCKED_PATTERNS = [
+  'access denied',
+  'bot detected',
+  'captcha',
+  'cf-chl-',
+  'checking your browser',
+  'cloudflare',
+  'just a moment',
+  'attention required',
+  'verification required',
+];
+const JAVASCRIPT_REQUIRED_PATTERNS = [
+  'enable javascript',
+  'javascript required',
+  'requires javascript',
+  'turn on javascript',
+];
 const USER_AGENT =
   'Mozilla/5.0 (Macintosh; Intel Mac OS X 14_7_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.0.0 Safari/537.36';
 
@@ -271,10 +290,71 @@ async function fetchWithRedirects(
   throw new Error(`Too many redirects (max ${maxRedirects})`);
 }
 
+function normalizeForDetection(value: string): string {
+  return String(value || '').toLowerCase().replace(/\s+/g, ' ').trim();
+}
+
+function includesAny(haystack: string, needles: readonly string[]): boolean {
+  for (const needle of needles) {
+    if (haystack.includes(needle)) return true;
+  }
+  return false;
+}
+
+function detectEscalationHint(params: {
+  status: number;
+  contentType: string;
+  body: string;
+  extractedText: string;
+}): WebFetchEscalationHint | undefined {
+  const normalizedBody = normalizeForDetection(params.body);
+  if (params.status === 403 || params.status === 429 || includesAny(normalizedBody, BOT_BLOCKED_PATTERNS)) {
+    return 'bot_blocked';
+  }
+
+  const isHtml = params.contentType.toLowerCase().includes('text/html');
+  if (!isHtml) return undefined;
+
+  if (
+    /<noscript[\s\S]{0,2000}javascript[\s\S]{0,2000}<\/noscript>/i.test(params.body) ||
+    includesAny(normalizedBody, JAVASCRIPT_REQUIRED_PATTERNS)
+  ) {
+    return 'javascript_required';
+  }
+
+  if (
+    /<div[^>]+id=["'](?:root|app|__next)["'][^>]*>\s*<\/div>/i.test(params.body) &&
+    normalizeForDetection(params.extractedText).length < ESCALATION_MIN_TEXT_CHARS
+  ) {
+    return 'spa_shell_only';
+  }
+
+  const normalizedExtracted = normalizeForDetection(params.extractedText);
+  if (normalizedExtracted.length === 0) {
+    return 'empty_extraction';
+  }
+
+  if (
+    normalizedExtracted.length < ESCALATION_MIN_TEXT_CHARS &&
+    params.body.length > ESCALATION_MIN_HTML_CHARS
+  ) {
+    return 'boilerplate_only';
+  }
+
+  return undefined;
+}
+
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
 
+export type WebFetchEscalationHint =
+  | 'javascript_required'
+  | 'empty_extraction'
+  | 'spa_shell_only'
+  | 'bot_blocked'
+  | 'boilerplate_only';
+
 export interface WebFetchResult {
   url: string;
   finalUrl: string;
@@ -290,6 +370,7 @@ export interface WebFetchResult {
   text: string;
   cached?: boolean;
   warning?: string;
+  escalationHint?: WebFetchEscalationHint;
 }
 
 export async function webFetch(params: {
@@ -327,10 +408,6 @@ export async function webFetch(params: {
       controller.signal,
     );
 
-    if (!res.ok) {
-      throw new Error(`Web fetch failed (${res.status}): ${res.statusText}`);
-    }
-
     const contentType = res.headers.get('content-type') ?? 'application/octet-stream';
     const normalizedContentType = contentType.split(';')[0]?.trim() || 'application/octet-stream';
     const bodyResult = await readResponseText(res, MAX_RESPONSE_BYTES);
@@ -357,13 +434,26 @@ export async function webFetch(params: {
       }
     }
 
+    const extractedText = extractMode === 'text' ? text : markdownToText(text);
+    const escalationHint = detectEscalationHint({
+      status: res.status,
+      contentType: normalizedContentType,
+      body,
+      extractedText,
+    });
+
+    if (!res.ok && !escalationHint) {
+      throw new Error(`Web fetch failed (${res.status}): ${res.statusText}`);
+    }
+
     // Truncate
     const truncated = text.length > maxChars;
     if (truncated) text = text.slice(0, maxChars);
 
-    const warning = bodyResult.truncated
-      ? `Response body truncated after ${MAX_RESPONSE_BYTES} bytes.`
-      : undefined;
+    const warnings: string[] = [];
+    if (!res.ok) warnings.push(`HTTP ${res.status} ${res.statusText}.`);
+    if (bodyResult.truncated) warnings.push(`Response body truncated after ${MAX_RESPONSE_BYTES} bytes.`);
+    const warning = warnings.length > 0 ? warnings.join(' ') : undefined;
 
     const result: WebFetchResult = {
       url: params.url,
@@ -379,6 +469,7 @@ export async function webFetch(params: {
       tookMs: Date.now() - start,
       text,
       warning,
+      escalationHint,
     };
 
     writeCache(cacheKey, result);

package/dist/prompt-hooks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prompt-hooks.d.ts","sourceRoot":"","sources":["../src/prompt-hooks.ts"],"names":[],"mappings":"AACA,OAAO,EAAqB,KAAK,KAAK,EAAE,MAAM,aAAa,CAAC;AAK5D,MAAM,MAAM,cAAc,GAAG,WAAW,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAC/D,MAAM,MAAM,sBAAsB,GAAG,cAAc,GAAG,aAAa,CAAC;AAEpE,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,MAAM,EAAE,KAAK,EAAE,CAAC;IAChB,OAAO,CAAC,EAAE,cAAc,GAAG,cAAc,CAAC;IAC1C,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,sBAAsB,CAAC;IAC7B,OAAO,EAAE,MAAM,CAAC;CACjB;AAQD,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CASpF;AA2KD,wBAAgB,cAAc,CAAC,OAAO,EAAE,iBAAiB,GAAG,gBAAgB,EAAE,CAY7E;AAED,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,iBAAiB,GAAG,MAAM,CAI7E"}
+{"version":3,"file":"prompt-hooks.d.ts","sourceRoot":"","sources":["../src/prompt-hooks.ts"],"names":[],"mappings":"AACA,OAAO,EAAqB,KAAK,KAAK,EAAE,MAAM,aAAa,CAAC;AAK5D,MAAM,MAAM,cAAc,GAAG,WAAW,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAC/D,MAAM,MAAM,sBAAsB,GAAG,cAAc,GAAG,aAAa,CAAC;AAEpE,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,MAAM,EAAE,KAAK,EAAE,CAAC;IAChB,OAAO,CAAC,EAAE,cAAc,GAAG,cAAc,CAAC;IAC1C,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,sBAAsB,CAAC;IAC7B,OAAO,EAAE,MAAM,CAAC;CACjB;AAQD,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CASpF;AAsLD,wBAAgB,cAAc,CAAC,OAAO,EAAE,iBAAiB,GAAG,gBAAgB,EAAE,CAY7E;AAED,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,iBAAiB,GAAG,MAAM,CAI7E"}

package/dist/prompt-hooks.js

@@ -45,6 +45,17 @@ function buildSafetyHook(context) {
         'After file changes, run commands only when asked; otherwise explicitly offer to run them immediately.',
         'Only skip file creation when the user explicitly asks for snippet-only or explanation-only output.',
         '',
+        '## Web Retrieval Routing (web_fetch vs browser_*)',
+        'Decision rule: default to `web_fetch` for read-only content retrieval.',
+        'Use browser tools only when at least one of these is true: (1) known app-like/auth-gated URL, (2) interaction is required (click/type/login/scroll), (3) `web_fetch` returned escalation hints, (4) user explicitly requested browser use.',
+        'Prefer browser for: SPAs/client-rendered apps (React/Vue/Angular/Next client routes), dashboards/web apps, social feeds, login/OAuth/cookie-consent/CAPTCHA flows, or API-driven pages that populate after initial render.',
+        'Prefer web_fetch for: docs/wikis/READMEs/articles/reference pages, direct JSON/XML/text/CSV/PDF endpoints, and simple read-only extraction.',
+        'Escalation signals from web_fetch: `escalationHint` present, JavaScript-required pages, empty extraction, SPA shell-only pages, boilerplate-only extraction, or bot-blocked responses (403/429/challenge pages).',
+        'Cost note: browser calls are typically ~10-100x slower/more expensive than web_fetch.',
+        'Browser extraction flow (for read/summarize requests): after `browser_navigate`, call `browser_snapshot` with `mode="full"` before deciding content is unavailable.',
+        'If snapshot content is incomplete, run `browser_scroll` and then `browser_snapshot` again (repeat a few times for long/lazy-loaded pages).',
+        'Do not use `browser_pdf` as a text-reading step; it is an export artifact, not a text extraction tool.',
+        '',
         '## Browser Auth Handling',
         'When the user explicitly asks for login/auth-flow testing, browser tools may be used on the requested site, including filling credentials and submitting forms.',
         'Do not invent blanket restrictions such as "browser tools are only for public/unauthenticated pages" unless an actual tool/policy error says so.',

package/dist/prompt-hooks.js.map

@@ -1 +1 @@
-{"version":3,"file":"prompt-hooks.js","sourceRoot":"","sources":["../src/prompt-hooks.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"prompt-hooks.js","sourceRoot":"","sources":["../src/prompt-hooks.ts"],"names":[],"mappings":"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"}

package/dist/runtime-config.d.ts

@@ -11,6 +11,9 @@ export interface RuntimeSecurityConfig {
 export interface RuntimeConfig {
     version: number;
     security: RuntimeSecurityConfig;
+    skills: {
+        extraDirs: string[];
+    };
     discord: {
         prefix: string;
     };

package/dist/runtime-config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime-config.d.ts","sourceRoot":"","sources":["../src/runtime-config.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"runtime-config.d.ts","sourceRoot":"","sources":["../src/runtime-config.ts"],"names":[],"mappings":"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"}

package/dist/runtime-config.js

@@ -14,6 +14,9 @@ const DEFAULT_RUNTIME_CONFIG = {
         trustModelVersion: '',
         trustModelAcceptedBy: '',
     },
+    skills: {
+        extraDirs: [],
+    },
     discord: {
         prefix: '!claw',
     },
@@ -201,6 +204,7 @@ function readLegacyEnvPatch() {
     const env = process.env;
     const patch = {
         discord: {},
+        skills: {},
         hybridai: {},
         container: {},
         heartbeat: {},
@@ -217,6 +221,7 @@ function readLegacyEnvPatch() {
         },
     };
     const discord = patch.discord;
+    const skills = patch.skills;
     const hybridai = patch.hybridai;
     const container = patch.container;
     const heartbeat = patch.heartbeat;
@@ -230,6 +235,8 @@ function readLegacyEnvPatch() {
     const proactiveAutoRetry = proactive.autoRetry;
     if (env.DISCORD_PREFIX != null)
         discord.prefix = env.DISCORD_PREFIX;
+    if (env.SKILLS_EXTRA_DIRS != null)
+        skills.extraDirs = env.SKILLS_EXTRA_DIRS;
     if (env.HYBRIDAI_BASE_URL != null)
         hybridai.baseUrl = env.HYBRIDAI_BASE_URL;
     if (env.HYBRIDAI_MODEL != null)
@@ -349,6 +356,7 @@ function readLegacyEnvPatch() {
 function normalizeRuntimeConfig(patch) {
     const raw = patch ?? {};
     const rawSecurity = isRecord(raw.security) ? raw.security : {};
+    const rawSkills = isRecord(raw.skills) ? raw.skills : {};
     const rawDiscord = isRecord(raw.discord) ? raw.discord : {};
     const rawHybridAi = isRecord(raw.hybridai) ? raw.hybridai : {};
     const rawContainer = isRecord(raw.container) ? raw.container : {};
@@ -381,6 +389,9 @@ function normalizeRuntimeConfig(patch) {
             trustModelVersion: normalizeString(rawSecurity.trustModelVersion, DEFAULT_RUNTIME_CONFIG.security.trustModelVersion, { allowEmpty: true }),
             trustModelAcceptedBy: normalizeString(rawSecurity.trustModelAcceptedBy, DEFAULT_RUNTIME_CONFIG.security.trustModelAcceptedBy, { allowEmpty: true }),
         },
+        skills: {
+            extraDirs: normalizeStringArray(rawSkills.extraDirs, DEFAULT_RUNTIME_CONFIG.skills.extraDirs),
+        },
         discord: {
             prefix: normalizeString(rawDiscord.prefix, DEFAULT_RUNTIME_CONFIG.discord.prefix, { allowEmpty: false }),
         },
@@ -656,7 +667,12 @@ function migrateConfigSchemaOnStartup() {
     try {
         writeConfigFile(migrated);
         const from = previousVersion == null ? 'unknown' : String(previousVersion);
-        console.info(`[runtime-config] migrated config schema from v${from} to v${CONFIG_VERSION}`);
+        if (previousVersion !== CONFIG_VERSION) {
+            console.info(`[runtime-config] migrated config schema from v${from} to v${CONFIG_VERSION}`);
+        }
+        else {
+            console.info(`[runtime-config] normalized config schema v${CONFIG_VERSION} (filled defaults/canonicalized values)`);
+        }
     }
     catch (err) {
         console.warn(`[runtime-config] schema migration failed: ${err instanceof Error ? err.message : String(err)}`);