@alfe.ai/openclaw-identity 0.1.0 → 0.1.1

package/dist/plugin2.cjs

@@ -147,74 +147,70 @@ function setCachedResolve(key, value) {
 		expiresAt: Date.now() + RESOLVE_CACHE_TTL_MS
 	});
 }
-function resolveCachedSession(params) {
+function invalidateCachedResolve(key) {
+	resolveCache.delete(key);
+}
+function findMostRelevantCacheEntry(probeKeys) {
+	for (const k of probeKeys) {
+		if (!k) continue;
+		const hit = getCachedResolve(k);
+		if (hit) return hit;
+	}
+	let mostRecent = null;
+	const now = Date.now();
+	for (const entry of resolveCache.values()) {
+		if (entry.expiresAt < now) continue;
+		if (!mostRecent || entry.expiresAt > mostRecent.expiresAt) mostRecent = entry;
+	}
+	return mostRecent;
+}
+const UNCONDITIONAL_SELF_SERVICE_TOOLS = new Set(["request_identity_verification", "confirm_identity_verification"]);
+function isSelfScopedWhoIsThis(toolArgs, cacheKey) {
+	if (!cacheKey) return false;
+	const cached = getCachedResolve(cacheKey);
+	if (!cached) return false;
+	const argProvider = toolArgs?.provider;
+	const argPlatformId = toolArgs?.platformId;
+	if (typeof argProvider !== "string" || typeof argPlatformId !== "string") return false;
+	return argProvider === cached.senderProvider && argPlatformId === cached.senderPlatformId;
+}
+/**
+* Resolve the inbound session identity from `conversationId`. Returns
+* `{ error }` on cache miss / missing param — never falls back to LLM-
+* supplied identity (that's the security property — see header).
+*/
+function resolveSessionIdentity(params) {
 	const conversationId = params.conversationId;
-	const explicitClaimed = params.claimedIdentityId;
 	if (!conversationId) return {
-		hit: false,
-		conversationId: null
+		ok: false,
+		error: "missing_conversation_id: pass conversationId from the inbound message metadata. The verify tools auto-bind to the inbound sender's identity — there is no manual override."
 	};
 	const cached = getCachedResolve(conversationId);
 	if (cached?.identityId == null) return {
-		hit: false,
-		conversationId,
-		error: "session_identity_unavailable: inbound identity cache miss for this conversationId. Pass claimedIdentityId explicitly, or wait for the next inbound message."
-	};
-	if (explicitClaimed && explicitClaimed !== cached.identityId) return {
-		hit: false,
-		conversationId,
-		error: "claimedIdentityId conflicts with the inbound session identity. Either omit claimedIdentityId (recommended) or remove conversationId."
+		ok: false,
+		error: "session_identity_unavailable: inbound identity cache miss for this conversationId. The plugin populates the cache from the message_received hook on every inbound message; if this fires the inbound channel either hasn't sent a message recently (>60s) or the daemon failed to plumb the hook context."
 	};
 	return {
-		hit: true,
-		cached: {
-			...cached,
-			identityId: cached.identityId
-		}
+		ok: true,
+		identityId: cached.identityId,
+		senderProvider: cached.senderProvider,
+		senderPlatformId: cached.senderPlatformId
 	};
 }
-/**
-* Resolution order for the request flow (needs the full requester tuple):
-*  1. conversationId hits cache → derive all four from cached entry.
-*  2. conversationId set but cache miss → reject session_identity_unavailable.
-*  3. No conversationId AND no claimedIdentityId → reject missing_identity.
-*  4. claimedIdentityId + full requester tuple supplied → legacy explicit
-*     flow. Layer 1's server-side `no_op_already_verified` guard catches
-*     the common misuse case (looking up an existing identity by name).
-*/
 function resolveRequesterContext(params) {
-	const session = resolveCachedSession(params);
-	if (session.hit) return {
-		claimedIdentityId: session.cached.identityId,
-		requestingIdentityId: session.cached.identityId,
-		requestingProvider: session.cached.senderProvider,
-		requestingPlatformId: session.cached.senderPlatformId
-	};
-	if (session.conversationId) return { error: session.error };
-	const claimedIdentityId = params.claimedIdentityId;
-	const requestingIdentityId = params.requestingIdentityId;
-	const requestingProvider = params.requestingProvider;
-	const requestingPlatformId = params.requestingPlatformId;
-	if (!claimedIdentityId) return { error: "missing_identity: pass conversationId (recommended — auto-binds to the inbound sender) or claimedIdentityId + requestingIdentityId + requestingProvider + requestingPlatformId explicitly." };
-	if (!requestingIdentityId || !requestingProvider || !requestingPlatformId) return { error: "missing_identity: when claimedIdentityId is supplied without conversationId, requestingIdentityId / requestingProvider / requestingPlatformId are also required. Prefer passing conversationId so all four are auto-derived." };
+	const session = resolveSessionIdentity(params);
+	if (!session.ok) return { error: session.error };
 	return {
-		claimedIdentityId,
-		requestingIdentityId,
-		requestingProvider,
-		requestingPlatformId
+		claimedIdentityId: session.identityId,
+		requestingIdentityId: session.identityId,
+		requestingProvider: session.senderProvider,
+		requestingPlatformId: session.senderPlatformId
 	};
 }
-/**
-* Confirm flow only needs `claimedIdentityId` — same conflict / cache-miss
-* branches as the requester resolver, but no requester tuple.
-*/
 function resolveClaimedIdentity(params) {
-	const session = resolveCachedSession(params);
-	if (session.hit) return { claimedIdentityId: session.cached.identityId };
-	if (session.conversationId) return { error: session.error };
-	const claimedIdentityId = params.claimedIdentityId;
-	if (!claimedIdentityId) return { error: "missing_identity: pass conversationId (recommended — auto-binds to the inbound sender) or claimedIdentityId explicitly." };
-	return { claimedIdentityId };
+	const session = resolveSessionIdentity(params);
+	if (!session.ok) return { error: session.error };
+	return { claimedIdentityId: session.identityId };
 }
 function ok(data) {
 	return {
@@ -259,6 +255,27 @@ function getClient() {
 	});
 	return cachedClient;
 }
+let cachedAgentContext = null;
+let inflightWhoami = null;
+async function getAgentContext(client) {
+	if (cachedAgentContext) return cachedAgentContext;
+	if (inflightWhoami) return inflightWhoami;
+	inflightWhoami = (async () => {
+		try {
+			const r = await client.whoami();
+			cachedAgentContext = {
+				agentId: r.agentId,
+				tenantId: r.tenantId
+			};
+			return cachedAgentContext;
+		} catch {
+			return null;
+		} finally {
+			inflightWhoami = null;
+		}
+	})();
+	return inflightWhoami;
+}
 const plugin = {
 	id: "@alfe.ai/openclaw-identity",
 	name: "Alfe Identity",
@@ -399,13 +416,9 @@ const plugin = {
 			}),
 			defineTool({
 				name: "request_identity_verification",
-				description: "Send a verification phrase to the inbound user's email or mobile to prove they own that contact endpoint. Use when the user has just told you their email or mobile number and you want them to confirm it. PASS conversationId (from the inbound message metadata) — that auto-binds the verification to the inbound sender's identity (the WhatsApp / SMS / Discord / Google Chat user who just spoke). Any merge into a pre-existing account with the same contact happens automatically. Do NOT pass claimedIdentityId yourself unless you have a specific reason to verify a different identity than the inbound sender; looking up an identity by name and passing it here is a footgun and the server will reject with no_op_already_verified.",
+				description: "Send a verification phrase to the inbound user's email or mobile to prove they own that contact endpoint. Use when the inbound user has just told you their email or mobile number and you want them to confirm it. PASS conversationId from the inbound message metadata — the verification ALWAYS binds to the inbound sender's identity (the WhatsApp / SMS / Discord / Google Chat / chat-web user who just spoke). There is no way to verify a different identity via this tool — identity is server-authoritative, resolved at session-start by the chat service. If the contact you supply already lives on another existing identity (e.g. the user's Clerk web account), the merge happens automatically on confirm. To add a new contact to an already-verified canonical identity (e.g. add a new email to a Clerk account), the user must be talking from a session that already resolves to that canonical identity (post-merge, or chat-web logged in as Clerk).",
 				parameters: _sinclair_typebox.Type.Object({
-					conversationId: _sinclair_typebox.Type.Optional(_sinclair_typebox.Type.String({ description: "Conversation ID from the inbound message — the daemon attaches this to every message. Pass it to auto-bind the verification to the inbound sender's identity. When set you should NOT also pass claimedIdentityId / requestingIdentityId / requestingProvider / requestingPlatformId." })),
-					claimedIdentityId: _sinclair_typebox.Type.Optional(_sinclair_typebox.Type.String({ description: "Override for the inbound sender's identity. NEVER set this from a lookup_identity result — that's a footgun (the verification will no-op). Leave unset and pass conversationId so the inbound identity is used automatically. Only set this for explicit non-inbound verification flows (rare — dashboard / admin only)." })),
-					requestingIdentityId: _sinclair_typebox.Type.Optional(_sinclair_typebox.Type.String({ description: "Identity of the person making the claim. Auto-derived from conversationId; only set explicitly when conversationId is omitted." })),
-					requestingProvider: _sinclair_typebox.Type.Optional(_sinclair_typebox.Type.String({ description: "Provider the requester is on (discord, slack, whatsapp, etc.). Auto-derived from conversationId; only set explicitly when conversationId is omitted." })),
-					requestingPlatformId: _sinclair_typebox.Type.Optional(_sinclair_typebox.Type.String({ description: "Requester's provider-specific user ID. Auto-derived from conversationId; only set explicitly when conversationId is omitted." })),
+					conversationId: _sinclair_typebox.Type.String({ description: "Conversation ID from the inbound message — the daemon attaches this to every message. REQUIRED — there is no manual override path." }),
 					contactEmail: _sinclair_typebox.Type.Optional(_sinclair_typebox.Type.String({ description: "Email to verify (mutually exclusive with contactMobile)" })),
 					contactMobile: _sinclair_typebox.Type.Optional(_sinclair_typebox.Type.String({ description: "E.164 mobile to verify (mutually exclusive with contactEmail)" })),
 					preferredChannel: _sinclair_typebox.Type.Optional(_sinclair_typebox.Type.String({ description: "When neither contactEmail nor contactMobile is provided, pick which existing verified contact to deliver to: 'mobile' or 'email'" }))
@@ -435,21 +448,25 @@ const plugin = {
 			}),
 			defineTool({
 				name: "confirm_identity_verification",
-				description: "Confirm a verification by submitting the phrase the user received. Returns `{ verified, identityId, action }` where `action` is 'merged' (the verified contact already lived on another identity, which is now the survivor) or 'contact_verified' (the contact was attached to the claimed identity). PASS the same conversationId you used on request_identity_verification — claimedIdentityId is auto-derived from it.",
+				description: "Confirm a verification by submitting the phrase the inbound user received. Returns `{ verified, identityId, action }` where `action` is 'merged' (the verified contact already lived on another identity, which is now the survivor — the inbound identity merged into it) or 'contact_verified' (the contact was attached to the inbound identity). PASS the same conversationId you used on request_identity_verification — identity is auto-derived from it, no override.",
 				parameters: _sinclair_typebox.Type.Object({
-					conversationId: _sinclair_typebox.Type.Optional(_sinclair_typebox.Type.String({ description: "Conversation ID from the inbound message — same one passed to request_identity_verification. Auto-binds claimedIdentityId to the inbound sender." })),
-					claimedIdentityId: _sinclair_typebox.Type.Optional(_sinclair_typebox.Type.String({ description: "Override for the inbound sender's identity. Must match the value used on the request. Leave unset and pass conversationId." })),
+					conversationId: _sinclair_typebox.Type.String({ description: "Conversation ID from the inbound message — same one passed to request_identity_verification. REQUIRED." }),
 					verificationId: _sinclair_typebox.Type.String({ description: "Verification ID returned from request_identity_verification" }),
-					phrase: _sinclair_typebox.Type.String({ description: "Three-word phrase the person received via mobile or email" })
+					phrase: _sinclair_typebox.Type.String({ description: "Three-word phrase the inbound user received via mobile or email" })
 				}),
-				handler: (params) => {
+				handler: async (params) => {
 					const resolved = resolveClaimedIdentity(params);
-					if ("error" in resolved) return Promise.resolve({ error: resolved.error });
-					return client.confirmIdentityVerification({
+					if ("error" in resolved) return { error: resolved.error };
+					const result = await client.confirmIdentityVerification({
 						claimedIdentityId: resolved.claimedIdentityId,
 						verificationId: params.verificationId,
 						phrase: params.phrase
 					});
+					if (result.verified === true) {
+						const conversationId = params.conversationId;
+						invalidateCachedResolve(conversationId);
+					}
+					return result;
 				}
 			})
 		];
@@ -461,13 +478,17 @@ const plugin = {
 			const provider = ctx.channelId ?? "unknown";
 			const senderId = event.metadata?.UserId ?? event.from;
 			if (!senderId) return;
-			const agentId = ctx.agentId;
+			let agentId = ctx.agentId;
 			if (!agentId) {
-				log.warn(`message_received without ctx.agentId — fail-closed`);
-				return {
-					block: true,
-					blockReason: "Identity: agentId missing on message context"
-				};
+				const fallback = await getAgentContext(client);
+				if (fallback) agentId = fallback.agentId;
+				else {
+					log.warn("message_received without ctx.agentId AND whoami unavailable — fail-closed");
+					return {
+						block: true,
+						blockReason: "Identity: agentId missing on message context and whoami fallback unavailable"
+					};
+				}
 			}
 			const forwarded = Array.isArray(event.metadata?.SenderPermissions) ? event.metadata.SenderPermissions.filter((p) => typeof p === "string") : [];
 			const cacheKey = ctx.conversationId ?? `${provider}:${senderId}`;
@@ -516,40 +537,68 @@ const plugin = {
 				};
 			}
 		}, { priority: 100 });
-		const beforeToolCallStub = (event, ctx) => {
-			if (ctx.authMethod === "token" && ctx.tokenPermissions !== void 0) {
-				const blocked = applyGateMode(evaluateAgentExec(ctx.tokenPermissions, {
-					agentId: ctx.agentId,
-					toolName: event.toolName,
-					toolArgs: event.toolArgs
-				}), resolveToolGatingMode(), event.toolName);
-				return Promise.resolve(blocked);
+		const beforeToolCallStub = async (event, ctx) => {
+			if (UNCONDITIONAL_SELF_SERVICE_TOOLS.has(event.toolName)) return;
+			if (event.toolName === "who_is_this") {
+				const cacheKey = ctx.conversationId ?? (ctx.channelId && ctx.actingIdentityId ? `${ctx.channelId}:${ctx.actingIdentityId}` : null);
+				if (isSelfScopedWhoIsThis(event.toolArgs, cacheKey)) return;
 			}
+			let agentId = ctx.agentId;
+			if (!agentId) {
+				const fallback = await getAgentContext(client);
+				if (fallback) agentId = fallback.agentId;
+			}
+			if (ctx.authMethod === "token" && ctx.tokenPermissions !== void 0) return applyGateMode(evaluateAgentExec(ctx.tokenPermissions, {
+				agentId,
+				toolName: event.toolName,
+				toolArgs: event.toolArgs
+			}), resolveToolGatingMode(), event.toolName);
 			const cacheKey = ctx.conversationId ?? (ctx.channelId && ctx.actingIdentityId ? `${ctx.channelId}:${ctx.actingIdentityId}` : null);
 			if (cacheKey) {
 				const cached = getCachedResolve(cacheKey);
-				if (cached && cached.permissions.length > 0) {
-					const blocked = applyGateMode(evaluateAgentExec([...cached.permissions], {
-						agentId: ctx.agentId,
-						toolName: event.toolName,
-						toolArgs: event.toolArgs
-					}), resolveToolGatingMode(), event.toolName);
-					return Promise.resolve(blocked);
-				}
+				if (cached && cached.permissions.length > 0) return applyGateMode(evaluateAgentExec([...cached.permissions], {
+					agentId,
+					toolName: event.toolName,
+					toolArgs: event.toolArgs
+				}), resolveToolGatingMode(), event.toolName);
 			}
-			const fallback = evaluateAgentExec([], {
-				agentId: ctx.agentId,
+			return applyGateMode(evaluateAgentExec([], {
+				agentId,
 				toolName: event.toolName,
 				toolArgs: event.toolArgs
-			});
-			const mode = resolveToolGatingMode();
-			return Promise.resolve(applyGateMode(fallback, mode, event.toolName));
+			}), resolveToolGatingMode(), event.toolName);
 		};
 		api.on("before_tool_call", (...args) => beforeToolCallStub(args[0], args[1]), { priority: 100 });
+		api.on("before_agent_start", (...args) => {
+			const ctx = args[1];
+			const cached = findMostRelevantCacheEntry([
+				ctx.conversationId,
+				ctx.sessionKey,
+				ctx.sessionId,
+				ctx.channelId
+			]);
+			if (!cached) return Promise.resolve(void 0);
+			if (cached.status !== "anonymous" && cached.status !== "partial") return Promise.resolve(void 0);
+			return Promise.resolve({ prependSystemContext: [
+				"Identity status: the user has not yet verified their identity.",
+				"Tools available now: request_identity_verification,",
+				"confirm_identity_verification, who_is_this.",
+				"All other tools are restricted until the user verifies.",
+				"If the user asks for a capability you cannot perform, briefly",
+				"explain that they need to verify first and offer to start the",
+				"verification flow."
+			].join(" ") });
+		}, { priority: 100 });
+		if (!cachedAgentContext) getAgentContext(client).then((c) => {
+			if (c) log.info(`Plugin context warmed: agent=${c.agentId} tenant=${c.tenantId}`);
+			else log.warn("Plugin context warm failed; will retry on next hook fire");
+		});
 		log.info("Alfe Identity plugin activated");
 	},
 	deactivate(api) {
 		cachedClient = null;
+		cachedAgentContext = null;
+		inflightWhoami = null;
 		api.logger.info("Alfe Identity plugin deactivated");
 	}
 };

package/dist/plugin2.js

@@ -147,74 +147,70 @@ function setCachedResolve(key, value) {
 		expiresAt: Date.now() + RESOLVE_CACHE_TTL_MS
 	});
 }
-function resolveCachedSession(params) {
+function invalidateCachedResolve(key) {
+	resolveCache.delete(key);
+}
+function findMostRelevantCacheEntry(probeKeys) {
+	for (const k of probeKeys) {
+		if (!k) continue;
+		const hit = getCachedResolve(k);
+		if (hit) return hit;
+	}
+	let mostRecent = null;
+	const now = Date.now();
+	for (const entry of resolveCache.values()) {
+		if (entry.expiresAt < now) continue;
+		if (!mostRecent || entry.expiresAt > mostRecent.expiresAt) mostRecent = entry;
+	}
+	return mostRecent;
+}
+const UNCONDITIONAL_SELF_SERVICE_TOOLS = new Set(["request_identity_verification", "confirm_identity_verification"]);
+function isSelfScopedWhoIsThis(toolArgs, cacheKey) {
+	if (!cacheKey) return false;
+	const cached = getCachedResolve(cacheKey);
+	if (!cached) return false;
+	const argProvider = toolArgs?.provider;
+	const argPlatformId = toolArgs?.platformId;
+	if (typeof argProvider !== "string" || typeof argPlatformId !== "string") return false;
+	return argProvider === cached.senderProvider && argPlatformId === cached.senderPlatformId;
+}
+/**
+* Resolve the inbound session identity from `conversationId`. Returns
+* `{ error }` on cache miss / missing param — never falls back to LLM-
+* supplied identity (that's the security property — see header).
+*/
+function resolveSessionIdentity(params) {
 	const conversationId = params.conversationId;
-	const explicitClaimed = params.claimedIdentityId;
 	if (!conversationId) return {
-		hit: false,
-		conversationId: null
+		ok: false,
+		error: "missing_conversation_id: pass conversationId from the inbound message metadata. The verify tools auto-bind to the inbound sender's identity — there is no manual override."
 	};
 	const cached = getCachedResolve(conversationId);
 	if (cached?.identityId == null) return {
-		hit: false,
-		conversationId,
-		error: "session_identity_unavailable: inbound identity cache miss for this conversationId. Pass claimedIdentityId explicitly, or wait for the next inbound message."
-	};
-	if (explicitClaimed && explicitClaimed !== cached.identityId) return {
-		hit: false,
-		conversationId,
-		error: "claimedIdentityId conflicts with the inbound session identity. Either omit claimedIdentityId (recommended) or remove conversationId."
+		ok: false,
+		error: "session_identity_unavailable: inbound identity cache miss for this conversationId. The plugin populates the cache from the message_received hook on every inbound message; if this fires the inbound channel either hasn't sent a message recently (>60s) or the daemon failed to plumb the hook context."
 	};
 	return {
-		hit: true,
-		cached: {
-			...cached,
-			identityId: cached.identityId
-		}
+		ok: true,
+		identityId: cached.identityId,
+		senderProvider: cached.senderProvider,
+		senderPlatformId: cached.senderPlatformId
 	};
 }
-/**
-* Resolution order for the request flow (needs the full requester tuple):
-*  1. conversationId hits cache → derive all four from cached entry.
-*  2. conversationId set but cache miss → reject session_identity_unavailable.
-*  3. No conversationId AND no claimedIdentityId → reject missing_identity.
-*  4. claimedIdentityId + full requester tuple supplied → legacy explicit
-*     flow. Layer 1's server-side `no_op_already_verified` guard catches
-*     the common misuse case (looking up an existing identity by name).
-*/
 function resolveRequesterContext(params) {
-	const session = resolveCachedSession(params);
-	if (session.hit) return {
-		claimedIdentityId: session.cached.identityId,
-		requestingIdentityId: session.cached.identityId,
-		requestingProvider: session.cached.senderProvider,
-		requestingPlatformId: session.cached.senderPlatformId
-	};
-	if (session.conversationId) return { error: session.error };
-	const claimedIdentityId = params.claimedIdentityId;
-	const requestingIdentityId = params.requestingIdentityId;
-	const requestingProvider = params.requestingProvider;
-	const requestingPlatformId = params.requestingPlatformId;
-	if (!claimedIdentityId) return { error: "missing_identity: pass conversationId (recommended — auto-binds to the inbound sender) or claimedIdentityId + requestingIdentityId + requestingProvider + requestingPlatformId explicitly." };
-	if (!requestingIdentityId || !requestingProvider || !requestingPlatformId) return { error: "missing_identity: when claimedIdentityId is supplied without conversationId, requestingIdentityId / requestingProvider / requestingPlatformId are also required. Prefer passing conversationId so all four are auto-derived." };
+	const session = resolveSessionIdentity(params);
+	if (!session.ok) return { error: session.error };
 	return {
-		claimedIdentityId,
-		requestingIdentityId,
-		requestingProvider,
-		requestingPlatformId
+		claimedIdentityId: session.identityId,
+		requestingIdentityId: session.identityId,
+		requestingProvider: session.senderProvider,
+		requestingPlatformId: session.senderPlatformId
 	};
 }
-/**
-* Confirm flow only needs `claimedIdentityId` — same conflict / cache-miss
-* branches as the requester resolver, but no requester tuple.
-*/
 function resolveClaimedIdentity(params) {
-	const session = resolveCachedSession(params);
-	if (session.hit) return { claimedIdentityId: session.cached.identityId };
-	if (session.conversationId) return { error: session.error };
-	const claimedIdentityId = params.claimedIdentityId;
-	if (!claimedIdentityId) return { error: "missing_identity: pass conversationId (recommended — auto-binds to the inbound sender) or claimedIdentityId explicitly." };
-	return { claimedIdentityId };
+	const session = resolveSessionIdentity(params);
+	if (!session.ok) return { error: session.error };
+	return { claimedIdentityId: session.identityId };
 }
 function ok(data) {
 	return {
@@ -259,6 +255,27 @@ function getClient() {
 	});
 	return cachedClient;
 }
+let cachedAgentContext = null;
+let inflightWhoami = null;
+async function getAgentContext(client) {
+	if (cachedAgentContext) return cachedAgentContext;
+	if (inflightWhoami) return inflightWhoami;
+	inflightWhoami = (async () => {
+		try {
+			const r = await client.whoami();
+			cachedAgentContext = {
+				agentId: r.agentId,
+				tenantId: r.tenantId
+			};
+			return cachedAgentContext;
+		} catch {
+			return null;
+		} finally {
+			inflightWhoami = null;
+		}
+	})();
+	return inflightWhoami;
+}
 const plugin = {
 	id: "@alfe.ai/openclaw-identity",
 	name: "Alfe Identity",
@@ -399,13 +416,9 @@ const plugin = {
 			}),
 			defineTool({
 				name: "request_identity_verification",
-				description: "Send a verification phrase to the inbound user's email or mobile to prove they own that contact endpoint. Use when the user has just told you their email or mobile number and you want them to confirm it. PASS conversationId (from the inbound message metadata) — that auto-binds the verification to the inbound sender's identity (the WhatsApp / SMS / Discord / Google Chat user who just spoke). Any merge into a pre-existing account with the same contact happens automatically. Do NOT pass claimedIdentityId yourself unless you have a specific reason to verify a different identity than the inbound sender; looking up an identity by name and passing it here is a footgun and the server will reject with no_op_already_verified.",
+				description: "Send a verification phrase to the inbound user's email or mobile to prove they own that contact endpoint. Use when the inbound user has just told you their email or mobile number and you want them to confirm it. PASS conversationId from the inbound message metadata — the verification ALWAYS binds to the inbound sender's identity (the WhatsApp / SMS / Discord / Google Chat / chat-web user who just spoke). There is no way to verify a different identity via this tool — identity is server-authoritative, resolved at session-start by the chat service. If the contact you supply already lives on another existing identity (e.g. the user's Clerk web account), the merge happens automatically on confirm. To add a new contact to an already-verified canonical identity (e.g. add a new email to a Clerk account), the user must be talking from a session that already resolves to that canonical identity (post-merge, or chat-web logged in as Clerk).",
 				parameters: Type.Object({
-					conversationId: Type.Optional(Type.String({ description: "Conversation ID from the inbound message — the daemon attaches this to every message. Pass it to auto-bind the verification to the inbound sender's identity. When set you should NOT also pass claimedIdentityId / requestingIdentityId / requestingProvider / requestingPlatformId." })),
-					claimedIdentityId: Type.Optional(Type.String({ description: "Override for the inbound sender's identity. NEVER set this from a lookup_identity result — that's a footgun (the verification will no-op). Leave unset and pass conversationId so the inbound identity is used automatically. Only set this for explicit non-inbound verification flows (rare — dashboard / admin only)." })),
-					requestingIdentityId: Type.Optional(Type.String({ description: "Identity of the person making the claim. Auto-derived from conversationId; only set explicitly when conversationId is omitted." })),
-					requestingProvider: Type.Optional(Type.String({ description: "Provider the requester is on (discord, slack, whatsapp, etc.). Auto-derived from conversationId; only set explicitly when conversationId is omitted." })),
-					requestingPlatformId: Type.Optional(Type.String({ description: "Requester's provider-specific user ID. Auto-derived from conversationId; only set explicitly when conversationId is omitted." })),
+					conversationId: Type.String({ description: "Conversation ID from the inbound message — the daemon attaches this to every message. REQUIRED — there is no manual override path." }),
 					contactEmail: Type.Optional(Type.String({ description: "Email to verify (mutually exclusive with contactMobile)" })),
 					contactMobile: Type.Optional(Type.String({ description: "E.164 mobile to verify (mutually exclusive with contactEmail)" })),
 					preferredChannel: Type.Optional(Type.String({ description: "When neither contactEmail nor contactMobile is provided, pick which existing verified contact to deliver to: 'mobile' or 'email'" }))
@@ -435,21 +448,25 @@ const plugin = {
 			}),
 			defineTool({
 				name: "confirm_identity_verification",
-				description: "Confirm a verification by submitting the phrase the user received. Returns `{ verified, identityId, action }` where `action` is 'merged' (the verified contact already lived on another identity, which is now the survivor) or 'contact_verified' (the contact was attached to the claimed identity). PASS the same conversationId you used on request_identity_verification — claimedIdentityId is auto-derived from it.",
+				description: "Confirm a verification by submitting the phrase the inbound user received. Returns `{ verified, identityId, action }` where `action` is 'merged' (the verified contact already lived on another identity, which is now the survivor — the inbound identity merged into it) or 'contact_verified' (the contact was attached to the inbound identity). PASS the same conversationId you used on request_identity_verification — identity is auto-derived from it, no override.",
 				parameters: Type.Object({
-					conversationId: Type.Optional(Type.String({ description: "Conversation ID from the inbound message — same one passed to request_identity_verification. Auto-binds claimedIdentityId to the inbound sender." })),
-					claimedIdentityId: Type.Optional(Type.String({ description: "Override for the inbound sender's identity. Must match the value used on the request. Leave unset and pass conversationId." })),
+					conversationId: Type.String({ description: "Conversation ID from the inbound message — same one passed to request_identity_verification. REQUIRED." }),
 					verificationId: Type.String({ description: "Verification ID returned from request_identity_verification" }),
-					phrase: Type.String({ description: "Three-word phrase the person received via mobile or email" })
+					phrase: Type.String({ description: "Three-word phrase the inbound user received via mobile or email" })
 				}),
-				handler: (params) => {
+				handler: async (params) => {
 					const resolved = resolveClaimedIdentity(params);
-					if ("error" in resolved) return Promise.resolve({ error: resolved.error });
-					return client.confirmIdentityVerification({
+					if ("error" in resolved) return { error: resolved.error };
+					const result = await client.confirmIdentityVerification({
 						claimedIdentityId: resolved.claimedIdentityId,
 						verificationId: params.verificationId,
 						phrase: params.phrase
 					});
+					if (result.verified === true) {
+						const conversationId = params.conversationId;
+						invalidateCachedResolve(conversationId);
+					}
+					return result;
 				}
 			})
 		];
@@ -461,13 +478,17 @@ const plugin = {
 			const provider = ctx.channelId ?? "unknown";
 			const senderId = event.metadata?.UserId ?? event.from;
 			if (!senderId) return;
-			const agentId = ctx.agentId;
+			let agentId = ctx.agentId;
 			if (!agentId) {
-				log.warn(`message_received without ctx.agentId — fail-closed`);
-				return {
-					block: true,
-					blockReason: "Identity: agentId missing on message context"
-				};
+				const fallback = await getAgentContext(client);
+				if (fallback) agentId = fallback.agentId;
+				else {
+					log.warn("message_received without ctx.agentId AND whoami unavailable — fail-closed");
+					return {
+						block: true,
+						blockReason: "Identity: agentId missing on message context and whoami fallback unavailable"
+					};
+				}
 			}
 			const forwarded = Array.isArray(event.metadata?.SenderPermissions) ? event.metadata.SenderPermissions.filter((p) => typeof p === "string") : [];
 			const cacheKey = ctx.conversationId ?? `${provider}:${senderId}`;
@@ -516,40 +537,68 @@ const plugin = {
 				};
 			}
 		}, { priority: 100 });
-		const beforeToolCallStub = (event, ctx) => {
-			if (ctx.authMethod === "token" && ctx.tokenPermissions !== void 0) {
-				const blocked = applyGateMode(evaluateAgentExec(ctx.tokenPermissions, {
-					agentId: ctx.agentId,
-					toolName: event.toolName,
-					toolArgs: event.toolArgs
-				}), resolveToolGatingMode(), event.toolName);
-				return Promise.resolve(blocked);
+		const beforeToolCallStub = async (event, ctx) => {
+			if (UNCONDITIONAL_SELF_SERVICE_TOOLS.has(event.toolName)) return;
+			if (event.toolName === "who_is_this") {
+				const cacheKey = ctx.conversationId ?? (ctx.channelId && ctx.actingIdentityId ? `${ctx.channelId}:${ctx.actingIdentityId}` : null);
+				if (isSelfScopedWhoIsThis(event.toolArgs, cacheKey)) return;
 			}
+			let agentId = ctx.agentId;
+			if (!agentId) {
+				const fallback = await getAgentContext(client);
+				if (fallback) agentId = fallback.agentId;
+			}
+			if (ctx.authMethod === "token" && ctx.tokenPermissions !== void 0) return applyGateMode(evaluateAgentExec(ctx.tokenPermissions, {
+				agentId,
+				toolName: event.toolName,
+				toolArgs: event.toolArgs
+			}), resolveToolGatingMode(), event.toolName);
 			const cacheKey = ctx.conversationId ?? (ctx.channelId && ctx.actingIdentityId ? `${ctx.channelId}:${ctx.actingIdentityId}` : null);
 			if (cacheKey) {
 				const cached = getCachedResolve(cacheKey);
-				if (cached && cached.permissions.length > 0) {
-					const blocked = applyGateMode(evaluateAgentExec([...cached.permissions], {
-						agentId: ctx.agentId,
-						toolName: event.toolName,
-						toolArgs: event.toolArgs
-					}), resolveToolGatingMode(), event.toolName);
-					return Promise.resolve(blocked);
-				}
+				if (cached && cached.permissions.length > 0) return applyGateMode(evaluateAgentExec([...cached.permissions], {
+					agentId,
+					toolName: event.toolName,
+					toolArgs: event.toolArgs
+				}), resolveToolGatingMode(), event.toolName);
 			}
-			const fallback = evaluateAgentExec([], {
-				agentId: ctx.agentId,
+			return applyGateMode(evaluateAgentExec([], {
+				agentId,
 				toolName: event.toolName,
 				toolArgs: event.toolArgs
-			});
-			const mode = resolveToolGatingMode();
-			return Promise.resolve(applyGateMode(fallback, mode, event.toolName));
+			}), resolveToolGatingMode(), event.toolName);
 		};
 		api.on("before_tool_call", (...args) => beforeToolCallStub(args[0], args[1]), { priority: 100 });
+		api.on("before_agent_start", (...args) => {
+			const ctx = args[1];
+			const cached = findMostRelevantCacheEntry([
+				ctx.conversationId,
+				ctx.sessionKey,
+				ctx.sessionId,
+				ctx.channelId
+			]);
+			if (!cached) return Promise.resolve(void 0);
+			if (cached.status !== "anonymous" && cached.status !== "partial") return Promise.resolve(void 0);
+			return Promise.resolve({ prependSystemContext: [
+				"Identity status: the user has not yet verified their identity.",
+				"Tools available now: request_identity_verification,",
+				"confirm_identity_verification, who_is_this.",
+				"All other tools are restricted until the user verifies.",
+				"If the user asks for a capability you cannot perform, briefly",
+				"explain that they need to verify first and offer to start the",
+				"verification flow."
+			].join(" ") });
+		}, { priority: 100 });
+		if (!cachedAgentContext) getAgentContext(client).then((c) => {
+			if (c) log.info(`Plugin context warmed: agent=${c.agentId} tenant=${c.tenantId}`);
+			else log.warn("Plugin context warm failed; will retry on next hook fire");
+		});
 		log.info("Alfe Identity plugin activated");
 	},
 	deactivate(api) {
 		cachedClient = null;
+		cachedAgentContext = null;
+		inflightWhoami = null;
 		api.logger.info("Alfe Identity plugin deactivated");
 	}
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alfe.ai/openclaw-identity",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "OpenClaw identity plugin — identity resolution, access gating, permission enforcement",
   "type": "module",
   "main": "./dist/plugin.js",
@@ -29,8 +29,8 @@
   "dependencies": {
     "@auriclabs/roles": "0.1.1",
     "@sinclair/typebox": "^0.34.48",
-    "@alfe.ai/config": "0.0.8",
-    "@alfe.ai/agent-api-client": "0.1.2"
+    "@alfe.ai/agent-api-client": "0.1.3",
+    "@alfe.ai/config": "0.0.8"
   },
   "license": "UNLICENSED",
   "scripts": {