pi-note 0.7.1 → 0.9.0

package/README.md

@@ -56,10 +56,10 @@ standalone `settings/pi/extensions/pinote.ts` entry if installed; load only one
 
 ## Use
 
-`/pi-note` picks a task, marks it in progress, and adds this prompt to the editor:
+`/pi-note` picks a task, marks it in progress, and adds this default prompt to the editor:
 “Read the current Pinote task. Summarize your understanding, but don’t start work yet.”
 The agent fetches current task text and saved handoff fields when you submit;
-they are not copied into the draft. The prompt asks for a summary, not implementation.
+they are not copied into the draft. The default prompt asks for a summary, not implementation.
 Existing drafts are preserved; nothing is submitted automatically.
 With a selected task it offers **Continue**, **Done**, and **Switch task**.
 Type in the task picker to filter by text, ID, tag, or state (all words must match).
@@ -74,14 +74,47 @@ Resume restores that session's task; a new session starts unselected and does no
 an older per-folder selection. Pi saves the session after the first submitted message;
 quitting before that leaves the next launch unselected, while the task stays in progress.
 Use **Continue**
-to insert the same read-and-summarize prompt. Completing, removing, or scheduling a task clears it
+to insert the same configured prompt. Completing, removing, or scheduling a task clears it
 from sessions that refresh it. Switching does not complete or reset the previous task.
 Task fields such as `Worktree` and `PR` stay on the task, so sessions can use separate
 worktrees and pull requests. Task status refreshes at session start, before/after
 agent activity, and after commands/tools. The CLI's per-directory `agent selected`
 command is not this session memory.
 
-Agent tools:
+### Personal configuration
+
+Configure `~/.pi/agent/pi-note.json` (or the agent directory set by
+`PI_CODING_AGENT_DIR`):
+
+```json
+{
+  "handoffPrompt": "Read the current Pinote task. Summarize your understanding and proposed approach, but don’t start work yet.",
+  "taskOfferPolicy": "github-remote"
+}
+```
+
+`taskOfferPolicy` controls the agent's task-offer guidance:
+
+- `always` (default): offer a task when given work with no task selected.
+- `github-remote`: first verify with Git that the repository has an HTTPS or SSH
+  remote hosted on `github.com`; otherwise do not offer. Local paths and other
+  hosts do not qualify. This is agent guidance, not a network or PR-access check.
+- `never`: do not offer tasks; explicit requests to create one remain allowed.
+
+All policies preserve the existing creation tools, user-consent requirement,
+and selected tasks. Run `/reload` after changing this setting. Invalid policy
+values or unreadable/malformed configuration suppress offers; interactive startup
+warns until you fix the file and reload. No project-local configuration is read.
+
+Task selection and **Continue** reread `handoffPrompt` each time; changing that
+field needs no `/reload`. Its value is literal text, not a prompt template; use
+`\n` in JSON strings for multiple lines. It must be a nonblank string without control
+characters other than tabs and newlines. A missing file or key uses the default.
+Invalid/unreadable configuration reports an error without starting/switching a
+task or changing the editor. **Done** and agent tools are unaffected. This is
+user-level configuration only; project-local files are not read.
+
+### Agent tools
 
 - `pinote_get_current`: read this session's selected task, including its revision.
   Takes no arguments; returns null when this session has no selected task.
@@ -98,8 +131,8 @@ Version 0.7.0 replaces `pinote_get`/`pinote_update` with these current-task tool
 and removes `pinote_tag`, without aliases. Agents cannot read/update tasks by ID
 or retag existing tasks; use `/pi-note` to select an existing task.
 
-When the user gives work and no task is selected, the agent proposes one note as
-`[tag] text` and asks before creating it. No continues without a note. Yes calls
+When allowed by `taskOfferPolicy`, the agent proposes one note as `[tag] text`
+and asks before creating it. No continues without a note. Yes calls
 `pinote_add` with `select: true`. An existing selection is not replaced unless the
 user asks to switch. Reuse a saved tag name when it fits.
 

package/index.ts

