@qloo/qloo-harness 0.1.18 → 0.1.19

package/dist/qloo-tools.js

@@ -786,12 +786,12 @@ var QLOO_LIMIT_SCHEMA = Type.Optional(Type.Integer({
 var QLOO_ENTITY_INPUTS_SCHEMA = Type.Array(Type.String({ minLength: 1 }), {
   minItems: 1,
   maxItems: 10,
-  description: "Entity names or Qloo entity UUIDs. Keep one combined taste profile in one call."
+  description: "Named entities or Qloo entity UUIDs; use tag fields for abstract concepts."
 });
 var QLOO_TAG_INPUTS_SCHEMA = Type.Array(Type.String({ minLength: 1 }), {
   minItems: 1,
   maxItems: 10,
-  description: "Natural-language tag concepts or stable Qloo tag URNs."
+  description: "Genres, moods, styles, traits, or other concepts, or Qloo tag URNs; not named entities."
 });
 var QLOO_DEMOGRAPHIC_SCHEMA = Type.String({
   minLength: 1,
@@ -951,6 +951,7 @@ var QLOO_WORKFLOW_METADATA = {
     promptSnippet: "Recommend entities from a combined Qloo taste profile",
     promptGuidelines: [
       "Pass every related taste and audience signal together in one qloo_recommend call.",
+      "Put named things in signals; put genres, moods, styles, traits, and concepts such as quiet luxury in signal_tags; reuse returned Qloo UUIDs and tag URNs.",
       "Use signal_location for audience location and filter_location to constrain result geography.",
       "Include demographic and location in the same call when both describe the audience."
     ],
@@ -961,7 +962,10 @@ var QLOO_WORKFLOW_METADATA = {
     label: "Qloo rank",
     description: "Rank one supplied option set against one shared entity, location, demographic, and tag profile. Scores from separate calls are not comparable.",
     promptSnippet: "Rank a caller-supplied shortlist with Qloo",
-    promptGuidelines: ["Pass every option in one qloo_rank call so scores remain comparable."],
+    promptGuidelines: [
+      "Pass every option in one qloo_rank call so scores remain comparable.",
+      "Put named things in entity fields and concepts in tag fields; reuse returned Qloo UUIDs and tag URNs."
+    ],
     documentation: ["https://docs.qloo.com/reference/insights-api-deep-dive"]
   },
   describe: {
@@ -1445,7 +1449,7 @@ function interpretedEntity(entity) {
 function interpretedEntities(entities) {
   return entities.map(interpretedEntity);
 }
-async function resolveEntities(provider, inputs, type, signal, correlationId) {
+async function resolveEntities(provider, inputs, type, signal, correlationId, field) {
   const { outcomes } = await provider.resolveEntities({
     inputs,
     ...type ? { type } : {}
@@ -1466,6 +1470,9 @@ async function resolveEntities(provider, inputs, type, signal, correlationId) {
     issues: outcomes.flatMap((outcome) => outcome.status === "resolved" ? [] : [{
       input: outcome.input,
       kind: outcome.status,
+      input_kind: "entity",
+      field,
+      ...type ? { scope: type } : {},
       ...outcome.candidates ? {
         candidates: outcome.candidates.map((candidate) => ({ ...candidate }))
       } : {},
@@ -1484,7 +1491,7 @@ function interpretedTags(tags) {
     ...tag.score !== void 0 ? { score: tag.score } : {}
   }));
 }
-async function resolveTags(provider, inputs, targetType, purpose, signal, correlationId) {
+async function resolveTags(provider, inputs, targetType, purpose, signal, correlationId, field) {
   const { outcomes } = await provider.resolveTags({
     inputs,
     ...targetType ? { targetType } : {},
@@ -1509,6 +1516,10 @@ async function resolveTags(provider, inputs, targetType, purpose, signal, correl
     issues: outcomes.flatMap((outcome) => outcome.status === "resolved" ? [] : [{
       input: outcome.input,
       kind: outcome.status,
+      input_kind: "tag",
+      field,
+      ...targetType ? { scope: targetType } : {},
+      purpose,
       ...outcome.candidates ? {
         candidates: outcome.candidates.map((candidate) => ({ ...candidate }))
       } : {},
@@ -1656,10 +1667,10 @@ function makeRecommendTool(clientOption, resolutionProviderOption) {
         return needsInput("recommend", [], "Provide at least one entity, tag, location, or demographic taste signal.");
       }
       const [entities, signalTags, includeTags, excludeTags] = await Promise.all([
-        resolveEntities(resolutionProvider, params.signals ?? [], void 0, signal, toolCallId),
-        resolveTags(resolutionProvider, params.signal_tags ?? [], targetType, "signal", signal, toolCallId),
-        resolveTags(resolutionProvider, params.include_tags ?? [], targetType, "include_filter", signal, toolCallId),
-        resolveTags(resolutionProvider, params.exclude_tags ?? [], targetType, "exclude_filter", signal, toolCallId)
+        resolveEntities(resolutionProvider, params.signals ?? [], void 0, signal, toolCallId, "signals"),
+        resolveTags(resolutionProvider, params.signal_tags ?? [], targetType, "signal", signal, toolCallId, "signal_tags"),
+        resolveTags(resolutionProvider, params.include_tags ?? [], targetType, "include_filter", signal, toolCallId, "include_tags"),
+        resolveTags(resolutionProvider, params.exclude_tags ?? [], targetType, "exclude_filter", signal, toolCallId, "exclude_tags")
       ]);
       const issues = [...entities.issues, ...signalTags.issues, ...includeTags.issues, ...excludeTags.issues];
       if (issues.length > 0)
@@ -1743,10 +1754,10 @@ function makeRankTool(clientOption, resolutionProviderOption) {
         return needsInput("rank", [], "Ranking requires an entity, location, or demographic signal.");
       }
       const [options, signals, includeTags, excludeTags] = await Promise.all([
-        resolveEntities(resolutionProvider, params.options, targetType, signal, toolCallId),
-        resolveEntities(resolutionProvider, params.signals ?? [], void 0, signal, toolCallId),
-        resolveTags(resolutionProvider, params.include_tags ?? [], targetType, "include_filter", signal, toolCallId),
-        resolveTags(resolutionProvider, params.exclude_tags ?? [], targetType, "exclude_filter", signal, toolCallId)
+        resolveEntities(resolutionProvider, params.options, targetType, signal, toolCallId, "options"),
+        resolveEntities(resolutionProvider, params.signals ?? [], void 0, signal, toolCallId, "signals"),
+        resolveTags(resolutionProvider, params.include_tags ?? [], targetType, "include_filter", signal, toolCallId, "include_tags"),
+        resolveTags(resolutionProvider, params.exclude_tags ?? [], targetType, "exclude_filter", signal, toolCallId, "exclude_tags")
       ]);
       const issues = [...options.issues, ...signals.issues, ...includeTags.issues, ...excludeTags.issues];
       if (issues.length > 0)
@@ -1805,7 +1816,7 @@ function makeDescribeTool(clientOption, resolutionProviderOption) {
       const client = requireClient(clientOption);
       const resolutionProvider = requireResolutionProvider(resolutionProviderOption);
       const type = params.type ? resolveSearchType(params.type) : void 0;
-      const resolution = await resolveEntities(resolutionProvider, [params.entity], type, signal, toolCallId);
+      const resolution = await resolveEntities(resolutionProvider, [params.entity], type, signal, toolCallId, "entity");
       if (resolution.issues.length > 0)
         return needsInput("describe", resolution.issues, "Choose the intended Qloo entity.");
       const needsDetailHydration = resolution.resolved.some(({ match }) => match !== "identifier");
@@ -1842,7 +1853,7 @@ function makeWherePopularTool(clientOption, resolutionProviderOption) {
       const client = requireClient(clientOption);
       const resolutionProvider = requireResolutionProvider(resolutionProviderOption);
       const type = params.entity_type ? resolveSearchType(params.entity_type) : void 0;
-      const resolution = await resolveEntities(resolutionProvider, [params.entity], type, signal, toolCallId);
+      const resolution = await resolveEntities(resolutionProvider, [params.entity], type, signal, toolCallId, "entity");
       if (resolution.issues.length > 0)
         return needsInput("where_popular", resolution.issues, "Choose the intended Qloo entity.");
       const entity = resolution.resolved[0];
@@ -1880,8 +1891,8 @@ function makeCompareAudiencesTool(clientOption, resolutionProviderOption) {
       const client = requireClient(clientOption);
       const resolutionProvider = requireResolutionProvider(resolutionProviderOption);
       const [groupA, groupB] = await Promise.all([
-        resolveEntities(resolutionProvider, params.group_a, void 0, signal, toolCallId),
-        resolveEntities(resolutionProvider, params.group_b, void 0, signal, toolCallId)
+        resolveEntities(resolutionProvider, params.group_a, void 0, signal, toolCallId, "group_a"),
+        resolveEntities(resolutionProvider, params.group_b, void 0, signal, toolCallId, "group_b")
       ]);
       const issues = [...groupA.issues, ...groupB.issues];
       if (issues.length > 0)
@@ -1920,7 +1931,7 @@ function makeEntityTagsTool(clientOption, resolutionProviderOption) {
       const client = requireClient(clientOption);
       const resolutionProvider = requireResolutionProvider(resolutionProviderOption);
       const type = params.entity_type ? resolveSearchType(params.entity_type) : void 0;
-      const resolution = await resolveEntities(resolutionProvider, params.entities, type, signal, toolCallId);
+      const resolution = await resolveEntities(resolutionProvider, params.entities, type, signal, toolCallId, "entities");
       if (resolution.issues.length > 0)
         return needsInput("entity_tags", resolution.issues, "Choose or correct the unresolved Qloo entities.");
       const query = {
@@ -1953,7 +1964,7 @@ function makeAudienceDemographicsTool(clientOption, resolutionProviderOption) {
       const client = requireClient(clientOption);
       const resolutionProvider = requireResolutionProvider(resolutionProviderOption);
       const type = params.entity_type ? resolveSearchType(params.entity_type) : void 0;
-      const resolution = await resolveEntities(resolutionProvider, [params.entity], type, signal, toolCallId);
+      const resolution = await resolveEntities(resolutionProvider, [params.entity], type, signal, toolCallId, "entity");
       if (resolution.issues.length > 0)
         return needsInput("audience_demographics", resolution.issues, "Choose the intended Qloo entity.");
       const entity = resolution.resolved[0];
@@ -1992,7 +2003,7 @@ function makeTrendsTool(clientOption, resolutionProviderOption) {
         throw new Error("Trend dates must be valid YYYY-MM-DD values with start_date on or before end_date.");
       }
       const type = resolveInsightsType(params.entity_type);
-      const resolution = await resolveEntities(resolutionProvider, params.entities, type, signal, toolCallId);
+      const resolution = await resolveEntities(resolutionProvider, params.entities, type, signal, toolCallId, "entities");
       if (resolution.issues.length > 0)
         return needsInput("trends", resolution.issues, "Choose or correct the unresolved Qloo entities.");
       const requests = resolution.resolved.map((entity) => ({

package/dist/resolution-provider.js

@@ -188,12 +188,12 @@ var QLOO_LIMIT_SCHEMA = Type.Optional(Type.Integer({
 var QLOO_ENTITY_INPUTS_SCHEMA = Type.Array(Type.String({ minLength: 1 }), {
   minItems: 1,
   maxItems: 10,
-  description: "Entity names or Qloo entity UUIDs. Keep one combined taste profile in one call."
+  description: "Named entities or Qloo entity UUIDs; use tag fields for abstract concepts."
 });
 var QLOO_TAG_INPUTS_SCHEMA = Type.Array(Type.String({ minLength: 1 }), {
   minItems: 1,
   maxItems: 10,
-  description: "Natural-language tag concepts or stable Qloo tag URNs."
+  description: "Genres, moods, styles, traits, or other concepts, or Qloo tag URNs; not named entities."
 });
 var QLOO_DEMOGRAPHIC_SCHEMA = Type.String({
   minLength: 1,
@@ -353,6 +353,7 @@ var QLOO_WORKFLOW_METADATA = {
     promptSnippet: "Recommend entities from a combined Qloo taste profile",
     promptGuidelines: [
       "Pass every related taste and audience signal together in one qloo_recommend call.",
+      "Put named things in signals; put genres, moods, styles, traits, and concepts such as quiet luxury in signal_tags; reuse returned Qloo UUIDs and tag URNs.",
       "Use signal_location for audience location and filter_location to constrain result geography.",
       "Include demographic and location in the same call when both describe the audience."
     ],
@@ -363,7 +364,10 @@ var QLOO_WORKFLOW_METADATA = {
     label: "Qloo rank",
     description: "Rank one supplied option set against one shared entity, location, demographic, and tag profile. Scores from separate calls are not comparable.",
     promptSnippet: "Rank a caller-supplied shortlist with Qloo",
-    promptGuidelines: ["Pass every option in one qloo_rank call so scores remain comparable."],
+    promptGuidelines: [
+      "Pass every option in one qloo_rank call so scores remain comparable.",
+      "Put named things in entity fields and concepts in tag fields; reuse returned Qloo UUIDs and tag URNs."
+    ],
     documentation: ["https://docs.qloo.com/reference/insights-api-deep-dive"]
   },
   describe: {
@@ -578,6 +582,60 @@ function scalar(record, ...keys) {
 function normalizeName(value) {
   return value.normalize("NFKC").trim().toLocaleLowerCase("en-US");
 }
+var ENTITY_CONTEXT_STOP_WORDS = /* @__PURE__ */ new Set([
+  "a",
+  "an",
+  "and",
+  "at",
+  "by",
+  "for",
+  "from",
+  "in",
+  "of",
+  "on",
+  "the",
+  "to",
+  "with"
+]);
+function contextTokens(value) {
+  return [...new Set(value.normalize("NFKC").toLocaleLowerCase("en-US").match(/[\p{L}\p{N}]+/gu)?.filter((token) => token.length >= 2 && !ENTITY_CONTEXT_STOP_WORDS.has(token)) ?? [])];
+}
+function candidateContextText(candidate) {
+  const address = typeof candidate.address === "string" ? candidate.address : candidate.address === void 0 ? "" : JSON.stringify(candidate.address);
+  return [candidate.name, candidate.type, candidate.description, address].filter((value) => typeof value === "string").join(" ");
+}
+function contextualEntityMatch(input, candidates) {
+  if (candidates.length < 2)
+    return { candidates };
+  const inputTokens = contextTokens(input);
+  if (inputTokens.length < 2)
+    return { candidates };
+  const ranked = candidates.map((candidate) => {
+    const searchable = new Set(contextTokens(candidateContextText(candidate)));
+    return {
+      candidate,
+      matched: inputTokens.filter((token) => searchable.has(token)).length
+    };
+  });
+  const maximum = Math.max(...ranked.map(({ matched }) => matched));
+  const strongest = ranked.filter(({ matched }) => matched === maximum);
+  const decisive = maximum === inputTokens.length && strongest.length === 1 && ranked.some(({ matched }) => matched < maximum);
+  if (decisive && strongest[0]) {
+    return {
+      candidates: [strongest[0].candidate],
+      selected: strongest[0].candidate,
+      alternatives: candidates.filter(({ id }) => id !== strongest[0]?.candidate.id).slice(0, 4),
+      warning: "Qloo selected the only candidate matching every supplied name and location term; reuse its Qloo ID to override future name resolution."
+    };
+  }
+  if (maximum === inputTokens.length && strongest.length < candidates.length) {
+    return {
+      candidates: strongest.map(({ candidate }) => candidate),
+      warning: "Qloo candidate choices were narrowed using the supplied name and location terms."
+    };
+  }
+  return { candidates };
+}
 function requestOptions(context) {
   return {
     ...context.signal ? { signal: context.signal } : {},
@@ -686,7 +744,7 @@ function createNativeQlooResolutionProvider(client, options = {}) {
     contract_version: QLOO_RESOLUTION_CONTRACT_VERSION,
     provider_id: "qloo_api",
     name: "Qloo native resolution",
-    entity_strategy: "exact_name_or_choice",
+    entity_strategy: "exact_name_context_or_choice",
     tag_strategy: "target_scoped_semantic_search_exact_name_or_choice",
     remote: true,
     uses_model: false,
@@ -696,6 +754,7 @@ function createNativeQlooResolutionProvider(client, options = {}) {
   const cacheKey = (kind, input, scope) => JSON.stringify([
     QLOO_RESOLUTION_CONTRACT_VERSION,
     descriptor.provider_id,
+    descriptor.entity_strategy,
     descriptor.tag_strategy,
     kind,
     scope ?? "",
@@ -752,7 +811,7 @@ function createNativeQlooResolutionProvider(client, options = {}) {
         return { input, status: "ambiguous", candidates: exact2.slice(0, 5), provenance: source2 };
       return { input, status: "not_found", provenance: source2 };
     }
-    const source = provenance(descriptor, "/search", "exact_name_or_choice");
+    const source = provenance(descriptor, "/search", "exact_name_context_or_choice");
     const response = await client.searchEntities({
       query: input,
       ...type ? { types: type } : {},
@@ -766,11 +825,19 @@ function createNativeQlooResolutionProvider(client, options = {}) {
       const alternatives = candidates.filter(({ id }) => id !== exact[0]?.id).slice(0, 4);
       return resolved(input, exact[0], "exact", source, { alternatives });
     }
+    const contextual = contextualEntityMatch(input, candidates);
+    if (contextual.selected) {
+      return resolved(input, contextual.selected, "semantic", source, {
+        ...contextual.alternatives ? { alternatives: contextual.alternatives } : {},
+        ...contextual.warning ? { warnings: [contextual.warning] } : {}
+      });
+    }
     return {
       input,
       status: "ambiguous",
-      candidates: (exact.length > 0 ? exact : candidates).slice(0, 5),
-      provenance: source
+      candidates: (exact.length > 0 ? exact : contextual.candidates).slice(0, 5),
+      provenance: source,
+      ...contextual.warning ? { warnings: [contextual.warning] } : {}
     };
   };
   const resolveTag = async (input, targetType, context) => {

package/dist/router.js

@@ -3940,7 +3940,7 @@ var qloo_workflow_contract_default = {
             },
             minItems: 1,
             maxItems: 10,
-            description: "Entity names or Qloo entity UUIDs. Keep one combined taste profile in one call."
+            description: "Named entities or Qloo entity UUIDs; use tag fields for abstract concepts."
           },
           signal_tags: {
             type: "array",
@@ -3950,7 +3950,7 @@ var qloo_workflow_contract_default = {
             },
             minItems: 1,
             maxItems: 10,
-            description: "Natural-language tag concepts or stable Qloo tag URNs."
+            description: "Genres, moods, styles, traits, or other concepts, or Qloo tag URNs; not named entities."
           },
           signal_tags_operator: {
             type: "string",
@@ -3986,7 +3986,7 @@ var qloo_workflow_contract_default = {
             },
             minItems: 1,
             maxItems: 10,
-            description: "Natural-language tag concepts or stable Qloo tag URNs."
+            description: "Genres, moods, styles, traits, or other concepts, or Qloo tag URNs; not named entities."
           },
           include_tags_operator: {
             type: "string",
@@ -4004,7 +4004,7 @@ var qloo_workflow_contract_default = {
             },
             minItems: 1,
             maxItems: 10,
-            description: "Natural-language tag concepts or stable Qloo tag URNs."
+            description: "Genres, moods, styles, traits, or other concepts, or Qloo tag URNs; not named entities."
           },
           exclude_tags_operator: {
             type: "string",
@@ -4075,7 +4075,7 @@ var qloo_workflow_contract_default = {
             },
             minItems: 1,
             maxItems: 10,
-            description: "Entity names or Qloo entity UUIDs. Keep one combined taste profile in one call."
+            description: "Named entities or Qloo entity UUIDs; use tag fields for abstract concepts."
           },
           option_type: {
             type: "string",
@@ -4100,7 +4100,7 @@ var qloo_workflow_contract_default = {
             },
             minItems: 1,
             maxItems: 10,
-            description: "Entity names or Qloo entity UUIDs. Keep one combined taste profile in one call."
+            description: "Named entities or Qloo entity UUIDs; use tag fields for abstract concepts."
           },
           signal_location: {
             type: "string",
@@ -4124,7 +4124,7 @@ var qloo_workflow_contract_default = {
             },
             minItems: 1,
             maxItems: 10,
-            description: "Natural-language tag concepts or stable Qloo tag URNs."
+            description: "Genres, moods, styles, traits, or other concepts, or Qloo tag URNs; not named entities."
           },
           exclude_tags: {
             type: "array",
@@ -4134,7 +4134,7 @@ var qloo_workflow_contract_default = {
             },
             minItems: 1,
             maxItems: 10,
-            description: "Natural-language tag concepts or stable Qloo tag URNs."
+            description: "Genres, moods, styles, traits, or other concepts, or Qloo tag URNs; not named entities."
           }
         },
         additionalProperties: false
@@ -4330,7 +4330,7 @@ var qloo_workflow_contract_default = {
             },
             minItems: 1,
             maxItems: 10,
-            description: "Entity names or Qloo entity UUIDs. Keep one combined taste profile in one call."
+            description: "Named entities or Qloo entity UUIDs; use tag fields for abstract concepts."
           },
           group_b: {
             type: "array",
@@ -4340,7 +4340,7 @@ var qloo_workflow_contract_default = {
             },
             minItems: 1,
             maxItems: 10,
-            description: "Entity names or Qloo entity UUIDs. Keep one combined taste profile in one call."
+            description: "Named entities or Qloo entity UUIDs; use tag fields for abstract concepts."
           },
           target_type: {
             type: "string",
@@ -4413,7 +4413,7 @@ var qloo_workflow_contract_default = {
             },
             minItems: 1,
             maxItems: 10,
-            description: "Entity names or Qloo entity UUIDs. Keep one combined taste profile in one call."
+            description: "Named entities or Qloo entity UUIDs; use tag fields for abstract concepts."
           },
           entity_type: {
             type: "string",
@@ -4721,7 +4721,7 @@ var qloo_workflow_contract_default = {
       }
     ]
   },
-  contract_checksum: "sha256:d356f1c6f6163c3f44c4c92d70d789e651763c4dae3ad2d150aa83acc85a6a62"
+  contract_checksum: "sha256:762bdcc5e14ff797b6de739d2658a83f78af35e68d7a5a3449455be6046924f5"
 };
 
 // apps/qloo-cli/dist/mcp.js

package/dist/runtime/explore-policy.js

@@ -4,10 +4,12 @@ const require = __qlooCreateRequire(import.meta.url);
 // apps/qloo-harness/dist/runtime/explore-policy.js
 import { findGuidedGoal, guidedGoalLabel, QLOO_GUIDED_GOALS, qlooNextActions, qlooStarterIdeaLines } from "../guided-journey.js";
 import { getQlooProfileDefinition } from "../profiles.js";
-import { applyResolutionChoices, formatQlooResolutionCandidateLabels, paginateQlooResult, parseQlooRawPage, resolutionCandidates } from "../qloo-presentation.js";
+import { applyResolutionChoices, paginateQlooResult, parseQlooRawPage, resolutionCandidates } from "../qloo-presentation.js";
 import { QLOO_NO_GUIDED_START_ENVIRONMENT_VARIABLE } from "../setup.js";
 import { isBlockedPiInteractiveCommand } from "./pi-command-policy.js";
 import { renderQlooHeader } from "./qloo-header.js";
+import { selectQlooResolutionChoices } from "./resolution-choice-ui.js";
+import { QLOO_RESOLUTION_CHOICE_ENTRY_TYPE, QlooResolutionMemory, clearResolutionChoicesEvent, forgetResolutionChoiceEvent, rememberResolutionChoicesEvent } from "./resolution-memory.js";
 var QLOO_WORKSPACE_TOOL_NAMES = [
   ...getQlooProfileDefinition("build").workspaceTools
 ];
@@ -141,6 +143,7 @@ function createHarnessPolicyExtension(profile, allowedToolNames, runtimeInfo, co
       let lastQlooToolName;
       let rawPage = 1;
       let activeProfile = profile;
+      const resolutionMemory = new QlooResolutionMemory();
       const customToolNames = [...allowedToolNames].filter((name) => !reservedBuiltInTools.has(name));
       const activeDefinition = () => getQlooProfileDefinition(activeProfile);
       const activeAllowedToolNames = () => /* @__PURE__ */ new Set([
@@ -156,6 +159,7 @@ function createHarnessPolicyExtension(profile, allowedToolNames, runtimeInfo, co
       };
       const restoreLastQlooResult = (context) => {
         const entries = context.sessionManager?.getBranch() ?? [];
+        resolutionMemory.restore(entries);
         for (let index = entries.length - 1; index >= 0; index -= 1) {
           const entry = entries[index];
           if (entry === null || typeof entry !== "object")
@@ -190,7 +194,64 @@ ${bounded}`);
       const setNextWidget = (context) => {
         if (context?.mode !== "tui" || !context.ui?.setWidget)
           return;
-        context.ui.setWidget(QLOO_NEXT_WIDGET_KEY, ["Next: /next choose a follow-up \xB7 /why interpretation \xB7 /request API request"], { placement: "belowEditor" });
+        context.ui.setWidget(QLOO_NEXT_WIDGET_KEY, ["Next: /next follow-up \xB7 /why interpretation \xB7 /request API request \xB7 /matches remembered choices"], { placement: "belowEditor" });
+      };
+      const bindingLabel = (binding, index) => {
+        const prefix = index === void 0 ? "" : `${index + 1}. `;
+        const scope = binding.scope ? ` \xB7 ${binding.scope.replace(/^urn:entity:/u, "")}` : "";
+        return `${prefix}${binding.input} \u2192 ${binding.selected.name} \xB7 ${binding.input_kind}${scope}`;
+      };
+      const decorateConfirmedChoices = (details, bindings) => {
+        if (bindings.length === 0)
+          return { ...details };
+        const resolution = details.resolution !== null && typeof details.resolution === "object" && !Array.isArray(details.resolution) ? details.resolution : {};
+        return {
+          ...details,
+          resolution: {
+            ...resolution,
+            confirmed_choices: bindings.map((binding) => ({
+              input: binding.input,
+              input_kind: binding.input_kind,
+              field: binding.field,
+              ...binding.scope ? { scope: binding.scope } : {},
+              selected: { ...binding.selected },
+              instruction: "Reuse this Qloo identifier verbatim for this meaning in later calls."
+            }))
+          }
+        };
+      };
+      const showRememberedMatches = async (args, context) => {
+        if (args.trim().length > 0) {
+          context.ui.notify("Usage: /matches", "warning");
+          return;
+        }
+        const bindings = resolutionMemory.list();
+        if (bindings.length === 0) {
+          context.ui.notify("No user-confirmed Qloo matches are remembered in this session.");
+          return;
+        }
+        const visible = bindings.slice(-20);
+        const forgetLabels = visible.map((binding2, index2) => `Forget ${bindingLabel(binding2, index2)}`);
+        const clearLabel = `Forget all ${bindings.length} remembered matches`;
+        const cancelLabel = "Keep remembered matches";
+        const selected = await context.ui.select("Remembered Qloo matches", [...forgetLabels, clearLabel, cancelLabel]);
+        if (!selected || selected === cancelLabel)
+          return;
+        if (selected === clearLabel) {
+          const confirmed = await context.ui.confirm("Forget all remembered Qloo matches?", "The harness will ask again when any of these inputs are ambiguous.");
+          if (!confirmed)
+            return;
+          resolutionMemory.clear();
+          pi.appendEntry(QLOO_RESOLUTION_CHOICE_ENTRY_TYPE, clearResolutionChoicesEvent());
+          context.ui.notify("Forgot all remembered Qloo matches.");
+          return;
+        }
+        const index = forgetLabels.indexOf(selected);
+        const binding = visible[index];
+        if (index < 0 || !binding || !resolutionMemory.forget(binding))
+          return;
+        pi.appendEntry(QLOO_RESOLUTION_CHOICE_ENTRY_TYPE, forgetResolutionChoiceEvent(binding));
+        context.ui.notify(`Forgot \u201C${binding.input}\u201D \u2192 ${binding.selected.name}.`);
       };
       const recordQlooResult = (toolName, input, details, context) => {
         const boundedInput = boundedWorkflowInput(input);
@@ -384,6 +445,7 @@ ${bounded}`);
             `Fallback: ${runtimeInfo?.fallback ?? "none"}`,
             `Model: ${model}`,
             `Workspace: ${context.cwd}`,
+            `Remembered matches: ${resolutionMemory.list().length}`,
             `Context: ${usage?.tokens ?? "unknown"}/${usage?.contextWindow ?? "unknown"} tokens${usage?.percent === null || usage?.percent === void 0 ? "" : ` (${usage.percent.toFixed(1)}%)`}`,
             `Turn budget: ${activeDefinition().maxToolCallsPerTurn} calls; ${activeDefinition().maxIdenticalToolCallsPerTurn} identical calls`
           ].join("\n"));
@@ -483,6 +545,10 @@ ${bounded}`);
           await retryLastWorkflow(context);
         }
       });
+      pi.registerCommand("matches", {
+        description: "Inspect or forget user-confirmed Qloo entity and tag matches",
+        handler: async (args, context) => showRememberedMatches(args, context)
+      });
       pi.on("session_start", async (event, context) => {
         if (activeProfile === "build" && event.reason !== "startup") {
           activateProfile("plan", context);
@@ -549,42 +615,35 @@ ${bounded}`);
         if (event.details === null || typeof event.details !== "object" || Array.isArray(event.details))
           return;
         const details = event.details;
-        const issues = resolutionCandidates(details);
+        const issues = resolutionCandidates(details, event.toolName, event.input);
         if (issues.length === 0 || !context.hasUI || !commandActions.retry) {
           recordQlooResult(event.toolName, event.input, details, context);
           await maybeRunAutomaticDiagnosis(details, context);
           return;
         }
-        const choices = [];
-        for (const issue of issues) {
-          const labels = formatQlooResolutionCandidateLabels(issue.candidates).map((label, index) => `${index + 1}. ${label}`);
-          const cancelLabel = "Cancel and ask me";
-          const selected = await context.ui.select(`Choose the Qloo match for \u201C${issue.input.slice(0, 120)}\u201D`, [...labels, cancelLabel]);
-          if (!selected || selected === cancelLabel) {
-            recordQlooResult(event.toolName, event.input, details, context);
-            return;
-          }
-          const selectedIndex = labels.indexOf(selected);
-          const selectedId = issue.candidates[selectedIndex]?.id;
-          if (selectedIndex < 0 || typeof selectedId !== "string") {
-            recordQlooResult(event.toolName, event.input, details, context);
-            return;
-          }
-          choices.push({ input: issue.input, selectedId });
+        const choices = await selectQlooResolutionChoices(context.ui, issues, context.mode === "tui");
+        if (!choices) {
+          recordQlooResult(event.toolName, event.input, details, context);
+          return;
         }
         const patchedInput = applyResolutionChoices(event.toolName, event.input, choices);
         if (!patchedInput) {
           recordQlooResult(event.toolName, event.input, details, context);
           return;
         }
+        const remembered = resolutionMemory.remember(event.toolName, choices);
+        if (remembered.length > 0) {
+          pi.appendEntry(QLOO_RESOLUTION_CHOICE_ENTRY_TYPE, rememberResolutionChoicesEvent(remembered));
+        }
         try {
           context.ui.setWorkingMessage("Qloo \xB7 applying your selection\u2026");
           const retriedDetails = await commandActions.retry(event.toolName, patchedInput);
-          recordQlooResult(event.toolName, patchedInput, retriedDetails, context);
-          await maybeRunAutomaticDiagnosis(retriedDetails, context);
+          const confirmedDetails = decorateConfirmedChoices(retriedDetails, remembered);
+          recordQlooResult(event.toolName, patchedInput, confirmedDetails, context);
+          await maybeRunAutomaticDiagnosis(confirmedDetails, context);
           return {
-            content: [{ type: "text", text: JSON.stringify(retriedDetails) }],
-            details: retriedDetails,
+            content: [{ type: "text", text: JSON.stringify(confirmedDetails) }],
+            details: confirmedDetails,
             isError: false
           };
         } catch {
@@ -603,6 +662,11 @@ ${bounded}`);
             reason: `Tool "${event.toolName}" is unavailable in Qloo's ${activeProfile} profile.`
           };
         }
+        if (event.toolName.startsWith("qloo_") && event.toolName !== "qloo_capabilities") {
+          const remembered = resolutionMemory.apply(event.toolName, event.input);
+          if (remembered)
+            Object.assign(event.input, remembered.input);
+        }
         toolCallsThisTurn += 1;
         if (toolCallsThisTurn > definition.maxToolCallsPerTurn) {
           return {