kibi-agent-core 0.7.0 → 0.8.1

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # kibi-agent-core
 
+## 0.8.1
+
+### Patch Changes
+
+- f4c5822: After a migration, the `kb_apply_plan` digest of the remaining plan now says when an automatic action in it is blocked: it waits for the actions in its `dependsOn` and needs no approval until a later plan shows it ready. Before, a blocked automatic action looked like something left to approve. The Claude hook's firm-edit question no longer prints a double full stop after a requirement title that ends in one.
+
+  The digest's `next` text appends a count of blocked automatic actions when there are any. `firmEditConfirmation` in `kibi-agent-core/decision-guard` trims a trailing full stop from the named requirements before closing the sentence.
+
+## 0.8.0
+
+### Minor Changes
+
+- 00d2871: The Codex, Cursor and ZCode hooks now act on recorded decisions while the work happens, as the Claude Code hooks do.
+  - **Firm requirements before the edit.** When an edit changes code that implements a current firm requirement, the pre-edit hook tells the agent to ask the person before an edit that breaks that rule, naming the rule; once per requirement per session. These hosts cannot put the question to the person from a hook (Codex has no "ask", Cursor does not enforce one, and the ZCode adapter stays advisory), so this is a notice to the agent. Set `KIBI_CONFIRM_FIRM_EDITS=0` to turn it off.
+  - **Stated rules are captured.** A prompt that reads as a rule ("must", "never", "from now on") gets the note that recording it with `kb_upsert` is part of the change: through a new `UserPromptSubmit` hook in Codex and ZCode, and in Cursor through a new `beforeSubmitPrompt` hook whose note arrives with the next pre-edit message. When a session changed source files and wrote nothing with `kb_upsert`, the stop hook asks once for the decision to be recorded (Codex continues the turn with it; Cursor adds it to the stop follow-up; ZCode adds it to the Stop context).
+  - **Codex unlinked-file candidates** are ranked by the latest prompt's words as well as the path's.
+
+  `kibi-agent-core`: new `kibi-agent-core/decision-guard` entry with the host-neutral pieces (`firmRequirementsTouched`, `firmEditNotice`, `confirmFirmEdits`, the prompt and stop notes, and per-session markers). `kibi-claude` now imports its firm-edit and capture texts from it; behavior is unchanged.
+
 ## 0.7.0
 
 ### Minor Changes

package/dist/decision-guard.d.ts

