dsh-session-recall 0.3.0 → 0.4.0

package/README.md

@@ -4,7 +4,32 @@ English | [中文](README.zh.md)
 
 [![npm version](https://img.shields.io/npm/v/dsh-session-recall)](https://www.npmjs.com/package/dsh-session-recall) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-Cross-session full-text recall for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness): the model-facing `recall` tool lets the agent **search its own past session transcripts** — "that bug we fixed last week", "the font we chose for my resume" — through the trusted `ctx.sessionQuery` seam.
+Deterministic cross-session full-text retrieval for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness): the model-facing `recall` tool lets the agent **search its own past session transcripts** — "that bug we fixed last week", "the font we chose for my resume" — through the trusted `ctx.sessionQuery` seam.
+
+## Positioning
+
+`dsh-session-recall` is a **transcript retrieval layer** focused on correctness and control.
+
+- It returns evidence from original session logs, not synthesized summaries.
+- It enforces explicit retrieval scope (cwd by default, opt-in widening).
+- It favors deterministic behavior over "smart" but lossy memory extraction.
+
+If you need agent memory orchestration, use a memory framework; if you need bounded, auditable lookup over historical transcripts, use this plugin.
+
+## Competitive context
+
+| Capability focus | Memory frameworks | Generic transcript search | `dsh-session-recall` |
+|---|---|---|---|
+| Retrieval target | Derived memory objects | Varies by implementation | **Original session transcript events** |
+| Scope control | Framework-specific | Often coarse | **cwd-scoped default + explicit `all_projects` gate** |
+| CJK behavior | Framework-specific | Often tokenizer-limited | **FTS + CJK zero-hit substring fallback** |
+| Output contract | Usually framework-native | Varies | **Typed `recall` result with stable fields/hints** |
+
+## Roadmap
+
+- **P1: ranking controls** — configurable recency decay and session pinning on top of FTS relevance.
+- **P1: query diagnostics** — expose match reason (fts/cjk-fallback/filters) and scan budget in result metadata.
+- **P2: evidence handoff** — one-click bridge to session export for matched sessions.
 
 ## Why
 
@@ -86,6 +111,19 @@ Plugin row config (all optional):
 
 Every failure returns a friendly `hint` instead of a raw exception: a disabled index explains the two config keys needed, a stale cursor tells the model to restart without one, an unknown `session_id` suggests discovering sessions first. Title enrichment is best-effort — a failed title batch degrades to untitled rows, never a failed search.
 
+## Scope policy & redaction (v0.4)
+
+Deployment-level controls for what the model may read back:
+
+| Option | Values | Default | Effect |
+|---|---|---|---|
+| `redactionMode` | `off` / `mask` / `hash` | `off` | Redact secret-looking text (bearer headers, prefixed API keys, private-key blocks, emails) in snippets and titles. `hash` keeps secrets comparable (`#xxxxxxxx`, same secret → same marker) without being readable. Results carry a `redacted` count. |
+| `cwdAllowlist` | list of paths | (none) | Only sessions started in these directories are searchable; the calling cwd itself must be listed. |
+| `cwdDenylist` | list of paths | (none) | These directories are never searchable. Deny wins over allow. |
+| `allProjectsPolicy` | `allow` / `deny` / `confirm` | `allow` | `deny` ignores `all_projects` with a model-facing hint; `confirm` asks the user through the official `@deepseek-ai/dsh-user-approval` seam — fail-closed when no answerer is composed. |
+
+All three gates apply uniformly to cross-session hits, the CJK fallback scan, and `session_id` reads — no bypass route.
+
 ## Known limitations
 
 - First search after startup walks the durable logs to build the index (the tool description warns the model); subsequent searches are incremental.

package/README.zh.md

@@ -4,7 +4,32 @@
 
 [![npm version](https://img.shields.io/npm/v/dsh-session-recall)](https://www.npmjs.com/package/dsh-session-recall) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-DeepSeek Harness 的跨会话全文回忆插件：注册模型可调用的 `recall` 工具，让 agent 能**检索自己过往的会话原文**——"上周修的那个 bug"、"简历选的什么字体"——全部通过可信的 `ctx.sessionQuery` 缝完成。
+DeepSeek Harness 的**确定性跨会话全文检索**插件：注册模型可调用的 `recall` 工具，让 agent 能**检索自己过往的会话原文**——"上周修的那个 bug"、"简历选的什么字体"——全部通过可信的 `ctx.sessionQuery` 缝完成。
+
+## 项目定位
+
+`dsh-session-recall` 是一个强调正确性与边界控制的**会话检索层**。
+
+- 检索对象是原始会话日志，不是二次总结内容。
+- 默认按 cwd 收敛权限范围，放宽范围必须显式声明。
+- 追求可解释、可复现的检索行为，而不是"看起来更聪明"但有损的记忆抽取。
+
+如果你要做长期记忆编排，请用记忆框架；如果你要做可审计、有权限边界的历史检索，请用本插件。
+
+## 竞品视角
+
+| 能力重心 | 记忆框架类插件 | 通用检索类插件 | `dsh-session-recall` |
+|---|---|---|---|
+| 检索对象 | 推导后的记忆结构 | 视实现而定 | **原始会话事件文本** |
+| 范围控制 | 框架内约束 | 常较粗粒度 | **默认 cwd + 显式 `all_projects` 闸门** |
+| CJK 体验 | 视实现而定 | 常受分词限制 | **FTS + CJK 零命中子串回退** |
+| 输出契约 | 框架内部格式 | 不统一 | **类型化 `recall` 结果 + 稳定 hint** |
+
+## 路线图
+
+- **P1：排序策略可配** —— 在 FTS 相关度之上增加时间衰减、会话 pin 权重。
+- **P1：查询诊断元数据** —— 返回命中来源（fts/cjk-fallback/filters）与扫描预算。
+- **P2：证据联动导出** —— 命中后可一键触发对应会话导出。
 
 ## 为什么做这个
 
@@ -86,6 +111,19 @@ dsh plugin --profile web add github:kittimzhe/dsh-session-recall
 
 所有失败都返回友好的 `hint` 而不是裸异常：索引未开启会说明需要哪两个配置键；游标失效会告诉模型不带游标重开一次；`session_id` 不存在会建议先做跨会话搜索。标题补全是尽力而为——标题批量读取失败只降级为"无标题"行，绝不让搜索失败。
 
+## 范围策略与脱敏（v0.4）
+
+部署级权限控制——模型能读回什么，由配置说了算：
+
+| 配置 | 取值 | 默认 | 效果 |
+|---|---|---|---|
+| `redactionMode` | `off` / `mask` / `hash` | `off` | 对标题与摘录中疑似密钥的文本（Bearer 头、前缀式 API key、私钥块、邮箱）脱敏。`hash` 用确定性摘要 `#xxxxxxxx`（同一密钥同一标记）保持可比性。结果带 `redacted` 计数。 |
+| `cwdAllowlist` | 路径列表 | （无） | 只检索这些目录下启动的会话；当前项目目录本身也必须在列表内。 |
+| `cwdDenylist` | 路径列表 | （无） | 这些目录永不检索。deny 优先于 allow。 |
+| `allProjectsPolicy` | `allow` / `deny` / `confirm` | `allow` | `deny` 忽略 `all_projects` 并向模型说明；`confirm` 走官方 `@deepseek-ai/dsh-user-approval` 接缝向用户请求批准——无应答者时 fail-closed。 |
+
+三道闸门统一作用于跨会话命中、CJK 回退扫描和 `session_id` 直读——没有绕行路径。
+
 ## 已知限制
 
 - 启动后第一次搜索会扫全量日志建索引（工具描述里已警告模型）；之后增量更新。

package/lib/index.d.ts

@@ -1,10 +1,26 @@
-import { ToolDefinition } from "@deepseek-ai/dsh-tools";
+import { ToolDefinition, ToolRunContext } from "@deepseek-ai/dsh-tools";
 import { SessionEventResultFilter, SessionEventSearchDocument, SessionEventSearchPage, SessionEventSearchRequest, SessionRecord, SessionSearchExecContext, SessionSearchHit, SessionSearchPage, SessionSearchRequest, SessionTitleObservationResult } from "@deepseek-ai/dsh-session-query";
 import { JsonValue, SessionId } from "@deepseek-ai/dsh-session";
 import { Context } from "@deepseek-ai/cordis";
 import { ContentBlock } from "@deepseek-ai/dsh-llm";
+//#region src/redact.d.ts
+type RedactionMode = 'off' | 'mask' | 'hash';
+declare const REDACTION_MODES: readonly RedactionMode[];
+/**
+ * Redact one piece of text. Returns the new text plus how many replacements
+ * happened (0 when mode is `off`).
+ */
+declare function redactText(text: string, mode: RedactionMode): {
+  text: string;
+  count: number;
+};
+/** Normalize an untrusted config value into a valid mode (default `off`). */
+declare function normalizeRedactionMode(value: unknown): RedactionMode;
+//#endregion
 //#region src/config.d.ts
-/** Plugin-row configuration for dsh-session-recall. */
+/** What happens when the model passes `all_projects=true`. */
+type AllProjectsPolicy = 'allow' | 'deny' | 'confirm';
+declare const ALL_PROJECTS_POLICIES: readonly AllProjectsPolicy[];
 interface RecallConfig {
   /** Honor the tool's `all_projects` argument. Default `true`. */
   allowAllProjects?: boolean;
@@ -18,6 +34,18 @@ interface RecallConfig {
   cjkFallback?: boolean;
   /** Max sessions to scan on a cross-session CJK fallback. Default `50`. */
   cjkFallbackScanMax?: number;
+  /** Redact secret-looking text in snippets and titles. Default `'off'`. */
+  redactionMode?: RedactionMode;
+  /** When non-empty, only sessions started in these project directories are searchable. Default: no restriction. */
+  cwdAllowlist?: readonly string[];
+  /** Sessions started in these project directories are never searchable. Default: none. */
+  cwdDenylist?: readonly string[];
+  /**
+   * `all_projects` gate: `'allow'` (default, previous behavior), `'deny'`
+   * (ignored, with a model-facing hint), or `'confirm'` (the user must
+   * approve through the `@deepseek-ai/dsh-user-approval` seam; fail-closed).
+   */
+  allProjectsPolicy?: AllProjectsPolicy;
 }
 /** Validated, fully defaulted configuration. */
 interface NormalizedRecallConfig {
@@ -27,9 +55,15 @@ interface NormalizedRecallConfig {
   readonly cjkHint: boolean;
   readonly cjkFallback: boolean;
   readonly cjkFallbackScanMax: number;
+  readonly redactionMode: RedactionMode;
+  readonly cwdAllowlist: readonly string[];
+  readonly cwdDenylist: readonly string[];
+  readonly allProjectsPolicy: AllProjectsPolicy;
 }
 /** Default, clamp, and cross-check every optional field. */
 declare function normalizeRecallConfig(config?: RecallConfig): NormalizedRecallConfig;
+/** Whether a session cwd is searchable under the allowlist/denylist policy. */
+declare function cwdAllowed(cwd: string | null | undefined, cfg: NormalizedRecallConfig): boolean;
 //#endregion
 //#region src/types.d.ts
 /** Canonical value types for the `recall` tool's declared output. */
@@ -66,6 +100,8 @@ interface RecallResult {
   items: RecallItem[];
   nextCursor: string | null;
   hint: string | null;
+  /** How many secret-looking fields were redacted in this result (0 when redaction is off). */
+  redacted: number;
 }
 /** The typed model-facing arguments after schema validation. */
 interface RecallArgs {
@@ -86,11 +122,20 @@ interface RecallQueryEngine {
   filterEvents(sessionId: SessionId, filters: readonly SessionEventResultFilter[]): Promise<SessionEventSearchDocument[]>;
 }
 declare const RECALL_TOOL_DESCRIPTION: string;
+/** The approval verdict vocabulary mirrored from `@deepseek-ai/dsh-user-approval`. */
+type RecallApprovalVerdict = 'allowed-once' | 'rejected' | 'cancelled' | 'unavailable';
+/**
+ * Optional user-approval seam for the `all_projects` gate (`allProjectsPolicy:
+ * 'confirm'`). Receives the tool run context (for the agent) and a
+ * human-readable reason; `'allowed-once'` is the only grant. Wired from
+ * `ctx.approval` in the plugin entry; fail-closed when absent.
+ */
+type RecallApprover = (exec: ToolRunContext, reason: string) => Promise<RecallApprovalVerdict>;
 /**
  * Build the `recall` ToolDefinition around a concrete sessionQuery engine.
  * Pure construction — no registration happens here.
  */
-declare function createRecallTool(config?: RecallConfig, engine?: RecallQueryEngine): ToolDefinition;
+declare function createRecallTool(config?: RecallConfig, engine?: RecallQueryEngine, approver?: RecallApprover): ToolDefinition;
 //#endregion
 //#region src/render.d.ts
 /**
@@ -140,4 +185,4 @@ declare const inject: string[];
 /** Plugin entry: mount the `recall` tool on the global tool registry. */
 declare function apply(ctx: Context, config?: RecallConfig): void;
 //#endregion
-export { type NormalizedRecallConfig, RECALL_TOOL_DESCRIPTION, type RecallArgs, type RecallBestMatch, type RecallConfig, type RecallItem, type RecallQueryEngine, type RecallResult, type RecallScope, apply, cjkFallbackHint, cjkZeroHitHint, clamp, createRecallTool, firstLineClipped, formatDate, hasCJK, id8, inject, name, normalizeQuery, normalizeRecallConfig, recallContentBlocks, recallPresentationMeta, renderRecallText, snippetAround };
+export { ALL_PROJECTS_POLICIES, type AllProjectsPolicy, type NormalizedRecallConfig, RECALL_TOOL_DESCRIPTION, REDACTION_MODES, type RecallApprovalVerdict, type RecallApprover, type RecallArgs, type RecallBestMatch, type RecallConfig, type RecallItem, type RecallQueryEngine, type RecallResult, type RecallScope, type RedactionMode, apply, cjkFallbackHint, cjkZeroHitHint, clamp, createRecallTool, cwdAllowed, firstLineClipped, formatDate, hasCJK, id8, inject, name, normalizeQuery, normalizeRecallConfig, normalizeRedactionMode, recallContentBlocks, recallPresentationMeta, redactText, renderRecallText, snippetAround };

package/lib/index.js

@@ -1,10 +1,87 @@
 import { defineTool } from "@deepseek-ai/dsh-tools";
 import { SessionSearchCursor } from "@deepseek-ai/dsh-session-query";
 import { SessionId } from "@deepseek-ai/dsh-session";
+import { createHash } from "node:crypto";
+//#region src/redact.ts
+/**
+* Redaction for recall output text (snippets and titles).
+*
+* Three modes: `off` (default, unchanged), `mask` (placeholder), `hash`
+* (deterministic 8-hex digest — the same secret always hashes to the same
+* marker, so equal markers prove equality without revealing content).
+*
+* Pattern set covers the credential shapes that actually show up in agent
+* transcripts: bearer headers, prefixed API keys, private-key blocks, and
+* email addresses. It is best-effort, not a secrecy guarantee.
+*/
+const REDACTION_MODES = [
+	"off",
+	"mask",
+	"hash"
+];
+const RULES = [
+	{
+		pattern: /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g,
+		mask: "[PRIVATE KEY REDACTED]"
+	},
+	{
+		pattern: /Bearer\s+[A-Za-z0-9\-._~+/]+=*/g,
+		mask: "Bearer [REDACTED]"
+	},
+	{
+		pattern: /\b(?:sk-[A-Za-z0-9]{20,}|ghp_[A-Za-z0-9]{30,}|gho_[A-Za-z0-9]{30,}|github_pat_[A-Za-z0-9_]{30,}|xox[baprs]-[A-Za-z0-9-]{10,}|AKIA[A-Z0-9]{16})\b/g,
+		mask: "[REDACTED]"
+	},
+	{
+		pattern: /[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g,
+		mask: "[EMAIL]"
+	}
+];
+function hashMarker(match) {
+	return `#${createHash("sha256").update(match).digest("hex").slice(0, 8)}`;
+}
+/**
+* Redact one piece of text. Returns the new text plus how many replacements
+* happened (0 when mode is `off`).
+*/
+function redactText(text, mode) {
+	if (mode === "off" || text.length === 0) return {
+		text,
+		count: 0
+	};
+	let count = 0;
+	let out = text;
+	for (const rule of RULES) out = out.replace(rule.pattern, (match) => {
+		count += 1;
+		return mode === "mask" ? rule.mask : hashMarker(match);
+	});
+	return {
+		text: out,
+		count
+	};
+}
+/** Normalize an untrusted config value into a valid mode (default `off`). */
+function normalizeRedactionMode(value) {
+	return typeof value === "string" && REDACTION_MODES.includes(value) ? value : "off";
+}
+//#endregion
+//#region src/config.ts
+/** Plugin-row configuration for dsh-session-recall. */
+const ALL_PROJECTS_POLICIES = [
+	"allow",
+	"deny",
+	"confirm"
+];
 function intIn(value, fallback, lo, hi) {
 	if (typeof value !== "number" || !Number.isFinite(value)) return fallback;
 	return Math.min(hi, Math.max(lo, Math.trunc(value)));
 }
+function stringList(value) {
+	return Array.isArray(value) ? value.filter((entry) => typeof entry === "string" && entry.length > 0) : [];
+}
+function normalizePolicy(value) {
+	return typeof value === "string" && ALL_PROJECTS_POLICIES.includes(value) ? value : "allow";
+}
 /** Default, clamp, and cross-check every optional field. */
 function normalizeRecallConfig(config) {
 	const defaultLimit = intIn(config?.defaultLimit, 5, 1, 10);
@@ -14,9 +91,20 @@ function normalizeRecallConfig(config) {
 		maxLimit: Math.max(defaultLimit, intIn(config?.maxLimit, 10, 1, 25)),
 		cjkHint: config?.cjkHint !== false,
 		cjkFallback: config?.cjkFallback !== false,
-		cjkFallbackScanMax: intIn(config?.cjkFallbackScanMax, 50, 1, 500)
+		cjkFallbackScanMax: intIn(config?.cjkFallbackScanMax, 50, 1, 500),
+		redactionMode: normalizeRedactionMode(config?.redactionMode),
+		cwdAllowlist: stringList(config?.cwdAllowlist),
+		cwdDenylist: stringList(config?.cwdDenylist),
+		allProjectsPolicy: normalizePolicy(config?.allProjectsPolicy)
 	};
 }
+/** Whether a session cwd is searchable under the allowlist/denylist policy. */
+function cwdAllowed(cwd, cfg) {
+	if (cwd == null || cwd === "") return cfg.cwdAllowlist.length === 0;
+	if (cfg.cwdDenylist.includes(cwd)) return false;
+	if (cfg.cwdAllowlist.length > 0 && !cfg.cwdAllowlist.includes(cwd)) return false;
+	return true;
+}
 //#endregion
 //#region src/util.ts
 /** Small pure helpers shared by the recall tool and its renderers. */
@@ -161,7 +249,8 @@ const RECALL_TOOL_DESCRIPTION = [
 	"Use it when the user refers to earlier work (\"that bug we fixed last week\", \"the font we chose for my resume\") or when prior context was compacted away.",
 	"Matches whole words/phrases for English and code identifiers; a zero-hit Chinese (CJK) query automatically falls back to a substring scan in which every whitespace-separated term must match. Returns the best-matching event snippet per session plus the session id.",
 	"Then use the read tool on files, or ask the user, to go deeper — this tool only points at history, it does not resume sessions.",
-	"Scoping: by default only sessions started in the current project directory; pass all_projects=true to search everywhere.",
+	"Scoping: by default only sessions started in the current project directory; pass all_projects=true to search everywhere (the deployment may ignore it or require user approval).",
+	"When the deployment enables redaction, secret-looking text in snippets appears as [REDACTED] or a #hash marker — treat it as removed; do not try to reconstruct or echo it.",
 	"The first search after startup may be slow while the index builds."
 ].join(" ");
 function errCode(error) {
@@ -192,7 +281,8 @@ function recallError(query, error) {
 		hasMore: false,
 		items: [],
 		nextCursor: null,
-		hint: friendlyError(error)
+		hint: friendlyError(error),
+		redacted: 0
 	};
 }
 function brand(value) {
@@ -270,9 +360,9 @@ function cjkTextFilters(query) {
 * providers, so scanning each scoped session with it recovers the exact
 * substring matches the full-text index cannot see.
 */
-async function cjkScanSessions(engine, query, agentCwd, wantAll, scanMax, limit, signal) {
+async function cjkScanSessions(engine, query, agentCwd, wantAll, cfg, scanMax, limit, signal) {
 	const all = await engine.listSessions(signal);
-	const candidates = !wantAll && agentCwd != null ? all.filter((record) => record.header.cwd === agentCwd) : all;
+	const candidates = (!wantAll && agentCwd != null ? all.filter((record) => record.header.cwd === agentCwd) : all).filter((record) => cwdAllowed(record.header.cwd, cfg));
 	const items = [];
 	for (const record of candidates.slice(0, scanMax)) {
 		if (items.length >= limit) break;
@@ -343,15 +433,57 @@ const recallOutputSchema = {
 			}
 		},
 		nextCursor: nullableString,
-		hint: nullableString
+		hint: nullableString,
+		redacted: { type: "integer" }
 	}
 };
 /**
 * Build the `recall` ToolDefinition around a concrete sessionQuery engine.
 * Pure construction — no registration happens here.
 */
-function createRecallTool(config, engine) {
+function createRecallTool(config, engine, approver) {
 	const cfg = normalizeRecallConfig(config);
+	/** Apply configured redaction to titles and snippets; report a model-facing note. */
+	function applyRedaction(items) {
+		if (cfg.redactionMode === "off") return {
+			items,
+			redacted: 0,
+			hint: null
+		};
+		let redacted = 0;
+		const out = items.map((item) => {
+			const title = item.title == null ? null : redactText(item.title, cfg.redactionMode);
+			const snippet = redactText(item.bestMatch.snippet, cfg.redactionMode);
+			redacted += (title?.count ?? 0) + snippet.count;
+			return {
+				...item,
+				title: title == null ? null : title.text,
+				bestMatch: {
+					...item.bestMatch,
+					snippet: snippet.text
+				}
+			};
+		});
+		const hint = redacted > 0 ? `${redacted} secret-looking field(s) were redacted from this result (mode: ${cfg.redactionMode}).` : null;
+		return {
+			items: out,
+			redacted,
+			hint
+		};
+	}
+	function joinHints(...parts) {
+		const kept = parts.filter((part) => part != null && part !== "");
+		return kept.length > 0 ? kept.join(" ") : null;
+	}
+	/** Ask the approval seam whether this all_projects call may proceed. */
+	async function decideAllProjects(exec, query) {
+		if (approver == null) return "unavailable";
+		try {
+			return await approver(exec, `recall: search sessions from ALL project directories (query: "${query}")`);
+		} catch {
+			return "unavailable";
+		}
+	}
 	return defineTool({
 		name: "recall",
 		description: RECALL_TOOL_DESCRIPTION,
@@ -391,12 +523,31 @@ function createRecallTool(config, engine) {
 			if (query === "") return recallError(query, Object.assign(/* @__PURE__ */ new Error("empty query"), { code: "SESSION_QUERY_INVALID_QUERY" }));
 			const limit = clamp(Math.trunc(args.limit ?? cfg.defaultLimit), 1, cfg.maxLimit);
 			const agentCwd = exec.agent?.session.header?.cwd ?? null;
-			const wantAll = args.all_projects === true && cfg.allowAllProjects;
+			const scopeHints = [];
+			let wantAll = false;
+			if (args.session_id == null && args.all_projects === true) {
+				if (!cfg.allowAllProjects || cfg.allProjectsPolicy === "deny") scopeHints.push("all_projects was ignored: cross-project search is disabled by this deployment. Searched the current project only.");
+				else if (cfg.allProjectsPolicy === "confirm") {
+					const verdict = await decideAllProjects(exec, query);
+					if (verdict === "allowed-once") wantAll = true;
+					else scopeHints.push(`all_projects was not approved (${verdict}); searched the current project only.`);
+				} else wantAll = true;
+			}
 			const scope = {
 				cwd: agentCwd,
 				allProjects: wantAll,
 				sessionId: args.session_id ?? null
 			};
+			if (args.session_id == null && !wantAll && agentCwd != null && !cwdAllowed(agentCwd, cfg)) return {
+				query,
+				scope,
+				count: 0,
+				hasMore: false,
+				items: [],
+				nextCursor: null,
+				hint: "the current project directory is excluded by the recall scope policy (cwd allowlist/denylist). Ask the user to adjust the plugin configuration if this is unexpected.",
+				redacted: 0
+			};
 			try {
 				if (args.session_id != null && args.session_id !== "") {
 					const sessionId = SessionId(args.session_id);
@@ -406,6 +557,16 @@ function createRecallTool(config, engine) {
 						limit,
 						cursor: brand(args.cursor)
 					}, { signal: exec.signal });
+					if (!cwdAllowed(page.session.cwd ?? null, cfg)) return {
+						query,
+						scope,
+						count: 0,
+						hasMore: false,
+						items: [],
+						nextCursor: null,
+						hint: "that session belongs to a project directory excluded by the recall scope policy (cwd allowlist/denylist).",
+						redacted: 0
+					};
 					let items = eventItems(page, sessionId);
 					let hint = null;
 					if (items.length === 0 && hasCJK(query) && cfg.cjkFallback) {
@@ -428,14 +589,16 @@ function createRecallTool(config, engine) {
 						}));
 						hint = items.length > 0 ? cjkFallbackHint(items.length, cfg.cjkHint) : cjkZeroHitHint(query, true, cfg.cjkHint);
 					} else if (items.length === 0) hint = cjkZeroHitHint(query, true, cfg.cjkHint);
+					const red = applyRedaction(items);
 					return {
 						query,
 						scope,
-						count: items.length,
+						count: red.items.length,
 						hasMore: page.nextCursor != null,
-						items,
+						items: red.items,
 						nextCursor: page.nextCursor ?? null,
-						hint
+						hint: joinHints(hint, red.hint),
+						redacted: red.redacted
 					};
 				}
 				const request = {
@@ -449,12 +612,12 @@ function createRecallTool(config, engine) {
 				if (args.cursor != null && args.cursor !== "") request.cursor = brand(args.cursor);
 				const page = await engine.searchSessions(request, { signal: exec.signal });
 				const titles = await titlesFor(engine, page.items.map((hit) => hit.header.id), exec.signal);
-				let items = toItems(page.items, titles);
+				let items = toItems(page.items, titles).filter((item) => cwdAllowed(item.cwd, cfg));
 				let hint = null;
 				let fallbackRan = false;
 				if (items.length === 0 && hasCJK(query) && cfg.cjkFallback) {
 					fallbackRan = true;
-					const scanned = await cjkScanSessions(engine, query, agentCwd, wantAll, cfg.cjkFallbackScanMax, limit, exec.signal);
+					const scanned = await cjkScanSessions(engine, query, agentCwd, wantAll, cfg, cfg.cjkFallbackScanMax, limit, exec.signal);
 					const scanTitles = await titlesFor(engine, scanned.map((item) => item.sessionId), exec.signal);
 					items = scanned.map((item) => ({
 						...item,
@@ -462,14 +625,16 @@ function createRecallTool(config, engine) {
 					}));
 					hint = items.length > 0 ? cjkFallbackHint(items.length, cfg.cjkHint) : cjkZeroHitHint(query, true, cfg.cjkHint);
 				} else if (items.length === 0) hint = cjkZeroHitHint(query, true, cfg.cjkHint);
+				const red = applyRedaction(items);
 				return {
 					query,
 					scope,
-					count: items.length,
+					count: red.items.length,
 					hasMore: !fallbackRan && page.nextCursor != null,
-					items,
+					items: red.items,
 					nextCursor: !fallbackRan ? page.nextCursor ?? null : null,
-					hint
+					hint: joinHints(hint, ...scopeHints, red.hint),
+					redacted: red.redacted
 				};
 			} catch (error) {
 				return recallError(query, error);
@@ -499,11 +664,33 @@ function createRecallTool(config, engine) {
 //#region src/index.ts
 const name = "session-recall";
 const inject = ["tools", "sessionQuery"];
+/**
+* Build the optional approval seam for `allProjectsPolicy: 'confirm'`: ask
+* `ctx.approval` when the service is composed and the call carries an agent;
+* fail closed (`'unavailable'`) otherwise. Never throws.
+*/
+function makeApprover(ctx) {
+	const approval = ctx.approval;
+	if (approval == null || typeof approval.request !== "function") return void 0;
+	return async (exec, reason) => {
+		const agent = exec.agent;
+		if (agent == null) return "unavailable";
+		try {
+			return await approval.request({
+				agent,
+				toolName: "recall",
+				reason
+			});
+		} catch {
+			return "unavailable";
+		}
+	};
+}
 /** Plugin entry: mount the `recall` tool on the global tool registry. */
 function apply(ctx, config) {
 	ctx.effect(function* () {
-		yield ctx.tools.register(createRecallTool(config, ctx.sessionQuery));
+		yield ctx.tools.register(createRecallTool(config, ctx.sessionQuery, makeApprover(ctx)));
 	}, "session-recall lifecycle");
 }
 //#endregion
-export { RECALL_TOOL_DESCRIPTION, apply, cjkFallbackHint, cjkZeroHitHint, clamp, createRecallTool, firstLineClipped, formatDate, hasCJK, id8, inject, name, normalizeQuery, normalizeRecallConfig, recallContentBlocks, recallPresentationMeta, renderRecallText, snippetAround };
+export { ALL_PROJECTS_POLICIES, RECALL_TOOL_DESCRIPTION, REDACTION_MODES, apply, cjkFallbackHint, cjkZeroHitHint, clamp, createRecallTool, cwdAllowed, firstLineClipped, formatDate, hasCJK, id8, inject, name, normalizeQuery, normalizeRecallConfig, normalizeRedactionMode, recallContentBlocks, recallPresentationMeta, redactText, renderRecallText, snippetAround };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-session-recall",
-  "description": "Cross-session full-text recall for DeepSeek Harness: the model-facing `recall` tool searches past session transcripts through ctx.sessionQuery",
-  "version": "0.3.0",
+  "description": "Deterministic cross-session transcript retrieval for DeepSeek Harness: the model-facing `recall` tool searches past session logs with explicit scope control",
+  "version": "0.4.0",
   "publishConfig": {
     "access": "public"
   },