portable-agent-layer 0.92.0 → 0.93.0

package/assets/schema/pal-settings.schema.json

@@ -98,6 +98,14 @@
           "type": "boolean",
           "description": "Let the rules you approved from your past corrections steer the agent: a rule triggered by your prompt is injected before the agent answers, and a reply that matches a rule's trigger is sent back to the agent once at stop. Each firing is logged to memory/adaptation/rule-events.jsonl. Set false to switch every rule off. Reply-side rules do not run on Cursor, whose stop payload carries no reply text, or on opencode, whose plugin does not run the stop check."
         },
+        "entityCards": {
+          "type": "boolean",
+          "description": "When a prompt names a person or company from the knowledge store, inject a short card about them before the agent answers. Reads files only; no model call."
+        },
+        "entityExtraction": {
+          "type": "boolean",
+          "description": "After a session stops, ask a background model which people and companies your own messages mentioned, and write clear matches and new full names to the knowledge store with the message as source. A name that could be more than one entry, or a first name alone, waits for `pal cli knowledge review` instead."
+        },
         "steeringTestReport": { "type": "boolean", "description": "When true, the assistant notes to the user which steering self-check fired. For the dual-live test period; ships false." }
       }
     },

package/assets/templates/pal-settings.json

@@ -33,6 +33,8 @@
     "claimCheck": true,
     "claimCheckBlocks": false,
     "adaptationRules": true,
+    "entityCards": true,
+    "entityExtraction": true,
     "steeringTestReport": false
   },
   "steering": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portable-agent-layer",
-  "version": "0.92.0",
+  "version": "0.93.0",
   "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
   "type": "module",
   "bin": {

package/src/cli/knowledge.ts

@@ -6,6 +6,13 @@
  */
 
 import { readFileSync } from "node:fs";
+import type { ReviewItem } from "../hooks/lib/entity-extraction";
+import {
+  type AcceptChoice,
+  acceptReview,
+  pendingReviews,
+  rejectReview,
+} from "../hooks/lib/entity-review";
 import { toPath } from "../hooks/lib/paths";
 import { buildGraph, resolveSlug, stats, traverse } from "../tools/knowledge/graph";
 import {
@@ -113,6 +120,36 @@ export const knowledgeCommand = group({
       },
       run: ({ values }) => cmdIngest(values.source ?? "manual", values.file),
     }),
+    review: group({
+      summary: "People and companies the background extractor would not guess",
+      fallback: "list",
+      commands: {
+        list: leaf({ summary: "Show what waits for an answer", run: cmdReviewList }),
+        accept: leaf({
+          summary: "Write an item, to an existing entry (--as) or a new one",
+          args: "<id>",
+          options: {
+            as: {
+              type: "string",
+              value: "<slug>",
+              description: "Existing entry to update",
+            },
+            name: {
+              type: "string",
+              value: "<name>",
+              description: "Name for a new entry (default: as extracted)",
+            },
+          },
+          run: ({ positionals, values }) =>
+            cmdReviewAccept(positionals[0], { as: values.as, name: values.name }),
+        }),
+        reject: leaf({
+          summary: "Drop an item without writing it",
+          args: "<id>",
+          run: ({ positionals }) => cmdReviewReject(positionals[0]),
+        }),
+      },
+    }),
   },
   details: VOCABULARY,
 });
@@ -578,3 +615,63 @@ async function cmdIngest(sourceId: string, file: string | undefined): Promise<nu
   console.log(JSON.stringify(summary, null, 2));
   return 0;
 }
+
+// ── review ─────────────────────────────────────────────────────────
+
+function reviewReason(reason: ReviewItem["reason"]): string {
+  const reasons: Record<ReviewItem["reason"], string> = {
+    ambiguous: "could be more than one known entry",
+    "unknown-existing": "named an entry the store does not have",
+    "first-name-only": "first name only",
+  };
+  return reasons[reason];
+}
+
+function reviewLines(item: ReviewItem): string[] {
+  const { kind, name, fact } = item.entity;
+  const candidates =
+    item.candidates.length > 0 ? `could be: ${item.candidates.join(", ")}` : "";
+  return [
+    `  ${item.id}  ${kind} "${name}" — ${reviewReason(item.reason)}`,
+    ...[fact, candidates, `from ${item.source}`]
+      .filter(Boolean)
+      .map((line) => `            ${line}`),
+  ];
+}
+
+function cmdReviewList(): number {
+  const items = pendingReviews();
+  if (items.length === 0) {
+    console.log("Nothing waits for review.");
+    return 0;
+  }
+  console.log(`\n${items.length} waiting for review\n`);
+  for (const item of items) console.log(reviewLines(item).join("\n"));
+  console.log(
+    "\nAccept: pal cli knowledge review accept <id> [--as <slug>] [--name <name>]\nReject: pal cli knowledge review reject <id>\n"
+  );
+  return 0;
+}
+
+function acceptOrExplain(id: string, choice: AcceptChoice) {
+  try {
+    return acceptReview(id, choice);
+  } catch (err) {
+    throw new UsageError(err instanceof Error ? err.message : String(err));
+  }
+}
+
+function cmdReviewAccept(id: string, choice: AcceptChoice): number {
+  const accepted = acceptOrExplain(id, choice);
+  if (!accepted) throw new UsageError(`no review item "${id}"`);
+  const verb = accepted.created ? "Created" : "Updated";
+  console.log(`${verb} ${accepted.slug} from "${accepted.item.entity.name}".`);
+  return 0;
+}
+
+function cmdReviewReject(id: string): number {
+  const rejected = rejectReview(id);
+  if (!rejected) throw new UsageError(`no review item "${id}"`);
+  console.log(`Dropped "${rejected.entity.name}".`);
+  return 0;
+}

package/src/hooks/handlers/entity-extraction.ts

