@kickythrust/pi-kicky-glue 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bogdan Cristian Bucurenciu (Kicky)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,98 @@
+# pi-kicky-glue
+
+Pi-native agent operating glue for Kicky.
+
+This package bundles Kicky's first layer of Pi harness discipline: safety blockers, workflow reminders, and owned-stack context pointers. It is personal-first and publishable; generic extraction can happen later if the patterns earn it.
+
+## What it does
+
+- **Blocks dangerous bash** before execution: force-pushes, destructive git resets/cleans, direct secret reads, kill-by-port pipelines, and broad `rm -rf` targets.
+- **Confirms risky bash** when a UI is available: normal `git push`, `gh pr create`, `kata --done`, `sed -i`, `sudo`, `chmod 777`, and recursive deletes.
+- **Nudges full reads** after repeated search/snippet operations. Search locates; reading understands.
+- **Nudges code pride** after code edits. Before final response, reread edited files and check imports, types, control flow, conventions, and owner-grade cleanliness.
+- **Injects owned-stack pointers** when prompts mention Pi, Runline, Dripline, Dripyard, kata, fnox, Omarchy, or Michaelliv.
+- **Adds commands**: `/kicky-glue-status` and `/kicky-glue-config`.
+
+No Claude Code dependency. Claude artifacts are source material only; Pi is the harness.
+
+## Install
+
+From npm, after publishing:
+
+```bash
+pi install npm:@kickythrust/pi-kicky-glue
+```
+
+Local dogfood:
+
+```bash
+pi install /home/kicky/work/studio/kicky/pi-kicky-glue
+/reload
+```
+
+## Commands
+
+| Command | Description |
+| --- | --- |
+| `/kicky-glue-status` | Show enabled features and lightweight runtime state. |
+| `/kicky-glue-config` | Show environment config knobs. |
+
+## Environment config
+
+| Env var | Effect |
+| --- | --- |
+| `PI_KICKY_GLUE_DISABLE=1` | Disable the whole package. |
+| `PI_KICKY_GLUE_NO_READ_FULLY=1` | Disable repeated-search reminder. |
+| `PI_KICKY_GLUE_NO_CODE_PRIDE=1` | Disable post-edit code-pride reminder. |
+| `PI_KICKY_GLUE_NO_DANGEROUS_BASH=1` | Disable bash blocker/confirmation gate. |
+| `PI_KICKY_GLUE_NO_CONTEXT=1` | Disable owned-stack pointer injection. |
+| `PI_KICKY_GLUE_READ_THRESHOLD=3` | Change repeated-search threshold. Default: `2`. |
+
+## Safety behavior
+
+Hard-blocked by default:
+
+- `git push --force` / `--force-with-lease`
+- `git reset --hard`
+- forceful `git clean -fd`
+- `lsof -ti:<port> | xargs kill`
+- direct secret reads such as `fnox get`, `psst get`, `op read`, `cat .env`, `env`, `printenv`
+- broad `rm -rf /`, `rm -rf ~`, `rm -rf $HOME`
+
+Confirmed in TUI/RPC, blocked in non-interactive modes:
+
+- ordinary `git push`
+- `gh pr create`, `kata --done`, `npm version`
+- `sed -i` / sed redirect editing
+- `sudo`
+- `chmod/chown 777`
+- recursive deletes not covered by the hard block
+
+## Package shape
+
+```text
+pi-kicky-glue/
+├── extensions/index.ts      # Pi extension entrypoint
+├── src/                     # Pure tested modules
+├── skills/kicky-glue/       # Skill docs loaded by Pi
+└── tests/                   # Bun tests for pure modules
+```
+
+## Development
+
+```bash
+bun install
+bun test
+bun run typecheck
+npm pack --dry-run
+```
+
+## Why this exists
+
+Michael's dotfiles showed the real lesson: the agent stack needs glue, not more tools. Small reminders and hard blockers keep the model inside the operator's discipline.
+
+For Kicky, that glue belongs in Pi.
+
+## License
+
+MIT