@@ -1,6 +1,7 @@
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { getAgentDir, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { truncateToWidth } from "@earendil-works/pi-tui";
 import { readFileSync } from "node:fs";
+import { join } from "node:path";
 import { stripVTControlCharacters } from "node:util";
 import { Type } from "typebox";
 import { createPRWatcher } from "./pr-watch.ts";
@@ -8,10 +9,13 @@ import { TaskPicker, taskState, taskTag } from "./task-picker.ts";
 import { bundledCLIVersion, cliMenu, detectCLI, setupCLI, setupHint, versionAtLeast, type CLIAction } from "./setup.ts";
 
 const handoffGuidance = "Keep agent notes to at most three short bullets total: outcome, blocker, next action, only when relevant. Replace stale notes; omit narration, repeated task text, and routine test logs. Keep a GitHub pull request in the PR field. To show another footer field, set its Markdown value and append its label to Bar, one label per line. Links in that text are clickable. Do not list PR in Bar. Remove the field and its Bar line to drop it. Notes stay off the footer unless named in Bar.";
-const createGuidance = [
-  "When the user gives work and no pinote task is selected, propose one note as `[tag] text` and ask before creating it. On no, continue without a note. On yes, call pinote_add with select true so it becomes this session's active task. Never add or select without a yes. If a task is already selected, do not replace it unless the user asks to switch.",
-  "Reuse a pinote_tags name when it fits. One tag; case-sensitive, trimmed, at most 64 characters. Tags are set when creating tasks with pinote_add; agent tools cannot retag existing tasks. Do not use pinote_update_current for tags or task text.",
-];
+const offerGuidance = {
+  always: "When the user gives work and no pinote task is selected, propose one note as `[tag] text` and ask before creating it.",
+  "github-remote": "When the user gives work and no pinote task is selected, first verify with Git that the current repository has a remote whose URL host is github.com (HTTPS or SSH). Only then propose one note as `[tag] text` and ask before creating it. Local paths, other hosts, and GitHub-looking URL paths do not qualify. If no GitHub remote is verified, do not offer a task; explicit user requests to create one remain allowed.",
+  never: "Do not offer to create a pinote task. Create one only when the user explicitly requests it.",
+};
+const consentGuidance = "On no, continue without a note. On yes, call pinote_add with select true so it becomes this session's active task. Never add or select without a yes. If a task is already selected, do not replace it unless the user asks to switch.";
+const tagGuidance = "Reuse a pinote_tags name when it fits. One tag; case-sensitive, trimmed, at most 64 characters. Tags are set when creating tasks with pinote_add; agent tools cannot retag existing tasks. Do not use pinote_update_current for tags or task text.";
 type Task = {
   id: number;
   text: string;
@@ -34,6 +38,51 @@ const clean = (value: string) => stripVTControlCharacters(value).replace(/[\x00-
 const firstLine = (task: Summary) => clean(task.text.split("\n", 1)[0]).replace(/\s+/gu, " ").trim();
 const title = (task: Summary) => truncateToWidth(`#${task.id} ${firstLine(task)}`, 60);
 
+const defaultHandoffPrompt = "Read the current Pinote task. Summarize your understanding, but don’t start work yet.";
+function readConfig(): Record<string, unknown> {
+  const path = join(getAgentDir(), "pi-note.json");
+  let raw: string;
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return {};
+    throw new Error(`Cannot read ${path}. Check the pi-note configuration.`);
+  }
+  let config: unknown;
+  try { config = JSON.parse(raw); } catch { throw new Error(`Invalid JSON in ${path}.`); }
+  if (!record(config)) throw new Error(`Expected a JSON object in ${path}.`);
+  return config;
+}
+
+function creationGuidance(): { guidelines: string[]; error?: string } {
+  let policy: keyof typeof offerGuidance = "always";
+  let error: string | undefined;
+  try {
+    const config = readConfig();
+    if ("taskOfferPolicy" in config) {
+      const value = config.taskOfferPolicy;
+      if (value !== "always" && value !== "github-remote" && value !== "never") {
+        throw new Error(`taskOfferPolicy in ${join(getAgentDir(), "pi-note.json")} must be always, github-remote, or never.`);
+      }
+      policy = value;
+    }
+  } catch (cause) {
+    policy = "never";
+    error = cause instanceof Error ? cause.message : String(cause);
+  }
+  return { guidelines: [`${offerGuidance[policy]} ${consentGuidance}`, tagGuidance], error };
+}
+
+function handoffPrompt(): string {
+  const config = readConfig();
+  const path = join(getAgentDir(), "pi-note.json");
+  if (!("handoffPrompt" in config)) return defaultHandoffPrompt;
+  if (!text(config.handoffPrompt) || !config.handoffPrompt.trim()) {
+    throw new Error(`handoffPrompt in ${path} must be a nonblank string without control characters (except tabs/newlines).`);
+  }
+  return config.handoffPrompt;
+}
+
 function parse(raw: string): unknown {
   try { return JSON.parse(raw); } catch { throw new Error(compatible); }
 }
@@ -69,6 +118,7 @@ function toolResult(value: Task | null) {
 }
 
 export default function (pi: ExtensionAPI) {
+  const { guidelines: createGuidance, error: offerConfigError } = creationGuidance();
   let alive = true;
   let epoch = 0;
   let refreshSerial = 0;
@@ -227,6 +277,7 @@ export default function (pi: ExtensionAPI) {
     const generation = epoch;
     cliState = undefined;
     if (ctx.hasUI && ctx.mode === "tui") {
+      if (offerConfigError) ctx.ui.notify(`Pinote task offers disabled: ${clean(offerConfigError)} Fix the configuration and /reload.`, "warning");
       ctx.ui.addAutocompleteProvider((current) => cliMenu(current, () => setupAbort ? undefined : cliState));
     }
     // Keep the setup lock until its aborted subprocess has actually settled.
@@ -333,6 +384,7 @@ export default function (pi: ExtensionAPI) {
           if (currentSession()) ctx.ui.notify(`Pinote #${current.id} completed.`, "info");
           return;
         }
+        const handoff = handoffPrompt();
         let id: number;
         if (action === "Continue" && current) {
           id = current.id;
@@ -349,7 +401,6 @@ export default function (pi: ExtensionAPI) {
         const chosen = await startTask(id, canAct);
         if (!chosen || !canAct()) return;
         const draft = ctx.ui.getEditorText();
-        const handoff = "Read the current Pinote task. Summarize your understanding, but don’t start work yet.";
         ctx.ui.setEditorText(draft ? `${draft}\n\n${handoff}` : handoff);
         ctx.ui.notify(`Pinote #${chosen.id} is in progress. Task added to input.`, "info");
       } catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-note",
-  "version": "0.7.1",
+  "version": "0.9.0",
   "description": "Persistent pinote tasks, Markdown handoffs, and task status for Pi",
   "license": "MIT",
   "type": "module",