@@ -0,0 +1,90 @@
+import type { EntitySummary, IndexedSymbol } from "./knowledge-index.js";
+import { type LineRange, type Summarize } from "./snippets.js";
+/**
+ * Host-neutral pieces of the hooks that act on recorded decisions while the
+ * work happens: which firm requirements an edit changes, the confirmation and
+ * agent texts for it, and the prompt-time and stop-time capture notes. Each
+ * host adapter decides how to put the confirmation to the person.
+ */
+/** Set to `0`, `false` or `off` to stop asking before edits of firm requirements. */
+export declare const CONFIRM_FIRM_EDITS_ENV = "KIBI_CONFIRM_FIRM_EDITS";
+/** False when the operator turned the firm-edit confirmation off. */
+export declare function confirmFirmEdits(env: NodeJS.ProcessEnv): boolean;
+/**
+ * The current firm requirements an edit changes that are not in `confirmed`:
+ * those implemented by the symbols the edit lands in, or by every symbol of
+ * the file for a whole-file write. An edit whose location is unknown, or
+ * outside every symbol, changes none.
+ */
+export declare function firmRequirementsTouched(input: {
+    symbols: readonly IndexedSymbol[];
+    focus: readonly LineRange[] | undefined;
+    wholeFile: boolean;
+    summarize: Summarize;
+    confirmed?: ReadonlySet<string>;
+}): {
+    ids: string[];
+    symbol: IndexedSymbol | undefined;
+};
+/**
+ * The permission-prompt text for an edit of a firm requirement's code: what
+ * the edit changes, the requirements, and what allowing it means. The person
+ * reads it, so it names the rule rather than the mechanism.
+ */
+export declare function firmEditConfirmation(where: string, requirements: readonly EntitySummary[]): string;
+/** What the agent is told when its edit was put to the person. */
+export declare function firmEditContext(ids: readonly string[]): string;
+/** The phrase that makes `prompt` read as a rule, or undefined. */
+export declare function statedRule(prompt: string): string | undefined;
+/** Prompt-time note for a request that reads as a rule or decision. */
+export declare function rulePromptNote(phrase: string): string;
+/**
+ * Stop-time note for a session that changed source files and wrote nothing
+ * to the knowledge base.
+ */
+export declare function captureReminder(rulePrompt: boolean): string;
+/**
+ * Pre-edit context for hosts whose pre-tool hook cannot put a call to the
+ * person: the edit is named as a change to the person's rule, and the agent
+ * is told to ask before making it unless it keeps the rule.
+ */
+export declare function firmEditNotice(where: string, requirements: readonly EntitySummary[]): string;
+/** Where one host session's decision-guard markers live. */
+export type DecisionSession = {
+    stateDir: string | undefined;
+    sessionId: string | undefined;
+};
+/** Session markers the decision guard keeps. */
+export type DecisionFlag = "source-edited" | "kb-recorded" | "rule-prompt" | "capture-asked";
+/** Set a session marker; best effort. */
+export declare function markDecisionFlag(session: DecisionSession, flag: DecisionFlag): void;
+export declare function hasDecisionFlag(session: DecisionSession, flag: DecisionFlag): boolean;
+/**
+ * True the first time `flag` is claimed in the session. Without a state
+ * directory nothing can be remembered, so nothing is claimed.
+ */
+export declare function claimDecisionFlag(session: DecisionSession, flag: DecisionFlag): boolean;
+/**
+ * Remember a submitted prompt's topic words (for unlinked-file candidates)
+ * and whether it read as a rule. Returns the rule phrase, if any.
+ */
+export declare function recordRequest(session: DecisionSession, prompt: string): string | undefined;
+/** Topic words of the session's latest prompt, or none. */
+export declare function requestWords(session: DecisionSession): string[];
+/**
+ * Whether the stop should ask for the session's decision to be recorded:
+ * source changed, nothing was written with kb_upsert, and the session has
+ * not been asked yet (claiming the ask).
+ */
+export declare function claimCaptureReminder(session: DecisionSession): boolean;
+/** Firm requirements the agent was already told about this session. */
+export declare function settledFirmRequirements(session: DecisionSession): Set<string>;
+/** Remember that the agent was told about these firm requirements. */
+export declare function settleFirmRequirements(session: DecisionSession, ids: readonly string[]): void;
+/**
+ * Keep a prompt's rule note for a host whose prompt hook cannot add context,
+ * so the next hook that can speak to the agent delivers it.
+ */
+export declare function holdRuleNote(session: DecisionSession, phrase: string): void;
+/** The held rule note, removed so it is delivered once; or undefined. */
+export declare function takeRuleNote(session: DecisionSession): string | undefined;

package/dist/decision-guard.js

