@iowarp/clio-coder 0.4.9 → 0.5.0

package/dist/chunk-TGWZXJ7L.js

@@ -0,0 +1,1205 @@
+import { createRequire as __clioCreateRequire } from "node:module"; const require = __clioCreateRequire(import.meta.url);
+import {
+  SETTING_CONTROLS
+} from "./chunk-VOYUCAQF.js";
+import {
+  buildRecallFields,
+  recallErrorMessage,
+  recallParentTurnId,
+  recallableRefListing,
+  resolveRecall
+} from "./chunk-EG4ARXPC.js";
+import {
+  foldWorkingSet
+} from "./chunk-EZD2BXGP.js";
+import {
+  getAtPath
+} from "./chunk-GGWI3OVM.js";
+import {
+  resolveSettingsSection,
+  settingsSectionForPath
+} from "./chunk-LJRBX7QR.js";
+import {
+  checkSkillDrift
+} from "./chunk-4WOOTKFD.js";
+import {
+  discoverMarketplaceSkills,
+  installedSkillNames,
+  installedSkillPackages,
+  loadSkills,
+  modelVisibleSkills
+} from "./chunk-LAR7DX5E.js";
+import {
+  contextToolSurface
+} from "./chunk-CTFPFW3H.js";
+import {
+  OBSERVE_SELF_CAPS,
+  finalizeObservation,
+  observationBudgetExhausted,
+  reserveObservation
+} from "./chunk-OPD7GL6F.js";
+import {
+  truncateHead
+} from "./chunk-GHXGMFQ5.js";
+import {
+  SKILL_INSTALL_OFFER_OPTION_NEVER,
+  SKILL_INSTALL_OFFER_OPTION_NOT_NOW,
+  SKILL_INSTALL_OFFER_OPTION_PROJECT,
+  SKILL_INSTALL_OFFER_OPTION_USER,
+  SKILL_SUGGESTION_ANCHOR
+} from "./chunk-I4Y4WKZR.js";
+import {
+  ToolNames
+} from "./chunk-V4XJWDHR.js";
+import {
+  resolvePackageRoot
+} from "./chunk-ZPST2KQO.js";
+import {
+  init_esm_shims
+} from "./chunk-ECBHH7LU.js";
+
+// src/tools/context/index.ts
+init_esm_shims();
+import { readdirSync as readdirSync2 } from "node:fs";
+import path from "node:path";
+
+// src/core/settings-awareness.ts
+init_esm_shims();
+var AUTONOMY_HELP = {
+  "read-only": "Inspect the workspace and answer questions. Edits, execution, and dispatch are refused.",
+  suggest: "Inspect freely; ask before edits, execution, or dispatch. Useful when reviewing an unfamiliar project.",
+  "auto-edit": "Edit the workspace, run recognized checks, and delegate routine work without repeated approval. Ask for unfamiliar commands, reads outside the workspace, declared outward actions, and larger dispatch plans. Safety rules still apply.",
+  "full-auto": "Skip autonomy approvals, including unfamiliar commands and outward actions. Safety rules can still block or require approval. Choose this only for work you are prepared to let run unattended."
+};
+function describeSettingsPosture(settings) {
+  const worker = settings.fleet.permissions.mode === "escalate" ? "Workers ask you when a call needs approval; unanswered requests follow the configured timeout and fallback." : settings.fleet.permissions.mode === "fail" ? "Workers stop their run when a call needs approval." : "Workers follow their allowed tool and safety policy; a call needing approval is denied and the worker can continue with allowed work.";
+  const budget = settings.safety.limits.sessionCostUsd === 0 ? "Tracked spending has no session ceiling." : `Tracked session spending is capped at $${settings.safety.limits.sessionCostUsd}; unknown provider prices are not a guaranteed dollar limit.`;
+  return `${AUTONOMY_HELP[settings.safety.autonomy]} ${worker} ${budget}`;
+}
+var SAFE_STRING_VALUES = /* @__PURE__ */ new Set([
+  "chat.target",
+  "chat.model",
+  "fleet.default.target",
+  "fleet.default.model",
+  "context.memory.target",
+  "context.memory.model",
+  "fleet.concurrency"
+]);
+function settingsAwareness(settings, query = "", offset = 0, limit = 12) {
+  const area = resolveSettingsSection(query);
+  const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
+  const controls = SETTING_CONTROLS.map((control, index) => {
+    const text = `${control.path} ${control.label} ${control.description}`.toLowerCase();
+    const score = terms.filter((term) => text.includes(term)).length;
+    return { control, index, score };
+  }).filter(
+    ({ control, score }) => area ? settingsSectionForPath(control.path) === area : terms.length === 0 || score > 0
+  ).sort((a, b) => area ? a.index - b.index : b.score - a.score || a.index - b.index).map(({ control }) => control);
+  const route = (value) => ({
+    target: value.target ?? null,
+    model: value.model ?? null,
+    thinkingLevel: value.thinkingLevel,
+    ...value.node ? { node: value.node } : {}
+  });
+  const rows = controls.slice(offset, offset + limit).map((control) => {
+    const disclose = control.kind === "number" || control.kind === "boolean" || Boolean(control.choices) || SAFE_STRING_VALUES.has(control.path);
+    return {
+      path: control.path,
+      label: control.label,
+      description: control.description,
+      ...disclose ? { value: getAtPath(settings, control.path) ?? null } : { valueOmitted: "Free-form or structured value; inspect through the user settings UI." },
+      ...control.choices ? { choices: control.choices } : {},
+      tui: `/settings ${settingsSectionForPath(control.path)}`,
+      cli: `clio-coder configure --section ${settingsSectionForPath(control.path)}`
+    };
+  });
+  return {
+    scope: "effective settings for the running session; includes its overrides",
+    routing: {
+      chat: route(settings.chat),
+      fleetDefault: route(settings.fleet.default),
+      profiles: Object.fromEntries(Object.entries(settings.fleet.profiles).map(([name, value]) => [name, route(value)])),
+      agentProfiles: { ...settings.fleet.agentProfiles },
+      targets: settings.targets.map((target) => ({
+        id: target.id,
+        runtime: target.runtime,
+        defaultModel: target.defaultModel ?? null
+      })),
+      note: "These are configured routes, not backend health or a guarantee of a particular dispatch. Shadow helpers use fleet routing; do not substitute the chat model for the fleet default. Agent/profile bindings, explicit requests, recipe requirements and admission can affect a run. Null means not explicitly configured, not inheritance from chat."
+    },
+    posture: describeSettingsPosture(settings),
+    limits: {
+      sessionCostUsd: settings.safety.limits.sessionCostUsd,
+      chatToolCallsPerTurn: settings.safety.limits.chatToolCallsPerTurn,
+      workerToolCallsPerRun: settings.fleet.limits.toolCallsPerRun,
+      workerPermissionMode: settings.fleet.permissions.mode,
+      concurrency: settings.fleet.concurrency
+    },
+    note: "Answer current-configuration questions from this live snapshot; documentation describes behavior, not this session\u2019s configured values. For zero search matches, retry this settings scope with a short key or no query instead of reading whole guides. These are configured ceilings, not remaining budgets. This read changes nothing. Guide the user to the listed UI controls; do not edit settings files or relax safety, trust, credentials, or spending limits to get past a denial. /settings supports session-only changes where available; configure saves global defaults.",
+    rows,
+    total: controls.length,
+    nextOffset: offset + rows.length < controls.length ? offset + rows.length : null
+  };
+}
+
+// src/tools/context/docs-engine.ts
+init_esm_shims();
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { basename, join, relative, resolve } from "node:path";
+var DEFAULT_LIMIT = 5;
+var MAX_LIMIT = 12;
+var SNIPPET_MAX = 360;
+var SNIPPET_CONTEXT_LINES = 2;
+var BODY_K1 = 1.2;
+var BODY_B = 0.75;
+var HEADING_WEIGHT = 3.5;
+var TITLE_WEIGHT = 2;
+var PHRASE_BODY_BOOST = 3;
+var PHRASE_HEADING_BOOST = 7;
+var COVERAGE_BOOST = 4;
+var EXPANDED_TERM_WEIGHT = 0.45;
+var NONCURRENT_REFERENCE_WEIGHT = 0.25;
+var NONCURRENT_REFERENCE_PATH = /^docs\/(?:history\/|gui\/(?!readme\.md$)|process\/[^/]*(?:proposal|audit-v\d|battletest-\d{4})[^/]*\.md$)/iu;
+var EXPLICIT_NONCURRENT_INTENT = /\b(?:histor(?:y|ical|ic)|archives?|archived|proposal|proposed|blueprints?|design|spec(?:ification)?s?|roadmaps?|audits?|legacy|previous|older|old)\b/iu;
+var STOP_WORDS = /* @__PURE__ */ new Set([
+  "a",
+  "an",
+  "and",
+  "are",
+  "as",
+  "at",
+  "be",
+  "by",
+  "can",
+  "for",
+  "from",
+  "how",
+  "in",
+  "into",
+  "is",
+  "it",
+  "of",
+  "on",
+  "or",
+  "that",
+  "the",
+  "this",
+  "to",
+  "what",
+  "when",
+  "where",
+  "with"
+]);
+var VOCABULARY_ALIASES = [
+  {
+    triggers: ["approval", "confirm", "confirmation", "deny", "permission", "permissions", "prompt"],
+    expansions: ["autonomy", "ask", "deny", "safety", "policy", "full-auto", "read-only"]
+  },
+  {
+    triggers: ["agent", "agents", "dispatch", "fleet", "worker", "workers", "run"],
+    expansions: ["agent", "dispatch", "fleet", "profile", "worker", "receipt", "run"]
+  },
+  {
+    triggers: ["model", "models", "provider", "runtime", "target", "targets", "endpoint"],
+    expansions: ["catalog", "model", "probe", "provider", "runtime", "target", "wireModels"]
+  },
+  {
+    triggers: ["auth", "credential", "credentials", "login", "oauth", "subscription"],
+    expansions: ["auth", "credential", "login", "oauth", "target", "runtime"]
+  },
+  {
+    triggers: ["memory", "evidence", "receipt", "receipts", "audit", "accountability", "provenance"],
+    expansions: ["accountability", "evidence", "findings", "memory", "receipt", "run", "audit"]
+  },
+  {
+    triggers: ["validate", "validated", "validation", "verify", "verified", "test", "tests", "rigor"],
+    expansions: ["validation", "verify", "evidence", "rigor", "finish", "contract", "check"]
+  },
+  {
+    triggers: ["bash", "command", "commands", "shell", "terminal", "tool", "tools"],
+    expansions: ["bash", "command", "tool", "registry", "safety", "result", "cap"]
+  },
+  {
+    triggers: ["context", "compact", "compaction", "token", "tokens", "cache", "prompt"],
+    expansions: ["context", "compaction", "prompt", "token", "cache", "window"]
+  },
+  {
+    triggers: ["hook", "hooks", "middleware", "component", "components", "budget"],
+    expansions: ["middleware", "hook", "effect", "component", "budget", "registration"]
+  },
+  {
+    triggers: ["install", "upgrade", "uninstall", "doctor", "lifecycle", "reset", "paths"],
+    expansions: ["install", "lifecycle", "doctor", "reset", "state", "config", "paths"]
+  },
+  {
+    triggers: ["skill", "skills", "marketplace"],
+    expansions: ["skill", "skills", "marketplace", "discovery", "context"]
+  },
+  {
+    triggers: ["docs", "documentation", "manual", "self"],
+    expansions: ["documentation", "docs", "context", "blueprint", "guide"]
+  }
+];
+var cachedIndex = null;
+function normalizeText(text) {
+  return text.toLowerCase().replace(/[`'"’]/g, "").replace(/[^a-z0-9]+/g, " ").replace(/\s+/g, " ").trim();
+}
+function rawTokens(text) {
+  return normalizeText(text).split(" ").filter(Boolean);
+}
+function stemToken(token) {
+  if (token.length <= 3) return token;
+  if (token.endsWith("ies") && token.length > 4) return `${token.slice(0, -3)}y`;
+  if (token.endsWith("ing") && token.length > 5) return token.slice(0, -3);
+  if (token.endsWith("ed") && token.length > 4) return token.slice(0, -2);
+  if (token.endsWith("es") && token.length > 4) return token.slice(0, -2);
+  if (token.endsWith("s") && token.length > 4) return token.slice(0, -1);
+  return token;
+}
+function tokenize(text, options = {}) {
+  const tokens = rawTokens(text).map(stemToken);
+  return options.keepStopWords ? tokens : tokens.filter((token) => !STOP_WORDS.has(token));
+}
+function countTerms(tokens) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const token of tokens) counts.set(token, (counts.get(token) ?? 0) + 1);
+  return counts;
+}
+function unique(items) {
+  return [...new Set(items)];
+}
+function slugify(heading, counts) {
+  const base = heading.replace(/<[^>]*>/g, "").replace(/[`*_~]/g, "").toLowerCase().replace(/[^\p{L}\p{N}_\s-]/gu, "").replace(/\s/g, "-");
+  const count = counts.get(base) ?? 0;
+  counts.set(base, count + 1);
+  return count > 0 ? `${base}-${count}` : base;
+}
+function titleFromFile(name) {
+  return basename(name, ".md").split(/[-_]+/).filter(Boolean).map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join(" ");
+}
+function parseSections(file, markdown) {
+  const lines = markdown.split(/\r?\n/);
+  const sections = [];
+  let title = titleFromFile(file);
+  let heading = "(overview)";
+  let level = 0;
+  let headingLine = 1;
+  let bodyStartLine = 1;
+  let buffer = [];
+  let inFence = false;
+  const stack = [];
+  const headingCounts = /* @__PURE__ */ new Map();
+  const breadcrumbFor = () => {
+    const parts = stack.map((entry) => entry.text);
+    if (heading === "(overview)") return title;
+    return parts.length > 0 ? parts.join(" > ") : heading;
+  };
+  const flush = (endLine) => {
+    const body = buffer.join("\n").trim();
+    if (body.length > 0 || heading !== "(overview)") {
+      sections.push({
+        file,
+        title,
+        heading,
+        breadcrumb: breadcrumbFor(),
+        level,
+        anchor: heading === "(overview)" ? "" : `#${slugify(heading, headingCounts)}`,
+        startLine: headingLine,
+        bodyStartLine,
+        endLine: Math.max(headingLine, endLine),
+        body,
+        bodyLines: [...buffer]
+      });
+    }
+    buffer = [];
+  };
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i] ?? "";
+    if (/^\s*(```|~~~)/.test(line)) inFence = !inFence;
+    const headingMatch = inFence ? null : /^(#{1,6})\s+(.+?)\s*#*\s*$/.exec(line);
+    if (headingMatch) {
+      flush(i);
+      level = (headingMatch[1] ?? "").length;
+      heading = (headingMatch[2] ?? "").trim();
+      if (level === 1) title = heading;
+      while (stack.length > 0 && (stack[stack.length - 1]?.level ?? 0) >= level) stack.pop();
+      stack.push({ level, text: heading });
+      headingLine = i + 1;
+      bodyStartLine = i + 2;
+      continue;
+    }
+    buffer.push(line);
+  }
+  flush(lines.length);
+  return sections;
+}
+function indexSection(section) {
+  const headingText = `${section.title} ${section.breadcrumb} ${section.heading}`;
+  const bodyTokens = tokenize(section.body);
+  const headingTokens = tokenize(headingText);
+  const titleTokens = tokenize(section.title);
+  const bodyCounts = countTerms(bodyTokens);
+  const headingCounts = countTerms(headingTokens);
+  const titleCounts = countTerms(titleTokens);
+  const terms = /* @__PURE__ */ new Set([...bodyCounts.keys(), ...headingCounts.keys(), ...titleCounts.keys()]);
+  return {
+    ...section,
+    bodyCounts,
+    headingCounts,
+    titleCounts,
+    bodyLength: Math.max(1, bodyTokens.length),
+    terms,
+    normalizedBody: normalizeText(section.body),
+    normalizedHeading: normalizeText(headingText)
+  };
+}
+function candidateDocFiles(root) {
+  const docsDir = join(root, "docs");
+  const htmlDir = join(docsDir, "html");
+  const files = [];
+  const walk = (dir) => {
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries.sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0)) {
+      const absolute = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (absolute !== htmlDir) walk(absolute);
+        continue;
+      }
+      if (entry.isFile() && entry.name.toLowerCase().endsWith(".md")) {
+        files.push(relative(root, absolute).replaceAll("\\", "/"));
+      }
+    }
+  };
+  walk(docsDir);
+  for (const name of ["README.md", "CHANGELOG.md", "CLIO-CODER.md"]) {
+    if (existsSync(join(root, name))) files.push(name);
+  }
+  return files;
+}
+function buildDocumentFrequency(sections) {
+  const df = /* @__PURE__ */ new Map();
+  for (const section of sections) {
+    for (const term of section.terms) df.set(term, (df.get(term) ?? 0) + 1);
+  }
+  return df;
+}
+function loadDocsIndex() {
+  let root;
+  try {
+    const override = process.env.CLIO_CODER_PACKAGE_ROOT?.trim();
+    if (override) {
+      root = resolve(override);
+    } else {
+      root = resolvePackageRoot();
+    }
+  } catch (err) {
+    return { ok: false, message: err instanceof Error ? err.message : String(err) };
+  }
+  const docsDir = join(root, "docs");
+  if (cachedIndex && cachedIndex.dir === docsDir) return { ok: true, index: cachedIndex };
+  const files = candidateDocFiles(root);
+  if (files.length === 0) return { ok: false, message: `bundled docs directory not found at ${docsDir}` };
+  const sections = [];
+  const indexedFiles = [];
+  let docCount = 0;
+  for (const file of files) {
+    let raw;
+    try {
+      raw = readFileSync(join(root, file), "utf8");
+    } catch {
+      continue;
+    }
+    docCount += 1;
+    indexedFiles.push(file);
+    for (const section of parseSections(file, raw)) sections.push(indexSection(section));
+  }
+  if (sections.length === 0) return { ok: false, message: `no markdown sections found under ${docsDir}` };
+  const totalLength = sections.reduce((sum, section) => sum + section.bodyLength, 0);
+  cachedIndex = {
+    dir: docsDir,
+    files: indexedFiles,
+    sections,
+    docCount,
+    avgBodyLength: totalLength / sections.length,
+    documentFrequency: buildDocumentFrequency(sections)
+  };
+  return { ok: true, index: cachedIndex };
+}
+function makeQueryPlan(query) {
+  const originalTokens = unique(tokenize(query));
+  const originalSet = new Set(originalTokens);
+  const expanded = [];
+  for (const rule of VOCABULARY_ALIASES) {
+    const triggerTokens = rule.triggers.flatMap((trigger) => tokenize(trigger));
+    if (!triggerTokens.some((token) => originalSet.has(token))) continue;
+    expanded.push(...rule.expansions.flatMap((term) => tokenize(term)));
+  }
+  const expandedTerms = unique(expanded).filter((term) => !originalSet.has(term));
+  const weightedTerms = [
+    ...originalTokens.map((term) => ({ term, source: "query", weight: 1 })),
+    ...expandedTerms.map((term) => ({ term, source: "alias", weight: EXPANDED_TERM_WEIGHT }))
+  ];
+  const normalizedQuery = normalizeText(query);
+  const phraseCandidates = [
+    normalizedQuery,
+    ...rawTokens(query).slice(0, -1).map((token, index, tokens) => `${token} ${tokens[index + 1] ?? ""}`.trim())
+  ];
+  const phrases = unique(phraseCandidates.filter((phrase) => phrase.includes(" ") && phrase.length >= 5));
+  return { query, originalTokens, weightedTerms, expandedTerms, phrases };
+}
+function idf(index, term) {
+  const df = index.documentFrequency.get(term) ?? 0;
+  return Math.log(1 + (index.sections.length - df + 0.5) / (df + 0.5));
+}
+function bm25(count, sectionLength, avgLength) {
+  if (count <= 0) return 0;
+  return count * (BODY_K1 + 1) / (count + BODY_K1 * (1 - BODY_B + BODY_B * (sectionLength / avgLength)));
+}
+function phraseSignals(section, phrases) {
+  let score = 0;
+  const signals = [];
+  for (const phrase of phrases) {
+    if (section.normalizedHeading.includes(phrase)) {
+      score += PHRASE_HEADING_BOOST;
+      signals.push(`heading phrase: ${phrase}`);
+    }
+    if (section.normalizedBody.includes(phrase)) {
+      score += PHRASE_BODY_BOOST;
+      signals.push(`body phrase: ${phrase}`);
+    }
+  }
+  return { score, signals };
+}
+function scoreSection(index, section, plan) {
+  let score = 0;
+  const matchedTerms = [];
+  const signals = [];
+  let originalHits = 0;
+  for (const weighted of plan.weightedTerms) {
+    const bodyCount = section.bodyCounts.get(weighted.term) ?? 0;
+    const headingCount = section.headingCounts.get(weighted.term) ?? 0;
+    const titleCount = section.titleCounts.get(weighted.term) ?? 0;
+    if (bodyCount + headingCount + titleCount === 0) continue;
+    const termIdf = idf(index, weighted.term);
+    const bodyScore = termIdf * bm25(bodyCount, section.bodyLength, index.avgBodyLength);
+    const headingScore = headingCount > 0 ? termIdf * HEADING_WEIGHT : 0;
+    const titleScore = titleCount > 0 ? termIdf * TITLE_WEIGHT : 0;
+    score += weighted.weight * (bodyScore + headingScore + titleScore);
+    matchedTerms.push(weighted.term);
+    if (weighted.source === "query") originalHits += 1;
+    if (headingCount > 0) signals.push(`heading: ${weighted.term}`);
+    else if (titleCount > 0) signals.push(`title: ${weighted.term}`);
+  }
+  const phrases = phraseSignals(section, plan.phrases);
+  score += phrases.score;
+  signals.push(...phrases.signals);
+  const coverage = plan.originalTokens.length === 0 ? 0 : originalHits / plan.originalTokens.length;
+  score += coverage * COVERAGE_BOOST;
+  if (score <= 0) return null;
+  return {
+    section,
+    score,
+    matchedTerms: unique(matchedTerms).slice(0, 12),
+    signals: unique(signals).slice(0, 6),
+    coverage
+  };
+}
+function prioritizeCurrentGuidance(entry, query) {
+  if (!NONCURRENT_REFERENCE_PATH.test(entry.section.file) || EXPLICIT_NONCURRENT_INTENT.test(query)) return entry;
+  return {
+    ...entry,
+    score: entry.score * NONCURRENT_REFERENCE_WEIGHT,
+    signals: unique(["historical/design reference demotion", ...entry.signals]).slice(0, 6)
+  };
+}
+function cleanSnippet(text) {
+  return text.replace(/^\s{0,3}#{1,6}\s+/gm, "").replace(/\[([^\]]+)\]\([^)]+\)/g, "$1").replace(/`([^`]+)`/g, "$1").replace(/\s+/g, " ").trim();
+}
+function snippetFor(section, plan) {
+  const needles = unique([...plan.phrases, ...plan.originalTokens, ...plan.expandedTerms.slice(0, 8)]).filter(
+    (needle) => needle.length > 0
+  );
+  let hitLine = -1;
+  let bestNeedleCount = 0;
+  for (let i = 0; i < section.bodyLines.length; i += 1) {
+    const normalized = normalizeText(section.bodyLines[i] ?? "");
+    let needleCount = 0;
+    for (const needle of needles) {
+      if (normalized.includes(needle)) needleCount += 1;
+    }
+    if (needleCount > bestNeedleCount) {
+      bestNeedleCount = needleCount;
+      hitLine = i;
+    }
+  }
+  if (hitLine < 0) hitLine = section.bodyLines.findIndex((line) => line.trim().length > 0);
+  if (hitLine < 0) {
+    return {
+      text: section.heading === "(overview)" ? section.title : section.heading,
+      startLine: section.startLine,
+      endLine: section.startLine
+    };
+  }
+  const from = Math.max(0, hitLine - SNIPPET_CONTEXT_LINES);
+  const to = Math.min(section.bodyLines.length - 1, hitLine + SNIPPET_CONTEXT_LINES);
+  let snippet = cleanSnippet(section.bodyLines.slice(from, to + 1).join(" "));
+  if (snippet.length > SNIPPET_MAX) snippet = `${snippet.slice(0, SNIPPET_MAX - 3).trimEnd()}...`;
+  return {
+    text: snippet,
+    startLine: section.bodyStartLine + from,
+    endLine: section.bodyStartLine + to
+  };
+}
+function clampDocsLimit(value) {
+  if (typeof value === "number" && Number.isFinite(value) && value > 0) return Math.min(Math.floor(value), MAX_LIMIT);
+  return DEFAULT_LIMIT;
+}
+function resultPayload(index, plan, scored) {
+  const results = scored.map((entry, i) => {
+    const snippet = snippetFor(entry.section, plan);
+    return {
+      rank: i + 1,
+      file: entry.section.file,
+      heading: entry.section.heading,
+      breadcrumb: entry.section.breadcrumb,
+      anchor: entry.section.anchor,
+      lines: { start: entry.section.startLine, end: entry.section.endLine },
+      snippetLines: { start: snippet.startLine, end: snippet.endLine },
+      snippet: snippet.text,
+      score: Number(entry.score.toFixed(3)),
+      coverage: Number(entry.coverage.toFixed(2)),
+      matchedTerms: entry.matchedTerms,
+      signals: entry.signals
+    };
+  });
+  return {
+    version: 2,
+    query: plan.query,
+    corpus: {
+      docs: index.docCount,
+      sections: index.sections.length,
+      files: index.files,
+      excludes: ["docs/html/**"]
+    },
+    terms: {
+      query: plan.originalTokens,
+      expanded: plan.expandedTerms,
+      phrases: plan.phrases
+    },
+    resultCount: results.length,
+    results,
+    followUp: results.length > 0 ? `Cited files are Clio's bundled docs: read them from the installed documentation path named in your prompt, never by searching the workspace for them. For more depth, call gateway(op="call", capability="clio_docs", args={query:"<more specific terms>"}).` : "Try Clio vocabulary such as target, autonomy, dispatch, evidence, middleware, context, validation, install, or model catalog."
+  };
+}
+function listDocsCorpus() {
+  const loaded = loadDocsIndex();
+  if (!loaded.ok) return { ok: false, message: loaded.message };
+  const index = loaded.index;
+  const payload = {
+    version: 2,
+    corpus: {
+      docs: index.docCount,
+      sections: index.sections.length,
+      files: index.files,
+      excludes: ["docs/html/**"]
+    },
+    followUp: 'Call gateway(op="call", capability="clio_docs", args={query:"<terms>"}) to search these bundled docs; omit query to list the corpus. They ship with Clio and are not workspace files. Try Clio vocabulary such as target, autonomy, dispatch, evidence, middleware, context, validation, install, or model catalog.'
+  };
+  return { ok: true, payload, fileCount: index.files.length };
+}
+function searchDocs(query, limitArg) {
+  const plan = makeQueryPlan(query);
+  if (plan.originalTokens.length === 0) return { ok: false, message: "query has no searchable terms" };
+  const loaded = loadDocsIndex();
+  if (!loaded.ok) return { ok: false, message: loaded.message };
+  const limit = clampDocsLimit(limitArg);
+  const ranked = loaded.index.sections.map((section) => {
+    const scored = scoreSection(loaded.index, section, plan);
+    return scored === null ? null : prioritizeCurrentGuidance(scored, query);
+  }).filter((entry) => entry !== null).sort(
+    (a, b) => b.score - a.score || b.coverage - a.coverage || a.section.file.localeCompare(b.section.file) || a.section.startLine - b.section.startLine || a.section.heading.localeCompare(b.section.heading)
+  );
+  const shown = ranked.slice(0, limit);
+  const next = shown.length === 0 ? `query=${plan.expandedTerms[0] ?? "overview"}` : null;
+  const payload = {
+    ...resultPayload(loaded.index, plan, shown),
+    omitted: ranked.length - shown.length,
+    ...next !== null ? { next } : {}
+  };
+  return { ok: true, payload, resultCount: shown.length, rankedTotal: ranked.length, next };
+}
+
+// src/tools/context/index.ts
+var DEFAULT_TREE_ENTRIES = 50;
+function cwdFromDeps(deps) {
+  return deps?.getCwd?.() ?? process.cwd();
+}
+function buildResourceTree(baseDir, maxEntries) {
+  const out = [];
+  const walk = (dir) => {
+    if (out.length >= maxEntries) return;
+    let entries;
+    try {
+      entries = readdirSync2(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (out.length >= maxEntries) return;
+      if (entry.name.startsWith(".") || entry.name === "node_modules") continue;
+      const full = path.join(dir, entry.name);
+      const rel = path.relative(baseDir, full).split(path.sep).join("/");
+      if (entry.isDirectory()) {
+        out.push(`${rel}/`);
+        walk(full);
+      } else if (entry.isFile()) {
+        out.push(rel);
+      }
+    }
+  };
+  walk(baseDir);
+  return out;
+}
+function skillSourceOrigin(skill) {
+  return skill.sourceInfo.source ?? `${skill.source}-${skill.scope}`;
+}
+function skillExecutionFrame(skill, workspaceRoot) {
+  return [
+    "How to read this skill:",
+    `- Workspace root: ${workspaceRoot}. Run every command and resolve every repository path there. ${skill.baseDir} holds only this skill's own resource files; it is never the working directory.`,
+    "- This skill may name tools, subagents, or commands from another harness. Use Clio's equivalent from your own tool list; if there is no equivalent, say so and continue without that step. Never invent one, and never substitute repeated calls to a different agent for an agent the skill named.",
+    "- The skill describes a workflow. Your safety policy, permissions, and tool surface still bind it.",
+    ""
+  ];
+}
+function renderSkillBody(skill, tree) {
+  const sourceOrigin = skillSourceOrigin(skill);
+  const lines = [
+    `<skill name="${skill.name}" scope="${skill.scope}" source="${skill.source}" origin="${sourceOrigin}" hash="${skill.hash}">`,
+    `path: ${skill.filePath}`,
+    `base_dir: ${skill.baseDir}`,
+    `source_origin: ${sourceOrigin}`,
+    `disable_model_invocation: ${skill.disableModelInvocation}`
+  ];
+  if (skill.allowedTools) lines.push(`allowed_tools: ${skill.allowedTools.join(", ")}`);
+  if (skill.disallowedTools) lines.push(`disallowed_tools: ${skill.disallowedTools.join(", ")}`);
+  if (skill.diagnostics.length > 0) {
+    lines.push(`diagnostics: ${skill.diagnostics.map((d) => d.message).join("; ")}`);
+  }
+  const metadataKeys = Object.keys(skill.metadata);
+  if (metadataKeys.length > 0) lines.push(`metadata: ${metadataKeys.join(", ")}`);
+  if (tree) {
+    lines.push("resources:");
+    for (const entry of tree) lines.push(`  ${entry}`);
+  }
+  lines.push("", skill.content, "</skill>");
+  return lines.join("\n");
+}
+function policyIsRecipeBound(policy) {
+  return policy.requests.length > 0 && policy.requests.every((request) => request.source === "recipe");
+}
+var NO_PENDING_SKILL_DENIAL = `context: no pending skill request is active this turn; only the operator can activate a skill, so do not retry this load. If a listed skill matches the task, open your reply with the line \`${SKILL_SUGGESTION_ANCHOR}\` and continue the task without it; only the operator can run it. Otherwise continue without skills.`;
+function pendingSkillPolicyError(name, options) {
+  const policy = options?.pendingSkillPolicy;
+  if (!policy) {
+    return NO_PENDING_SKILL_DENIAL;
+  }
+  const recipeBound = policyIsRecipeBound(policy);
+  if (policy.modelActivation === true && !recipeBound) {
+    if (!policy.loadedSkillNames.has(name)) return null;
+    const window = policy.carriedSurface === true ? "in this session" : "this turn";
+    return `context: skill ${name} already loaded ${window}; continue with the loaded workflow and call ask_user if an interview/choice is needed.`;
+  }
+  const allowed = [...new Set(policy.allowedSkillNames.map((entry) => entry.trim()).filter(Boolean))];
+  if (allowed.length === 0) {
+    return NO_PENDING_SKILL_DENIAL;
+  }
+  if (!allowed.includes(name)) {
+    if (recipeBound) return `context: this agent run may load only its declared skill(s): ${allowed.join(", ")}.`;
+    if (policy.carriedSurface === true) return NO_PENDING_SKILL_DENIAL;
+    return `context: this turn has pending skill request(s): ${allowed.join(", ")}. Load only those before doing anything else.`;
+  }
+  if (policy.loadedSkillNames.has(name)) {
+    if (recipeBound) return `context: skill ${name} is already loaded in this run; continue with its workflow.`;
+    const window = policy.carriedSurface === true ? "in this session" : "this turn";
+    return `context: pending skill ${name} already loaded ${window}; continue with the loaded workflow and call ask_user if an interview/choice is needed.`;
+  }
+  return null;
+}
+function pendingSkillRequestFor(name, options) {
+  return options?.pendingSkillPolicy?.requests.find((request) => request.name === name) ?? null;
+}
+function operatorRequestedManualSkill(skill, request) {
+  return skill.trusted && skill.disableModelInvocation && request?.installed === true && (request.source === "slash-command" || request.source === "selector");
+}
+function renderPendingSkillTask(name, options) {
+  const request = pendingSkillRequestFor(name, options);
+  if (!request) return [];
+  if (request.source === "recipe") return [];
+  const task = request.args.trim();
+  const lines = [
+    "Pending skill request",
+    `name: ${request.name}`,
+    `source: ${request.source}`,
+    `task: ${task.length > 0 ? task : "(none supplied)"}`
+  ];
+  if (task.length > 0) {
+    lines.push(
+      "",
+      "Treat task as the user's starting subject for this skill workflow. Do not ask what the subject is again; ask_user only for missing follow-up decisions."
+    );
+  }
+  lines.push("");
+  return lines;
+}
+function marketplaceRowsFor(deps, installed, options) {
+  if (deps.skillMarketplace === false) return [];
+  if (deps.getSkillLoaderOptions?.().disableDiscovery === true) return [];
+  const policy = options?.pendingSkillPolicy;
+  if (policy && policyIsRecipeBound(policy)) return [];
+  const installedNames = installedSkillNames(installed, cwdFromDeps(deps));
+  try {
+    return discoverMarketplaceSkills({ cwd: cwdFromDeps(deps) }).skills.filter(
+      (entry) => !installedNames.has(entry.name)
+    );
+  } catch {
+    return [];
+  }
+}
+function renderSkillsList(skills, marketplace, marketplaceOffered, modelActivation, packages = []) {
+  if (skills.length === 0 && marketplace.length === 0 && packages.length === 0) {
+    return marketplaceOffered ? "No skills are available in Clio and no additional marketplace skills were found." : "No skills are available in Clio.";
+  }
+  const lines = ["Available skills.", ""];
+  const native = skills.filter((skill) => skill.source === "clio-coder" || skill.source === "plugin");
+  const discovered = skills.filter((skill) => skill.source !== "clio-coder" && skill.source !== "plugin");
+  lines.push(`Ready skills in Clio (${native.length}):`);
+  if (native.length === 0) lines.push("- none");
+  for (const skill of native) {
+    lines.push(`- ${skill.name} (source: ${skill.source}; scope: ${skill.scope}): ${skill.description}`);
+  }
+  if (discovered.length > 0) {
+    lines.push("", "Explicitly supplied session skills (not installed packages):");
+    for (const skill of discovered) {
+      lines.push(
+        `- ${skill.name} (source: ${skill.source}; scope: ${skill.scope}; file: ${skill.filePath}): ${skill.description}`
+      );
+    }
+    lines.push(
+      "These skills were explicitly supplied for this session. Preserve their source; session availability does not mean Clio installed or copied them."
+    );
+  }
+  if (packages.length > 0) {
+    lines.push("", `Installed packages providing skills (${packages.length}):`);
+    for (const pkg of packages)
+      lines.push(
+        `- ${pkg.name} (scope: ${pkg.scope}; origin: ${pkg.origin === "catalog" ? "marketplace catalog" : pkg.origin}; state: ${pkg.state}; path: ${pkg.path})`
+      );
+  }
+  lines.push(
+    "",
+    "Other-agent skill folders are discovery-only. Explicitly import into Clio before use; the trust-imports setting does not install or activate loose files."
+  );
+  if (marketplace.length > 0) {
+    lines.push("", "Marketplace (additional skills available to install; /skill <name> offers to install):");
+    for (const entry of marketplace) {
+      const category = entry.category ? ` [${entry.category}]` : "";
+      lines.push(`- ${entry.name}${category}: ${entry.description}`);
+    }
+  }
+  lines.push(
+    "",
+    modelActivation ? `If one skill above matches the current task, load it now with context(scope="skills", name="<name>") and continue in the same turn; at this autonomy level you activate installed skills yourself and do not wait for the operator. Marketplace additions still require operator approval. If none match, do not mention skills.` : `If one skill above matches the current task, begin your reply with the line \`${SKILL_SUGGESTION_ANCHOR}\` (a comma-separated sequence, in order, when several compose), then continue the task in the same turn without it; only the operator can run it. If none match, do not mention skills.`
+  );
+  if (marketplace.length > 0) {
+    lines.push(
+      `When no installed skill serves the task but a marketplace skill above genuinely does, you may instead ask the operator with ask_user (mode=single_question, header "Install skill") whether to install it, offering exactly: "${SKILL_INSTALL_OFFER_OPTION_PROJECT}", "${SKILL_INSTALL_OFFER_OPTION_USER}", "${SKILL_INSTALL_OFFER_OPTION_NOT_NOW}", "${SKILL_INSTALL_OFFER_OPTION_NEVER}". The harness handles those exact offer options. An explicit operator request or approval also authorizes the documented library install CLI. After installation, refresh the inventory; distinguish installed from ready and report /library reload when required.`
+    );
+  }
+  return lines.join("\n");
+}
+function runWorkspaceScope(deps, reservation, options) {
+  const workspace = deps.workspace;
+  if (!workspace?.hasSession()) {
+    return { kind: "error", message: "context: workspace scope requires a bound session; none is active here" };
+  }
+  let snap = workspace.getSnapshot();
+  if (!snap) {
+    snap = workspace.probeWorkspace();
+    workspace.saveSnapshot(snap);
+  }
+  const payload = {
+    ...withSkillsPointer(deps, snap),
+    ...deps.getSettings ? { configuration: 'For current autonomy, limits, and configuration guidance, call context(scope="settings").' } : {}
+  };
+  return finalizeObservation({
+    tool: ToolNames.Context,
+    unit: "results",
+    format: "json",
+    output: JSON.stringify(payload, null, 2),
+    shownCount: 1,
+    totalCount: 1,
+    truncated: false,
+    reservation,
+    ...options ? { options } : {}
+  });
+}
+function withSkillsPointer(deps, snap) {
+  let installed = 0;
+  let installable = 0;
+  try {
+    const list = loadSkills({ cwd: cwdFromDeps(deps), ...deps.getSkillLoaderOptions?.() ?? {} });
+    const visible = modelVisibleSkills(list.items);
+    installed = visible.length;
+    installable = marketplaceRowsFor(deps, visible, void 0).length;
+  } catch {
+    return { ...snap };
+  }
+  if (installed === 0 && installable === 0) return { ...snap };
+  return {
+    ...snap,
+    skills: `Skills: ${installed} available in Clio (ready workflows, not a marketplace installation count), ${installable} installable from the marketplace. If one matches this task, or the operator names a skill, list them with context(scope="skills") and suggest /skill <name> to the operator; load only on operator request.`
+  };
+}
+function runDocsScope(args, reservation, options, toolName = ToolNames.Context) {
+  const query = typeof args.query === "string" ? args.query.trim() : "";
+  if (query.length === 0) {
+    const corpus = listDocsCorpus();
+    if (!corpus.ok) return { kind: "error", message: `${toolName}: ${corpus.message}` };
+    return finalizeObservation({
+      tool: toolName,
+      unit: "entries",
+      format: "json",
+      output: JSON.stringify(corpus.payload),
+      shownCount: corpus.fileCount,
+      totalCount: corpus.fileCount,
+      truncated: false,
+      reservation,
+      ...options ? { options } : {}
+    });
+  }
+  const outcome = searchDocs(query, args.limit);
+  if (!outcome.ok) return { kind: "error", message: `${toolName}: ${outcome.message}` };
+  return finalizeObservation({
+    tool: toolName,
+    unit: "sections",
+    format: "json",
+    output: JSON.stringify(outcome.payload),
+    shownCount: outcome.resultCount,
+    totalCount: outcome.rankedTotal,
+    truncated: outcome.resultCount < outcome.rankedTotal,
+    ...outcome.next !== null ? { next: outcome.next } : {},
+    reservation,
+    ...options ? { options } : {}
+  });
+}
+function runSkillsScope(deps, args, reservation, options) {
+  const name = typeof args.name === "string" ? args.name.trim() : "";
+  if (name.length === 0) {
+    const list2 = loadSkills({ cwd: cwdFromDeps(deps), ...deps.getSkillLoaderOptions?.() ?? {} });
+    const visible2 = modelVisibleSkills(list2.items);
+    const marketplace = marketplaceRowsFor(deps, list2.items, options);
+    const packages = deps.skillMarketplace === false || deps.getSkillLoaderOptions?.().disableDiscovery === true ? [] : installedSkillPackages(
+      list2.items,
+      cwdFromDeps(deps),
+      deps.getSkillLoaderOptions?.().trustProjectCompatRoots === true
+    );
+    const rendered = renderSkillsList(
+      visible2,
+      marketplace,
+      deps.skillMarketplace !== false,
+      options?.pendingSkillPolicy?.modelActivation === true,
+      packages
+    );
+    const truncation2 = truncateHead(rendered, { maxBytes: reservation.callCapBytes, maxLines: Number.MAX_SAFE_INTEGER });
+    const total = visible2.length + marketplace.length + packages.length;
+    return finalizeObservation({
+      tool: ToolNames.Context,
+      unit: "entries",
+      output: truncation2.content,
+      ...truncation2.truncated ? { fullOutput: rendered } : {},
+      shownCount: total,
+      totalCount: total,
+      truncated: truncation2.truncated,
+      details: {
+        skills: visible2.map((skill2) => ({
+          name: skill2.name,
+          scope: skill2.scope,
+          source: skill2.source,
+          path: skill2.filePath
+        })),
+        installedPackages: packages,
+        marketplace: marketplace.map((entry) => ({
+          name: entry.name,
+          ...entry.category ? { category: entry.category } : {}
+        }))
+      },
+      reservation,
+      ...options ? { options } : {}
+    });
+  }
+  const policyError = pendingSkillPolicyError(name, options);
+  if (policyError) return { kind: "error", message: policyError };
+  const list = loadSkills({ cwd: cwdFromDeps(deps), ...deps.getSkillLoaderOptions?.() ?? {} });
+  const visible = modelVisibleSkills(list.items);
+  const pendingRequest = pendingSkillRequestFor(name, options);
+  const skill = visible.find((item) => item.name === name) ?? list.items.find((item) => item.name === name && operatorRequestedManualSkill(item, pendingRequest));
+  if (!skill) {
+    if (deps.skillMarketplace !== false && deps.getSkillLoaderOptions?.().disableDiscovery !== true) {
+      const installed = installedSkillPackages(
+        list.items,
+        cwdFromDeps(deps),
+        deps.getSkillLoaderOptions?.().trustProjectCompatRoots === true
+      ).find((pkg) => pkg.names.includes(name));
+      if (installed && installed.state !== "ready")
+        return {
+          kind: "error",
+          message: `context: skill "${name}" is installed in ${installed.scope} scope but ${installed.state}. Inspect it in /library; do not reinstall it.`
+        };
+    }
+    const unavailable = list.items.find((item) => item.name === name);
+    if (unavailable) {
+      return {
+        kind: "error",
+        message: unavailable.trusted ? `context: skill "${name}" requires explicit operator activation with /skill ${name}; it disables model invocation. Do not retry this load.` : unavailable.source === "plugin" ? `context: skill "${name}" is imported but untrusted. Review it in /library, then enable integrations.projectResources.trustProjectImports to use it. Do not retry this load.` : `context: skill "${name}" is discovered in ${unavailable.source}/${unavailable.scope}, not imported into Clio. Use interop adopt or library import explicitly; the trust setting alone does not activate it. Do not retry this load.`
+      };
+    }
+    const installable = marketplaceRowsFor(deps, list.items, options).some((entry) => entry.name === name);
+    if (installable) {
+      return {
+        kind: "error",
+        message: `context: skill "${name}" is not installed; it is available in the marketplace. If installation has not been declined, offer /skill ${name} to install it. If the operator chose Not now or Cancel, continue without this skill and do not offer it again. Do not retry this load.`
+      };
+    }
+    const available = visible.map((item) => item.name).join(", ");
+    const suffix = available.length > 0 ? ` Available skills: ${available}.` : " No skills are currently available.";
+    return { kind: "error", message: `context: unknown skill "${name}".${suffix}` };
+  }
+  const includeTree = args.include_tree === true;
+  const tree = includeTree ? buildResourceTree(skill.baseDir, DEFAULT_TREE_ENTRIES) : null;
+  const pendingTask = pendingRequest?.args.trim() ?? "";
+  const driftReport = checkSkillDrift(skill, cwdFromDeps(deps));
+  const drift = driftReport?.verdict ?? null;
+  const driftWarning = driftReport?.verdict === "mismatch" ? `WARNING skill_drift: '${skill.name}' content (sha256 ${skill.hash.slice(0, 12)}\u2026) no longer matches the hash recorded for it ${driftReport.authority === "pinned-manifest" ? "in the audited skill catalog" : "when it was installed on this machine"} (expected ${driftReport.expected.slice(0, 12)}\u2026); the installed skill drifted from the content it claims to be.` : null;
+  const body = [
+    ...driftWarning !== null ? [driftWarning] : [],
+    ...renderPendingSkillTask(name, options),
+    ...skillExecutionFrame(skill, cwdFromDeps(deps)),
+    renderSkillBody(skill, tree)
+  ].join("\n");
+  const pendingPolicy = options?.pendingSkillPolicy;
+  if (pendingPolicy) {
+    pendingPolicy.loadedSkillNames.add(name);
+    pendingPolicy.loadedSkillPolicies.set(name, {
+      ...skill.allowedTools ? { allowedTools: skill.allowedTools } : {},
+      ...skill.disallowedTools ? { disallowedTools: skill.disallowedTools } : {}
+    });
+  }
+  const truncation = truncateHead(body, { maxBytes: reservation.callCapBytes, maxLines: Number.MAX_SAFE_INTEGER });
+  return finalizeObservation({
+    tool: ToolNames.Context,
+    unit: "sections",
+    output: truncation.content,
+    ...truncation.truncated ? { fullOutput: body } : {},
+    shownCount: 1,
+    totalCount: 1,
+    truncated: truncation.truncated,
+    details: {
+      name: skill.name,
+      description: skill.description,
+      ...pendingTask.length > 0 ? { pendingTask } : {},
+      path: skill.filePath,
+      baseDir: skill.baseDir,
+      hash: skill.hash,
+      source: skill.source,
+      sourceOrigin: skillSourceOrigin(skill),
+      sourceInfo: skill.sourceInfo,
+      scope: skill.scope,
+      disableModelInvocation: skill.disableModelInvocation,
+      ...skill.allowedTools ? { allowedTools: skill.allowedTools } : {},
+      ...skill.disallowedTools ? { disallowedTools: skill.disallowedTools } : {},
+      diagnostics: skill.diagnostics.map((d) => d.message),
+      metadata: skill.metadata,
+      ...skill.provenance ? { provenance: skill.provenance } : {},
+      ...drift !== null ? { drift } : {},
+      ...tree ? { tree } : {}
+    },
+    reservation,
+    ...options ? { options } : {}
+  });
+}
+function runRecallScope(deps, args, reservation, options) {
+  if (deps.workerRecall) {
+    const result2 = deps.workerRecall(args);
+    if ("error" in result2) return { kind: "error", message: `context: ${result2.error}` };
+    const truncated = truncateHead(result2.body, {
+      maxBytes: reservation.callCapBytes,
+      maxLines: Number.MAX_SAFE_INTEGER
+    });
+    return finalizeObservation({
+      tool: ToolNames.Context,
+      unit: "results",
+      output: truncated.content,
+      ...truncated.truncated ? { fullOutput: result2.body } : {},
+      shownCount: result2.shown,
+      totalCount: result2.total,
+      truncated: truncated.truncated || result2.nextOffset !== void 0,
+      details: { workerRecall: { ref: args.ref ?? null, nextOffset: result2.nextOffset ?? null } },
+      reservation,
+      ...options ? { options } : {}
+    });
+  }
+  const session = deps.session;
+  if (!session?.hasSession()) {
+    return { kind: "error", message: "context: recall scope requires a bound session; none is active here" };
+  }
+  const ref = typeof args.ref === "string" ? args.ref.trim() : "";
+  const entries = session.readEntries();
+  const leaf = session.activeLeafTurnId();
+  const view = foldWorkingSet(entries, leaf);
+  if (args.ref === void 0) {
+    const listing = recallableRefListing(entries, view, {
+      ...leaf === void 0 ? {} : { activeLeafTurnId: leaf },
+      ...typeof args.query === "string" ? { query: args.query } : {},
+      ...typeof args.limit === "number" ? { limit: args.limit } : {},
+      ...typeof args.offset === "number" ? { offset: args.offset } : {}
+    });
+    const output = [
+      ...listing.refs,
+      listing.nextOffset === void 0 ? "End of matching recallable refs." : `More matches: repeat this query with offset=${listing.nextOffset}.`,
+      'Recall an exact persisted body with context(scope="recall", ref="<turnId>").'
+    ].join("\n");
+    const truncation2 = truncateHead(output, { maxBytes: reservation.callCapBytes, maxLines: Number.MAX_SAFE_INTEGER });
+    return finalizeObservation({
+      tool: ToolNames.Context,
+      unit: "results",
+      output: truncation2.content,
+      ...truncation2.truncated ? { fullOutput: output } : {},
+      shownCount: listing.refs.length,
+      totalCount: listing.total,
+      truncated: truncation2.truncated || listing.remaining > 0,
+      details: { recallDiscovery: listing },
+      reservation,
+      ...options ? { options } : {}
+    });
+  }
+  const resolved = resolveRecall(entries, view, ref, leaf);
+  if (!resolved.ok)
+    return { kind: "error", message: `context: ${recallErrorMessage(resolved.error, entries, view, leaf)}` };
+  const { result } = resolved;
+  const fields = buildRecallFields(result, {
+    trigger: "tool",
+    ...options?.toolCallId ? { toolCallId: options.toolCallId } : {}
+  });
+  const parentTurnId = recallParentTurnId(entries, leaf);
+  let recorded;
+  try {
+    recorded = session.appendEntry({ ...fields, parentTurnId });
+  } catch (err) {
+    return {
+      kind: "error",
+      message: `context: recall of ${result.ref.entry} could not be recorded: ${err instanceof Error ? err.message : String(err)}`
+    };
+  }
+  session.onRecalled?.({ ref: result.ref.entry, trigger: "tool", tokensReadmitted: result.tokens, at: Date.now() });
+  const evictedState = view.evicted.get(result.ref.entry);
+  const truncation = truncateHead(result.body, {
+    maxBytes: reservation.callCapBytes,
+    maxLines: Number.MAX_SAFE_INTEGER
+  });
+  return finalizeObservation({
+    tool: ToolNames.Context,
+    unit: "results",
+    output: truncation.content,
+    ...truncation.truncated ? { fullOutput: result.body } : {},
+    shownCount: 1,
+    totalCount: 1,
+    truncated: truncation.truncated,
+    details: {
+      recall: {
+        ref: result.ref.entry,
+        state: result.state,
+        tokensReadmitted: result.tokens,
+        recallTurnId: recorded.turnId,
+        ...evictedState ? { reason: evictedState.reason, evictedAtTurnId: evictedState.evictedAtTurnId } : {},
+        ...result.offloadPath !== void 0 ? { offloadPath: result.offloadPath } : {}
+      }
+    },
+    reservation,
+    ...options ? { options } : {}
+  });
+}
+function createContextTool(deps = {}) {
+  return {
+    ...contextToolSurface,
+    async run(args, options) {
+      const scope = typeof args.scope === "string" ? args.scope : "";
+      if (scope === "docs" || scope === "library") {
+        const capability = scope === "docs" ? ToolNames.ClioDocs : ToolNames.ClioLibrary;
+        return {
+          kind: "error",
+          message: `context: scope "${scope}" is a gateway capability now: call gateway(op="call", capability="${capability}", args={...}) or gateway(op="describe", capability="${capability}") for its arguments.`
+        };
+      }
+      if (scope !== "workspace" && scope !== "settings" && scope !== "skills" && scope !== "recall") {
+        return {
+          kind: "error",
+          message: `context: scope must be workspace, settings, skills, or recall; got '${scope}'`
+        };
+      }
+      const selfCap = scope === "skills" ? OBSERVE_SELF_CAPS.contextSkills : OBSERVE_SELF_CAPS.contextWorkspace;
+      const reservation = reserveObservation(selfCap, options);
+      if (reservation.exhausted) {
+        return observationBudgetExhausted({
+          tool: ToolNames.Context,
+          unit: scope === "skills" ? "entries" : "results",
+          reservation,
+          subject: `scope=${scope}`,
+          hint: "Continue in a follow-up turn."
+        });
+      }
+      if (scope === "settings") {
+        if (!deps.getSettings)
+          return {
+            kind: "error",
+            message: "An authoritative live settings snapshot is unavailable in this run. Ask the user to open /settings or run clio-coder config inspect; do not infer current limits from defaults."
+          };
+        const offset = args.offset === void 0 ? 0 : args.offset;
+        const limit = args.limit === void 0 ? 12 : args.limit;
+        if (typeof offset !== "number" || !Number.isSafeInteger(offset) || offset < 0 || typeof limit !== "number" || !Number.isSafeInteger(limit) || limit < 1 || limit > 12)
+          return { kind: "error", message: "Use a non-negative integer offset and a limit from 1 to 12." };
+        const snapshot = settingsAwareness(
+          deps.getSettings(),
+          typeof args.query === "string" ? args.query : "",
+          offset,
+          limit
+        );
+        return finalizeObservation({
+          tool: ToolNames.Context,
+          unit: "entries",
+          format: "json",
+          output: JSON.stringify(snapshot, null, 2),
+          shownCount: snapshot.rows.length,
+          totalCount: snapshot.total,
+          truncated: snapshot.nextOffset !== null,
+          reservation,
+          ...options ? { options } : {}
+        });
+      }
+      if (scope === "workspace") return runWorkspaceScope(deps, reservation, options);
+      if (scope === "recall") return runRecallScope(deps, args, reservation, options);
+      return runSkillsScope(deps, args, reservation, options);
+    }
+  };
+}
+
+export {
+  runDocsScope,
+  createContextTool
+};
+//# sourceMappingURL=chunk-TGWZXJ7L.js.map