pi-quiver 5.0.0 → 5.1.0

package/CHANGELOG.md

@@ -8,6 +8,10 @@ Published to npm as `pi-quiver` (`pi install npm:pi-quiver`). Pushing a
 via OIDC trusted publishing. The release helper at
 `.agents/skills/release/scripts/release.sh` cuts the tag; CI publishes.
 
+## v5.1.0 - 2026-09-01
+
+- `slack`: optional `policyPath` config injects a repo policy file into the system prompt every turn (`<slack-policy source="...">`); a missing/unreadable/empty file degrades to a `status=` block plus one deduped warning, tools stay fully usable either way (#9). `slack_post`/`slack_update` now resolve `@name` mentions to `<@U...>` (cache-first, one batched `users.list` live pass), leaving unresolvable names literal and reported via `unresolved mentions: ...` plus `details.unresolvedMentions`. The name cache gained an optional per-user `email` field and a file-level `snapshot_at` marker (set only by a full `slack_cache_refresh`, gating whether an alias match can be trusted straight from cache); `slack_cache_refresh`'s result line now reports an email/user ratio with a missing-scope hint. `slack_post` gained `unfurl_links`/`unfurl_media` params, applied to the headline and inline detail leg (never the upload stub), omitted when unset so Slack's default stands; `slack_update` has no equivalent (`chat.update` has no unfurl argument). See [doc/slack.md](doc/slack.md).
+
 ## v5.0.0 - 2026-08-29
 
 - **New opt-in `slack` extension** (#7): eight `slack_*` tools (search, thread, post, update, delete, pin, upload, cache refresh) for context-safe Slack search/threads/posting. Dual `user`/`bot` token identities resolved per call from process env or the repo's `.env`, never cross-identity fallback. Workspace-keyed channel/user name->ID cache with a repo-overridable `cachePath`. Fetch-style output size gating on search/thread reads. `slack_post`'s `thread_body` (no `thread_ts`) posts a transactional headline+thread announce - oversized detail bodies upload as a file - with a documented recovery path on delivery failure. OFF by default; nested-only `quiver.slack` config, no legacy flat form. See [doc/slack.md](doc/slack.md).

package/README.md

@@ -18,7 +18,7 @@ But the moment an agent does that, one `fetch` or PDF read can dump hundreds of
 
 `fetch` and `doc_to_md` bring real web pages, GitHub issues/PRs, and local PDF/DOCX/PPTX files into context - and every result is size-gated by construction: over 32 KB or 1000 lines spills to a temp file with a preview and a grep/read hint, so a single call can never flood the window. Ingestion is what makes data-driven work possible; the gate is what keeps it safe.
 
-`session-name`, `sword-header`, `fast-mode`, `provider-stall-watchdog`, and `slack` are opt-in ergonomics, recovery, and integration controls: session labeling, a themed startup header, Anthropic fast mode, semantic-stall recovery, and context-safe Slack search/threads/posting.
+`session-name`, `sword-header`, `fast-mode`, `provider-stall-watchdog`, and `slack` are opt-in ergonomics, recovery, and integration controls: session labeling, a themed startup header, Anthropic fast mode, semantic-stall recovery, and context-safe Slack search/threads/posting with repo-policy injection, `@name` mention resolution, cached emails, and per-call unfurl control.
 
 ## Part of the pi agent toolkit
 

package/extensions/slack.ts

@@ -16,6 +16,7 @@ import { basename, isAbsolute, join } from "node:path";
 import {
 	defaultApiCall,
 	defaultUploadBytes,
+	buildPolicyBlock,
 	discoverRepoRoot,
 	resolveSlackConfig,
 	resolveToken,
@@ -26,6 +27,7 @@ import {
 	deleteMessage,
 	pinMessage,
 	uploadFile,
+	formatUnresolvedSuffix,
 	SlackError,
 	type SlackConfig,
 	type CoreDeps,
@@ -33,8 +35,9 @@ import {
 	type AnnounceResult,
 	type SearchResult,
 	type ThreadResult,
+	type UnresolvedMention,
 } from "../lib/slack-core.ts";
-import { cacheFilePath, teamIdFor, resolveChannel, refreshCache, assertSameTeam, type CacheCtx } from "../lib/slack-cache.ts";
+import { cacheFilePath, teamIdFor, resolveChannel, refreshCache, resolveMentions, assertSameTeam, type CacheCtx } from "../lib/slack-cache.ts";
 
 const IDENTITY = Type.Union([Type.Literal("user"), Type.Literal("bot")], {
 	description: 'Which token to act as: "user" (a real person, needed for slack_search/slack_thread) or "bot" (an app identity). Determines which token env var is used and whose name shows as the author.',
@@ -139,6 +142,19 @@ export function channelLine(result: MutationResult | (MutationResult & { fileId:
 	return parts.join(" | ");
 }
 
+/** Shared by slack_post/slack_update: the channelLine + unresolved-mentions suffix result shape. */
+function mentionAwareResult(
+	result: MutationResult | AnnounceResult,
+	mentions: { unresolved: UnresolvedMention[]; lookupError?: string },
+	opts: { detailUploaded?: boolean } = {},
+) {
+	const suffix = formatUnresolvedSuffix(mentions.unresolved, { lookupError: mentions.lookupError, ...opts });
+	return {
+		content: [{ type: "text" as const, text: suffix ? `${channelLine(result)} | ${suffix}` : channelLine(result) }],
+		details: { ...result, ...(mentions.unresolved.length > 0 ? { unresolvedMentions: mentions.unresolved } : {}) },
+	};
+}
+
 export function searchResultText(result: SearchResult): string {
 	return `${result.output}\n\ntotal: ${result.total} | page: ${result.page} of ${result.pageCount}`;
 }
@@ -191,6 +207,36 @@ export default function slackExtension(pi: ExtensionAPI) {
 
 		const repoRoot = discoverRepoRoot(ctx.cwd);
 
+		const policyPath = cfg.policyPath;
+		if (policyPath !== undefined) {
+			const resolvedPolicyPath = isAbsolute(policyPath) ? policyPath : join(repoRoot, policyPath);
+			let policyWarned = false;
+			const warnOnce = (eventCtx: typeof ctx, message: string): void => {
+				if (policyWarned) return;
+				policyWarned = true;
+				if (eventCtx.hasUI) eventCtx.ui.notify(message, "warning");
+				else console.warn(message);
+			};
+
+			pi.on("before_agent_start", async (event, eventCtx) => {
+				let block: string;
+				try {
+					const body = readFileSync(resolvedPolicyPath, "utf8");
+					if (body.trim() === "") {
+						warnOnce(eventCtx, `pi-quiver: Slack policy file ${policyPath} is empty; posting policy is unknown this session.`);
+						block = buildPolicyBlock({ source: policyPath, status: "empty" });
+					} else {
+						block = buildPolicyBlock({ source: policyPath, status: "ok", body });
+					}
+				} catch (err) {
+					const code = (err as { code?: string }).code ?? (err instanceof Error ? err.message : String(err));
+					warnOnce(eventCtx, `pi-quiver: Slack policy file ${policyPath} could not be read (${code}); posting policy is unknown this session.`);
+					block = buildPolicyBlock({ source: policyPath, status: "unreadable", code });
+				}
+				return { systemPrompt: `${event.systemPrompt}\n\n${block}` };
+			});
+		}
+
 		pi.registerTool({
 			name: "slack_search",
 			label: "Slack Search",
@@ -248,7 +294,7 @@ export default function slackExtension(pi: ExtensionAPI) {
 			label: "Slack Post",
 			promptSnippet: "Post a Slack message, reply, or headline+detail announcement",
 			description:
-				"Post a Slack message via chat.postMessage, as `as: \"user\"` or `as: \"bot\"`. `channel` accepts #name or a channel ID (user @names not accepted). Plain post: `text` and/or `blocks` (Block Kit JSON, passed through unvalidated). Threaded reply: also set `thread_ts` - no headline is ever emitted, `thread_body` (or `text`) becomes the reply body. Announce mode: set `thread_body` WITHOUT `thread_ts` - posts a short single-line `text` headline, then posts `thread_body` as the first threaded reply in the same call; if `thread_body`'s rendered length exceeds the configured uploadThresholdChars (default 4000), it is delivered as a threaded file upload instead. Recovery: re-invoke with `thread_ts` set (never re-omit it) to post only into the existing thread - a second headline is never sent. On detail-delivery failure the headline is marked \"detail pending\" and the detail is saved to a temp file; the error names the path.",
+				"Post a Slack message via chat.postMessage, as `as: \"user\"` or `as: \"bot\"`. `channel` accepts #name or a channel ID (user @names not accepted). Plain post: `text` and/or `blocks` (Block Kit JSON, passed through unvalidated). Threaded reply: also set `thread_ts` - no headline is ever emitted, `thread_body` (or `text`) becomes the reply body. Announce mode: set `thread_body` WITHOUT `thread_ts` - posts a short single-line `text` headline, then posts `thread_body` as the first threaded reply in the same call; if `thread_body`'s rendered length exceeds the configured uploadThresholdChars (default 4000), it is delivered as a threaded file upload instead. Recovery: re-invoke with `thread_ts` set (never re-omit it) to post only into the existing thread - a second headline is never sent. On detail-delivery failure the headline is marked \"detail pending\" and the detail is saved to a temp file; the error names the path. `unfurl_links`/`unfurl_media` apply to this post only, are omitted when unset (Slack's default stands), and slack_update cannot change unfurling after the fact.",
 			parameters: Type.Object({
 				as: IDENTITY,
 				channel: Type.String({ description: "#name or channel ID (user @names not accepted)" }),
@@ -256,20 +302,69 @@ export default function slackExtension(pi: ExtensionAPI) {
 				blocks: Type.Optional(Type.Array(Type.Unknown(), { description: "Block Kit JSON array, passed through unvalidated" })),
 				thread_ts: Type.Optional(Type.String({ description: "Reply into this existing thread instead of posting a new headline" })),
 				thread_body: Type.Optional(Type.String({ description: "Detail body for an announce headline, or the reply body when thread_ts is set" })),
+				unfurl_links: Type.Optional(
+					Type.Boolean({ description: "Slack unfurls link previews by default; pass false to suppress text-link previews for this message." }),
+				),
+				unfurl_media: Type.Optional(
+					Type.Boolean({ description: "Pass false to suppress image/video previews for this message." }),
+				),
 			}),
 			async execute(_toolCallId, params, signal) {
 				return guarded(async () => {
 					assertNoMarkdownText(params);
 					const { deps, cacheCtx } = await resolveCall(params.as, cfg, ctx, signal, repoRoot);
 					const channel = await resolveChannel(params.channel, cacheCtx);
+
+					// Only the fields core will actually send: announce uses text + thread_body (both
+					// scanned), a threaded reply collapses to thread_body ?? text (whichever param carried
+					// the body is the one core reads, so substitute into that same field - never the
+					// other), a plain post is text alone.
+					const isAnnounce = params.thread_body !== undefined && params.thread_ts === undefined;
+					const isReply = params.thread_ts !== undefined;
+					let text: string | undefined;
+					let threadBody: string | undefined;
+					let mentions: { unresolved: UnresolvedMention[]; lookupError?: string };
+					if (isAnnounce) {
+						const resolved = await resolveMentions(
+							[
+								{ field: "text", value: params.text ?? "" },
+								{ field: "thread_body", value: params.thread_body ?? "" },
+							],
+							cacheCtx,
+						);
+						mentions = resolved;
+						text = resolved.values[0];
+						threadBody = resolved.values[1];
+					} else if (isReply) {
+						const replyField: "text" | "thread_body" = params.thread_body !== undefined ? "thread_body" : "text";
+						const resolved = await resolveMentions([{ field: replyField, value: params.thread_body ?? params.text ?? "" }], cacheCtx);
+						mentions = resolved;
+						if (replyField === "thread_body") {
+							text = params.text;
+							threadBody = resolved.values[0];
+						} else {
+							text = params.text === undefined ? undefined : resolved.values[0];
+							threadBody = undefined;
+						}
+					} else {
+						const resolved = await resolveMentions([{ field: "text", value: params.text ?? "" }], cacheCtx);
+						mentions = resolved;
+						text = params.text === undefined ? undefined : resolved.values[0];
+					}
+
 					const result = await postMessage(
-						{ channel, text: params.text, blocks: params.blocks, thread_ts: params.thread_ts, thread_body: params.thread_body },
+						{
+							channel,
+							text,
+							blocks: params.blocks,
+							thread_ts: params.thread_ts,
+							thread_body: threadBody,
+							unfurl_links: params.unfurl_links,
+							unfurl_media: params.unfurl_media,
+						},
 						{ ...deps, thresholdChars: cfg.uploadThresholdChars, uploadBytes: defaultUploadBytes },
 					);
-					return {
-						content: [{ type: "text" as const, text: channelLine(result) }],
-						details: result,
-					};
+					return mentionAwareResult(result, mentions, { detailUploaded: "detailUploaded" in result && result.detailUploaded === true });
 				}, params.as);
 			},
 			renderCall: (args, theme) => oneLine(theme, "slack_post", `as:${args.as} ${args.channel}`),
@@ -294,11 +389,12 @@ export default function slackExtension(pi: ExtensionAPI) {
 					assertNoMarkdownText(params);
 					const { deps, cacheCtx } = await resolveCall(params.as, cfg, ctx, signal, repoRoot);
 					const channel = await resolveChannel(params.channel, cacheCtx);
-					const result = await updateMessage({ channel, ts: params.ts, text: params.text, blocks: params.blocks }, deps);
-					return {
-						content: [{ type: "text" as const, text: channelLine(result) }],
-						details: result,
-					};
+					const mentions = await resolveMentions([{ field: "text", value: params.text ?? "" }], cacheCtx);
+					const result = await updateMessage(
+						{ channel, ts: params.ts, text: params.text === undefined ? undefined : mentions.values[0], blocks: params.blocks },
+						deps,
+					);
+					return mentionAwareResult(result, mentions);
 				}, params.as);
 			},
 			renderCall: (args, theme) => oneLine(theme, "slack_update", `as:${args.as} ${args.channel} ts:${args.ts}`),
@@ -410,15 +506,21 @@ export default function slackExtension(pi: ExtensionAPI) {
 			label: "Slack Cache Refresh",
 			promptSnippet: "Rebuild the Slack channel/user name->ID cache",
 			description:
-				'Rebuild the Slack channel and user name->ID cache from scratch (full conversations.list + users.list scan, atomic replace). Uses the "user" identity when a user token is configured, else falls back to "bot" (no `as` param). Run this after channels/users change or when a #name/@name lookup unexpectedly fails with name_not_found. Reports the resulting channel and user counts.',
+				'Rebuild the Slack channel and user name->ID cache from scratch (full conversations.list + users.list scan, atomic replace). Uses the "user" identity when a user token is configured, else falls back to "bot" (no `as` param). Run this after channels/users change or when a #name/@name lookup unexpectedly fails with name_not_found. Reports the resulting channel, user, and email counts - a low email/user ratio hints the users:read.email scope may be missing.',
 			parameters: Type.Object({}),
 			async execute(_toolCallId, _params, signal) {
 				const identity = pickCacheRefreshIdentity(cfg, process.env, repoRoot);
 				return guarded(async () => {
 					const { cacheCtx } = await resolveCall(identity, cfg, ctx, signal, repoRoot);
 					const result = await refreshCache(cacheCtx);
+					const ratio =
+						result.users === 0
+							? ""
+							: result.emails === 0
+								? ` | emails: 0/${result.users} (users:read.email scope may be missing)`
+								: ` | emails: ${result.emails}/${result.users}`;
 					return {
-						content: [{ type: "text" as const, text: `channels: ${result.channels}, users: ${result.users}` }],
+						content: [{ type: "text" as const, text: `channels: ${result.channels}, users: ${result.users}${ratio}` }],
 						details: result,
 					};
 				}, identity);

package/lib/slack-cache.ts

@@ -7,14 +7,24 @@
 
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { dirname, isAbsolute, join } from "node:path";
-import type { ApiCall, SlackConfig } from "./slack-core.ts";
+import type { ApiCall, SlackConfig, UnresolvedMention } from "./slack-core.ts";
 import { SlackError } from "./slack-core.ts";
 
+export interface UserEntry {
+	id: string;
+	display_name: string;
+	real_name: string;
+	email?: string;
+}
+
 export interface SlackCacheFile {
 	team_id: string;
 	channels: Record<string, string>;
-	users: Record<string, { id: string; display_name: string; real_name: string }>;
+	users: Record<string, UserEntry>;
 	refreshed_at: string;
+	/** Set only by refreshCache's full replacement; presence means this file once held a complete
+	 * workspace listing, which is the only state where an alias match may be trusted from cache. */
+	snapshot_at?: string;
 }
 
 export interface CacheCtx {
@@ -99,6 +109,16 @@ function stripPrefix(input: string): string {
 	return input.startsWith("#") || input.startsWith("@") ? input.slice(1) : input;
 }
 
+function toUserEntry(u: SlackUser): UserEntry {
+	const email = u.profile?.email;
+	return {
+		id: u.id,
+		display_name: u.profile?.display_name ?? "",
+		real_name: u.profile?.real_name ?? u.real_name ?? "",
+		...(email ? { email } : {}),
+	};
+}
+
 export async function resolveChannel(input: string, ctx: CacheCtx): Promise<string> {
 	if (RAW_CHANNEL_ID.test(input)) return input;
 	if (input.startsWith("@")) {
@@ -150,7 +170,7 @@ export async function resolveChannel(input: string, ctx: CacheCtx): Promise<stri
 interface SlackUser {
 	id: string;
 	name: string;
-	profile?: { display_name?: string; real_name?: string };
+	profile?: { display_name?: string; real_name?: string; email?: string };
 	real_name?: string;
 }
 
@@ -208,11 +228,7 @@ export async function resolveUser(input: string, ctx: CacheCtx): Promise<string>
 		for (const u of members) {
 			if (u.name === name) {
 				mergeAndWrite(ctx.filePath, cached?.team_id ?? (await teamIdFor(ctx.token, ctx.apiCall, ctx.signal)), (base) => {
-					base.users[name] = {
-						id: u.id,
-						display_name: u.profile?.display_name ?? "",
-						real_name: u.profile?.real_name ?? u.real_name ?? "",
-					};
+					base.users[name] = toUserEntry(u);
 				});
 				return u.id;
 			}
@@ -231,11 +247,7 @@ export async function resolveUser(input: string, ctx: CacheCtx): Promise<string>
 	if (displayCandidates.length === 1) {
 		const u = displayCandidates[0];
 		mergeAndWrite(ctx.filePath, cached?.team_id ?? (await teamIdFor(ctx.token, ctx.apiCall, ctx.signal)), (base) => {
-			base.users[u.name] = {
-				id: u.id,
-				display_name: u.profile?.display_name ?? "",
-				real_name: u.profile?.real_name ?? u.real_name ?? "",
-			};
+			base.users[u.name] = toUserEntry(u);
 		});
 		return u.id;
 	}
@@ -249,11 +261,7 @@ export async function resolveUser(input: string, ctx: CacheCtx): Promise<string>
 	if (realCandidates.length === 1) {
 		const u = realCandidates[0];
 		mergeAndWrite(ctx.filePath, cached?.team_id ?? (await teamIdFor(ctx.token, ctx.apiCall, ctx.signal)), (base) => {
-			base.users[u.name] = {
-				id: u.id,
-				display_name: u.profile?.display_name ?? "",
-				real_name: u.profile?.real_name ?? u.real_name ?? "",
-			};
+			base.users[u.name] = toUserEntry(u);
 		});
 		return u.id;
 	}
@@ -267,16 +275,202 @@ export async function resolveUser(input: string, ctx: CacheCtx): Promise<string>
 	throw new SlackError("name_not_found", `No user named "${name}" was found in the workspace.`);
 }
 
+const MENTION_DENY = new Set(["here", "channel", "everyone"]);
+const MENTION_BOUNDARY = new Set([" ", "\t", "\n", "\r", "(", "[", "*", "_", '"', "'"]);
+// `_` is trimmed here even though it is also a boundary character: it is a legal username
+// character too, so an italic-wrapped mention like `_@alice_` is otherwise unreachable - the
+// trailing `_` must be stripped for the candidate to resolve.
+const MENTION_TRAILING = /[.,;:!?)_]+$/;
+const MENTION_SCAN = /(\\?)@([A-Za-z0-9._-]+)/g;
+
+function isBoundary(text: string, atIndex: number): boolean {
+	if (atIndex === 0) return true;
+	return MENTION_BOUNDARY.has(text[atIndex - 1]);
+}
+
+/**
+ * Substitutes `@name` -> `<@U...>` across every field a mutation will actually send.
+ * Never throws for an unresolvable name: not-found, ambiguous, and a failed live lookup all
+ * leave the text literal and report it, because a mention is prose, not an addressed parameter.
+ */
+export async function resolveMentions(
+	fields: { field: "text" | "thread_body"; value: string }[],
+	ctx: CacheCtx,
+): Promise<{
+	values: string[];
+	unresolved: UnresolvedMention[];
+	lookupError?: string;
+}> {
+	interface Candidate {
+		field: "text" | "thread_body";
+		start: number;
+		end: number;
+		escaped: boolean;
+		/** [name, endOffsetForThatName] pairs, trimmed variant first so it wins the lookup race. */
+		lookups: [string, number][];
+	}
+
+	const perField: Candidate[][] = fields.map(() => []);
+	const wanted = new Set<string>();
+
+	fields.forEach((f, fi) => {
+		for (const m of f.value.matchAll(MENTION_SCAN)) {
+			const escaped = m[1] === "\\";
+			const at = m.index + m[1].length;
+			if (escaped) {
+				if (!isBoundary(f.value, m.index)) continue;
+			} else if (!isBoundary(f.value, at)) continue;
+
+			const raw = m[2];
+			const fullEnd = m.index + m[0].length;
+			const trimmed = raw.replace(MENTION_TRAILING, "");
+			// Check the deny list against both forms: `_@channel_`/`@here.` still carry the
+			// trailing punctuation stripped below, so a raw-only check misses them.
+			if (MENTION_DENY.has(raw) || MENTION_DENY.has(trimmed)) continue;
+			// A name that is entirely trailing-punctuation (e.g. `@...`) trims to "" - not a
+			// real candidate, so skip it rather than looking up an empty username.
+			if (trimmed === "") continue;
+			const trimmedEnd = fullEnd - (raw.length - trimmed.length);
+			const lookups: [string, number][] =
+				trimmed === raw ? [[raw, fullEnd]] : [[trimmed, trimmedEnd], [raw, fullEnd]];
+			perField[fi].push({ field: f.field, start: m.index, end: fullEnd, escaped, lookups });
+			if (!escaped) for (const [name] of lookups) wanted.add(name);
+		}
+	});
+
+	const cached = readCacheFile(ctx.filePath);
+	const resolved = new Map<string, string>();
+	const aliasTrusted = cached?.snapshot_at !== undefined;
+	// Names an aliasTrusted FULL snapshot already proved ambiguous: a live users.list call
+	// cannot un-ambiguate them, so they must not fall into `outstanding`.
+	const conclusivelyAmbiguous = new Set<string>();
+
+	if (cached) {
+		for (const name of wanted) {
+			const byUsername = cached.users[name];
+			if (byUsername) {
+				resolved.set(name, byUsername.id);
+				continue;
+			}
+			if (!aliasTrusted) continue;
+			const entries = Object.values(cached.users);
+			const display = entries.filter((u) => u.display_name === name);
+			if (display.length === 1) {
+				resolved.set(name, display[0].id);
+				continue;
+			}
+			if (display.length > 1) {
+				conclusivelyAmbiguous.add(name);
+				continue;
+			}
+			const real = entries.filter((u) => u.real_name === name);
+			if (real.length === 1) resolved.set(name, real[0].id);
+			else if (real.length > 1) conclusivelyAmbiguous.add(name);
+		}
+	}
+
+	const outstanding = [...wanted].filter((n) => !resolved.has(n) && !conclusivelyAmbiguous.has(n));
+	let lookupError: string | undefined;
+
+	if (outstanding.length > 0) {
+		try {
+			const found = new Map<string, SlackUser>();
+			const aliasHits = new Map<string, SlackUser[]>();
+			let cursor = "";
+			for (let page = 1; ; page++) {
+				if (page > MAX_LIST_PAGES) {
+					throw new SlackError(
+						"pagination_overflow",
+						`resolveMentions: users.list did not terminate within ${MAX_LIST_PAGES} pages.`,
+					);
+				}
+				const data = await ctx.apiCall(
+					"users.list",
+					ctx.token,
+					{ limit: 1000, ...(cursor ? { cursor } : {}) },
+					{ retry: false, signal: ctx.signal },
+				);
+				for (const u of (data.members as SlackUser[]) ?? []) {
+					for (const name of outstanding) {
+						if (u.name === name) found.set(name, u);
+						else if (u.profile?.display_name === name || (u.profile?.real_name ?? u.real_name) === name) {
+							aliasHits.set(name, [...(aliasHits.get(name) ?? []), u]);
+						}
+					}
+				}
+				const meta = data.response_metadata as { next_cursor?: string } | undefined;
+				const nextCursor = meta?.next_cursor ?? "";
+				if (nextCursor !== "" && nextCursor === cursor) break;
+				cursor = nextCursor;
+				if (!cursor) break;
+			}
+
+			const writes: SlackUser[] = [];
+			for (const name of outstanding) {
+				const exact = found.get(name);
+				const aliases = aliasHits.get(name) ?? [];
+				const pick = exact ?? (aliases.length === 1 ? aliases[0] : undefined);
+				if (!pick) continue;
+				resolved.set(name, pick.id);
+				writes.push(pick);
+			}
+			if (writes.length > 0) {
+				const teamId = cached?.team_id ?? (await teamIdFor(ctx.token, ctx.apiCall, ctx.signal));
+				mergeAndWrite(ctx.filePath, teamId, (base) => {
+					for (const u of writes) base.users[u.name] = toUserEntry(u);
+				});
+			}
+		} catch (err) {
+			lookupError = err instanceof Error ? err.message : String(err);
+		}
+	}
+
+	const unresolved: UnresolvedMention[] = [];
+	const seenUnresolved = new Set<string>();
+	const values = fields.map((f, fi) => {
+		let out = "";
+		let cursor = 0;
+		for (const c of perField[fi]) {
+			out += f.value.slice(cursor, c.start);
+			const literal = f.value.slice(c.start, c.end);
+			if (c.escaped) {
+				out += literal.slice(1);
+				cursor = c.end;
+			} else {
+				const hit = c.lookups.find(([n]) => resolved.has(n));
+				if (hit !== undefined) {
+					out += `<@${resolved.get(hit[0])}>`;
+					cursor = hit[1];
+				} else {
+					out += literal;
+					const name = `@${c.lookups[0][0]}`;
+					// Documented contract (doc/slack.md): unresolvedMentions is deduplicated by
+					// (field, name), so "cc @bob @bob" reports @bob once, not once per occurrence.
+					const key = `${c.field}\u0000${name}`;
+					if (!seenUnresolved.has(key)) {
+						seenUnresolved.add(key);
+						unresolved.push({ field: c.field, name });
+					}
+					cursor = c.end;
+				}
+			}
+		}
+		return out + f.value.slice(cursor);
+	});
+
+	return { values, unresolved, ...(lookupError !== undefined ? { lookupError } : {}) };
+}
+
 /**
  * Full snapshot replace, deliberately asymmetric with mergeAndWrite: refresh's job is to
  * atomically overwrite the whole file, so a concurrent mergeAndWrite write racing this one may
  * be clobbered (last-writer-wins). Accepted per spec (doc/specs/2026-08-29-gh-7-slack-extension.md
  * Cache section) - a clobbered merge self-heals on the next cache miss.
  */
-export async function refreshCache(ctx: CacheCtx): Promise<{ channels: number; users: number }> {
+export async function refreshCache(ctx: CacheCtx): Promise<{ channels: number; users: number; emails: number }> {
 	const teamId = await teamIdFor(ctx.token, ctx.apiCall, ctx.signal);
 	const channels: Record<string, string> = {};
-	const users: Record<string, { id: string; display_name: string; real_name: string }> = {};
+	const users: Record<string, UserEntry> = {};
 
 	let cursor = "";
 	for (let page = 1; ; page++) {
@@ -319,7 +513,7 @@ export async function refreshCache(ctx: CacheCtx): Promise<{ channels: number; u
 		const data = await ctx.apiCall("users.list", ctx.token, { limit: 1000, ...(cursor ? { cursor } : {}) }, { retry: false, signal: ctx.signal });
 		const members = (data.members as SlackUser[]) ?? [];
 		for (const u of members) {
-			users[u.name] = { id: u.id, display_name: u.profile?.display_name ?? "", real_name: u.profile?.real_name ?? u.real_name ?? "" };
+			users[u.name] = toUserEntry(u);
 		}
 		const meta = data.response_metadata as { next_cursor?: string } | undefined;
 		const nextCursor = meta?.next_cursor ?? "";
@@ -333,6 +527,11 @@ export async function refreshCache(ctx: CacheCtx): Promise<{ channels: number; u
 		if (!cursor) break;
 	}
 
-	atomicWrite(ctx.filePath, { team_id: teamId, channels, users, refreshed_at: new Date().toISOString() });
-	return { channels: Object.keys(channels).length, users: Object.keys(users).length };
+	const snapshotAt = new Date().toISOString();
+	atomicWrite(ctx.filePath, { team_id: teamId, channels, users, refreshed_at: snapshotAt, snapshot_at: snapshotAt });
+	return {
+		channels: Object.keys(channels).length,
+		users: Object.keys(users).length,
+		emails: Object.values(users).filter((u) => u.email !== undefined).length,
+	};
 }

package/lib/slack-core.ts

@@ -19,6 +19,7 @@ import { resolveConfig } from "./extension-config.ts";
 export interface SlackConfig {
 	enabled: boolean;
 	cachePath: string | undefined;
+	policyPath: string | undefined;
 	userTokenEnv: string;
 	botTokenEnv: string;
 	uploadThresholdChars: number;
@@ -27,6 +28,7 @@ export interface SlackConfig {
 export const DEFAULT_SLACK_CONFIG: SlackConfig = {
 	enabled: false,
 	cachePath: undefined,
+	policyPath: undefined,
 	userTokenEnv: "SLACK_USER_TOKEN",
 	botTokenEnv: "SLACK_BOT_TOKEN",
 	uploadThresholdChars: 4000,
@@ -49,6 +51,7 @@ export function coerce(raw: unknown): Partial<SlackConfig> | undefined {
 	const patch: Partial<SlackConfig> = {};
 	if (typeof o.enabled === "boolean") patch.enabled = o.enabled;
 	if (typeof o.cachePath === "string") patch.cachePath = o.cachePath;
+	if (typeof o.policyPath === "string") patch.policyPath = o.policyPath;
 	if (typeof o.userTokenEnv === "string") patch.userTokenEnv = o.userTokenEnv;
 	if (typeof o.botTokenEnv === "string") patch.botTokenEnv = o.botTokenEnv;
 	if (typeof o.uploadThresholdChars === "number" && Number.isInteger(o.uploadThresholdChars) && o.uploadThresholdChars > 0) {
@@ -635,7 +638,14 @@ async function withPermalink(deps: CoreDeps, channel: string, ts: string): Promi
 }
 
 export async function postPlain(
-	args: { channel: string; text?: string; blocks?: unknown[]; thread_ts?: string },
+	args: {
+		channel: string;
+		text?: string;
+		blocks?: unknown[];
+		thread_ts?: string;
+		unfurl_links?: boolean;
+		unfurl_media?: boolean;
+	},
 	deps: CoreDeps,
 ): Promise<MutationResult> {
 	assertTextWithinLimit(args.text);
@@ -644,6 +654,8 @@ export async function postPlain(
 	if (args.text !== undefined) params.text = args.text;
 	if (args.blocks !== undefined) params.blocks = args.blocks;
 	if (args.thread_ts !== undefined) params.thread_ts = args.thread_ts;
+	if (args.unfurl_links !== undefined) params.unfurl_links = args.unfurl_links;
+	if (args.unfurl_media !== undefined) params.unfurl_media = args.unfurl_media;
 
 	const data = await deps.apiCall("chat.postMessage", deps.token, params, { retry: true, signal: deps.signal });
 	const channel = typeof data.channel === "string" ? data.channel : args.channel;
@@ -740,6 +752,49 @@ export function linkCollapsedLength(text: string): number {
 	return text.replace(/<([^|>]+)\|([^>]+)>/g, "$2").replace(/<[^>]+>/g, "x").length;
 }
 
+function escapeAttr(value: string): string {
+	return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+
+/** Pure: the handler in extensions/slack.ts owns readFileSync and maps the outcome to this input. */
+export function buildPolicyBlock(input: {
+	source: string;
+	status: "ok" | "unreadable" | "empty";
+	body?: string;
+	code?: string;
+}): string {
+	const source = escapeAttr(input.source);
+	if (input.status === "ok") {
+		return `<slack-policy source="${source}">\n${input.body ?? ""}</slack-policy>`;
+	}
+	const reason =
+		input.status === "empty"
+			? `Configured Slack policy file is empty.`
+			: `Configured Slack policy file could not be read (${input.code ?? "unknown error"}).`;
+	return `<slack-policy source="${source}" status="${input.status}">\n${reason} Slack tools are available but the repository's posting policy is unknown - ask the operator before posting.\n</slack-policy>`;
+}
+
+export interface UnresolvedMention {
+	field: "text" | "thread_body";
+	name: string;
+}
+
+/** Pure: the `channelLine` suffix segment for unresolved mentions. Empty string means "append nothing". */
+export function formatUnresolvedSuffix(
+	unresolved: UnresolvedMention[],
+	opts: { lookupError?: string; detailUploaded?: boolean },
+): string {
+	if (unresolved.length === 0) return "";
+	const names: string[] = [];
+	for (const u of unresolved) if (!names.includes(u.name)) names.push(u.name);
+	let suffix = `unresolved mentions: ${names.join(", ")}`;
+	if (opts.lookupError !== undefined) suffix += ` (lookup failed: ${opts.lookupError})`;
+	if (opts.detailUploaded && unresolved.some((u) => u.field === "thread_body")) {
+		suffix += ` (detail uploaded as a file - slack_update cannot repair it; repost to fix)`;
+	}
+	return suffix;
+}
+
 export function persistDetail(body: string): string {
 	const dir = join(tmpdir(), "pi-slack");
 	mkdirSync(dir, { recursive: true });
@@ -763,6 +818,11 @@ function assertHeadline(text: string): void {
 
 export interface AnnounceResult extends MutationResult {
 	detailTs?: string;
+	// Set only when the detail leg took the file-upload path (deliverDetailUpload) rather than the
+	// inline threaded chat.postMessage reply - detailTs alone can't distinguish the two, since both
+	// paths set it. slack_update can edit the headline or the "Detail attached." stub, never an
+	// uploaded file's contents, so callers need this to know a mention-repair edit won't reach it.
+	detailUploaded?: true;
 }
 
 async function deliverDetailUpload(
@@ -874,14 +934,23 @@ async function recoverFromDetailFailure(
 
 export async function announce(
 	args: { channel: string; text: string; thread_body: string },
-	deps: CoreDeps & { uploadBytes: UploadBytes; thresholdChars: number; persist?: (body: string) => string },
+	deps: CoreDeps & {
+		uploadBytes: UploadBytes;
+		thresholdChars: number;
+		persist?: (body: string) => string;
+		unfurl_links?: boolean;
+		unfurl_media?: boolean;
+	},
 ): Promise<AnnounceResult> {
 	assertHeadline(args.text);
 	const persist = deps.persist ?? persistDetail;
+	const unfurl: Record<string, unknown> = {};
+	if (deps.unfurl_links !== undefined) unfurl.unfurl_links = deps.unfurl_links;
+	if (deps.unfurl_media !== undefined) unfurl.unfurl_media = deps.unfurl_media;
 
 	let headlineData: Record<string, unknown>;
 	try {
-		headlineData = await deps.apiCall("chat.postMessage", deps.token, { channel: args.channel, text: args.text }, { retry: false, signal: deps.signal });
+		headlineData = await deps.apiCall("chat.postMessage", deps.token, { channel: args.channel, text: args.text, ...unfurl }, { retry: false, signal: deps.signal });
 	} catch (err) {
 		if (err instanceof SlackError && err.code === "transport") {
 			const { detailPath, note } = persistOrDescribe(args.thread_body, persist);
@@ -923,7 +992,7 @@ export async function announce(
 			const causeMessage = err instanceof Error ? err.message : String(err);
 			return recoverFromDetailFailure(causeMessage, args.text, args.thread_body, channel, ts, permalink, deps, persist);
 		}
-		return { channel, ts, permalink, warning, detailTs };
+		return { channel, ts, permalink, warning, detailTs, detailUploaded: true };
 	}
 
 	let detailData: Record<string, unknown>;
@@ -931,14 +1000,14 @@ export async function announce(
 		detailData = await deps.apiCall(
 			"chat.postMessage",
 			deps.token,
-			{ channel, text: args.thread_body, thread_ts: ts },
+			{ channel, text: args.thread_body, thread_ts: ts, ...unfurl },
 			{ retry: true, signal: deps.signal },
 		);
 	} catch (err) {
 		if (err instanceof SlackError && err.code === "msg_too_long") {
 			try {
 				const { detailTs } = await deliverDetailUpload(channel, ts, args.thread_body, deps);
-				return { channel, ts, permalink, warning, detailTs };
+				return { channel, ts, permalink, warning, detailTs, detailUploaded: true };
 			} catch (uploadErr) {
 				const causeMessage = uploadErr instanceof Error ? uploadErr.message : String(uploadErr);
 				return recoverFromDetailFailure(causeMessage, args.text, args.thread_body, channel, ts, permalink, deps, persist);
@@ -953,11 +1022,22 @@ export async function announce(
 }
 
 export async function postMessage(
-	args: { channel: string; text?: string; blocks?: unknown[]; thread_ts?: string; thread_body?: string },
+	args: {
+		channel: string;
+		text?: string;
+		blocks?: unknown[];
+		thread_ts?: string;
+		thread_body?: string;
+		unfurl_links?: boolean;
+		unfurl_media?: boolean;
+	},
 	deps: CoreDeps & { uploadBytes: UploadBytes; thresholdChars: number; persist?: (body: string) => string },
 ): Promise<MutationResult | AnnounceResult> {
 	if (args.thread_body !== undefined && args.thread_ts === undefined) {
-		return announce({ channel: args.channel, text: args.text ?? "", thread_body: args.thread_body }, deps);
+		return announce(
+			{ channel: args.channel, text: args.text ?? "", thread_body: args.thread_body },
+			{ ...deps, unfurl_links: args.unfurl_links, unfurl_media: args.unfurl_media },
+		);
 	}
 
 	if (args.thread_ts !== undefined) {
@@ -965,7 +1045,14 @@ export async function postMessage(
 		// the threshold/upload path only applies when composing plain mrkdwn from thread_body/text.
 		if (args.blocks !== undefined) {
 			return postPlain(
-				{ channel: args.channel, text: args.thread_body ?? args.text, blocks: args.blocks, thread_ts: args.thread_ts },
+				{
+					channel: args.channel,
+					text: args.thread_body ?? args.text,
+					blocks: args.blocks,
+					thread_ts: args.thread_ts,
+					unfurl_links: args.unfurl_links,
+					unfurl_media: args.unfurl_media,
+				},
 				deps,
 			);
 		}
@@ -980,7 +1067,10 @@ export async function postMessage(
 		// (server-side). This body is extension-composed detail, same as announce's detail leg, so
 		// it gets the same upload fallback instead of a bare throw.
 		try {
-			return await postPlain({ channel: args.channel, text: body, thread_ts: args.thread_ts }, deps);
+			return await postPlain(
+				{ channel: args.channel, text: body, thread_ts: args.thread_ts, unfurl_links: args.unfurl_links, unfurl_media: args.unfurl_media },
+				deps,
+			);
 		} catch (err) {
 			if (err instanceof SlackError && (err.code === "text_too_long" || err.code === "msg_too_long")) {
 				const { detailTs } = await deliverDetailUploadOrPersist(args.channel, args.thread_ts, body, deps);
@@ -990,5 +1080,8 @@ export async function postMessage(
 		}
 	}
 
-	return postPlain({ channel: args.channel, text: args.text, blocks: args.blocks }, deps);
+	return postPlain(
+		{ channel: args.channel, text: args.text, blocks: args.blocks, unfurl_links: args.unfurl_links, unfurl_media: args.unfurl_media },
+		deps,
+	);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-quiver",
-  "version": "5.0.0",
+  "version": "5.1.0",
   "description": "Personal pack of Pi coding-agent extensions: context-safe fetch, doc_to_md PDF/DOCX/PPTX-to-Markdown conversion, session naming, a themed ASCII startup header, Opus 4.8 fast mode, and a provider-stall watchdog.",
   "author": "Jacek Juraszek",
   "license": "MIT",