@@ -0,0 +1,276 @@
+// implements REQ-claude-firm-edit-confirmation, REQ-claude-decision-capture-nudges, REQ-agent-hosts-decision-guard
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { requestTopicWords } from "./requirement-candidates.js";
+import { focusedSymbols, implementedRequirementIds, isRetiredStatus, } from "./snippets.js";
+/**
+ * Host-neutral pieces of the hooks that act on recorded decisions while the
+ * work happens: which firm requirements an edit changes, the confirmation and
+ * agent texts for it, and the prompt-time and stop-time capture notes. Each
+ * host adapter decides how to put the confirmation to the person.
+ */
+/** Set to `0`, `false` or `off` to stop asking before edits of firm requirements. */
+export const CONFIRM_FIRM_EDITS_ENV = "KIBI_CONFIRM_FIRM_EDITS";
+// implements REQ-claude-firm-edit-confirmation, REQ-agent-hosts-decision-guard
+/** False when the operator turned the firm-edit confirmation off. */
+export function confirmFirmEdits(env) {
+    const value = env[CONFIRM_FIRM_EDITS_ENV]?.trim().toLowerCase();
+    return !(value === "0" || value === "false" || value === "off");
+}
+// implements REQ-claude-firm-edit-confirmation, REQ-agent-hosts-decision-guard
+/**
+ * The current firm requirements an edit changes that are not in `confirmed`:
+ * those implemented by the symbols the edit lands in, or by every symbol of
+ * the file for a whole-file write. An edit whose location is unknown, or
+ * outside every symbol, changes none.
+ */
+export function firmRequirementsTouched(input) {
+    const touched = input.wholeFile
+        ? input.symbols
+        : focusedSymbols(input.symbols, input.focus);
+    const ids = implementedRequirementIds(touched).filter((id) => {
+        if (input.confirmed?.has(id))
+            return false;
+        const summary = input.summarize(id);
+        return summary.firmness === "firm" && !isRetiredStatus(summary.status);
+    });
+    return { ids, symbol: input.wholeFile ? undefined : touched[0] };
+}
+// implements REQ-claude-firm-edit-confirmation
+/**
+ * The permission-prompt text for an edit of a firm requirement's code: what
+ * the edit changes, the requirements, and what allowing it means. The person
+ * reads it, so it names the rule rather than the mechanism.
+ */
+export function firmEditConfirmation(where, requirements) {
+    // Every one is firm, so each is named by id and title only.
+    const shown = requirements
+        .slice(0, 2)
+        .map((summary) => summary.title ? `${summary.id}: ${summary.title}` : summary.id);
+    const more = requirements.length > shown.length
+        ? ` (+${requirements.length - shown.length} more)`
+        : "";
+    const noun = requirements.length === 1 ? "a firm requirement" : "firm requirements";
+    // A title that ends in a full stop would read "preference.. Allow".
+    const named = `${shown.join("; ")}${more}`.replace(/\.+$/, "");
+    return `Kibi: this edit changes ${where}, which implements ${noun} recorded in the knowledge base: ${named}. Allow it if the change keeps ${requirements.length === 1 ? "that requirement" : "them"}, or if you mean to change ${requirements.length === 1 ? "the requirement" : "them"} too.`;
+}
+// implements REQ-claude-firm-edit-confirmation
+/** What the agent is told when its edit was put to the person. */
+export function firmEditContext(ids) {
+    const named = ids.slice(0, 2).join(", ");
+    return [
+        `Kibi asked the person to confirm this edit because it changes code that implements firm ${ids.length === 1 ? "requirement" : "requirements"} ${named}.`,
+        "If the edit was declined or could not be confirmed, the requirement stands: name it and ask the person how to proceed, rather than reaching the same change another way. If it was allowed and the change alters what the requirement says, the requirement is updated with kb_upsert in this change.",
+    ].join("\n");
+}
+/**
+ * Phrases that make a request read as a rule or decision. Matching is
+ * deliberately loose: the note it triggers only asks whether there is
+ * something to record.
+ */
+const RULE_PHRASES = /\b(?:from now on|going forward|must(?:n['’]t| not)?|should (?:always|never)|never|always|is not allowed|are not allowed|not be allowed|only (?:allow|admins?|owners?)|is required|are required|has to|have to)\b/i;
+// implements REQ-claude-decision-capture-nudges, REQ-agent-hosts-decision-guard
+/** The phrase that makes `prompt` read as a rule, or undefined. */
+export function statedRule(prompt) {
+    const match = RULE_PHRASES.exec(prompt);
+    return match ? match[0].toLowerCase() : undefined;
+}
+// implements REQ-claude-decision-capture-nudges, REQ-agent-hosts-decision-guard
+/** Prompt-time note for a request that reads as a rule or decision. */
+export function rulePromptNote(phrase) {
+    return [
+        `Kibi: this request reads as a rule or decision (it says "${phrase}").`,
+        "A rule the person states is project knowledge: kb_search shows whether a recorded requirement already says something about it (changing a firm one is a question for the person first), and a new or changed rule is recorded with kb_upsert (a requirement, firm because the person stated it, with the implements link from the code that enforces it) as part of this change, not after it.",
+    ].join("\n");
+}
+// implements REQ-claude-decision-capture-nudges, REQ-agent-hosts-decision-guard
+/**
+ * Stop-time note for a session that changed source files and wrote nothing
+ * to the knowledge base.
+ */
+export function captureReminder(rulePrompt) {
+    return [
+        rulePrompt
+            ? "Kibi: a request this session read as a rule or decision, the session changed source files, and nothing was recorded in the knowledge base."
+            : "Kibi: this session changed source files and recorded nothing in the knowledge base.",
+        "A decision the person stated or this change made (a rule, a limit, a default, who may do what) is recorded with kb_upsert as a requirement linked to the code that implements it before the work is reported done; when there was none, the final report says so in one line.",
+    ].join("\n");
+}
+// implements REQ-agent-hosts-decision-guard
+/**
+ * Pre-edit context for hosts whose pre-tool hook cannot put a call to the
+ * person: the edit is named as a change to the person's rule, and the agent
+ * is told to ask before making it unless it keeps the rule.
+ */
+export function firmEditNotice(where, requirements) {
+    const shown = requirements
+        .slice(0, 2)
+        .map((summary) => summary.title ? `${summary.id}: ${summary.title}` : summary.id);
+    const more = requirements.length > shown.length
+        ? ` (+${requirements.length - shown.length} more)`
+        : "";
+    const one = requirements.length === 1;
+    return [
+        `Kibi: this edit changes ${where}, which implements ${one ? "a firm requirement" : "firm requirements"}, a rule the person set: ${shown.join("; ")}${more}.`,
+        `Unless the edit keeps ${one ? "that rule" : "those rules"}, ask the person before making it and name the rule; change the requirement with kb_upsert in this change only when they say so.`,
+    ].join("\n");
+}
+function sessionPath(session, name) {
+    if (!session.stateDir)
+        return undefined;
+    const key = createHash("sha256")
+        .update(session.sessionId?.trim() || "unattributed")
+        .digest("hex")
+        .slice(0, 32);
+    return path.join(session.stateDir, "decision-guard", key, name);
+}
+function writeMarker(file, content, flag) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, content, { flag });
+}
+// implements REQ-agent-hosts-decision-guard
+/** Set a session marker; best effort. */
+export function markDecisionFlag(session, flag) {
+    const file = sessionPath(session, flag);
+    if (!file)
+        return;
+    try {
+        writeMarker(file, "", "w");
+    }
+    catch {
+        // Markers are best effort; a lost one means a note may repeat or skip.
+    }
+}
+// implements REQ-agent-hosts-decision-guard
+export function hasDecisionFlag(session, flag) {
+    const file = sessionPath(session, flag);
+    return file !== undefined && fs.existsSync(file);
+}
+// implements REQ-agent-hosts-decision-guard
+/**
+ * True the first time `flag` is claimed in the session. Without a state
+ * directory nothing can be remembered, so nothing is claimed.
+ */
+export function claimDecisionFlag(session, flag) {
+    const file = sessionPath(session, flag);
+    if (!file)
+        return false;
+    try {
+        writeMarker(file, "", "wx");
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// implements REQ-agent-hosts-decision-guard
+/**
+ * Remember a submitted prompt's topic words (for unlinked-file candidates)
+ * and whether it read as a rule. Returns the rule phrase, if any.
+ */
+export function recordRequest(session, prompt) {
+    const rule = statedRule(prompt);
+    const file = sessionPath(session, "request-words.json");
+    if (file) {
+        try {
+            writeMarker(file, JSON.stringify(requestTopicWords(prompt)), "w");
+        }
+        catch {
+            // Best effort.
+        }
+    }
+    if (rule !== undefined)
+        markDecisionFlag(session, "rule-prompt");
+    return rule;
+}
+// implements REQ-agent-hosts-decision-guard
+/** Topic words of the session's latest prompt, or none. */
+export function requestWords(session) {
+    const file = sessionPath(session, "request-words.json");
+    if (!file)
+        return [];
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+        return Array.isArray(parsed)
+            ? parsed.filter((word) => typeof word === "string")
+            : [];
+    }
+    catch {
+        return [];
+    }
+}
+// implements REQ-agent-hosts-decision-guard
+/**
+ * Whether the stop should ask for the session's decision to be recorded:
+ * source changed, nothing was written with kb_upsert, and the session has
+ * not been asked yet (claiming the ask).
+ */
+export function claimCaptureReminder(session) {
+    return (hasDecisionFlag(session, "source-edited") &&
+        !hasDecisionFlag(session, "kb-recorded") &&
+        claimDecisionFlag(session, "capture-asked"));
+}
+function readSettled(file) {
+    if (!file)
+        return [];
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+        return Array.isArray(parsed)
+            ? parsed.filter((id) => typeof id === "string")
+            : [];
+    }
+    catch {
+        return [];
+    }
+}
+// implements REQ-agent-hosts-decision-guard
+/** Firm requirements the agent was already told about this session. */
+export function settledFirmRequirements(session) {
+    return new Set(readSettled(sessionPath(session, "firm-settled.json")));
+}
+// implements REQ-agent-hosts-decision-guard
+/** Remember that the agent was told about these firm requirements. */
+export function settleFirmRequirements(session, ids) {
+    const file = sessionPath(session, "firm-settled.json");
+    if (!file)
+        return;
+    try {
+        writeMarker(file, JSON.stringify([...new Set([...readSettled(file), ...ids])]), "w");
+    }
+    catch {
+        // Best effort: a lost write means the notice may repeat.
+    }
+}
+// implements REQ-agent-hosts-decision-guard
+/**
+ * Keep a prompt's rule note for a host whose prompt hook cannot add context,
+ * so the next hook that can speak to the agent delivers it.
+ */
+export function holdRuleNote(session, phrase) {
+    const file = sessionPath(session, "rule-note");
+    if (!file)
+        return;
+    try {
+        writeMarker(file, rulePromptNote(phrase), "w");
+    }
+    catch {
+        // Best effort.
+    }
+}
+// implements REQ-agent-hosts-decision-guard
+/** The held rule note, removed so it is delivered once; or undefined. */
+export function takeRuleNote(session) {
+    const file = sessionPath(session, "rule-note");
+    if (!file)
+        return undefined;
+    try {
+        const note = fs.readFileSync(file, "utf8");
+        fs.rmSync(file, { force: true });
+        return note || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+export * from "./decision-guard.js";
 export * from "./hook-usage-log.js";
 export * from "./kb-mcp-tools.js";
 export * from "./knowledge-index.js";

package/dist/index.js

@@ -1,3 +1,4 @@
+export * from "./decision-guard.js";
 export * from "./hook-usage-log.js";
 export * from "./kb-mcp-tools.js";
 export * from "./knowledge-index.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-agent-core",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "description": "Shared low-latency hook helpers for Kibi agent adapters",
   "type": "module",
   "main": "./dist/index.js",
@@ -10,6 +10,10 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./decision-guard": {
+      "types": "./dist/decision-guard.d.ts",
+      "default": "./dist/decision-guard.js"
+    },
     "./hook-usage-log": {
       "types": "./dist/hook-usage-log.d.ts",
       "default": "./dist/hook-usage-log.js"