@phnx-labs/agents-cli 1.20.52 → 1.20.54

package/dist/lib/feed.js

@@ -13,11 +13,19 @@
  * A block carries enough identity (sessionId, mailboxId, host, runtime) for
  * `agents feed` to aggregate across hosts and for `agents message` to route
  * a reply back to the right agent.
+ *
+ * Answer lifecycle:
+ *   - A block may be answered from any surface (feed, terminal, tmux, cloud).
+ *   - The first answer wins: `recordAnswer` atomically checks an answered
+ *     marker so exactly one surface can claim the block.
+ *   - Answered blocks stay visible until the agent consumes the message and
+ *     continues, so the UI can show delivered/consumed/continued receipts.
  */
 import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'yaml';
 import { getFeedDir, getUserAgentsDir } from './state.js';
+import { isHighConsequenceAllowed } from './operator.js';
 /**
  * Stable block id for a session. One block per session -- a new question
  * replaces the previous one (the agent can only ask one question at a time).
@@ -32,7 +40,186 @@ function blockPath(root, blockId) {
     }
     return path.join(root, `${blockId}.json`);
 }
-/** Atomic write a block record to the feed store. */
+function answeredDir(root) { return path.join(root, 'answered'); }
+function receiptDir(root) { return path.join(root, 'receipts'); }
+function ensureDir(dir) {
+    fs.mkdirSync(dir, { recursive: true });
+}
+function safeReadJson(file) {
+    try {
+        return JSON.parse(fs.readFileSync(file, 'utf-8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+function atomicWriteJson(file, value) {
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(value, null, 2), 'utf-8');
+    fs.renameSync(tmp, file);
+}
+/** Read one block record. Returns undefined when missing or corrupt. */
+export function readBlock(blockId, root) {
+    const parsed = safeReadJson(blockPath(root ?? getFeedDir(), blockId));
+    if (!parsed || !parsed.blockId || !parsed.sessionId || !parsed.questions?.length)
+        return undefined;
+    return parsed;
+}
+/**
+ * Atomically claim the first answer for a block. Returns `{ ok: true }` when
+ * this call is the first to answer; returns `{ ok: false, existing }` when a
+ * different surface already answered the block. The marker file is created
+ * with `O_EXCL` so two concurrent claimers cannot both succeed.
+ *
+ * High-consequence blocks require a verified operator identity. Unverified
+ * answers (no operatorId or not in the registry/allowed list) are refused.
+ */
+export function recordAnswer(blockId, answer, root) {
+    const dir = root ?? getFeedDir();
+    const block = readBlock(blockId, dir);
+    const operatorId = answer.operatorId;
+    if (block?.consequence && block.consequence !== 'normal') {
+        // Operators live in ~/.agents/operators.yaml — never the feed store root.
+        if (!operatorId || answer.verified !== true || !isHighConsequenceAllowed(block.consequence, operatorId)) {
+            return {
+                ok: false,
+                unauthorized: true,
+                reason: `High-consequence block '${block.consequence}' requires a verified, authorized operator.`,
+            };
+        }
+    }
+    ensureDir(answeredDir(dir));
+    const marker = path.join(answeredDir(dir), `${blockId}.json`);
+    const record = {
+        answeredAt: new Date().toISOString(),
+        answeredFrom: answer.answeredFrom,
+        answeredBy: answer.answeredBy,
+        operatorId: answer.operatorId,
+        verified: answer.verified,
+    };
+    // Try to create the answered marker atomically.
+    try {
+        const fd = fs.openSync(marker, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL, 0o644);
+        try {
+            const buf = Buffer.from(JSON.stringify(record, null, 2), 'utf-8');
+            fs.writeSync(fd, buf, 0, buf.length);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === 'EEXIST') {
+            const existing = safeReadJson(marker);
+            return { ok: false, existing: existing ?? { answeredAt: '', answeredFrom: 'unknown' } };
+        }
+        throw err;
+    }
+    // Marker created successfully -- mirror the answer into the block file.
+    if (block) {
+        block.answer = record;
+        publishBlock(block, dir);
+    }
+    return { ok: true };
+}
+/** Read the answer record for a block, if one exists. */
+export function getAnswerRecord(blockId, root) {
+    return safeReadJson(path.join(answeredDir(root ?? getFeedDir()), `${blockId}.json`));
+}
+/** True when the block has already been answered. */
+export function isBlockAnswered(blockId, root) {
+    return fs.existsSync(path.join(answeredDir(root ?? getFeedDir()), `${blockId}.json`));
+}
+/** Receipt lifecycle rank — higher means further along; never regress. */
+const RECEIPT_STATUS_RANK = {
+    queued: 0,
+    consumed: 1,
+    continued: 2,
+};
+/**
+ * Record a delivery-receipt transition for a message tied to a block.
+ * Updates the receipts list in the block file. Status is monotonic
+ * (queued → consumed → continued): a late `queued` write cannot overwrite
+ * an already-recorded `consumed`/`continued` (race with mailbox drain).
+ */
+export function recordMessageReceipt(blockId, receipt, root) {
+    const dir = root ?? getFeedDir();
+    const block = readBlock(blockId, dir);
+    if (!block)
+        return;
+    const receipts = block.receipts ?? [];
+    const idx = receipts.findIndex((r) => r.msgId === receipt.msgId);
+    if (idx >= 0) {
+        const prev = receipts[idx];
+        if (RECEIPT_STATUS_RANK[receipt.status] < RECEIPT_STATUS_RANK[prev.status]) {
+            return; // do not regress
+        }
+        receipts[idx] = receipt;
+    }
+    else {
+        receipts.push(receipt);
+    }
+    block.receipts = receipts;
+    publishBlock(block, dir);
+}
+/** Read the receipt list for a block. */
+export function getBlockReceipts(blockId, root) {
+    return readBlock(blockId, root)?.receipts ?? [];
+}
+/** Mark a block as "continued" -- the agent consumed the answer and moved on. */
+export function recordContinued(blockId, root) {
+    const dir = root ?? getFeedDir();
+    const block = readBlock(blockId, dir);
+    if (!block)
+        return;
+    block.continuedAt = new Date().toISOString();
+    publishBlock(block, dir);
+}
+/** Mark a decision-class block as hard-parked (no safe default existed). */
+export function recordParked(blockId, root) {
+    const dir = root ?? getFeedDir();
+    const block = readBlock(blockId, dir);
+    if (!block)
+        return;
+    block.parkedAt = new Date().toISOString();
+    publishBlock(block, dir);
+}
+/** Mark that the approval safe-default was applied by policy. */
+export function recordDefaulted(blockId, root) {
+    const dir = root ?? getFeedDir();
+    const block = readBlock(blockId, dir);
+    if (!block)
+        return;
+    block.defaultedAt = new Date().toISOString();
+    publishBlock(block, dir);
+}
+/** Mark that an urgent block was paged to the phone. */
+export function recordNotified(blockId, root) {
+    const dir = root ?? getFeedDir();
+    const block = readBlock(blockId, dir);
+    if (!block)
+        return;
+    block.notifiedAt = new Date().toISOString();
+    publishBlock(block, dir);
+}
+/** Convenience: record that a terminal answer closed the block. */
+export function recordTerminalAnswer(blockId, root) {
+    recordAnswer(blockId, { answeredFrom: 'terminal' }, root);
+}
+/** Remove answered marker and receipts for a block (used by block removal/GC). */
+export function clearBlockLifecycle(blockId, root) {
+    const dir = root ?? getFeedDir();
+    for (const sub of [answeredDir(dir), receiptDir(dir)]) {
+        try {
+            fs.unlinkSync(path.join(sub, `${blockId}.json`));
+        }
+        catch {
+            // ignore missing
+        }
+    }
+}
+/** Atomic write a block record to the feed store. Clears stale lifecycle state. */
 export function publishBlock(block, root) {
     const dir = root ?? getFeedDir();
     fs.mkdirSync(dir, { recursive: true });
@@ -66,9 +253,10 @@ export function listBlocks(root) {
     }
     return blocks;
 }
-/** Remove a block record. Returns true if the file was deleted. */
+/** Remove a block record and its lifecycle sidecars. Returns true if the file was deleted. */
 export function removeBlock(blockId, root) {
     const dir = root ?? getFeedDir();
+    clearBlockLifecycle(blockId, dir);
     try {
         fs.unlinkSync(blockPath(dir, blockId));
         return true;
@@ -86,12 +274,12 @@ export function removeBlock(blockId, root) {
  * CLI-writable user hooks dir without a separate file in the npm tarball.
  */
 export const FEED_PUBLISH_HOOK_SCRIPT = `#!/usr/bin/env python3
-"""PreToolUse hook: publish an open-block record when the agent calls
-AskUserQuestion, so \`agents feed\` can aggregate pending decisions.
+"""Publish and clear open-block records for \`agents feed\`.
 
-Outbound counterpart to the inbound mailbox-inject hook. Fires only on
-AskUserQuestion (matcher-gated in agents.yaml). Writes one block per session
-to ~/.agents/.history/feed/. A new question replaces the previous block.
+The manifest invokes this script for top-level AskUserQuestion calls, waiting
+notifications, question answers, and session lifecycle events. One atomic file
+per session means a new block replaces the previous block. Answer/resume/stop
+events remove it so \`agents feed\` only lists decisions that are still open.
 
 Sub-agent gate: when the PreToolUse payload carries \`agent_type\`, this is a
 Task/Agent subagent -- skip. Only the top-level agent publishes. Verified on
@@ -107,6 +295,40 @@ import socket
 import tempfile
 from datetime import datetime, timezone
 
+WAITING_NOTIFICATION_TYPES = {
+    "permission_prompt",
+    "idle_prompt",
+    "elicitation_dialog",
+}
+CLEAR_EVENTS = {
+    "PostToolUse",
+    "Stop",
+    "SessionEnd",
+}
+
+
+def read_json(path):
+    try:
+        with open(path) as f:
+            return json.load(f)
+    except Exception:
+        return None
+
+
+def write_json(path, value):
+    dir_name = os.path.dirname(path)
+    os.makedirs(dir_name, exist_ok=True)
+    fd, tmp = tempfile.mkstemp(dir=dir_name, suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w") as f:
+            json.dump(value, f, indent=2)
+        os.replace(tmp, path)
+    except Exception:
+        try:
+            os.unlink(tmp)
+        except Exception:
+            pass
+
 
 def main():
     raw = sys.stdin.read()
@@ -119,35 +341,113 @@ def main():
     if payload.get("agent_type"):
         return
 
-    tool_input = payload.get("tool_input", {})
-    questions = tool_input.get("questions", [])
-    if not questions:
-        return
-
     session_id = payload.get("session_id", "")
     if not session_id:
         return
 
-    normalized_questions = []
-    for q in questions:
-        if not isinstance(q, dict):
-            continue
-        question = {
-            "text": q.get("question", q.get("header", "")),
-            "header": q.get("header"),
-            "multiSelect": q.get("multiSelect", False),
-        }
-        raw_opts = q.get("options", [])
-        if raw_opts:
-            question["options"] = [
-                {"label": o.get("label", ""), "description": o.get("description")}
-                for o in raw_opts
-                if isinstance(o, dict)
-            ]
-        normalized_questions.append(question)
-    if not normalized_questions:
+    safe_session_id = re.sub(r"[^A-Za-z0-9._-]", "-", session_id)
+    block_id = f"block-{safe_session_id}"
+    home = os.environ.get("HOME") or os.path.expanduser("~")
+    feed_dir = os.path.join(home, ".agents", ".history", "feed")
+    answered_dir = os.path.join(feed_dir, "answered")
+    target = os.path.join(feed_dir, f"{block_id}.json")
+    hook_event = payload.get("hook_event_name", "PreToolUse")
+
+    if hook_event in CLEAR_EVENTS:
+        try:
+            os.unlink(target)
+        except FileNotFoundError:
+            pass
+        except Exception:
+            pass
+        # Also clear the answered marker so a future question for this session
+        # is not permanently locked.
+        try:
+            os.unlink(os.path.join(answered_dir, f"{block_id}.json"))
+        except FileNotFoundError:
+            pass
+        except Exception:
+            pass
         return
 
+    # Terminal answers (human typed in the TUI) record an answered marker and
+    # remove the block file so the feed stops showing it within one poll cycle.
+    # The marker stays behind so a concurrent surface cannot double-answer.
+    if hook_event == "UserPromptSubmit":
+        os.makedirs(answered_dir, exist_ok=True)
+        marker = os.path.join(answered_dir, f"{block_id}.json")
+        try:
+            fd = os.open(marker, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o644)
+            record = {
+                "answeredAt": datetime.now(timezone.utc).isoformat(),
+                "answeredFrom": "terminal",
+            }
+            with os.fdopen(fd, "w") as f:
+                json.dump(record, f, indent=2)
+        except FileExistsError:
+            pass
+        except Exception:
+            pass
+        # Remove the visible block so the feed drops the answered question.
+        try:
+            os.unlink(target)
+        except FileNotFoundError:
+            pass
+        except Exception:
+            pass
+        return
+
+    notification_type = None
+    if hook_event == "Notification":
+        notification_type = payload.get("notification_type", "")
+        if notification_type not in WAITING_NOTIFICATION_TYPES:
+            return
+        # Claude emits a generic permission notification after presenting an
+        # AskUserQuestion. Keep the structured questions and options already
+        # published for this session instead of replacing them with that less
+        # useful notification text.
+        try:
+            with open(target) as existing_file:
+                existing = json.load(existing_file)
+            if existing.get("kind") == "question":
+                return
+        except Exception:
+            pass
+        message = payload.get("message", "")
+        if not message:
+            return
+        normalized_questions = [{
+            "text": message,
+            "header": payload.get("title") or notification_type.replace("_", " ").title(),
+            "multiSelect": False,
+        }]
+        kind = "notification"
+    else:
+        tool_input = payload.get("tool_input", {})
+        questions = tool_input.get("questions", [])
+        if not questions:
+            return
+        normalized_questions = []
+        for q in questions:
+            if not isinstance(q, dict):
+                continue
+            question = {
+                "text": q.get("question", q.get("header", "")),
+                "header": q.get("header"),
+                "multiSelect": q.get("multiSelect", False),
+            }
+            raw_opts = q.get("options", [])
+            if raw_opts:
+                question["options"] = [
+                    {"label": o.get("label", ""), "description": o.get("description")}
+                    for o in raw_opts
+                    if isinstance(o, dict)
+                ]
+            normalized_questions.append(question)
+        if not normalized_questions:
+            return
+        kind = "question"
+
     # Identity from env (set by agents-cli at spawn).
     mailbox_id = os.path.basename(
         os.environ.get("AGENTS_MAILBOX_DIR", "").rstrip("/")
@@ -159,8 +459,6 @@ def main():
 
     runtime = os.environ.get("AGENTS_RUNTIME", "headless")
 
-    safe_session_id = re.sub(r"[^A-Za-z0-9._-]", "-", session_id)
-    block_id = f"block-{safe_session_id}"
     block = {
         "blockId": block_id,
         "sessionId": session_id,
@@ -169,21 +467,52 @@ def main():
         "runtime": runtime,
         "ts": datetime.now(timezone.utc).isoformat(),
         "questions": normalized_questions,
+        "kind": kind,
     }
+    if notification_type:
+        block["notificationType"] = notification_type
+
+    # Optional multi-operator control metadata passed by the agent in the
+    # AskUserQuestion tool_input. Defaults keep the existing behavior.
+    controls = payload.get("tool_input", {}) if hook_event != "Notification" else {}
+    block_class = controls.get("blockClass") if isinstance(controls, dict) else None
+    if block_class in ("approval", "decision"):
+        block["blockClass"] = block_class
+    consequence = controls.get("consequence") if isinstance(controls, dict) else None
+    if consequence:
+        block["consequence"] = consequence
+    allowed = controls.get("allowedOperators") if isinstance(controls, dict) else None
+    if isinstance(allowed, list):
+        block["allowedOperators"] = [str(a) for a in allowed]
+    timeout = controls.get("timeoutMinutes") if isinstance(controls, dict) else None
+    if isinstance(timeout, (int, float)) and timeout > 0:
+        block["timeoutMinutes"] = int(timeout)
+    safe_default = controls.get("safeDefault") if isinstance(controls, dict) else None
+    if isinstance(safe_default, str):
+        block["safeDefault"] = safe_default
+    cost = controls.get("costOfDelay") if isinstance(controls, dict) else None
+    if cost in ("low", "medium", "high"):
+        block["costOfDelay"] = cost
+
+    # Publishing a new question clears any stale answered marker from the
+    # previous question in this session.
+    try:
+        os.unlink(os.path.join(answered_dir, f"{block_id}.json"))
+    except FileNotFoundError:
+        pass
+    except Exception:
+        pass
 
     # Python's expanduser() ignores HOME on Windows, while agents-cli honors a
     # HOME override on every platform. Use the same anchor so hooks and the CLI
     # always read/write one feed store (including temp-home and sandbox runs).
-    home = os.environ.get("HOME") or os.path.expanduser("~")
-    feed_dir = os.path.join(home, ".agents", ".history", "feed")
     os.makedirs(feed_dir, exist_ok=True)
 
-    target = os.path.join(feed_dir, f"{block_id}.json")
     fd, tmp = tempfile.mkstemp(dir=feed_dir, suffix=".tmp")
     try:
         with os.fdopen(fd, "w") as f:
             json.dump(block, f, indent=2)
-        os.rename(tmp, target)
+        os.replace(tmp, target)
     except Exception:
         try:
             os.unlink(tmp)
@@ -205,6 +534,26 @@ export const FEED_PUBLISH_HOOK_MANIFEST = {
     script: '10-feed-publish.py',
     timeout: 5,
 };
+export const FEED_NOTIFICATION_HOOK_MANIFEST = {
+    name: 'feed-publish-notification',
+    events: ['Notification'],
+    matcher: 'permission_prompt|idle_prompt|elicitation_dialog',
+    script: '10-feed-publish.py',
+    timeout: 5,
+};
+export const FEED_ANSWERED_HOOK_MANIFEST = {
+    name: 'feed-clear-answered',
+    events: ['PostToolUse'],
+    matcher: 'AskUserQuestion',
+    script: '10-feed-publish.py',
+    timeout: 5,
+};
+export const FEED_LIFECYCLE_HOOK_MANIFEST = {
+    name: 'feed-clear-lifecycle',
+    events: ['Stop', 'UserPromptSubmit', 'SessionEnd'],
+    script: '10-feed-publish.py',
+    timeout: 5,
+};
 /**
  * Install the feed-publish hook script into the user hooks dir and add its
  * manifest entry to the user agents.yaml. The system repo is an auto-pulled,
@@ -230,18 +579,45 @@ export function ensureFeedPublishHook(userAgentsDir = getUserAgentsDir()) {
         if (yamlDoc.errors.length > 0) {
             throw new Error(`Cannot install feed hook: ${agentsYamlPath} is invalid YAML`);
         }
-        if (!yamlDoc.getIn(['hooks', 'feed-publish'])) {
-            yamlDoc.setIn(['hooks', 'feed-publish'], {
+        const desiredHooks = {
+            'feed-publish': {
                 agents: ['claude'],
                 events: ['PreToolUse'],
                 matcher: 'AskUserQuestion',
                 script: '10-feed-publish.py',
                 timeout: 5,
-            });
+            },
+            'feed-publish-notification': {
+                agents: ['claude'],
+                events: ['Notification'],
+                matcher: 'permission_prompt|idle_prompt|elicitation_dialog',
+                script: '10-feed-publish.py',
+                timeout: 5,
+            },
+            'feed-clear-answered': {
+                agents: ['claude'],
+                events: ['PostToolUse'],
+                matcher: 'AskUserQuestion',
+                script: '10-feed-publish.py',
+                timeout: 5,
+            },
+            'feed-clear-lifecycle': {
+                agents: ['claude'],
+                events: ['Stop', 'UserPromptSubmit', 'SessionEnd'],
+                script: '10-feed-publish.py',
+                timeout: 5,
+            },
+        };
+        for (const [name, definition] of Object.entries(desiredHooks)) {
+            if (!yamlDoc.getIn(['hooks', name])) {
+                yamlDoc.setIn(['hooks', name], definition);
+                installed = true;
+            }
+        }
+        if (installed) {
             const tmpYaml = `${agentsYamlPath}.${process.pid}.tmp`;
             fs.writeFileSync(tmpYaml, String(yamlDoc));
             fs.renameSync(tmpYaml, agentsYamlPath);
-            installed = true;
         }
         return { installed };
     }

package/dist/lib/git.d.ts

@@ -88,9 +88,25 @@ export declare function commitAndPush(repoPath: string, message: string): Promis
  */
 export declare function hasUncommittedChanges(repoPath: string): Promise<boolean>;
 /**
- * Check if a directory is a git repository.
+ * Check if a directory is a git repository (**synchronous, root-only**).
+ *
+ * Tests for a `.git` entry directly under `dir`, so it recognizes only a
+ * repository *root* — it returns false inside a subdirectory and for linked
+ * worktrees (whose `.git` is a file pointing elsewhere is caught, but a nested
+ * cwd is not). This is deliberate: the system-repo sync callers here always
+ * pass a known root. For the async, worktree-correct predicate used by teams,
+ * see `isGitRepo` in `lib/teams/worktree.ts` (which shells out to
+ * `git rev-parse --git-dir`). The two are intentionally **not** merged.
  */
 export declare function isGitRepo(dir: string): boolean;
+/**
+ * Return the absolute path to the git working-tree root containing `dir`.
+ *
+ * Shells out to `git rev-parse --show-toplevel`, so it resolves correctly from
+ * any subdirectory and for linked worktrees (unlike the root-only, synchronous
+ * {@link isGitRepo} above). Throws if `dir` is not inside a git repository.
+ */
+export declare function getGitRoot(dir: string): Promise<string>;
 /**
  * Initialize a git repo in an existing directory.
  */

package/dist/lib/git.js

@@ -403,11 +403,30 @@ export async function hasUncommittedChanges(repoPath) {
     }
 }
 /**
- * Check if a directory is a git repository.
+ * Check if a directory is a git repository (**synchronous, root-only**).
+ *
+ * Tests for a `.git` entry directly under `dir`, so it recognizes only a
+ * repository *root* — it returns false inside a subdirectory and for linked
+ * worktrees (whose `.git` is a file pointing elsewhere is caught, but a nested
+ * cwd is not). This is deliberate: the system-repo sync callers here always
+ * pass a known root. For the async, worktree-correct predicate used by teams,
+ * see `isGitRepo` in `lib/teams/worktree.ts` (which shells out to
+ * `git rev-parse --git-dir`). The two are intentionally **not** merged.
  */
 export function isGitRepo(dir) {
     return fs.existsSync(path.join(dir, '.git'));
 }
+/**
+ * Return the absolute path to the git working-tree root containing `dir`.
+ *
+ * Shells out to `git rev-parse --show-toplevel`, so it resolves correctly from
+ * any subdirectory and for linked worktrees (unlike the root-only, synchronous
+ * {@link isGitRepo} above). Throws if `dir` is not inside a git repository.
+ */
+export async function getGitRoot(dir) {
+    const root = await simpleGit(dir).revparse(['--show-toplevel']);
+    return root.trim();
+}
 /**
  * Initialize a git repo in an existing directory.
  */