package/extensions/index.ts

@@ -0,0 +1,165 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { classifyBashCommand } from "../src/classifiers";
+import { loadConfig } from "../src/config";
+import { getOwnedStackPointers } from "../src/context";
+import { createGlueState } from "../src/state";
+
+const READ_FULLY_REMINDER = [
+  "Kicky glue reminder: search locates; reading understands.",
+  "You've been using snippet/search surfaces. Before editing based on those results, read the full symbol or file so imports, types, control flow, and local conventions are visible.",
+].join("\n");
+
+function getCommand(input: unknown): string {
+  if (!input || typeof input !== "object") return "";
+  const command = (input as { command?: unknown }).command;
+  return typeof command === "string" ? command : "";
+}
+
+function textList(items: string[]): string {
+  return items.map((item) => `- ${item}`).join("\n");
+}
+
+function codePrideReminder(paths: string[]): string {
+  return [
+    "Kicky glue reminder: code edited this turn.",
+    "Before the final answer, reread the edited code paths and verify imports, types, control flow, conventions, and owner-grade cleanliness.",
+    "Edited code paths:",
+    textList(paths),
+  ].join("\n");
+}
+
+function ownedStackContext(prompt: string): string | undefined {
+  const pointers = getOwnedStackPointers(prompt);
+  if (pointers.length === 0) return undefined;
+
+  return [
+    "\n## Kicky owned-stack pointers",
+    "The prompt touches Kicky-owned stack / Pi glue territory. Use progressive disclosure: read only the specific notes needed.",
+    ...pointers.map((pointer) => `- ${pointer.label}: ${pointer.path} — ${pointer.reason}`),
+  ].join("\n");
+}
+
+export default function kickyGlue(pi: ExtensionAPI) {
+  const config = loadConfig();
+  const state = createGlueState({ readFullyThreshold: config.readFullyThreshold });
+
+  pi.on("session_start", async (_event, ctx) => {
+    if (!config.enabled) {
+      ctx.ui.setStatus("kicky-glue", "kicky-glue off");
+      return;
+    }
+    ctx.ui.setStatus("kicky-glue", "kicky-glue on");
+  });
+
+  pi.on("session_shutdown", async (_event, ctx) => {
+    ctx.ui.setStatus("kicky-glue", undefined);
+  });
+
+  pi.on("tool_call", async (event, ctx) => {
+    if (!config.dangerousBash || event.toolName !== "bash") return undefined;
+
+    const command = getCommand(event.input);
+    const classification = classifyBashCommand(command);
+
+    if (classification.action === "allow") return undefined;
+
+    const reason = classification.reason ?? `Matched ${classification.rule ?? "unknown"}`;
+
+    if (classification.action === "block") {
+      if (ctx.hasUI) ctx.ui.notify(`kicky-glue blocked bash: ${classification.rule ?? "unknown"}`, "warning");
+      return { block: true, reason };
+    }
+
+    if (!ctx.hasUI) {
+      return {
+        block: true,
+        reason: `Command requires confirmation but this Pi mode has no UI. ${reason}`,
+      };
+    }
+
+    const confirmed = await ctx.ui.confirm(
+      `kicky-glue confirmation: ${classification.rule ?? "bash command"}`,
+      `${reason}\n\nCommand:\n${command}\n\nAllow?`,
+    );
+
+    if (!confirmed) {
+      return { block: true, reason: "Blocked by user via kicky-glue confirmation." };
+    }
+
+    return undefined;
+  });
+
+  pi.on("tool_result", async (event) => {
+    if (!config.enabled) return undefined;
+
+    if (config.readFully && state.recordSearch(event.toolName, event.input)) {
+      pi.sendMessage(
+        {
+          customType: "kicky-glue-reminder",
+          content: READ_FULLY_REMINDER,
+          display: true,
+          details: { kind: "read-fully" },
+        },
+        { deliverAs: "steer" },
+      );
+    }
+
+    const editedPaths = config.codePride ? state.recordEdit(event.toolName, event.input) : [];
+    if (editedPaths.length > 0) {
+      const paths = state.drainEditedCodePaths();
+      pi.sendMessage(
+        {
+          customType: "kicky-glue-reminder",
+          content: codePrideReminder(paths),
+          display: true,
+          details: { kind: "code-pride", paths },
+        },
+        { deliverAs: "steer" },
+      );
+    }
+
+    return undefined;
+  });
+
+  pi.on("before_agent_start", async (event) => {
+    if (!config.ownedStackContext) return undefined;
+    const context = ownedStackContext(event.prompt);
+    if (!context) return undefined;
+    return { systemPrompt: event.systemPrompt + context };
+  });
+
+  pi.registerCommand("kicky-glue-status", {
+    description: "Show pi-kicky-glue runtime status",
+    handler: async (_args, ctx) => {
+      const status = state.status();
+      const lines = [
+        `enabled: ${config.enabled}`,
+        `readFully: ${config.readFully} (threshold ${config.readFullyThreshold})`,
+        `codePride: ${config.codePride}`,
+        `dangerousBash: ${config.dangerousBash}`,
+        `ownedStackContext: ${config.ownedStackContext}`,
+        `consecutiveSearches: ${status.consecutiveSearches}`,
+        `pendingEditedCodePaths: ${status.pendingEditedCodePaths.length}`,
+      ];
+      ctx.ui.notify(`pi-kicky-glue status\n${lines.join("\n")}`, "info");
+    },
+  });
+
+  pi.registerCommand("kicky-glue-config", {
+    description: "Show pi-kicky-glue environment config knobs",
+    handler: async (_args, ctx) => {
+      ctx.ui.notify(
+        [
+          "pi-kicky-glue env config:",
+          "PI_KICKY_GLUE_DISABLE=1",
+          "PI_KICKY_GLUE_NO_READ_FULLY=1",
+          "PI_KICKY_GLUE_NO_CODE_PRIDE=1",
+          "PI_KICKY_GLUE_NO_DANGEROUS_BASH=1",
+          "PI_KICKY_GLUE_NO_CONTEXT=1",
+          "PI_KICKY_GLUE_READ_THRESHOLD=3",
+        ].join("\n"),
+        "info",
+      );
+    },
+  });
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@kickythrust/pi-kicky-glue",
+  "version": "0.1.0",
+  "description": "Pi extension pack for Kicky's agent operating glue: safety blockers, context nudges, doc/model checks, and owner-grade workflow reminders.",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "agent",
+    "safety",
+    "reminders",
+    "kicky",
+    "workflow"
+  ],
+  "license": "MIT",
+  "author": "Bogdan Cristian Bucurenciu (Kicky)",
+  "homepage": "https://github.com/Bucurenciu-Cristian/pi-kicky-glue",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Bucurenciu-Cristian/pi-kicky-glue.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Bucurenciu-Cristian/pi-kicky-glue/issues"
+  },
+  "type": "module",
+  "files": [
+    "extensions/",
+    "src/",
+    "skills/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@types/bun": "latest",
+    "typescript": "latest"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/skills/kicky-glue/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: kicky-glue
+description: Use when working on Kicky's Pi harness glue package, debugging pi-kicky-glue reminders/blockers, or deciding whether a workflow should become a Pi reminder, blocker, skill, or owned-stack pointer.
+---
+
+# Kicky Glue
+
+This skill documents the operating rules for `@kickythrust/pi-kicky-glue`.
+
+## Core decision
+
+Pi is Kicky's coding-agent harness. Claude Code artifacts are source material only.
+
+Do not add `.claude` runtime dependencies to this package. If a Claude hook is useful, port the behavior to Pi extension events.
+
+## Classification rule of thumb
+
+- Frequent but harmless behavior → skill or AGENTS guideline.
+- Frequent and often forgotten behavior → reminder.
+- Dangerous when wrong → blocker or confirmation gate.
+- Broad/low-frequency action surface → Runline.
+- Read/sync/query surface → Dripline.
+- Durable context → Napkin / kicky-brain.
+- Issue state → kata.
+
+## Current features
+
+- `dangerous-bash`: blocks or confirms risky bash commands.
+- `read-fully`: reminds after repeated search/snippet operations.
+- `code-pride`: reminds after code edits.
+- `owned-stack-context`: injects concise pointers to canonical Kicky notes when relevant.
+
+## Development workflow
+
+Use TDD for classifier/state/context behavior:
+
+```bash
+bun test
+bun run typecheck
+npm pack --dry-run
+```
+
+Keep the extension entrypoint thin. Add pure behavior to `src/` and tests under `tests/`.
+
+## Boundaries
+
+V1 must not:
+
+- auto-edit docs
+- auto-commit
+- create kata issues
+- call LLMs internally
+- install tools
+- modify `pi-fnox`
+- depend on Claude Code
+
+## Useful references
+
+- `~/personal/kicky-brain/kicky-brain/concepts/michaelliv-system-map.md`
+- `~/personal/kicky-brain/kicky-brain/decisions/2026-07-06-pi-harness-over-claude-code.md`
+- Pi docs: `/home/kicky/.cache/.bun/install/global/node_modules/@earendil-works/pi-coding-agent/docs/extensions.md`
+- Pi package docs: `/home/kicky/.cache/.bun/install/global/node_modules/@earendil-works/pi-coding-agent/docs/packages.md`

package/src/classifiers.ts

@@ -0,0 +1,130 @@
+export type BashAction = "allow" | "confirm" | "block";
+
+export interface BashClassification {
+  action: BashAction;
+  rule?: string;
+  reason?: string;
+}
+
+export interface BashClassifierOptions {
+  confirmGitPush: boolean;
+  blockForcePush: boolean;
+  blockSecretReads: boolean;
+  blockKillByPort: boolean;
+  blockSedEditing: boolean;
+  confirmModelDocActions: boolean;
+}
+
+export const DEFAULT_BASH_CLASSIFIER_OPTIONS: BashClassifierOptions = {
+  confirmGitPush: true,
+  blockForcePush: true,
+  blockSecretReads: true,
+  blockKillByPort: true,
+  blockSedEditing: true,
+  confirmModelDocActions: true,
+};
+
+const BLOCK_RULES: Array<{
+  rule: string;
+  reason: string;
+  pattern: RegExp;
+  option?: keyof BashClassifierOptions;
+}> = [
+  {
+    rule: "git-force-push",
+    reason: "Force-push is destructive and requires explicit human scope outside the command.",
+    pattern: /\bgit\s+push\b[\s\S]*(--force(?:-with-lease)?|-f(?:\s|$))/i,
+    option: "blockForcePush",
+  },
+  {
+    rule: "git-reset-hard",
+    reason: "git reset --hard can destroy local work.",
+    pattern: /\bgit\s+reset\b[\s\S]*--hard\b/i,
+  },
+  {
+    rule: "git-clean-force",
+    reason: "git clean with force can delete untracked work.",
+    pattern: /\bgit\s+clean\b[\s\S]*-(?:[a-z]*f[a-z]*d|[a-z]*d[a-z]*f)\b/i,
+  },
+  {
+    rule: "kill-by-port",
+    reason: "Kill-by-port can terminate the agent or unrelated services; stop the named service instead.",
+    pattern: /\blsof\b[\s\S]*-t[i]?\s*:?[0-9]+[\s\S]*\|[\s\S]*\bxargs\s+kill\b/i,
+    option: "blockKillByPort",
+  },
+  {
+    rule: "secret-read",
+    reason: "Agents may use secrets through injected environment variables, but must not print secret values.",
+    pattern: /(^|[;&|]\s*)(fnox|psst)\s+(get|export|show|cat)\b|\bop\s+read\b|\bcat\s+([^\n;&|]*\/)?\.env(\.[A-Za-z0-9_-]+)?\b|(^|[;&|]\s*)(printenv|env)\s*($|[;&|])/i,
+    option: "blockSecretReads",
+  },
+  {
+    rule: "rm-rf-root",
+    reason: "Broad rm -rf target is too destructive for agent execution.",
+    pattern: /\brm\s+-(?:[a-z]*r[a-z]*f|[a-z]*f[a-z]*r)\s+(\/|~|\$HOME)(?:\s|$)/i,
+  },
+];
+
+const CONFIRM_RULES: Array<{
+  rule: string;
+  reason: string;
+  pattern: RegExp;
+  option?: keyof BashClassifierOptions;
+}> = [
+  {
+    rule: "model-doc-check",
+    reason: "Before finalizing, check whether domain docs, AGENTS.md, runbooks, or kata evidence need updates.",
+    pattern: /\bgh\s+pr\s+create\b|\bkata\b[\s\S]*(--done|\bdone\b)|\bnpm\s+version\b/i,
+    option: "confirmModelDocActions",
+  },
+  {
+    rule: "git-push",
+    reason: "Push publishes work; confirm durable docs/model/evidence are current.",
+    pattern: /\bgit\s+push\b/i,
+    option: "confirmGitPush",
+  },
+  {
+    rule: "sed-editing",
+    reason: "Brittle sed file editing is discouraged; use Pi's edit tool for exact replacements.",
+    pattern: /\bsed\b[\s\S]*(-i\b|>\s*[^|;&]+)/i,
+    option: "blockSedEditing",
+  },
+  {
+    rule: "sudo",
+    reason: "sudo crosses privilege boundaries.",
+    pattern: /\bsudo\b/i,
+  },
+  {
+    rule: "chmod-777",
+    reason: "chmod/chown 777 is usually an unsafe permission change.",
+    pattern: /\b(chmod|chown)\b[\s\S]*\b777\b/i,
+  },
+  {
+    rule: "rm-rf",
+    reason: "Recursive deletion requires exact human confirmation.",
+    pattern: /\brm\s+-(?:[a-z]*r[a-z]*f|[a-z]*f[a-z]*r)\b/i,
+  },
+];
+
+export function classifyBashCommand(
+  command: string,
+  options: Partial<BashClassifierOptions> = {},
+): BashClassification {
+  const resolved = { ...DEFAULT_BASH_CLASSIFIER_OPTIONS, ...options };
+
+  for (const rule of BLOCK_RULES) {
+    if (rule.option && !resolved[rule.option]) continue;
+    if (rule.pattern.test(command)) {
+      return { action: "block", rule: rule.rule, reason: rule.reason };
+    }
+  }
+
+  for (const rule of CONFIRM_RULES) {
+    if (rule.option && !resolved[rule.option]) continue;
+    if (rule.pattern.test(command)) {
+      return { action: "confirm", rule: rule.rule, reason: rule.reason };
+    }
+  }
+
+  return { action: "allow" };
+}

package/src/config.ts

@@ -0,0 +1,33 @@
+export interface KickyGlueConfig {
+  enabled: boolean;
+  readFully: boolean;
+  codePride: boolean;
+  dangerousBash: boolean;
+  ownedStackContext: boolean;
+  readFullyThreshold: number;
+}
+
+function envFlag(name: string, defaultValue: boolean): boolean {
+  const value = process.env[name];
+  if (value === undefined) return defaultValue;
+  return !["0", "false", "no", "off"].includes(value.toLowerCase());
+}
+
+function envNumber(name: string, defaultValue: number): number {
+  const value = process.env[name];
+  if (value === undefined) return defaultValue;
+  const parsed = Number(value);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : defaultValue;
+}
+
+export function loadConfig(): KickyGlueConfig {
+  const enabled = envFlag("PI_KICKY_GLUE_ENABLED", true) && !envFlag("PI_KICKY_GLUE_DISABLE", false);
+  return {
+    enabled,
+    readFully: enabled && !envFlag("PI_KICKY_GLUE_NO_READ_FULLY", false),
+    codePride: enabled && !envFlag("PI_KICKY_GLUE_NO_CODE_PRIDE", false),
+    dangerousBash: enabled && !envFlag("PI_KICKY_GLUE_NO_DANGEROUS_BASH", false),
+    ownedStackContext: enabled && !envFlag("PI_KICKY_GLUE_NO_CONTEXT", false),
+    readFullyThreshold: envNumber("PI_KICKY_GLUE_READ_THRESHOLD", 2),
+  };
+}

package/src/context.ts

@@ -0,0 +1,71 @@
+export interface OwnedStackPointer {
+  label: string;
+  path: string;
+  reason: string;
+}
+
+interface PointerRule extends OwnedStackPointer {
+  terms: readonly string[];
+}
+
+const POINTER_RULES: PointerRule[] = [
+  {
+    label: "Michaelliv system map",
+    path: "~/personal/kicky-brain/kicky-brain/concepts/michaelliv-system-map.md",
+    reason: "agent OS pattern language, Pi glue candidates, and do/don't-copy list",
+    terms: ["michaelliv", "miclivs", "dotpi", "dotskills", "agent glue", "pi glue"],
+  },
+  {
+    label: "Michaelliv framework",
+    path: "~/personal/kicky-brain/kicky-brain/concepts/michaelliv-framework.md",
+    reason: "why behind Code Mode, Dripline, Runline, and owned runtimes",
+    terms: ["runline", "dripline", "dripyard", "code mode", "query mode", "michaelliv"],
+  },
+  {
+    label: "Verified personal stack",
+    path: "~/personal/kicky-brain/kicky-brain/context/personal-stack.md",
+    reason: "canonical list of what Kicky actually uses vs drop-list",
+    terms: ["runline", "dripline", "dripyard", "dokku", "tailscale", "fnox", "kata", "omarchy", "stack"],
+  },
+  {
+    label: "Pi documentation",
+    path: "/home/kicky/.cache/.bun/install/global/node_modules/@earendil-works/pi-coding-agent/README.md and docs/",
+    reason: "current Pi extension/package/skill API reference",
+    terms: ["pi", "extension", "pi package", "pi-package", "harness"],
+  },
+  {
+    label: "Pi-over-Claude decision",
+    path: "~/personal/kicky-brain/kicky-brain/decisions/2026-07-06-pi-harness-over-claude-code.md",
+    reason: "Claude Code artifacts are source material only; Pi is the harness",
+    terms: ["claude", "claude code", "harness", "pi glue"],
+  },
+  {
+    label: "Omarchy operating guide",
+    path: "~/dev/kicky-brain/infra/omarchy-agent-operating-guide.md",
+    reason: "desktop/OS workflow for this Omarchy machine",
+    terms: ["omarchy", "hyprland", "waybar"],
+  },
+];
+
+function includesTerm(text: string, term: string): boolean {
+  const escaped = term.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return new RegExp(`(^|[^a-z0-9-])${escaped}([^a-z0-9-]|$)`, "i").test(text);
+}
+
+export function getOwnedStackPointers(
+  prompt: string,
+  options: { maxPointers?: number } = {},
+): OwnedStackPointer[] {
+  const maxPointers = options.maxPointers ?? 6;
+  const normalized = prompt.toLowerCase();
+  const pointers: OwnedStackPointer[] = [];
+
+  for (const rule of POINTER_RULES) {
+    if (rule.terms.some((term) => includesTerm(normalized, term.toLowerCase()))) {
+      pointers.push({ label: rule.label, path: rule.path, reason: rule.reason });
+    }
+    if (pointers.length >= maxPointers) break;
+  }
+
+  return pointers;
+}

package/src/state.ts

@@ -0,0 +1,127 @@
+export interface GlueStateOptions {
+  readFullyThreshold: number;
+  codeExtensions: readonly string[];
+}
+
+export interface GlueStatus {
+  pendingEditedCodePaths: string[];
+  consecutiveSearches: number;
+}
+
+export interface GlueState {
+  recordSearch(toolName: string, input?: unknown): boolean;
+  recordNonSearch(): void;
+  recordEdit(toolName: string, input?: unknown): string[];
+  drainEditedCodePaths(): string[];
+  status(): GlueStatus;
+}
+
+export const DEFAULT_CODE_EXTENSIONS = [
+  ".ts",
+  ".tsx",
+  ".js",
+  ".jsx",
+  ".mjs",
+  ".cjs",
+  ".py",
+  ".rs",
+  ".go",
+  ".rb",
+  ".java",
+  ".kt",
+  ".swift",
+  ".c",
+  ".cpp",
+  ".h",
+  ".hpp",
+  ".cs",
+  ".lua",
+  ".zig",
+  ".sh",
+  ".bash",
+  ".zsh",
+  ".vue",
+  ".svelte",
+  ".astro",
+  ".css",
+  ".scss",
+  ".html",
+] as const;
+
+const SEARCH_COMMAND_PATTERN = /\b(rg|grep|egrep|fgrep|zgrep|bzgrep|xzgrep|ag|ack|pt|sift|ucg)\b/;
+const SEARCH_TOOL_NAMES = new Set([
+  "grep",
+  "find",
+  "ls",
+  "ast_grep_search",
+  "lsp_navigation",
+]);
+
+function getStringPath(input: unknown): string | undefined {
+  if (!input || typeof input !== "object") return undefined;
+  const maybePath = (input as { path?: unknown }).path;
+  return typeof maybePath === "string" ? maybePath : undefined;
+}
+
+function getCommand(input: unknown): string {
+  if (!input || typeof input !== "object") return "";
+  const maybeCommand = (input as { command?: unknown }).command;
+  return typeof maybeCommand === "string" ? maybeCommand : "";
+}
+
+function isCodePath(path: string, extensions: readonly string[]): boolean {
+  return extensions.some((extension) => path.endsWith(extension));
+}
+
+function isSearch(toolName: string, input: unknown): boolean {
+  if (toolName === "bash") return SEARCH_COMMAND_PATTERN.test(getCommand(input));
+  return SEARCH_TOOL_NAMES.has(toolName);
+}
+
+export function createGlueState(options: Partial<GlueStateOptions> = {}): GlueState {
+  const readFullyThreshold = options.readFullyThreshold ?? 2;
+  const codeExtensions = options.codeExtensions ?? DEFAULT_CODE_EXTENSIONS;
+  let consecutiveSearches = 0;
+  const pendingEditedCodePaths = new Set<string>();
+
+  return {
+    recordSearch(toolName: string, input?: unknown): boolean {
+      if (!isSearch(toolName, input)) {
+        consecutiveSearches = 0;
+        return false;
+      }
+
+      consecutiveSearches += 1;
+      if (consecutiveSearches >= readFullyThreshold) {
+        consecutiveSearches = 0;
+        return true;
+      }
+      return false;
+    },
+
+    recordNonSearch(): void {
+      consecutiveSearches = 0;
+    },
+
+    recordEdit(toolName: string, input?: unknown): string[] {
+      if (toolName !== "edit" && toolName !== "write") return [];
+      const path = getStringPath(input);
+      if (!path || !isCodePath(path, codeExtensions)) return [];
+      pendingEditedCodePaths.add(path);
+      return [path];
+    },
+
+    drainEditedCodePaths(): string[] {
+      const paths = [...pendingEditedCodePaths].sort();
+      pendingEditedCodePaths.clear();
+      return paths;
+    },
+
+    status(): GlueStatus {
+      return {
+        pendingEditedCodePaths: [...pendingEditedCodePaths].sort(),
+        consecutiveSearches,
+      };
+    },
+  };
+}