@@ -0,0 +1,85 @@
+/**
+ * Stop handler: learn the people and companies the user mentioned since the last
+ * stop, so the prompt-time cards know them next time. Runs detached; one model
+ * call at most, and only when the new text names someone.
+ */
+
+import { ingestEntities } from "../../tools/knowledge/ingest";
+import { excludedNames, loadKnownEntities, loadNameIndex } from "../lib/entity-cards";
+import {
+  extractionSchema,
+  extractionSystem,
+  extractionUser,
+  markSeen,
+  parseExtraction,
+  planExtraction,
+  queueForReview,
+  seenCount,
+  unseenUserText,
+  worthExtracting,
+} from "../lib/entity-extraction";
+import { canInfer, inference } from "../lib/inference";
+import { logDebug, logError } from "../lib/log";
+import { identity, isEnabled } from "../lib/settings";
+import { logTokenUsage } from "../lib/token-usage";
+import { parseMessages } from "../lib/transcript";
+
+function sourceId(sessionId: string, count: number): string {
+  return `chat ${new Date().toISOString().slice(0, 10)} ${sessionId.slice(0, 8)} #${count}`;
+}
+
+/** @lintignore exercised directly by test/entity-extraction.test.ts */
+export async function extractSessionEntities(
+  transcript: string,
+  sessionId?: string
+): Promise<void> {
+  if (!sessionId || !isEnabled("entityExtraction")) return;
+  const seen = seenCount(sessionId);
+  const { text, count } = unseenUserText(parseMessages(transcript), seen);
+  if (count <= seen) return;
+
+  const index = loadNameIndex(loadKnownEntities());
+  const excluded = excludedNames();
+  markSeen(sessionId, count);
+  if (!worthExtracting(text, index, excluded) || !canInfer()) return;
+
+  const id = identity();
+  const result = await inference({
+    system: extractionSystem(id.principal.name, id.ai.name),
+    user: extractionUser(text, index),
+    tier: "medium",
+    maxTokens: 900,
+    timeout: 90000,
+    jsonSchema: extractionSchema(),
+    caller: "entity-extraction",
+    sessionId,
+  });
+  if (result.usage) logTokenUsage("entity-extraction", result.usage);
+  if (!result.success || !result.output) return;
+
+  const source = sourceId(sessionId, count);
+  const plan = planExtraction(parseExtraction(result.output), index, excluded, source);
+  const written = ingestEntities(plan.ingest, source);
+  queueForReview(plan.review);
+  logDebug(
+    "entity-extraction",
+    `${written.people.length} people, ${written.companies.length} companies, ${plan.review.length} for review`
+  );
+}
+
+if (process.argv[2] === "--run") {
+  const sid = process.argv[3];
+  const transcriptPath = process.argv[4];
+  if (transcriptPath) {
+    const { readFile, unlink } = await import("node:fs/promises");
+    try {
+      const transcript = await readFile(transcriptPath, "utf-8");
+      await extractSessionEntities(transcript, sid === "" ? undefined : sid);
+    } catch (err) {
+      logError("entity-extraction:run", err);
+    } finally {
+      await unlink(transcriptPath).catch(() => {});
+    }
+  }
+  process.exit(0);
+}

package/src/hooks/handlers/inject-retrieval.ts

@@ -10,6 +10,7 @@
 import { promptRulesReminder } from "../lib/adaptation-steering";
 import { promptContextResponse } from "../lib/agent";
 import { dueNudgeReminder } from "../lib/daily-nudge";
+import { getEntityReminder } from "../lib/entity-cards";
 import { observeTurn } from "../lib/interaction";
 import { logDebug, logError } from "../lib/log";
 import { parkPromptContext } from "../lib/parked-context";
@@ -91,6 +92,9 @@ export async function getPromptContext(
     withinBudget(() => dueNudgeReminder(), BUDGET_MS),
     userText && getSteeringReminder(userText),
     userText && getSkillReminder(userText),
+    userText &&
+      isEnabled("entityCards") &&
+      withinBudget(() => getEntityReminder(userText), BUDGET_MS),
     userText && (await getRetrievalReminder(userText)),
   ].filter((p): p is string => Boolean(p));
 

package/src/hooks/lib/daily-nudge.ts

@@ -3,9 +3,10 @@ import { resolve } from "node:path";
 import { loadReflectNudge } from "../handlers/reflect-trigger";
 import { loadAlgorithmReviewNudge } from "./algorithm-review";
 import { loadAnalyzeNudge } from "./analyze-nudge";
+import { loadEntityReviewNudge } from "./entity-review";
 import { ensureDir, paths } from "./paths";
 import { loadReactionAuditNudge } from "./reaction-audit";
-import { isOptedIn } from "./settings";
+import { isEnabled, isOptedIn } from "./settings";
 import { localDay } from "./wall-clock";
 
 type ShownOn = Record<string, string>;
