@phnx-labs/agents-cli 1.20.52 → 1.20.53

package/dist/lib/feed-outcome.js

@@ -0,0 +1,244 @@
+/**
+ * Outcome keys for the agent feed.
+ *
+ * 1,100 agents is not 1,100 things the operator cares about — dozens of agents
+ * map onto each real deliverable (a Linear ticket, a PR, a worktree/epic). The
+ * feed groups by **outcome** so one human reasons about initiatives, not
+ * processes. Every block is attributed to exactly one outcome; orphans land in
+ * the shared "Unassigned" bucket.
+ *
+ * Precedence (first match wins):
+ *   1. ticket   — RUSH-1125 / explicit `ticket` field / ticket-shaped branch
+ *   2. pr       — #534 / PR#534 / github.com/.../pull/534
+ *   3. worktree — `.agents/worktrees/<slug>` slug (or epic label)
+ *   4. unassigned
+ *
+ * Pure functions, no I/O — unit-testable and shared by `agents feed` rendering
+ * and any UI that collapses blocks under deliverables.
+ */
+import { detectTicket, extractPrUrl } from './session/state.js';
+const UNASSIGNED = {
+    key: 'unassigned',
+    kind: 'unassigned',
+    label: 'Unassigned',
+};
+/**
+ * Normalize a PR ref.
+ * - Full GitHub URL → `owner/repo#N` (repo identity included)
+ * - Bare `#123` / `PR#123` → `#123` (no repo known)
+ */
+export function normalizePrRef(raw) {
+    if (!raw)
+        return undefined;
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return undefined;
+    const fromUrl = extractPrUrl(trimmed);
+    if (fromUrl?.number != null) {
+        const repo = repoFromPrUrl(fromUrl.url);
+        return repo ? `${repo}#${fromUrl.number}` : `#${fromUrl.number}`;
+    }
+    const m = /(?:^|\bpr\s*#?\s*|pull\/|#)(\d{1,7})\b/i.exec(trimmed);
+    if (m)
+        return `#${m[1]}`;
+    return undefined;
+}
+/** `https://github.com/owner/repo/pull/N` → `owner/repo`. */
+export function repoFromPrUrl(url) {
+    if (!url)
+        return undefined;
+    const m = /github\.com\/([^/\s]+)\/([^/\s]+)\/pull\/\d+/i.exec(url);
+    if (!m)
+        return undefined;
+    return `${m[1]}/${m[2]}`;
+}
+/** Canonical ticket id (uppercase team key). */
+export function normalizeTicketRef(raw) {
+    if (!raw)
+        return undefined;
+    const m = raw.trim().match(/\b([A-Za-z]{2,6}-\d{1,6})\b/);
+    if (!m)
+        return undefined;
+    const id = m[1].toUpperCase();
+    // Reuse the session state's denylist via detectTicket on the id alone.
+    return detectTicket(id)?.id ?? id;
+}
+function ticketFromSignals(s) {
+    const direct = normalizeTicketRef(s.ticket ?? undefined);
+    if (direct)
+        return direct;
+    const fromText = detectTicket(s.text ?? undefined, s.branch ?? undefined)?.id;
+    return fromText;
+}
+function prFromSignals(s) {
+    const direct = normalizePrRef(s.pr ?? undefined);
+    if (direct)
+        return direct;
+    if (s.text) {
+        // Prefer full URL so keys include owner/repo (RUSH-1630).
+        const fromUrl = extractPrUrl(s.text);
+        if (fromUrl?.number != null) {
+            return normalizePrRef(fromUrl.url) ?? `#${fromUrl.number}`;
+        }
+        const m = /(?:\bpr\s*#?\s*|#)(\d{1,7})\b/i.exec(s.text);
+        if (m)
+            return `#${m[1]}`;
+    }
+    return undefined;
+}
+/**
+ * Derive the single outcome a block/agent belongs to.
+ * Exactly one outcome per call — never ambiguous, never empty.
+ */
+export function deriveOutcome(signals) {
+    const ticket = ticketFromSignals(signals);
+    if (ticket) {
+        return { key: `ticket:${ticket}`, kind: 'ticket', label: ticket };
+    }
+    const pr = prFromSignals(signals);
+    if (pr) {
+        // pr is either `owner/repo#N` or `#N`
+        const hash = pr.includes('#') ? pr.slice(pr.indexOf('#')) : pr;
+        const n = hash.replace(/^#/, '');
+        const label = pr.includes('/') ? `PR ${pr}` : `PR#${n}`;
+        return { key: `pr:${pr}`, kind: 'pr', label };
+    }
+    const wt = (signals.worktreeSlug ?? '').trim();
+    if (wt) {
+        return { key: `worktree:${wt}`, kind: 'worktree', label: wt };
+    }
+    const epic = (signals.epic ?? '').trim();
+    if (epic) {
+        // Epic folds into the worktree kind: both are soft deliverable labels
+        // without a tracker id. Key prefix keeps them disjoint from worktree slugs.
+        return { key: `epic:${epic}`, kind: 'worktree', label: epic };
+    }
+    return UNASSIGNED;
+}
+/** Join question headers + bodies into one scan target for ticket/PR detection. */
+export function blockScanText(block) {
+    return block.questions
+        .map((q) => [q.header, q.text].filter(Boolean).join(' '))
+        .filter(Boolean)
+        .join('\n');
+}
+/** Outcome for a stored open block (uses stamped fields + question text). */
+export function outcomeForBlock(block) {
+    return deriveOutcome({
+        ticket: block.ticket,
+        pr: block.pr,
+        worktreeSlug: block.worktreeSlug,
+        epic: block.epic,
+        text: blockScanText(block),
+    });
+}
+function isOpen(block) {
+    return !block.answer && !block.parkedAt && !block.continuedAt && !block.defaultedAt;
+}
+/**
+ * Collapse blocks under their outcome. Order: needs-you outcomes first
+ * (open count desc), then by label. Unassigned always last among ties of 0 open.
+ */
+export function groupBlocksByOutcome(blocks) {
+    const byKey = new Map();
+    for (const block of blocks) {
+        const outcome = outcomeForBlock(block);
+        const bucket = byKey.get(outcome.key);
+        if (bucket)
+            bucket.blocks.push(block);
+        else
+            byKey.set(outcome.key, { outcome, blocks: [block] });
+    }
+    const groups = [];
+    for (const { outcome, blocks: members } of byKey.values()) {
+        const mailboxes = new Set(members.map((b) => b.mailboxId));
+        let open = 0;
+        let answered = 0;
+        let parked = 0;
+        for (const b of members) {
+            if (b.parkedAt)
+                parked += 1;
+            else if (b.answer || b.defaultedAt || b.continuedAt)
+                answered += 1;
+            else
+                open += 1;
+        }
+        groups.push({
+            outcome,
+            blocks: members,
+            counts: { agents: mailboxes.size, open, answered, parked },
+        });
+    }
+    groups.sort((a, b) => {
+        // Unassigned always last.
+        if (a.outcome.kind === 'unassigned' && b.outcome.kind !== 'unassigned')
+            return 1;
+        if (b.outcome.kind === 'unassigned' && a.outcome.kind !== 'unassigned')
+            return -1;
+        if (b.counts.open !== a.counts.open)
+            return b.counts.open - a.counts.open;
+        return a.outcome.label.localeCompare(b.outcome.label);
+    });
+    return groups;
+}
+/**
+ * Stamp each block with its derived outcome for JSON consumers.
+ * Does not mutate the input records.
+ */
+export function stampBlockOutcomes(blocks) {
+    return blocks.map((b) => ({ ...b, outcome: outcomeForBlock(b) }));
+}
+/**
+ * True when every still-open block under the outcome asks the same question
+ * (same cluster of header+text). Fan-out answers are only safe when this holds
+ * — otherwise the operator must pick a specific agent.
+ */
+export function isUnambiguousOutcomeAnswer(group) {
+    const open = group.blocks.filter(isOpen);
+    if (open.length <= 1)
+        return open.length === 1;
+    const keys = new Set(open.map((b) => b.questions.map((q) => `${q.header ?? ''}\0${q.text}`).join('\n')));
+    return keys.size === 1;
+}
+/** Still-open blocks under an outcome (candidates for a fan-out reply). */
+export function openBlocksForOutcome(group) {
+    return group.blocks.filter(isOpen);
+}
+/**
+ * Overlay session meta onto a block when the block itself is missing ticket/PR/
+ * worktree. Never overwrites a field the block already carries.
+ */
+export function enrichBlockFromSession(block, hint) {
+    const next = { ...block };
+    if (!next.ticket && hint.ticketId)
+        next.ticket = hint.ticketId;
+    if (!next.pr) {
+        if (hint.prUrl)
+            next.pr = hint.prUrl;
+        else if (hint.prNumber != null)
+            next.pr = `#${hint.prNumber}`;
+    }
+    if (!next.worktreeSlug && hint.worktreeSlug)
+        next.worktreeSlug = hint.worktreeSlug;
+    return next;
+}
+/**
+ * Build a mailboxId → session-hint index and enrich every block. Pure.
+ * Matching order: mailboxId, then sessionId, then agentId.
+ */
+export function enrichBlocksFromSessions(blocks, sessions) {
+    const byMailbox = new Map();
+    const bySession = new Map();
+    for (const s of sessions) {
+        if (s.mailboxId)
+            byMailbox.set(s.mailboxId, s);
+        if (s.sessionId)
+            bySession.set(s.sessionId, s);
+        if (s.agentId)
+            bySession.set(s.agentId, s);
+    }
+    return blocks.map((b) => {
+        const hint = byMailbox.get(b.mailboxId) ?? bySession.get(b.sessionId);
+        return hint ? enrichBlockFromSession(b, hint) : b;
+    });
+}

package/dist/lib/feed-policy.d.ts

@@ -0,0 +1,30 @@
+import { type OpenBlock, type AnswerRecord } from './feed.js';
+export type BlockClass = 'approval' | 'decision';
+export interface ClassPolicy {
+    timeoutMinutes: number;
+    /** For approval class only: the answer to apply when the timeout fires. */
+    safeDefault?: string;
+}
+export interface FeedPolicy {
+    approval: ClassPolicy;
+    decision: ClassPolicy;
+    /** High-cost-of-delay blocks below this threshold do not page the phone. */
+    phoneNotifyThreshold: 'low' | 'medium' | 'high';
+}
+export declare const DEFAULT_POLICY: FeedPolicy;
+export declare function getPolicyPath(root?: string): string;
+export declare function loadPolicy(root?: string): FeedPolicy;
+export declare function blockClass(block: OpenBlock): BlockClass;
+export declare function isPhoneUrgent(block: OpenBlock, policy: FeedPolicy): boolean;
+export declare function minutesElapsed(block: OpenBlock, now: Date): number;
+export declare function isTimedOut(block: OpenBlock, policy: FeedPolicy, now: Date): boolean;
+export interface PolicyResult {
+    blockId: string;
+    action: 'none' | 'defaulted' | 'parked';
+    answer?: AnswerRecord;
+}
+/**
+ * Apply policy to a single open block. Returns the action taken (none/defaulted/parked).
+ * Caller is responsible for persistence/logging side effects not owned by feed.ts.
+ */
+export declare function applyPolicyToBlock(block: OpenBlock, policy: FeedPolicy, now: Date, root?: string): PolicyResult;

package/dist/lib/feed-policy.js

@@ -0,0 +1,133 @@
+/**
+ * Feed timeout policy — unattended default-on-no-answer behavior.
+ *
+ * Two block classes:
+ *   - Approval: has a safe default (e.g. 'deny'). After the configured timeout with
+ *     no operator answer, the policy auto-records that default and queues it to the
+ *     agent. Logged so the operator can audit later.
+ *   - Decision: no safe default (a real choice). After the timeout the block is
+ *     hard-parked: a parked marker is recorded and, if we can locate the session
+ *     process, it is stopped so the agent cannot proceed on a stale default.
+ *
+ * Policy is loaded from ~/.agents/feed-policy.yaml. Missing file uses the built-in
+ * conservative defaults.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as yaml from 'yaml';
+import { getUserAgentsDir } from './state.js';
+import { recordAnswer, recordDefaulted, recordMessageReceipt, recordParked, } from './feed.js';
+import { enqueue, mailboxDir } from './mailbox.js';
+const POLICY_FILE = 'feed-policy.yaml';
+const COST_RANK = { low: 0, medium: 1, high: 2 };
+export const DEFAULT_POLICY = {
+    approval: { timeoutMinutes: 30, safeDefault: 'deny' },
+    decision: { timeoutMinutes: 60 },
+    phoneNotifyThreshold: 'medium',
+};
+export function getPolicyPath(root) {
+    return path.join(root ?? getUserAgentsDir(), POLICY_FILE);
+}
+function normalizeClassPolicy(raw) {
+    const p = (raw ?? {});
+    const timeout = typeof p.timeoutMinutes === 'number' ? p.timeoutMinutes : DEFAULT_POLICY.approval.timeoutMinutes;
+    return {
+        timeoutMinutes: Math.max(1, Math.round(timeout)),
+        safeDefault: typeof p.safeDefault === 'string' ? p.safeDefault : undefined,
+    };
+}
+export function loadPolicy(root) {
+    const file = getPolicyPath(root);
+    try {
+        const raw = fs.readFileSync(file, 'utf-8');
+        const parsed = yaml.parse(raw);
+        if (parsed && typeof parsed === 'object') {
+            const p = parsed;
+            const threshold = p.phoneNotifyThreshold;
+            return {
+                approval: normalizeClassPolicy(p.approval ?? { timeoutMinutes: DEFAULT_POLICY.approval.timeoutMinutes, safeDefault: DEFAULT_POLICY.approval.safeDefault }),
+                decision: normalizeClassPolicy(p.decision ?? { timeoutMinutes: DEFAULT_POLICY.decision.timeoutMinutes }),
+                phoneNotifyThreshold: threshold === 'low' || threshold === 'medium' || threshold === 'high' ? threshold : DEFAULT_POLICY.phoneNotifyThreshold,
+            };
+        }
+    }
+    catch {
+        // missing or malformed -> defaults
+    }
+    return DEFAULT_POLICY;
+}
+export function blockClass(block) {
+    return block.blockClass === 'decision' ? 'decision' : 'approval';
+}
+export function isPhoneUrgent(block, policy) {
+    if (block.answer)
+        return false; // already answered
+    const cost = block.costOfDelay ?? 'low';
+    return COST_RANK[cost] >= COST_RANK[policy.phoneNotifyThreshold];
+}
+export function minutesElapsed(block, now) {
+    const ts = Date.parse(block.ts);
+    if (Number.isNaN(ts))
+        return 0;
+    return (now.getTime() - ts) / 60_000;
+}
+export function isTimedOut(block, policy, now) {
+    const cls = blockClass(block);
+    const minutes = minutesElapsed(block, now);
+    return minutes >= policy[cls].timeoutMinutes;
+}
+/**
+ * Apply policy to a single open block. Returns the action taken (none/defaulted/parked).
+ * Caller is responsible for persistence/logging side effects not owned by feed.ts.
+ */
+export function applyPolicyToBlock(block, policy, now, root) {
+    if (block.answer || block.parkedAt || block.defaultedAt) {
+        return { blockId: block.blockId, action: 'none' };
+    }
+    if (!isTimedOut(block, policy, now)) {
+        return { blockId: block.blockId, action: 'none' };
+    }
+    const cls = blockClass(block);
+    if (cls === 'approval') {
+        const safeDefault = block.safeDefault ?? policy.approval.safeDefault;
+        if (!safeDefault) {
+            return { blockId: block.blockId, action: 'none' };
+        }
+        const claim = recordAnswer(block.blockId, { answeredFrom: 'policy', answeredBy: 'default-on-no-answer', operatorId: 'policy', verified: true }, root);
+        if (!claim.ok) {
+            return { blockId: block.blockId, action: 'none' };
+        }
+        const msgId = enqueue(mailboxDir(block.mailboxId, root ?? undefined), {
+            to: block.mailboxId,
+            text: safeDefault,
+            from: 'policy',
+            blockId: block.blockId,
+        });
+        recordMessageReceipt(block.blockId, { msgId, status: 'queued', at: now.toISOString(), from: 'policy' }, root);
+        recordDefaulted(block.blockId, root);
+        return {
+            blockId: block.blockId,
+            action: 'defaulted',
+            answer: {
+                answeredAt: now.toISOString(),
+                answeredFrom: 'policy',
+                answeredBy: 'default-on-no-answer',
+                operatorId: 'policy',
+                verified: true,
+            },
+        };
+    }
+    // Decision class: hard-park.
+    recordParked(block.blockId, root);
+    return {
+        blockId: block.blockId,
+        action: 'parked',
+        answer: {
+            answeredAt: now.toISOString(),
+            answeredFrom: 'policy',
+            answeredBy: 'hard-park',
+            operatorId: 'policy',
+            verified: true,
+        },
+    };
+}

package/dist/lib/feed.d.ts

@@ -8,6 +8,28 @@ export interface BlockQuestion {
     options?: BlockOption[];
     multiSelect?: boolean;
 }
+export interface MessageReceipt {
+    /** The message id this receipt describes. */
+    msgId: string;
+    /** Delivery lifecycle state. */
+    status: 'queued' | 'consumed' | 'continued';
+    /** ISO-8601 timestamp of the state transition. */
+    at: string;
+    /** Optional sender label for the message. */
+    from?: string;
+}
+export interface AnswerRecord {
+    /** ISO-8601 timestamp of when the answer was recorded. */
+    answeredAt: string;
+    /** Surface that recorded the answer (e.g. 'feed', 'terminal', 'tmux', 'cloud', 'policy'). */
+    answeredFrom: string;
+    /** Optional operator/agent label recorded as the sender. */
+    answeredBy?: string;
+    /** Operator id from the local registry, if verified. */
+    operatorId?: string;
+    /** Whether the operator identity was verified against the registry. */
+    verified?: boolean;
+}
 export interface OpenBlock {
     blockId: string;
     sessionId: string;
@@ -16,26 +38,108 @@ export interface OpenBlock {
     runtime: string;
     ts: string;
     questions: BlockQuestion[];
+    kind?: 'question' | 'notification';
+    notificationType?: string;
     ticket?: string;
     pr?: string;
+    /** Worktree slug under `.agents/worktrees/` — soft outcome when no ticket/PR. */
+    worktreeSlug?: string;
+    /** Epic / initiative label when no ticket/PR/worktree is known. */
+    epic?: string;
+    /** Block class: approval has a safe default; decision requires human choice. */
+    blockClass?: 'approval' | 'decision';
+    /** Consequence tag for authz. 'high' gates merge/deploy/admin-style answers. */
+    consequence?: 'normal' | 'high' | string;
+    /** Operator ids allowed to answer a high-consequence block. Admins always pass. */
+    allowedOperators?: string[];
+    /** Timeout in minutes before default-on-no-answer policy fires. */
+    timeoutMinutes?: number;
+    /** Safe default answer for approval-class blocks. */
+    safeDefault?: string;
+    /** Cost-of-delay for notification routing: low/medium/high. */
+    costOfDelay?: 'low' | 'medium' | 'high';
+    /** Set once the block has been answered; see `recordAnswer`. */
+    answer?: AnswerRecord;
+    /** Per-message delivery receipts for answers to this block. */
+    receipts?: MessageReceipt[];
+    /** ISO-8601 timestamp when the agent continued past the block. */
+    continuedAt?: string;
+    /** ISO-8601 timestamp when an urgent block was paged to the phone. */
+    notifiedAt?: string;
+    /** ISO-8601 timestamp when the approval safe-default was applied. */
+    defaultedAt?: string;
+    /** ISO-8601 timestamp when a decision block was hard-parked. */
+    parkedAt?: string;
 }
 /**
  * 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).
  */
 export declare function blockIdForSession(sessionId: string): string;
-/** Atomic write a block record to the feed store. */
+/** Read one block record. Returns undefined when missing or corrupt. */
+export declare function readBlock(blockId: string, root?: string): OpenBlock | undefined;
+export type RecordAnswerResult = {
+    ok: true;
+} | {
+    ok: false;
+    existing: AnswerRecord;
+} | {
+    ok: false;
+    unauthorized: true;
+    reason: string;
+};
+/**
+ * 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 declare function recordAnswer(blockId: string, answer: {
+    answeredBy?: string;
+    answeredFrom: string;
+    operatorId?: string;
+    verified?: boolean;
+}, root?: string): RecordAnswerResult;
+/** Read the answer record for a block, if one exists. */
+export declare function getAnswerRecord(blockId: string, root?: string): AnswerRecord | undefined;
+/** True when the block has already been answered. */
+export declare function isBlockAnswered(blockId: string, root?: string): boolean;
+/**
+ * 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 declare function recordMessageReceipt(blockId: string, receipt: MessageReceipt, root?: string): void;
+/** Read the receipt list for a block. */
+export declare function getBlockReceipts(blockId: string, root?: string): MessageReceipt[];
+/** Mark a block as "continued" -- the agent consumed the answer and moved on. */
+export declare function recordContinued(blockId: string, root?: string): void;
+/** Mark a decision-class block as hard-parked (no safe default existed). */
+export declare function recordParked(blockId: string, root?: string): void;
+/** Mark that the approval safe-default was applied by policy. */
+export declare function recordDefaulted(blockId: string, root?: string): void;
+/** Mark that an urgent block was paged to the phone. */
+export declare function recordNotified(blockId: string, root?: string): void;
+/** Convenience: record that a terminal answer closed the block. */
+export declare function recordTerminalAnswer(blockId: string, root?: string): void;
+/** Remove answered marker and receipts for a block (used by block removal/GC). */
+export declare function clearBlockLifecycle(blockId: string, root?: string): void;
+/** Atomic write a block record to the feed store. Clears stale lifecycle state. */
 export declare function publishBlock(block: OpenBlock, root?: string): void;
 /** Read all block records. Returns them sorted by stable block filename. */
 export declare function listBlocks(root?: string): OpenBlock[];
-/** 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 declare function removeBlock(blockId: string, root?: string): boolean;
 /**
  * The feed-publish PreToolUse hook script (Python, mirroring 09-mailbox-inject.py).
  * Embedded so it ships with the compiled CLI and can be installed to the
  * CLI-writable user hooks dir without a separate file in the npm tarball.
  */
-export declare const FEED_PUBLISH_HOOK_SCRIPT = "#!/usr/bin/env python3\n\"\"\"PreToolUse hook: publish an open-block record when the agent calls\nAskUserQuestion, so `agents feed` can aggregate pending decisions.\n\nOutbound counterpart to the inbound mailbox-inject hook. Fires only on\nAskUserQuestion (matcher-gated in agents.yaml). Writes one block per session\nto ~/.agents/.history/feed/. A new question replaces the previous block.\n\nSub-agent gate: when the PreToolUse payload carries `agent_type`, this is a\nTask/Agent subagent -- skip. Only the top-level agent publishes. Verified on\nClaude Code 2.1.170 (2026-07).\n\nFail-open: ANY error is swallowed so a feed hiccup never blocks a tool call.\n\"\"\"\nimport os\nimport sys\nimport json\nimport re\nimport socket\nimport tempfile\nfrom datetime import datetime, timezone\n\n\ndef main():\n    raw = sys.stdin.read()\n    try:\n        payload = json.loads(raw) if raw.strip() else {}\n    except Exception:\n        return\n\n    # Sub-agent gate.\n    if payload.get(\"agent_type\"):\n        return\n\n    tool_input = payload.get(\"tool_input\", {})\n    questions = tool_input.get(\"questions\", [])\n    if not questions:\n        return\n\n    session_id = payload.get(\"session_id\", \"\")\n    if not session_id:\n        return\n\n    normalized_questions = []\n    for q in questions:\n        if not isinstance(q, dict):\n            continue\n        question = {\n            \"text\": q.get(\"question\", q.get(\"header\", \"\")),\n            \"header\": q.get(\"header\"),\n            \"multiSelect\": q.get(\"multiSelect\", False),\n        }\n        raw_opts = q.get(\"options\", [])\n        if raw_opts:\n            question[\"options\"] = [\n                {\"label\": o.get(\"label\", \"\"), \"description\": o.get(\"description\")}\n                for o in raw_opts\n                if isinstance(o, dict)\n            ]\n        normalized_questions.append(question)\n    if not normalized_questions:\n        return\n\n    # Identity from env (set by agents-cli at spawn).\n    mailbox_id = os.path.basename(\n        os.environ.get(\"AGENTS_MAILBOX_DIR\", \"\").rstrip(\"/\")\n    ) or session_id\n\n    hostname = os.environ.get(\"AGENTS_SYNC_MACHINE_ID\") or socket.gethostname()\n    host = hostname.split(\".\")[0].strip().lower()\n    host = re.sub(r\"[^a-z0-9_-]\", \"-\", host) or \"unknown\"\n\n    runtime = os.environ.get(\"AGENTS_RUNTIME\", \"headless\")\n\n    safe_session_id = re.sub(r\"[^A-Za-z0-9._-]\", \"-\", session_id)\n    block_id = f\"block-{safe_session_id}\"\n    block = {\n        \"blockId\": block_id,\n        \"sessionId\": session_id,\n        \"mailboxId\": mailbox_id,\n        \"host\": host,\n        \"runtime\": runtime,\n        \"ts\": datetime.now(timezone.utc).isoformat(),\n        \"questions\": normalized_questions,\n    }\n\n    # Python's expanduser() ignores HOME on Windows, while agents-cli honors a\n    # HOME override on every platform. Use the same anchor so hooks and the CLI\n    # always read/write one feed store (including temp-home and sandbox runs).\n    home = os.environ.get(\"HOME\") or os.path.expanduser(\"~\")\n    feed_dir = os.path.join(home, \".agents\", \".history\", \"feed\")\n    os.makedirs(feed_dir, exist_ok=True)\n\n    target = os.path.join(feed_dir, f\"{block_id}.json\")\n    fd, tmp = tempfile.mkstemp(dir=feed_dir, suffix=\".tmp\")\n    try:\n        with os.fdopen(fd, \"w\") as f:\n            json.dump(block, f, indent=2)\n        os.rename(tmp, target)\n    except Exception:\n        try:\n            os.unlink(tmp)\n        except Exception:\n            pass\n\n\nif __name__ == \"__main__\":\n    try:\n        main()\n    except Exception:\n        pass  # fail open\n";
+export declare const FEED_PUBLISH_HOOK_SCRIPT = "#!/usr/bin/env python3\n\"\"\"Publish and clear open-block records for `agents feed`.\n\nThe manifest invokes this script for top-level AskUserQuestion calls, waiting\nnotifications, question answers, and session lifecycle events. One atomic file\nper session means a new block replaces the previous block. Answer/resume/stop\nevents remove it so `agents feed` only lists decisions that are still open.\n\nSub-agent gate: when the PreToolUse payload carries `agent_type`, this is a\nTask/Agent subagent -- skip. Only the top-level agent publishes. Verified on\nClaude Code 2.1.170 (2026-07).\n\nFail-open: ANY error is swallowed so a feed hiccup never blocks a tool call.\n\"\"\"\nimport os\nimport sys\nimport json\nimport re\nimport socket\nimport tempfile\nfrom datetime import datetime, timezone\n\nWAITING_NOTIFICATION_TYPES = {\n    \"permission_prompt\",\n    \"idle_prompt\",\n    \"elicitation_dialog\",\n}\nCLEAR_EVENTS = {\n    \"PostToolUse\",\n    \"Stop\",\n    \"SessionEnd\",\n}\n\n\ndef read_json(path):\n    try:\n        with open(path) as f:\n            return json.load(f)\n    except Exception:\n        return None\n\n\ndef write_json(path, value):\n    dir_name = os.path.dirname(path)\n    os.makedirs(dir_name, exist_ok=True)\n    fd, tmp = tempfile.mkstemp(dir=dir_name, suffix=\".tmp\")\n    try:\n        with os.fdopen(fd, \"w\") as f:\n            json.dump(value, f, indent=2)\n        os.replace(tmp, path)\n    except Exception:\n        try:\n            os.unlink(tmp)\n        except Exception:\n            pass\n\n\ndef main():\n    raw = sys.stdin.read()\n    try:\n        payload = json.loads(raw) if raw.strip() else {}\n    except Exception:\n        return\n\n    # Sub-agent gate.\n    if payload.get(\"agent_type\"):\n        return\n\n    session_id = payload.get(\"session_id\", \"\")\n    if not session_id:\n        return\n\n    safe_session_id = re.sub(r\"[^A-Za-z0-9._-]\", \"-\", session_id)\n    block_id = f\"block-{safe_session_id}\"\n    home = os.environ.get(\"HOME\") or os.path.expanduser(\"~\")\n    feed_dir = os.path.join(home, \".agents\", \".history\", \"feed\")\n    answered_dir = os.path.join(feed_dir, \"answered\")\n    target = os.path.join(feed_dir, f\"{block_id}.json\")\n    hook_event = payload.get(\"hook_event_name\", \"PreToolUse\")\n\n    if hook_event in CLEAR_EVENTS:\n        try:\n            os.unlink(target)\n        except FileNotFoundError:\n            pass\n        except Exception:\n            pass\n        # Also clear the answered marker so a future question for this session\n        # is not permanently locked.\n        try:\n            os.unlink(os.path.join(answered_dir, f\"{block_id}.json\"))\n        except FileNotFoundError:\n            pass\n        except Exception:\n            pass\n        return\n\n    # Terminal answers (human typed in the TUI) record an answered marker and\n    # remove the block file so the feed stops showing it within one poll cycle.\n    # The marker stays behind so a concurrent surface cannot double-answer.\n    if hook_event == \"UserPromptSubmit\":\n        os.makedirs(answered_dir, exist_ok=True)\n        marker = os.path.join(answered_dir, f\"{block_id}.json\")\n        try:\n            fd = os.open(marker, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o644)\n            record = {\n                \"answeredAt\": datetime.now(timezone.utc).isoformat(),\n                \"answeredFrom\": \"terminal\",\n            }\n            with os.fdopen(fd, \"w\") as f:\n                json.dump(record, f, indent=2)\n        except FileExistsError:\n            pass\n        except Exception:\n            pass\n        # Remove the visible block so the feed drops the answered question.\n        try:\n            os.unlink(target)\n        except FileNotFoundError:\n            pass\n        except Exception:\n            pass\n        return\n\n    notification_type = None\n    if hook_event == \"Notification\":\n        notification_type = payload.get(\"notification_type\", \"\")\n        if notification_type not in WAITING_NOTIFICATION_TYPES:\n            return\n        # Claude emits a generic permission notification after presenting an\n        # AskUserQuestion. Keep the structured questions and options already\n        # published for this session instead of replacing them with that less\n        # useful notification text.\n        try:\n            with open(target) as existing_file:\n                existing = json.load(existing_file)\n            if existing.get(\"kind\") == \"question\":\n                return\n        except Exception:\n            pass\n        message = payload.get(\"message\", \"\")\n        if not message:\n            return\n        normalized_questions = [{\n            \"text\": message,\n            \"header\": payload.get(\"title\") or notification_type.replace(\"_\", \" \").title(),\n            \"multiSelect\": False,\n        }]\n        kind = \"notification\"\n    else:\n        tool_input = payload.get(\"tool_input\", {})\n        questions = tool_input.get(\"questions\", [])\n        if not questions:\n            return\n        normalized_questions = []\n        for q in questions:\n            if not isinstance(q, dict):\n                continue\n            question = {\n                \"text\": q.get(\"question\", q.get(\"header\", \"\")),\n                \"header\": q.get(\"header\"),\n                \"multiSelect\": q.get(\"multiSelect\", False),\n            }\n            raw_opts = q.get(\"options\", [])\n            if raw_opts:\n                question[\"options\"] = [\n                    {\"label\": o.get(\"label\", \"\"), \"description\": o.get(\"description\")}\n                    for o in raw_opts\n                    if isinstance(o, dict)\n                ]\n            normalized_questions.append(question)\n        if not normalized_questions:\n            return\n        kind = \"question\"\n\n    # Identity from env (set by agents-cli at spawn).\n    mailbox_id = os.path.basename(\n        os.environ.get(\"AGENTS_MAILBOX_DIR\", \"\").rstrip(\"/\")\n    ) or session_id\n\n    hostname = os.environ.get(\"AGENTS_SYNC_MACHINE_ID\") or socket.gethostname()\n    host = hostname.split(\".\")[0].strip().lower()\n    host = re.sub(r\"[^a-z0-9_-]\", \"-\", host) or \"unknown\"\n\n    runtime = os.environ.get(\"AGENTS_RUNTIME\", \"headless\")\n\n    block = {\n        \"blockId\": block_id,\n        \"sessionId\": session_id,\n        \"mailboxId\": mailbox_id,\n        \"host\": host,\n        \"runtime\": runtime,\n        \"ts\": datetime.now(timezone.utc).isoformat(),\n        \"questions\": normalized_questions,\n        \"kind\": kind,\n    }\n    if notification_type:\n        block[\"notificationType\"] = notification_type\n\n    # Optional multi-operator control metadata passed by the agent in the\n    # AskUserQuestion tool_input. Defaults keep the existing behavior.\n    controls = payload.get(\"tool_input\", {}) if hook_event != \"Notification\" else {}\n    block_class = controls.get(\"blockClass\") if isinstance(controls, dict) else None\n    if block_class in (\"approval\", \"decision\"):\n        block[\"blockClass\"] = block_class\n    consequence = controls.get(\"consequence\") if isinstance(controls, dict) else None\n    if consequence:\n        block[\"consequence\"] = consequence\n    allowed = controls.get(\"allowedOperators\") if isinstance(controls, dict) else None\n    if isinstance(allowed, list):\n        block[\"allowedOperators\"] = [str(a) for a in allowed]\n    timeout = controls.get(\"timeoutMinutes\") if isinstance(controls, dict) else None\n    if isinstance(timeout, (int, float)) and timeout > 0:\n        block[\"timeoutMinutes\"] = int(timeout)\n    safe_default = controls.get(\"safeDefault\") if isinstance(controls, dict) else None\n    if isinstance(safe_default, str):\n        block[\"safeDefault\"] = safe_default\n    cost = controls.get(\"costOfDelay\") if isinstance(controls, dict) else None\n    if cost in (\"low\", \"medium\", \"high\"):\n        block[\"costOfDelay\"] = cost\n\n    # Publishing a new question clears any stale answered marker from the\n    # previous question in this session.\n    try:\n        os.unlink(os.path.join(answered_dir, f\"{block_id}.json\"))\n    except FileNotFoundError:\n        pass\n    except Exception:\n        pass\n\n    # Python's expanduser() ignores HOME on Windows, while agents-cli honors a\n    # HOME override on every platform. Use the same anchor so hooks and the CLI\n    # always read/write one feed store (including temp-home and sandbox runs).\n    os.makedirs(feed_dir, exist_ok=True)\n\n    fd, tmp = tempfile.mkstemp(dir=feed_dir, suffix=\".tmp\")\n    try:\n        with os.fdopen(fd, \"w\") as f:\n            json.dump(block, f, indent=2)\n        os.replace(tmp, target)\n    except Exception:\n        try:\n            os.unlink(tmp)\n        except Exception:\n            pass\n\n\nif __name__ == \"__main__\":\n    try:\n        main()\n    except Exception:\n        pass  # fail open\n";
 /** Manifest entry for the feed-publish hook, matching the ManifestHook shape. */
 export declare const FEED_PUBLISH_HOOK_MANIFEST: {
     name: string;
@@ -44,6 +148,26 @@ export declare const FEED_PUBLISH_HOOK_MANIFEST: {
     script: string;
     timeout: number;
 };
+export declare const FEED_NOTIFICATION_HOOK_MANIFEST: {
+    name: string;
+    events: string[];
+    matcher: string;
+    script: string;
+    timeout: number;
+};
+export declare const FEED_ANSWERED_HOOK_MANIFEST: {
+    name: string;
+    events: string[];
+    matcher: string;
+    script: string;
+    timeout: number;
+};
+export declare const FEED_LIFECYCLE_HOOK_MANIFEST: {
+    name: string;
+    events: string[];
+    script: string;
+    timeout: number;
+};
 /**
  * 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,