@@ -14,6 +15,7 @@ interface DueNudge {
   key: string;
   command: string;
   load: () => string;
+  enabled?: () => boolean;
 }
 
 const DUE_NUDGES: DueNudge[] = [
@@ -27,6 +29,27 @@ const DUE_NUDGES: DueNudge[] = [
   { key: "analyze", command: "/pal-analyze", load: loadAnalyzeNudge },
 ];
 
+function entityReviewNudge(): DueNudge {
+  return {
+    key: "entity-review",
+    command: "pal cli knowledge review",
+    load: loadEntityReviewNudge,
+    enabled: () => isEnabled("entityExtraction"),
+  };
+}
+
+function dueNudges(): DueNudge[] {
+  return [...DUE_NUDGES, entityReviewNudge()];
+}
+
+function dueRemindersOn(): boolean {
+  return isOptedIn("dueReminders");
+}
+
+function isSwitchedOn(nudge: DueNudge): boolean {
+  return (nudge.enabled ?? dueRemindersOn)();
+}
+
 function shownPath(): string {
   return resolve(ensureDir(paths.state()), "nudges-shown.json");
 }
@@ -53,7 +76,7 @@ export function pendingToday(
 }
 
 export function acknowledgeMentioned(reply: string, now: Date = new Date()): void {
-  const mentioned = DUE_NUDGES.filter((nudge) => reply.includes(nudge.command));
+  const mentioned = dueNudges().filter((nudge) => reply.includes(nudge.command));
   if (!mentioned.length) return;
   const today = localDay(now);
   const shownOn = readShownOn();
@@ -62,10 +85,10 @@ export function acknowledgeMentioned(reply: string, now: Date = new Date()): voi
 }
 
 export function dueNudgeSections(now: Date = new Date()): string[] {
-  if (!isOptedIn("dueReminders")) return [];
-  return DUE_NUDGES.map((nudge) => pendingToday(nudge.key, nudge.load(), now)).filter(
-    Boolean
-  );
+  return dueNudges()
+    .filter(isSwitchedOn)
+    .map((nudge) => pendingToday(nudge.key, nudge.load(), now))
+    .filter(Boolean);
 }
 
 export function dueNudgeReminder(now: Date = new Date()): string | null {

package/src/hooks/lib/entity-cards.ts

@@ -0,0 +1,112 @@
+/**
+ * Prompt-time cards for the people and companies a prompt names, so the user
+ * never has to re-explain who someone is. Reads files only; no model call.
+ */
+
+import { type Entity, list } from "../../tools/knowledge/lib";
+import {
+  buildNameIndex,
+  entityKey,
+  findMentions,
+  type Mention,
+  type NamedEntity,
+  type NameIndex,
+} from "./entity-names";
+import { identity } from "./settings";
+
+const MAX_CARDS = 3;
+const MAX_LATEST = 160;
+
+function stringList(value: unknown): string[] {
+  return Array.isArray(value)
+    ? value.filter((v): v is string => typeof v === "string")
+    : [];
+}
+
+function textField(entity: Entity, key: string): string {
+  const value = entity.frontmatter[key];
+  return typeof value === "string" ? value.trim() : "";
+}
+
+function namedEntity(entity: Entity): NamedEntity {
+  return {
+    slug: entity.slug,
+    domain: entity.domain === "Companies" ? "Companies" : "People",
+    title: entity.frontmatter.title,
+    aliases: stringList(entity.frontmatter.aliases),
+    domainName: textField(entity, "domain_name") || undefined,
+  };
+}
+
+export function loadKnownEntities(rootDir?: string): Entity[] {
+  return [...list("People", rootDir), ...list("Companies", rootDir)];
+}
+
+export function excludedNames(): string[] {
+  const id = identity();
+  return [id.principal.name, id.ai.name];
+}
+
+export function loadNameIndex(entities: Entity[]): NameIndex {
+  return buildNameIndex(entities.map(namedEntity), excludedNames());
+}
+
+function isSourceLine(line: string): boolean {
+  return (
+    line.startsWith("### ") ||
+    line.startsWith("<!--") ||
+    /^(?:role|importance|mentioned_as|sentiment): /.test(line)
+  );
+}
+
+/** The newest thing the store learned about this entity, in a sentence or two. */
+export function latestNote(body: string): string {
+  const sections = body.split(/\n(?=### )/);
+  const text = (sections.at(-1) ?? "")
+    .split("\n")
+    .map((l) => l.trim())
+    .filter((l) => l && !isSourceLine(l))
+    .join(" ")
+    .replace(/\*\*/g, "");
+  return text.length > MAX_LATEST ? `${text.slice(0, MAX_LATEST - 1)}…` : text;
+}
+
+function describe(entity: Entity): string {
+  const fields =
+    entity.domain === "People"
+      ? [
+          textField(entity, "position") || textField(entity, "role"),
+          textField(entity, "company"),
+        ]
+      : [textField(entity, "industry")];
+  const facts = [...fields, textField(entity, "relation")].filter(
+    (f) => f && f !== "subject"
+  );
+  const latest = latestNote(entity.body);
+  return [facts.join(", "), latest].filter(Boolean).join(". ");
+}
+
+function card(mention: Mention, bySlug: Map<string, Entity>): string {
+  if (mention.entities.length > 1) {
+    const names = mention.entities.map((e) => e.title).join(", ");
+    return `- "${mention.said}" could be: ${names}. Ask which one if it matters.`;
+  }
+  const entity = bySlug.get(entityKey(mention.entities[0]));
+  const summary = entity ? describe(entity) : "";
+  const name = `- **${mention.entities[0].title}**`;
+  return summary ? `${name}: ${summary}` : name;
+}
+
+export function entityReminder(prompt: string, entities: Entity[]): string | null {
+  const mentions = findMentions(prompt, loadNameIndex(entities)).slice(0, MAX_CARDS);
+  if (mentions.length === 0) return null;
+  const bySlug = new Map(entities.map((e) => [entityKey(e), e]));
+  return [
+    "**Known people and companies in this message** (PAL knowledge store):",
+    ...mentions.map((m) => card(m, bySlug)),
+  ].join("\n");
+}
+
+export function getEntityReminder(prompt: string): string | null {
+  return entityReminder(prompt, loadKnownEntities());
+}

package/src/hooks/lib/entity-extraction.ts

@@ -0,0 +1,334 @@
+/**
+ * Turning what the user said about people and companies into knowledge-store
+ * writes. A clear match or a new name is written; a name that could be more than
+ * one known entity waits in the review queue instead of being guessed.
+ */
+
+import { appendFileSync, existsSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import type {
+  CompanyInput,
+  IngestInput,
+  PersonInput,
+} from "../../tools/knowledge/ingest";
+import {
+  findMentions,
+  foldName,
+  indexedEntities,
+  isExcluded,
+  lookupName,
+  type NamedEntity,
+  type NameIndex,
+  proseOnly,
+} from "./entity-names";
+import { paths } from "./paths";
+import { isSystemText, stripInjectedTags } from "./prompt-text";
+
+export interface ExtractedEntity {
+  kind: "person" | "company";
+  name: string;
+  existing: string;
+  aliases: string[];
+  role: string;
+  organization: string;
+  relation: string;
+  fact: string;
+}
+
+export interface ReviewItem {
+  ts: string;
+  source: string;
+  id: string;
+  reason: "ambiguous" | "unknown-existing" | "first-name-only";
+  entity: ExtractedEntity;
+  candidates: string[];
+}
+
+export interface ExtractionPlan {
+  ingest: IngestInput;
+  review: ReviewItem[];
+}
+
+function closedObject<P extends Record<string, unknown>>(properties: P) {
+  return {
+    type: "object" as const,
+    additionalProperties: false,
+    properties,
+    required: Object.keys(properties),
+  };
+}
+
+export function extractionSchema() {
+  const text = { type: "string" as const };
+  const entity = closedObject({
+    kind: { type: "string" as const, enum: ["person", "company"] },
+    name: text,
+    existing: text,
+    aliases: { type: "array" as const, items: text },
+    role: text,
+    organization: text,
+    relation: text,
+    fact: text,
+  });
+  return closedObject({ entities: { type: "array" as const, items: entity } });
+}
+
+const MAX_TEXT = 4000;
+const MIN_TEXT = 20;
+const MAX_KNOWN = 120;
+const CURSOR_KEEP = 200;
+
+interface Message {
+  role: string;
+  content: unknown;
+}
+
+function userTexts(messages: Message[]): string[] {
+  return messages
+    .filter((m) => m.role === "user" && typeof m.content === "string")
+    .map((m) => stripInjectedTags(m.content as string))
+    .filter((t) => t.length > 0 && !isSystemText(t));
+}
+
+/** The user's words since the last extraction, and the new high-water mark. */
+export function unseenUserText(
+  messages: Message[],
+  seen: number
+): { text: string; count: number } {
+  const texts = userTexts(messages);
+  const fresh = texts.slice(Math.min(seen, texts.length));
+  const text = fresh.map((t, i) => `${i + 1}. ${proseOnly(t).trim()}`).join("\n");
+  return { text: text.slice(-MAX_TEXT), count: texts.length };
+}
+
+function hasUnknownProperName(text: string, ignored: Set<string>): boolean {
+  const sentences = proseOnly(text).split(/[.!?\n]+/);
+  return sentences.some((s) =>
+    s
+      .trim()
+      .split(/\s+/)
+      .slice(1)
+      .some((w) => /^\p{Lu}\p{Ll}/u.test(w) && !ignored.has(foldName(w)))
+  );
+}
+
+/** Cheap gate before a model call: a known name, or a capitalised word mid-sentence. */
+export function worthExtracting(
+  text: string,
+  index: NameIndex,
+  excluded: string[]
+): boolean {
+  if (proseOnly(text).trim().length < MIN_TEXT) return false;
+  if (findMentions(text, index).length > 0) return true;
+  return hasUnknownProperName(text, new Set(excluded.map(foldName)));
+}
+
+function knownLine(entity: NamedEntity): string {
+  const aliases =
+    entity.aliases.length > 0 ? ` (also: ${entity.aliases.join(", ")})` : "";
+  const kind = entity.domain === "People" ? "person" : "company";
+  return `${entity.slug} | ${kind} | ${entity.title}${aliases}`;
+}
+
+export function extractionSystem(principal: string, assistant: string): string {
+  return [
+    `You keep a contact book for ${principal}. From ${principal}'s own messages to an AI assistant, list the people and companies ${principal} talks about as part of their work and life.`,
+    `- Never list ${principal} or the assistant (${assistant}).`,
+    `- People: individuals ${principal} deals with (colleagues, clients, partners, friends, family, contacts). Skip public figures cited only for their work.`,
+    `- Companies: only organisations ${principal} has a relationship with: employer, own company, client, prospect, partner, contractor, school. Skip tools, products, platforms, languages and vendors that are merely used or discussed.`,
+    "- existing: the slug of the matching known entry below, or empty when it is someone new.",
+    "- aliases: other names the messages use for it (nickname, short form), not the main name.",
+    `- role, organization (a person's company), relation (how ${principal} relates to it: client, partner, colleague, friend, employer, prospect, own company): only what the messages state, else empty.`,
+    "- fact: one sentence of what the messages state about it, else empty. Never guess.",
+    "- Ignore names that appear only inside pasted logs, code or email headers.",
+    "Return an empty list when nobody qualifies.",
+  ].join("\n");
+}
+
+export function extractionUser(text: string, index: NameIndex): string {
+  const known = indexedEntities(index)
+    .filter((e) => !isExcluded(e, index))
+    .slice(0, MAX_KNOWN)
+    .map(knownLine);
+  return `Known entries (slug | kind | name):\n${known.join("\n") || "(none)"}\n\nMessages:\n${text}`;
+}
+
+function domainOf(kind: ExtractedEntity["kind"]): NamedEntity["domain"] {
+  return kind === "person" ? "People" : "Companies";
+}
+
+function namesUser(e: ExtractedEntity, excluded: string[]): boolean {
+  const own = new Set(excluded.filter(Boolean).map(foldName));
+  return [e.name, ...e.aliases].some((n) => own.has(foldName(n)));
+}
+
+type Resolution =
+  | { kind: "new" }
+  | { kind: "known"; entity: NamedEntity }
+  | { kind: "review"; reason: ReviewItem["reason"]; candidates: NamedEntity[] };
+
+function resolveExisting(e: ExtractedEntity, sameDomain: NamedEntity[]): Resolution {
+  const entity = sameDomain.find((c) => c.slug === e.existing);
+  return entity
+    ? { kind: "known", entity }
+    : { kind: "review", reason: "unknown-existing", candidates: [] };
+}
+
+/** "Dan" alone may be a known Daniel under a nickname the store hasn't seen yet. */
+function newcomer(e: ExtractedEntity): Resolution {
+  const firstNameOnly = e.kind === "person" && !/\s/.test(e.name.trim());
+  return firstNameOnly
+    ? { kind: "review", reason: "first-name-only", candidates: [] }
+    : { kind: "new" };
+}
+
+function resolveEntity(e: ExtractedEntity, index: NameIndex): Resolution {
+  const domain = domainOf(e.kind);
+  const sameDomain = indexedEntities(index).filter((c) => c.domain === domain);
+  if (e.existing) return resolveExisting(e, sameDomain);
+  const { entities, exact } = lookupName(e.name, index);
+  const candidates = entities.filter((c) => c.domain === domain);
+  if (candidates.length === 0) return newcomer(e);
+  if (exact && candidates.length === 1) return { kind: "known", entity: candidates[0] };
+  return { kind: "review", reason: "ambiguous", candidates };
+}
+
+function otherNames(e: ExtractedEntity, storedName: string): string[] {
+  const names = [e.name, ...e.aliases].map((n) => n.trim()).filter(Boolean);
+  return [...new Set(names)].filter((n) => foldName(n) !== foldName(storedName));
+}
+
+/** "Acme" for a stored "Acme Kft." links the person to that file, not a new stub. */
+function storedOrganization(organization: string, index: NameIndex): string | null {
+  if (!organization.trim()) return null;
+  const { entities, exact } = lookupName(organization, index);
+  const companies = entities.filter((c) => c.domain === "Companies");
+  return exact && companies.length === 1 ? companies[0].title : organization;
+}
+
+function personInput(
+  e: ExtractedEntity,
+  name: string,
+  index: NameIndex,
+  slug: string | null
+): PersonInput {
+  return {
+    name,
+    slug,
+    role: e.role || null,
+    company: storedOrganization(e.organization, index),
+    context: e.fact || null,
+    aliases: otherNames(e, name),
+    relation: e.relation || null,
+  };
+}
+
+function companyInput(
+  e: ExtractedEntity,
+  name: string,
+  slug: string | null
+): CompanyInput {
+  return {
+    name,
+    slug,
+    context: e.fact || null,
+    aliases: otherNames(e, name),
+    relation: e.relation || null,
+  };
+}
+
+/** Ingest input for one extracted entity: the known file it updates, or a new one. */
+export function ingestInput(
+  e: ExtractedEntity,
+  index: NameIndex,
+  known: NamedEntity | null,
+  newName?: string
+): IngestInput {
+  const name = known?.title ?? (newName?.trim() || e.name.trim());
+  const slug = known?.slug ?? null;
+  return e.kind === "person"
+    ? { people: [personInput(e, name, index, slug)] }
+    : { companies: [companyInput(e, name, slug)] };
+}
+
+export function planExtraction(
+  extracted: ExtractedEntity[],
+  index: NameIndex,
+  excluded: string[],
+  source: string
+): ExtractionPlan {
+  const plan: ExtractionPlan = { ingest: { people: [], companies: [] }, review: [] };
+  const queue = (
+    entity: ExtractedEntity,
+    reason: ReviewItem["reason"],
+    candidates: NamedEntity[]
+  ) =>
+    plan.review.push({
+      id: crypto.randomUUID().slice(0, 8),
+      ts: new Date().toISOString(),
+      source,
+      reason,
+      entity,
+      candidates: candidates.map((c) => c.slug).sort(),
+    });
+  for (const e of extracted) {
+    if (!e.name.trim() || namesUser(e, excluded)) continue;
+    const resolution = resolveEntity(e, index);
+    if (resolution.kind === "review") {
+      queue(e, resolution.reason, resolution.candidates);
+      continue;
+    }
+    if (resolution.kind === "known" && isExcluded(resolution.entity, index)) continue;
+    const known = resolution.kind === "known" ? resolution.entity : null;
+    const input = ingestInput(e, index, known);
+    plan.ingest.people?.push(...(input.people ?? []));
+    plan.ingest.companies?.push(...(input.companies ?? []));
+  }
+  return plan;
+}
+
+export function parseExtraction(output: string): ExtractedEntity[] {
+  try {
+    const parsed = JSON.parse(output) as { entities?: ExtractedEntity[] };
+    return Array.isArray(parsed.entities) ? parsed.entities : [];
+  } catch {
+    return [];
+  }
+}
+
+function cursorFile(): string {
+  return resolve(paths.state(), "entity-extraction.json");
+}
+
+function readCursors(): Record<string, number> {
+  const file = cursorFile();
+  if (!existsSync(file)) return {};
+  try {
+    return JSON.parse(readFileSync(file, "utf-8")) as Record<string, number>;
+  } catch {
+    return {};
+  }
+}
+
+export function seenCount(sessionId: string): number {
+  return readCursors()[sessionId] ?? 0;
+}
+
+export function markSeen(sessionId: string, count: number): void {
+  const cursors = Object.entries({ ...readCursors(), [sessionId]: count }).slice(
+    -CURSOR_KEEP
+  );
+  writeFileSync(
+    cursorFile(),
+    `${JSON.stringify(Object.fromEntries(cursors), null, 2)}\n`
+  );
+}
+
+export function reviewQueueFile(): string {
+  return resolve(paths.knowledge(), "_review.jsonl");
+}
+
+export function queueForReview(items: ReviewItem[]): void {
+  if (items.length === 0) return;
+  appendFileSync(reviewQueueFile(), items.map((i) => `${JSON.stringify(i)}\n`).join(""));
+}

package/src/hooks/lib/entity-names.ts

@@ -0,0 +1,242 @@
+/**
+ * Which known people and companies a text mentions. A lookup against the names
+ * already in the knowledge store, never a guess at what a name looks like.
+ */
+
+export interface NamedEntity {
+  slug: string;
+  domain: "People" | "Companies";
+  title: string;
+  aliases: string[];
+  domainName?: string;
+}
+
+interface Term {
+  tokens: string[];
+  entity: NamedEntity;
+  partial: boolean;
+}
+
+export interface NameIndex {
+  terms: Term[];
+  excluded: Set<string>;
+}
+
+export interface Mention {
+  said: string;
+  entities: NamedEntity[];
+}
+
+interface Token {
+  raw: string;
+  folded: string;
+  gapBefore: string;
+}
+
+const MIN_PARTIAL = 3;
+
+function nonProse(): RegExp[] {
+  return [
+    /```[\s\S]*?```/g,
+    /`[^`\n]*`/g,
+    /\bhttps?:\/\/\S+/g,
+    /[\w.+-]+@[\w-]+(?:\.[\w-]+)+/g,
+    /[\w.-]+(?:\/[\w.-]+)+/g,
+    /<[^>\n]*>/g,
+  ];
+}
+
+function withoutLegalSuffix(name: string): string {
+  return name.replace(
+    /\s+(?:kft|nyrt|zrt|bt|kkt|ltd|inc|llc|gmbh|korlatolt felelossegu tarsasag)\.?$/,
+    ""
+  );
+}
+
+function breaksSentence(gap: string): boolean {
+  return /[.!?:;\n]/.test(gap);
+}
+
+export function foldName(name: string): string {
+  return name
+    .normalize("NFKD")
+    .replace(/\p{M}/gu, "")
+    .toLowerCase()
+    .replace(/['’]s$/, "")
+    .replace(/[.,]+$/, "")
+    .trim();
+}
+
+export function proseOnly(text: string): string {
+  return nonProse().reduce((out, re) => out.replace(re, " "), text);
+}
+
+function tokenize(text: string): Token[] {
+  const tokens: Token[] = [];
+  let last = 0;
+  for (const m of text.matchAll(/[\p{L}\p{N}](?:[\p{L}\p{N}'’.-]*[\p{L}\p{N}])?/gu)) {
+    const start = m.index ?? 0;
+    tokens.push({
+      raw: m[0],
+      folded: foldName(m[0]),
+      gapBefore: text.slice(last, start),
+    });
+    last = start + m[0].length;
+  }
+  return tokens;
+}
+
+function words(name: string): string[] {
+  return tokenize(name).map((t) => t.folded);
+}
+
+function companyNames(entity: NamedEntity): string[] {
+  const bare = withoutLegalSuffix(foldName(entity.title));
+  const site = entity.domainName ? foldName(entity.domainName).split(".")[0] : "";
+  return [entity.title, bare, site, ...entity.aliases];
+}
+
+function personNames(entity: NamedEntity): string[] {
+  const parts = words(entity.title);
+  const reversed = parts.length === 2 ? `${parts[1]} ${parts[0]}` : "";
+  return [entity.title, reversed, ...entity.aliases];
+}
+
+function fullTerms(entity: NamedEntity): Term[] {
+  const names = entity.domain === "People" ? personNames(entity) : companyNames(entity);
+  return names
+    .map(words)
+    .filter((tokens) => tokens.join(" ").length >= 2)
+    .map((tokens) => ({ tokens, entity, partial: false }));
+}
+
+function partialTerms(entity: NamedEntity): Term[] {
+  if (entity.domain !== "People") return [];
+  const parts = words(entity.title);
+  if (parts.length < 2) return [];
+  return parts
+    .filter((p) => p.length >= MIN_PARTIAL)
+    .map((p) => ({ tokens: [p], entity, partial: true }));
+}
+
+/** Names in `excludedNames` (the user, the assistant) are indexed so they consume
+ *  their words, but never reported. */
+export function buildNameIndex(
+  entities: NamedEntity[],
+  excludedNames: string[]
+): NameIndex {
+  const excludedFolded = new Set(excludedNames.filter(Boolean).map(foldName));
+  const excluded = new Set(
+    entities
+      .filter((e) => fullTerms(e).some((t) => excludedFolded.has(t.tokens.join(" "))))
+      .map(entityKey)
+  );
+  const terms = entities.flatMap((e) => [...fullTerms(e), ...partialTerms(e)]);
+  terms.sort(
+    (a, b) => Number(a.partial) - Number(b.partial) || b.tokens.length - a.tokens.length
+  );
+  return { terms, excluded };
+}
+
+function matchesAt(tokens: Token[], at: number, term: Term): boolean {
+  return term.tokens.every((w, i) => tokens[at + i]?.folded === w);
+}
+
+function isCapitalized(token: Token | undefined): boolean {
+  return Boolean(token && /^\p{Lu}/u.test(token.raw));
+}
+
+function joinedTo(token: Token | undefined): boolean {
+  return Boolean(
+    token && /^\s+$/.test(token.gapBefore) && !breaksSentence(token.gapBefore)
+  );
+}
+
+function startsSentence(tokens: Token[], at: number): boolean {
+  return at === 0 || breaksSentence(tokens[at].gapBefore);
+}
+
+/** "Daniel Miessler" is not a known Dániel: a lone given name next to an unknown
+ *  capitalised word belongs to someone else. */
+function besideUnknownName(tokens: Token[], at: number): boolean {
+  const next = tokens[at + 1];
+  if (joinedTo(next) && isCapitalized(next)) return true;
+  const prev = tokens[at - 1];
+  return joinedTo(tokens[at]) && isCapitalized(prev) && !startsSentence(tokens, at - 1);
+}
+
+function isLoneWordOfPerson(term: Term): boolean {
+  return term.entity.domain === "People" && term.tokens.length === 1;
+}
+
+function termsAt(index: NameIndex, tokens: Token[], at: number): Term[] {
+  const first = index.terms.find((t) => matchesAt(tokens, at, t));
+  if (!first) return [];
+  if (isLoneWordOfPerson(first) && besideUnknownName(tokens, at)) return [];
+  return index.terms.filter(
+    (t) =>
+      t.partial === first.partial &&
+      t.tokens.length === first.tokens.length &&
+      matchesAt(tokens, at, t)
+  );
+}
+
+function addMention(
+  found: Map<string, Mention>,
+  said: string,
+  terms: Term[],
+  index: NameIndex
+) {
+  const entities = distinctEntities(terms);
+  if (entities.some((e) => isExcluded(e, index))) return;
+  const key = entities.map(entityKey).sort().join("|");
+  if (!found.has(key)) found.set(key, { said, entities });
+}
+
+export function findMentions(text: string, index: NameIndex): Mention[] {
+  const tokens = tokenize(proseOnly(text));
+  const found = new Map<string, Mention>();
+  let at = 0;
+  while (at < tokens.length) {
+    const terms = termsAt(index, tokens, at);
+    const width = terms[0]?.tokens.length ?? 1;
+    if (terms.length > 0) {
+      const said = tokens
+        .slice(at, at + width)
+        .map((t) => t.raw)
+        .join(" ");
+      addMention(found, said, terms, index);
+    }
+    at += width;
+  }
+  return [...found.values()];
+}
+
+/** The entities a name could mean; `exact` when it is someone's full name or alias
+ *  rather than one word of a longer name. */
+export function lookupName(
+  name: string,
+  index: NameIndex
+): { entities: NamedEntity[]; exact: boolean } {
+  const folded = words(name).join(" ");
+  const named = (t: Term) => t.tokens.join(" ") === folded;
+  const full = index.terms.filter((t) => !t.partial && named(t));
+  if (full.length > 0) return { entities: distinctEntities(full), exact: true };
+  return { entities: distinctEntities(index.terms.filter(named)), exact: false };
+}
+
+export function indexedEntities(index: NameIndex): NamedEntity[] {
+  return distinctEntities(index.terms);
+}
+
+export function isExcluded(entity: NamedEntity, index: NameIndex): boolean {
+  return index.excluded.has(entityKey(entity));
+}
+
+export function entityKey(entity: { domain: string; slug: string }): string {
+  return `${entity.domain}/${entity.slug}`;
+}
+
+function distinctEntities(terms: Term[]): NamedEntity[] {
+  return [...new Map(terms.map((t) => [entityKey(t.entity), t.entity])).values()];
+}

package/src/hooks/lib/entity-review.ts

@@ -0,0 +1,88 @@
+/**
+ * The user's answers to the extraction review queue: an accepted item is written
+ * to the entity the user names (or a new one), a rejected one is dropped.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { ingestEntities } from "../../tools/knowledge/ingest";
+import { loadKnownEntities, loadNameIndex } from "./entity-cards";
+import { ingestInput, type ReviewItem, reviewQueueFile } from "./entity-extraction";
+import { indexedEntities, type NamedEntity, type NameIndex } from "./entity-names";
+
+export interface AcceptChoice {
+  as?: string;
+  name?: string;
+}
+
+export interface Accepted {
+  item: ReviewItem;
+  slug: string;
+  created: boolean;
+}
+
+function parseItem(line: string): ReviewItem[] {
+  try {
+    return [JSON.parse(line) as ReviewItem];
+  } catch {
+    return [];
+  }
+}
+
+export function pendingReviews(): ReviewItem[] {
+  const file = reviewQueueFile();
+  if (!existsSync(file)) return [];
+  return readFileSync(file, "utf-8").split("\n").filter(Boolean).flatMap(parseItem);
+}
+
+function takeFromQueue(id: string): ReviewItem | null {
+  const items = pendingReviews();
+  const item = items.find((i) => i.id === id);
+  if (!item) return null;
+  const rest = items.filter((i) => i !== item);
+  writeFileSync(reviewQueueFile(), rest.map((i) => `${JSON.stringify(i)}\n`).join(""));
+  return item;
+}
+
+function chosenEntity(
+  item: ReviewItem,
+  slug: string | undefined,
+  index: NameIndex
+): NamedEntity | null {
+  if (!slug) return null;
+  const domain = item.entity.kind === "person" ? "People" : "Companies";
+  const entity = indexedEntities(index).find(
+    (e) => e.domain === domain && e.slug === slug
+  );
+  if (!entity) throw new Error(`no ${domain} entry with slug "${slug}"`);
+  return entity;
+}
+
+export function loadEntityReviewNudge(): string {
+  const count = pendingReviews().length;
+  if (count === 0) return "";
+  const waiting =
+    count === 1 ? "1 person or company waits" : `${count} people or companies wait`;
+  return [
+    "## Entity Review Due",
+    `👥 ${waiting} for the user's answer before the knowledge store records them — offer \`pal cli knowledge review\`.`,
+  ].join("\n");
+}
+
+export function rejectReview(id: string): ReviewItem | null {
+  return takeFromQueue(id);
+}
+
+/** Writes the item to `as` when given, else to a new entity named `name` or as extracted. */
+export function acceptReview(id: string, choice: AcceptChoice = {}): Accepted | null {
+  const queued = pendingReviews().find((i) => i.id === id);
+  if (!queued) return null;
+  const index = loadNameIndex(loadKnownEntities());
+  const known = chosenEntity(queued, choice.as, index);
+  const result = ingestEntities(
+    ingestInput(queued.entity, index, known, choice.name),
+    queued.source
+  );
+  takeFromQueue(id);
+  const written = result.people[0] ?? result.companies[0];
+  return { item: queued, slug: written.slug, created: written.created };
+}

package/src/hooks/lib/inference.ts

@@ -580,8 +580,10 @@ async function inferenceViaAntigravitySpawn(
  *   --disable-builtin-mcps    → no MCP servers in the child (extra safety)
  *   --no-auto-update          → prevent CLI self-update from delaying the spawn
  *   --no-color                → clean stdout for capture
- *   --allow-all-tools         → REQUIRED for non-interactive mode (without it,
- *                                copilot prompts for tool-use confirmation)
+ *   --available-tools=none    → Copilot has no "no tools" flag; an allowlist
+ *                                naming an unknown tool hides every tool
+ *   --deny-tool=…             → backstop: deny rules win over any allow rule
+ *   --silent                  → keeps the tool-filter notices out of stdout
  *
  * Copilot has no --system-prompt flag, so system + user + JSON-schema are
  * concatenated into one prompt delivered on stdin. `-p/--prompt` is deliberately
@@ -595,7 +597,11 @@ export function buildCopilotArgs(_opts: InferenceOptions): string[] {
     "--disable-builtin-mcps",
     "--no-auto-update",
     "--no-color",
-    "--allow-all-tools",
+    "--silent",
+    "--available-tools=none",
+    "--deny-tool=shell",
+    "--deny-tool=write",
+    "--deny-tool=url",
   ];
 }
 

package/src/hooks/lib/stop.ts

@@ -168,6 +168,7 @@ export async function runStopHandlers(
   // any in-hook budget. These spawn detached bun subprocesses that run the
   // inference and write results to disk; they don't block this hook.
   await detachSessionIntelligence(transcript, options.sessionId);
+  await detachEntityExtraction(transcript, options.sessionId);
   await detachFailurePrinciple(transcript);
   detachAgenda(options.sessionId);
   // Failure auto-graduation is intentionally NOT wired here: every pattern it
@@ -325,6 +326,24 @@ async function detachSessionIntelligence(
   }
 }
 
+async function detachEntityExtraction(
+  transcript: string,
+  sessionId?: string
+): Promise<void> {
+  if (!sessionId) return;
+  try {
+    const transcriptPath = await writeTranscriptTmp(transcript);
+    const scriptPath = resolve(assets.hooks(), "handlers", "entity-extraction.ts");
+    spawnDetachedInference(
+      scriptPath,
+      ["--run", sessionId, transcriptPath],
+      "entity-extraction"
+    );
+  } catch (err) {
+    logError("detachEntityExtraction", err);
+  }
+}
+
 /**
  * If a pending-failure exists, rename it to a unique path (race-free claim),
  * write the transcript to tmp, spawn the failure-principle handler detached.

package/src/hooks/lib/token-usage.ts

@@ -14,6 +14,7 @@ type TokenCaller =
   | "failure"
   | "session-name"
   | "session-intelligence"
+  | "entity-extraction"
   | "relationship"
   | "self-model"
   | "agenda-serves"

package/src/tools/knowledge/ingest.ts

@@ -29,7 +29,14 @@ import {
 
 // --- Public input shape -----------------------------------------------------
 
-export interface PersonInput {
+interface Addressing {
+  aliases?: string[] | null;
+  relation?: string | null;
+  /** The stored file to update, when its slug is not derived from the name or domain. */
+  slug?: string | null;
+}
+
+export interface PersonInput extends Addressing {
   name: string;
   role?: string | null;
   title?: string | null;
@@ -40,7 +47,7 @@ export interface PersonInput {
   [extra: string]: unknown;
 }
 
-export interface CompanyInput {
+export interface CompanyInput extends Addressing {
   name: string;
   domain?: string | null;
   industry?: string | null;
@@ -201,7 +208,17 @@ function newPersonEntity(input: PersonInput, slug: string): Entity {
   if (Object.keys(socials).length > 0) {
     fm.socials = Object.entries(socials).map(([k, v]) => `${k}:${v}`);
   }
-  return { domain: "People", slug, frontmatter: fm, body: "" };
+  return { domain: "People", slug, frontmatter: withAddressing(fm, input), body: "" };
+}
+
+/** How the user refers to an entity and stands towards it — both only ever grow. */
+function withAddressing(fm: EntityFrontmatter, input: Addressing): EntityFrontmatter {
+  const prior = Array.isArray(fm.aliases) ? (fm.aliases as string[]) : undefined;
+  const aliases = mergeStringArray(prior, input.aliases ?? undefined);
+  if (aliases.length > 0) fm.aliases = aliases;
+  const relation = mergeScalar(fm.relation, input.relation);
+  if (relation) fm.relation = relation;
+  return fm;
 }
 
 function newCompanyEntity(input: CompanyInput, slug: string): Entity {
@@ -220,7 +237,7 @@ function newCompanyEntity(input: CompanyInput, slug: string): Entity {
   if (input.industry) fm.industry = input.industry;
   if (input.mentioned_as) fm.mentioned_as = input.mentioned_as;
   if (input.sentiment) fm.sentiment = input.sentiment;
-  return { domain: "Companies", slug, frontmatter: fm, body: "" };
+  return { domain: "Companies", slug, frontmatter: withAddressing(fm, input), body: "" };
 }
 
 function mergePerson(prior: Entity, input: PersonInput): Entity {
@@ -248,7 +265,7 @@ function mergePerson(prior: Entity, input: PersonInput): Entity {
   if (Object.keys(socials).length > 0) {
     fm.socials = Object.entries(socials).map(([k, v]) => `${k}:${v}`);
   }
-  return { ...prior, frontmatter: fm };
+  return { ...prior, frontmatter: withAddressing(fm, input) };
 }
 
 function mergeCompany(prior: Entity, input: CompanyInput): Entity {
@@ -260,7 +277,7 @@ function mergeCompany(prior: Entity, input: CompanyInput): Entity {
   if (input.industry) {
     fm.tags = mergeStringArray(fm.tags, industryToTopicTags(input.industry));
   }
-  return { ...prior, frontmatter: fm };
+  return { ...prior, frontmatter: withAddressing(fm, input) };
 }
 
 function upsertPerson(
@@ -268,7 +285,7 @@ function upsertPerson(
   sourceId: string,
   rootDir?: string
 ): UpsertResult {
-  const slug = slugify(input.name);
+  const slug = input.slug || slugify(input.name);
   if (!slug) throw new Error(`ingest: cannot slugify person name "${input.name}"`);
   const prior = load("People", slug, rootDir);
   const created = prior === null;
@@ -294,7 +311,7 @@ function upsertCompany(
   rootDir?: string
 ): UpsertResult {
   const baseKey = input.domain?.trim() ? input.domain : input.name;
-  const slug = slugify(baseKey);
+  const slug = input.slug || slugify(baseKey);
   if (!slug) throw new Error(`ingest: cannot slugify company "${input.name}"`);
   const prior = load("Companies", slug, rootDir);
   const created = prior === null;